Tenon.DistributedId.Snowflake 0.0.1-alpha-202502101554

This is a prerelease version of Tenon.DistributedId.Snowflake.
dotnet add package Tenon.DistributedId.Snowflake --version 0.0.1-alpha-202502101554                
NuGet\Install-Package Tenon.DistributedId.Snowflake -Version 0.0.1-alpha-202502101554                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Tenon.DistributedId.Snowflake" Version="0.0.1-alpha-202502101554" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Tenon.DistributedId.Snowflake --version 0.0.1-alpha-202502101554                
#r "nuget: Tenon.DistributedId.Snowflake, 0.0.1-alpha-202502101554"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Tenon.DistributedId.Snowflake as a Cake Addin
#addin nuget:?package=Tenon.DistributedId.Snowflake&version=0.0.1-alpha-202502101554&prerelease

// Install Tenon.DistributedId.Snowflake as a Cake Tool
#tool nuget:?package=Tenon.DistributedId.Snowflake&version=0.0.1-alpha-202502101554&prerelease                

Tenon.DistributedId.Snowflake

NuGet version License: MIT

基于 Yitter.IdGenerator 的分布式 ID 生成器实现,为 .NET 应用程序提供高性能、可靠的分布式唯一 ID 生成服务。

✨ 功能特性

  • 🚀 基于 Yitter.IdGenerator 的高性能实现
  • 🔧 支持 Redis 工作节点管理
  • 💉 集成 .NET 依赖注入框架
  • 🎯 自动工作节点注册和注销
  • 🔄 支持工作节点自动刷新
  • 📊 完整的日志监控支持
  • 🛡️ 完善的异常处理机制

📦 安装方式

通过 NuGet 包管理器安装:

dotnet add package Tenon.DistributedId.Snowflake

🚀 快速入门

1. 配置 appsettings.json

{
  "SnowflakeId": {
    "ServiceName": "OrderService",
    "WorkerNode": {
      "Prefix": "distributedId:workerIds:",
      "ExpireTimeInSeconds": 60,
      "RefreshTimeInSeconds": 30,
      "Redis": {
        "ConnectionString": "localhost:6379,defaultDatabase=0"
      }
    }
  }
}

2. 注册服务

// 添加分布式 ID 生成服务
services.AddDistributedId(options =>
{
    // 使用 Snowflake 算法
    options.UseSnowflake(configuration.GetSection("DistributedId"));
    // 使用 StackExchange.Redis 作为工作节点提供者
    options.UseWorkerNode<StackExchangeProvider>(
        configuration.GetSection("DistributedId:WorkerNode"));
});

// 或者使用委托配置
services.AddDistributedId(options => 
{
    options.UseSnowflake(snowflakeOptions => 
    {
        snowflakeOptions.ServiceName = "OrderService";
        snowflakeOptions.WorkerNode = new WorkerNodeOptions 
        {
            Prefix = "distributedId:workerIds:",
            ExpireTimeInSeconds = 60,
            RefreshTimeInSeconds = 30,
            Redis = new RedisOptions 
            {
                ConnectionString = "localhost:6379"
            }
        };
    });
});

3. 使用 ID 生成器

public class OrderService
{
    private readonly IDGenerator _idGenerator;

    public OrderService(IDGenerator idGenerator)
    {
        _idGenerator = idGenerator;
    }

    public long CreateOrderId()
    {
        return _idGenerator.GetNextId();
    }
}

📖 工作节点管理

工作节点配置

public class WorkerNodeOptions
{
    // Redis 键前缀
    public string Prefix { get; set; } = "distributedId:workerIds:";
    
    // 工作节点过期时间(秒)
    public int ExpireTimeInSeconds { get; set; } = 60;
    
    // 工作节点刷新时间(秒)
    public int RefreshTimeInSeconds { get; set; }
    
    // Redis 配置选项
    public RedisOptions Redis { get; set; }
}

工作节点生命周期

// 服务启动时自动注册工作节点
public override async Task StartAsync(CancellationToken cancellationToken)
{
    await _workerNode.RegisterAsync();
    await base.StartAsync(cancellationToken);
}

// 服务停止时自动注销工作节点
public override async Task StopAsync(CancellationToken cancellationToken)
{
    await _workerNode.UnRegisterAsync();
    await base.StopAsync(cancellationToken);
}

⚙️ 配置选项说明

基础配置

配置项 说明 默认值
ServiceName 服务名称(必填) -
WorkerNode.Prefix Redis 键前缀 distributedId:workerIds:
WorkerNode.ExpireTimeInSeconds 工作节点过期时间 60
WorkerNode.RefreshTimeInSeconds 工作节点刷新时间 0

