RuoVea.ExIdGen 10.0.0.3

🆔 RuoVea.ExIdGen

分布式唯一 ID 生成器 — 基于雪花漂移算法（移植自 yitter/idgenerator），生成 64 位长整型 ID、带前缀字符串 ID、以及基于时间戳的自增编号，内置中、英、法、日、繁体中文、粤语、越南语等 8 种语言的异常提示。

📖 目录

• 📋 概览
• 📦 安装
• ⚡ 30 秒快速开始
• 🧩 核心场景
  • 场景一：生成 Snowflake ID（长整型）
  • 场景二：生成带前缀的字符串 ID
  • 场景三：生成基于时间的自增编号
  • 场景四：三种算法模式切换
  • 场景五：通过 IConfiguration 配置
  • 场景六：使用 IIdGenerator 接口
• ⚙️ 配置选项详解
• 🛡️ 错误处理与日志
• 🧵 线程安全
• 📊 算法速查表
• 🌍 国际化
• 🗺️ 版本迁移指南

📋 概览

RuoVea.ExIdGen 为 .NET 开发者提供开箱即用的分布式唯一 ID 生成能力，基于雪花（Snowflake）算法并通过漂移补偿机制解决时钟回拨问题。

 ┌──────────────────────────────────────────────────────────┐
 │                    RuoVea.ExIdGen                         │
 ├──────────────────────────────────────────────────────────┤
 │  ID 生成方式                                              │
 │  ├─ Id (static long)           → 64 位 Snowflake ID      │
 │  ├─ IdStr(prefix)              → 带前缀字符串 ID          │
 │  ├─ No(format)                 → 时间戳自增长整型编号     │
 │  └─ NoStr(format)              → 时间戳自增字符串编号     │
 │                                                          │
 │  算法模式                                                 │
 │  ├─ Method 1 (默认) — 雪花漂移算法，时钟回拨补偿          │
 │  ├─ Method 2        — 传统雪花算法，时钟回拨抛出异常      │
 │  └─ Method 3        — 漂移算法 + DataCenter + 秒级时间戳 │
 │                                                          │
 │  配置方式                                                 │
 │  ├─ Configure(options)         → IdGeneratorOptions 对象 │
 │  ├─ Configure(workerId, seq)   → 精简配置                │
 │  └─ Configure(IConfiguration)  → appsettings.json 驱动   │
 ├──────────────────────────────────────────────────────────┤
 │  国际化: zh-CN | zh-TW | zh-HK | en-US | fr-FR |          │
 │           ja-JP | vi-VN                                  │
 └──────────────────────────────────────────────────────────┘

设计原则

📦 安装

.NET CLI

# .NET 8.0
dotnet add package RuoVea.ExIdGen --version 8.0.1.1

# .NET 10.0
dotnet add package RuoVea.ExIdGen --version 10.0.0.2

Package Manager

Install-Package RuoVea.ExIdGen -Version 8.0.1.1

PackageReference

<PackageReference Include="RuoVea.ExIdGen" Version="8.0.1.1" />

支持的 Target Framework

⚡ 30 秒快速开始

1. 导入命名空间

using RuoVea.ExIdGen;                   // IdGenerator, ConfigureOption
using RuoVea.ExIdGen.Contract;          // IdGeneratorOptions, IIdGenerator

2. 配置并生成第一个 ID

// ① 配置（应用启动时执行一次）
IdGenerator.Configure(workerId: 1, seqBitLength: 6);

// ② 生成 64 位 Snowflake ID
long id = IdGenerator.Id;
Console.WriteLine(id); // 如: 745635281972854784

// ③ 生成带前缀的字符串 ID
string orderId = IdGenerator.IdStr("ORDER_");
Console.WriteLine(orderId); // "ORDER_745635281972854784"

3. 通过 appsettings.json 配置

{
  "IdGenerator": {
    "WorkerId": "1",
    "SeqBitLength": "6"
  }
}

