# spring-boot-starter-distributed-randomId

**Repository Path**: castdlg/spring-boot-starter-distributed-random-id

## Basic Information

- **Project Name**: spring-boot-starter-distributed-randomId
- **Description**: 分布式ID发号器，支持多种生成方式，无缝集成SpringBoot
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-03-01
- **Last Updated**: 2025-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Boot Starter Distributed RandomId

## 简介
分布式ID生成器Spring Boot Starter，支持多种ID生成策略，包括Snowflake、Leaf、TinyID、UID和GUID等。本项目旨在为Spring Boot应用提供简单易用、高性能且可靠的分布式ID生成解决方案。

## 特性
- 支持多种ID生成策略
- 配置简单，易于集成
- 支持异步加载和双buffer优化
- 高性能，低延迟
- 可扩展性强

## 快速开始

### Maven依赖
```xml
<dependency>
    <groupId>com.example</groupId>
    <artifactId>spring-boot-starter-distributed-randomId</artifactId>
    <version>1.0.2-SNAPSHOT</version>
</dependency>
```

### 基础配置
在application.yml中添加配置：
```yaml
random-id:
  type: snowflake  # 可选值：snowflake、leaf、tiny、uid、guid
  worker-id: 1     # Snowflake模式的机器ID
  datacenter-id: 1 # Snowflake模式的数据中心ID
```

### 包扫描配置
在Spring Boot主应用类上添加包扫描注解：
```java
@SpringBootApplication(scanBasePackages = {"com.example.randomid"})
public class YourApplication {
    public static void main(String[] args) {
        SpringApplication.run(YourApplication.class, args);
    }
}
```

## ID生成策略详解

### 1. Snowflake算法
基于Twitter的Snowflake算法实现，生成64位的长整型ID。

#### 适用场景
- 单机部署环境
- 需要按时间顺序生成ID
- 对ID长度敏感的场景

#### 配置参数
```yaml
random-id:
  type: snowflake
  worker-id: 1       # 机器ID（0-31）
  datacenter-id: 1   # 数据中心ID（0-31）
  twepoch: 1577808000000  # 可选，自定义起始时间戳
```

#### 使用示例
```java
@Autowired
private IdGenerator idGenerator;

public void example() {
    long id = idGenerator.nextId();
    System.out.println("Generated ID: " + id);
}
```

### 2. Leaf分段模式
基于美团Leaf算法实现的分布式ID生成器，支持号段模式。

#### 适用场景
- 分布式环境
- 需要高性能且可靠的ID生成
- 可接受号段预分配机制

#### 配置参数
```yaml
random-id:
  type: leaf
  biz-tag: order      # 业务标签
  step: 1000          # 号段步长
  key-prefix: "leaf:segment:"  # Redis key前缀
  async-loading-segment: true  # 是否异步加载号段
  update-interval: 1000        # 更新间隔（毫秒）

spring:
  redis:
    host: localhost
    port: 6379
    database: 0
    password: # 如果有密码，请在此配置
    timeout: 3000
    lettuce:
      pool:
        max-active: 8
        max-idle: 8
        min-idle: 0
        max-wait: -1ms

  # ZooKeeper配置（Leaf号段模式时需要）
  zookeeper:
    connect-string: localhost:2181
    session-timeout: 30000
    connection-timeout: 10000
    base-sleep-time: 1000
    max-retries: 3
    namespace: leaf-segment
```

### 3. TinyID模式
轻量级分布式ID生成器，基于号段模式设计。

#### 适用场景
- 小规模分布式系统
- 需要简单可靠的ID生成方案

#### 配置参数
```yaml
random-id:
  type: tiny
  biz-type: order    # 业务类型
  step: 1000         # 步长
  retry-times: 3     # 重试次数
  segment-duration: 600000  # 号段有效期（毫秒）
```

### 4. UID模式
基于百度UidGenerator的简化实现。

#### 适用场景
- 大规模分布式系统
- 需要极高性能的场景

#### 配置参数
```yaml
random-id:
  type: uid
  worker-id: 1       # 机器ID
  seq-bits: 12       # 序列号位数
  time-bits: 28      # 时间位数
  worker-bits: 22    # 机器ID位数
```

### 5. GUID模式
基于UUID的改进实现，生成全局唯一的字符串ID。

#### 适用场景
- 对ID长度不敏感的场景
- 需要全局唯一性保证

#### 配置参数
```yaml
random-id:
  type: guid
  prefix: ""        # ID前缀
  suffix: ""        # ID后缀
  separator: "-"    # 分隔符
```

## 性能优化

### 各策略性能对比

| 策略类型 | QPS | 延迟(P99) | 内存占用 | CPU使用率 | 优点 | 缺点 |
|---------|-----|-----------|---------|-----------|------|------|
| Snowflake | 50万+ | <1ms | 低 | 低 | 性能高，趋势递增 | 依赖时钟，可能时钟回拨 |
| Leaf | 2万+ | <10ms | 中 | 中 | 可靠性高，号段连续 | 依赖存储，QPS较低 |
| TinyID | 5万+ | <5ms | 低 | 低 | 轻量，易部署 | 可靠性相对较低 |
| UID | 100万+ | <0.5ms | 中 | 中高 | 超高性能 | 配置复杂，ID较长 |
| GUID | 10万+ | <1ms | 低 | 低 | 全局唯一，无状态 | ID长度固定，无序 |

### 异步加载优化
对于Leaf和TinyID模式，支持异步加载下一个号段，提高性能：
```yaml
random-id:
  async-loading-segment: true
  loading-percent: 70  # 触发异步加载的使用量百分比
```

### 双Buffer机制
通过维护两个号段Buffer，实现无锁切换，提升并发性能。

### 号段预加载
系统启动时预加载号段，避免冷启动延迟。

## 常见问题

### 1. ID重复问题
- 确保Snowflake模式下workerId和datacenterId全局唯一
- Leaf模式下注意号段步长和业务标签的配置
- 定期检查系统时钟，避免时钟回拨

### 2. 性能问题
- 开启异步加载机制
- 适当增加号段步长
- 使用性能更优的存储介质

### 3. 可用性问题
- 配置合适的重试策略
- 实现存储层的高可用
- 做好监控和告警

## 监控指标
- ID生成QPS
- 号段使用情况
- 异步加载成功率
- 响应时间分布

## 最佳实践
1. 根据业务场景选择合适的ID生成策略
2. 合理配置号段步长，平衡性能和资源占用
3. 实现存储层高可用，避免单点故障
4. 做好监控和预警，及时发现问题
5. 定期备份和清理历史数据

## 版本历史
- 1.0.2-SNAPSHOT: 当前版本
  - 支持多种ID生成策略
  - 优化性能和可靠性
  - 完善文档和示例