受管注解缓存

受管注解缓存是 Forge Admin 在 forge-starter-cache 中提供的声明式 + 运行时治理缓存能力：开发者用注解声明缓存与代码默认策略，运维在管理后台按「缓存名 + 应用」覆盖运行策略（模式、TTL、容量、空值缓存），并受代码不可变安全边界约束。

核心概念

概念	说明
缓存定义	由 `@ForgeCacheConfig` 在类型上声明的命名缓存，含默认策略与安全边界
缓存注解	`@ForgeCacheable` / `@ForgeCachePut` / `@ForgeCacheEvict` 在方法上的缓存操作
存储模式	`CacheMode`：LOCAL（本地）/ REDIS / MULTI（多级）
身份隔离范围	`CacheScope`：GLOBAL / TENANT / TENANT_USER / TENANT_USER_ORG
运行策略	`sys_cache_policy` 表，按「应用编码 + 缓存名」覆盖代码默认策略

声明缓存

1. 声明缓存定义

在类型上用 @ForgeCacheConfig（可重复，@Inherited）声明命名缓存：

java

@ForgeCacheConfig(
    name = "sys_dict_data",
    description = "字典数据缓存",
    mode = CacheMode.REDIS,                 // 默认存储模式
    allowedModes = {CacheMode.LOCAL, CacheMode.REDIS, CacheMode.MULTI}, // 不可变安全边界
    scope = CacheScope.TENANT,              // 键隔离范围
    redisTtlSeconds = 1800,
    localTtlSeconds = 60,
    localMaxSize = 1000,
    cacheNull = false,
    nullTtlSeconds = 30
)
@Service
public class SysDictDataService { ... }

属性	默认值	说明
`name`	—（必填）	缓存名
`description`	`""`	缓存描述
`mode`	`REDIS`	默认存储模式
`allowedModes`	LOCAL/REDIS/MULTI	代码声明的不可变安全边界，运行时不能越界
`scope`	`TENANT`	缓存键身份隔离范围
`redisTtlSeconds`	`1800`	Redis TTL（秒）
`localTtlSeconds`	`60`	本地 TTL（秒）
`localMaxSize`	`1000`	本地缓存容量
`cacheNull`	`false`	是否缓存空值
`nullTtlSeconds`	`30`	空值 TTL（秒）

2. 使用缓存注解

java

@ForgeCacheable(cacheName = "sys_dict_data", key = "#dictType")
public List<SysDictData> listByType(String dictType) { ... }

@ForgeCachePut(cacheName = "sys_dict_data", key = "#vo.dictType")
public void update(...) { ... }

@ForgeCacheEvict(cacheName = "sys_dict_data", key = "#dictType")
public void remove(String dictType) { ... }

// 全量失效
@ForgeCacheEvict(cacheName = "sys_dict_data", allEntries = true)
public void clearAll() { ... }

注解	属性	说明
`@ForgeCacheable`	`cacheName`、`key`	命中即返回缓存，未命中回源并写入
`@ForgeCachePut`	`cacheName`、`key`	强制写入缓存
`@ForgeCacheEvict`	`cacheName`、`key`、`allEntries`	失效指定键或全量失效

key 支持 SpEL 表达式（如 #dictType），留空走默认键策略。

配置项

受管缓存配置前缀为 forge.cache：

配置	默认值	说明
`forge.cache.annotation-enabled`	`true`	是否启用注解拦截，关闭后业务方法全部穿透
`forge.cache.application-code`	`spring.application.name`	应用编码
`forge.cache.namespace`	`forge:managed-cache`	Redis 控制面和数据对象前缀
`forge.cache.policy-refresh-seconds`	`30`	Pub/Sub 丢失时重新校准策略快照的最小间隔

运行策略治理

运行策略存放在 sys_cache_policy 表，按「应用编码 + 缓存名」唯一约束：

字段	说明
`application_code`	应用编码
`cache_name`	缓存名
`enabled`	是否启用
`cache_mode`	LOCAL / REDIS / MULTI
`local_ttl_seconds` / `redis_ttl_seconds`	本地 / Redis TTL
`local_max_size`	本地容量
`cache_null` / `null_ttl_seconds`	空值缓存与 TTL
`policy_version`	策略版本（乐观并发控制）

管理接口

受管缓存策略接口在 /system/cache/policy 下，仅超级管理员可调用：

接口	说明
`GET /page`	分页查询受管缓存策略
`POST /edit`	修改运行策略
`POST /reset`	恢复默认策略（`applicationCode` + `cacheName`）
`POST /clear`	清空受管缓存（`applicationCode` + `cacheName`）

管理后台入口为 平台管理 > 运维监控 > 缓存监控，可查看各缓存的运行策略、过期策略、容量 / 空值配置与运行统计，并在线编辑、重置、清空。

安全边界

allowedModes 是代码声明的不可变安全边界，运行时策略只能在其范围内选择，不能越界改模式。
缓存名与允许模式仍由代码定义约束，管理端只覆盖 TTL、容量、空值与启用状态。
策略变更通过 policy_version 乐观并发控制，避免并发覆盖。
仅超级管理员可管理策略；关闭 annotation-enabled 后所有受管缓存方法穿透执行。

受管注解缓存 ​

核心概念 ​

声明缓存 ​

1. 声明缓存定义 ​

2. 使用缓存注解 ​

配置项 ​

运行策略治理 ​

管理接口 ​

安全边界 ​

相关文档 ​