业务缓存

业务缓存减少重复查询，但不改变数据所有权、权限判断或业务事务。Java 使用带环境前缀的 Redis 命名空间，而非把所有业务对象放进一个可任意清理的键空间。

已缓存内容

监控分组	内容	TTL
site-settings	站点公开/管理配置及相关策略	300 秒
menus	管理菜单、用户菜单与按钮	300 秒
api-permissions	有效角色显式 API 授权快照	300 秒
system-params	启用参数快照	86400 秒
dicts	字典查询，含筛选和分页条件	300 秒

这些分组由缓存监控白名单控制。Redis 总 keyCount 包含登录态、版本键等，不等于业务缓存数量。

页面数据没有更新时怎么处理

先确认修改请求业务码成功，再重新查询相关页面。若仍是旧值，在缓存监控中查看对应业务分组，只清理这个分组，然后再次查询。系统参数也提供自己的刷新缓存入口，需要相应接口权限。

例如站点名称修改后仍显示旧值，先查 site-settings 的失效日志、当前 Redis 库和环境前缀；不要把整个 Redis 清空，因为其中还有会话与任务锁。手动清理成功后，下次读取会回源并重新填充缓存。

读取、写入与失效

写入成功后清理相关空间，有事务时在提交后执行；事务回滚不失效。事务内查询绕过共享缓存，避免读到旧值或发布未提交状态。

清理先更新命名空间版本，再分批扫描/删除。填充时验证版本，防止清理前开始的慢查询将旧结果重新写回；已经读取到值的进行中请求仍可能返回旧结果。

空集合可缓存，null 不缓存。JSON 按声明的具体类型恢复，不启用 AutoType。新增缓存先明确类型、键参数、TTL 与写入后失效关系。

Redis 故障时

情况	当前行为
业务缓存查询或填充故障	查询回源
手动清理故障	明确返回错误
提交后自动清理故障	记录警告，不把已提交业务改报失败
自动清理未完成	没有持久化重试补偿，可能持续到 TTL；恢复后可手动清理
登录共享状态故障	不退化为本机登录态

不能把“缓存回源”推广为所有 Redis 用途都可忽略故障。任务锁、登录态、临时凭证与验证码分别遵循自己的失败策略。

权限与环境隔离

敏感 API 按有效角色实时鉴权，缓存快照用于前端体验，不作为后端放行依据。

art.cache.key-prefix 同时隔离业务缓存、登录态、验证码、下载凭证与任务锁。不同部署使用不同 Redis 库/前缀；同一部署各节点必须一致。Java 与 Nest.js 不共用序列化缓存。

切换库或前缀会使旧会话与临时凭证不可读，也会创建新锁空间。先排空任务、协调全部实例配置后再切换，不在两个锁空间并行运行同一业务任务。

修改和排查入口

先看业务读取 Service 的缓存注解、失效声明，再看 cache 域与 art-common-redis。站点或角色变更后页面陈旧时，核对写入是否提交、失效日志、命名空间和 TTL，不直接清空整个 Redis。

验证覆盖读取命中、参数区分、事务回滚、提交后失效、Redis 故障及并发旧值回填。随包深入说明见 docs/guides/business-cache.md。