feat: refactor word count logic and add caching service

Author: HowieHz

README.md

@@ -13,7 +13,7 @@
 这个插件正是基于这个理念：
 - 让复杂的逻辑在后端处理
 - 前端模板只负责展示
-- 提供简洁的 Finder API
+- 为主题提供简洁的 Finder API
 - 减少不必要的 JavaScript 依赖
 
 <details><summary>前端动态加载方式 vs 后端服务端渲染方式</summary>
@@ -35,7 +35,6 @@
 
 ## TODO
 
-- [ ] 缓存文章字数统计 API 结果，仅在文章更新时刷新统计 API 结果
 - [ ] 提供随机文章 API
 - [ ] 提供预计阅读时间 API，及相关配置项
 
@@ -58,18 +57,18 @@
 <!--/* 先检测插件可用性，再使用 API */-->
 <th:block th:if="${pluginFinder.available('extra-api')}">
     <span 
-        th:text="|总字数：${extraApiStatsFinder.wordCount()}|"
+        th:text="|总字数：${extraApiStatsFinder.postWordCount()}|"
     ></span>
 </th:block>
 
 <!--/* 写在一个标签内也可以，th:if 的优先级比 th:text 高 */-->
 <span
     th:if="${pluginFinder.available('extra-api')}"
-    th:text="|总字数：${extraApiStatsFinder.wordCount()}|"
+    th:text="|总字数：${extraApiStatsFinder.postWordCount()}|"
 ></span>
 
 <!--/* 自然模板写法 */-->
-<span th:if="${pluginFinder.available('extra-api')}">总字数：[[${extraApiStatsFinder.wordCount()}]]</span>
+<span th:if="${pluginFinder.available('extra-api')}">总字数：[[${extraApiStatsFinder.postWordCount()}]]</span>
 ```
 
 **说明**
@@ -83,14 +82,14 @@
 #### 文章字数统计
 
 ```javascript
