add document

cosid-spring-boot-starter/src/main/java/me/ahoo/cosid/spring/boot/starter/segment/CosIdSegmentAutoConfiguration.java

@@ -74,7 +74,6 @@ public SegmentId shareSegmentId(IdSegmentDistributorFactory distributorFactory,
         IdSegmentDistributorDefinition shareDistributorDefinition = asDistributorDefinition(IdGeneratorProvider.SHARE, shareIdDefinition);
         IdSegmentDistributor shareIdSegmentDistributor = distributorFactory.create(shareDistributorDefinition);
 
-
         SegmentId shareIdGen = createSegment(segmentIdProperties, shareIdDefinition, shareIdSegmentDistributor, prefetchWorkerExecutorService);
 
         if (Objects.isNull(idGeneratorProvider.getShare())) {

cosid-spring-boot-starter/src/main/java/me/ahoo/cosid/spring/boot/starter/segment/SegmentIdProperties.java

@@ -38,7 +38,6 @@ public class SegmentIdProperties {
 
     private boolean enabled = false;
     private Mode mode = Mode.CHAIN;
-    private long step;
     /**
      * idSegment time to live
      * unit {@link java.util.concurrent.TimeUnit#SECONDS}
@@ -71,14 +70,6 @@ public void setMode(Mode mode) {
         this.mode = mode;
     }
 
-    public long getStep() {
-        return step;
-    }
-
-    public void setStep(int step) {
-        this.step = step;
-    }
-
     public long getTtl() {
         return ttl;
     }

cosid-spring-boot-starter/src/main/java/me/ahoo/cosid/spring/boot/starter/zookeeper/CosIdZookeeperProperties.java

@@ -87,33 +87,33 @@ public void setConnectionTimeout(Duration connectionTimeout) {
 
     public static class Retry {
 
-        private Integer baseSleepTimeMs = 100;
+        private int baseSleepTimeMs = 100;
 
-        private Integer maxRetries = 5;
+        private int maxRetries = 5;
 
-        private Integer maxSleepMs = 500;
+        private int maxSleepMs = 500;
 
-        public Integer getBaseSleepTimeMs() {
+        public int getBaseSleepTimeMs() {
             return baseSleepTimeMs;
         }
 
-        public void setBaseSleepTimeMs(Integer baseSleepTimeMs) {
+        public void setBaseSleepTimeMs(int baseSleepTimeMs) {
             this.baseSleepTimeMs = baseSleepTimeMs;
         }
 
-        public Integer getMaxRetries() {
+        public int getMaxRetries() {
             return maxRetries;
         }
 
-        public void setMaxRetries(Integer maxRetries) {
+        public void setMaxRetries(int maxRetries) {
             this.maxRetries = maxRetries;
         }
 
-        public Integer getMaxSleepMs() {
+        public int getMaxSleepMs() {
             return maxSleepMs;
         }
 
-        public void setMaxSleepMs(Integer maxSleepMs) {
+        public void setMaxSleepMs(int maxSleepMs) {
             this.maxSleepMs = maxSleepMs;
         }
     }

document/docs/README.md

@@ -0,0 +1,16 @@
+---
+home: true
+heroImage: /logo.png
+heroText: CosId
+tagline: 通用、灵活、高性能分布式ID生成器
+actionText: 快速上手 →
+actionLink: /guide/
+features:
+- title: 通用
+  details: 支持多种类型的分布式ID算法：SnowflakeId、SegmentId、SegmentChainId。 并且支持多种号段分发器、机器号分发器。
+- title: 灵活
+  details: 通过简单配置即可自定义切换多种算法实现，定制以满足场景需要。
+- title: 高性能
+  details: 设计极致优化，SegmentChainId 性能可达到近似 AtomicLong 的 TPS 性能:12743W+/s。
+footer: Apache 2.0 Licensed | Copyright © 2021-present Ahoo Wang
+---

document/docs/config/README.md

@@ -0,0 +1,52 @@
+# 基础配置
+
+> `me.ahoo.cosid.spring.boot.starter.CosIdProperties`
+
+| 名称        | 数据类型      | 说明                   | 默认值       |
+|-----------|-----------|----------------------|-----------|
+| enabled   | `boolean` | 是否启用 CosId           | `true`    |
+| namespace | `String`  | 命名空间，用于隔离不同应用间的分布式ID | `{cosid}` |
+
+**YAML 配置样例**
+
+```yaml
+cosid:
+  namespace: ${spring.application.name}
+```
+
+## IdConverterDefinition
+
+> `me.ahoo.cosid.spring.boot.starter.IdConverterDefinition`
+
+| 名称     | 数据类型                          | 说明                                             | 默认值                         |
+|--------|-------------------------------|------------------------------------------------|-----------------------------|
+| type   | `IdConverterDefinition.Type`  | 转换器类型：`TO_STRING`、`SNOWFLAKE_FRIENDLY`、`RADIX` | `Type.TO_STRING`            |
+| prefix | `String`                      | 前缀                                             | `""`                        |
+| radix  | `IdConverterDefinition.Radix` | `Radix62IdConverter` 转换器配置                     | `TimestampUnit.MILLISECOND` |
+
+### Radix
+
+| 名称        | 数据类型      | 说明                                                    | 默认值     |
+|-----------|-----------|-------------------------------------------------------|---------|
+| char-size | `String`  | 字符串ID长度                                               | `11`    |
+| pad-start | `boolean` | 当字符串不满足 `charSize` 时，是否填充字符(`'0'`)。如果需要保证字符串有序，需开启该功能 | `false` |
+
+**YAML 配置样例**
+
+```yaml
+cosid:
+  snowflake:
+    share:
+      converter:
+        prefix: cosid_
+        radix:
+          pad-start: false
+          char-size: 11
+  segment:
+    share:
+      converter:
+        prefix: cosid_
+        radix:
+          pad-start: false
+          char-size: 8
+```

document/docs/config/segment.md

@@ -0,0 +1,88 @@
+# SegmentId 配置
+
+> `me.ahoo.cosid.spring.boot.starter.segment.SegmentIdProperties`
+
+| 名称          | 数据类型                        | 说明                         | 默认值                    |
+|-------------|-----------------------------|----------------------------|------------------------|
+| enabled     | `boolean`                   | 是否启用                       | `false`                |
+| mode        | `Mode`                      | 号段生成器模式：`DEFAULT`/ `CHAIN` | `CHAIN`                |
+| ttl         | `long`                      | 号段的生存期（秒）                  | `TIME_TO_LIVE_FOREVER` |
+| distributor | `Distributor`               | 号段分发器                      |                        |
+| chain       | `Chain`                     | 号段链模式配置                    |                        |
+| share       | `IdDefinition`              | 共享ID生成器配置                  |                        |
+| provider    | `Map<String, IdDefinition>` | 多ID生成器配置                   |                        |
+
+## Distributor
+
+> `me.ahoo.cosid.spring.boot.starter.segment.SegmentIdProperties.Distributor`
+
+| 名称   | 数据类型               | 说明                                  | 默认值          |
+|------|--------------------|-------------------------------------|--------------|
+| type | `Distributor.Type` | 号段分发器类型： `REDIS`/`JDBC`/`ZOOKEEPER` | `Type.REDIS` |
+| jdbc | `Distributor.Jdbc` | Jdbc号段生成器配置                         |              |
+
+### Distributor.Jdbc
+
+| 名称                           | 数据类型      | 说明             | 默认值     |
+|------------------------------|-----------|----------------|---------|
+| enable-auto-init-cosid-table | `boolean` | 自动创建号段`cosid`表 | `false` |
+| enable-auto-init-id-segment  | `boolean` | 自动创建号段行        | `true`  |
+
+## Chain
+
+> `me.ahoo.cosid.spring.boot.starter.segment.SegmentIdProperties.Chain`
+
+| 名称              | 数据类型                   | 说明         | 默认值    |
+|-----------------|------------------------|------------|--------|
+| safe-distance   | `int`                  | 安全距离       | `10`   |
+| prefetch-worker | `Chain.PrefetchWorker` | 号段预取工作者线程池 | `true` |
+
+### Chain.PrefetchWorker
+
+| 名称              | 数据类型       | 说明    | 默认值                                          |
+|-----------------|------------|-------|----------------------------------------------|
+| prefetch-period | `Duration` | 预取周期  | `Duration.ofSeconds(1)`                      |
+| core-pool-size  | `int`      | 线程池大小 | `Runtime.getRuntime().availableProcessors()` |
+
+## IdDefinition
+
+> `me.ahoo.cosid.spring.boot.starter.segment.SegmentIdProperties.IdDefinition`
+
+| 名称        | 数据类型                    | 说明                         | 默认值                   |
+|-----------|-------------------------|----------------------------|-----------------------|
+| mode      | `Mode`                  | 号段生成器模式：`DEFAULT`/ `CHAIN` | `cosid.segment.mode`  |
+| offset    | `int`                   | 号段初始偏移量                    | `0`                   |
+| step      | `long`                  | 步长                         | 100                   |
+| ttl       | `long`                  | 号段的生存期（秒）                  | `cosid.segment.ttl`   |
+| chain     | `Chain`                 | 号段链模式配置                    | `cosid.segment.chain` |
+| converter | `IdConverterDefinition` | Id转换器配置                    |                       |
+
+**YAML 配置样例**
+
+```yaml
+cosid:
+  namespace: ${spring.application.name}
+  segment:
+    enabled: true
+    mode: chain
+    chain:
+      safe-distance: 5
+      prefetch-worker:
+        core-pool-size: 2
+        prefetch-period: 1s
+    distributor:
+      type: redis
+    share:
+      offset: 0
+      step: 100
+      converter:
+        prefix: cosid_
+        type: radix
+        radix:
+          char-size: 6
+          pad-start: false
+    provider:
+      order:
+        offset: 10000
+        step: 100
+```

document/docs/config/snowflake.md

@@ -0,0 +1,110 @@
+# SnowflakeId 配置
+
+> `me.ahoo.cosid.spring.boot.starter.snowflake.SnowflakeIdProperties`
+
+| 名称              | 数据类型                        | 说明        | 默认值                                             |
+|-----------------|-----------------------------|-----------|-------------------------------------------------|
+| enabled         | `boolean`                   | 是否启用      | `false`                                         |
+| zoneId          | `String`                    | 时区        | `ZoneId.systemDefault().getId()`                |
+| epoch           | `long`                      | EPOCH     | `CosId.COSID_EPOCH` <br> (UTC 2019-12-24 16:00) |
+| clock-backwards | `ClockBackwards`            | 时钟回拨配置    |                                                 |
+| machine         | `Machine`                   | 机器号分配器配置  |                                                 |
+| share           | `IdDefinition`              | 共享ID生成器配置 | 有                                               |
+| provider        | `Map<String, IdDefinition>` | 多ID生成器配置  | `null`                                          |
+
+## ClockBackwards
+
+> `me.ahoo.cosid.spring.boot.starter.snowflake.SnowflakeIdProperties.ClockBackwards`
+
+| 名称               | 数据类型  | 说明                                           | 默认值    |
+|------------------|-------|----------------------------------------------|--------|
+| spin-threshold   | `int` | 自旋同步阈值（ms）                                   | `10`   |
+| broken-threshold | `int` | 抛出异常（`ClockTooManyBackwardsException`）阈值（ms） | `2000` |
+
+## Machine
+
+> `me.ahoo.cosid.spring.boot.starter.snowflake.SnowflakeIdProperties.Machine`
+
+| 名称           | 数据类型                   | 说明                   | 默认值       |
+|--------------|------------------------|----------------------|-----------|
+| stable       | `boolean`              | 是否为稳定的实例,稳定实例将不回收机器号 | `false`   |
+| port         | `Integer`              | 端口号                  | 进程ID（PID） |
+| instanceId   | `String`               | 应用实例编号(全局唯一)         | 应用IP:PID  |
+| machineBit   | `int`                  | 机器位数                 | `10`      |
+| stateStorage | `Machine.StateStorage` | 机器状态存储               |           |
+| distributor  | `Machine.Distributor`  | 机器号分发器               |           |
+
+### Machine.StateStorage
+
+| 名称      | 数据类型                         | 说明         | 默认值    |
+|---------|------------------------------|------------|--------|
+| enabled | `boolean`                    | 是否启用状态存储   | `true` |
+| local   | `Machine.StateStorage.Local` | 本地机器状态存储配置 |        |
+
+#### Machine.StateStorage.Local
+
+| 名称             | 数据类型     | 说明     | 默认值                      |
+|----------------|----------|--------|--------------------------|
+| state-location | `String` | 状态存储位置 | `./cosid-machine-state/` |
+
+### Machine.Distributor
+
+| 名称     | 数据类型                         | 说明                                                          | 默认值      |
+|--------|------------------------------|-------------------------------------------------------------|----------|
+| type   | `Machine.Distributor.Type`   | 机器号分配器类型：`MANUAL`/`STATEFUL_SET`/`JDBC`/`REDIS`/`ZOOKEEPER` | `MANUAL` |
+| manual | `Machine.Distributor.Manual` | 手动分配器配置                                                     |          |
+
+#### Machine.Distributor.Manual
+
+| 名称        | 数据类型      | 说明  | 默认值    |
+|-----------|-----------|-----|--------|
+| machineId | `Integer` | 机器号 | `null` |
+
+## IdDefinition
+
+> `me.ahoo.cosid.spring.boot.starter.snowflake.SnowflakeIdProperties.IdDefinition`
+
+| 名称             | 数据类型                         | 说明                               | 默认值                                   |
+|----------------|------------------------------|----------------------------------|---------------------------------------|
+| clock-sync     | `boolean`                    | 是否开启时钟同步                         | `true`                                |
+| friendly       | `boolean`                    | 是否启用`SnowflakeFriendlyId`        | `true`                                |
+| timestamp-unit | `IdDefinition.TimestampUnit` | 时间戳位的单位：`SECOND` / `MILLISECOND` | `TimestampUnit.MILLISECOND`           |
+| epoch          | `int`                        | EPOCH                            | `cosid.snowflake.epoch`               |
+| timestamp-bit  | `int`                        | 时间戳位数                            | 41                                    |
+| machine-bit    | `int`                        | 机器位数                             | `cosid.snowflake.machine.machine-bit` |
+| sequence-bit   | `int`                        | 序列位数                             | 12                                    |
+| converter      | `IdConverterDefinition`      | Id转换器配置                          |                                       |
+
+**YAML 配置样例**
+
+```yaml
+cosid:
+  namespace: ${spring.application.name}
+  snowflake:
+    enabled: true
+    zone-id: Asia/Shanghai
+    epoch: 1577203200000
+    clock-backwards:
+      spin-threshold: 10
+      broken-threshold: 2000
+    machine:
+      distributor:
+        type: redis
+      state-storage:
+        local:
+          state-location: ./cosid-machine-state/
+    share:
+      clock-sync: true
+      friendly: true
+    provider:
+      short_id:
+        converter:
+          prefix: cosid_
+          type: radix
+          radix:
+            char-size: 11
+            pad-start: false
+      safe-js:
+        machine-bit: 3
+        sequence-bit: 9
+```

document/docs/config/zookeeper.md

@@ -0,0 +1,41 @@
+# ZooKeeper 配置
+
+> `me.ahoo.cosid.spring.boot.starter.zookeeper.CosIdZookeeperProperties`
+
+| 名称                         | 数据类型       | 说明              | 默认值                      |
+|----------------------------|------------|-----------------|--------------------------|
+| 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`    | 重试策略配置          |                          |
+
+## Retry (`ExponentialBackoffRetry`) 配置
+
+| 名称              | 数据类型  | 说明                | 默认值   |
+|-----------------|-------|-------------------|-------|
+| baseSleepTimeMs | `int` | 重试之间等待的初始时间量 （毫秒） | `100` |
+| maxRetries      | `int` | 最大重试次数            | `5`   |
+| maxSleepMs      | `int` | 每次重试时的最大睡眠时间（毫秒）  | `500` |
+
+**YAML 配置样例**
+
+```yaml
+cosid:
+  zookeeper:
+    enabled: true
+    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
+  snowflake:
+    machine:
+      distributor:
+        type: zookeeper
+```