feat(doc): update documentation

Ahoo-Wang · Jan 2, 2024 · 5c493bb · 5c493bb
1 parent ea76329
commit 5c493bb
Show file tree

Hide file tree

Showing 9 changed files with 84 additions and 40 deletions.
diff --git a/documentation/docs/.vitepress/configs/sidebar.ts b/documentation/docs/.vitepress/configs/sidebar.ts
@@ -26,7 +26,10 @@ export const sidebar: DefaultTheme.Sidebar = {
                 {text: 'SegmentId', link: 'segment'},
                 {text: 'SegmentChainId', link: 'segment-chain'},
                 {text: 'CosIdGenerator', link: 'cosid-generator'},
+                {text: 'IdConverter', link: 'id-converter'},
+                {text: 'Id生成器容器', link: 'provider'},
                 {text: 'CosIdProxy', link: 'cosid-proxy'},
+
             ],
         }, {
             base: '/guide/extensions/',
@@ -57,14 +60,12 @@ export const sidebar: DefaultTheme.Sidebar = {
                 {text: 'CosId VS 美团 Leaf', link: 'Performance-CosId-Leaf'},
             ],
         }, {
-            base: '/guide/advanced/',
-            text: '深入',
+            base: '/guide/sharding/',
+            text: '分片算法',
             collapsed: false,
             items: [
-                {text: 'IdGenerator', link: 'id-generator'},
-                {text: 'IdConverter', link: 'id-converter'},
-                {text: 'IdGeneratorProvider', link: 'provider'},
-                {text: 'Sharding', link: 'sharding'},
+                {text: '取模分片算法', link: 'mod-cycle'},
+                {text: '时间范围分片算法', link: 'interval-timeline'}
             ],
         }, {
             text: '配置',

diff --git a/documentation/docs/guide/advanced/sharding.md b/documentation/docs/guide/advanced/sharding.md
diff --git a/documentation/docs/guide/extensions/cosid-jackson.md b/documentation/docs/guide/extensions/cosid-jackson.md
@@ -33,6 +33,8 @@
 ```
 :::
 
+## 使用
+
 ```java
 public class AsStringDto {
 

diff --git a/documentation/docs/guide/extensions/cosid-shardingsphere.md b/documentation/docs/guide/extensions/cosid-shardingsphere.md
@@ -1,7 +1,7 @@
 # CosId-ShardingSphere 模块
 
 ::: tip 维护说明
-`CosIdKeyGenerateAlgorithm`、`CosIdModShardingAlgorithm`、`CosIdIntervalShardingAlgorithm` 已合并至 [ShardingSphere](https://github.com/apache/shardingsphere/pull/14132) 官方，未来 *[cosid-shardingsphere](https://github.com/Ahoo-Wang/CosId/tree/main/cosid-shardingsphere)* 模块的维护可能会以官方为主。
+`CosIdKeyGenerateAlgorithm`、`CosIdModShardingAlgorithm`、`CosIdIntervalShardingAlgorithm` 已合并至 [ShardingSphere](https://github.com/apache/shardingsphere/pull/14132) 官方，当前该模块的维护可能会以官方为主。
 :::
 
 ## 安装
@@ -22,7 +22,7 @@
 ```
 :::
 
-## CosIdKeyGenerateAlgorithm (分布式主键)
+## 分布式主键
 
 ```yaml
 spring:
@@ -80,8 +80,8 @@ spring:
 
 - 性能 : 相比于 `org.apache.shardingsphere.sharding.algorithm.sharding.mod.ModShardingAlgorithm` 性能高出 *1200~4000* 倍。并且稳定性更高，不会出现严重的性能退化。
 
-| **PreciseShardingValue**                                                                                     | **RangeShardingValue**                                                                                     |
-|--------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
+| **PreciseShardingValue**                                                                                   | **RangeShardingValue**                                                                                   |
+|------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
 | <img src="../../public/assets/perf/sharding/Throughput-Of-ModShardingAlgorithm-PreciseShardingValue.png"/> | <img src="../../public/assets/perf/sharding/Throughput-Of-ModShardingAlgorithm-RangeShardingValue.png"/> |
 
 ```yaml

diff --git a/documentation/docs/guide/extensions/cosid-zookeeper.md b/documentation/docs/guide/extensions/cosid-zookeeper.md
@@ -1,7 +1,9 @@
 # CosId-ZooKeeper 模块
 
-[cosid-zookeeper](https://github.com/Ahoo-Wang/CosId/tree/main/cosid-zookeeper) 使用**ZooKeeper**作为**雪花算法**(`SnowflakeId`)
-的 机器号分配器 (`MachineIdDistributor`) 、**号段算法**(`SegmentId`)的号段分发器 (`IdSegmentDistributor`)。
+[cosid-zookeeper](https://github.com/Ahoo-Wang/CosId/tree/main/cosid-zookeeper) 模块提供 *ZooKeeper* 的支持。实现了：
+
+- `MachineIdDistributor`：作为**雪花算法**(`SnowflakeId`)的机器号分配器 (`MachineIdDistributor`)。
+- `IdSegmentDistributor`：作为**号段算法**(`SegmentId`)的号段分发器 (`IdSegmentDistributor`)。
 
 ## 安装
 
@@ -21,15 +23,45 @@
 ```
 :::
 
-## ZookeeperIdSegmentDistributor
+## 配置
 
-> 基于zookeeper的Id片段分发器。维护一个step步长id。
+- 配置类：[CosIdZookeeperProperties](https://github.com/Ahoo-Wang/CosId/blob/main/cosid-spring-boot-starter/src/main/java/me/ahoo/cosid/spring/boot/starter/zookeeper/CosIdZookeeperProperties.java)
+- 前缀：`cosid.zookeeper.`
 
-主要方法：获取下一个步长最大值
+| 名称                         | 数据类型       | 说明              | 默认值                      |
+|----------------------------|------------|-----------------|--------------------------|
+| enabled                    | `boolean`  | 是否开启*ZooKeeper* | true                     |
+| connect-string             | `String`   | 链接字符串           | `localhost:2181`         |
+| block-until-connected-wait | `Duration` | 阻塞直到客户端已连接等待时间  | `Duration.ofSeconds(10)` |
+| session-timeout            | `Duration` | 会话超时时间          | `Duration.ofSeconds(60`  |
+| connection-timeout         | `Duration` | 连接超时时间          | `Duration.ofSeconds(15)` |
+| retry                      | `Retry`    | 重试策略配置          |                          |
 
-```java
-long nextMaxId(long step);
-```
+### Retry (`ExponentialBackoffRetry`) 配置
+
+| 名称              | 数据类型  | 说明                | 默认值   |
+|-----------------|-------|-------------------|-------|
+| baseSleepTimeMs | `int` | 重试之间等待的初始时间量 （毫秒） | `100` |
+| maxRetries      | `int` | 最大重试次数            | `5`   |
+| maxSleepMs      | `int` | 每次重试时的最大睡眠时间（毫秒）  | `500` |
 
-## ZookeeperMachineIdDistributor
-> 基于zookeeper的机器号分发器。
+### 配置案例
+
+[CosId-Example-Zookeeper](https://github.com/Ahoo-Wang/CosId/tree/main/examples/cosid-example-zookeeper)
+
+```yaml {2-8,11,14}
+cosid:
+  zookeeper:
+    connect-string: localhost:2181
+    retry:
+      base-sleep-time-ms: 100
+      max-retries: 5
+      max-sleep-ms: 500
+    block-until-connected-wait: 10s
+  segment:
+    distributor:
+      type: zookeeper
+  machine:
+    distributor:
+      type: zookeeper
+```
diff --git a/...ation/docs/guide/advanced/id-converter.md → documentation/docs/guide/id-converter.md b/...ation/docs/guide/advanced/id-converter.md → documentation/docs/guide/id-converter.md
@@ -27,7 +27,7 @@ public interface IdConverter {
 ## IdConverter implementation class diagram
 
 <p align="center">
-  <img src="../../public/assets/design/IdConverter-impl-class.png" alt="IdGenerator implementation class diagram"/>
+  <img src="../public/assets/design/IdConverter-impl-class.png" alt="IdGenerator implementation class diagram"/>
 </p>
 
 ## ToStringIdConverter

diff --git a/...mentation/docs/guide/advanced/provider.md → documentation/docs/guide/provider.md b/...mentation/docs/guide/advanced/provider.md → documentation/docs/guide/provider.md
@@ -3,7 +3,7 @@
 > `IdGenerator` 容器
 
 <p align="center">
-  <img src="../../public/assets/design/IdGeneratorProvider-impl-class.png" alt="IdGeneratorProvider implementation class diagram"/>
+  <img src="../public/assets/design/IdGeneratorProvider-impl-class.png" alt="IdGeneratorProvider implementation class diagram"/>
 </p>
 
 ## DefaultIdGeneratorProvider

diff --git a/documentation/docs/guide/sharding/interval-timeline.md b/documentation/docs/guide/sharding/interval-timeline.md
@@ -0,0 +1,14 @@
+# 基于间隔的时间范围分片算法
+
+<p align="center" >
+  <img src="../../public/assets/design/CosIdIntervalShardingAlgorithm.png" alt="CosIdIntervalShardingAlgorithm"/>
+</p>
+
+- 算法复杂度：O(1)
+- 易用性: 支持多种数据类型 (`Long`/`LocalDateTime`/`DATE`/ `String` / `SnowflakeId`)，而官方实现是先转换成字符串再转换成`LocalDateTime`，转换成功率受时间格式化字符影响。
+- 性能 : 相比于 `org.apache.shardingsphere.sharding.algorithm.sharding.datetime.IntervalShardingAlgorithm` 性能高出 *1200~4000* 倍。
+
+| **PreciseShardingValue**                                                                                        | **RangeShardingValue**                                                                                        |
+|-----------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
+| <img src="../../public/assets/perf/sharding/Throughput-Of-IntervalShardingAlgorithm-PreciseShardingValue.png"/> | <img src="../../public/assets/perf/sharding/Throughput-Of-IntervalShardingAlgorithm-RangeShardingValue.png"/> |
+
diff --git a/documentation/docs/guide/sharding/mod-cycle.md b/documentation/docs/guide/sharding/mod-cycle.md
@@ -0,0 +1,13 @@
+# 取模分片算法
+
+<p align="center" >
+  <img src="../../public/assets/design/CosIdModShardingAlgorithm.png" alt="CosIdModShardingAlgorithm"/>
+</p>
+
+- 算法复杂度：O(1)
+- 性能 : 相比于 `org.apache.shardingsphere.sharding.algorithm.sharding.mod.ModShardingAlgorithm` 性能高出 *1200~4000* 倍。并且稳定性更高，不会出现严重的性能退化。
+
+| **PreciseShardingValue**                                                                                   | **RangeShardingValue**                                                                                   |
+|------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
+| <img src="../../public/assets/perf/sharding/Throughput-Of-ModShardingAlgorithm-PreciseShardingValue.png"/> | <img src="../../public/assets/perf/sharding/Throughput-Of-ModShardingAlgorithm-RangeShardingValue.png"/> |
+
-Original file line number
+Diff line change
@@ Expand Up / @@ -33,6 +33,8 @@ @@
     ```
     :::
+    ## 使用
     ```java
     public class AsStringDto {
@@ Expand Down @@