Jordium.Snowflake.NET

<p align="center"> <img src="./assets/images/trans-min.png" alt="Jordium.Snowflake.NET Logo" width="200"/> </p>

English | 简体中文

高性能分布式 ID 生成器，基于 Twitter Snowflake 算法的 .NET 实现。支持三种实现方式，适用于不同的应用场景。

特性

• ✅ 全局唯一：支持多数据中心、多机器部署
• 📈 趋势递增：ID 按时间戳递增，支持数据库索引优化
• ⚡ 高性能：单机器可达 200 万 - 2000 万 ID/秒（依据不同测试环境的条件会产生结果偏差）
• 🔧 多种实现：漂移算法、传统算法、无锁算法
• ⏰ 时间回拨处理：自动处理系统时间回拨问题
• 🎯 灵活配置：支持自定义位数分配

ID 结构

标准 64 位雪花 ID

┌─────────────────┬─────────────┬─────────────┬──────────────┐
│ 时间戳 (41 位)   │ 数据中心(5位)│ 机器ID (5位) │ 序列号(12位)  │
└─────────────────┴─────────────┴─────────────┴──────────────┘
  约 69 年          32 个        32 台        4096/毫秒

位数分配示例

| 配置 | Worker 位 | DC 位 | Seq 位 | 容量 | | ---------- | --------- | ----- | ------ | --------------------------- | | 标准 | 5 | 5 | 12 | 32 DC × 32 Worker × 4096/ms | | 多数据中心 | 4 | 6 | 12 | 64 DC × 16 Worker × 4096/ms | | 多机器 | 6 | 4 | 12 | 16 DC × 64 Worker × 4096/ms | | 低并发 | 5 | 5 | 10 | 32 DC × 32 Worker × 1024/ms |

约束条件：

• Worker 位 + DC 位 + Seq 位 ≤ 22
• Seq 位 ≤ 12

安装

NuGet CLI

Install-Package Jordium.Snowflake.NET

.NET CLI

dotnet add package Jordium.Snowflake.NET

PackageReference

<PackageReference Include="Jordium.Snowflake.NET" Version="1.2.0" />

开始使用（v1.2.0）

客户端应用

1. 引入命名空间

using Jordium.Snowflake.NET;

2. 利用工厂模型创建实例

// 方式1： 使用WorkerId和DataCenterId创建实例
var generator1 = JordiumSnowflakeIDGeneratorFactory.Create(workerId: 1, dataCenterId: 1);
System.Console.WriteLine($"Generator 1 (WorkerId=1, DataCenterId=1): {generator1.NewLong()}");

// 方式2： 使用IDGeneratorOption对象创建实例
var options = new IDGeneratorOptions(workerId: 2, dataCenterId: 1)
{
    Method = 1
};
var generator2 = JordiumSnowflakeIDGeneratorFactory.Create(options);
System.Console.WriteLine($"Generator 2 (WorkerId=2, DataCenterId=1): {generator2.NewLong()}");

// 方式3： 使用配置委托创建实例
var generator3 = JordiumSnowflakeIDGeneratorFactory.Create(opt =>
{
    opt.WorkerId = 3;
    opt.DataCenterId = 1;
    opt.Method = 1;
    opt.BaseTime = new DateTime(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc);
});
System.Console.WriteLine($"Generator 3 (WorkerId=3, DataCenterId=1): {generator3.NewLong()}");

3. 利用单例模型初始化全局实例

// Check if default instance is initialized
if (!JordiumSnowflakeIDGeneratorFactory.IsDefaultInitialized)
{
    System.Console.WriteLine("Default instance not initialized. Initializing now...");

    // Initialize the default singleton instance
    JordiumSnowflakeIDGeneratorFactory.InitializeDefault(workerId: 10, dataCenterId: 2);
    System.Console.WriteLine("> Default instance initialized successfully!");
}

// Use the default instance anywhere in your application
long id1 = JordiumSnowflakeIDGeneratorFactory.Default.NewLong();
long id2 = JordiumSnowflakeIDGeneratorFactory.Default.NewLong();
long id3 = JordiumSnowflakeIDGeneratorFactory.Default.NewLong();

ASP.NET Core 依赖注入（v1.2.0+ 更方便的注册方式，更遵循 ASP.NET Core 标准）

1. 引入命名空间

using Jordium.Snowflake.NET.Extensions;

2. 注册 Jordium.Snowflake.NET 服务

// Program.cs OR Startup.cs
public void ConfigureServices(IServiceCollection services)
{
    // use code-based configuration
    services.AddJordiumSnowflakeIdGenerator(options => {
        options.WorkerId = 1;
        options.DataCenterId = 1;
    });
}

// Controller
public class OrderController : ControllerBase
{
    private readonly IIDGenerator _idGenerator;

    public OrderController(IIDGenerator idGenerator)
    {
        _idGenerator = idGenerator;
    }

    [HttpPost]
    public IActionResult CreateOrder()
    {
        long orderId = _idGenerator.NewLong();
        // ID Generated
        return Ok(new { OrderId = orderId });
    }
}

3. 支持 3 种注册方式

// 方式1: 从appsettings.json中读取默认的"JordiumSnowflakeConfig"配置
services.AddJordiumSnowflakeIdGenerator();

// appsettings.json中配置：
"JordiumSnowflakeConfig": {
  "DataCenterId": 1,
  "WorkerId": 2,
  "Method": 1,
  "WorkerIdBitLength": 5,
  "DataCenterIdBitLength": 5,
  "SequenceBitLength": 12
}

