feat：增加文章和列表缓存逻辑

yqz · yqz · commit fea6f11af178 · 2026-05-26T23:04:41.000+08:00
diff --git a/OpenBlog-business/src/main/java/com/yqz/openblog/article/service/ArticlePublishedContentCacheService.java b/OpenBlog-business/src/main/java/com/yqz/openblog/article/service/ArticlePublishedContentCacheService.java
@@ -1,7 +1,10 @@
 package com.yqz.openblog.article.service;
 
+import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import com.yqz.openblog.article.dto.ArticleListItemResponse;
 import com.yqz.openblog.article.dto.ArticlePublishedContentCachePayload;
+import com.yqz.openblog.common.PageResult;
 import com.yqz.openblog.config.CacheProperties;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -12,14 +15,25 @@
 import java.util.Optional;
 
 /**
- * 已发布文章「正文 + 相对稳定元数据」的 Redis 缓存（默认 30 分钟）。
+ * 已发布文章的 Redis 缓存服务。
  * <p>
+ * 包含两部分缓存：
+ * <ol>
+ *   <li>文章正文缓存（个体）：缓存相对稳定的正文与元数据，计数类字段每次从数据库合并。</li>
+ *   <li>文章列表缓存（分页）：使用版本号机制，任何影响列表的写操作会递增版本号，
+ *       使旧版本缓存自然过期，避免全量扫描删除。</li>
+ * </ol>
  * Redis 不可用或读写异常时：读侧返回 empty，写侧忽略，由 {@link ArticleService} 直接走数据库。
  */
 @Service
 public class ArticlePublishedContentCacheService {
 
     private static final String KEY_PREFIX = "openblog:article:published:content:";
+    private static final String LIST_KEY_PREFIX = "openblog:article:published:list:v";
+    private static final String LIST_VERSION_KEY = "openblog:article:published:list:version";
+
+    private static final TypeReference<PageResult<ArticleListItemResponse>> LIST_PAGE_TYPE =
+            new TypeReference<>() {};
 
     private static final Logger log = LoggerFactory.getLogger(ArticlePublishedContentCacheService.class);
 
@@ -36,6 +50,8 @@ public ArticlePublishedContentCacheService(
         this.cacheProperties = cacheProperties;
     }
 
+    // ==================== 文章正文缓存（个体） ====================
+
     public Optional<ArticlePublishedContentCachePayload> get(Long articleId) {
         if (articleId == null) {
             return Optional.empty();
@@ -76,7 +92,68 @@ public void evict(Long articleId) {
         }
     }
 
+    // ==================== 文章列表缓存（分页） ====================
+
+    /**
+     * 获取当前列表版本号。版本号用于构造缓存 key，不存在时默认为 0。
+     */
+    private long getListVersion() {
+        try {
+            String v = redisTemplate.opsForValue().get(LIST_VERSION_KEY);
+            return v == null ? 0L : Long.parseLong(v);
+        } catch (Exception e) {
+            log.warn("读取列表版本号失败，降级为 version=0。", e);
+            return 0L;
+        }
+    }
+
+    /**
+     * 递增列表版本号，使所有旧版本列表缓存自然过期（靠 TTL 清理）。
+     * 任何影响已发布列表的写操作（发布、取消发布、更新已发布文章、删除）都应调用此方法。
+     */
+    public void evictPublishedList() {
+        try {
+            redisTemplate.opsForValue().increment(LIST_VERSION_KEY);
+        } catch (Exception e) {
+            log.warn("递增列表版本号失败（已忽略）。", e);
+        }
+    }
+
+    public Optional<PageResult<ArticleListItemResponse>> getList(Long categoryId, int page, int size) {
+        try {
+            long version = getListVersion();
+            String json = redisTemplate.opsForValue().get(listKey(version, categoryId, page, size));
+            if (json == null || json.isBlank()) {
+                return Optional.empty();
+            }
+            return Optional.of(objectMapper.readValue(json, LIST_PAGE_TYPE));
+        } catch (Exception e) {
+            log.warn("读取文章列表缓存失败，降级为数据库。categoryId={}, page={}, size={}", categoryId, page, size, e);
+            return Optional.empty();
+        }
+    }
+
+    public void putList(Long categoryId, int page, int size, PageResult<ArticleListItemResponse> payload) {
+        if (payload == null) {
+            return;
+        }
+        int minutes = Math.max(1, cacheProperties.getArticleListTtlMinutes());
+        try {
+            long version = getListVersion();
+            String json = objectMapper.writeValueAsString(payload);
+            redisTemplate.opsForValue().set(listKey(version, categoryId, page, size), json, Duration.ofMinutes(minutes));
+        } catch (Exception e) {
+            log.warn("写入文章列表缓存失败（已忽略）。categoryId={}, page={}, size={}", categoryId, page, size, e);
+        }
+    }
+
+    // ==================== Key 构造 ====================
+
     private static String key(Long articleId) {
         return KEY_PREFIX + articleId;
     }
+
+    private static String listKey(long version, Long categoryId, int page, int size) {
+        return LIST_KEY_PREFIX + version + ":" + (categoryId == null ? "all" : categoryId) + ":" + page + ":" + size;
+    }
 }
diff --git a/OpenBlog-business/src/main/java/com/yqz/openblog/article/service/ArticleService.java b/OpenBlog-business/src/main/java/com/yqz/openblog/article/service/ArticleService.java
@@ -158,6 +158,11 @@ private ArticleDetailResponse mergePublishedDetailFromCache(ArticlePublishedCont
     }
 
     public PageResult<ArticleListItemResponse> listPublished(int page, int size, Long categoryId) {
+        Optional<PageResult<ArticleListItemResponse>> cached = publishedContentCache.getList(categoryId, page, size);
+        if (cached.isPresent()) {
+            return cached.get();
+        }
+
         Page<Article> mpPage = new Page<>(page + 1L, size);
         LambdaQueryWrapper<Article> w = Wrappers.lambdaQuery();
         w.eq(Article::getStatus, ArticleStatus.PUBLISHED)
@@ -171,7 +176,9 @@ public PageResult<ArticleListItemResponse> listPublished(int page, int size, Lon
         }
         IPage<Article> p = articleMapper.selectPage(mpPage, w);
         List<ArticleListItemResponse> items = p.getRecords().stream().map(this::mapListItem).toList();
-        return new PageResult<>(items, page, size, p.getTotal());
+        PageResult<ArticleListItemResponse> result = new PageResult<>(items, page, size, p.getTotal());
+        publishedContentCache.putList(categoryId, page, size, result);
+        return result;
     }
 
     public ArticleDetailResponse detailPublished(Long id, String clientIp) {
@@ -281,6 +288,7 @@ public ArticleListItemResponse updateArticle(Long authorId, Long articleId, Arti
 
         if (a.getStatus() == ArticleStatus.PUBLISHED) {
             publishedContentCache.evict(articleId);
+            publishedContentCache.evictPublishedList();
         }
         return mapListItem(a);
     }
@@ -317,6 +325,7 @@ public ArticleListItemResponse publish(Long authorId, Long articleId, Instant pu
         a.setRejectedReason(null);
         articleMapper.updateById(a);
         publishedContentCache.evict(articleId);
+        publishedContentCache.evictPublishedList();
         return mapListItem(a);
     }
 
@@ -334,6 +343,9 @@ public int publishDueScheduled(int batchSize) {
                 publishedContentCache.evict(id);
             }
         }
+        if (published > 0) {
+            publishedContentCache.evictPublishedList();
+        }
         return published;
     }
 
