@h-ai/cache 1.0.0-beta.2 → 1.0.0-beta.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +202 -35
- package/README.ja.md +233 -68
- package/README.md +234 -69
- package/dist/index.d.ts +2 -1
- package/dist/index.js +258 -89
- package/dist/index.js.map +1 -1
- package/package.json +8 -8
package/README.md
CHANGED
|
@@ -4,36 +4,9 @@
|
|
|
4
4
|
|
|
5
5
|
[框架首页](../../README.md) · 相关模块:[@h-ai/core](../core/README.md)
|
|
6
6
|
|
|
7
|
-
## 简介
|
|
8
|
-
|
|
9
7
|
统一缓存模块,通过 `cache` 对象提供 KV / Hash / List / Set / ZSet / 分布式锁 操作,支持内存与 Redis 两种后端。
|
|
10
8
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
初始化只在健康检查成功后发布连接;失败时释放候选资源。若清理仍失败,初始化错误的 `error.ext.cleanupPending` 为 `true`。`cache.close()` 返回 `Promise<HaiResult<void>>`,等待正在进行的初始化,并合并并发关闭。开始清理后 `isInitialized` 为 `false`,配置与业务操作不再可用;清理失败仍保留资源,后续 `close()` 或 `init()` 先重试释放,成功前不会创建替代连接。调用方必须检查关闭结果。
|
|
14
|
-
|
|
15
|
-
```ts
|
|
16
|
-
const closed = await cache.close()
|
|
17
|
-
if (!closed.success) {
|
|
18
|
-
// 处理清理故障后有限重试;再次失败应向应用报告。
|
|
19
|
-
const retried = await cache.close()
|
|
20
|
-
if (!retried.success)
|
|
21
|
-
throw new Error(retried.error.message)
|
|
22
|
-
}
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
Redis 的 QUIT 失败后会强制 disconnect;只有实际释放成功才报告关闭成功。
|
|
26
|
-
|
|
27
|
-
## 核心功能清单
|
|
28
|
-
|
|
29
|
-
- 开发/测试场景下的内存缓存
|
|
30
|
-
- 生产环境 Redis 缓存(单机、URL、集群、哨兵)
|
|
31
|
-
- IAM 会话与权限相关的集合缓存
|
|
32
|
-
- 分布式锁(多节点部署互斥控制)
|
|
33
|
-
|
|
34
|
-
## 使用入门
|
|
35
|
-
|
|
36
|
-
### 快速开始
|
|
9
|
+
## 快速开始
|
|
37
10
|
|
|
38
11
|
```ts
|
|
39
12
|
import { cache } from '@h-ai/cache'
|
|
@@ -61,49 +34,187 @@ finally {
|
|
|
61
34
|
|
|
62
35
|
`cache.config` 返回的是**脱敏后的配置快照**:如后续接入 Redis `password` / `url` 等凭证字段,会自动做安全处理,不应用作回写原始密钥。
|
|
63
36
|
|
|
64
|
-
|
|
37
|
+
## 功能
|
|
38
|
+
|
|
39
|
+
内存 KV 在到期时间点即视为失效;`incr/decr/incrBy/decrBy` 只接受安全整数数值或整数字符串,非法增量和溢出返回 `OPERATION_FAILED` 并保留原值。Hash 的 `__proto__` / `constructor` 等名称按普通字段保留,不修改返回对象原型。
|
|
40
|
+
|
|
41
|
+
Memory 的 KV、Hash、List、Set、ZSet 共用 key 命名空间。`exists/expire/expireAt/ttl/persist/keys/scan/del/type` 覆盖全部结构,期限到达后结构操作也立即视为不存在;del 按实际删除的逻辑 key 计数,错误类型的结构操作返回失败。
|
|
42
|
+
|
|
43
|
+
初始化只在健康检查成功后发布连接;失败时释放候选资源。若清理仍失败,初始化错误的 `error.ext.cleanupPending` 为 `true`。`cache.close()` 返回 `Promise<HaiResult<void>>`,等待正在进行的初始化,并合并并发关闭。开始清理后 `isInitialized` 为 `false`,配置与业务操作不再可用;清理失败仍保留资源,后续 `close()` 或 `init()` 先重试释放,成功前不会创建替代连接。调用方必须检查关闭结果。
|
|
65
44
|
|
|
66
45
|
```ts
|
|
67
|
-
|
|
68
|
-
|
|
46
|
+
const closed = await cache.close()
|
|
47
|
+
if (!closed.success) {
|
|
48
|
+
// 处理清理故障后有限重试;再次失败应向应用报告。
|
|
49
|
+
const retried = await cache.close()
|
|
50
|
+
if (!retried.success)
|
|
51
|
+
throw new Error(retried.error.message)
|
|
52
|
+
}
|
|
53
|
+
```
|
|
69
54
|
|
|
70
|
-
|
|
71
|
-
await cache.init({
|
|
72
|
-
type: 'redis',
|
|
73
|
-
host: 'localhost',
|
|
74
|
-
port: 6379,
|
|
75
|
-
password: 'secret',
|
|
76
|
-
db: 0,
|
|
77
|
-
})
|
|
55
|
+
Redis 的 QUIT 失败后会强制 disconnect;只有实际释放成功才报告关闭成功。
|
|
78
56
|
|
|
79
|
-
|
|
80
|
-
await cache.init({
|
|
81
|
-
type: 'redis',
|
|
82
|
-
url: 'redis://:password@localhost:6379/0',
|
|
83
|
-
})
|
|
57
|
+
### 功能输入输出
|
|
84
58
|
|
|
85
|
-
|
|
86
|
-
await cache.init({
|
|
87
|
-
type: 'redis',
|
|
88
|
-
cluster: [
|
|
89
|
-
{ host: 'node1', port: 6379 },
|
|
90
|
-
{ host: 'node2', port: 6379 },
|
|
91
|
-
],
|
|
92
|
-
})
|
|
59
|
+
以下片段依赖本节完整初始化流程。示例中的业务值由宿主校验和授权后传入;异步领域结果先判断 success,再读取 data。表中 void 表示操作已完成且没有返回数据,null 表示不存在;同步工厂/工具直接返回表中类型。
|
|
93
60
|
|
|
94
|
-
|
|
95
|
-
await cache.init({
|
|
96
|
-
type: 'redis',
|
|
97
|
-
sentinel: {
|
|
98
|
-
sentinels: [{ host: 'sentinel1', port: 26379 }],
|
|
99
|
-
name: 'mymaster',
|
|
100
|
-
},
|
|
101
|
-
})
|
|
102
|
-
```
|
|
61
|
+
key/keys 是业务键,field/fields 是哈希字段,value/members 为 JSON 值;start/stop/index 为下标,min/max 为分数边界;seconds/ttl/timeout 为秒,timestamp 为 Unix 秒;owner 只能使用 acquire 返回值。
|
|
103
62
|
|
|
104
|
-
|
|
63
|
+
#### cache.kv
|
|
105
64
|
|
|
106
|
-
|
|
65
|
+
缓存 JSON 快照。get/mget 返回值或 null(批量保序);set 输入期限/NX/XX,返回实际写入 boolean;mset 接收 [key,value][] 返回 void。
|
|
66
|
+
|
|
67
|
+
| 入口 | 输入参数 | 成功结果 | 调用示例 |
|
|
68
|
+
| --------------- | ------------------- | --------------- | ---------------------------------------------------------- |
|
|
69
|
+
| `cache.kv.get` | key | `T \| null` | `await cache.kv.get('u:1')` |
|
|
70
|
+
| `cache.kv.set` | key, value, options | `boolean` | `await cache.kv.set('u:1', { name: 'Alice' }, { ex: 60 })` |
|
|
71
|
+
| `cache.kv.mget` | keys | `(T \| null)[]` | `await cache.kv.mget('u:1', 'u:2')` |
|
|
72
|
+
| `cache.kv.mset` | entries | `void` | `await cache.kv.mset([['u:1', { name: 'Alice' }]])` |
|
|
73
|
+
|
|
74
|
+
#### cache.kv
|
|
75
|
+
|
|
76
|
+
跨节点版本提交。key、expected、value 加期限选项原子比较后返回 applied;undefined 代表不存在/删除,比较失败不改原值或 TTL。
|
|
77
|
+
|
|
78
|
+
| 入口 | 输入参数 | 成功结果 | 调用示例 |
|
|
79
|
+
| ------------------------- | ----------------------------- | --------- | ------------------------------------------------ |
|
|
80
|
+
| `cache.kv.compareAndSwap` | key, expected, value, options | `boolean` | `await cache.kv.compareAndSwap('version', 1, 2)` |
|
|
81
|
+
|
|
82
|
+
#### cache.kv
|
|
83
|
+
|
|
84
|
+
按 key 管理全部数据结构;del/exists 输入一个或多个键,返回删除/存在数;type 输入单键返回结构类型。
|
|
85
|
+
|
|
86
|
+
| 入口 | 输入参数 | 成功结果 | 调用示例 |
|
|
87
|
+
| ----------------- | -------- | -------- | ------------------------------------- |
|
|
88
|
+
| `cache.kv.del` | keys | `number` | `await cache.kv.del('u:1', 'u:2')` |
|
|
89
|
+
| `cache.kv.exists` | keys | `number` | `await cache.kv.exists('u:1', 'u:2')` |
|
|
90
|
+
| `cache.kv.type` | key | `string` | `await cache.kv.type('u:1')` |
|
|
91
|
+
|
|
92
|
+
#### cache.kv
|
|
93
|
+
|
|
94
|
+
控制保存期限;相对秒数、Unix 秒数或键分别设置/查询/移除 TTL。修改返回 boolean,ttl 返回秒数(-1 无期限、-2 不存在)。
|
|
95
|
+
|
|
96
|
+
| 入口 | 输入参数 | 成功结果 | 调用示例 |
|
|
97
|
+
| ------------------- | -------------- | --------- | -------------------------------------------------------------------- |
|
|
98
|
+
| `cache.kv.expire` | key, seconds | `boolean` | `await cache.kv.expire('u:1', 60)` |
|
|
99
|
+
| `cache.kv.expireAt` | key, timestamp | `boolean` | `await cache.kv.expireAt('u:1', Math.floor(Date.now() / 1000) + 60)` |
|
|
100
|
+
| `cache.kv.ttl` | key | `number` | `await cache.kv.ttl('u:1')` |
|
|
101
|
+
| `cache.kv.persist` | key | `boolean` | `await cache.kv.persist('u:1')` |
|
|
102
|
+
|
|
103
|
+
#### cache.kv
|
|
104
|
+
|
|
105
|
+
计数器输入 key 和可选整数增量,返回新安全整数;类型不符或溢出失败且不修改原值。
|
|
106
|
+
|
|
107
|
+
| 入口 | 输入参数 | 成功结果 | 调用示例 |
|
|
108
|
+
| ----------------- | -------------- | -------- | ----------------------------------- |
|
|
109
|
+
| `cache.kv.incr` | key | `number` | `await cache.kv.incr('hits')` |
|
|
110
|
+
| `cache.kv.incrBy` | key, increment | `number` | `await cache.kv.incrBy('hits', 2)` |
|
|
111
|
+
| `cache.kv.decr` | key | `number` | `await cache.kv.decr('stock')` |
|
|
112
|
+
| `cache.kv.decrBy` | key, decrement | `number` | `await cache.kv.decrBy('stock', 2)` |
|
|
113
|
+
|
|
114
|
+
#### cache.kv
|
|
115
|
+
|
|
116
|
+
运维遍历。keys 接收 glob 返回键数组;scan 接收不透明游标和 match/count,返回 [新游标,键数组],不保证快照或无重复。
|
|
117
|
+
|
|
118
|
+
| 入口 | 输入参数 | 成功结果 | 调用示例 |
|
|
119
|
+
| --------------- | --------------- | -------------------- | -------------------------------------------------------- |
|
|
120
|
+
| `cache.kv.keys` | pattern | `string[]` | `await cache.kv.keys('u:*')` |
|
|
121
|
+
| `cache.kv.scan` | cursor, options | `[string, string[]]` | `await cache.kv.scan('0', { match: 'u:*', count: 100 })` |
|
|
122
|
+
|
|
123
|
+
#### cache.hash
|
|
124
|
+
|
|
125
|
+
字段缓存输入 key、field/fields/对象或增量。读取返回值/null、对象、字段/值数组或长度;hset/hdel 返回新增/删除数,hexists 返回 boolean,hincrBy 返回新整数。
|
|
126
|
+
|
|
127
|
+
| 入口 | 输入参数 | 成功结果 | 调用示例 |
|
|
128
|
+
| -------------------- | --------------------- | --------------- | ----------------------------------------------- |
|
|
129
|
+
| `cache.hash.hget` | key, field | `T \| null` | `await cache.hash.hget('u:1', 'name')` |
|
|
130
|
+
| `cache.hash.hset` | key, field, value | `number` | `await cache.hash.hset('u:1', 'name', 'Alice')` |
|
|
131
|
+
| `cache.hash.hdel` | key, fields | `number` | `await cache.hash.hdel('u:1', 'name')` |
|
|
132
|
+
| `cache.hash.hexists` | key, field | `boolean` | `await cache.hash.hexists('u:1', 'name')` |
|
|
133
|
+
| `cache.hash.hgetall` | key | `T` | `await cache.hash.hgetall('u:1')` |
|
|
134
|
+
| `cache.hash.hkeys` | key | `string[]` | `await cache.hash.hkeys('u:1')` |
|
|
135
|
+
| `cache.hash.hvals` | key | `T[]` | `await cache.hash.hvals('u:1')` |
|
|
136
|
+
| `cache.hash.hlen` | key | `number` | `await cache.hash.hlen('u:1')` |
|
|
137
|
+
| `cache.hash.hmget` | key, fields | `(T \| null)[]` | `await cache.hash.hmget('u:1', 'name', 'age')` |
|
|
138
|
+
| `cache.hash.hincrBy` | key, field, increment | `number` | `await cache.hash.hincrBy('u:1', 'visits', 1)` |
|
|
139
|
+
|
|
140
|
+
#### cache.list
|
|
141
|
+
|
|
142
|
+
有序队列输入 key、值、索引/区间;push 返回长度,pop/index 返回值/null,range 返回数组,set/trim 返回 void。阻塞 pop 输入秒数与键,返回 [key,value]/null。
|
|
143
|
+
|
|
144
|
+
| 入口 | 输入参数 | 成功结果 | 调用示例 |
|
|
145
|
+
| ------------------- | ----------------- | --------------------- | ------------------------------------------------- |
|
|
146
|
+
| `cache.list.lpush` | key, values | `number` | `await cache.list.lpush('jobs', 'job-1')` |
|
|
147
|
+
| `cache.list.rpush` | key, values | `number` | `await cache.list.rpush('jobs', 'job-2')` |
|
|
148
|
+
| `cache.list.lpop` | key | `T \| null` | `await cache.list.lpop('jobs')` |
|
|
149
|
+
| `cache.list.rpop` | key | `T \| null` | `await cache.list.rpop('jobs')` |
|
|
150
|
+
| `cache.list.llen` | key | `number` | `await cache.list.llen('jobs')` |
|
|
151
|
+
| `cache.list.lrange` | key, start, stop | `T[]` | `await cache.list.lrange('jobs', 0, 9)` |
|
|
152
|
+
| `cache.list.lindex` | key, index | `T \| null` | `await cache.list.lindex('jobs', 0)` |
|
|
153
|
+
| `cache.list.lset` | key, index, value | `void` | `await cache.list.lset('jobs', 0, 'replacement')` |
|
|
154
|
+
| `cache.list.ltrim` | key, start, stop | `void` | `await cache.list.ltrim('jobs', 0, 99)` |
|
|
155
|
+
| `cache.list.blpop` | timeout, keys | `[string, T] \| null` | `await cache.list.blpop(5, 'jobs')` |
|
|
156
|
+
| `cache.list.brpop` | timeout, keys | `[string, T] \| null` | `await cache.list.brpop(5, 'jobs')` |
|
|
157
|
+
|
|
158
|
+
#### cache.set_
|
|
159
|
+
|
|
160
|
+
去重/集合运算。key+成员用于增删/成员判定,返回数量/boolean;members 返回数组,card 返回基数,random/pop 按 count 返回成员/数组/null,交并差接收多个键返回数组。
|
|
161
|
+
|
|
162
|
+
| 入口 | 输入参数 | 成功结果 | 调用示例 |
|
|
163
|
+
| ------------------------ | ------------ | ------------------ | ----------------------------------------------- |
|
|
164
|
+
| `cache.set_.sadd` | key, members | `number` | `await cache.set_.sadd('roles', 'editor')` |
|
|
165
|
+
| `cache.set_.srem` | key, members | `number` | `await cache.set_.srem('roles', 'editor')` |
|
|
166
|
+
| `cache.set_.smembers` | key | `T[]` | `await cache.set_.smembers('roles')` |
|
|
167
|
+
| `cache.set_.sismember` | key, member | `boolean` | `await cache.set_.sismember('roles', 'editor')` |
|
|
168
|
+
| `cache.set_.scard` | key | `number` | `await cache.set_.scard('roles')` |
|
|
169
|
+
| `cache.set_.srandmember` | key, count | `T \| T[] \| null` | `await cache.set_.srandmember('roles', 2)` |
|
|
170
|
+
| `cache.set_.spop` | key, count | `T \| T[] \| null` | `await cache.set_.spop('roles', 1)` |
|
|
171
|
+
| `cache.set_.sinter` | keys | `T[]` | `await cache.set_.sinter('roles:a', 'roles:b')` |
|
|
172
|
+
| `cache.set_.sunion` | keys | `T[]` | `await cache.set_.sunion('roles:a', 'roles:b')` |
|
|
173
|
+
| `cache.set_.sdiff` | keys | `T[]` | `await cache.set_.sdiff('roles:a', 'roles:b')` |
|
|
174
|
+
|
|
175
|
+
#### cache.zset
|
|
176
|
+
|
|
177
|
+
排行榜输入成员及 score、排序范围或分数范围;新增/删除返回数量,score/rank 返回数字/null,range 返回成员或带分数对象数组,incrBy 返回新分数,card/count 返回数量。
|
|
178
|
+
|
|
179
|
+
| 入口 | 输入参数 | 成功结果 | 调用示例 |
|
|
180
|
+
| ----------------------------- | ---------------------------- | ----------------------- | ------------------------------------------------------------------------- |
|
|
181
|
+
| `cache.zset.zadd` | key, members | `number` | `await cache.zset.zadd('scores', { member: 'u1', score: 10 })` |
|
|
182
|
+
| `cache.zset.zrem` | key, members | `number` | `await cache.zset.zrem('scores', 'u1')` |
|
|
183
|
+
| `cache.zset.zscore` | key, member | `number \| null` | `await cache.zset.zscore('scores', 'u1')` |
|
|
184
|
+
| `cache.zset.zrank` | key, member | `number \| null` | `await cache.zset.zrank('scores', 'u1')` |
|
|
185
|
+
| `cache.zset.zrevrank` | key, member | `number \| null` | `await cache.zset.zrevrank('scores', 'u1')` |
|
|
186
|
+
| `cache.zset.zrange` | key, start, stop, withScores | `string[] \| ZMember[]` | `await cache.zset.zrange('scores', 0, 9, true)` |
|
|
187
|
+
| `cache.zset.zrevrange` | key, start, stop, withScores | `string[] \| ZMember[]` | `await cache.zset.zrevrange('scores', 0, 9, true)` |
|
|
188
|
+
| `cache.zset.zrangeByScore` | key, min, max, options | `string[] \| ZMember[]` | `await cache.zset.zrangeByScore('scores', 10, 100, { withScores: true })` |
|
|
189
|
+
| `cache.zset.zcard` | key | `number` | `await cache.zset.zcard('scores')` |
|
|
190
|
+
| `cache.zset.zcount` | key, min, max | `number` | `await cache.zset.zcount('scores', 10, 100)` |
|
|
191
|
+
| `cache.zset.zincrBy` | key, increment, member | `number` | `await cache.zset.zincrBy('scores', 5, 'u1')` |
|
|
192
|
+
| `cache.zset.zremRangeByRank` | key, start, stop | `number` | `await cache.zset.zremRangeByRank('scores', 0, 9)` |
|
|
193
|
+
| `cache.zset.zremRangeByScore` | key, min, max | `number` | `await cache.zset.zremRangeByScore('scores', 0, 10)` |
|
|
194
|
+
|
|
195
|
+
#### cache.lock
|
|
196
|
+
|
|
197
|
+
短期互斥。acquire 输入键/TTL 返回 owner 或 null;release/extend 必须传 owner,返回 boolean;isLocked 仅观察占用。锁不替代业务存储的 CAS。
|
|
198
|
+
|
|
199
|
+
| 入口 | 输入参数 | 成功结果 | 调用示例 |
|
|
200
|
+
| --------------------- | --------------- | ---------------- | ------------------------------------------------ |
|
|
201
|
+
| `cache.lock.acquire` | key, options | `string \| null` | `await cache.lock.acquire('daily', { ttl: 30 })` |
|
|
202
|
+
| `cache.lock.release` | key, owner | `boolean` | `await cache.lock.release('daily', owner)` |
|
|
203
|
+
| `cache.lock.isLocked` | key | `boolean` | `await cache.lock.isLocked('daily')` |
|
|
204
|
+
| `cache.lock.extend` | key, ttl, owner | `boolean` | `await cache.lock.extend('daily', 60, owner)` |
|
|
205
|
+
|
|
206
|
+
#### cache
|
|
207
|
+
|
|
208
|
+
健康检查,无参数;返回后端响应字符串,连接故障为失败。
|
|
209
|
+
|
|
210
|
+
| 入口 | 输入参数 | 成功结果 | 调用示例 |
|
|
211
|
+
| ------------ | -------- | -------- | -------------------- |
|
|
212
|
+
| `cache.ping` | 无参数 | `string` | `await cache.ping()` |
|
|
213
|
+
|
|
214
|
+
- 开发/测试场景下的内存缓存
|
|
215
|
+
- 生产环境 Redis 缓存(单机、URL、集群、哨兵)
|
|
216
|
+
- IAM 会话与权限相关的集合缓存
|
|
217
|
+
- 分布式锁(多节点部署互斥控制)
|
|
107
218
|
|
|
108
219
|
### API 概览
|
|
109
220
|
|
|
@@ -165,7 +276,65 @@ if (acquired.success && acquired.data)
|
|
|
165
276
|
|
|
166
277
|
owner 只保护锁的续期与释放,不是资源 fencing token。进程暂停或租约到期后旧任务仍能继续;最终写入必须在资源存储中使用 CAS、代际条件或事务约束。续租成功或最后返回失败都不能代替提交条件。
|
|
167
278
|
|
|
168
|
-
###
|
|
279
|
+
### 生产共享状态
|
|
280
|
+
|
|
281
|
+
生产仅使用 Redis(含 Cluster);memory 只用于开发/明确测试。Redis 故障返回失败,不回退本机缓存。 NODE_ENV 或 HAI_CORE_ENV 为 production 时在初始化发布成功前校验;仅 HAI_E2E=1/HAI_E2E_MOCK=1 明确测试可豁免。 [状态、并发和恢复边界](../../.agents/instructions/distributed-state.md).
|
|
282
|
+
|
|
283
|
+
## 配置
|
|
284
|
+
|
|
285
|
+
生命周期:init 输入后端/业务配置,成功后才能使用;close 在释放借用依赖前等待完成。返回值以快速开始示例和公开签名为准。
|
|
286
|
+
|
|
287
|
+
```ts
|
|
288
|
+
// Memory(开发/测试)
|
|
289
|
+
await cache.init({ type: 'memory' })
|
|
290
|
+
|
|
291
|
+
// Redis 单机
|
|
292
|
+
await cache.init({
|
|
293
|
+
type: 'redis',
|
|
294
|
+
host: 'localhost',
|
|
295
|
+
port: 6379,
|
|
296
|
+
password: 'secret',
|
|
297
|
+
db: 0,
|
|
298
|
+
})
|
|
299
|
+
|
|
300
|
+
// Redis URL(优先级最高)
|
|
301
|
+
await cache.init({
|
|
302
|
+
type: 'redis',
|
|
303
|
+
url: 'redis://:password@localhost:6379/0',
|
|
304
|
+
})
|
|
305
|
+
|
|
306
|
+
// Redis 集群
|
|
307
|
+
await cache.init({
|
|
308
|
+
type: 'redis',
|
|
309
|
+
cluster: [
|
|
310
|
+
{ host: 'node1', port: 6379 },
|
|
311
|
+
{ host: 'node2', port: 6379 },
|
|
312
|
+
],
|
|
313
|
+
})
|
|
314
|
+
|
|
315
|
+
// Redis 哨兵
|
|
316
|
+
await cache.init({
|
|
317
|
+
type: 'redis',
|
|
318
|
+
sentinel: {
|
|
319
|
+
sentinels: [
|
|
320
|
+
{ host: 'sentinel1', port: 26379 }
|
|
321
|
+
],
|
|
322
|
+
name: 'mymaster',
|
|
323
|
+
},
|
|
324
|
+
})
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
内置后端由 `cache.init(config)` 选择 memory/redis;Provider 实现是内部契约,不提供自定义后端注册入口。
|
|
328
|
+
|
|
329
|
+
`password` 用于单机、Cluster 与 Sentinel 数据节点;Cluster 发现和重定向后的节点连接也携带密码。配置 `url` 时采用 URL 自身的认证信息,独立 password 字段不覆盖它。
|
|
330
|
+
|
|
331
|
+
配置由宿主加载和校验,再传入本模块;私密值放服务端私有环境,不传到浏览器。按实际使用场景逐项选择后端、容量、期限和日志策略,修改后重新初始化并核验成功结果。
|
|
332
|
+
|
|
333
|
+
[逐项配置说明、适用场景和示例](../../docs/usage/configuration/data.md).
|
|
334
|
+
|
|
335
|
+
## 错误处理
|
|
336
|
+
|
|
337
|
+
领域操作先判断 `result.success`,失败按本模块错误定义与安全提示处理,服务端保留错误码、关联编号和脱敏原因。同步工具、工厂、流迭代及生命周期按各自签名处理,不把 Promise 完成视为业务成功。具体失败与恢复边界见对应功能。
|
|
169
338
|
|
|
170
339
|
所有操作返回 `HaiResult<T>`,常用错误码如下:
|
|
171
340
|
|
|
@@ -181,10 +350,6 @@ owner 只保护锁的续期与释放,不是资源 fencing token。进程暂停
|
|
|
181
350
|
| `HaiCacheError.UNSUPPORTED_TYPE` | `hai:cache:011` | 不支持的缓存类型 |
|
|
182
351
|
| `HaiCacheError.CONFIG_ERROR` | `hai:cache:012` | 配置错误 |
|
|
183
352
|
|
|
184
|
-
## 生产共享状态
|
|
185
|
-
|
|
186
|
-
生产仅使用 Redis(含 Cluster);memory 只用于开发/明确测试。Redis 故障返回失败,不回退本机缓存。 NODE_ENV 或 HAI_CORE_ENV 为 production 时在初始化发布成功前校验;仅 HAI_E2E=1/HAI_E2E_MOCK=1 明确测试可豁免。 [状态、并发和恢复边界](../../.agents/instructions/distributed-state.md)。
|
|
187
|
-
|
|
188
353
|
## 开发测试
|
|
189
354
|
|
|
190
355
|
```bash
|
|
@@ -193,7 +358,7 @@ pnpm --filter @h-ai/cache test
|
|
|
193
358
|
|
|
194
359
|
> Redis 相关测试需要 Docker 环境。
|
|
195
360
|
|
|
196
|
-
公开契约与内部结构均提供可类型检查的示例;见[模块 JSDoc 约定](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证)
|
|
361
|
+
公开契约与内部结构均提供可类型检查的示例;见[模块 JSDoc 约定](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证).
|
|
197
362
|
|
|
198
363
|
## 许可证
|
|
199
364
|
|
package/dist/index.d.ts
CHANGED
|
@@ -668,4 +668,5 @@ interface CacheFunctions extends CacheCompositeOperations {
|
|
|
668
668
|
*/
|
|
669
669
|
declare const cache: CacheFunctions;
|
|
670
670
|
|
|
671
|
-
export {
|
|
671
|
+
export { CacheConfigSchema, HaiCacheError, MemoryConfigSchema, RedisClusterNodeSchema, RedisConfigSchema, RedisSentinelConfigSchema, cache };
|
|
672
|
+
export type { CacheCompositeOperations, CacheConfig, CacheConfigInput, CacheFunctions, CacheValue, CompareAndSwapOptions, HashOperations, KvOperations, ListOperations, LockOperations, LockOptions, RedisClusterNode, RedisSentinelConfig, ScanOptions, SetOperations, SetOptions, ZMember, ZSetOperations };
|