Sparkdo.DistributedLocking 3.0.0-preview.1

Sparkdo.DistributedLocking

Sparkdo.DistributedLocking 是分布式锁契约的进程内 provider 与 DI 组合包：每键一个信号量排队、可注入 TimeProvider 的租约与自动续租、默认键规范化器，以及 AddSparkdoDistributedLocking() 一行接线。它传递引入 Sparkdo.DistributedLocking.Abstractions。

单机多任务互斥开箱可用；跨进程/跨机器互斥请改用 Sparkdo.DistributedLocking.Redis（本包 Provider.IsProcessLocal == true，业务侧可据此拒绝）。

快速开始

using Microsoft.Extensions.DependencyInjection;
using Sparkdo.DistributedLocking;

var services = new ServiceCollection();
services.AddSparkdoDistributedLocking(options => options.KeyPrefix = "tenant-a:");
var provider = services.BuildServiceProvider();

var distributedLock = provider.GetRequiredService<IDistributedLock>();

await using var handle = await distributedLock.TryAcquireAsync(
    "orders:42",
    new DistributedLockAcquisitionOptions
    {
        WaitTimeout = TimeSpan.FromSeconds(5),       // 最多等 5 秒，等不到返回 null
        LeaseDuration = TimeSpan.FromMinutes(1),     // 租约 1 分钟
        AutoRenewalInterval = TimeSpan.FromSeconds(20), // 每 20 秒自动续租（必须 < 租约）
    });

if (handle is null)
{
    return;   // 锁被占用：降级、跳过或换键，不是异常
}

// 持锁执行。租约到期或续租失败时 LostToken 被取消，受保护的工作必须据此停止。
await DoWorkAsync(handle.LostToken);
if (handle.LostToken.IsCancellationRequested)
{
    // 已经失锁：本次结果不可信，按业务规则重试或放弃
}

不走 DI 时可直接构造（与容器内注册的实例同型）：

var normalizer = new DefaultDistributedLockKeyNormalizer(
    Microsoft.Extensions.Options.Options.Create(new DistributedLockingOptions { KeyPrefix = "tenant-a:" }));

IDistributedLock distributedLock = new InMemoryDistributedLock(normalizer);              // 系统时钟
IDistributedLock testable = new InMemoryDistributedLock(normalizer, myFakeTimeProvider); // 注入时钟

AddSparkdoDistributedLocking 注册了什么

services.AddSparkdoDistributedLocking();                    // 纯接线
services.AddSparkdoDistributedLocking(options => ...);      // 接线 + 追加默认 named options 配置

因为全部是 TryAdd：重复调用 AddSparkdoDistributedLocking() 幂等（容器里始终只有一个 IDistributedLock），宿主自己注册的实现永不被覆盖。要换成 Redis provider 用的不是「后注册覆盖」，而是 AddSparkdoRedisDistributedLock() 的显式 RemoveAll。

InMemoryDistributedLock 单实例服务全部锁键，必须是 singleton；把它注册成 scoped/transient 会让每个作用域各持一套信号量，互斥立刻失效。

进程内 provider 的逐项行为

用法要点

忘记释放的两种后果，取决于是否设置 AutoRenewalInterval：

前缀只作用于键，不作用于名字：配了 KeyPrefix = "tenant-a:" 后，TryAcquireAsync("orders") 与 TryAcquireAsync("tenant-a:orders") 落在两个不同键上，互相不阻塞（实测两者都能拿到）；handle.Name 始终是传入的原始名。多租户/多应用共用一套 provider 时，前缀是唯一隔离入口，但同一进程内的前缀只能有一份（默认 IDistributedLockKeyNormalizer 只读 DistributedLockingOptions.KeyPrefix）。

测试可直接推进虚拟时钟，不需要真实等待：

var clock = new FakeTimeProvider(DateTimeOffset.UnixEpoch);      // 任何 TimeProvider 实现
var distributedLock = new InMemoryDistributedLock(normalizer, clock);
var handle = await distributedLock.TryAcquireAsync("orders",
    new DistributedLockAcquisitionOptions { LeaseDuration = TimeSpan.FromSeconds(10) });

clock.Advance(TimeSpan.FromSeconds(10));

handle!.IsLost.ShouldBeTrue();                                    // 到期即失锁
var next = await distributedLock.TryAcquireAsync("orders");       // 非 null：槽位已让出

同一个 TimeProvider 也决定了 TryRenewAsync 的本地预检，所以「到期后续租报 Lost」这类用例完全确定性。

选项

KeyPrefix 在 DefaultDistributedLockKeyNormalizer 构造时读取一次并冻结；宿主用 IOptionsMonitor 热更新前缀不会影响已注册的 singleton provider——需要动态前缀请实现自己的 IDistributedLockKeyNormalizer。

替换与扩展

边界与非目标

• 只在当前进程内互斥：Provider.IsProcessLocal == true，多实例部署必须换 Redis provider；
• 进程退出即丢失全部持锁状态，没有持久化、没有恢复、没有崩溃后的租约接管；
• 不可重入：同键第二次获取只会排队或超时，句柄上也没有「再加一层」的 API；
• 不区分持有者身份：同进程任何代码路径都能在持锁者释放后拿到锁，不提供线程/请求归属校验；
• 不保证等待公平性与唤醒顺序，也不提供优先级继承；
• ExpiresAt 与续租全部来自本地时钟，没有服务端权威。

异常一览

获取失败（锁被占用）返回 null，不是异常。

安装

dotnet add package Sparkdo.DistributedLocking

目标框架 net10.0;net11.0，IsAotCompatible + trimming 兼容；包内无运行时扫描、无反射序列化。