idgen

package
v0.19.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 1, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// ShortFlakeMaxNodeID 节点 ID 上限（含），6 位
	ShortFlakeMaxNodeID = 63
	// ShortFlakeSequencePerMilli 同一毫秒内可发的 ID 数，6 位
	// 超出后会等到下一毫秒，因此单实例吞吐上限约为 6.4 万每秒
	ShortFlakeSequencePerMilli = 64
)

ShortFlake 位布局

时间戳(41位) + 节点ID(6位) + 序列号(6位) = 53位，刚好落在 JavaScript 的 Number 安全整数范围内，前端不需要用字符串承载

序列号只有 6 位，单实例吞吐上限是 6.4 万每秒，远低于 Snowflake 的 409.6 万 这是为了压进 53 位换来的，取舍本身合理，但容量必须让调用方看得见： 把常量公开出来，免得压测时才发现卡在一个来路不明的数字上

View Source 
const (
	// SnowflakeMaxWorkerID 工作机器 ID 上限（含），5 位
	SnowflakeMaxWorkerID = 31
	// SnowflakeMaxDatacenterID 数据中心 ID 上限（含），5 位
	SnowflakeMaxDatacenterID = 31
	// SnowflakeSequencePerMilli 同一毫秒内可发的 ID 数，12 位
	// 超出后会等到下一毫秒，因此单实例吞吐上限约为 409.6 万每秒
	SnowflakeSequencePerMilli = 4096
)

Snowflake 位布局

时间戳(41位) + 数据中心(5位) + 工作机器(5位) + 序列号(12位) = 63位 这些值决定了容量上限，公开出来便于调用方在部署前核算，而不是读源码里的掩码

Variables

View Source 
var DefaultSpec = IDSpec{
	TraceLen:       32,
	SpanLen:        16,
	RequestCounter: true,
	CorrelationFmt: true,
}

DefaultSpec 默认规格

View Source 
var SpecForGenerator = map[GeneratorType]IDSpec{
	GeneratorTypeDefault:    {TraceLen: 32, SpanLen: 16, RequestCounter: true, CorrelationFmt: true},
	GeneratorTypeUUID:       {TraceLen: 36, SpanLen: 16, RequestCounter: true, CorrelationFmt: true},
	GeneratorTypeNanoID:     {TraceLen: 21, SpanLen: 16, RequestCounter: true, CorrelationFmt: false},
	GeneratorTypeSnowflake:  {TraceLen: 0, SpanLen: 0, RequestCounter: true, CorrelationFmt: true},
	GeneratorTypeShortFlake: {TraceLen: 0, SpanLen: 0, RequestCounter: true, CorrelationFmt: true},
	GeneratorTypeShortID:    {TraceLen: 10, SpanLen: 8, RequestCounter: true, CorrelationFmt: false},
	GeneratorTypeNumeric:    {TraceLen: 8, SpanLen: 8, RequestCounter: true, CorrelationFmt: false},
	GeneratorTypeULID:       {TraceLen: 26, SpanLen: 16, RequestCounter: true, CorrelationFmt: false},
}

SpecForGenerator 各生成器的规格映射

Functions

func FormatSpanID 

func FormatSpanID(uuid string) string

FormatSpanID 从 UUID 中提取 SpanID（16字符）

func FormatTraceID 

func FormatTraceID(uuid string) string

FormatTraceID 将标准 UUID 格式化为无连字符的 TraceID（32字符） 用于兼容 OpenTelemetry 的 TraceID 格式

Types

type CounterStore 

type CounterStore interface {
	// Increment 原子递增计数器，返回递增后的值
	// key: 存储 key（格式 "numeric:{workerID}:{day}"）
	// delta: 递增量（批量预取时为 BatchSize）
	// initValue: 如果 key 不存在，先初始化为 initValue 再递增 delta
	//   即: 不存在时 value = initValue + delta; 已存在时 value = value + delta
	// 返回: 递增后的值
	Increment(key string, delta uint64, initValue uint64) (uint64, error)
}

