服务缓存接入

规则 CORE-CACHE-001。2026-09-19 对照同步与响应式缓存源码。

选择运行时

两套模块含同包同名契约，分别用于独立运行时。不能将阻塞缓存引入响应式应用作为复用手段。

声明缓存

Service 的可选缓存能力由 IServiceCache.getServiceCacheSpec() 提供；默认返回 null，表示不启用。规格由 ServiceCacheSpec 描述缓存名称及各读取能力开关。

源码：IServiceCache、ServiceCacheSpec。

接入步骤：确认查询适合缓存 → 提供明确 cache name 和规格 → 确认运行时实际有 cache/store → 检查标准读取能力与自定义方法的注解 → 确认全部写入口的失效范围 → 验证隔离与回滚。

自定义只读方法使用 @ServiceCacheable 时仍要满足 Service 策略与 Spring 代理条件；@ServiceCacheEvict 用于成功写入后的失效。同步标准 CRUD、账户、状态及排序 Service 写方法也使用该注解，清理当前目标租户登记的缓存 key；业务覆盖标准方法或新增写动作时需保留对应失效声明，避免用 @CacheEvict(allEntries=true) 替换。自调用不会自动经过代理。

Key 与权限

Core 缓存包含租户隔离契约。业务仍需判断结果是否还依赖用户、角色、数据范围、语言等条件；有租户 key 不等于所有个性化查询都安全。无法稳定表达授权上下文的结果，优先不缓存。

不要用另一个模块的 cache name，也不要在绕过 Service 的仓储写入后假定缓存一定失效。自定义写动作必须被纳入失效测试。

提交与回滚

同步 ServiceCacheAfterCommitCoordinator在有事务时协调提交后失效；回滚不执行该提交动作，无事务时在方法成功返回后执行。REQUIRES_NEW 挂起外层失效批次，内层提交独立失效，再恢复外层批次；外层回滚不能吞掉已提交内层的失效。

响应式 ReactiveServiceCacheAfterCommitCoordinator组合源 Publisher 与响应式事务同步。未订阅不得执行缓存工作。

事务成功后缓存失效仍可能失败；这不等于数据库回滚。业务应根据一致性要求设计重试、告警或补偿，不能把本地缓存接口当作可靠消息系统。

验证

同租户命中、不同租户隔离、写后失效、事务内不提前失效、回滚保留原缓存、无事务行为、响应式未订阅无动作。可运行依据：提交后协调测试、缓存注解集成测试。这些测试不代表已连接生产 Redis。

标准默认方法的真实代理验证见 StandardServiceCacheTransactionTest：覆盖外层事务、提交前旧值回填、回滚、其他租户保留、Service 自身事务和 REQUIRES_NEW。测试采用默认 Spring 事务 Advisor 顺序；应用若自定义 Advisor 顺序，应让事务拦截器包住缓存失效拦截器（事务 order 数值更小），并运行同类传播测试。独立事务的四种提交/回滚组合见 RequiresNewCacheEvictionTest，使用真实 H2 事务。