@h-ai/cache

统一缓存模块，通过 cache 对象提供 KV / Hash / List / Set / ZSet / 分布式锁 操作，支持内存与 Redis 两种后端。

适用场景

• 开发/测试场景下的内存缓存
• 生产环境 Redis 缓存（单机、URL、集群、哨兵）
• IAM 会话与权限相关的集合缓存
• 分布式锁（多节点部署互斥控制）

快速开始

import { cache, HaiCacheError } from '@h-ai/cache'

const initResult = await cache.init({ type: 'memory' })
if (!initResult.success) {
  throw new Error(initResult.error.message)
}

await cache.kv.set('user:1', { name: '张三' }, { ex: 3600 })
const user = await cache.kv.get<{ name: string }>('user:1')

await cache.hash.hset('profile:1', { age: 18, city: 'Hangzhou' })
await cache.list.lpush('queue:jobs', 'job-1', 'job-2')
await cache.set_.sadd('role:admin:perms', 'user.read', 'user.write')
await cache.zset.zadd('rank', { member: 'u1', score: 100 })

// 分布式锁
const acquired = await cache.lock.acquire('my-lock', { ttl: 30, owner: 'node-1' })
if (acquired.success && acquired.data) {
  try {
    // 执行受保护的操作
  }
  finally {
    await cache.lock.release('my-lock', 'node-1')
  }
}

if (!user.success && user.error.code === HaiCacheError.NOT_INITIALIZED.code) {
  // 请先调用 cache.init()
}

await cache.close()

初始化配置

// Memory（开发/测试）
await cache.init({ type: 'memory' })

// Redis 单机
await cache.init({
  type: 'redis',
  host: 'localhost',
  port: 6379,
  password: 'secret',
  db: 0,
})

// Redis URL（优先级最高）
await cache.init({
  type: 'redis',
  url: 'redis://:password@localhost:6379/0',
})

// Redis 集群
await cache.init({
  type: 'redis',
  cluster: [
    { host: 'node1', port: 6379 },
    { host: 'node2', port: 6379 },
  ],
})

// Redis 哨兵
await cache.init({
  type: 'redis',
  sentinel: {
    sentinels: [{ host: 'sentinel1', port: 26379 }],
    name: 'mymaster',
  },
})

API 概览

• cache.kv: 字符串/对象键值与 TTL（set/get/mget/mset/expire/ttl/...）
• cache.hash: 哈希结构（hset/hget/hgetall/...）
• cache.list: 列表结构（lpush/rpush/lpop/rpop/...）
• cache.set_: 集合结构（sadd/smembers/sismember/...）
• cache.zset: 有序集合（zadd/zrange/zrevrange/...）
• cache.lock: 分布式锁（acquire/release/isLocked/extend）

分布式锁

基于 SET NX EX 模式实现的分布式互斥锁，适用于多节点部署场景。

// 获取锁（TTL 30 秒，owner 用于标识持有者）
const acquired = await cache.lock.acquire('my-lock', { ttl: 30, owner: 'node-1' })
if (acquired.success && acquired.data) {
  try {
    // 执行受保护操作
  }
  finally {
    await cache.lock.release('my-lock', 'node-1')
  }
}

// 检查锁状态
const locked = await cache.lock.isLocked('my-lock')

// 续期锁
await cache.lock.extend('my-lock', 60, 'node-1')

• Memory 后端：基于 Map + TTL 过期机制
• Redis 后端：使用 SET NX EX 原子获锁，Lua 脚本实现 owner 验证的安全释放/续期
• owner 参数用于防止误释放他人锁，多节点部署时建议设置稳定的节点标识

错误码

所有操作返回 HaiResult<T>，常用错误码如下：

| 错误码 | code | 说明 | | -------------------------------------- | --------------- | ---------------- | | HaiCacheError.CONNECTION_FAILED | hai:cache:001 | 连接失败 | | HaiCacheError.OPERATION_FAILED | hai:cache:002 | 操作失败 | | HaiCacheError.SERIALIZATION_FAILED | hai:cache:003 | 序列化失败 | | HaiCacheError.DESERIALIZATION_FAILED | hai:cache:004 | 反序列化失败 | | HaiCacheError.KEY_NOT_FOUND | hai:cache:005 | 键不存在 | | HaiCacheError.TIMEOUT | hai:cache:006 | 超时 | | HaiCacheError.NOT_INITIALIZED | hai:cache:010 | 未初始化 | | HaiCacheError.UNSUPPORTED_TYPE | hai:cache:011 | 不支持的缓存类型 | | HaiCacheError.CONFIG_ERROR | hai:cache:012 | 配置错误 |

测试

pnpm --filter @h-ai/cache test

Redis 相关测试需要 Docker 环境。

License

Apache-2.0