docs: add onixbyte-toolbox documentation
Add English and Chinese docs for the OnixByte Toolbox monorepo covering all six modules: common-toolbox, crypto-toolbox, math-toolbox, tuple, identity-generator, and version-catalogue.
This commit is contained in:
@@ -0,0 +1,209 @@
|
||||
---
|
||||
title: OnixByte Toolbox API
|
||||
---
|
||||
|
||||
## Package Overview
|
||||
|
||||
All modules are published under the `com.onixbyte` group ID. Each module has its own base package:
|
||||
|
||||
| Module | Maven Artifact | Base Package |
|
||||
|----------------------|------------------------|---------------------------------------|
|
||||
| Common Toolbox | `common-toolbox` | `com.onixbyte.common` |
|
||||
| Crypto Toolbox | `crypto-toolbox` | `com.onixbyte.crypto` |
|
||||
| Math Toolbox | `math-toolbox` | `com.onixbyte.math` |
|
||||
| Tuple | `tuple` | `com.onixbyte.tuple` |
|
||||
| Identity Generator | `identity-generator` | `com.onixbyte.identitygenerator` |
|
||||
|
||||
---
|
||||
|
||||
## Common Toolbox
|
||||
|
||||
### Adapter
|
||||
|
||||
`ObjectMapAdapter` — Converts between objects and maps. Useful for serialisation or data transformation scenarios where key-value representations are preferred.
|
||||
|
||||
```java
|
||||
import com.onixbyte.common.adapter.ObjectMapAdapter;
|
||||
```
|
||||
|
||||
### Utility Classes
|
||||
|
||||
| Class | Description |
|
||||
|--------------------|----------------------------------------------------------|
|
||||
| `AesUtil` | AES symmetric encryption/decryption with key generation |
|
||||
| `Base64Util` | Base64 encoding and decoding with multiple charset support|
|
||||
| `BoolUtil` | Boolean parsing and conversion utilities |
|
||||
| `BranchUtil` | Conditional branching helpers with functional-style chains|
|
||||
| `CollectionUtil` | Collection manipulation — grouping, partitioning, merging |
|
||||
| `HashUtil` | Hashing utilities supporting MD5, SHA-1, SHA-256, SHA-512 |
|
||||
| `MapUtil` | Map builder, merge, and transformation helpers |
|
||||
| `RangeUtil` | Numeric range operations with boundary handling |
|
||||
|
||||
**AesUtil Example:**
|
||||
|
||||
```java
|
||||
var key = AesUtil.generateKey();
|
||||
var encrypted = AesUtil.encrypt("hello world", key);
|
||||
var decrypted = AesUtil.decrypt(encrypted, key);
|
||||
```
|
||||
|
||||
**HashUtil Example:**
|
||||
|
||||
```java
|
||||
var md5 = HashUtil.md5("hello world");
|
||||
var sha256 = HashUtil.sha256("hello world");
|
||||
var fileSha = HashUtil.sha256(new File("data.bin"));
|
||||
```
|
||||
|
||||
**CollectionUtil Example:**
|
||||
|
||||
```java
|
||||
var partitioned = CollectionUtil.partition(list, 100);
|
||||
var grouped = CollectionUtil.groupBy(users, User::getDepartment);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Crypto Toolbox
|
||||
|
||||
Provides a clean abstraction for loading cryptographic keys in PEM format. Supports both RSA and ECDSA algorithms.
|
||||
|
||||
### Key Loaders
|
||||
|
||||
| Class | Description |
|
||||
|---------------------------|--------------------------------------------|
|
||||
| `RSAPrivateKeyLoader` | Load RSA private keys from PEM strings |
|
||||
| `RSAPublicKeyLoader` | Load RSA public keys from PEM strings |
|
||||
| `ECPrivateKeyLoader` | Load ECDSA private keys from PEM strings |
|
||||
| `ECPublicKeyLoader` | Load ECDSA public keys from PEM strings |
|
||||
|
||||
All key loaders implement either `PrivateKeyLoader` or `PublicKeyLoader` interfaces.
|
||||
|
||||
**RSA Example:**
|
||||
|
||||
```java
|
||||
var privateKey = new RSAPrivateKeyLoader().load(pemString);
|
||||
var publicKey = new RSAPublicKeyLoader().load(pemString);
|
||||
```
|
||||
|
||||
**ECDSA Example:**
|
||||
|
||||
```java
|
||||
var ecPrivateKey = new ECPrivateKeyLoader().load(pemString);
|
||||
var ecPublicKey = new ECPublicKeyLoader().load(pemString);
|
||||
```
|
||||
|
||||
### Utility
|
||||
|
||||
`CryptoUtil` — Provides convenient methods for digital signature creation and verification, as well as general-purpose cryptographic helpers.
|
||||
|
||||
### Exceptions
|
||||
|
||||
| Class | Description |
|
||||
|------------------------|---------------------------------------------------|
|
||||
| `KeyLoadingException` | Thrown when a PEM-formatted key fails to parse |
|
||||
|
||||
---
|
||||
|
||||
## Math Toolbox
|
||||
|
||||
Statistical computation utilities for working with numeric datasets.
|
||||
|
||||
### Core Classes
|
||||
|
||||
| Class | Description |
|
||||
|-------------------------|----------------------------------------------------------|
|
||||
| `Calculator` | Statistical calculator for mean, median, variance, standard deviation, sum, min, max |
|
||||
| `PercentileCalculator` | Percentile computation with configurable interpolation strategies |
|
||||
|
||||
**Calculator Example:**
|
||||
|
||||
```java
|
||||
var stats = new Calculator(Arrays.asList(1.0, 2.0, 3.0, 4.0, 5.0));
|
||||
double mean = stats.getMean();
|
||||
double median = stats.getMedian();
|
||||
double stdDev = stats.getStandardDeviation();
|
||||
```
|
||||
|
||||
**PercentileCalculator Example:**
|
||||
|
||||
```java
|
||||
var calculator = new PercentileCalculator(data);
|
||||
double p95 = calculator.calculate(95);
|
||||
double p99 = calculator.calculate(99);
|
||||
```
|
||||
|
||||
### Model
|
||||
|
||||
| Class | Description |
|
||||
|-------------------|----------------------------------------------------------------|
|
||||
| `QuartileBounds` | Holds Q1, median (Q2), Q3 values along with IQR and whisker bounds |
|
||||
|
||||
---
|
||||
|
||||
## Tuple
|
||||
|
||||
Lightweight generic tuple types for when you need to return multiple values without defining a dedicated class.
|
||||
|
||||
### Classes
|
||||
|
||||
| Class | Type Parameters | Mutability |
|
||||
|--------------------|-----------------|------------|
|
||||
| `Tuple<A, B>` | Two elements | Mutable |
|
||||
| `ImmutableTuple<A, B>` | Two elements | Immutable |
|
||||
| `Triple<A, B, C>` | Three elements | Mutable |
|
||||
| `ImmutableTriple<A, B, C>` | Three elements | Immutable |
|
||||
|
||||
**Example:**
|
||||
|
||||
```java
|
||||
var pair = Tuple.of("key", 42);
|
||||
var triple = Triple.of("id", "name", 100);
|
||||
var immutable = ImmutableTuple.of("constant", true);
|
||||
|
||||
// Accessors
|
||||
String first = pair.getFirst();
|
||||
Integer second = pair.getSecond();
|
||||
|
||||
// Triple accessors
|
||||
String a = triple.getFirst();
|
||||
String b = triple.getSecond();
|
||||
Integer c = triple.getThird();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Identity Generator
|
||||
|
||||
Generates unique identifiers suitable for use as database primary keys or distributed IDs.
|
||||
|
||||
### Interface
|
||||
|
||||
`IdentityGenerator<T>` — Generates identities of type `T`.
|
||||
|
||||
### Implementations
|
||||
|
||||
| Class | Description |
|
||||
|------------------------------|-----------------------------------------------------------------|
|
||||
| `SequentialUuidGenerator` | Generates time-ordered, sequential UUIDs (optimised for DB indexes) |
|
||||
| `SnowflakeIdentityGenerator` | Snowflake-style distributed unique ID generation |
|
||||
|
||||
**Sequential UUID:**
|
||||
|
||||
```java
|
||||
var generator = new SequentialUuidGenerator();
|
||||
UUID id = generator.nextId(); // time-ordered UUID, B-tree friendly
|
||||
```
|
||||
|
||||
**Snowflake:**
|
||||
|
||||
```java
|
||||
var generator = new SnowflakeIdentityGenerator(workerId, datacenterId);
|
||||
long id = generator.nextId(); // 64-bit snowflake ID
|
||||
```
|
||||
|
||||
### Exceptions
|
||||
|
||||
| Class | Description |
|
||||
|-------------------|----------------------------------------------------------------|
|
||||
| `TimingException` | Thrown when the system clock moves backwards, compromising ID uniqueness |
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: OnixByte Toolbox
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
OnixByte Toolbox is a Development Kit for Java applications that provides a set of convenient, reusable tools for writing code efficiently. It is designed and maintained by OnixByte as a monorepo containing multiple purpose-built libraries, each addressing a specific development need — from common utilities and cryptography to mathematical computation and identity generation.
|
||||
|
||||
The toolkit is available on Maven Central under the `com.onixbyte` group ID. Each module is independently versioned and can be included in any Java 17+ project.
|
||||
|
||||
## Modules
|
||||
|
||||
| Module | Artifact ID | Description |
|
||||
|----------------------|-----------------------|-------------------------------------------------------|
|
||||
| Common Toolbox | `common-toolbox` | Everyday utilities — AES, hashing, Base64, collections, branching, ranges |
|
||||
| Crypto Toolbox | `crypto-toolbox` | Public/private key loading for RSA and ECDSA algorithms |
|
||||
| Math Toolbox | `math-toolbox` | Statistical calculation, percentile analysis, quartile computation |
|
||||
| Tuple | `tuple` | Generic 2-tuple and 3-tuple with immutable variants |
|
||||
| Identity Generator | `identity-generator` | Snowflake-style and sequential UUID identity generation |
|
||||
| Version Catalogue | `version-catalogue` | Centralised Gradle version catalogue for OnixByte projects |
|
||||
|
||||
## Installation
|
||||
|
||||
Add the desired module as a dependency in your build config:
|
||||
|
||||
**Gradle (Kotlin DSL):**
|
||||
|
||||
```kotlin
|
||||
implementation("com.onixbyte:common-toolbox:$version")
|
||||
implementation("com.onixbyte:crypto-toolbox:$version")
|
||||
implementation("com.onixbyte:math-toolbox:$version")
|
||||
implementation("com.onixbyte:tuple:$version")
|
||||
implementation("com.onixbyte:identity-generator:$version")
|
||||
```
|
||||
|
||||
**Maven:**
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.onixbyte</groupId>
|
||||
<artifactId>common-toolbox</artifactId>
|
||||
<version>${version}</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
Refer to the [changelog](https://codecrafters.org.cn/devkit/changelog) for available versions.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Java 17 or later
|
||||
|
||||
## License
|
||||
|
||||
OnixByte Toolbox is open-source software released under the MIT License.
|
||||
@@ -0,0 +1,209 @@
|
||||
---
|
||||
title: OnixByte Toolbox API
|
||||
---
|
||||
|
||||
## 包结构概览
|
||||
|
||||
所有模块均在 `com.onixbyte` group ID 下发布。每个模块有自己独立的基础包：
|
||||
|
||||
| 模块 | Maven Artifact | 基础包 |
|
||||
|---|---|---|
|
||||
| Common Toolbox | `common-toolbox` | `com.onixbyte.common` |
|
||||
| Crypto Toolbox | `crypto-toolbox` | `com.onixbyte.crypto` |
|
||||
| Math Toolbox | `math-toolbox` | `com.onixbyte.math` |
|
||||
| Tuple | `tuple` | `com.onixbyte.tuple` |
|
||||
| Identity Generator | `identity-generator` | `com.onixbyte.identitygenerator` |
|
||||
|
||||
---
|
||||
|
||||
## Common Toolbox
|
||||
|
||||
### 适配器
|
||||
|
||||
`ObjectMapAdapter` — 对象与 Map 之间的转换器。适用于需要键值表示的场景，如序列化或数据转换。
|
||||
|
||||
```java
|
||||
import com.onixbyte.common.adapter.ObjectMapAdapter;
|
||||
```
|
||||
|
||||
### 工具类
|
||||
|
||||
| 类 | 描述 |
|
||||
|---|---|
|
||||
| `AesUtil` | AES 对称加密/解密，支持密钥生成 |
|
||||
| `Base64Util` | Base64 编解码，支持多种字符集 |
|
||||
| `BoolUtil` | 布尔值解析与转换工具 |
|
||||
| `BranchUtil` | 条件分支辅助，支持函数式链式调用 |
|
||||
| `CollectionUtil` | 集合操作 — 分组、分区、合并 |
|
||||
| `HashUtil` | 哈希工具，支持 MD5、SHA-1、SHA-256、SHA-512 |
|
||||
| `MapUtil` | Map 构建、合并和转换辅助 |
|
||||
| `RangeUtil` | 数值范围操作，支持边界处理 |
|
||||
|
||||
**AesUtil 示例：**
|
||||
|
||||
```java
|
||||
var key = AesUtil.generateKey();
|
||||
var encrypted = AesUtil.encrypt("hello world", key);
|
||||
var decrypted = AesUtil.decrypt(encrypted, key);
|
||||
```
|
||||
|
||||
**HashUtil 示例：**
|
||||
|
||||
```java
|
||||
var md5 = HashUtil.md5("hello world");
|
||||
var sha256 = HashUtil.sha256("hello world");
|
||||
var fileSha = HashUtil.sha256(new File("data.bin"));
|
||||
```
|
||||
|
||||
**CollectionUtil 示例：**
|
||||
|
||||
```java
|
||||
var partitioned = CollectionUtil.partition(list, 100);
|
||||
var grouped = CollectionUtil.groupBy(users, User::getDepartment);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Crypto Toolbox
|
||||
|
||||
提供了加载 PEM 格式密钥的简洁抽象。支持 RSA 和 ECDSA 算法。
|
||||
|
||||
### 密钥加载器
|
||||
|
||||
| 类 | 描述 |
|
||||
|---|---|
|
||||
| `RSAPrivateKeyLoader` | 从 PEM 字符串加载 RSA 私钥 |
|
||||
| `RSAPublicKeyLoader` | 从 PEM 字符串加载 RSA 公钥 |
|
||||
| `ECPrivateKeyLoader` | 从 PEM 字符串加载 ECDSA 私钥 |
|
||||
| `ECPublicKeyLoader` | 从 PEM 字符串加载 ECDSA 公钥 |
|
||||
|
||||
所有密钥加载器实现 `PrivateKeyLoader` 或 `PublicKeyLoader` 接口。
|
||||
|
||||
**RSA 示例：**
|
||||
|
||||
```java
|
||||
var privateKey = new RSAPrivateKeyLoader().load(pemString);
|
||||
var publicKey = new RSAPublicKeyLoader().load(pemString);
|
||||
```
|
||||
|
||||
**ECDSA 示例：**
|
||||
|
||||
```java
|
||||
var ecPrivateKey = new ECPrivateKeyLoader().load(pemString);
|
||||
var ecPublicKey = new ECPublicKeyLoader().load(pemString);
|
||||
```
|
||||
|
||||
### 工具类
|
||||
|
||||
`CryptoUtil` — 提供便捷的数字签名生成和验证方法，以及通用密码学辅助功能。
|
||||
|
||||
### 异常
|
||||
|
||||
| 类 | 描述 |
|
||||
|---|---|
|
||||
| `KeyLoadingException` | PEM 格式密钥解析失败时抛出 |
|
||||
|
||||
---
|
||||
|
||||
## Math Toolbox
|
||||
|
||||
用于处理数值数据集的统计计算工具。
|
||||
|
||||
### 核心类
|
||||
|
||||
| 类 | 描述 |
|
||||
|---|---|
|
||||
| `Calculator` | 统计计算器 — 均值、中位数、方差、标准差、总和、最小值、最大值 |
|
||||
| `PercentileCalculator` | 百分位数计算器，支持可配置的插值策略 |
|
||||
|
||||
**Calculator 示例：**
|
||||
|
||||
```java
|
||||
var stats = new Calculator(Arrays.asList(1.0, 2.0, 3.0, 4.0, 5.0));
|
||||
double mean = stats.getMean();
|
||||
double median = stats.getMedian();
|
||||
double stdDev = stats.getStandardDeviation();
|
||||
```
|
||||
|
||||
**PercentileCalculator 示例：**
|
||||
|
||||
```java
|
||||
var calculator = new PercentileCalculator(data);
|
||||
double p95 = calculator.calculate(95);
|
||||
double p99 = calculator.calculate(99);
|
||||
```
|
||||
|
||||
### 数据模型
|
||||
|
||||
| 类 | 描述 |
|
||||
|---|---|
|
||||
| `QuartileBounds` | 包含 Q1、中位数（Q2）、Q3 值及 IQR 和须线边界 |
|
||||
|
||||
---
|
||||
|
||||
## Tuple
|
||||
|
||||
轻量级泛型元组类型，适用于需要返回多个值但无需定义专用类的场景。
|
||||
|
||||
### 类
|
||||
|
||||
| 类 | 类型参数 | 可变性 |
|
||||
|---|---|---|
|
||||
| `Tuple<A, B>` | 两个元素 | 可变 |
|
||||
| `ImmutableTuple<A, B>` | 两个元素 | 不可变 |
|
||||
| `Triple<A, B, C>` | 三个元素 | 可变 |
|
||||
| `ImmutableTriple<A, B, C>` | 三个元素 | 不可变 |
|
||||
|
||||
**示例：**
|
||||
|
||||
```java
|
||||
var pair = Tuple.of("key", 42);
|
||||
var triple = Triple.of("id", "name", 100);
|
||||
var immutable = ImmutableTuple.of("constant", true);
|
||||
|
||||
// 访问器
|
||||
String first = pair.getFirst();
|
||||
Integer second = pair.getSecond();
|
||||
|
||||
// 三元组访问器
|
||||
String a = triple.getFirst();
|
||||
String b = triple.getSecond();
|
||||
Integer c = triple.getThird();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Identity Generator
|
||||
|
||||
生成适用于数据库主键或分布式 ID 的唯一标识符。
|
||||
|
||||
### 接口
|
||||
|
||||
`IdentityGenerator<T>` — 生成类型为 `T` 的标识符。
|
||||
|
||||
### 实现
|
||||
|
||||
| 类 | 描述 |
|
||||
|---|---|
|
||||
| `SequentialUuidGenerator` | 生成时间排序的顺序 UUID（优化数据库索引性能） |
|
||||
| `SnowflakeIdentityGenerator` | 雪花算法分布式唯一 ID 生成 |
|
||||
|
||||
**顺序 UUID：**
|
||||
|
||||
```java
|
||||
var generator = new SequentialUuidGenerator();
|
||||
UUID id = generator.nextId(); // 时间排序 UUID，对 B-tree 友好
|
||||
```
|
||||
|
||||
**雪花：**
|
||||
|
||||
```java
|
||||
var generator = new SnowflakeIdentityGenerator(workerId, datacenterId);
|
||||
long id = generator.nextId(); // 64 位雪花 ID
|
||||
```
|
||||
|
||||
### 异常
|
||||
|
||||
| 类 | 描述 |
|
||||
|---|---|
|
||||
| `TimingException` | 系统时钟回拨时抛出，保证 ID 唯一性不受影响 |
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: OnixByte Toolbox
|
||||
---
|
||||
|
||||
## 介绍
|
||||
|
||||
OnixByte Toolbox 是一个面向 Java 应用的开发工具包，提供了一系列便捷、可复用的工具，帮助开发者高效编写代码。它由 OnixByte 设计和维护，采用 monorepo 架构，包含多个专用库，每个库解决一个特定的开发需求 — 从通用工具类和密码学，到数学计算和标识符生成。
|
||||
|
||||
该工具包已发布到 Maven Central，使用 `com.onixbyte` 作为 group ID。每个模块独立版本管理，可在任何 Java 17+ 项目中使用。
|
||||
|
||||
## 模块
|
||||
|
||||
| 模块 | Artifact ID | 描述 |
|
||||
|---|---|---|
|
||||
| Common Toolbox | `common-toolbox` | 日常工具类 — AES 加密、哈希、Base64、集合、分支、范围 |
|
||||
| Crypto Toolbox | `crypto-toolbox` | RSA 和 ECDSA 算法的公私钥加载 |
|
||||
| Math Toolbox | `math-toolbox` | 统计计算、百分位数分析、四分位数计算 |
|
||||
| Tuple | `tuple` | 泛型二元组和三元组，含不可变版本 |
|
||||
| Identity Generator | `identity-generator` | 雪花算法和顺序 UUID 唯一标识符生成 |
|
||||
| Version Catalogue | `version-catalogue` | OnixByte 项目的集中式 Gradle 版本目录 |
|
||||
|
||||
## 安装
|
||||
|
||||
在构建配置中添加所需模块的依赖：
|
||||
|
||||
**Gradle (Kotlin DSL):**
|
||||
|
||||
```kotlin
|
||||
implementation("com.onixbyte:common-toolbox:$version")
|
||||
implementation("com.onixbyte:crypto-toolbox:$version")
|
||||
implementation("com.onixbyte:math-toolbox:$version")
|
||||
implementation("com.onixbyte:tuple:$version")
|
||||
implementation("com.onixbyte:identity-generator:$version")
|
||||
```
|
||||
|
||||
**Maven:**
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.onixbyte</groupId>
|
||||
<artifactId>common-toolbox</artifactId>
|
||||
<version>${version}</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
可查阅[更新日志](https://codecrafters.org.cn/devkit/changelog)了解可用版本。
|
||||
|
||||
## 要求
|
||||
|
||||
- Java 17 或更高版本
|
||||
|
||||
## 许可证
|
||||
|
||||
OnixByte Toolbox 是采用 MIT 许可证发布的开源软件。
|
||||
Reference in New Issue
Block a user