CounterStore 计数器持久化接口 分布式环境下必须保证 Increment 操作的原子性 Redis 实现: SETNX + INCRBY（或 Lua 脚本） MySQL 实现: INSERT ... ON DUPLICATE KEY UPDATE counter = counter + ? 建议对 key 设置 TTL（如 48 小时），自动清理过期日数据

type DefaultIDGenerator 

type DefaultIDGenerator struct {
	// contains filtered or unexported fields
}

DefaultIDGenerator 默认ID生成器（高性能 Hex 编码）

func NewDefaultIDGenerator 

func NewDefaultIDGenerator() *DefaultIDGenerator

NewDefaultIDGenerator 创建默认ID生成器

func (*DefaultIDGenerator) GenerateCorrelationID 

func (g *DefaultIDGenerator) GenerateCorrelationID() string

GenerateCorrelationID 生成关联ID（UUID v4 格式，跨服务传递） 格式: 8-4-4-4-12 hex（含版本位和变体位） 示例: "550e8400-e29b-41d4-a716-446655440000" 与 TraceID 的区别: 标准 UUID 格式，含连字符，适合跨系统关联

func (*DefaultIDGenerator) GenerateRequestID 

func (g *DefaultIDGenerator) GenerateRequestID() string

GenerateRequestID 生成请求ID（时间戳-计数器格式，可排序） 格式: unix时间戳-递增计数器 示例: "1732184000-1" 与 TraceID 的区别: 带计数器后缀，方便按请求顺序排序

func (*DefaultIDGenerator) GenerateSpanID 

func (g *DefaultIDGenerator) GenerateSpanID() string

GenerateSpanID 生成跨度ID（16字符 hex，纯随机，零分配优化） 格式: 16字符随机hex 示例: "0123456789abcdef" 与 TraceID 的区别: 无时间戳前缀，纯随机，更短

func (*DefaultIDGenerator) GenerateTraceID 

func (g *DefaultIDGenerator) GenerateTraceID() string

GenerateTraceID 生成跟踪ID（32字符 hex，时间戳+随机数，零分配优化） 格式: 16字符时间戳hex + 16字符随机hex = 32字符 示例: "000001234567abcd89ef0123456789ab"

type GeneratorType 

type GeneratorType string

GeneratorType 生成器类型 

const (
	GeneratorTypeDefault    GeneratorType = "default"    // 默认 Hex 生成器
	GeneratorTypeUUID       GeneratorType = "uuid"       // UUID v4
	GeneratorTypeNanoID     GeneratorType = "nanoid"     // NanoID
	GeneratorTypeSnowflake  GeneratorType = "snowflake"  // Snowflake
	GeneratorTypeShortFlake GeneratorType = "shortflake" // ShortFlake (短ID)
	GeneratorTypeShortID    GeneratorType = "shortid"    // ShortID (8~10位Base62)
	GeneratorTypeNumeric    GeneratorType = "numeric"    // Numeric (8位纯数字)
	GeneratorTypeULID       GeneratorType = "ulid"       // ULID
)

func (GeneratorType) Spec 

func (t GeneratorType) Spec() IDSpec

Spec 获取生成器对应的 ID 规格

func (GeneratorType) String 

func (t GeneratorType) String() string

String 转换为字符串

type IDGenerator 

type IDGenerator interface {
	GenerateTraceID() string
	GenerateSpanID() string
	GenerateRequestID() string
	GenerateCorrelationID() string
}

IDGenerator ID生成器接口

func NewIDGenerator 

func NewIDGenerator(generatorType interface{}) IDGenerator

NewIDGenerator 创建 ID 生成器

func NewIDGeneratorFromString 

func NewIDGeneratorFromString(generatorType string) IDGenerator

NewIDGeneratorFromString 从字符串创建 ID 生成器（已废弃，使用 NewIDGenerator 代替） Deprecated: 使用 NewIDGenerator 代替

type IDSpec 

