From 7114b85a231fab334440c2ac24e756230299f8d0 Mon Sep 17 00:00:00 2001 From: Ahoo Wang Date: Wed, 3 Jan 2024 16:07:23 +0800 Subject: [PATCH] feat(doc): add specific-id.md (#518) --- .../docs/.vitepress/configs/sidebar.ts | 2 +- documentation/docs/guide/cosid-proxy.md | 7 +- documentation/docs/guide/specific-id.md | 548 ++++++++++++++++++ examples/cosid-example-redis/build.gradle.kts | 4 +- .../redis/controller/IdController.java | 21 +- .../src/main/resources/application.yaml | 82 ++- 6 files changed, 634 insertions(+), 30 deletions(-) create mode 100644 documentation/docs/guide/specific-id.md diff --git a/documentation/docs/.vitepress/configs/sidebar.ts b/documentation/docs/.vitepress/configs/sidebar.ts index 1e64898ba5..f846087f8a 100644 --- a/documentation/docs/.vitepress/configs/sidebar.ts +++ b/documentation/docs/.vitepress/configs/sidebar.ts @@ -28,8 +28,8 @@ export const sidebar: DefaultTheme.Sidebar = { {text: 'CosIdGenerator', link: 'cosid-generator'}, {text: 'IdConverter', link: 'id-converter'}, {text: 'Id生成器容器', link: 'provider'}, + {text:'特定场景ID配置',link: 'specific-id'}, {text: 'CosIdProxy', link: 'cosid-proxy'}, - ], }, { base: '/guide/extensions/', diff --git a/documentation/docs/guide/cosid-proxy.md b/documentation/docs/guide/cosid-proxy.md index 044d7301c6..4b6c3d9112 100644 --- a/documentation/docs/guide/cosid-proxy.md +++ b/documentation/docs/guide/cosid-proxy.md @@ -1 +1,6 @@ -# CosId Proxy 模块 \ No newline at end of file +# CosId Proxy 模块 + +
+ +![CosId Proxy](../public/assets/design/CosId-Proxy.png) +
\ No newline at end of file diff --git a/documentation/docs/guide/specific-id.md b/documentation/docs/guide/specific-id.md new file mode 100644 index 0000000000..cd33fb16b1 --- /dev/null +++ b/documentation/docs/guide/specific-id.md @@ -0,0 +1,548 @@ +# 特定场景ID配置 + +## snowflake_friendly + +使用 _SnowflakeId_ 算法，要求输出的ID字符串： + +- 格式：`yyyyMMddHHmmssSSS--` +- 例如：`20240103152415876-5-16` + +::: code-group +```yaml {9-11} [配置] +cosid: + machine: + enabled: true + distributor: + type: redis + snowflake: + enabled: true + provider: + snowflake_friendly: + converter: + type: snowflake_friendly +``` +```json [配置信息] +{ + "snowflake_friendly": { + "kind": "DefaultSnowflakeFriendlyId", + "actual": { + "kind": "ClockSyncSnowflakeId", + "actual": { + "kind": "MillisecondSnowflakeId", + "epoch": 1577203200000, + "timestampBit": 41, + "machineBit": 10, + "sequenceBit": 12, + "isSafeJavascript": false, + "machineId": 5, + "lastTimestamp": -1, + "converter": { + "kind": "Radix62IdConverter", + "radix": 62, + "charSize": 11, + "padStart": true, + "maxId": 9223372036854775807 + } + }, + "converter": { + "kind": "Radix62IdConverter", + "radix": 62, + "charSize": 11, + "padStart": true, + "maxId": 9223372036854775807 + } + }, + "converter": { + "kind": "SnowflakeFriendlyIdConverter", // [!code focus] + "actual": null + } + } +} +``` +::: + +## snowflake_short_id + +使用 _SnowflakeId_ 算法，要求输出的ID字符串： + +- 格式：尽可能短 +- 例如：`0dMszf3Ht1l` + +::: code-group +```yaml {9-14} [配置] +cosid: + machine: + enabled: true + distributor: + type: redis + snowflake: + enabled: true + provider: + snowflake_short_id: + converter: + type: radix + radix: + char-size: 11 + pad-start: true +``` +```json [配置信息] +{ + "snowflake_short_id": { + "kind": "DefaultSnowflakeFriendlyId", + "actual": { + "kind": "ClockSyncSnowflakeId", + "actual": { + "kind": "MillisecondSnowflakeId", + "epoch": 1577203200000, + "timestampBit": 41, + "machineBit": 10, + "sequenceBit": 12, + "isSafeJavascript": false, + "machineId": 5, + "lastTimestamp": -1, + "converter": { + "kind": "Radix62IdConverter", + "radix": 62, + "charSize": 11, + "padStart": true, + "maxId": 9223372036854775807 + } + }, + "converter": { + "kind": "Radix62IdConverter", + "radix": 62, + "charSize": 11, + "padStart": true, + "maxId": 9223372036854775807 + } + }, + "converter": { + "kind": "Radix62IdConverter", + "radix": 62, + "charSize": 11, + "padStart": true, + "maxId": 9223372036854775807 + } + } +} +``` +::: + +## snowflake_friendly_second + +使用 _SnowflakeId_ 算法，要求输出的ID字符串： + +- 格式：`yyyyMMddHHmmss--` +- 例如：`20240103153900-5-4` + +::: code-group +```yaml {9-16} [配置] +cosid: + machine: + enabled: true + distributor: + type: redis + snowflake: + enabled: true + provider: + snowflake_friendly_second: + timestamp-unit: second + epoch: 1577203200 + timestamp-bit: 31 + machine-bit: 10 + sequence-bit: 22 + converter: + type: snowflake_friendly +``` +```json [配置信息] +{ + "snowflake_friendly_second": { + "kind": "DefaultSnowflakeFriendlyId", + "actual": { + "kind": "ClockSyncSnowflakeId", + "actual": { + "kind": "SecondSnowflakeId", + "epoch": 1577203200, + "timestampBit": 31, + "machineBit": 10, + "sequenceBit": 22, + "isSafeJavascript": false, + "machineId": 5, + "lastTimestamp": 1704265875, + "converter": { + "kind": "Radix62IdConverter", + "radix": 62, + "charSize": 11, + "padStart": true, + "maxId": 9223372036854775807 + } + }, + "converter": { + "kind": "Radix62IdConverter", + "radix": 62, + "charSize": 11, + "padStart": true, + "maxId": 9223372036854775807 + } + }, + "converter": { + "kind": "SnowflakeFriendlyIdConverter", + "actual": null + } + } +} +``` +::: + +## biz_prefix_no + +使用 _SegmentId_ 算法，要求输出的ID字符串： +- 起始序号：`2000000000` +- 格式：`` +- 序号位：10位数值，不足10位前补0 +- 例如：`BIZ2000000219` + +::: code-group +```yaml {7-14} [配置] +cosid: + segment: + enabled: true + distributor: + type: redis + provider: + biz_prefix_no: + offset: 2000000000 + converter: + type: to_string + prefix: BIZ + to-string: + char-size: 10 + pad-start: true +``` +```json [配置信息] +{ + "biz_prefix_no": { + "kind": "StringSegmentId", + "actual": { + "kind": "SegmentChainId", + "fetchTime": 1704265844, + "maxId": 2000000220, + "offset": 2000000200, + "sequence": 2000000218, + "step": 20, + "isExpired": false, + "isOverflow": false, + "isAvailable": true, + "converter": { + "kind": "Radix62IdConverter", + "radix": 62, + "charSize": 11, + "padStart": true, + "maxId": 9223372036854775807 + } + }, + "converter": { + "kind": "PrefixIdConverter", + "prefix": "BIZ", + "actual": { + "kind": "ToStringIdConverter", + "padStart": true, + "charSize": 10 + } + } + } +} +``` +::: + +## no_suffix_biz + +使用 _SegmentId_ 算法，要求输出的ID字符串： +- 起始序号：`2000000000` +- 格式：`` +- 序号位：10位数值，不足10位前补0 +- 例如：`2000000201BIZ` + +::: code-group +```yaml {7-14} [配置] +cosid: + segment: + enabled: true + distributor: + type: redis + provider: + no_suffix_biz: + offset: 2000000000 + converter: + type: to_string + suffix: BIZ + to-string: + char-size: 10 + pad-start: true +``` +```json [配置信息] +{ + "no_suffix_biz": { + "kind": "StringSegmentId", + "actual": { + "kind": "SegmentChainId", + "fetchTime": 1704265915, + "maxId": 2000000210, + "offset": 2000000200, + "sequence": 2000000200, + "step": 10, + "isExpired": false, + "isOverflow": false, + "isAvailable": true, + "converter": { + "kind": "Radix62IdConverter", + "radix": 62, + "charSize": 11, + "padStart": true, + "maxId": 9223372036854775807 + } + }, + "converter": { + "kind": "SuffixIdConverter", + "suffix": "BIZ", + "actual": { + "kind": "ToStringIdConverter", + "padStart": true, + "charSize": 10 + } + } + } +} +``` +::: + +## biz_prefix_radix + +使用 _SegmentId_ 算法，要求输出的ID字符串： +- 起始序号：`2000000000` +- 格式：`` +- 序号位：6位62进制字符串，不足6位前补0 +- 例如：`BIZ2BLnPb` + +::: code-group +```yaml {7-14} [配置] +cosid: + segment: + enabled: true + distributor: + type: redis + provider: + biz_prefix_radix: + offset: 2000000000 + converter: + type: radix + prefix: BIZ + radix: + char-size: 6 + pad-start: true +``` +```json [配置信息] +{ + "biz_prefix_radix": { + "kind": "StringSegmentId", + "actual": { + "kind": "SegmentChainId", + "fetchTime": 1704265844, + "maxId": 2000000200, + "offset": 2000000180, + "sequence": 2000000190, + "step": 20, + "isExpired": false, + "isOverflow": false, + "isAvailable": true, + "converter": { + "kind": "Radix62IdConverter", + "radix": 62, + "charSize": 11, + "padStart": true, + "maxId": 9223372036854775807 + } + }, + "converter": { + "kind": "PrefixIdConverter", + "prefix": "BIZ", + "actual": { + "kind": "Radix62IdConverter", + "radix": 62, + "charSize": 6, + "padStart": true, + "maxId": 56800235584 + } + } + } +} +``` +::: + +## biz_prefix_radix36 + +使用 _SegmentId_ 算法，要求输出的ID字符串： +- 起始序号：`2000000000` +- 格式：`` +- 序号位：8位36进制字符串，不足8位前补0 +- 例如：`BIZ00000044` + +::: code-group +```yaml {7-14} [配置] +cosid: + segment: + enabled: true + distributor: + type: redis + provider: + biz_prefix_radix: + offset: 2000000000 + converter: + type: radix + prefix: BIZ + radix: + char-size: 6 + pad-start: true +``` +```json [配置信息] +{ + "biz_prefix_radix36": { + "kind": "StringSegmentId", + "actual": { + "kind": "SegmentChainId", + "fetchTime": 1704265844, + "maxId": 150, + "offset": 130, + "sequence": 147, + "step": 20, + "isExpired": false, + "isOverflow": false, + "isAvailable": true, + "converter": { + "kind": "Radix62IdConverter", + "radix": 62, + "charSize": 11, + "padStart": true, + "maxId": 9223372036854775807 + } + }, + "converter": { + "kind": "PrefixIdConverter", + "prefix": "BIZ", + "actual": { + "kind": "Radix36IdConverter", + "radix": 36, + "charSize": 8, + "padStart": true, + "maxId": 2821109907456 + } + } + } +} +``` +::: + +## group_year_biz + +使用 _SegmentId_ 算法，要求输出的ID字符串： +- 起始序号：`0` +- 格式：`` +- 分组：按年分组，每年序号从0开始。即每年序号需要重置为0. +- 序号位：8位数值，不足8位前补0 +- 例如：`BIZ-2024-00000231` + +::: code-group +```yaml {7-17} [配置] +cosid: + segment: + enabled: true + distributor: + type: redis + provider: + group_year_biz: + group: + by: year + converter: + type: to_string + to-string: + pad-start: true + char-size: 8 + prefix: BIZ- + group-prefix: + enabled: true +``` +```json [配置信息] +{ + "group_year_biz": { + "kind": "StringSegmentId", + "actual": { + "kind": "SegmentChainId", + "fetchTime": 1704265845, + "maxId": 240, + "offset": 220, + "sequence": 230, + "step": 20, + "isExpired": false, + "isOverflow": false, + "isAvailable": true, + "converter": { + "kind": "Radix62IdConverter", + "radix": 62, + "charSize": 11, + "padStart": true, + "maxId": 9223372036854775807 + } + }, + "converter": { + "kind": "PrefixIdConverter", + "prefix": "BIZ-", + "actual": { + "kind": "GroupedPrefixIdConverter", + "delimiter": "-", + "actual": { + "kind": "ToStringIdConverter", + "padStart": true, + "charSize": 8 + } + } + } + } +} +``` +::: + +## 百万级规模集群实例的全局ID + +使用 _CosIdGenerator_ 算法，要求支持百万级规模集群实例的全局ID生成器。 + +::: code-group +```yaml {6-7} [配置] +cosid: + machine: + enabled: true + distributor: + type: redis + generator: + enabled: true +``` +```json [配置信息] +{ + "cosid": { + "kind": "ClockSyncCosIdGenerator", + "actual": { + "kind": "Radix62CosIdGenerator", + "machineId": 5, + "lastTimestamp": 1704265904677, + "converter": { + "kind": "RadixCosIdStateParser", + "actual": null + } + }, + "converter": { + "kind": "RadixCosIdStateParser", + "actual": null + } + } +} +``` +::: \ No newline at end of file diff --git a/examples/cosid-example-redis/build.gradle.kts b/examples/cosid-example-redis/build.gradle.kts index 7900ae14b8..991a76d5c3 100644 --- a/examples/cosid-example-redis/build.gradle.kts +++ b/examples/cosid-example-redis/build.gradle.kts @@ -50,11 +50,11 @@ dependencies { implementation(project(":cosid-spring-boot-starter")) implementation(project(":cosid-jackson")) implementation(project(":cosid-spring-redis")) -// implementation("org.springframework.cloud:spring-cloud-commons") + implementation("org.springdoc:springdoc-openapi-starter-webflux-ui") implementation("org.springframework.boot:spring-boot-starter-data-redis") implementation("org.springframework.boot:spring-boot-starter-actuator") implementation("com.google.guava:guava") - implementation("org.springframework.boot:spring-boot-starter-web") + implementation("org.springframework.boot:spring-boot-starter-webflux") compileOnly("org.projectlombok:lombok") annotationProcessor("org.projectlombok:lombok") annotationProcessor("org.springframework.boot:spring-boot-configuration-processor") diff --git a/examples/cosid-example-redis/src/main/java/me/ahoo/cosid/example/redis/controller/IdController.java b/examples/cosid-example-redis/src/main/java/me/ahoo/cosid/example/redis/controller/IdController.java index 82c308df91..84ddcb55f1 100644 --- a/examples/cosid-example-redis/src/main/java/me/ahoo/cosid/example/redis/controller/IdController.java +++ b/examples/cosid-example-redis/src/main/java/me/ahoo/cosid/example/redis/controller/IdController.java @@ -13,13 +13,10 @@ package me.ahoo.cosid.example.redis.controller; -import me.ahoo.cosid.IdGenerator; import me.ahoo.cosid.provider.IdGeneratorProvider; -import org.springframework.beans.factory.annotation.Autowired; -import org.springframework.beans.factory.annotation.Qualifier; -import org.springframework.context.annotation.Lazy; import org.springframework.web.bind.annotation.GetMapping; +import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @@ -32,26 +29,22 @@ @RequestMapping("ids") public class IdController { private final IdGeneratorProvider provider; - @Qualifier("__share__SegmentId") - @Autowired - @Lazy - private IdGenerator idGenerator; public IdController(IdGeneratorProvider provider) { this.provider = provider; } - @GetMapping - public long generate() { + @GetMapping("{idName}") + public long generate(@PathVariable String idName) { return provider - .getShare() + .getRequired(idName) .generate(); } - @GetMapping("/as-string") - public String generateAsString() { + @GetMapping("/{idName}/as-string") + public String generateAsString(@PathVariable String idName) { return provider - .getShare() + .getRequired(idName) .generateAsString(); } diff --git a/examples/cosid-example-redis/src/main/resources/application.yaml b/examples/cosid-example-redis/src/main/resources/application.yaml index d16984f6e4..63591c300a 100644 --- a/examples/cosid-example-redis/src/main/resources/application.yaml +++ b/examples/cosid-example-redis/src/main/resources/application.yaml @@ -6,7 +6,8 @@ management: - cosid - cosidGenerator - cosidStringGenerator - +springdoc: + show-actuator: true server: port: 8601 spring: @@ -21,25 +22,82 @@ cosid: enabled: true distributor: type: redis + generator: + enabled: true snowflake: - enabled: false + enabled: true + share: + enabled: false + provider: + snowflake_friendly: + converter: + type: snowflake_friendly + snowflake_short_id: + converter: + type: radix + radix: + char-size: 11 + pad-start: true + snowflake_friendly_second: + timestamp-unit: second + epoch: 1577203200 + timestamp-bit: 31 + machine-bit: 10 + sequence-bit: 22 + converter: + type: snowflake_friendly segment: enabled: true mode: chain distributor: type: redis share: - group: - by: year - converter: - type: to_string - to-string: - pad-start: true - char-size: 8 - prefix: COSID- - group-prefix: - enabled: true + enabled: false + provider: + biz_prefix_no: + offset: 2000000000 + converter: + type: to_string + prefix: BIZ + to-string: + char-size: 10 + pad-start: true + no_suffix_biz: + offset: 2000000000 + converter: + type: to_string + suffix: BIZ + to-string: + char-size: 10 + pad-start: true + biz_prefix_radix: + offset: 2000000000 + converter: + type: radix + prefix: BIZ + radix: + char-size: 6 + pad-start: true + biz_prefix_radix36: + converter: + type: radix36 + prefix: BIZ + radix36: + char-size: 8 + pad-start: true + group_year_biz: + group: + by: year + converter: + type: to_string + to-string: + pad-start: true + char-size: 8 + prefix: BIZ- + group-prefix: + enabled: true logging: level: me.ahoo.cosid: debug +