feat(doc): Use VitePress instead of Vuepress

Ahoo-Wang · Dec 29, 2023 · dd0cc77 · dd0cc77
1 parent 2a3b52c
commit dd0cc77
Show file tree

Hide file tree

Showing 75 changed files with 2,207 additions and 0 deletions.
diff --git a/documentation/.gitignore b/documentation/.gitignore
@@ -0,0 +1,5 @@
+node_modules
+.temp
+cache
+docs/.vitepress/dist
+docs/.vitepress/public/dokka
diff --git a/documentation/docs/.vitepress/config.mts b/documentation/docs/.vitepress/config.mts
@@ -0,0 +1,56 @@
+import {defineConfig} from 'vitepress'
+import {SITE_BASE} from "./configs/SITE_BASE";
+import {head} from "./configs/head";
+import {navbar} from "./configs/navbar";
+import {sidebar} from "./configs/sidebar";
+
+let hostname = 'https://cosid.ahoo.me/';
+if (SITE_BASE == '/wow/') {
+    hostname = 'https://ahoowang.gitee.io/cosid/'
+}
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+    lang: 'zh-CN',
+    title: "CosId",
+    description: "通用、灵活、高性能的分布式ID生成器",
+    ignoreDeadLinks: 'localhostLinks',
+    head: head,
+    base: SITE_BASE,
+    sitemap: {
+        hostname: hostname
+    },
+    appearance: 'dark',
+    themeConfig: {
+        logo: '/logo.png',
+        siteTitle: '分布式ID生成器 | CosId',
+        editLink: {
+            pattern: 'https://github.com/Ahoo-Wang/CosId/edit/main/documentation/docs/:path'
+        },
+        lastUpdated: {
+            text: '上次更新'
+        },
+        outline: {
+            label: '本页目录',
+            level: [2, 3]
+        },
+        aside: true,
+        search: {provider: 'local',},
+        // https://vitepress.dev/reference/default-theme-config
+        nav: navbar,
+        sidebar: sidebar,
+        socialLinks: [
+            {icon: 'github', link: 'https://github.com/Ahoo-Wang/CosId'}
+        ],
+        externalLinkIcon: true,
+        footer: {
+            message: 'Released under the Apache 2.0 License.',
+            copyright: 'Copyright © 2022-present <a href="https://github.com/Ahoo-Wang" target="_blank">Ahoo Wang</a>'
+        },
+        notFound: {
+            title: '页面未找到',
+            quote: '你访问的页面不存在。',
+            linkText: '返回首页'
+        }
+    }
+})
diff --git a/documentation/docs/.vitepress/configs/SITE_BASE.ts b/documentation/docs/.vitepress/configs/SITE_BASE.ts
@@ -0,0 +1,14 @@
+/*
+ * Copyright [2021-present] [ahoo wang <[email protected]> (https://github.com/Ahoo-Wang)].
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export const SITE_BASE: '/' | `/${string}/` = process.env.SITE_BASE || "/"
diff --git a/documentation/docs/.vitepress/configs/head.ts b/documentation/docs/.vitepress/configs/head.ts
@@ -0,0 +1,41 @@
+/*
+ * Copyright [2021-present] [ahoo wang <[email protected]> (https://github.com/Ahoo-Wang)].
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {SITE_BASE} from "./SITE_BASE";
+import {HeadConfig} from "vitepress";
+
+export const head: HeadConfig[] = [
+    ['link', {rel: 'icon', href: `${SITE_BASE}favicon.ico`}],
+    ['meta', {
+        name: 'keywords',
+        content: '通用, 灵活, 高性能的分布式ID生成器'
+    }],
+    ['meta', {'http-equiv': 'cache-control', content: 'no-cache, no-store, must-revalidate'}],
+    ['meta', {'http-equiv': 'pragma', content: 'no-cache'}],
+    ['meta', {'http-equiv': 'expires', content: '0'}],
+    ['link', {rel: 'manifest', href: `${SITE_BASE}manifest.webmanifest`}],
+    ['meta', {name: 'application-name', content: 'CosId'}],
+    ['meta', {name: 'theme-color', content: '#5f67ee'}],
+    [
+        'script',
+        {async: '', src: 'https://www.googletagmanager.com/gtag/js?id=G-SP6EEGK56L'}
+    ],
+    [
+        'script',
+        {},
+        `window.dataLayer = window.dataLayer || [];
+      function gtag(){dataLayer.push(arguments);}
+      gtag('js', new Date());
+      gtag('config', 'G-SP6EEGK56L');`
+    ]
+]
diff --git a/documentation/docs/.vitepress/configs/navbar.ts b/documentation/docs/.vitepress/configs/navbar.ts
@@ -0,0 +1,52 @@
+import {DefaultTheme} from "vitepress/types/default-theme";
+
+export const navbar: DefaultTheme.NavItem[] = [
+    {
+        text: '指南',
+        link: '/guide/getting-started',
+        activeMatch: '^/guide/'
+    },
+    {
+        text: '配置',
+        link: '/reference/config/basic',
+        activeMatch: '^/reference/config/'
+    },
+    {
+        text: "资源",
+        items: [
+            {
+                text: '开源项目 - 微服务治理',
+                items: [
+                    {
+                        text: 'Wow - 基于 DDD & EventSourcing 的现代响应式 CQRS 架构微服务开发框架',
+                        link: 'https://github.com/Ahoo-Wang/Wow'
+                    },
+                    {
+                        text: 'CoSky - 高性能、低成本微服务治理平台',
+                        link: 'https://github.com/Ahoo-Wang/CoSky'
+                    },
+                    {
+                        text: 'CoSec - 基于 RBAC 和策略的多租户响应式安全框架',
+                        link: 'https://github.com/Ahoo-Wang/CoSec'
+                    },
+                    {
+                        text: 'CoCache - 分布式一致性二级缓存框架',
+                        link: 'https://github.com/Ahoo-Wang/CoCache'
+                    },
+                    {
+                        text: 'Simba - 易用、灵活的分布式锁服务',
+                        link: 'https://github.com/Ahoo-Wang/Simba'
+                    }
+                ]
+            }
+        ]
+    },
+    {
+        text: `更新日志`,
+        link: `https://github.com/Ahoo-Wang/CosId/releases`
+    },
+    {
+        text: `Gitee`,
+        link: `https://gitee.com/AhooWang/CosId`
+    }
+]
diff --git a/documentation/docs/.vitepress/configs/sidebar.ts b/documentation/docs/.vitepress/configs/sidebar.ts
@@ -0,0 +1,86 @@
+/*
+ * Copyright [2021-present] [ahoo wang <[email protected]> (https://github.com/Ahoo-Wang)].
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {DefaultTheme} from "vitepress/types/default-theme";
+
+export const sidebar: DefaultTheme.Sidebar = {
+    '/guide/': [
+        {
+            base: '/guide/',
+            text: '指南',
+            collapsed: false,
+            items: [
+                {text: '简介', link: 'introduction'},
+                {text: '快速上手', link: 'getting-started'},
+                {text: '号段链模式', link: 'segment-chain'},
+                {text: 'Faq', link: 'faq'},
+                {text: '性能评测', link: 'perf-test'},
+                {text: 'CosId VS 美团 Leaf', link: 'Performance-CosId-Leaf'},
+            ],
+        }, {
+            base: '/guide/extensions/',
+            text: '扩展',
+            collapsed: false,
+            items: [
+                {text: 'Redis', link: 'cosid-redis'},
+                {text: 'Jdbc', link: 'cosid-jdbc'},
+                {text: 'Zookeeper', link: 'cosid-zookeeper'},
+                {text: 'MyBatis', link: 'cosid-mybatis'},
+                {text: 'Jackson', link: 'cosid-jackson'},
+                {text: 'ShardingSphere', link: 'cosid-shardingsphere'},
+                {text: 'Axon', link: 'cosid-axon'},
+                {text: 'Flowable', link: 'cosid-flowable'},
+            ],
+        }, {
+            text: '配置',
+            link: '/reference/config/basic'
+        }
+    ],
+    '/reference/': [
+        {
+            text: '配置',
+            base: '/reference/config/',
+            collapsed: false,
+            items: [
+                {text: '基础', link: 'basic'},
+                {text: '工作进程号', link: 'machine'},
+                {text: 'Snowflake', link: 'snowflake'},
+                {text: 'Segment', link: 'segment'},
+                {text: 'Zookeeper', link: 'zookeeper'},
+                {text: 'ShardingSphere', link: 'shardingsphere'},
+            ],
+        },
+        {
+            text: 'API',
+            base: '/reference/api/',
+            collapsed: false,
+            items: [
+                {text: 'IdGenerator', link: 'id-generator'},
+                {text: 'IdConverter', link: 'id-converter'},
+                {text: 'IdGeneratorProvider', link: 'provider'},
+                {text: 'CosIdGenerator', link: 'cosid-generator'},
+                {text: 'Segment', link: 'segment'},
+                {text: 'SnowflakeId', link: 'snowflake'},
+                {text: 'Sharding', link: 'sharding'},
+            ],
+        },
+        {
+            text: '博客',
+            base: '/reference/blog/',
+            collapsed: false,
+            items: [
+                {text: 'ShardingSphere 集成 CosId 实战', link: 'ShardingSphere-Integration-CosId'}
+            ],
+        }
+    ]
+}
diff --git a/documentation/docs/guide/Performance-CosId-Leaf.md b/documentation/docs/guide/Performance-CosId-Leaf.md
@@ -0,0 +1,58 @@
+# 分布式ID性能评测：CosId VS 美团 Leaf
+
+## 环境
+
+- MacBook Pro (M1)
+- JDK 17
+- JMH 1.36
+- 运行在本机 Docker 内的 mariadb:10.6.4 
+
+## 运行
+
+> 基准测试代码： [cosid-benchmark](https://github.com/Ahoo-Wang/CosId/tree/main/cosid-benchmark)
+
+``` shell
+git clone [email protected]:Ahoo-Wang/CosId.git
+cd cosid-benchmark
+./gradlew jmh
+```
+or
+```shell
+gradle jmhJar
+java -jar build/libs/cosid-benchmark-2.2.6-jmh.jar -wi 1 -rf json -f 1
+```
+
+## 报告
+
+```
+# JMH version: 1.36
+# VM version: JDK 17.0.7, OpenJDK 64-Bit Server VM, 17.0.7+7-LTS
+# Warmup: 1 iterations, 10 s each
+# Measurement: 1 iterations, 10 s each
+# Timeout: 10 min per iteration
+# Threads: 1 thread, will synchronize iterations
+
+Benchmark                     (step)   Mode  Cnt          Score   Error  Units
+AtomicLongBenchmark.generate     N/A  thrpt       142725210.565          ops/s
+CosIdBenchmark.generate            1  thrpt       131920684.604          ops/s
+CosIdBenchmark.generate          100  thrpt       132113994.232          ops/s
+CosIdBenchmark.generate         1000  thrpt       130281016.155          ops/s
+LeafBenchmark.generate             1  thrpt        25787669.815          ops/s
+LeafBenchmark.generate           100  thrpt        23897328.183          ops/s
+LeafBenchmark.generate          1000  thrpt        23550106.538          ops/s
+```
+
+<p align="center" >
+  <img  src="../public/assets/perf/CosId-VS-Leaf.png" alt="CosId VS 美团 Leaf"/>
+</p>
+
+> GitHub Action 环境测试报告: [Performance: CosId vs Leaf](https://github.com/Ahoo-Wang/CosId/issues/22)
+> 
+> 因受到 GitHub Runner 资源限制，运行在 GitHub Runner 中的基准测试与真实环境基准测试对比有非常大的差距（近2倍），
+但是对于运行在同一环境配置资源情况下（都运行在 GitHub Runner），进行 commit 前后的基准对比、以及第三方库的对比依然是有价值的。
+
+## 结论
+
+1. CosId (`SegmentChainId`) 性能是 Leaf (`segment`) 的 5 倍。
+2. CosId 、Leaf 的性能与号段步长(Step) 无关。
+3. CosId TPS 基本接近 `AtomicLong` 。
diff --git a/documentation/docs/guide/best-practices.md b/documentation/docs/guide/best-practices.md
@@ -0,0 +1 @@
+# 最佳实践
diff --git a/documentation/docs/guide/extensions/cosid-axon.md b/documentation/docs/guide/extensions/cosid-axon.md
@@ -0,0 +1,3 @@
+# CosId-Axon 模块
+
+TODO
diff --git a/documentation/docs/guide/extensions/cosid-flowable.md b/documentation/docs/guide/extensions/cosid-flowable.md
@@ -0,0 +1,3 @@
+# CosId-Flowable 模块
+
+TODO
diff --git a/documentation/docs/guide/extensions/cosid-jackson.md b/documentation/docs/guide/extensions/cosid-jackson.md
@@ -0,0 +1,59 @@
+# CosId-Jackson 模块
+
+> **Jackson** 序列化/反序列化注解插件，相当于隔离了应用API边界内外的 *ID* 使用方式，应用内部使用 `long`、外部使用 `String`，做到了应用无侵入，无感知。
+
+::: danger JavaScript Number 溢出问题
+
+`JavaScript` 的 `Number.MAX_SAFE_INTEGER` 只有**53-bit**，如果直接将63位的 `SnowflakeId` 返回给前端，那么会产生值溢出的情况（所以这里我们应该知道后端传给前端的 `long` 值溢出问题，迟早会出现，只不过`SnowflakeId`出现得更快而已）。 
+很显然溢出是不能被接受的，一般可以使用以下处理方案：
+
+- 直接将 `long` 转换成 `String` (`@AsString(AsString.Type.TO_STRING)`)
+- 使用 `SnowflakeFriendlyId` 将 `SnowflakeId` 转换成比较友好的字符串表示：`{timestamp}-{machineId}-{sequence} -> 20210623131730192-1-0` (`@AsString(AsString.Type.FRIENDLY_ID)`)
+- 自定义 `SnowflakeId` 位分配来缩短 `SnowflakeId` 的位数（**53-bit**）使 **ID** 提供给前端时不溢出(`SafeJavaScriptSnowflakeId`)
+- 使用 `Radix62IdConverter` 转换 `long` 类型的 **ID**，并且压缩字符串。(`@AsString(AsString.Type.RADIX)`)
+
+[cosid-jackson](https://github.com/Ahoo-Wang/CosId/tree/main/cosid-jackson) 模块为提供上述方案提供了最小的侵入性。
+:::
+
+## 安装
+
+> Kotlin DSL
+
+``` kotlin
+    implementation("me.ahoo.cosid:cosid-jackson:${cosidVersion}")
+```
+
+```java
+public class AsStringDto {
+
+    @AsString
+    private Long id;
+
+    @AsString(AsString.Type.RADIX)
+    private Long radixId;
+
+    @AsString(value = AsString.Type.RADIX, radixPadStart = true)
+    private Long radixPadStartId;
+
+    @AsString(value = AsString.Type.RADIX, radixPadStart = true, radixCharSize = 10)
+    private Long radixPadStartCharSize10Id;
+
+    @AsString(AsString.Type.FRIENDLY_ID)
+    private long friendlyId;
+
+   // getter / setter
+}
+```
+
+**序列化结果**
+
+```json
+{
+  "id": "266300479548424192",
+  "radixId": "JferHIEYZk",
+  "radixPadStartId": "0JferHIEYZk",
+  "radixPadStartCharSize10Id": "JferHIEYZk",
+  "friendlyId": "20211228202301948-0-0"
+}
+```
+