// 在 Program.cs / Startup.cs 中
var configuration = builder.Configuration;
IdGenerator.Configure(configuration);

❗ 注意: Configure(IConfiguration) 方法存在 Bug——当配置文件中未提供 SeqBitLength 时，会将 workerId 错误赋值为 6（而非将 seqBitLength 赋值为 6）。请务必在配置文件中显式提供 SeqBitLength 字段，或改用 Configure(ushort, byte) 重载。

30 秒内你完成了: 导入命名空间 → 配置 WorkerId → 生成 Snowflake ID → 生成带前缀字符串 ID。

🧩 核心场景

场景一：生成 Snowflake ID（长整型）

┌──────────────┐    IdGenerator.Id    ┌───────────────────┐
│  WorkerId=1  │ ─────────────────▶  │  745635281972854784 │
│  (机器码)     │                      │  (64-bit long)      │
└──────────────┘                      └───────────────────┘
用例: 数据库主键、消息队列消息ID、全局唯一标识

// 生成单个 ID
long userId = IdGenerator.Id;

// 批量生成（用于数据迁移等场景）
var ids = new List<long>();
for (int i = 0; i < 1000; i++)
{
    ids.Add(IdGenerator.Id);
}

// 验证唯一性
bool allUnique = ids.Distinct().Count() == ids.Count;
Console.WriteLine(allUnique); // True

场景二：生成带前缀的字符串 ID

┌──────────────┐  IdGenerator.IdStr("ORDER_")  ┌──────────────────────────┐
│  WorkerId=1  │ ──────────────────────────▶  │  "ORDER_745635281972854784" │
└──────────────┘                                └──────────────────────────┘
用例: 订单编号、物流单号、工单编号（人类可读前缀 + 机器唯一后缀）

// 无前缀
string id1 = IdGenerator.IdStr();
// → "745647812025876480"

// 业务前缀——订单
string orderId = IdGenerator.IdStr("ORD");
// → "ORD745647812025876480"

// 业务前缀——支付流水
string paymentId = IdGenerator.IdStr("PAY");
// → "PAY745647812025876481"

⚠️ 注意: IdStr 仅做字符串拼接（prefix + NextId()），不保证前缀在分布式场景下的唯一性。如需确保前缀 + 业务语义的全局唯一，应在业务层设计前缀规范。

场景三：生成基于时间的自增编号

┌──────────┐   IdGenerator.No("yyyyMMddHHmmss")   ┌──────────────────────┐
│  当前时间  │ ─────────────────────────────────▶  │  202602231508451234  │
│  随机后缀  │                                       │  (时间戳 + 4位随机)  │
└──────────┘                                       └──────────────────────┘
用例: 流水号、批次号、临时编号（时间可读 + 简易去重）

// 默认格式 yyyyMMddHHmmss + 4 位随机数
string noStr = IdGenerator.NoStr();
// → "202602231508451234"

long noLong = IdGenerator.No();
// → 202602231508459876

// 自定义时间格式
string shortNo = IdGenerator.NoStr("yyMMddHHmm");
// → "2602231508" + 随机后缀

⚠️ 使用注意: No / NoStr 使用共享的 static Random + 自增计数器 _sn 生成后缀，单实例内线程安全。该格式非 Snowflake ID，不保证跨实例唯一性。

场景四：三种算法模式切换

// 模式 1（默认）: 雪花漂移算法 — 时钟回拨自动补偿，推荐用于生产环境
IdGenerator.Configure(new IdGeneratorOptions
{
    WorkerId = 1,
    Method = 1                     // 漂移补偿
});

// 模式 2: 传统雪花算法 — 严格单调递增，遇到时钟回拨直接抛出异常
IdGenerator.Configure(new IdGeneratorOptions
{
    WorkerId = 2,
    Method = 2                     // 传统雪花
});