-extraApiStatsFinder.wordCount({
+extraApiStatsFinder.postWordCount({
   name: 'post-metadata-name',  // 可选，未传入则统计全部文章字数总和
   version: 'release' | 'draft'  // 可选，默认 'release'
 });
 ```
 
 ```javascript
-extraApiStatsFinder.wordCount();
+extraApiStatsFinder.postWordCount();
 ```
 
 **描述**
@@ -106,6 +105,7 @@ extraApiStatsFinder.wordCount();
   - 输入为空或文章不存在时返回 0，不会抛出异常。
 - 性能说明：
   - 单次调用开销较小，适合在模板中直接使用。
+  - 启动时自动计算并缓存，仅在文章内容更新时重新计算。
 
 **参数**
 - `name:string` – 文章 `metadata.name`（可选，不传则统计全站）
@@ -117,18 +117,18 @@ extraApiStatsFinder.wordCount();
 **使用示例**
 ```html
 <!--/* 统计文章已发布版本的字，适用于 /templates/post.html */-->
-<span th:text="${extraApiStatsFinder.wordCount({name: post.metadata.name})}"></span>
+<span th:text="${extraApiStatsFinder.postWordCount({name: post.metadata.name})}"></span>
 
 <!--/* 统计文章最新版本的字数（含草稿），适用于 /templates/post.html */-->
-<span th:text="${extraApiStatsFinder.wordCount({name: post.metadata.name, version: 'draft'})}"></span>
+<span th:text="${extraApiStatsFinder.postWordCount({name: post.metadata.name, version: 'draft'})}"></span>
 
 <!--/* 统计全站已发布文章的总字数，适用于全部模板 */-->
-<span th:text="${extraApiStatsFinder.wordCount()}"></span>
+<span th:text="${extraApiStatsFinder.postWordCount()}"></span>
 <!--/* 与下方写法等价 */-->
- <span th:text="${extraApiStatsFinder.wordCount({})}"></span>
+ <span th:text="${extraApiStatsFinder.postWordCount({})}"></span>
 
 <!--/* 统计全站所有文章最新版本的总字数（含草稿），适用于全部模板 */-->
-<span th:text="${extraApiStatsFinder.wordCount({version: 'draft'})}"></span>
+<span th:text="${extraApiStatsFinder.postWordCount({version: 'draft'})}"></span>
 ```
 
 ## 开发环境

build.gradle

@@ -1,6 +1,6 @@
 plugins {
     id 'java'
-    id "io.freefair.lombok" version "8.13"
+    id "io.freefair.lombok" version "8.14"
     id "run.halo.plugin.devtools" version "0.6.1"
 }
 

src/main/java/top/howiehz/halo/plugin/extra/api/HaloPluginExtraApiPlugin.java

@@ -3,27 +3,41 @@
 import org.springframework.stereotype.Component;
 import run.halo.app.plugin.BasePlugin;
 import run.halo.app.plugin.PluginContext;
+import top.howiehz.halo.plugin.extra.api.service.PostWordCountService;
 
 /**
- * <p>Plugin main class to manage the lifecycle of the plugin.</p>
- * <p>This class must be public and have a public constructor.</p>
+ * Plugin main class to manage the lifecycle of the plugin.
+ * 插件主类，负责管理插件的生命周期。
  * <p>Only one main class extending {@link BasePlugin} is allowed per plugin.</p>
- *
- * @author HowieHz
- * @since 1.0.0
+ * <p>每个插件只能有一个继承 {@link BasePlugin} 的主类。</p>
  */
 @Component
 public class HaloPluginExtraApiPlugin extends BasePlugin {
 
-    public HaloPluginExtraApiPlugin(PluginContext pluginContext) {
+    private final PostWordCountService postWordCountService;
+
+    public HaloPluginExtraApiPlugin(PluginContext pluginContext, PostWordCountService postWordCountService) {
         super(pluginContext);
+        this.postWordCountService = postWordCountService;
     }
 
+    /**
+     * Called when the plugin is starting.
+     * 插件启动时调用。
+     */
     @Override
     public void start() {
         System.out.println("插件启动成功！");
+        // Preload all caches when the plugin starts
+        // 插件启动时预加载所有缓存
+        // post word count cache / 文章字数缓存
+        postWordCountService.warmUpAllCache();
     }
 
+    /**
+     * Called when the plugin is stopping.
+     * 插件停止时调用。
+     */
     @Override
     public void stop() {
         System.out.println("插件停止！");

src/main/java/top/howiehz/halo/plugin/extra/api/finder/ExtraApiStatsFinder.java

@@ -2,30 +2,37 @@
 
 import reactor.core.publisher.Mono;
 import java.util.Collections;
+import java.math.BigInteger;
 
 /**
  * Finder for calculating post word/character counts for themes to use.
+ * 供主题使用的文章字数/字符数统计 Finder。
  */
 public interface ExtraApiStatsFinder {
     /**
      * Unified word count API.
+     * 统一的字数统计接口。
+     * <p>
      * Parameters (all optional):
-     * - name: metadata.name of the post
-     * - version: 'release' or 'draft' (default 'release')
+     * 参数（均为可选）：
+     * - name: metadata.name of the post / 文章的 metadata.name
+     * - version: 'release' or 'draft' (default 'release') / 版本：发布版或草稿（默认发布版）
      * If name is provided, count the specific post; otherwise, count all posts.
+     * 若提供 name 参数，则统计对应文章；否则统计所有文章的总字数。
+     * </p>
      *
-     * @param params parameter map from templates
-     * @return word count as Mono (non-negative)
+     * @param params parameter map from templates / 来自模板的参数映射
+     * @return word count as Mono (non-negative) / 返回字数（非负）的 Mono
      */
-    Mono<Integer> wordCount(java.util.Map<String, Object> params);
+    Mono<BigInteger> postWordCount(java.util.Map<String, Object> params);
 
     /**
      * Get total word count of all published posts.
      * 获取所有已发布文章的总字数。
      *
-     * @return word count as Mono (non-negative)
+     * @return word count as Mono (non-negative) / 返回字数（非负）的 Mono
      */
-    default Mono<Integer> wordCount(){
-        return wordCount(Collections.emptyMap());
-    };
+    default Mono<BigInteger> postWordCount() {
+        return postWordCount(Collections.emptyMap());
+    }
 }

src/main/java/top/howiehz/halo/plugin/extra/api/finder/ExtraApiStatsFinderImpl.java

@@ -1,190 +1,52 @@
 package top.howiehz.halo.plugin.extra.api.finder;
 
 import java.util.*;
-import java.util.regex.Pattern;
-import org.springframework.data.domain.Sort;
+import java.math.BigInteger;
 import org.springframework.stereotype.Component;
 import reactor.core.publisher.Mono;
-import run.halo.app.content.ContentWrapper;
-import run.halo.app.content.PostContentService;
-import run.halo.app.core.extension.content.Post;
-import run.halo.app.extension.ListOptions;
-import run.halo.app.extension.ReactiveExtensionClient;
 import run.halo.app.theme.finders.Finder;
+import top.howiehz.halo.plugin.extra.api.service.PostWordCountService;
 
 /**
  * Implementation of ExtraApiStatsFinder.
+ * 统计 Finder 的实现，用于为主题提供字数统计能力。
  */
 @Component
 @Finder("extraApiStatsFinder")
 public class ExtraApiStatsFinderImpl implements ExtraApiStatsFinder {
 
-    private final ReactiveExtensionClient client; // 响应式扩展客户端 / Reactive extension client
-    private final PostContentService postContentService; // 文章内容服务 / Post content service
+    private final PostWordCountService postWordCountService;
 
     /**
      * Constructor to initialize ExtraApiStatsFinderImpl with required dependencies.
-     * 构造函数，使用必需的依赖项初始化 ExtraApiStatsFinderImpl。
+     * 构造函数，注入所需依赖。
      */
-    public ExtraApiStatsFinderImpl(ReactiveExtensionClient client,
-                                   PostContentService postContentService) {
-        this.client = client; // 注入响应式扩展客户端 / Inject reactive extension client
-        this.postContentService = postContentService; // 注入文章内容服务 / Inject post content service
-    }
-
-    /**
-     * Get the word count of content by post name and method name.
-     * 根据文章名称和方法名获取内容的字数统计。
-     *
-     * @param name the post name / 文章名称
-     * @param methodName the method name to invoke / 要调用的方法名
-     * @return word count as Mono / 返回字数统计的 Mono
-     */
-    private Mono<Integer> postContentCountByName(String name, String methodName) {
-        if (name == null || name.isBlank()) {
-            return Mono.just(0); // 空名称直接返回0 / Return 0 for empty name
-        }
-
-        // 使用函数接口映射方法名到对应的服务调用 / Use function interface to map method name to service call
-        Mono<ContentWrapper> contentMono = switch (methodName) {
-            case "getHeadContent" -> postContentService.getHeadContent(name);
-            case "getReleaseContent" -> postContentService.getReleaseContent(name);
-            default -> Mono.empty(); // 不支持的方法名返回空 / Return empty for unsupported method
-        };
-
-        return contentMono.map(ContentWrapper::getContent) // 提取 content 字段 / Extract content field
-            .map(content -> countWords(
-                extractText(content))) // 从 HTML 提取文本并计数 / Extract text and count
-            .onErrorReturn(0) // 出错时返回 0 / Return 0 on error
-            .defaultIfEmpty(0); // 空结果时返回 0 / Return 0 if empty
-    }
-
-    // Patterns for stripping HTML quickly
-    // 快速移除HTML的正则表达式模式 / Patterns for quickly stripping HTML
-    private static final Pattern HTML_CONTENT_REMOVAL =
-        Pattern.compile("(?is)<(?:script|style)\\b[^>]*>.*?</(?:script|style)>|<[^>]+>|&[a-zA-Z0-9#]+;");
-
-    /**
-     * Extract plain text from HTML content by removing tags and entities.
-     * Removes script and style tags, HTML tags, and normalizes whitespace.
-     * 从 HTML 内容中提取纯文本，移除标签和实体。
-     * 移除 script 和 style 标签、HTML 标签，并规范化空白字符。
-     *
-     * @param html the HTML content / HTML 内容
-     * @return plain text / 返回纯文本
-     */
-    static String extractText(String html) {
-        if (html == null || html.isBlank()) {
-            return "";
-        }
-
-        // 一次性处理所有HTML标签和实体
-        return HTML_CONTENT_REMOVAL.matcher(html).replaceAll(" ");
-    }
-
-    /**
-     * Count words in text, supporting both CJK characters and ASCII words.
-     * CJK characters are counted individually, ASCII letters/digits are grouped as words.
-     * 统计文本中的词数，支持中日韩字符和 ASCII 单词。
-     * 中日韩字符单独计数，ASCII 字母/数字按单词分组计数。
-     *
-     * @param text the input text / 输入文本
-     * @return word count / 返回词数统计
-     */
-    static int countWords(String text) {
-        if (text == null || text.isEmpty()) {
-            return 0;
-        }
-        int count = 0; // 字数计数器 / Word count counter
-        boolean inAsciiWord = false; // 是否在ASCII单词中 / Whether in an ASCII word
-        int length = text.length();
-        for (int i = 0; i < length; ) {
-            int codePoint = text.codePointAt(i); // 获取当前字符的码点 / Get code point of current character
-            if (isCJK(codePoint)) {
-                // count each CJK code point as one word/char
-                // 每个CJK码点计为一个字/词 / Count each CJK code point as one word/char
-                count++;
-                inAsciiWord = false; // 重置ASCII单词状态 / Reset ASCII word state
-            } else if (Character.isLetterOrDigit(codePoint)) {
-                // group consecutive ASCII letters/digits as one word
-                // 连续的ASCII字母/数字作为一个单词 / Group consecutive ASCII letters/digits as one word
-                if (!inAsciiWord) {
-                    count++; // 开始新的ASCII单词 / Start a new ASCII word
-                    inAsciiWord = true; // 设置在ASCII单词中 / Set in ASCII word
-                }
-            } else {
-                inAsciiWord = false; // 非字母数字字符，重置状态 / Non-alphanumeric character, reset state
-            }
-            // 使用位运算优化字符长度计算 / Optimize character length calculation with bitwise operations
-            i += (codePoint <= 0xFFFF) ? 1 : 2;
-        }
-        return Math.max(count, 0); // 确保返回非负数 / Ensure non-negative result
-    }
-
-
-    /**
-     * Check if a Unicode code point belongs to CJK (Chinese, Japanese, Korean) character blocks.
-     * Includes various CJK unified ideographs, compatibility ideographs, and phonetic extensions.
-     * 检查 Unicode 码点是否属于中日韩 (CJK) 字符块。
-     * 包括各种 CJK 统一表意文字、兼容表意文字和音标扩展。
-     * Optimized CJK character detection using range checks.
-     * 使用范围检查优化的CJK字符检测。
-     */
-    private static boolean isCJK(int codePoint) {
-        // 常见CJK范围的快速检查 / Fast check for common CJK ranges
-        return (codePoint >= 0x4E00 && codePoint <= 0x9FFF) ||     // CJK Unified Ideographs
-            (codePoint >= 0x3400 && codePoint <= 0x4DBF) ||     // CJK Extension A
-            (codePoint >= 0x20000 && codePoint <= 0x2A6DF) ||   // CJK Extension B
-            (codePoint >= 0x2A700 && codePoint <= 0x2B73F) ||   // CJK Extension C
-            (codePoint >= 0x2B740 && codePoint <= 0x2B81F) ||   // CJK Extension D
-            (codePoint >= 0x2B820 && codePoint <= 0x2CEAF) ||   // CJK Extension E
-            (codePoint >= 0x2CEB0 && codePoint <= 0x2EBEF) ||   // CJK Extension F
-            (codePoint >= 0xF900 && codePoint <= 0xFAFF) ||     // CJK Compatibility Ideographs
-            (codePoint >= 0x2F800 && codePoint <= 0x2FA1F) ||
-            // CJK Compatibility Ideographs Supplement
-            (codePoint >= 0x3040 && codePoint <= 0x309F) ||     // Hiragana
-            (codePoint >= 0x30A0 && codePoint <= 0x30FF) ||     // Katakana
-            (codePoint >= 0x31F0 && codePoint <= 0x31FF) ||     // Katakana Phonetic Extensions
-            (codePoint >= 0xAC00 && codePoint <= 0xD7AF) ||     // Hangul Syllables
-            (codePoint >= 0x1100 && codePoint <= 0x11FF) ||     // Hangul Jamo
-            (codePoint >= 0x3130 && codePoint <= 0x318F);       // Hangul Compatibility Jamo
+    public ExtraApiStatsFinderImpl(PostWordCountService postWordCountService) {
+        this.postWordCountService = postWordCountService;
     }
 
     /**
      * Unified word count API without slug support.
      * If name provided, count by name; otherwise sum word counts across all posts
      * (release/draft selectable by version).
-     * 统一的字数统计API，不支持slug。
-     * 如果提供name参数则统计指定文章，否则统计所有文章的字数总和。
+     * 统一的字数统计 API
+     * 若提供 name 参数则按名称统计，否则统计所有文章的总字数（version 可选 release/draft）。
      *
-     * @param params parameter map: name? version? ('release'|'draft', default 'release')
-     * @return word count as Mono (non-negative)
+     * @param params parameter map: name? version? ('release'|'draft', default 'release') /
+     * 参数映射：name？version？（'release' 或 'draft'，默认 'release'）
+     * @return word count as Mono (non-negative) / 返回字数（非负）的 Mono
      */
     @Override
-    public Mono<Integer> wordCount(Map<String, Object> params) {
+    public Mono<BigInteger> postWordCount(Map<String, Object> params) {
         Map<String, Object> map = params == null ? java.util.Collections.emptyMap() : params;
-        String name = String.valueOf(map.get("name"));
+        String postName = String.valueOf(map.get("name"));
         boolean isDraft =
             String.valueOf(map.getOrDefault("version", "release")).equalsIgnoreCase("draft");
 
-        if ("null".equals(name) || name.isBlank()) {
-            return sumWordCountsAcrossAllPosts(isDraft);
+        if ("null".equals(postName) || postName.isBlank()) {
+            return postWordCountService.getTotalPostWordCount(isDraft);
         }
 
-        return isDraft ? postContentCountByName(name, "getHeadContent")
-            : postContentCountByName(name, "getReleaseContent");
-    }
-
-    /**
-     * sum word counts across all posts with pagination.
-     * 统计所有文章的字数总和。
-     */
-    private Mono<Integer> sumWordCountsAcrossAllPosts(boolean isDraft) {
-        return client.listAll(Post.class, ListOptions.builder().build(), Sort.unsorted())
-            .map(post -> post.getMetadata().getName()) // 提取需要的名称
-            .flatMapSequential(postName -> isDraft ? postContentCountByName(postName, "getHeadContent")
-                : postContentCountByName(postName, "getReleaseContent"), 1024) // 1024 并发
-            .reduce(0, Integer::sum) // 直接累加
-            .onErrorReturn(0);
+        return postWordCountService.getPostWordCount(postName, isDraft);
     }
 }