type IDSpec struct {
	TraceLen       int  // TraceID 长度
	SpanLen        int  // SpanID 长度（截取自 TraceID 或独立生成）
	RequestCounter bool // RequestID 是否附加计数器后缀
	CorrelationFmt bool // CorrelationID 是否使用 UUID 格式（含连字符）
}

IDSpec ID 规格配置 每种 IDType 对应不同的格式规格，生成器根据规格产出不同格式的 ID

type IDType 

type IDType string

IDType ID 语义类型 不同语义的 ID 有不同的格式要求和长度约束 

const (
	IDTypeTraceID       IDType = "trace_id"       // 全链路追踪 ID，长格式、时间排序、全局唯一
	IDTypeSpanID        IDType = "span_id"        // 单次操作跨度 ID，短格式、同 Trace 内唯一
	IDTypeRequestID     IDType = "request_id"     // 请求唯一标识，带计数器、可排序
	IDTypeCorrelationID IDType = "correlation_id" // 跨系统关联 ID，UUID 格式、跨服务传递
)

type NanoIDGenerator 

type NanoIDGenerator struct {
	// contains filtered or unexported fields
}

NanoIDGenerator NanoID 生成器（高性能版本，预分配字母表）

func NewNanoIDGenerator 

func NewNanoIDGenerator() *NanoIDGenerator

NewNanoIDGenerator 创建 NanoID 生成器

func (*NanoIDGenerator) GenerateCorrelationID 

func (g *NanoIDGenerator) GenerateCorrelationID() string

GenerateCorrelationID 生成关联ID（完整 NanoID，21字符） 格式: 与 TraceID 相同长度的 NanoID 示例: "K9mPxR2vN4qL7wBjT5cYs" 与 TraceID 的区别: 独立生成，用于跨系统关联

func (*NanoIDGenerator) GenerateRequestID 

func (g *NanoIDGenerator) GenerateRequestID() string

GenerateRequestID 生成请求ID（NanoID前缀+计数器后缀） 格式: NanoID前10字符-递增计数器 示例: "V1StGXR8_Z-1" 与 TraceID 的区别: 带计数器后缀，可按请求顺序排序

func (*NanoIDGenerator) GenerateSpanID 

func (g *NanoIDGenerator) GenerateSpanID() string

GenerateSpanID 生成跨度ID（NanoID 前16字符） 格式: 截取 NanoID 前16字符 示例: "V1StGXR8_Z5jdHi6" 与 TraceID 的区别: 更短，同一 Trace 内唯一即可

func (*NanoIDGenerator) GenerateTraceID 

func (g *NanoIDGenerator) GenerateTraceID() string

GenerateTraceID 生成跟踪ID（完整 NanoID，21字符） 格式: URL 安全的 21 字符随机字符串 示例: "V1StGXR8_Z5jdHi6B-myT"

type NumericIDConfig 

type NumericIDConfig struct {
	Epoch        int64        // 纪元时间戳（秒），默认 2024-01-01 00:00:00
	Base         uint64       // 起始基数，默认 10000000（8位数字起点）
	WorkerSpace  uint64       // 每个Worker的日序列空间，默认 10000（每机每天10000个）
	MaxWorkers   uint64       // 最大Worker数，默认 10（支持10台机器）
	DaySpace     uint64       // 每天总空间 = WorkerSpace * MaxWorkers，默认 100000
	RandomDigits int          // 随机ID位数（SpanID/CorrelationID），默认 8
	Store        CounterStore // 可选持久化存储，nil 则纯本地模式
	BatchSize    uint64       // 批量预取大小，默认 100（仅 Store 模式生效）
}

NumericIDConfig 纯数字ID生成器配置 所有参数均可动态配置，无需修改底层代码

func DefaultNumericIDConfig 

func DefaultNumericIDConfig() NumericIDConfig

DefaultNumericIDConfig 返回默认配置（8位纯数字，10台机器，每机每天10000个） 注意：Epoch 决定 8 位容量的起算点，约 899 天（~2.46 年）后会溢出至 9 位

func (NumericIDConfig) Validate 

func (c NumericIDConfig) Validate() error

Validate 校验配置合法性 约束: DaySpace 必须等于 WorkerSpace * MaxWorkers，确保位分配一致性 约束: BatchSize 必须 > 0 且 <= WorkerSpace

type NumericIDGenerator 

type NumericIDGenerator struct {
	// contains filtered or unexported fields
}

NumericIDGenerator 纯数字ID生成器 无时间轮，纯原子计数器，支持分布式 Worker ID Store 模式: 批量预取 + 原子递增，分布式安全 本地模式: 纯原子递增，适用于 StatefulSet 单实例运行

func NewNumericIDGenerator 

func NewNumericIDGenerator() *NumericIDGenerator

NewNumericIDGenerator 创建纯数字ID生成器（使用默认配置，自动获取Worker ID）

func NewNumericIDGeneratorWithConfig 

func NewNumericIDGeneratorWithConfig(cfg NumericIDConfig) *NumericIDGenerator

NewNumericIDGeneratorWithConfig 使用自定义配置创建生成器（自动获取Worker ID） 如果配置了 Store，首次启动会通过 Increment 原子递增获取区间，保证分布式安全

func NewNumericIDGeneratorWithConfigAndWorker 

func NewNumericIDGeneratorWithConfigAndWorker(cfg NumericIDConfig, workerID uint64) *NumericIDGenerator

NewNumericIDGeneratorWithConfigAndWorker 使用自定义配置和Worker ID创建生成器

func NewNumericIDGeneratorWithWorker 

func NewNumericIDGeneratorWithWorker(workerID uint64) *NumericIDGenerator

NewNumericIDGeneratorWithWorker 创建纯数字ID生成器（手动指定Worker ID）

func (*NumericIDGenerator) Config 

func (g *NumericIDGenerator) Config() NumericIDConfig

Config 返回当前配置

func (*NumericIDGenerator) GenerateCorrelationID 

func (g *NumericIDGenerator) GenerateCorrelationID() string

GenerateCorrelationID 生成关联ID（纯随机） 与 SpanID 的区别: 独立随机源，跨系统关联使用

func (*NumericIDGenerator) GenerateRequestID 

func (g *NumericIDGenerator) GenerateRequestID() string

GenerateRequestID 生成请求ID（天+原子计数器，可排序） 与 UserID 的区别: 使用独立原子计数器，无锁更高频

func (*NumericIDGenerator) GenerateSpanID 

func (g *NumericIDGenerator) GenerateSpanID() string

GenerateSpanID 生成跨度ID（纯随机） 与 TraceID 的区别: 无时间特征，纯随机，不可排序

func (*NumericIDGenerator) GenerateTraceID 

func (g *NumericIDGenerator) GenerateTraceID() string

GenerateTraceID 生成跟踪ID（秒级时间+原子序列，可排序） 格式: Base + 当日秒偏移*1000 + 原子序列 + Worker偏移 与 UserID 的区别: 秒级精度而非天级，每秒可生成 1000 个

func (*NumericIDGenerator) GenerateUserID 

func (g *NumericIDGenerator) GenerateUserID() string

GenerateUserID 生成用户ID（纯原子递增，无时间轮） Store 模式: 本地原子递增 + 批量预取，区间用完时原子获取新区间 本地模式: 纯原子递增，无锁 格式: 1 DDD W SSSS (固定首位 + 天数偏移 + Worker ID + 日序列)

func (*NumericIDGenerator) WorkerID 

func (g *NumericIDGenerator) WorkerID() uint64

WorkerID 返回当前Worker ID

type ShortFlakeBase62Generator 

type ShortFlakeBase62Generator struct {
	*ShortFlakeGenerator
}

ShortFlakeBase62Generator Base62 编码的短 ID 生成器 将 53 位数字编码为 9-10 字符的字符串

func NewShortFlakeBase62Generator 

func NewShortFlakeBase62Generator(nodeID int64) *ShortFlakeBase62Generator

