easy-idgen ID 生成器组件设计

本文档描述 easy-idgen 组件的设计与实现。该组件提供三种 ID 生成策略：Leaf 号段（leaf-core 外部库）、Snowflake 雪花算法（本地实现）、Simple 简单计数器（本地实现）。三种策略统一到 IdGenerator 接口，由 IdGeneratorProperties 配置驱动 Spring Boot 自动装配，生产代码零外部 MQ/Redis 依赖（Leaf 模式需可选 JDBC 依赖）。

• 一、背景与问题
• 二、组件定位与边界
• 三、总体架构
• 四、三种策略实现对比
• 五、包结构与核心类
• 六、雪花算法位分配
• 七、Spring Boot 自动装配
• 八、使用示例
• 九、关键设计决策
• 十、测试覆盖

一、背景与问题

1.1 分布式 ID 生成的常见方案对比

Matrix Framework 选择三种并存：本地单机场景用 Simple，分布式无 DB 场景用 Snowflake，有 DB 场景用 Leaf 号段（依赖 leaf-core 外部库）。

二、组件定位与边界

定位：策略可切换的分布式 ID 门面。业务方注入 IdGenerator，nextId() / nextId(batchSize) 取 ID；底层用配置驱动三种实现之一。

边界：

约束：

• 雪花算法的 allowClockBackward / maxClockBackwardMs 配置字段未生效——时钟回拨阈值硬编码为 5ms（见 关键设计决策）
• Leaf 模式运行时强依赖数据库（leaf-core SegmentService），jdbc 依赖为 compile scope
• Snowflake / Simple 模式无外部依赖，本地即可运行

三、总体架构

flowchart TD
    subgraph "业务层"
        A1["注入 IdGenerator<br/>(接口)"]
    end

    subgraph "统一接口"
        B1["IdGenerator 接口<br/>nextId() / nextId(batchSize)"]
    end

    subgraph "Spring Boot 自动装配"
        C1["EasyIdGenAutoConfiguration<br/>@ConfigurationProperties(IdGeneratorProperties)<br/>@ConditionalOnProperty"]
    end

    subgraph "三种策略实现"
        D1["SnowflakeIdGenerator<br/>雪花算法，本地实现"]
        D2["SimpleIdGenerator<br/>AtomicLong + setStartValue + 可选持久化"]
        D3["LeafIdGenerator<br/>委托 leaf-core IDGen (外部库)"]
    end

    subgraph "外部依赖"
        E1["leaf-core:1.0.2 (optional)"]
        E2["NetworkInterface.getNetworkInterfaces()"]
        E3["jdbc:runtime (Leaf 模式)"]
    end

    A1 --> B1
    C1 -- "enabled + type=snowflake" --> D1
    C1 -- "enabled + type=simple" --> D2
    C1 -- "enabled + type=leaf" --> D3
    D3 --> E1
    D1 --> E2
    D3 --> E3

策略选择流程：

flowchart TD
    A["matrix.id-generator.enabled=true"]
    B{"type=?"}
    C["simple → SimpleIdGenerator<br/>setStartValue(IdGeneratorProperties.simple.startValue)<br/>init()"]
    D["snowflake → SnowflakeIdGenerator<br/>注入 SnowflakeProperties<br/>init() 位数校验<br/>generateWorkerId()"]
    E["leaf → LeafIdGenerator<br/>segmentService.get(bizTag)<br/>Status.SUCCESS ? getId : throw"]
    A --> B
    B -- "simple" --> C
    B -- "snowflake" --> D
    B -- "leaf" --> E

四、三种策略实现对比

五、包结构与核心类

