Documentation
¶
Overview ¶
Package distlock 提供基于 etcd 的分布式锁,实现 github.com/oekit/pkg/distlock.Locker 后端中立契约(TryLock/Lock/Unlock + ownerID 语义,#123 契约单源),与 redisx/distlock 后端(迁移后)同类型 可互换,业务代码面向 Locker 接口编程即可。
跨后端错误面(#123 单源后) ¶
错误哨兵即 pkg/distlock 的契约哨兵(同值别名):ErrLockNotAcquired / ErrLockTimeout / ErrLockNotHeld(历史名 ErrNotOwner)——同一进程只此 一套值,适配层绑哪一侧哨兵做 errors.Is 分类都不漂移(429 不再变 500), 历史 #86/#112 的 sentinel.Is 同文案等价与 IsOneOf 双向判定补丁已随契约 单源删除。文案映射注意:ErrNotOwner 历史文案是 "lock not owned by this owner",契约单源后统一为 pkg 哨兵文案 "lock not held by this owner" (对外文案变化,见 changelog)。Unlock 对非持有者显式报 ErrLockNotHeld (redisx 侧同样在其 #115 对齐为显式报错),两侧不再一边静默一边报错。 机制级差异(亚秒 TTL 精度、降级放行面)见 Locker 类型注释的统一口径。
实现机制 ¶
- 每把锁独占一个 etcd Session(Lease + 自动续约):进程存活期间锁不会 因 TTL 到期丢失;进程崩溃后租约到期自动释放(ttl 即故障释放上限)
- 加锁走 clientv3/concurrency.Mutex(revision 公平排队,Lock 阻塞等待 前序持有者释放而非轮询)
- ownerID 由本进程生成并在 Unlock 时校验,防止错把他人的锁释放; 跨进程安全性由 etcd 租约与 Mutex 自身保证
- 可选「etcd 传输层不可达」时降级放行(单实例部署场景,默认关闭; 权限/参数等业务层错误不降级,见 WithGracefulDegradation)
快速接入 ¶
locker, err := distlock.NewEtcdLocker(cli, distlock.WithPrefix("myapp"))
if err != nil {
return err
}
err = distlock.WithLock(ctx, locker, "deploy:myapp:dev", 30*time.Second, 10*time.Second, func() error {
return doDeploy()
})
手动加解锁:
owner, err := locker.TryLock(ctx, "job:cleanup", 30*time.Second)
if errors.Is(err, distlock.ErrLockNotAcquired) { return } // 别人在跑
defer locker.Unlock(ctx, "job:cleanup", owner)
Index ¶
- Variables
- func WithLock(ctx context.Context, locker Locker, key string, ttl, timeout time.Duration, ...) error
- type EtcdLocker
- func (l *EtcdLocker) Close(ctx context.Context) error
- func (l *EtcdLocker) Lock(ctx context.Context, key string, ttl, timeout time.Duration) (string, error)
- func (l *EtcdLocker) TryLock(ctx context.Context, key string, ttl time.Duration) (string, error)
- func (l *EtcdLocker) Unlock(ctx context.Context, key, ownerID string) error
- type EtcdLockerOption
- type EtcdLockerOptionFunc
- type Locker
Constants ¶
This section is empty.
Variables ¶
var ( // ErrLockNotAcquired 表示锁被其他持有者占用,获取失败(TryLock 单次 // 未抢到,不是通信故障)。 ErrLockNotAcquired = pkgdistlock.ErrLockNotAcquired // ErrLockTimeout 表示在指定超时时间内未能获取锁。 ErrLockTimeout = pkgdistlock.ErrLockTimeout // ErrLockNotHeld 表示 Unlock 时锁不存在或已易主——本次 Unlock **没有 // 删除任何锁**(调用方不得继续假装持有)。契约名与 pkg/distlock、 // redisx/distlock 对齐。 ErrLockNotHeld = pkgdistlock.ErrLockNotHeld // ErrNotOwner 是 [ErrLockNotHeld] 的历史名(#123 哨兵映射):本包历史 // 哨兵文案 "lock not owned by this owner" 与 redisx 侧同语义哨兵文案 // 不同("lock not held by this owner"),是 #86/#112 补丁的根源之一。 // 契约单源后统一映射到 pkg 的 ErrLockNotHeld——**对外文案随之变为 // "lock not held by this owner"**(changelog BREAKING 注记),值身份 // 与 ErrLockNotHeld / pkg/distlock.ErrLockNotHeld 完全一致。 ErrNotOwner = pkgdistlock.ErrLockNotHeld )
哨兵错误集(#123 契约单源):本包不再 errors.New 自有哨兵,包级变量 **别名指向 github.com/oekit/pkg/distlock 的契约哨兵**——同一进程只此 一套值,errors.Is 跨包双向天然成立(errors.Is(etcdx.ErrLockTimeout, redisx.ErrLockTimeout) 与反方向都为 true,前提是 redisx 侧同样迁移), #86/#112 的 sentinel.Is 同文案等价与 IsOneOf 双向判定补丁随之失去存在 必要,已删除。
var ErrNilClient = errors.New("etcdx/distlock: client must be non-nil")
ErrNilClient 表示构造时传入了 nil 的 etcd client。
构造期 fail-fast:client 为 nil 时,首次加锁会在连接预检的 `cli.Get` 上 空指针崩溃——错误发生在**离构造点很远**的地方(往往是生产环境第一次抢锁 时),堆栈里只有 etcd 内部帧,看不出「是构造时没传 client」。构造期报错 把这道接线错误挡在启动阶段。
与 registry/nacosimpl 的 ErrNilClient 同口径。
Functions ¶
func WithLock ¶
func WithLock(ctx context.Context, locker Locker, key string, ttl, timeout time.Duration, fn func() error) error
WithLock 加锁 → 执行 fn → 自动释放的便捷包装(#123 契约单源:薄委托 github.com/oekit/pkg/distlock.WithLock,本包不再自持一份实现)。
获取锁失败(含 ErrLockTimeout)直接返回错误、fn 不执行;错误统一带 "lock <key>:" 前缀包装、哨兵经 %w 穿透(errors.Is 判定不丢)——与 redisx 侧口径一致(此前本包无包装,跨后端错误形态漂移)。
释放纪律统一为 pkg 单源的 pkgdistlock.ReleaseUncancelable 口径 (context.WithoutCancel):**持锁期 caller ctx 取消不吞释放动作**—— 解锁用与 caller 取消状态解耦、且保留 ctx 取值的 context。与历史实现 的差异(changelog BREAKING 注记):此前是 WithTimeout(Background, 3s) 的独立短超时 ctx(不携带 caller ctx 取值,3s 为魔法常数)。 释放失败只记日志不覆盖 fn 的返回值(租约到期兜底释放)。
Types ¶
type EtcdLocker ¶
type EtcdLocker struct {
// contains filtered or unexported fields
}
EtcdLocker 是基于 etcd Session + concurrency.Mutex 的分布式锁实现。
func NewEtcdLocker ¶
func NewEtcdLocker(cli *clientv3.Client, opts ...EtcdLockerOptionFunc) (*EtcdLocker, error)
NewEtcdLocker 创建 etcd 分布式锁。
client 为 nil 时返回 ErrNilClient(构造期 fail-fast,避免首次加锁时在 cli.Get 上空指针崩溃)。
func (*EtcdLocker) Close ¶
func (l *EtcdLocker) Close(ctx context.Context) error
Close 释放本进程持有的全部锁(幂等)。
func (*EtcdLocker) Lock ¶
func (l *EtcdLocker) Lock(ctx context.Context, key string, ttl, timeout time.Duration) (string, error)
Lock 阻塞获取锁(revision 公平排队),timeout 内未获得返回 ErrLockTimeout。 timeout≤0 为单次非阻塞尝试(与 redisx 对齐,#66):忙时返回 ErrLockTimeout。
type EtcdLockerOption ¶
type EtcdLockerOption struct {
Prefix string
GracefulDegradation bool
OnLock func(key string, acquired bool, err error)
// MaxHold 是单次持有的**最大持锁时长**(安全网,0 = 用默认 10×ttl,
// 负值 = 不限制)。
MaxHold time.Duration
}
EtcdLockerOption 配置 EtcdLocker 的可选参数。
type EtcdLockerOptionFunc ¶
type EtcdLockerOptionFunc func(*EtcdLockerOption)
EtcdLockerOptionFunc 配置函数类型。
func WithGracefulDegradation ¶
func WithGracefulDegradation() EtcdLockerOptionFunc
WithGracefulDegradation 开启「etcd 传输层不可达」时的降级放行:TryLock/Lock 直接返回成功(ownerID 带 "degraded:" 前缀)。
与 redisx/distlock 的同名选项统一口径(#63):那边只对「构造缺失 (client 为 nil)」放行;本包构造期即拒绝 nil client(ErrNilClient), 不存在该场景,对应放行面就是「运行期 etcd 传输层不可达」(连接拒绝/ 断开、gRPC Unavailable、拨号/请求超时)。**其余错误一律显式报错**: 权限/认证/参数/压缩等业务层故障 fail-open 会让多实例在故障窗口内同时 「拿到锁」并发进临界区,互斥静默失效。
即便对「不可达」放行也仅适用于单实例部署等互斥不关键的场景——多实例 下 etcd 重启窗口内各实例会同时降级放行,出现并发执行。
func WithMaxHold ¶ added in v0.2.2
func WithMaxHold(d time.Duration) EtcdLockerOptionFunc
WithMaxHold 设置单次持有的**最大持锁时长**(安全网,#36)。
与 redisx/distlock 的 `WithMaxAutoRenew` **对称**:忘记 Unlock 时, 到期后安全网会**停止续租**,锁在 TTL 后自然过期 ⇒ 不会形成 「永久持锁 + keepalive goroutine 泄漏」。
- 0(默认):10×ttl;
- 负值:不限制(兼容旧行为,需调用方保证 Unlock 一定被调用);
- 正值:显式上限。
实现用的是 etcd `Session.Orphan()`:它**停止 keepalive 但不撤销租约** ⇒ 租约在 TTL 后自然过期、键随之删除 ⇒ 语义与 redisx 侧 「续期到期后锁在 TTL 后自然过期」一致(不是立刻释放)。
func WithOnLock ¶
func WithOnLock(fn func(key string, acquired bool, err error)) EtcdLockerOptionFunc
WithOnLock 设置加锁结果回调(指标/日志钩子),在 TryLock/Lock 返回前同步调用。
func WithPrefix ¶
func WithPrefix(prefix string) EtcdLockerOptionFunc
WithPrefix 设置锁键命名空间:键形如 "/<prefix>/<key>"(默认 "/oekit/distlock")。
type Locker ¶
type Locker = pkgdistlock.Locker
Locker 是分布式锁接口(#123 契约单源):**类型别名**指向 github.com/oekit/pkg/distlock.Locker(TryLock/Lock/Unlock 三方法 + 哨兵契约,见该包文档)——etcdx 与 redisx 的 Locker 是同一个类型, 两个后端的实现可直接互换,业务代码面向本接口或 pkg/distlock.Locker 编程完全等价。
本后端的行为口径(契约层只定形状与哨兵;「方法集同形」之外的行为差异 逐条列明,不再宣称无条件的「换实现不改变行为」,#86):
- 哨兵即 pkg/distlock 哨兵(同值别名):ErrLockNotAcquired / ErrLockTimeout / ErrNotOwner(=ErrLockNotHeld) 与 redisx 侧(迁移后) 同一套值,errors.Is 判定不再有跨包身份分裂。
- Unlock 非持有者**显式报错**:返回 ErrLockNotHeld(历史名 ErrNotOwner); redisx 自其对齐修复(其 #115)起同样对非持有者显式报错而非静默 no-op——静默会让「锁没放掉」不可观测,调用方误以为已释放。
- ttl 必须为正:ttl≤0 直接报错(与 redisx 的 "ttl must be positive" 对齐,#62)——此前 etcdx 把零值/负值静默抬成 1s,同一份代码换后端 一个立刻报错、一个悄悄持 1s 锁。etcd 租约秒级精度,(0, 1s) 的亚秒 TTL 抬升至 1s 并记 Warn(redisx 毫秒精确,此处是机制差异)。
- Lock 的 timeout≤0 表示**单次非阻塞尝试**(与 redisx 对齐,#66): 成功或 ErrLockTimeout——redisx 的 Lock 先试一次再看 deadline,故 timeout=0 仍有一次尝试;此前 etcdx 用 WithTimeout(ctx, 0) 造出立即 过期的 ctx,一次都不试就 ErrLockTimeout。
- WithGracefulDegradation 的放行面(#63):redisx 仅对「构造缺失 (client 为 nil)」放行;etcdx 构造期即拒绝 nil client,不存在该 场景,对应放行面为「运行期 etcd 传输层不可达」。除该面外的一切 错误(权限/认证/参数/压缩/未知业务错)两后端都显式报错,绝不 fail-open。