idgen

Overview ¶

Package idgen 提供分布式唯一 ID 生成器(Snowflake 算法),纯标准库实现。

与 pkg/utils/uuid 的区别:uuid 生成 128 位字符串(UUIDv7),适合做外部可见的 资源标识;本包生成 64 位整数 ID,趋势递增、可排序、占用小,适合做数据库主键 / 对局 ID / 订单号 / 消息序号——凡是"要全局唯一 + 趋势递增 + 存储紧凑"的场景。

64 位布局(经典 Snowflake):

 1 bit  符号位,恒为 0(保证生成的 int64 为正)
41 bit  毫秒时间戳(相对 epoch,约可用 69 年)
10 bit  节点 ID(0..1023,同一部署内每个实例分配唯一值,避免跨节点冲突)
12 bit  同一毫秒内的序列号(0..4095,单节点单毫秒最多 4096 个 ID)

即单节点理论峰值 409.6 万 ID/秒。跨节点靠不同 node ID 保证不冲突, 同节点靠序列号 + 毫秒时间戳保证不冲突。

时钟回拨:NTP 校时或手动改时间可能让时钟倒退,导致重复 ID。本包检测到回拨时:

• 回拨在 maxBackwardWait(默认 5ms)内:自旋等待时钟追上,再生成;
• 回拨超过该阈值:返回错误(Next),或 panic(MustNext)——由调用方决策, 不静默生成可能重复的 ID。

并发安全(单锁保护序列号推进)。零值不可用,用 New 构造。