前言¶
在已有 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
