外观
Store 重点文件与方法
用于选择数据接口、核对重载和实现扩展。数据示例见数据操作，缓存回源见查询结果缓存，并发控制见锁与限流。
本页按重点文件查阅方法；表内方法名可打开源码。重载共享的约束写在表前，差异在各行说明。源码链接固定到核对版本，接入前提见快速开始。
StoreTemplate
源码：StoreTemplate。
一个模板固定命名空间和 Codec；注入 StoreClient 后创建模板，不要每次请求随机创建命名空间。五类数据使用独立类型空间，Atomic 不使用值 Codec。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| namespace() | 返回当前 StoreNamespace，便于确认键所属应用和模块。 | 同一逻辑键只有在命名空间、类型均相同的情况下才共享数据。 |
| codec() | 返回 StoreCodec<T>，编码模板中的 T。 | 跨服务读写必须使用兼容的编码协议。 |
| value() | 返回 ValueStore<T>，存单值。 | 切换接口不会迁移已有数据。 |
| map() | 返回 MapStore<T>，按 String 字段存值。 | TTL 属于整个 Map。 |
| set() | 返回 SetStore<T>，按编码结果去重。 | 不保证迭代顺序。 |
| list() | 返回 ListStore<T>，按位置存值。 | 下标从 0 开始。 |
| atomic() | 返回 AtomicStore，读写 long 计数器。 | 独立于 T；缺失值读取为 0。 |
| scanKeys() | 返回惰性 Iterable<StoreKey>，等价于 scanKeys("*")。 | 只扫描五类数据，不含锁和限流键。 |
| scanKeys(String pattern) | 按 glob 逐类型扫描；每项给出 type() 和 key()。 | 不是一致性快照，可能重复；应逐项处理，不全量收集到内存。 |
KeyStore
源码：KeyStore。
五类数据接口共同继承的键生命周期契约。key 必须非 null 且非空白；底层 TTL 必须为正 Duration。多个调用不组成事务。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| exists(String key) | 返回当前类型空间是否存在该键。 | 空集合在本地与 Redis 的留键行为不同，判断内容请用 size。 |
| delete(String key) | 删除整键；删除成功 true，缺失 false。 | Map 字段、Set/List 成员一并删除；不会删除其他类型的同名键。 |
| expire(String key, Duration ttl) | 为已有键设置相对有效期；不存在 false。 | 不能通过 expire 创建键；写入后设置过期存在两步之间的失败窗口。 |
| expireAt(String key, Instant deadline) | 未来时刻转换为 TTL；时间已到时直接 delete。 | deadline=null 抛 IllegalArgumentException；返回值沿用 expire/delete。 |
| keys(String pattern) | 返回有限 Set<String>，默认请求 1000 条。 | 仍受 scan-max-results 上限限制，不适合完整导出。 |
| keys(String pattern, int limit) | 按 glob 返回最多限制数量的逻辑键。 | limit 需为正数；无排序保证。 |
| scanKeys() | 惰性扫描全部本类型逻辑键，等价于 "*"。 | 不受 keys 的结果数量上限约束。 |
| scanKeys(String pattern) | 按 glob 惰性遍历。 | 接口默认抛 UnsupportedOperationException；内置两种后端提供实现，自定义后端需覆盖。 |
ValueStore
源码：ValueStore。
保存非 null 的单值。内置后端的条件删除比较编码字节；同样的业务对象必须编码稳定，才能用于比较。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| set(String key, T value) | 覆盖写入，不设过期。 | 会清除旧 TTL，临时数据应选带 ttl 的重载。 |
| set(String key, T value, Duration ttl) | 覆盖值并指定有效期。 | ttl 必须正数；不要把 DataCache 的非法 TTL 规则套到这里。 |
| get(String key) | 返回解码后的 T；不存在返回 null。 | 读取不续期；解码错误可能向外抛出。 |
| getAndDelete(String key) | 原子读取并删除，返回旧值或 null。 | 适合临时值一次性领取，不具备消息确认和重投。 |
| compareAndDelete(String key, T expected) | 仅当存储字节匹配 expected 的编码时删除；返回是否删除。 | 内置后端支持；接口默认不支持。可防止坏缓存清理误删并发新值。 |
MapStore
源码：MapStore。
field 不能空白，值不能 null；整表及字段/值集合是不可写回的结果，修改要调用存储方法。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| get(String key) | 返回全部字段和值；缺失为空 Map。 | 整键一次性加载，无顺序保证。 |
| get(String key, String field) | 读取单字段；缺失返回 null。 | 不创建键、不续期。 |
| put(String key, String field, T value) | 新增或覆盖一个字段，无返回值。 | 已有集合 TTL 不主动刷新。 |
| putAll(String key, Map<String,T> values) | 合并所有字段，同名字段覆盖。 | 不是整表替换；需要替换时显式编排删除与写入，并考虑并发。 |
| remove(String key, String field) | 删除一个字段，返回实际是否移除。 | 不删除其他字段。 |
| contains(String key, String field) | 判断字段存在；缺失 false。 | 先 contains 再 put 不是原子条件写入。 |
| size(String key) | 返回 long 字段数量，缺失 0。 | 数量可能随并发修改变化。 |
| fields(String key) | 返回字段 Set，缺失为空集合。 | 不能通过修改返回值写回。 |
| values(String key) | 返回值 Collection，缺失为空集合。 | 不同字段可持有相同值，不去重。 |
SetStore
源码：SetStore。
以编码结果判断成员是否相同。集合无顺序，读取结果不可修改；整集合共享 TTL。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| members(String key) | 返回全部成员 Set<T>，缺失为空。 | 读取开销随成员数增长。 |
| add(String key, T value) | 新增一个非 null 成员，返回是否新增。 | 重复成员返回 false。 |
| addAll(String key, Collection<T> values) | 批量新增，返回实际新增 long 数量。 | 输入中的重复值不会增加计数。 |
| contains(String key, T value) | 判断成员是否存在。 | 不是业务授权判断。 |
| remove(String key, T value) | 移除单成员，返回是否移除。 | 缺失 false，不报“记录不存在”。 |
| removeAll(String key, Collection<T> values) | 移除多个成员，返回实际移除数量。 | 不是删除整个键。 |
| size(String key) | 返回成员 long 数量，缺失 0。 | 跨调用读取不保证同一快照。 |
ListStore
源码：ListStore。
列表下标从 0 开始。range 的边界为左闭右开且必须满足 0 <= from <= to <= size，越界抛 IndexOutOfBoundsException；不按 Redis LRANGE 的负下标或自动截断规则使用。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| get(String key) | 返回全部元素 List<T>；缺失为空列表。 | 结果不可变，列表很大时改用 range。 |
| range(String key, int fromInclusive, int toExclusive) | 返回指定半开区间。 | 缺失键只有 [0,0) 合法；Redis 长度检查和读取之间可能被并发改变。 |
| get(String key, int index) | 返回指定位置元素。 | 越界抛异常，不返回 null。 |
| set(String key, int index, T value) | 替换指定位置元素。 | 不自动扩容或追加；value 非 null。 |
| addFirst(String key, T value) | 头部追加单值。 | 改变后续所有下标。 |
| addLast(String key, T value) | 尾部追加单值。 | 不主动刷新旧 TTL。 |
| addAllFirst(String key, Collection<T> values) | 整批按输入迭代顺序插到头部。 | [a,b] 得到 a,b,原元素，不是 b,a。 |
| addAllLast(String key, Collection<T> values) | 按输入顺序追加到尾部。 | 不等于可靠消息入队。 |
| pollFirst(String key) | 移除并返回头元素，空列表 null。 | 非阻塞，不等待新元素。 |
| pollLast(String key) | 移除并返回尾元素，空列表 null。 | 消费后没有失败重试。 |
| remove(String key, int index) | 按下标移除并返回旧值。 | Integer 类型模板传 int 时优先落入此重载。 |
| remove(String key, T value) | 移除首个编码相同的值，返回 boolean。 | 删除 Integer 值时使用 Integer.valueOf，避免误选下标重载。 |
| contains(String key, T value) | 判断列表是否含该编码值。 | 不要用于大列表高频检索。 |
| size(String key) | 返回 long 长度，缺失 0。 | 读取后不能假定下标一直有效。 |
AtomicStore
源码：AtomicStore。
保存 long；缺失键按 0 读取。递增带 TTL 的内置实现先更新计数再设置过期，所以设置失败时计数可能已经变化。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| get(String key) | 读取当前计数，缺失 0。 | 0 不能区分未创建与真实零值。 |
| getAndIncrement(String key) | 递增 1，返回更新前值。 | 首次返回 0。 |
| getAndIncrement(String key, Duration ttl) | 递增并刷新 TTL，返回旧值。 | 每次续期，调用前自行校验 ttl。 |
| incrementAndGet(String key) | 递增 1，返回更新后值。 | 首次返回 1。 |
| incrementAndGet(String key, Duration ttl) | 递增并刷新 TTL，返回新值。 | 不适合作为固定窗口的直接替代。 |
| compareAndSet(String key, long expect, long update, Duration ttl) | 当前计数等于 expect 才更新并设置 TTL，返回是否成功。 | 缺失按 0 比较；比较失败时本地可能留下零值键。接口默认不支持，内置后端已覆盖。 |
DataCacheUtil
源码：DataCacheUtil。
注入此 Bean 对数据库查询做 JSON 缓存。构造器接收 StoreTemplate<String> 与 StoreLockManager，第三个 boolean 参数控制 enabled，二参数构造默认 true。所有参数对象必须有效；查询类型用 Class<T> 表达，复杂嵌套泛型不能仅靠原始 Class 保留。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| DataCacheUtil(StoreTemplate<String> storeTemplate, StoreLockManager lockManager) | 手动构造启用缓存的实例。 | 通常由自动配置提供；锁后端和数据后端的共享范围应一致。 |
| DataCacheUtil(StoreTemplate<String> storeTemplate, StoreLockManager lockManager, boolean enabled) | 显式控制缓存是否启用。 | false 时仍校验调用参数，但直接回源，不读写缓存。 |
| get(String key, Supplier<T> supplier, Class<T> clazz, Consumer<ValueStore<String>> expirationAction) | 读缓存，未命中时加键锁并二次读取，再回源；非 null 结果才写入。 | 坏 JSON 条件删除后重新回源；过期回调抛异常会条件删除刚写的数据并重新抛出。 |
| list(String key, Supplier<List<T>> supplier, Class<T> clazz, Consumer<ValueStore<String>> expirationAction) | 按元素类型解析 JSON 数组；未命中流程同 get。 | null 和空列表不缓存，连续空查询仍会回源。 |
| delete(String key) | 启用时删除缓存值，返回 void。 | 禁用时不清理旧值；业务更新后由应用主动失效。 |
DataCacheObjectUtil
DataCacheUtil 实现的便捷重载；缓存键必须包含影响结果的用户/租户、筛选条件和数据类型，避免同键返回错误对象。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| get(String key, Supplier<T> supplier, Class<T> clazz) | 命中直接返回，未命中回源；无过期回调。 | 写入后为永久缓存，需要显式 delete。 |
| get(String key, Supplier<T> supplier, Class<T> clazz, Duration duration) | 正 duration 才设置相对过期。 | null、0、负数退化为永久缓存，不会抛底层 TTL 错误。 |
| get(String key, Supplier<T> supplier, Class<T> clazz, LocalDateTime expireTime) | 用 JVM 默认时区转为 Instant，写入后设置绝对截止时间。 | null 抛异常；截止时间已过时仍返回回源数据，但缓存随即删除。 |
| get(String key, Supplier<T> supplier, Class<T> clazz, Consumer<ValueStore<String>> expirationAction) | 由调用者对 ValueStore 设置过期策略。 | 回调只在回源数据被写入后执行；命中不续期。 |
DataCacheListUtil
DataCacheUtil 实现的便捷重载；缓存键必须包含影响结果的用户/租户、筛选条件和数据类型，避免同键返回错误对象。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| list(String key, Supplier<List<T>> supplier, Class<T> clazz) | 命中直接返回，未命中回源；无过期回调。 | 写入后为永久缓存，需要显式 delete。 |
| list(String key, Supplier<List<T>> supplier, Class<T> clazz, Duration duration) | 正 duration 才设置相对过期。 | null、0、负数退化为永久缓存，不会抛底层 TTL 错误。 |
| list(String key, Supplier<List<T>> supplier, Class<T> clazz, LocalDateTime expireTime) | 用 JVM 默认时区转为 Instant，写入后设置绝对截止时间。 | null 抛异常；截止时间已过时仍返回回源数据，但缓存随即删除。 |
| list(String key, Supplier<List<T>> supplier, Class<T> clazz, Consumer<ValueStore<String>> expirationAction) | 由调用者对 ValueStore 设置过期策略。 | 回调只在回源数据被写入后执行；命中不续期。 |
StoreLockManager
源码：StoreLockManager。
使用作用域方法包住同步业务，退出作用域时释放锁。Runnable 不返回业务结果，Supplier<T> 返回 action.get() 的 T。action 抛出的异常向外传播；锁不提供数据库事务，也不能保护在 action 中启动后立即返回的异步任务。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| withLock(String key, Runnable action) | 按后端默认等待策略取得单键锁后执行；返回 void。 | 默认等待策略见后端配置。键必须非空白。 |
| withLock(String key, Supplier<T> action) | 按后端默认等待策略取得单键锁后执行；返回业务结果 T。 | 默认等待策略见后端配置。键必须非空白。 |
| withLock(String key, Duration waitTime, Runnable action) | 等待至限定时间并取得单键锁后执行；返回 void。 | 超时抛 StoreLockException。键必须非空白。 |
| withLock(String key, Duration waitTime, Supplier<T> action) | 等待至限定时间并取得单键锁后执行；返回业务结果 T。 | 超时抛 StoreLockException。键必须非空白。 |
| withLocks(Collection<String> keys, Runnable action) | 按后端默认等待策略取得全部键锁后执行；返回 void。 | 默认等待策略见后端配置。多键去重后按字典序获取、逆序释放。 |
| withLocks(Collection<String> keys, Supplier<T> action) | 按后端默认等待策略取得全部键锁后执行；返回业务结果 T。 | 默认等待策略见后端配置。多键去重后按字典序获取、逆序释放。 |
| withLocks(Collection<String> keys, Duration waitTime, Runnable action) | 等待至限定时间并取得全部键锁后执行；返回 void。 | 超时抛 StoreLockException。多键去重后按字典序获取、逆序释放。 |
| withLocks(Collection<String> keys, Duration waitTime, Supplier<T> action) | 等待至限定时间并取得全部键锁后执行；返回业务结果 T。 | 超时抛 StoreLockException。多键去重后按字典序获取、逆序释放。 |
| tryWithLock(String key, Duration waitTime, Runnable action) | 拿到锁后执行并返回 true，超时返回 false 且不执行 action。 | waitTime 必须为正；不能把业务 action 抛异常当作 false。 |
| tryWithLocks(Collection<String> keys, Duration waitTime, Runnable action) | 全部锁成功才执行一次 action；waitTime 是整组共享预算。 | 集合非空，键逐一校验；失败释放已持有的锁，不能按每个键重新计算等待预算。 |
StoreRateLimiterManager
先配置额度策略，再申请正数 permits；同一个 key 对应一条策略。它控制调用速率，不替代身份或业务配额持久化。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| configure(String key, RateLimitPolicy policy) | 注册或更新该键的许可数和周期。 | 相同策略重复配置保留已有状态；策略改变时重建/重置额度。本地是平滑速率，Redis 使用共享周期额度，见锁与限流页。 |
| tryAcquire(String key, long permits) | 立即申请额度，成功 true，额度不足 false。 | 没有配置、参数非法或后端故障不是普通的 false；本地 permits 不得超过 Integer.MAX_VALUE。 |
| acquire(String key, long permits) | 阻塞等待额度，取得后返回 void。 | 可能长时间占用请求线程，实时接口优先使用 tryAcquire。 |
一次完整调用
以下片段放入已经注入 StoreTemplate<String> store、StoreLockManager locks 的业务方法，import 使用 java.time.Duration。
java
locks.withLock("job:42", Duration.ofSeconds(2), () -> {
store.value().set("job:42:state", "ready", Duration.ofMinutes(5));
});
String state = store.value().get("job:42:state"); // 未过期且没有并发覆盖时为 ready
boolean claimed = store.value().compareAndDelete("job:42:state", "ready");这里锁保护设置状态的同步调用；条件删除独立保证只删除匹配值。两者都不证明下载文件已生成或数据库已提交。完整接入配置见快速开始。