snowflake

package
v0.17.6 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 2026 License: MIT Imports: 4 Imported by: 0

README

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
  • 同一毫秒内序列号耗尽时,释放锁等待下一毫秒,不在持锁状态下空转

安装指南

依赖要求
  • Go 1.26.0+
安装依赖

组件已包含在 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 用 099,集群 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

Documentation

Overview

Package snowflake 提供基于雪花算法(Snowflake)的分布式唯一 ID 生成能力。

该实现为纯算法封装,不依赖任何业务类型或全局变量,可直接用于任意项目。 默认起始时间戳为 2024-01-01 00:00:00 UTC,节点位宽 10(0~1023)、序列位宽 12。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Snowflake

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

Snowflake 雪花 ID 生成器

func NewSnowflake

func NewSnowflake(node uint16) (*Snowflake, error)

NewSnowflake 创建雪花 ID 生成器(使用默认起始时间戳)。

参数:

  • node: 节点 ID,范围为 [0, 1023]

返回值:

  • *Snowflake: 生成器实例
  • error: 节点 ID 非法时返回错误

func NewSnowflakeWithEpoch

func NewSnowflakeWithEpoch(node uint16, epochMillis int64) (*Snowflake, error)

NewSnowflakeWithEpoch 创建雪花 ID 生成器,可自定义起始时间戳(毫秒)。

参数:

  • node: 节点 ID,范围为 [0, 1023]
  • epochMillis: 起始时间戳(毫秒)

返回值:

  • *Snowflake: 生成器实例
  • error: 节点 ID 非法时返回错误

func (*Snowflake) NextID

func (s *Snowflake) NextID() (uint64, error)

NextID 生成下一个唯一 ID。 整个生成过程持有互斥锁:序列号在当前毫秒内用尽、或时钟回拨时, 在锁内等待时钟严格越过上次生成时间后再继续,确保任何情况下序列号不会被复用。

返回值:

  • uint64: 生成的雪花 ID
  • error: 时钟回拨超过阈值时返回错误

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL