Snowflake 组件
基于雪花算法(Snowflake)的分布式唯一 ID 生成组件,纯算法封装,不依赖任何业务类型或全局变量,可直接用于任意项目。
概述
Snowflake 组件提供线程安全的分布式 ID 生成能力,ID 由「时间戳 + 节点 ID + 序列号」三段构成,具有以下特点:
- 趋势递增:ID 整体随时间递增,对数据库索引友好
- 纯算法封装:不依赖 Redis、数据库等外部服务,无全局变量
- 并发安全:内部互斥锁保护,可多 goroutine 并发调用
- 时钟回拨处理:小回拨自动等待恢复,大回拨直接返回错误,绝不产出重复 ID
- 可自定义起始时间戳:默认以 2024-01-01 00:00:00 UTC 为起点
功能特性
ID 结构
生成的 64 位无符号整数 ID 按以下方式拼接:
| 段 |
位数 |
说明 |
| 时间戳 |
41 位 |
当前毫秒时间戳减去起始时间戳,可用约 69 年 |
| 节点 ID |
10 位 |
取值范围 0~1023,用于区分不同机器/进程 |
| 序列号 |
12 位 |
同一毫秒内的自增序号,单节点每毫秒最多 4096 个 |
时钟回拨处理
- 小回拨(≤ 5 秒):释放锁后短等 1 毫秒重试,避免阻塞其他 ID 生成请求
- 大回拨(> 5 秒):直接返回错误,由调用方决定告警或终止,绝不冒着产出重复 ID 的风险继续发号
并发安全
NextID 全程持锁生成,多 goroutine 并发调用不会产出重复 ID
- 同一毫秒内序列号耗尽时,释放锁等待下一毫秒,不在持锁状态下空转
安装指南
依赖要求
安装依赖
组件已包含在 jcbaseGo 模块中,无需额外安装:
go get github.com/jcbowen/jcbaseGo
使用示例
基本使用
package main
import (
"fmt"
"log"
"github.com/jcbowen/jcbaseGo/component/snowflake"
)
func main() {
// 创建生成器,节点 ID 范围 [0, 1023]
sf, err := snowflake.NewSnowflake(1)
if err != nil {
log.Fatal(err)
}
id, err := sf.NextID()
if err != nil {
log.Fatal(err)
}
fmt.Println(id) // 例如: 7308842699542978561
}
自定义起始时间戳
需要与历史系统保持 ID 区间一致时,可自定义起始时间戳(毫秒):
// 以 2020-01-01 00:00:00 UTC 为起点
epochMillis := int64(1577836800000)
sf, err := snowflake.NewSnowflakeWithEpoch(1, epochMillis)
if err != nil {
log.Fatal(err)
}
错误处理
id, err := sf.NextID()
if err != nil {
// 时钟回拨超过阈值(5 秒)时返回错误
// 生产环境建议告警并等待人工介入,不要简单重试
log.Printf("ID 生成失败: %v", err)
return
}
多节点部署
每个节点使用不同的节点 ID(如按机器编号、Kubernetes Pod 序号分配),确保多实例并发发号不重复:
// 节点 ID 建议从配置中心或环境变量注入,范围 0~1023
nodeID := uint16(envNodeID)
sf, err := snowflake.NewSnowflake(nodeID)
详细功能说明
节点 ID 分配建议
- 单机房/单集群部署:按机器序号 0、1、2…… 分配
- 多集群部署:为每个集群划分独立区段(如集群 A 用 0
99,集群 B 用 100199),避免扩容时冲突
- 节点 ID 超过 1023 时
NewSnowflake 直接返回错误
容量估算
- 单节点每毫秒可生成 4096 个 ID,即单节点理论峰值约 409 万/秒
- 默认起始时间戳下,41 位时间戳约可用 69 年(至 2093 年左右)
- 需要更长有效期时,通过
NewSnowflakeWithEpoch 使用更早的起始时间戳
与数据库的配合
- ID 推荐使用
bigint unsigned(MySQL)/ INTEGER(SQLite)存储
- 不要依赖 ID 做业务排序以外的强语义(如解析出时间),时间戳段仅供趋势递增
API 参考
构造函数
NewSnowflake(node uint16) (*Snowflake, error) - 创建生成器(默认起始时间戳 2024-01-01 UTC)
NewSnowflakeWithEpoch(node uint16, epochMillis int64) (*Snowflake, error) - 创建生成器并自定义起始时间戳(毫秒)
实例方法
NextID() (uint64, error) - 生成下一个唯一 ID;时钟回拨超过 5 秒返回错误
常量
| 名称 |
值 |
说明 |
| 节点位宽 |
10 |
节点 ID 取值范围 0~1023 |
| 序列位宽 |
12 |
单节点每毫秒最多 4096 个 ID |
| 最大回拨阈值 |
5000 ms |
超过则拒绝生成 ID |
常见问题
时钟回拨错误如何处理?
服务器 NTP 同步、虚拟化迁移都可能引起时钟回拨。小回拨组件会自动等待恢复;超过 5 秒的大回拨说明环境异常,应告警并人工介入(修正系统时钟),不要在应用层无限重试。
节点 ID 用完了怎么办?
单区段 1024 个节点已覆盖绝大多数部署规模。确需更多节点时,按集群划分多个区段,或调整序列位宽重新编译(修改 nodeBits 常量)。
为什么生成的 ID 不是严格连续的?
同一毫秒内序列号连续,跨毫秒会有跳号(差值即毫秒偏移量),这是正常现象;多节点部署下各节点 ID 交错也是正常的。
贡献指南
欢迎提交 Issue 和 Pull Request 来改进这个组件。
许可证
MIT License