Sparkdo.IdGeneration.Abstractions 3.0.0-preview.1

Sparkdo.IdGeneration.Abstractions

Sparkdo.IdGeneration.Abstractions 是 Id 生成能力的稳定公共契约包：一个泛型生成器接口、三个按 Id 类型专用的接口、一个按类型/名称解析的 provider 接口，以及 capability identity。零依赖（纯 BCL）、零服务注册、无扩展方法——引用它只声明「我要用 Id 生成器」，不绑定任何算法、DI 容器或锁实现。

默认实现与接线在 Sparkdo.IdGeneration（UUID v7 / ULID）和 Sparkdo.IdGeneration.Snowflake（Snowflake long）；只需要面向接口编程的库（ORM 包装、领域层、多租户组件）引用本包即可。

契约一览

全部类型位于命名空间 Sparkdo.IdGeneration。

IIdGenerator<TId>

public interface IIdGenerator<out TId>
{
    TId Create();
}

三个专用接口

IGuidGenerator / IStringIdGenerator / ILongIdGenerator 都是空标记接口，只做一件事：给 DI 一个按 Id 类型区分的唯一服务键。同一类型可能有多种实现（string 可以是 ULID，也可以是随机串；long 可以是 Snowflake，也可以是数据库号段），因此「类型级默认」用专用接口表达，「具名备选」用 keyed IIdGenerator<TId> 表达。

默认运行时包同时注册专用接口与泛型接口两种服务形态（IGuidGenerator 与 IIdGenerator<Guid> 是两条独立描述符，因此是两个各自的 Singleton 实例，而不是同一实例的两个别名），所以调用方可以任选注入方式；替换实现时两处都要覆盖才彻底，见下节。

IIdGeneratorProvider

public interface IIdGeneratorProvider
{
    IIdGenerator<TId> Get<TId>(string? name = null);
}

var ids = serviceProvider.GetRequiredService<IIdGeneratorProvider>();

var a = ids.Get<Guid>().Create();
var b = ids.Get<Guid>("GUID").Create();     // 与 a 同一个实例
var c = ids.Get<int>("order-no").Create();  // keyed IIdGenerator<int>，实现由应用提供

用内置名注册 keyed 生成器是无效操作：AddKeyedSingleton<IIdGenerator<Guid>>(..., "guid") 永远不会被 Get<Guid>("guid") 读到（该名称被短路到 IGuidGenerator）。自定义名称请避开 guid、ulid、snowflake（大小写变体同样避开）。

默认实现解析的是接口而不是具体类：provider 不检查实现类型，也不缓存解析结果；long 的解析依赖 Sparkdo.IdGeneration.Snowflake 包是否注册了 ILongIdGenerator，未注册时抛 DI 标准的 InvalidOperationException（"No service for type ..."），与「名称未命中」的 KeyNotFoundException 是两类故障，排查时据此区分。

IdGenerationCapability

public static class IdGenerationCapability
{
    public const string Id = "Sparkdo.IdGeneration";
}

capability 的稳定标识，供需要声明「本组件依赖 Id 生成能力」的清单、诊断或组合根使用。它是常量而不是枚举：值不随包版本变化，三个运行时包共用同一个 Id。

面向实现者的备注

• 只提供契约：本包不含实现、不含 DI 扩展、不引用 Microsoft.Extensions.*。引用它不会让容器多出任何服务。
• Create() 里禁止 I/O、禁止 Task.Wait/.Result、禁止 sleep 等待时钟。需要异步准备就把准备动作放进独立的生命周期钩子（参考 SnowflakeWorkerStartupTask 的做法）。
• 建议保持 fail closed：前提不成立时抛异常，而不是返回可能重复或降质的 Id。默认实现的行为基线是「宁可拒绝生成，也不生成可疑 Id」。
• 若实现是 Singleton，必须无共享可变状态或用锁保护（SnowflakeIdState 用单把锁保护 sequence 与逻辑时间）。
• 想让自定义实现顶掉默认实现，请在调用 AddSparkdoIdGeneration() / AddSparkdoIdGenerationSnowflake() 之前注册（两个 Add 方法全部 TryAdd）；泛型形态 IIdGenerator<TId> 与专用接口形态是两个独立描述符，需要分别覆盖。
• 契约全部 AOT / trimming 友好：无反射、无动态代码、无 params/装箱热点。

边界

• 不承诺 Id 的不可预测性、不承诺同毫秒单调、不承诺跨进程唯一性由接口保证——这些属于具体实现（见 Sparkdo.IdGeneration 与 Sparkdo.IdGeneration.Snowflake 的 README）。
• 不提供异步生成器接口（CreateAsync）、不提供批量 CreateMany、不提供 Id 解析工具方法。
• 不含 worker id 分配 SPI（ISnowflakeWorkerIdProvider）与 SnowflakeWorkerLease——它们随 Snowflake 实现包发布，属于该实现的可替换点。

安装

dotnet add package Sparkdo.IdGeneration.Abstractions

需要默认实现与 DI 接线时改引用 Sparkdo.IdGeneration（已含对本包的传递引用）。

本文即包内 README.md（PackageReadmeFile，实测随 nupkg 发布），并与 Sparkdo.IdGeneration.Abstractions.xml 一起提供 IntelliSense。因此文中只以包名明文引用其他包，不使用相对路径链接；验证命令见域根 README（dotnet test src/id-generation/Sparkdo.IdGeneration.slnx）。