# uid-generator-spring-boot-starter-master

**Repository Path**: aper/uid-generator-spring-boot-starter-master

## Basic Information

- **Project Name**: uid-generator-spring-boot-starter-master
- **Description**: 雪花ID算法
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-04
- **Last Updated**: 2026-03-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# uid-generator-spring-boot-starter

基于 [百度UidGenerator](https://github.com/baidu/uid-generator) 改造的分布式唯一ID生成器 Spring Boot Starter，无需独立部署，建表引入即可使用。

## 与原版的主要改动

- 改造为 Spring Boot Starter，直接引入依赖即可使用
- **数据源必须由外部项目提供**，Starter 不会自动创建数据源，使用项目已有的 `DataSource` Bean
- **默认时间基点改为 `2025-01-01`**（原版为 2019-02-20），生成的 ID 更短
- 针对时钟回拨提供了修正选项（默认启用），小于阈值直接自旋等待，大于阈值则更换机器号
- 对机器 ID 用尽提供了取余复用策略
- 解除 ID 位数限制，由"必须64位"改为"不大于64位"，可获取更短的 ID
- **新增 `UidUtil` 静态工具类**，无需注入 Bean，直接调用静态方法获取 ID

## 默认 ID 位结构

```
+------+--------------------+----------------+-----------+
| sign |   delta seconds    |   worker id    | sequence  |
+------+--------------------+----------------+-----------+
 1bit        30bits              16bits          7bits
```

| 字段 | 位数 | 说明 |
|------|------|------|
| sign | 1 | 固定为0，保证正数 |
| delta seconds | 30 | 相对于 `2025-01-01` 的秒数，可支持约34年 |
| worker id | 16 | 机器ID，最多支持约6.5万次机器启动 |
| sequence | 7 | 每秒最多128个并发序列 |

默认配置下，初始 ID 长度约为 **12位**，随时间增长最终到 **16位**。

---

## Quick Start

### 步骤1：创建表 WORKER_NODE

在项目数据库中执行以下 SQL：

```sql
DROP TABLE IF EXISTS WORKER_NODE;
CREATE TABLE WORKER_NODE
(
  ID          BIGINT       NOT NULL AUTO_INCREMENT COMMENT 'auto increment id',
  HOST_NAME   VARCHAR(64)  NOT NULL COMMENT 'host name',
  PORT        VARCHAR(64)  NOT NULL COMMENT 'port',
  TYPE        INT          NOT NULL COMMENT 'node type: CONTAINER(1), ACTUAL(2), FAKE(3)',
  LAUNCH_DATE DATE         NOT NULL COMMENT 'launch date',
  MODIFIED    TIMESTAMP    NOT NULL COMMENT 'modified time',
  CREATED     TIMESTAMP    NOT NULL COMMENT 'created time',
  PRIMARY KEY(ID)
) COMMENT='DB WorkerID Assigner for UID Generator', ENGINE = INNODB;
```

### 步骤2：Maven 引入

将本项目打包为 jar 后安装到本地或私服，然后在业务项目中引入：

```xml
<dependency>
    <groupId>com.github.wujun234</groupId>
    <artifactId>uid-generator-spring-boot-starter</artifactId>
    <version>1.1.0.RELEASE</version>
</dependency>
```

> **注意**：业务项目需已配置好数据库连接（如 `spring.datasource.*`），Starter 会自动使用项目中已有的 `DataSource`。

### 步骤3：使用

#### 方式一：静态工具类（推荐）

无需注入 Bean，直接调用：

```java
// 获取 long 类型 ID
long id = UidUtil.nextId();

// 获取 String 类型 ID
String idStr = UidUtil.nextIdStr();
```

#### 方式二：注入 Bean

```java
@Resource
private UidGenerator cachedUidGenerator;

public void example() {
    long id = cachedUidGenerator.getUID();

    // 解析 ID，返回 JSON 字符串，包含时间戳、机器ID、序列号
    // {"UID":"450795408770","timestamp":"2025-01-01 14:55:39","workerId":"1","sequence":"2"}
    String parsed = cachedUidGenerator.parseUID(id);
}
```

两种实现可选：
- `cachedUidGenerator`（推荐）：基于 RingBuffer 预生成并缓存，高吞吐
- `defaultUidGenerator`：实时生成，每次请求时同步计算

---

## 可选配置

以下均为可选配置，未指定时使用默认值：

```yaml
uid:
  timeBits: 30               # 时间位，默认: 30
  workerBits: 16             # 机器位，默认: 16
  seqBits: 7                 # 序列号位，默认: 7
  epochStr: "2025-01-01"     # 时间基点，默认: "2025-01-01"
  enableBackward: true       # 是否容忍时钟回拨，默认: true
  maxBackwardSeconds: 1      # 时钟回拨最大容忍秒数，默认: 1
  cached-uid-generator:
    boostPower: 3            # RingBuffer 扩容倍数(2的幂)，默认: 3
    paddingFactor: 50        # RingBuffer 剩余百分比低于此值时触发填充，默认: 50
    #scheduleInterval: 60   # 定时填充间隔(秒)，默认不启用定时线程
```

## 拒绝策略扩展（可选）

使用 `CachedUidGenerator` 时，可实现自定义拒绝策略并注入到 Spring 容器：

```java
// 环满时的拒绝策略（默认：丢弃并打印日志）
@Bean
public RejectedPutBufferHandler rejectedPutBufferHandler() {
    return (ringBuffer, uid) -> log.warn("RingBuffer is full, discard uid: {}", uid);
}

// 环空时的拒绝策略（默认：抛出 UidGenerateException）
@Bean
public RejectedTakeBufferHandler rejectedTakeBufferHandler() {
    return (ringBuffer) -> { throw new UidGenerateException("RingBuffer is empty"); };
}
```