Sparkdo.DistributedLocking.Abstractions 3.0.0-preview.1

Sparkdo.DistributedLocking.Abstractions

分布式锁的契约包：零依赖（不引用任何 Sparkdo 包、不引用第三方包、不注册任何服务），只定义「获取 → 持有 → 续租 → 释放」的语义边界与类型形状，供进程内 provider、Redis provider 与自研后端共同遵循。业务代码只依赖本包即可保持后端无关。

契约包不承诺任何互斥强度——互斥由 provider 实现保证，业务用 IDistributedLock.Provider 判定当前接线够不够用。

该引用哪个包

只引用本包时容器里不会注册任何服务：IDistributedLock 无人实现，解析即失败。

契约地图

IDistributedLock：两种重载怎么选

便捷重载只定等待，不定租约：TryAcquireAsync(name, timeout) 内部用默认租约 30 秒且不自动续租。超过 30 秒的工作若用这个重载，会在你继续写入时静默失锁——长任务必须改用 options 重载。

返回值与异常的分工：

• null = 锁被占用且等待超时耗尽，这是正常分支，不是异常；
• OperationCanceledException = 等待期间 cancellationToken 触发；既有持有者不受任何影响（实测：取消等待后原持有者 IsLost=false、锁仍在手）；
• ArgumentException = name 为 null、空串或全空白；
• ArgumentNullException = options 为 null；
• ArgumentOutOfRangeException = 选项字段非法（见下）。

IDistributedLockHandle：一次持有权

状态机：持有中 →（DisposeAsync）已释放 或（租约到期 / 续租失败 / 后端报告失锁）已失效。两个终态都不可逆，句柄不会自动重新取得锁，也不会替你重新排队。

句柄的四条使用契约（违反任何一条都会破坏互斥）：

1. 必须由成功获取的一方释放：await using 或显式 await handle.DisposeAsync()；
2. 不得注册为 DI 单例——单例会永久持有一次持有权；
3. 不得跨请求缓存句柄；
4. 不得把同一句柄交给多个 owner（DisposeAsync 幂等只意味着重复释放安全，不意味着共享安全）。

三个失锁信号的分工（判断「现在还能不能继续写」用第一个）：

TryRenewAsync 参数与结果：

Redis provider 的续租会在服务端 CAS 之前用注入时钟做一次本地预检：GetUtcNow() >= ExpiresAt 即直接判失锁、不发命令；因此本地时钟大幅快于服务端会提前失锁（把租约设长或信任 ExpiresAt 来自服务端这一事实）。

DistributedLockAcquisitionOptions

校验发生在任何后端动作之前：非法选项不会留下半截持锁。契约不设租约时长上限——超过定时器实现上限（约 49.7 天）的租约照样可用，provider 会截断定时器 dueTime 而不是抛异常；但 LeaseDuration 大到到期时间不可表示时（如 TimeSpan.MaxValue）仍然会抛 ArgumentOutOfRangeException，而这一步发生在持有权已经到手之后，所以 provider 必须先归还持有权再原样抛出（本域两个内置实现都这么做）。

DistributedLockAcquisitionOptions 是 init-only record：可以安全地作为常量对象在多次获取间复用（provider 只读不改）。

DistributedLockRenewalResult

provider 作者在「无法确认持有」时必须返回 Lost() 而不是抛通信异常——这是 fail-closed 的落点（宁可丢锁，不可双持）。

IDistributedLockKeyNormalizer

实现契约：确定性纯映射。相同输入在同一配置下必须得到相同键，结果不得随调用次数、时间、随机数或持有者身份变化。

public sealed class TenantScopedLockKeyNormalizer(LockContext context) : IDistributedLockKeyNormalizer
{
    public string NormalizeKey(string name)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(name);
        return $"tenant:{context.CurrentTenantId}:{name}";   // 同一持锁请求内必须稳定
    }
}

映射本身可以读环境（租户、命名空间），但同一个 name 在同一配置/同一作用域内必须始终得到同一个键。禁止的做法：为键附加 nonce/时间戳（会让同名的两次获取落在不同键上，互斥直接失效）、返回与 name 无关的常量（所有锁互相阻塞）、抛非 ArgumentException 的异常。DefaultDistributedLockKeyNormalizer（在 Sparkdo.DistributedLocking 包）只做 KeyPrefix + name 拼接。

DistributedLockProviderInfo 与能力门禁

Provider 不是展示信息，是业务侧唯一的强度判据：

if (distributedLock.Provider.IsProcessLocal && !options.AllowProcessLocalWorkerLease)
{
    throw new InvalidOperationException(
        $"worker lease 需要跨进程协调：当前 provider '{distributedLock.Provider.Name}' 仅进程内互斥。");
}

真实消费方是 Sparkdo.IdGeneration.Snowflake 的 DistributedLockSnowflakeWorkerIdProvider——它会因进程内 provider 而拒绝启动，除非显式允许。

语义矩阵（provider 无关，两个内置实现一致，测试守卫）

自研 provider 的实现清单

1. Provider 如实声明强度：只有真正跨进程协调才 IsProcessLocal=false；
2. 获取失败一律 null，只有用户取消才 OperationCanceledException；
3. 选项校验先于任何后端动作（不要留下无人认领的持锁）；
4. 句柄终态不可逆、DisposeAsync 幂等；失锁必须同时取消 LostToken；
5. 无法确认持有时续租返回 Lost()（不抛）；
6. 同键 FencingToken 严格递增；不能保证时必须在包文档写明重置条件；
7. ExpiresAt 优先取后端权威时钟，不可得时用注入的 TimeProvider；
8. 不做重入，不阻塞不同键；
9. DI 注册用 TryAdd 语义，让宿主可以先注册自己的实现覆盖；
10. 持有权已经到手之后的任何抛出路径（句柄构造、定时器编排、后端结果换算）都必须先归还持有权再原样抛出——绝不允许留下无人认领的锁；归还自身的异常不覆盖原始异常。

安装

dotnet add package Sparkdo.DistributedLocking.Abstractions

目标框架 net10.0;net11.0，Native AOT / trimming 兼容（契约包无反射、无运行时扫描）。通常不必直接引用——安装 Sparkdo.DistributedLocking 或 Sparkdo.DistributedLocking.Redis 会传递引入。