Documentation
¶
Overview ¶
Package uidgen 提供分布式唯一 ID 生成器.
推荐使用 Snowflake（全局单例 + 极简 API）：
uidgen.InitSnowflake(7) // 一次性初始化, machineID ∈ [0, 1023] id := uidgen.SnowflakeID() // int64, 不返错, auto-init 兜底 uidgen.ExtractSnowflakeTime(id) // epoch = 2026-01-01 uidgen.ExtractSnowflakeMachineID(id) uidgen.ExtractSnowflakeSequence(id)
Extract 函数（epoch = 2024-01-01）用于从旧式 ID 中提取元数据：
uidgen.ExtractTime(id) uidgen.ExtractWorkerID(id) uidgen.ExtractSequence(id)
UUID 系列（与 Snowflake 无关）见 uuid.go.
crypto/rand 随机串生成（标识符/密钥面）：与 Snowflake（可预测、仅作 ID）分居—— 密钥、一次性凭据、高熵标识符必须走本文件。
Index ¶
- func ExtractSequence(id int64) int64
- func ExtractSnowflakeMachineID(id int64) int64
- func ExtractSnowflakeSequence(id int64) int64
- func ExtractSnowflakeTime(id int64) time.Time
- func ExtractTime(id int64) time.Time
- func ExtractWorkerID(id int64) int64
- func InitSnowflake(machineID int64) error
- func InitSnowflakeFromEnv() error
- func RandomHex(nBytes int) string
- func RandomString(alphabet string, n int) string
- func ShortUUID() string
- func ShortUUIDToUpper() string
- func SnowflakeID() int64
- func SnowflakeMachineID() int64
- func UUID() string
- func UUIDToUpper() string
- func UUIDWithHyphen() string
- type Snowflake
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractSnowflakeMachineID ¶
ExtractSnowflakeMachineID 从 Snowflake ID 中提取 machineID.
func ExtractSnowflakeSequence ¶
ExtractSnowflakeSequence 从 Snowflake ID 中提取 sequence.
func ExtractSnowflakeTime ¶
ExtractSnowflakeTime 从 Snowflake ID 中提取生成时间. 注意：与 ExtractTime 不可混用——epoch 不同（2026 vs 2024）.
func InitSnowflake ¶
InitSnowflake 初始化全局 Snowflake singleton. machineID 必须在 [0, 1023] 范围. 多次调用：第一次生效，后续返错（防止误用）.
并发安全：CAS(nil -> s) 失败表示已初始化，Load() 拿到的是上次成功的实例.
func InitSnowflakeFromEnv ¶
func InitSnowflakeFromEnv() error
InitSnowflakeFromEnv 从 MACHINE_ID env 读 machineID，解析失败兜底 0. 单进程 dev / 测试默认 0 够用；生产必须显式注入（e.g. docker-compose 配 0/1/2）.
func RandomHex ¶
RandomHex n 字节 crypto/rand 随机数的十六进制串（2n 字符）。n<=0 返回空串。 适用：对象 ID、webhook secret 等高熵标识符。
func RandomString ¶
RandomString 从 alphabet 均匀采样 n 个字符（拒绝采样消模偏差，无 mod 偏置）。 alphabet 为空时 panic。适用：带自定义字符集的短 ID/令牌。
func SnowflakeID ¶
func SnowflakeID() int64
SnowflakeID 拿下一个 int64 ID. 未 InitSnowflake 时自动以 machineID=0 初始化.
并发说明：auto-init 路径在多 goroutine 同时首次调用时，CAS 失败的 goroutine 会回退到 Load() 读已 init 的实例，保证不会 nil deref.
时钟回拨：阻塞等直到时间追平，不返错. 业务层应监控回拨时长，超过阈值告警.
func SnowflakeMachineID ¶
func SnowflakeMachineID() int64
SnowflakeMachineID 返当前 init 用的 machine ID，未初始化返 -1，测试用.
Types ¶
type Snowflake ¶
type Snowflake struct {
// contains filtered or unexported fields
}
Snowflake 是 singleton 模式的 Snowflake ID 生成器.
Bit 布局（bit 63 → 0）：
[1 sign | 41 ts | 10 machine | 12 sequence]
= ~69 years × 1024 machines × 4096 IDs/ms per machine.
区别于旧式 ID 生成：
- Singleton 模式，业务侧直接调 SnowflakeID() 拿下一个 int64 ID.
- 时钟回拨持锁忙等，不返错.
- API 极简：InitSnowflake + SnowflakeID，不暴露 mu / sequence / lastTS.
并发模型：
- InitSnowflake 用 atomic.Pointer CAS 保证 "只 init 一次" + "成功后立刻可见".
- SnowflakeID() auto-init 路径在 CAS 失败时回退到 Load()，避免 nil deref.
- next() 持单 mu 串行：临界区短（同 ms 仅几次算术，跨 ms 持锁等下 ms 最坏 1ms）.
Reference: https://github.com/twitter-archive/snowflake (Twitter, 2010)
Source Files