distlock

package
v0.3.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 20 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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 双向判定补丁随之失去存在 必要,已删除。

View Source
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。

func (*EtcdLocker) TryLock

func (l *EtcdLocker) TryLock(ctx context.Context, key string, ttl time.Duration) (string, error)

TryLock 非阻塞尝试获取锁:新建 Session(租约 ttl + 自动续约)后 Mutex.TryLock。

func (*EtcdLocker) Unlock

func (l *EtcdLocker) Unlock(ctx context.Context, key, ownerID string) error

Unlock 释放锁:ownerID 须与本进程持有记录一致;释放后 Session 关闭回收租约。

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。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL