# Distributed lock 手册

`rs-zero` 的分布式锁用于跨进程协调短时临界区。第一版提供 Redis backend，使用 `SET key token NX PX ttl` 获取锁，并用 Lua 脚本校验 owner token 后删除，避免误删他人锁。

## Feature

```toml
rs-zero = { version = "0.2.1", default-features = false, features = ["cache-redis"] }
```

`cache-redis` 会同时启用 `cache` 与 `resil`，因此 Redis lock 可复用 Redis client、timeout、breaker 和低基数 Redis 指标。

## 基本用法

```rust
use std::time::Duration;

use rs_zero::lock::{DistributedLock, RedisDistributedLock, RedisLockConfig};

let lock = RedisDistributedLock::new(RedisLockConfig::default())?;
let guard = lock
    .try_acquire("order:{123}", Duration::from_secs(5))
    .await?;

// 执行业务临界区。

lock.release(&guard).await?;
```

如果锁已被其他 owner 持有，`try_acquire` 返回 `LockError::Busy`。如果希望自行处理竞争，可以使用 `acquire`：

```rust
if let Some(guard) = lock.acquire("order:{123}", Duration::from_secs(5)).await? {
    lock.release(&guard).await?;
}
```

## 配置

```rust
use std::time::Duration;

use rs_zero::{
    cache_redis::{RedisBreakerConfig, RedisCacheConfig},
    lock::{RedisDistributedLock, RedisLockConfig},
};

let lock = RedisDistributedLock::new(RedisLockConfig {
    redis: RedisCacheConfig {
        url: "redis://127.0.0.1:6379".to_string(),
        connect_timeout: Duration::from_secs(1),
        command_timeout: Duration::from_millis(500),
        ..RedisCacheConfig::default()
    },
    namespace: "order-service:lock".to_string(),
    command_timeout: Duration::from_millis(500),
    breaker: RedisBreakerConfig::go_zero_defaults(),
    ..RedisLockConfig::default()
})?;
```

规则：

- `namespace` 必须稳定，避免不同服务或环境共享锁空间。
- TTL 必须大于 0，禁止无过期锁。
- owner token 是随机值，不应写入日志、metrics label 或错误消息。
- 解锁只删除 token 匹配的锁；锁已过期或被新 owner 获取时，旧 guard release 会返回 `LockError::OwnerMismatch`。
- 默认不自动续租。业务临界区必须短于 TTL，并保留足够安全余量。

## Redis Cluster

Cluster 模式使用 `RedisCacheConfig.cluster.enabled = true`。分布式锁 key 默认要求包含 Redis hash tag：

```rust
let guard = lock.try_acquire("order:{123}", Duration::from_secs(5)).await?;
```

原因：获取锁和 Lua 解锁都必须访问同一个 Redis slot。不要使用没有 hash tag 的 Cluster lock key。确有兼容需求时可以关闭 `require_cluster_hash_tag`，但生产环境不推荐。

## 观测与韧性

Redis lock 复用 Redis command recorder：

- `LOCK_ACQUIRE` 记录获取锁命令耗时和结果。
- `LOCK_RELEASE` 记录释放锁命令耗时和结果。
- `LOCK_PING` 记录健康检查。
- breaker 事件走 Redis breaker event。

指标必须保持低基数：只记录 command、shard、result，不记录原始 lock key、owner token、URL、用户 ID 或业务参数。

## 生产边界

- 分布式锁不是数据库唯一约束、事务或幂等设计的替代品。
- Redis 单实例锁适合短时互斥；强一致协调场景优先考虑 etcd lease/txn 或数据库事务。
- 第一版不实现 Redlock，也不默认自动续租。
- 若锁保护外部资源写入，建议业务额外设计 fencing token 或版本号检查。
- Redis down、breaker open、timeout 都应作为明确错误处理，不要静默放行业务临界区。

## 验证

默认测试不依赖真实 Redis：

```bash
cargo test -p rs-zero --features cache-redis --test redis_lock
```

真实 Redis 验证走 opt-in：

```bash
scripts/external-integration.sh redis-lock
```
