snowflakeid

package module
v1.0.4 Latest Latest
Warning

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

 Go to latest Published: Jun 28, 2026 License: MIT Imports: 6 Imported by: 0

README

我来帮您优化这个 Markdown 文档的排版，使其更加清晰和专业：

我来帮您优化这个 Markdown 文档的排版。先把您提供的内容进行专业的排版优化：

📦 SnowflakeID 中文文档

一个基于 Twitter Snowflake 算法的高性能分布式 ID 生成器，专为 Go 语言设计。

Go Version Go Reference

✨ 核心特性

特性 说明
🚀 高性能 基于 64 位整数的高效 ID 生成
🔒 分布式安全 支持多节点部署，避免 ID 冲突
📅 时间有序 ID 按时间顺序递增，便于排序和索引
🏷️ 业务分类 内置业务线分类前缀，支持多种业务场景
🔄 Base32 编码 支持 Base32 编码输出，URL 安全，便于传输
⚡ 时钟保护 内置时钟回拨检测与处理机制
🧵 并发安全 使用互斥锁保证多线程环境下的安全性

📐 位分配方案

该 ID 为 64 位结构，具体分配如下：

┌───────────────────────────────────────────────────────────────────────────────┐
│                               64-bit ID (64位ID)                             │
├─────────────────┬─────────────┬─────────────┬─────────────┬─────────────────┤
│     1 bit      │    5 bits   │   2 bits   │   3 bits   │     4 bits      │
│   (符号位)      │  (前缀)     │  (版本)    │ (业务线)   │   (系统ID)     │
├─────────────────┴─────────────┴─────────────┴─────────────┴─────────────────┤
│                               42 bits                                       │
│                            (时间戳)                                         │
├─────────────────────────────────────────────────────────────────────────────┤
│                               7 bits                                        │
│                             (序列号)                                        │
└─────────────────────────────────────────────────────────────────────────────┘
📝 详细说明
字段 位数 说明 支持范围
符号位 1 bit 固定为 0，保留位 -
前缀 5 bits 业务线 + 机器组标识 32 种分类
版本 2 bits 版本号 4 个版本
业务线 3 bits 子业务线 8 个子业务
系统 ID 4 bits 系统节点标识 16 个节点
时间戳 42 bits 毫秒级时间戳 约 139 年
序列号 7 bits 序列号 每毫秒 128 个 ID

📥 安装

go get gitee.com/golang_common/snowflakeid@v1.0.4

🚀 快速开始

基础用法
package main

import (
    "fmt"
    "binrc.com/pkg/snowflakeid"
)

func main() {
    // 创建生成器实例
    // 参数1: BusinessID (0-7)
    // 参数2: SystemID (0-15)
    generator := snowflakeid.NewGenerator(1, 2)
    
    // 生成 ID
    id, base32ID, err := generator.NextID()
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("十进制 ID: %d\n", id)
    fmt.Printf("Base32 ID: %s\n", base32ID)
}
使用自定义前缀
// 使用业务相关前缀
id, base32ID, err := generator.NextIDWithPrefix(snowflakeid.BusinessBit)

// 使用客户相关前缀
id, base32ID, err := generator.NextIDWithPrefix(snowflakeid.CustomerBit)

// 使用设备相关前缀
id, base32ID, err := generator.NextIDWithPrefix(snowflakeid.DeviceBit)
解析 ID 信息
// 将 ID 解析为结构化信息
snowflakeInfo := snowflakeid.ParseID(id)
fmt.Printf("业务 ID: %d\n", snowflakeInfo.Business)
fmt.Printf("系统 ID: %d\n", snowflakeInfo.SystemID)
fmt.Printf("创建时间: %s\n", snowflakeInfo.CreatedTime)
fmt.Printf("Base32 编码: %s\n", snowflakeInfo.Base32)

🏷️ 业务前缀分类表

前缀 二进制 十进制 业务类型 描述
A 00000 0 默认 通用业务
B 00001 1 业务 核心业务逻辑
C 00010 2 客户 客户管理相关
D 00011 3 设备 设备管理相关
E 00100 4 事件 事件记录相关
F 00101 5 文件 文件管理相关
G 00110 6 网关 网关服务相关
H 00111 7 主机 主机管理相关
I 01000 8 实例 实例管理相关
J 01001 9 任务 任务调度相关
K 01010 10 K8s 容器编排相关
L 01011 11 日志 日志管理相关
M 01100 12 模块 模块管理相关
N 01101 13 网络 网络管理相关

⚙️ 配置选项

纪元时间 (Epoch Time)

默认纪元时间为 2025-01-01 UTC，可以通过修改 Epoch 常量进行调整。

日志配置
import "log"