// 模式 3: 漂移算法 + DataCenter + 秒级时间戳 — 适用于多数据中心、低精度场景
IdGenerator.Configure(new IdGeneratorOptions
{
    WorkerId = 1,
    DataCenterId = 3,
    DataCenterIdBitLength = 2,
    TimestampType = 1,             // 秒级时间戳
    Method = 1                     // 漂移补偿（Method=1 时自动选择 M3 实现）
});

⚠️ 注意: 当 Method=1 且 DataCenterIdBitLength > 0 或 TimestampType = 1 时，自动选择 SnowWorkerM3 实现。

场景五：通过 IConfiguration 配置

// appsettings.json
{
  "IdGenerator": {
    "WorkerId": "3",
    "SeqBitLength": "8"
  }
}

// 初始化
var builder = WebApplication.CreateBuilder(args);
IdGenerator.Configure(builder.Configuration);

❗ Bug 警告: ConfigureOption.Configure(IConfiguration) 在第 61 行存在赋值错误——当 SeqBitLength 解析失败时执行的逻辑是 workerId = 6 而非 seqBitLength = 6。这意味着：如果你的配置文件中未显式提供 SeqBitLength，workerId 将被错误覆盖为 6，而 seqBitLength 保持默认值 6。请务必在配置文件中同时提供 WorkerId 和 SeqBitLength，避免触发此 Bug。

场景六：使用 IIdGenerator 接口

// 获取底层 IIdGenerator 实例
IIdGenerator generator = IdGenerator.IdGenInstance;

// 生成 ID
long id = generator.NewLong();

// 注册漂移事件回调（示例）
generator.GenIdActionAsync = (arg) =>
{
    Console.WriteLine(
        $"ActionType={arg.ActionType}, WorkerId={arg.WorkerId}, " +
        $"TimeTick={arg.TimeTick}, OverCostCount={arg.OverCostCountInOneTerm}");
};

⚠️ 死代码警告: SnowWorkerM1 中的 BeginOverCostAction、EndOverCostAction、BeginTurnBackAction、EndTurnBackAction 四个方法开头均有 return; 语句，导致 GenIdActionAsync 回调永远无法被触发。注册的回调不会收到任何通知。在修复前，不要依赖回调机制来监控 ID 生成状态。

⚙️ 配置选项详解

IdGeneratorOptions

位长约束

WorkerIdBitLength + DataCenterIdBitLength + SeqBitLength ≤ 22（毫秒模式）
WorkerIdBitLength + DataCenterIdBitLength + SeqBitLength ≤ 31（秒级模式）

Configure 重载

🛡️ 错误处理与日志

异常体系

DefaultIdGenerator 构造函数在参数不合法时抛出 ApplicationException（含本地化消息）：

// 未调用 Configure 时自动初始化为 WorkerId=0（不抛异常）
long id = IdGenerator.Id; // ✅ 自动初始化

// WorkerId 超出位长限制 → ApplicationException
IdGenerator.Configure(new IdGeneratorOptions { WorkerId = 64, WorkerIdBitLength = 6 });
// → "workerid错误。(范围：[0,63])"

// BaseTime 超过当前时间 → ApplicationException
IdGenerator.Configure(new IdGeneratorOptions { BaseTime = DateTime.UtcNow.AddDays(1) });
// → "basetime错误。"

// WorkerIdBitLength = 0 → ApplicationException
IdGenerator.Configure(new IdGeneratorOptions { WorkerIdBitLength = 0 });
// → "workeridbitlength错误。(范围:[1,21])"

Method 2 时钟回拨异常

IdGenerator.Configure(new IdGeneratorOptions { Method = 2, WorkerId = 1 });

try
{
    long id = IdGenerator.Id;
}
catch (Exception ex)
{
    // "xxx毫秒的时间错误" — Method 2 遇到时钟回拨时抛出
    _logger.LogError(ex, "Snowflake 时钟回拨，生成的 ID 可能重复");
    // ⚠️ 此时应切换到 Method 1 或暂停服务等待时钟恢复
}

推荐日志模式

using Microsoft.Extensions.Logging;

public class IdGeneratorService
{
    private readonly ILogger<IdGeneratorService> _logger;

