前言¶
在已有 SpringBoot 服务里加缓存，常见做法是手写 Redis 工具类或在每个查询方法里套一层 get/set。注解式缓存能减少重复代码，但 Spring Cache 与业务约定的 key 规则、null 值语义、SpEL 定制 key 仍要自己对齐实现。下面介绍 SkillHub 社区技能 springboot缓存注解（坐标 @user_faca7523/springboot-cache，版本 1.0.0）：通过脚本把 @CacheResult、AOP 切面、Redis 配置和依赖一次性落到项目里，适合在 springboot-init 生成的基础结构上继续扩展。
这是什么¶
springboot缓存注解 是面向 SpringBoot 的 Agent Skill，发布者为 user_faca7523，分类为 dev-programming，来源为 community。技能目标很明确：为 SpringBoot 项目添加基于 Redis 的缓存注解能力，用 @CacheResult 缓存方法返回值。
该技能声明依赖 springboot-init 技能生成的基础项目结构；单独空仓库若目录与约定不一致，需要先具备对应骨架再执行脚本。
核心功能¶
@CacheResult 注解参数¶
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| keyPrefix | String | project:cache |
缓存 key 的前缀 |
| key | String | "" |
普通缓存 key |
| spelKey | String | "" |
SpEL 表达式缓存 key |
| cacheTime | int | 1 |
缓存时间 |
| cacheTimeUnit | TimeUnit | TimeUnit.HOURS |
缓存时间单位 |
Key 生成策略¶
- 优先普通 key：
keyPrefix:key - 次优先 SpEL：
keyPrefix:解析SpEL表达式 - 默认：
keyPrefix:类全限定名:方法名:AES(参数)（资料中默认策略描述为对参数做 AES；技术特性一节同时说明使用 Hutool MD5 生成确定性 key，落地时以生成代码为准）
脚本会生成的工程内容¶
依赖（pom.xml）
cn.hutool:hutool-allspring-boot-starter-data-redisspring-boot-starter-aop
application.yml 会补充 Redis 连接项，例如：
spring:
data:
redis:
host: localhost
port: 6379
password:
database: 0
timeout: 3000ms
新增或更新的 Java 文件
| 文件路径 | 说明 |
|---|---|
annotation/CacheResult.java |
缓存注解 |
common/CacheNullValue.java |
null 值标记类 |
util/CacheKeyGenerator.java |
Key 生成工具类 |
aspect/CacheResultAspect.java |
缓存 AOP 切面 |
config/RedisConfig.java |
Redis 配置类 |
技术特性（官方说明）
- 使用 Hutool MD5 工具生成确定性 Key
- SpEL 支持
#参数名、#参数.属性等 - 通过
CacheNullValue区分「未缓存」与「缓存了 null」 - 缓存操作失败不影响业务执行
- 使用
GenericJackson2JsonRedisSerializer序列化复杂对象
安装与启用¶
技能安装后，典型路径为 .trae/skills/springboot-cache/。在具备 springboot-init 结构的项目根目录执行脚本，为指定 artifactId 与包名注入缓存能力：
python .trae/skills/springboot-cache/scripts/cache_annotation.py <artifactId> <packageName> [projectName] [springBootVersion] [author]
示例：
# 基本用法
python .trae/skills/springboot-cache/scripts/cache_annotation.py demo com.example
# 指定项目信息
python .trae/skills/springboot-cache/scripts/cache_annotation.py demo com.example Demo 3.5 wql
参数含义：artifactId、packageName 为必填；projectName、springBootVersion、author 可选。执行前请确认本机 Redis 地址与 application.yml 中配置一致。资料未单独列出 Cursor / Codex CLI / Claude Code 的差异步骤时，以 Skill 目录内脚本与 SKILL.md 为准。
SkillHub 页面显示该技能标签 requires_api_key=false，无需额外 API Key。
典型用法¶
在 Service 或查询方法上声明 @CacheResult，按 key 策略三选一或组合时间与单位：
// 使用普通 key
@CacheResult(keyPrefix = "user:", key = "info")
public User getUser(Long userId) {
// ...
}
// 使用 SpEL key
@CacheResult(keyPrefix = "user:", spelKey = "#userId")
public User getUser(Long userId) {
// ...
}
// 使用默认 key，并设置 30 分钟过期
@CacheResult(cacheTime = 30, cacheTimeUnit = TimeUnit.MINUTES)
public User getUser(Long userId) {
// ...
}
经过上面的步骤，首次调用会走方法逻辑并写入 Redis；相同 key 在有效期内由切面直接返回缓存。需要穿透或更新缓存时，应在业务层配合过期时间或自行扩展失效逻辑（技能资料未内置 @CacheEvict 类注解，以生成代码能力为界）。
适用场景与注意¶
适合
- 已在或计划用 springboot-init 搭好的 SpringBoot 项目，需要快速加上 Redis + 注解缓存
- 希望统一 key 前缀、支持 SpEL、并处理 null 缓存语义的场景
注意
- 前置依赖：必须先有 springboot-init 约定的项目结构，否则脚本目标路径可能对不齐。
- 运行环境：需要可用的 Redis；默认
localhost:6379，生产环境应改 host、密码与 database。 - 序列化：复杂对象依赖 Jackson JSON 序列化，类型变更可能导致旧缓存反序列化失败，改模型后宜清 key 或缩短 TTL。
- 失败策略：缓存异常不阻断业务，但可能造成短时击穿到数据库，需结合监控观察 Redis 可用性。
结尾¶
springboot缓存注解 把 Redis 依赖、配置、@CacheResult 切面与 key 策略封装成可脚本化的一步接入，适合在标准 SpringBoot 骨架上补缓存层。更多说明与安装见 SkillHub：
- API 文档：https://api.skillhub.cn/user_faca7523/springboot-cache
- 技能页面：https://www.skillhub.cn/skills/user_faca7523/springboot-cache