// 设置自定义日志器
generator := snowflakeid.NewGenerator(1, 2)
generator.Logger = log.New(os.Stdout, "[SnowflakeID] ", log.LstdFlags)

📊 性能特征

指标 数值
生成速度 每毫秒可生成 128 个唯一 ID
时钟精度 毫秒级时间戳
内存占用 极低，适合高密度部署
并发支持 完全线程安全

⚠️ 重要注意事项

  1. 时钟同步：确保所有节点使用 NTP 服务进行时间同步
  2. 节点 ID 唯一性：系统 ID 在同一业务线内必须保持唯一
  3. 时钟回拨：系统会自动检测并处理时钟回拨问题
  4. 序列号溢出：当序列号达到 127 时，自动等待下一毫秒

📄 许可证

MIT 许可证

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

📝 更新日志

v1.0.0
  • ✅ 发布初始版本
  • ✅ 支持 64 位分布式 ID 生成
  • ✅ 内置业务分类前缀
  • ✅ 支持 Base32 编码
  • ✅ 时钟回拨保护
  • ✅ 并发安全保证

这就是优化排版后的版本。主要优化点包括：

  1. 添加了徽章栏 - 显示 Go 版本、许可证和参考文档链接
  2. 表格优化 - 将核心特性改为表格形式，更清晰
  3. 结构优化 - 使用分隔线和分级标题增强层次感
  4. 代码块分组 - 基础用法/自定义前缀/解析分开展示
  5. 去掉重复 - 详细说明表格中已包含的内容不再重复
  6. 表格对齐 - 业务前缀分类表格式统一

请问您希望我如何处理这个优化后的版本？

  • 选项 A：直接用这个内容更新仓库的 README.md
  • 选项 B：先在仓库中创建一个 Issue 讨论
  • 选项 C：其他需求

Documentation

Index

Constants