NewShortFlakeBase62Generator 创建 Base62 编码生成器

func (*ShortFlakeBase62Generator) GenerateCorrelationID 

func (g *ShortFlakeBase62Generator) GenerateCorrelationID() string

GenerateCorrelationID 生成 Base62 编码的 CorrelationID（双段拼接） 格式: base62(shortflake_id)-base62(shortflake_id)，18-22字符 示例: "aB3xK9mPqR-xY7wN4qL2v" 与 TraceID 的区别: 双段拼接，增强唯一性，适合跨系统关联

func (*ShortFlakeBase62Generator) GenerateRequestID 

func (g *ShortFlakeBase62Generator) GenerateRequestID() string

GenerateRequestID 生成 Base62 编码的 RequestID（前缀+计数器） 格式: base62前6字符-递增计数器 示例: "aB3xK9-1" 与 TraceID 的区别: 带计数器后缀，可排序

func (*ShortFlakeBase62Generator) GenerateSpanID 

func (g *ShortFlakeBase62Generator) GenerateSpanID() string

GenerateSpanID 生成 Base62 编码的 SpanID（6字符） 格式: base62(shortflake_id & 0x3FFFFFFFFF)，取低36位 示例: "K9mPxR" 与 TraceID 的区别: 更短，仅保留低位部分

func (*ShortFlakeBase62Generator) GenerateTraceID 

func (g *ShortFlakeBase62Generator) GenerateTraceID() string

GenerateTraceID 生成 Base62 编码的 TraceID（9-10字符） 格式: base62(shortflake_id) 示例: "aB3xK9mPqR" 与 RequestID 的区别: Base62 编码更短，URL 安全

type ShortFlakeConfig 

type ShortFlakeConfig struct {
	Epoch  int64 // 纪元时间戳（毫秒），默认 2022-01-01 00:00:00 UTC
	NodeID int64 // 节点 ID，0 到 ShortFlakeMaxNodeID
}

ShortFlakeConfig ShortFlake 生成器配置

func DefaultShortFlakeConfig 

func DefaultShortFlakeConfig() ShortFlakeConfig

DefaultShortFlakeConfig 返回默认配置（纪元 2022-01-01，节点 0）

func (ShortFlakeConfig) Validate 

func (c ShortFlakeConfig) Validate() error

Validate 校验配置合法性

越界的节点 ID 必须报错，不能像原先那样用 nodeID & 0x3F 静默折回 折回会让配成 64 的节点和配成 0 的节点变成同一个节点，从此发出完全相同的 ID， 负数同理（-1 折成 63）这种错误启动时毫无迹象，只会在数据里留下重复 详见 SnowflakeConfig.Validate 的说明

[EN] An out-of-range node ID must be rejected rather than folded back with nodeID & 0x3F. Folding makes a node configured as 64 and one configured as 0 the same node, emitting identical IDs; negatives fold too. See SnowflakeConfig.Validate

type ShortFlakeGenerator 

type ShortFlakeGenerator struct {
	// contains filtered or unexported fields
}

ShortFlakeGenerator 短 Snowflake 生成器 生成 53 位整数（JavaScript Number 安全范围） 时间戳(41位) + 机器ID(6位) + 序列号(6位) = 53位 最大值: 9007199254740991 (约 9PB，16位数字)

func NewShortFlakeGenerator 

func NewShortFlakeGenerator(nodeID int64) *ShortFlakeGenerator

NewShortFlakeGenerator 创建短 Snowflake 生成器

nodeID 取值 0 到 ShortFlakeMaxNodeID，越界会 panic 原因见 ShortFlakeConfig.Validate

func NewShortFlakeGeneratorWithConfig 

func NewShortFlakeGeneratorWithConfig(cfg ShortFlakeConfig) *ShortFlakeGenerator

NewShortFlakeGeneratorWithConfig 按配置创建短 Snowflake 生成器

配置非法时 panic，与包内其他生成器一致

func (*ShortFlakeGenerator) Generate 

func (g *ShortFlakeGenerator) Generate() int64

Generate 生成 53 位整数 ID

func (*ShortFlakeGenerator) GenerateCorrelationID 

func (g *ShortFlakeGenerator) GenerateCorrelationID() string

GenerateCorrelationID 生成关联ID（UUID 风格的 hex 格式） 格式: 8-4-4-4-4 hex（由 shortflake ID 拆分 + 计数器填充） 示例: "018f5a3c-7d2e-4b10-a1c3-e5f67890" 与 TraceID 的区别: UUID 格式，含连字符，适合跨系统传递

func (*ShortFlakeGenerator) GenerateRequestID 

func (g *ShortFlakeGenerator) GenerateRequestID() string

GenerateRequestID 生成请求ID（纯数字+计数器后缀） 格式: shortflake数字-递增计数器 示例: "3425234523452-1" 与 TraceID 的区别: 纯数字+计数器，方便日志检索和排序

func (*ShortFlakeGenerator) GenerateSpanID 

func (g *ShortFlakeGenerator) GenerateSpanID() string

GenerateSpanID 生成跨度ID（hex 低8字符） 格式: hex(shortflake_id & 0xFFFFFFFF) 示例: "7d2e4b10" 与 TraceID 的区别: 更短，仅保留低位部分

func (*ShortFlakeGenerator) GenerateTraceID 

func (g *ShortFlakeGenerator) GenerateTraceID() string

GenerateTraceID 生成跟踪ID（hex 编码，13字符） 格式: hex(shortflake_id) 示例: "018f5a3c7d2e4" 与 RequestID 的区别: hex 编码更紧凑，适合 HTTP Header 传递

type ShortIDGenerator 

type ShortIDGenerator struct {
	// contains filtered or unexported fields
}

ShortIDGenerator 8~10位短ID生成器 使用 Base62 编码，时间戳+序列号组合，无互斥锁设计 TraceID: 10字符 (6字符ms时间戳 + 4字符序列号) SpanID: 8字符 (纯随机) RequestID: ~10字符 (5字符时间戳-计数器) CorrelationID: 10字符 (纯随机)

func NewShortIDGenerator 

func NewShortIDGenerator() *ShortIDGenerator

NewShortIDGenerator 创建短ID生成器

func (*ShortIDGenerator) GenerateCorrelationID 

func (g *ShortIDGenerator) GenerateCorrelationID() string

GenerateCorrelationID 生成关联ID（10字符 Base62，纯随机） 格式: 10字符随机Base62 示例: "xY7wN4qL2v" 与 TraceID 的区别: 无时间戳前缀，纯随机，适合跨系统关联

func (*ShortIDGenerator) GenerateRequestID 

func (g *ShortIDGenerator) GenerateRequestID() string

GenerateRequestID 生成请求ID（时间戳前缀+计数器，可排序） 格式: 5字符Base62(秒级时间戳)-递增计数器 示例: "0If09-1" 与 TraceID 的区别: 秒级精度+计数器，方便按请求顺序排序

func (*ShortIDGenerator) GenerateSpanID 

func (g *ShortIDGenerator) GenerateSpanID() string

GenerateSpanID 生成跨度ID（8字符 Base62，纯随机） 格式: 8字符随机Base62 示例: "K9mPxR2v" 与 TraceID 的区别: 无时间戳前缀，纯随机，更短，同 Trace 内唯一

func (*ShortIDGenerator) GenerateTraceID 

func (g *ShortIDGenerator) GenerateTraceID() string

GenerateTraceID 生成跟踪ID（10字符 Base62，时间可排序） 格式: 6字符Base62(毫秒时间戳) + 4字符Base62(原子序列号) 示例: "0If09Q4b2x" 特点: 前6字符编码时间戳，字典序=时间序，后4字符序列号保证同毫秒唯一(1476万/ms)

type SnowflakeConfig 