    public IdGeneratorService(ILogger<IdGeneratorService> logger) => _logger = logger;

    /// <summary>
    /// 带日志的 ID 生成器初始化
    /// </summary>
    public void Initialize(ushort workerId, byte seqBitLength = 6)
    {
        try
        {
            IdGenerator.Configure(workerId, seqBitLength);
            _logger.LogInformation(
                "ExIdGen 初始化成功: WorkerId={WorkerId}, SeqBitLength={SeqBitLength}",
                workerId, seqBitLength);
        }
        catch (ApplicationException ex)
        {
            _logger.LogError(ex, "ExIdGen 初始化失败，参数校验未通过");
            throw;
        }
    }

    /// <summary>
    /// 安全生成 ID（Method 2 时钟回拨兜底）
    /// </summary>
    public long NextIdSafe()
    {
        try
        {
            return IdGenerator.Id;
        }
        catch (Exception ex) when (ex.Message.Contains("毫秒的时间错误"))
        {
            _logger.LogWarning(ex, "传统雪花模式遭遇时钟回拨，考虑切换到 Method=1");
            throw;
        }
    }
}

🧵 线程安全

⚠️ 重要: 全局锁限制: SnowWorkerM1._SyncLock 是 static readonly，所有 DefaultIdGenerator 实例共享同一把锁。多实例场景下 ID 生成完全串行化。如需更高吞吐量，请在应用层做 worker 分片。

// ✅ 正确: 启动时配置
public static void Main(string[] args)
{
    IdGenerator.Configure(workerId: 1, seqBitLength: 6); // ← 先配置
    var app = BuildApp(args);
    app.Run();
}

// ❌ 错误: 延迟配置（并发访问可能创建多个实例）
Task.Run(() => IdGenerator.Configure(1, 6));
Task.Run(() => { var id = IdGenerator.Id; });   // ← 竞态！

⚠️ 重要（2）: 全局锁: SnowWorkerM1._SyncLock 被声明为 protected static object _SyncLock = new object()。这意味着即使你创建了多个 DefaultIdGenerator 实例（不同的 WorkerId），它们仍共享同一把锁，所有 ID 生成被全局串行化。这是设计权衡——确保时间戳和序列号在进程内绝对单调递增，但是以吞吐量为代价。

⚠️ 重要（3）: 不要声称"无锁"。NextId() 明确使用 lock(_SyncLock) 同步，且 No / NoStr 也使用独立 lock。这不是无锁实现。

📊 算法速查表

ID 结构（Method 1，默认位长配置）

┌─────────────────────────────────────────────────────────────┐
│  63 ......................... 12 │ 11 .... 6 │ 5 ........ 0 │
│         时间戳偏移 (52 bit)      │ WorkerId  │  序列号      │
│                                  │  (6 bit)  │  (6 bit)    │
└─────────────────────────────────────────────────────────────┘
  WorkerIdBitLength=6, SeqBitLength=6, TimestampShift=12

🌍 国际化

错误消息支持以下语言，根据 CultureInfo.CurrentUICulture 自动切换：

// 当前线程 UI 文化为 fr-FR 时:
// ApplicationException → 对应法语的 "basetime错误。"（具体内容取决于 .resx 翻译）
IdGenerator.Configure(new IdGeneratorOptions { BaseTime = DateTime.UtcNow.AddDays(1) });

可通过 I18nConverter.ConvertResxToJson() 将资源内容导出为 JSON（需 NET5_0_OR_GREATER）。

🗺️ 版本迁移指南

从手动管理 Snowflake 迁移

v8.0.x → v10.0.x

• API 无变化。v10.0.x 仅在 net10.0 TFM 上编译，所有公开 API 签名保持一致。
• 依赖 Microsoft.Extensions.Configuration.Binder 版本从 8.0.2 升级到 10.0.8。

📄 License

MIT License © RuoVea

原始算法版权：yitter/idgenerator (MIT)

🔗 相关资源: NuGet Gallery · 问题反馈