ID 生成器配置

基于 Yitter.IdGenerator 的配置:

  • WorkerIdBitLength: 6 位
  • SeqBitLength: 6 位
  • 最大支持的工作节点数:2^6 = 64 个

🔨 项目依赖

  • Tenon.DistributedId.Abstractions
  • Tenon.Infra.Redis
  • Microsoft.Extensions.DependencyInjection
  • Microsoft.Extensions.Hosting
  • Microsoft.Extensions.Options
  • Yitter.IdGenerator

📝 使用注意事项

1. Redis 配置

  • 确保 Redis 连接可用
  • 合理设置过期时间
  • 配置适当的刷新间隔

2. 工作节点管理

  • 服务名称必须唯一
  • 监控节点注册状态
  • 关注节点过期情况

3. 性能优化

  • 合理设置 WorkerIdBitLength
  • 适当配置 SeqBitLength
  • 避免频繁重启服务

🌰 应用场景示例

1. 订单 ID 生成

public class OrderIdGenerator
{
    private readonly IDGenerator _idGenerator;
    
    public string GenerateOrderId()
    {
        return _idGenerator.GetNextId().ToString("D18");
    }
}

2. 分布式主键生成

public class EntityIdGenerator
{
    private readonly IDGenerator _idGenerator;
    
    public void SetEntityId<T>(T entity) where T : IEntity
    {
        if (entity.Id <= 0)
        {
            entity.Id = _idGenerator.GetNextId();
        }
    }
}

🔍 异常处理

项目定义了两种主要异常类型:

  1. IDGeneratorException

    • ID 生成器异常基类
    • 处理 ID 生成相关的异常
  2. IdGeneratorWorkerNodeException

    • 工作节点异常
    • 处理节点注册、注销等操作异常

🤝 参与贡献

欢迎参与项目贡献!请阅读我们的贡献指南了解如何参与项目开发。

📄 开源协议

本项目采用 MIT 开源协议 - 详情请查看 LICENSE 文件。

Product Compatible and additional computed target framework versions.
.NET net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.0.1-alpha-202502101554 43 2/10/2025
0.0.1-alpha-202502101448 33 2/10/2025
0.0.1-alpha-202502101434 27 2/10/2025
0.0.1-alpha-202501130258 38 1/13/2025
0.0.1-alpha-202412311524 69 12/31/2024
0.0.1-alpha-202412061617 61 12/6/2024
0.0.1-alpha-202412051527 57 12/5/2024
0.0.1-alpha-202412051431 53 12/5/2024
0.0.1-alpha-202412041445 53 12/4/2024
0.0.1-alpha-202412021409 54 12/2/2024
0.0.1-alpha-202411301019 55 11/30/2024
0.0.1-alpha-202411170525 56 11/17/2024
0.0.1-alpha-202411161308 54 11/16/2024
0.0.1-alpha-202411131604 56 11/13/2024
0.0.1-alpha-202411111439 67 11/11/2024
0.0.1-alpha-202411051434 53 11/5/2024
0.0.1-alpha-202410281339 56 10/28/2024
0.0.1-alpha-202410131500 59 10/13/2024
0.0.1-alpha-202407261457 67 7/26/2024
0.0.1-alpha-202407261325 60 7/26/2024
0.0.1-alpha-202406271301 61 6/27/2024
0.0.1-alpha-202406251508 60 6/25/2024
0.0.1-alpha-202406251310 59 6/25/2024
0.0.1-alpha-202406141611 60 6/14/2024
0.0.1-alpha-202406141550 57 6/14/2024
0.0.1-alpha-202406121515 58 6/12/2024
0.0.1-alpha-202406061553 67 6/6/2024
0.0.1-alpha-202406041519 60 6/4/2024
0.0.1-alpha-202406011613 63 6/1/2024
0.0.1-alpha-202406011238 65 6/1/2024
0.0.1-alpha-202405311458 57 5/31/2024
0.0.1-alpha-202405291213 70 5/29/2024
0.0.1-alpha-202405190457 62 5/19/2024
0.0.1-alpha-202405161229 54 5/16/2024
0.0.1-alpha-202405141510 57 5/14/2024
0.0.1-alpha-202405101323 66 5/10/2024
0.0.1-alpha-202405081356 69 5/8/2024
0.0.1-alpha-202405021337 30 5/2/2024
0.0.1-alpha-202405021336 32 5/2/2024
0.0.1-alpha-202405020452 46 5/2/2024
0.0.1-alpha-202405011443 53 5/1/2024
0.0.1-alpha-202404291541 64 4/29/2024
0.0.1-alpha-202404281218 61 4/28/2024