@@ -353,6 +365,7 @@ public void unpublishOrDelete(Long authorId, Long articleId) {
         a.setScheduledAt(null);
         articleMapper.updateById(a);
         publishedContentCache.evict(articleId);
+        publishedContentCache.evictPublishedList();
     }
 
     public PageResult<ArticleListItemResponse> listMine(Long authorId, int page, int size) {
diff --git a/OpenBlog-business/src/main/java/com/yqz/openblog/common/PageResult.java b/OpenBlog-business/src/main/java/com/yqz/openblog/common/PageResult.java
@@ -8,6 +8,9 @@ public class PageResult<T> {
     private int size;
     private long total;
 
+    public PageResult() {
+    }
+
     public PageResult(List<T> items, int page, int size, long total) {
         this.items = items;
         this.page = page;
@@ -19,15 +22,31 @@ public List<T> getItems() {
         return items;
     }
 
+    public void setItems(List<T> items) {
+        this.items = items;
+    }
+
     public int getPage() {
         return page;
     }
 
+    public void setPage(int page) {
+        this.page = page;
+    }
+
     public int getSize() {
         return size;
     }
 
+    public void setSize(int size) {
+        this.size = size;
+    }
+
     public long getTotal() {
         return total;
     }
+
+    public void setTotal(long total) {
+        this.total = total;
+    }
 }
diff --git a/OpenBlog-business/src/main/java/com/yqz/openblog/config/CacheProperties.java b/OpenBlog-business/src/main/java/com/yqz/openblog/config/CacheProperties.java
@@ -13,11 +13,24 @@ public class CacheProperties {
      */
     private int articlePublishedTtlMinutes = 30;
 
+    /**
+     * 已发布文章列表页在 Redis 中的 TTL（分钟）。列表页变更频率高，TTL 较短以保证新鲜度。
+     */
+    private int articleListTtlMinutes = 5;
+
     public int getArticlePublishedTtlMinutes() {
         return articlePublishedTtlMinutes;
     }
 
     public void setArticlePublishedTtlMinutes(int articlePublishedTtlMinutes) {
         this.articlePublishedTtlMinutes = articlePublishedTtlMinutes;
     }
+
+    public int getArticleListTtlMinutes() {
+        return articleListTtlMinutes;
+    }
+
+    public void setArticleListTtlMinutes(int articleListTtlMinutes) {
+        this.articleListTtlMinutes = articleListTtlMinutes;
+    }
 }
diff --git a/OpenBlog-business/src/main/resources/application.yaml b/OpenBlog-business/src/main/resources/application.yaml
@@ -40,6 +40,8 @@ openblog:
   cache:
     # 已发布文章正文（Redis）；不可用或异常时自动仅查 MySQL
     article-published-ttl-minutes: 30
+    # 已发布文章列表页（Redis）；变更时通过版本号全局失效，短 TTL 兜底
+    article-list-ttl-minutes: 5
   site:
     version: "1.0.0"
   # 生产环境请改为前端实际域名，例如 https://blog.example.com
diff --git a/README.md b/README.md
@@ -33,6 +33,32 @@
 - **惰性回填**：迁移后的旧文章 `content_html` 为空，首次读取时自动渲染并写回。
 - **图片等二进制资源**：通过 MinIO（或本地文件系统）独立存储，不在数据库中。
 
+### 缓存架构
+
+已发布文章的读取链路使用 Redis 做两级缓存，减少数据库压力：
+
+| 缓存层级 | Redis Key | TTL | 说明 |
+|---------|-----------|-----|------|
+| 文章正文 | `openblog:article:published:content:{id}` | 30 min | 缓存标题、摘要、正文（Markdown + HTML）、作者、分类等相对稳定字段。计数类字段（阅读量、点赞数等）每次从数据库合并，避免缓存与数据库不一致。 |
+| 文章列表 | `openblog:article:published:list:v{version}:{categoryId}:{page}:{size}` | 5 min | 缓存已发布文章分页列表。写操作通过递增全局版本号使旧版本缓存自然过期，无需全量扫描删除。 |
+
+**缓存一致性策略（Cache-Aside）**：
+
+```
+读取：先查 Redis → 命中返回 → 未命中查 MySQL 并回写 Redis
+写入：更新 MySQL → 删除 Redis 缓存 → 下次读取时自动重建
+```
+
+| 写操作 | 正文缓存 | 列表缓存 |
+|--------|---------|---------|
+| 发布文章 | 删除 | 递增版本号（全局失效） |
+| 更新已发布文章 | 删除 | 递增版本号 |
+| 删除/下架文章 | 删除 | 递增版本号 |
+| 定时发布 | 逐条删除 | 批量完成后递增版本号 |
+| 创建草稿 | 不处理 | 不处理 |
+
+**故障降级**：Redis 读写异常时，读侧返回空（走数据库），写侧忽略异常并记录日志，不影响正常业务响应。
+
 ---
 
 ## 技术栈
@@ -43,7 +69,7 @@
 - Spring Boot **3.5.x**（Web、Validation、Security、Data JPA、Data Redis）
 - MyBatis-Plus **3.5.x**（与 JPA 并存，按模块使用）
 - MySQL **8**（Hibernate `ddl-auto: update` 便于开发迭代）
-- Redis（文章正文缓存、阅读量滑动窗口等）
+- Redis（文章正文缓存、列表页缓存、阅读量滑动窗口去重）
 - JWT（jjwt **0.12.x**）
 - MinIO 对象存储（图片上传，可选本地文件系统回退）
 - flexmark（服务端 Markdown → HTML 预渲染）
@@ -74,7 +100,7 @@ OpenBlog/
 │       ├── java/com/yqz/openblog/
 │       │   ├── article/           # 文章：实体、DTO、服务、导入/导出、定时发布
 │       │   │   ├── entity/        # Article, ArticleBody（正文独立存储）
-│       │   │   ├── service/       # 文章服务、缓存、阅读量、MarkdownRenderer
+│       │   │   ├── service/       # 文章服务、缓存（正文+列表）、阅读量、导入导出
 │       │   │   └── repo/          # MyBatis-Plus Mapper + JPA Repository
 │       │   ├── category/          # 分类
 │       │   ├── changelog/         # 更新日志
@@ -121,6 +147,7 @@ OpenBlog/
 | `spring.data.redis.*` | Redis 主机、端口、超时等 |
 | `openblog.jwt.*` | JWT 密钥、签发方、Access/Refresh 过期时间（秒） |
 | `openblog.storage.*` | 本地上传根目录、`public-base-url`（对外访问文件与拼 URL 用）、缩略图长边像素 |
+| `openblog.cache.*` | 文章正文缓存 TTL（`article-published-ttl-minutes`，默认 30）、列表缓存 TTL（`article-list-ttl-minutes`，默认 5） |
 
 **务必在部署环境中：**
 

Original file line number	Diff line number	Diff line change
`@@ -158,6 +158,11 @@ private ArticleDetailResponse mergePublishedDetailFromCache(ArticlePublishedCont`
`158`	`158`	`}`
`159`	`159`
`160`	`160`	`public PageResult<ArticleListItemResponse> listPublished(int page, int size, Long categoryId) {`
	`161`	`+ Optional<PageResult<ArticleListItemResponse>> cached = publishedContentCache.getList(categoryId, page, size);`
	`162`	`+ if (cached.isPresent()) {`
	`163`	`+ return cached.get();`
	`164`	`+ }`
	`165`	`+`
`161`	`166`	`Page<Article> mpPage = new Page<>(page + 1L, size);`
`162`	`167`	`LambdaQueryWrapper<Article> w = Wrappers.lambdaQuery();`
`163`	`168`	`w.eq(Article::getStatus, ArticleStatus.PUBLISHED)`
`@@ -171,7 +176,9 @@ public PageResult<ArticleListItemResponse> listPublished(int page, int size, Lon`
`171`	`176`	`}`
`172`	`177`	`IPage<Article> p = articleMapper.selectPage(mpPage, w);`
`173`	`178`	`List<ArticleListItemResponse> items = p.getRecords().stream().map(this::mapListItem).toList();`
`174`		`- return new PageResult<>(items, page, size, p.getTotal());`
	`179`	`+ PageResult<ArticleListItemResponse> result = new PageResult<>(items, page, size, p.getTotal());`
	`180`	`+ publishedContentCache.putList(categoryId, page, size, result);`
	`181`	`+ return result;`
`175`	`182`	`}`
`176`	`183`
`177`	`184`	`public ArticleDetailResponse detailPublished(Long id, String clientIp) {`
`@@ -281,6 +288,7 @@ public ArticleListItemResponse updateArticle(Long authorId, Long articleId, Arti`
`281`	`288`
`282`	`289`	`if (a.getStatus() == ArticleStatus.PUBLISHED) {`
`283`	`290`	`publishedContentCache.evict(articleId);`
	`291`	`+ publishedContentCache.evictPublishedList();`
`284`	`292`	`}`
`285`	`293`	`return mapListItem(a);`
`286`	`294`	`}`
`@@ -317,6 +325,7 @@ public ArticleListItemResponse publish(Long authorId, Long articleId, Instant pu`
`317`	`325`	`a.setRejectedReason(null);`
`318`	`326`	`articleMapper.updateById(a);`
`319`	`327`	`publishedContentCache.evict(articleId);`
	`328`	`+ publishedContentCache.evictPublishedList();`
`320`	`329`	`return mapListItem(a);`
`321`	`330`	`}`
`322`	`331`
`@@ -334,6 +343,9 @@ public int publishDueScheduled(int batchSize) {`
`334`	`343`	`publishedContentCache.evict(id);`
`335`	`344`	`}`
`336`	`345`	`}`
	`346`	`+ if (published > 0) {`
	`347`	`+ publishedContentCache.evictPublishedList();`
	`348`	`+ }`
`337`	`349`	`return published;`
`338`	`350`	`}`
`339`	`351`
`@@ -353,6 +365,7 @@ public void unpublishOrDelete(Long authorId, Long articleId) {`
`353`	`365`	`a.setScheduledAt(null);`
`354`	`366`	`articleMapper.updateById(a);`
`355`	`367`	`publishedContentCache.evict(articleId);`
	`368`	`+ publishedContentCache.evictPublishedList();`
`356`	`369`	`}`
`357`	`370`
`358`	`371`	`public PageResult<ArticleListItemResponse> listMine(Long authorId, int page, int size) {`