easy-idgen/
└── io/matrix/genid/
    ├── IdGenerator.java                    # 统一接口
    ├── autoconfig/EasyIdGenAutoConfiguration.java
    ├── config/
    │   ├── IdGeneratorProperties.java       # prefix=id-generator
    │   ├── SnowflakeProperties.java         # workerIdBits=10 / sequenceBits=12
    │   └── SimpleGenProperties.java         # startValue=1
    ├── local/
    │   ├── SimpleIdGenerator.java           # AtomicLong + @PostConstruct init() + reset() + getCurrentValue()
    │   └── SnowflakeIdGenerator.java         # 雪花算法 + parseId 还原 + 时钟回拨硬编码 5ms
    └── leaf/
        └── LeafIdGenerator.java              # 委托 leaf-core IDGen，@Autowired 注入 segmentService

六、雪花算法位分配

默认位分配（可配）：

0 ┄ 1 ┄ 41 ┄ 51 ┄ 63
  ├ timestamp (41 bits)     ← 毫秒级时间戳（相对 EPOCH=2023-01-01）
  ├ workerId (10 bits)      ← NetworkInterface MAC 低 bits 取模
  └ sequence (12 bits)      ← 同毫秒内自增

参数校验（SnowflakeIdGenerator.init()）：

Compact 模式（compactMode=true）：强制 workerIdBits=6 / sequenceBits=10，把更多位留给 timestamp。

parseId 还原：

public IdInfo parseId(long id) {
    // timestamp = id >> (workerIdBits + sequenceBits) + EPOCH
    // workerId = (id >> sequenceBits) & workerIdMask
    // sequence = id & sequenceMask
}

七、Spring Boot 自动装配

flowchart TD
    A["application.yml"] --> B["matrix.id-generator.enabled=true<br/>matrix.id-generator.snowflake.enabled=true"]
    B --> C["EasyIdGenAutoConfiguration<br/>@ConfigurationProperties(prefix='matrix.id-generator')"]
    C -- "snowflake.enabled=true" --> D["@Bean SnowflakeIdGenerator<br/>@ConditionalOnProperty(snowflake.enabled=true)"]
    C -- "simple.enabled=true" --> E["@Bean SimpleIdGenerator<br/>@ConditionalOnProperty(simple.enabled=true)"]
    C -- "segment.enabled=true" --> F["@Bean LeafIdGenerator<br/>@Autowired IDGen segmentService"]

三个 @ConditionalOnProperty：

八、使用示例

// application.yml
easy:
  id-generator:
    snowflake:
      enabled: true
      worker-id-bits: 10
      sequence-bits: 12
      epoch: 1672531200000  # 2023-01-01

// 注入
@Service
public class OrderService {
    @Autowired
    private IdGenerator idGenerator;

    public Order createOrder(...) {
        Long id = idGenerator.nextId();
        // 批量生成
        List<Long> batch = idGenerator.nextId(10);
        return new Order(id, ...);
    }
}

// 解析雪花 ID
SnowflakeIdGenerator sf = (SnowflakeIdGenerator) idGenerator;
SnowflakeIdGenerator.IdInfo info = sf.parseId(123456789L);
// info.getTimestamp() → 毫秒时间戳（相对 EPOCH）
// info.getWorkerId() → 节点 ID
// info.getSequence() → 同毫秒内序号

九、关键设计决策

十、测试覆盖

当前共 33 例（全绿）：

可测程度 4/5：SimpleIdGenerator / SnowflakeIdGenerator 纯 JVM；LeafIdGenerator 依赖 leaf-core Mock 但易 mock（Result/Status 都是 POJO）。Snowflake 时钟回拨阈值硬编码 5ms——不测试 maxClockBackwardMs 字段（已知 bug）。

踩坑：

1. StateMachineException — COLA StateMachineFactory 不允许重复 id
2. Result 构造器参数顺序 — leaf-core Result(long id, Status status) 而非 (Status, long)
3. Mock withContext(Runnable) — mock default 方法不会自动调用 Runnable，需 doAnswer(inv -> inv.getArgument(0, Runnable.class).run())
4. 雪花 clock backward 硬编码 5ms — maxClockBackwardMs 字段不生效，测试不覆盖