// 方案2: 使用自定义配置"MyCustomSnowflakeConfigSection"
services.AddJordiumSnowflakeIdGenerator(_configuration, "MyCustomSnowflakeConfigSection");

// appsettings.json中配置：
"MyCustomSnowflakeConfigSection": {
  "DataCenterId": 1,
  "WorkerId": 2,
  "Method": 1,
  "WorkerIdBitLength": 5,
  "DataCenterIdBitLength": 5,
  "SequenceBitLength": 12
}

// 方案3: 基于代码的配置
services.AddJordiumSnowflakeIdGenerator(options => {
    options.WorkerId = 1;
    options.DataCenterId = 1;
    ...其他属性
});

IDGeneratorOptions 属性说明

| 属性名 | 类型 | 说明 | 默认值 | | ------------------------- | -------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------- | | Method | short | 计算方法（1-漂移算法，2-传统算法，3-无锁算法） | 1 | | BaseTime | DateTime | 开始时间（UTC 格式），不能超过当前系统时间 | DateTime(2020, 2, 20, 2, 20, 2, 20, DateTimeKind.Utc) | | WorkerId | ushort | 机器码 | 0 | | DataCenterId | ushort | 数据中心标识码 | 0 | | WorkerIdBitLength | byte | 机器码位长。建议范围：1-5（要求：序列数位长+数据标识+机器码位长不超过 22）。 | 5 | | DataCenterIdBitLength | byte | 数据中心识别码位长。建议范围：1-5（要求：序列数位长+数据标识+机器码位长不超过 22）。 | 5 | | SeqBitLength | byte | 序列数位长。建议范围：1-12（要求：序列数位长+机器码位长不超过 22）4096。 | 12 | | MaxSeqNumber | int | 最大序列数（含）。（由 SeqBitLength 计算的最大值） | 0 | | MinSeqNumber | int | 最小序列数（含）。默认 0，不小于 0，不大于 MaxSeqNumber | 0 | | TopOverCostCount | int | 最大漂移次数（含）。默认 2000，推荐范围 500-10000（与计算能力有关） | 2000 |

支持目标框架

• .NET Framework (>= 4.6.1)
• .NET 6
• .NET 7
• .NET 8
• .NET 9
• .NET 10
• .NET Standard (>= 2.0)

内置算法对比（可查看开源库中提供的源码）

本章节提及的代码块为进行单元测试，基于底层代码直接实例化和演示，非依赖注入和工厂模式实例

三种算法

| 算法版本 | 实现类 | 适用场景 | 性能 | 时间回拨处理 | 推荐度 | | ------------ | ----------------- | -------------------- | ---------- | ----------------- | ---------- | | Method 1 | SnowflakeWorkerV1 | 单体应用、高并发单机 | ⭐⭐⭐⭐ | ✅ 特殊序列号 | ⭐⭐⭐⭐⭐ | | Method 2 | SnowflakeWorkerV2 | 通用场景、标准实现 | ⭐⭐⭐⭐ | ❌ 抛出异常 | ⭐⭐⭐ | | Method 3 | SnowflakeWorkerV3 | 分布式集群、微服务 | ⭐⭐⭐⭐⭐ | ⚠️ 大幅回拨抛异常 | ⭐⭐⭐⭐ |

详细说明

Method 1 - 漂移算法（推荐）

特点：

• ✅ 自动处理时间回拨（使用预留序列号 1-4）
• ✅ 序列号溢出时自动"漂移"到未来时间
• ✅ 有完善的事件回调机制
• 🔒 使用 lock 同步

适用场景：

• 单体应用（多线程竞争同一个 WorkerId）
• 对时间回拨敏感的业务
• 需要监控 ID 生成状态的系统

配置示例：

var options = new IDGeneratorOptions
{
    WorkerId = 1,
    DataCenterId = 1,
    Method = 1,
    TopOverCostCount = 2000  // 最大漂移次数
};

var generator = new DefaultIDGenerator(options);

// 可选：监听事件
generator.GenIdActionAsync = arg =>
{
    if (arg.ActionType == 1) // 开始漂移
    {
        Console.WriteLine($"开始漂移: WorkerId={arg.WorkerId}");
    }
};

---

Method 2 - 传统算法

特点：

• ✅ 标准 Snowflake 实现
• ✅ 逻辑简单，易于理解
• ❌ 时间回拨时抛出异常
• 🔒 使用 lock 同步

适用场景：

• 学习和理解 Snowflake 算法
• 时间回拨极少的稳定环境
• 不需要复杂功能的简单场景

配置示例：

var options = new IDGeneratorOptions
{
    WorkerId = 1,
    DataCenterId = 1,
    Method = 2
};

var generator = new DefaultIDGenerator(options);

try
{
    long id = generator.NewLong();
}
catch (Exception ex)
{
    // 时间回拨时会抛出异常
    Console.WriteLine($"时间回拨错误: {ex.Message}");
}

---

Method 3 - 无锁算法（高性能）

特点：

• ✅ 使用 CAS 无锁并发，性能最高
• ✅ 时间戳缓存在状态中，减少系统调用
• ✅ 在分布式场景下性能优势明显
• ⚠️ 短时间回拨自动休眠等待
• ⚠️ 大幅回拨（> 1000ms）抛出异常

适用场景：

• 微服务集群（每个服务独立 WorkerId）
• Kubernetes 部署（每个 Pod 独立 WorkerId）
• 高并发分布式系统
• 追求极致性能的场景

配置示例：

var options = new IDGeneratorOptions
{
    WorkerId = 1,
    DataCenterId = 1,
    Method = 3
};

var generato