type SnowflakeConfig struct {
	Epoch        int64 // 纪元时间戳（毫秒），默认 2022-01-01 00:00:00 UTC
	WorkerID     int64 // 工作机器 ID，0 到 SnowflakeMaxWorkerID
	DatacenterID int64 // 数据中心 ID，0 到 SnowflakeMaxDatacenterID
}

SnowflakeConfig Snowflake 生成器配置

func DefaultSnowflakeConfig 

func DefaultSnowflakeConfig() SnowflakeConfig

DefaultSnowflakeConfig 返回默认配置（纪元 2022-01-01，机器与数据中心均为 0）

func (SnowflakeConfig) Validate 

func (c SnowflakeConfig) Validate() error

Validate 校验配置合法性

越界的 ID 必须报错，不能像原先那样用 workerID & 0x1F 静默折回

静默折回的后果是两台机器拿到同一个 ID：配成 32 的机器和配成 0 的机器会被折成 同一个 worker，从此发出完全相同的 ID而这恰好是分布式 ID 生成器唯一要保证的事负数同理，-1 会被折成 31 这种错误在启动时没有任何迹象，等到数据里出现重复主键才被发现，溯源极难 启动即失败远好过静默发重号

[EN] Out-of-range IDs must be rejected rather than silently folded back with workerID & 0x1F as before. Folding makes two machines share one ID: a machine configured as 32 and one configured as 0 become the same worker and emit identical IDs from then on — the one thing a distributed ID generator exists to guarantee. Negatives fold too, with -1 becoming 31. Nothing shows at startup; it surfaces as duplicate primary keys much later, and tracing it back is very hard. Failing at startup is far better than silently issuing duplicates

type SnowflakeGenerator 

type SnowflakeGenerator struct {
	// contains filtered or unexported fields
}

SnowflakeGenerator Snowflake 分布式ID生成器

func NewSnowflakeGenerator 

func NewSnowflakeGenerator(workerID, datacenter int64) *SnowflakeGenerator

NewSnowflakeGenerator 创建 Snowflake 生成器

workerID 与 datacenter 的取值范围见 SnowflakeMaxWorkerID / SnowflakeMaxDatacenterID 越界会 panic，原因见 SnowflakeConfig.Validate

func NewSnowflakeGeneratorWithConfig 

func NewSnowflakeGeneratorWithConfig(cfg SnowflakeConfig) *SnowflakeGenerator

NewSnowflakeGeneratorWithConfig 按配置创建 Snowflake 生成器

配置非法时 panic，与 NewNumericIDGeneratorWithConfig 保持一致：ID 生成器的 配置属于启动期参数，带着错误配置继续跑只会污染数据

func (*SnowflakeGenerator) Generate 

func (g *SnowflakeGenerator) Generate() int64

Generate 生成 Snowflake ID

func (*SnowflakeGenerator) GenerateCorrelationID 

func (g *SnowflakeGenerator) GenerateCorrelationID() string

GenerateCorrelationID 生成关联ID（UUID 风格的 hex 格式） 格式: 8-4-4-4-4 hex（由 snowflake ID 拆分填充） 示例: "018f5a3c-7d2e-4b10-a1c3-e5f678901234" 与 TraceID 的区别: UUID 格式，含连字符，适合跨系统传递和关联

func (*SnowflakeGenerator) GenerateRequestID 

func (g *SnowflakeGenerator) GenerateRequestID() string

GenerateRequestID 生成请求ID（纯数字+计数器后缀） 格式: snowflake数字-递增计数器 示例: "1732184000123456789-1" 与 TraceID 的区别: 纯数字+计数器，可排序，方便日志检索

func (*SnowflakeGenerator) GenerateSpanID 

func (g *SnowflakeGenerator) GenerateSpanID() string

GenerateSpanID 生成跨度ID（hex截取后8字符） 格式: hex(snowflake_id) 后8字符 示例: "7d2e4b10" 与 TraceID 的区别: 更短，仅保留低位部分，同 Trace 内唯一

func (*SnowflakeGenerator) GenerateTraceID 

func (g *SnowflakeGenerator) GenerateTraceID() string

