# 1 简介
分布式ID服务提供生成环境内全局唯一ID。通过分布式ID服务生成的ID具有如下特性：
**1. 全局唯一**
在一个cluster内产生的id是唯一的。
**2. 趋势有序**
不能确保在极短的时间(取决于微服务节点之间的时间差)内生成的多个id是严格有序的，因此不能作为数据行生成的排序依据。ID值含有当前服务节点的时间值，一个服务节点产生的id是严格有序，多个服务节点之间的时间可能存在误差，因此无法保证严格有序，但趋势有序。
**3. 高性能**
服务本节点内生成ID，仅在启动服务的时候，需要通过网络获取种子(workerId)。
**4. 高可靠**
1.避免单点故障：ID服务由多个group组成，group内含多个worker。
2.容错与复用：含时钟回拨容错机制，可复用异常宕机服务节点的workerId。
# 2 应用场景
在复杂的分布式系统中，往往需要对大量的数据和消息进行唯一标识。在如下场景中比较常用：
> **分布式环境数据库表主键生成。**
# 3 接口说明
分布式ID相关接口定义和实现存在于bos-id-1.0.jar中。对于使用者来说只需要调用kd.bos.id.ID接口中的方法即可。
## 3.1 接口列表
| 方法 | 说明 |
| - | - |
| genLongId | 生成一个long类型的ID |
| genLongIds | 生成指定数量的long类型ID |
| genStringId | 生成一个String类型的ID |
| genStringIds | 生成指定数量的String类型ID |
| toStringId | 将long类型ID转成String类型ID |
| toLongId | 将String类型ID转成long类型ID |
| getCreateTime | 获取ID的创建时间 |
## 3.2 接口详情
### genLongId
+ **功能描述**
生成一个long类型的ID。
+ **方法**
```java
static long genLongId()
```
+ **参数说明**
无
+ **返回值**
返回一个long类型的ID
+ **示例代码**
```java
long id = ID.genLongId();
```
### genLongIds
+ **功能描述**
生成指定数量的long类型ID。
+ **方法**
```java
static long[] genLongIds(int count)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| count | int | 生成ID的数量 |
+ **返回值**
返回一个long类型的ID数组。
+ **示例代码**
```java
long[] ids = ID.genLongIds(10);
```
### genStringId
+ **功能描述**
生成一个String类型的ID。
+ **方法**
```java
static String genStringId()
```
+ **参数说明**
无
+ **返回值**
返回一个String类型的ID。
+ **示例代码**
```java
String id = ID.genStringId();
```
### genStringIds
+ **功能描述**
生成指定数量的String类型ID。
+ **方法**
```java
static String[] genStringIds(int count)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| count | int | 生成ID的数量 |
+ **返回值**
返回一个String类型的ID数组。
+ **示例代码**
```java
String[] ids = ID.genStringIds(10);
```
### toStringId
+ **功能描述**
将long类型ID转成String类型ID。
+ **方法**
```java
static String toStringId(long id)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| count | long | id |
+ **返回值**
返回long类型ID转换后的String类型ID。
+ **示例代码**
```java
String stringId = ID.toStringId(698290515157716992L);
```
### toLongId
+ **功能描述**
将Sting类型ID转成long类型ID。
+ **方法**
```java
static long toLongId(String id)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| count | String | id |
+ **返回值**
返回String类型ID转换后的long类型ID。
+ **示例代码**
```java
long longId = ID.toLongId("05REK/V8NPAE");
```
### getCreateTime
+ **功能描述**
获取创建ID的时间，可用于判断数据生成的大致时间。
+ **方法**
```java
static Date getCreateTime(long id)
static Date getCreateTime(String id)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| count | String或long | id |
+ **返回值**
返回ID创建时间，类型为Date。
+ **示例代码**
```java
Date longIdCreateTime = ID.getCreateTime(698290515157716992L); //返回 2019-08-22 10:58:36.212
Date stringIdcreateTime = ID.getCreateTime("05REK/V8NPAE");
```
# 4 注意事项
## 4.1 ID值说明
1. 产生的id值有long和string两种，一般情况下它们之间是可以相互转换。但是下面情况是不能互相转化的。
**系统的初始化数据，其id值可能不是通过id服务生成的，第三方系统的数据也不是，不能相互转换。**
2. String类型的id是对long进行了Base39编码，转换后保持有序。
如long v1 < v2，转换成string后，v1转换的string id < v2转换的string id。
Base39编码字符集：+/0123456789=ABCDEFGHIJKLMNOPQRSTUVWXYZ
3. 数据库ID字段设计
long类型：bigint(19)
String类型：varchar(12)
String类型最长为12个Base39编码字符集中的字符。
## 4.2 ID服务配置
**1.配置**
默认情况下不需要做任何配置。如需配置请参考下面配置。
```properties
IDService.store.zookeeper=指定使用的zk服务器地址，默认为集群使用的zk服务器
IDService.worker=一个节点启动的id生成器(worker)个数，默认为1
```
在zookeeper下的保存路径：集群名称/runtime/ids。
**2.启动**
ID服务是懒启动的，有调用到获取id值时ID服务才会启动。ID服务启动是需要获取workerId种子，会用到分布式锁(DLock)，分布式锁不能用会导致ID服务启动不起来。
**3.异常**
服务长期运行后，若抛WorkerId已用完的异常，则是因为微服务节点频繁重启，且运行期间时间有跳动(差额>10秒)导致，种子被用完。(种子最大可用数为1024个)。需要关闭所有服务节点，然后清除种子：种子节点保存在/ids/w下，节点名称为数值(0-1023)，可删除整个w目录。
# 5 公众号文章
[苍穹分布式ID，你知多少？](https://mp.weixin.qq.com/s/NLoyZAoOwBUr_gfpnXE5Jg)