View Source 
const (
	// 位分配
	SignBits      = 1  // 符号位固定为0（保留）
	PrefixBits    = 5  // 前缀类型（A-Z,2-6）
	VersionBits   = 2  // 版本号（0-3）
	BusinessBits  = 3  // 业务线（0-7）
	SystemBits    = 4  // 系统标识（0-15）
	TimestampBits = 42 // 时间戳（可支持139年，从Epoch起）
	SequenceBits  = 7  // 序列号（0-127）

	// 偏移量计算（从高位到低位）
	SignShift      = 63                          // 符号位偏移（第63位）
	PrefixShift    = SignShift - PrefixBits      // 前缀偏移（58-62位）
	VersionShift   = PrefixShift - VersionBits   // 版本偏移（56-57位）
	BusinessShift  = VersionShift - BusinessBits // 业务偏移（53-55位）
	SystemShift    = BusinessShift - SystemBits  // 系统偏移（49-52位）
	TimestampShift = SystemShift - TimestampBits // 时间戳偏移（7-48位）
	SequenceShift  = 0                           // 序列号偏移（0-6位）

	// 最大值计算
	MaxPrefix    = 1<<PrefixBits - 1    // 31（0b11111）
	MaxVersion   = 1<<VersionBits - 1   // 3（0b11）
	MaxBusiness  = 1<<BusinessBits - 1  // 7（0b111）
	MaxSystem    = 1<<SystemBits - 1    // 15（0b1111）
	MaxTimestamp = 1<<TimestampBits - 1 // 4398046511103（42位最大值）
	MaxSequence  = 1<<SequenceBits - 1  // 127（0b1111111）

	// 时间起点（2025-02-28 16:00:00 UTC）
	Epoch = 1740758400000
)
View Source 
const (
	// 默认前缀
	DefaultPrefixBit = 0b00000 // A 默认前缀
	DefaultPrefixTen = 0       // A 默认前缀

	// 业务相关
	BusinessBit = 0b00001 // B 业务相关
	BusinessTen = 1       // B 业务相关

	// 客户相关
	CustomerBit = 0b00010 // C 客户相关
	CustomerTen = 2       // C 客户相关

	// 设备相关
	DeviceBit = 0b00011 // D 设备相关
	DeviceTen = 3       // D 设备相关

	// 事件相关
	EventBit = 0b00100 // E 事件相关
	EventTen = 4       // E 事件相关

	// 文件相关
	FileBit = 0b00101 // F 文件相关
	FileTen = 5       // F 文件相关

	// 网关相关
	GatewayBit = 0b00110 // G 网关相关
	GatewayTen = 6       // G 网关相关

	// 主机相关
	HostBit = 0b00111 // H 主机相关
	HostTen = 7       // H 主机相关

	// 实例相关
	InstanceBit = 0b01000 // I 实例相关
	InstanceTen = 8       // I 实例相关

	// 任务相关
	JobBit = 0b01001 // J 任务相关
	JobTen = 9       // J 任务相关

	// Kubernetes相关
	KubernetesBit = 0b01010 // K Kubernetes相关
	KubernetesTen = 10      // K Kubernetes相关

	// 日志相关
	LogBit = 0b01011 // L 日志相关
	LogTen = 11      // L 日志相关

	// 模块相关
	ModuleBit = 0b01100 // M 模块相关
	ModuleTen = 12      // M 模块相关

	// 网络相关
	NetworkBit = 0b01101 // N 网络相关
	NetworkTen = 13      // N 网络相关

	// 组织相关
	OrganizationBit = 0b01110 // O 组织相关
	OrganizationTen = 14      // O 组织相关

	// 项目相关
	ProjectBit = 0b01111 // P 项目相关
	ProjectTen = 15      // P 项目相关

	// 队列相关
	QueueBit = 0b10000 // Q 队列相关
	QueueTen = 16      // Q 队列相关

	// 资源相关
	ResourceBit = 0b10001 // R 资源相关
	ResourceTen = 17      // R 资源相关

	// 服务相关
	ServiceBit = 0b10010 // S 服务相关
	ServiceTen = 18      // S 服务相关

	// 任务相关
	TaskBit = 0b10011 // T 任务相关
	TaskTen = 19      // T 任务相关

	// 用户相关
	UserBit = 0b10100 // U 用户相关
	UserTen = 20      // U 用户相关

	// 版本相关
	VersionBit = 0b10101 // V 版本相关
	VersionTen = 21      // V 版本相关

	// 工作流相关
	WorkflowBit = 0b10110 // W 工作流相关
	WorkflowTen = 22      // W 工作流相关

	// 实验相关
	ExperimentBit = 0b10111 // X 实验相关
	ExperimentTen = 23      // X 实验相关

	// 数据相关
	YieldBit = 0b11000 // Y 数据相关
	YieldTen = 24      // Y 数据相关

	// 区域相关
	ZoneBit = 0b11001 // Z 区域相关
	ZoneTen = 25      // Z 区域相关

	// 双因子认证相关
	TwoFactorBit = 0b11010 // 2 双因子认证相关
	TwoFactorTen = 26      // 2 双因子认证相关

	// 第三方相关
	ThirdPartyBit = 0b11011 // 3 第三方相关
	ThirdPartyTen = 27      // 3 第三方相关

	// 备份相关
	BackupBit = 0b11100 // 4 备份相关
	BackupTen = 28      // 4 备份相关

	// 测试相关
	TestBit = 0b11101 // 5 测试相关
	TestTen = 29      // 5 测试相关

	// 系统相关
	SystemBit = 0b11110 // 6 系统相关
	SystemTen = 30      // 6 系统相关

	// 保留未分配
	ReservedBit = 0b11111 // 7 保留未分配
	ReservedTen = 31      // 7 保留未分配
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Generator 

type Generator struct {
	Prefix     uint8
	BusinessID uint8
	SystemID   uint8
	Logger     *log.Logger
	// contains filtered or unexported fields
}

func NewGenerator 

func NewGenerator(BusinessID uint8, SystemID uint8) *Generator

func (*Generator) NextID 

func (g *Generator) NextID() (int64, string, error)

生成ID (返回十进制和Base32)

func (*Generator) NextIDWithPrefix 

func (g *Generator) NextIDWithPrefix(prefix uint8) (int64, string, error)

func (*Generator) ParseBase32 added in v1.0.3 

func (g *Generator) ParseBase32(base32ID string) (SnowflakeID, error)

Base32解码

func (*Generator) ParseBase322ID added in v1.0.3 

func (g *Generator) ParseBase322ID(base32ID string) (int64, error)

将 base32字符串还原成 id

func (*Generator) ParseID2Base32 added in v1.0.3 

func (g *Generator) ParseID2Base32(id int64) string

将 id 转成了 base32

type SnowflakeID 

type SnowflakeID struct {
	SignBit     uint8     `json:"signBit"`     // 固定为0（1位）
	Prefix      uint8     `json:"prefix"`      // 业务线+机器组（5位）
	Version     uint8     `json:"version"`     // 版本号（2位）
	Timestamp   int64     `json:"timestamp"`   // 毫秒时间戳（42位）
	Business    uint8     `json:"business"`    // 子业务线（3位）
	SystemID    uint8     `json:"systemId"`    // 系统节点（4位）
	Sequence    uint8     `json:"sequence"`    // 序列号（7位）
	Base32      string    `json:"base32"`      // Base32编码（13字符）
	CreatedTime time.Time `json:"createdTime"` // 生成时间
}

解构后的ID信息

func ParseID 

func ParseID(id int64) SnowflakeID

解析ID

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.