GenerateTraceID 生成跟踪ID（16进制格式，带时间排序特征） 格式: hex(snowflake_id)，16字符 示例: "018f5a3c7d2e4b10" 与 RequestID 的区别: 使用 hex 编码，更适合作为追踪标识

type ULIDGenerator 

type ULIDGenerator struct {
	// contains filtered or unexported fields
}

ULIDGenerator ULID 生成器（时间排序友好，高性能版本）

func NewULIDGenerator 

func NewULIDGenerator() *ULIDGenerator

NewULIDGenerator 创建 ULID 生成器

func (*ULIDGenerator) GenerateCorrelationID 

func (g *ULIDGenerator) GenerateCorrelationID() string

GenerateCorrelationID 生成关联ID（双 ULID 拼接，52字符） 格式: ULID-ULID 示例: "01ARZ3NDEKTSV4RRFFQ69G5FAV-01ARZ3ND0LWM4PQXX7HVK5FAVZ" 与 TraceID 的区别: 双段拼接，增强唯一性，适合跨系统关联

func (*ULIDGenerator) GenerateRequestID 

func (g *ULIDGenerator) GenerateRequestID() string

GenerateRequestID 生成请求ID（ULID前缀+计数器后缀） 格式: ULID前10字符(时间戳部分)-递增计数器 示例: "01ARZ3NDEK-1" 与 TraceID 的区别: 仅保留时间戳部分+计数器，可排序

func (*ULIDGenerator) GenerateSpanID 

func (g *ULIDGenerator) GenerateSpanID() string

GenerateSpanID 生成跨度ID（ULID 后16字符，即随机部分） 格式: 截取 ULID 的随机部分 示例: "TSV4RRFFQ69G5FAV" 与 TraceID 的区别: 去掉时间戳前缀，更短，同一 Trace 内唯一

func (*ULIDGenerator) GenerateTraceID 

func (g *ULIDGenerator) GenerateTraceID() string

GenerateTraceID 生成跟踪ID（完整 ULID，26字符） 格式: 10字符时间戳 + 16字符随机部分（Crockford Base32） 示例: "01ARZ3NDEKTSV4RRFFQ69G5FAV" 时间排序: 字典序 = 时间序，天然适合追踪

type UUIDGenerator 

type UUIDGenerator struct {
	// contains filtered or unexported fields
}

UUIDGenerator UUID v4 生成器（高性能版本）

func NewUUIDGenerator 

func NewUUIDGenerator() *UUIDGenerator

NewUUIDGenerator 创建 UUID 生成器

func (*UUIDGenerator) GenerateCorrelationID 

func (g *UUIDGenerator) GenerateCorrelationID() string

GenerateCorrelationID 生成关联ID（完整 UUID v4，36字符） 格式: 与 TraceID 相同的 UUID v4 格式 示例: "a1b2c3d4-e5f6-41d4-a716-446655440000" 与 TraceID 的区别: 独立生成，不与 TraceID 共享，用于跨系统关联

func (*UUIDGenerator) GenerateRequestID 

func (g *UUIDGenerator) GenerateRequestID() string

GenerateRequestID 生成请求ID（UUID前缀+计数器后缀） 格式: UUID前8字符-递增计数器 示例: "550e8400-1" 与 TraceID 的区别: 带计数器后缀，可按请求顺序排序

func (*UUIDGenerator) GenerateSpanID 

func (g *UUIDGenerator) GenerateSpanID() string

GenerateSpanID 生成跨度ID（UUID 前16字符，去除连字符） 格式: UUID 前8字节hex（16字符） 示例: "550e8400e29b41d4" 与 TraceID 的区别: 截取 UUID 时间戳部分，更短，同一 Trace 内唯一

func (*UUIDGenerator) GenerateTraceID 

func (g *UUIDGenerator) GenerateTraceID() string

GenerateTraceID 生成跟踪ID（完整 UUID v4，36字符） 格式: 8-4-4-4-12 hex（含版本位和变体位） 示例: "550e8400-e29b-41d4-a716-446655440000"

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.