feat: Improve Pangu spacing service robustness and logging

Author: HowieHz

README.md

@@ -74,17 +74,17 @@
       - [文章字数统计 API](#文章字数统计-api)
       - [HTML 内容字数统计 API](#html-内容字数统计-api)
     - [渲染 API](#渲染-api)
-      - [代码高亮 API](#代码高亮-api)
       - [中英文混排格式化 API](#中英文混排格式化-api)
+      - [代码高亮 API](#代码高亮-api)
   - [处理器文档](#处理器文档)
+    - [中英文混排格式化处理器](#中英文混排格式化处理器)
+      - [功能说明](#功能说明)
+      - [配置选项](#配置选项)
+      - [补充说明](#补充说明)
     - [代码高亮处理器](#代码高亮处理器)
       - [特点](#特点)
-      - [配置选项](#配置选项)
+      - [配置选项](#配置选项-1)
       - [支持的主题](#支持的主题)
-      - [补充说明](#补充说明)
-    - [中英文混排格式化处理器](#中英文混排格式化处理器)
-      - [功能说明](#功能说明)
-      - [使用说明](#使用说明)
       - [补充说明](#补充说明-1)
   - [版本说明](#版本说明)
     - [轻量版的优势](#轻量版的优势)
@@ -402,42 +402,6 @@ extraApiStatsFinder.getContentWordCount({
 
 ### 渲染 API
 
-**Finder 名称：** `extraApiRenderFinder`
-
-#### 代码高亮 API
-
-```javascript
-extraApiRenderFinder.renderCodeHtml(htmlContent)
-```
-
-**参数**
-
-- `htmlContent`
-    - 类型：`string`
-    - 解释：包含代码块的 HTML 内容，通常是文章或页面的内容字段。
-
-**返回值**
-
-- 类型：`string`
-- 解释：渲染后的 HTML 内容，渲染样式已内联，渲染失败时返回原始内容
-
-**描述**
-
-- 功能特性：
-    - 同 [处理器文档 - 代码高亮（通过 Shiki.js 渲染）](#代码高亮处理器) 中描述的功能特性一致。也受同样的配置项影响。
-
-**使用示例**
-
-```html
-<!--/* 渲染文章内容中的代码块，下面这段代码可直接用于 /templates/post.html */-->
-<div th:utext="${extraApiRenderFinder.renderCodeHtml(post.content?.content)}"></div>
-
-<!--/* 在模板中使用，下面这段代码可直接用于 /templates/moment.html */-->
-<div th:with="renderedContent=${extraApiRenderFinder.renderCodeHtml(moment.spec.content?.html)}">
-    <div th:utext="${renderedContent}"></div>
-</div>
-```
-
 #### 中英文混排格式化 API
 
 **Finder 名称：** `extraApiPanguFinder`
@@ -542,8 +506,83 @@ extraApiPanguFinder.spacingText(text)
 - HTML 解析失败时返回原始内容
 - 不会抛出异常，保证页面渲染稳定性
 
+#### 代码高亮 API
+
+**Finder 名称：** `extraApiRenderFinder`
+
+```javascript
+extraApiRenderFinder.renderCodeHtml(htmlContent)
+```
+
+**参数**
+
+- `htmlContent`
+    - 类型：`string`
+    - 解释：包含代码块的 HTML 内容，通常是文章或页面的内容字段。
+
+**返回值**
+
+- 类型：`string`
+- 解释：渲染后的 HTML 内容，渲染样式已内联，渲染失败时返回原始内容
+
+**描述**
+
+- 功能特性：
+    - 同 [处理器文档 - 代码高亮（通过 Shiki.js 渲染）](#代码高亮处理器) 中描述的功能特性一致。也受同样的配置项影响。
+
+**使用示例**
+
+```html
+<!--/* 渲染文章内容中的代码块，下面这段代码可直接用于 /templates/post.html */-->
+<div th:utext="${extraApiRenderFinder.renderCodeHtml(post.content?.content)}"></div>
+
+<!--/* 在模板中使用，下面这段代码可直接用于 /templates/moment.html */-->
+<div th:with="renderedContent=${extraApiRenderFinder.renderCodeHtml(moment.spec.content?.html)}">
+    <div th:utext="${renderedContent}"></div>
+</div>
+```
+
+
 ## 处理器文档
 
+### 中英文混排格式化处理器
+
+插件提供了自动化的中英文混排格式化处理器，无需在模板中手动调用，即可对文章和页面内容自动应用 Pangu 空格处理。
+
+此功能在轻量版和全量版中均可用。
+
+#### 功能说明
+
+- 自动处理范围：
+    - 处理器会自动处理文章（post）和页面（page）内容中的段落标签（`<p>`）
+    - 在中日韩字符与英文、数字、符号之间自动插入空格
+- 处理规则：
+    - 自动在 CJK 字符和英文字母之间添加空格
+    - 自动在 CJK 字符和数字之间添加空格
+    - 自动在 CJK 字符和常见符号之间添加空格
+    - 智能跳过 `<code>`、`<pre>`、`<script>`、`<style>`、`<textarea>` 等标签
+- 性能特点：
+    - 纯 Java 实现，无需 JavaScript 运行时
+    - 处理速度快，对页面加载影响极小
+    - 不涉及缓存，每次渲染时实时处理
+- 错误处理：
+    - 处理失败时保持原始内容不变
+    - 不会因格式化问题影响页面正常渲染
+
+#### 配置选项
+
+此处理器默认启用。开箱即用，无需额外配置。
+
+在“插件设置 - 中英文混排格式化”提供以下配置项：
+- 自动渲染: 启用之后会自动处理文章和单页中段落标签的中英文混排格式，在中日韩字符与英文、数字、符号之间自动插入空格。注：Finder API 渲染不受此配置项影响。
+
+#### 补充说明
+
+- 此功能使用 [Pangu.java](https://github.com/vinta/pangu.java) 库实现
+- 仅处理可见文本内容，不影响 HTML 结构
+- 递归处理嵌套元素，确保完整覆盖
+- 与本插件提供的其他处理器兼容，互不影响
+
 ### 代码高亮处理器
 
 插件提供了自动化的代码高亮处理器，无需在模板中手动调用，即可对文章和页面内容中的代码块进行语法高亮渲染。
@@ -576,6 +615,7 @@ extraApiPanguFinder.spacingText(text)
 
 #### 配置选项
 
+在“插件设置 - 代码高亮（仅全量版可用）”提供以下配置项：
 - 自动渲染: 启用之后会自动渲染文章和单页中的代码块。注：Finder API 渲染不受此配置项影响。
 - 自定义注入 CSS 样式：启用自动渲染时将在页面 head 注入样式以优化 Shiki 渲染效果，默认值提供了边距调整/行号显示/基于媒体查询的明暗切换功能。
     - 额外注入规则: 指定额外的页面路径规则，支持通配符。
@@ -627,48 +667,6 @@ extraApiPanguFinder.spacingText(text)
 - 补充说明：
     - 双主题模式会生成两个并列的 div 元素
 
-### 中英文混排格式化处理器
-
-插件提供了自动化的中英文混排格式化处理器，无需在模板中手动调用，即可对文章和页面内容自动应用 Pangu 空格处理。
-
-此功能在轻量版和全量版中均可用。
-
-#### 功能说明
-
-- **自动处理范围**：
-    - 处理器会自动处理文章（post）和页面（page）内容中的段落标签（`<p>`）
-    - 在中日韩字符与英文、数字、符号之间自动插入空格
-
-- **处理规则**：
-    - 自动在 CJK 字符和英文字母之间添加空格
-    - 自动在 CJK 字符和数字之间添加空格
-    - 自动在 CJK 字符和常见符号之间添加空格
-    - 智能跳过 `<code>`、`<pre>`、`<script>`、`<style>`、`<textarea>` 等标签
-
-- **性能特点**：
-    - 纯 Java 实现，无需 JavaScript 运行时
-    - 处理速度快，对页面加载影响极小
-    - 不涉及缓存，每次渲染时实时处理
-
-- **错误处理**：
-    - 处理失败时保持原始内容不变
-    - 不会因格式化问题影响页面正常渲染
-
-#### 使用说明
-
-处理器默认启用，无需额外配置。如果您希望禁用自动处理，可以通过以下方式：
-
-1. 在 Halo 管理后台进入插件设置页面
-2. 找到"中英文混排格式化"相关选项（如果提供）
-3. 或者仅使用 [Finder API](#中英文混排格式化-api) 在需要的地方手动调用
-
-#### 补充说明
-
-- 此功能使用 [Pangu.java](https://github.com/vinta/pangu.java) 库实现
-- 仅处理可见文本内容，不影响 HTML 结构
-- 递归处理嵌套元素，确保完整覆盖
-- 与代码高亮处理器兼容，互不影响
-
 ## 版本说明
 
 插件提供两个版本：

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

@@ -22,7 +22,7 @@ public interface ExtraApiPanguFinder {
      * 对 HTML 内容中的指定标签元素应用 Pangu 空格。
      *
      * @param htmlContent the HTML content to process / 要处理的 HTML 内容
-     * @param tagName     the tag name to process (e.g., "p", "div") / 要处理的标签名称（例如 "p"、"div"）
+     * @param tagName the tag name to process (e.g., "p", "div") / 要处理的标签名称（例如 "p"、"div"）
      * @return Mono emitting processed HTML content / 发出处理后的 HTML 内容的 Mono
      */
     Mono<String> spacingElementByTagName(String htmlContent, String tagName);
@@ -32,7 +32,7 @@ public interface ExtraApiPanguFinder {
      * 对 HTML 内容中具有指定 ID 的元素应用 Pangu 空格。
      *
      * @param htmlContent the HTML content to process / 要处理的 HTML 内容
-     * @param id          the element ID to process / 要处理的元素 ID
+     * @param id the element ID to process / 要处理的元素 ID
      * @return Mono emitting processed HTML content / 发出处理后的 HTML 内容的 Mono
      */
     Mono<String> spacingElementById(String htmlContent, String id);
@@ -42,7 +42,7 @@ public interface ExtraApiPanguFinder {
      * 对 HTML 内容中具有指定 class 的元素应用 Pangu 空格。
      *
      * @param htmlContent the HTML content to process / 要处理的 HTML 内容
-     * @param className   the class name to process / 要处理的 class 名称
+     * @param className the class name to process / 要处理的 class 名称
      * @return Mono emitting processed HTML content / 发出处理后的 HTML 内容的 Mono
      */
     Mono<String> spacingElementByClassName(String htmlContent, String className);

src/main/java/top/howiehz/halo/plugin/extra/api/finder/basic/impl/ExtraApiPanguFinderImpl.java

@@ -22,24 +22,24 @@
 @RequiredArgsConstructor
 @Finder("extraApiPanguFinder")
 public class ExtraApiPanguFinderImpl implements ExtraApiPanguFinder {
-    
+
     private final PanguSpacingService panguSpacingService;
 
     @Override
     public Mono<String> spacingElementByTagName(String htmlContent, String tagName) {
-        return Mono.fromCallable(() -> 
+        return Mono.fromCallable(() ->
             panguSpacingService.spacingElementByTagName(htmlContent, tagName));
     }
 
     @Override
     public Mono<String> spacingElementById(String htmlContent, String id) {
-        return Mono.fromCallable(() -> 
+        return Mono.fromCallable(() ->
             panguSpacingService.spacingElementById(htmlContent, id));
     }
 
     @Override
     public Mono<String> spacingElementByClassName(String htmlContent, String className) {
-        return Mono.fromCallable(() -> 
+        return Mono.fromCallable(() ->
             panguSpacingService.spacingElementByClassName(htmlContent, className));
     }
 

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

@@ -57,16 +57,16 @@ public Mono<BigInteger> getPostWordCount(Map<String, Object> params) {
     public Mono<BigInteger> getContentWordCount(Map<String, Object> params) {
         Map<String, Object> map = params == null ? java.util.Collections.emptyMap() : params;
         Object htmlContentObj = map.get("htmlContent");
-        
+
         if (htmlContentObj == null) {
             return Mono.just(BigInteger.ZERO);
         }
-        
+
         String htmlContent = String.valueOf(htmlContentObj);
         if ("null".equals(htmlContent) || htmlContent.isBlank()) {
             return Mono.just(BigInteger.ZERO);
         }
-        
+
         return Mono.fromCallable(() -> PostWordCountUtil.countHTMLWords(htmlContent))
             .onErrorReturn(BigInteger.ZERO);
     }

src/main/java/top/howiehz/halo/plugin/extra/api/service/basic/post/render/pangu/PanguPostContentRenderHandler.java

@@ -27,7 +27,7 @@
 @Component
 @RequiredArgsConstructor
 public class PanguPostContentRenderHandler implements ReactivePostContentHandler {
-    
+
     private final PanguSpacingService panguSpacingService;
     private final Supplier<Mono<PanguConfig>> panguConfigSupplier;
 
@@ -47,20 +47,20 @@ public Mono<PostContentContext> handle(@NotNull PostContentContext contentContex
                     log.debug("Pangu auto-render is disabled, skipping processing");
                     return Mono.just(contentContext);
                 }
-                
+
                 return Mono.fromCallable(() -> {
                     try {
                         String originalContent = contentContext.getContent();
-                        
+
                         // 对 <p> 标签应用 Pangu 空格处理
                         String processedContent = panguSpacingService.spacingElementByTagName(
                             originalContent, "p");
-                        
+
                         contentContext.setContent(processedContent);
-                        
+
                         log.debug("Successfully applied Pangu spacing to post content");
                         return contentContext;
-                        
+
                     } catch (Exception e) {
                         log.error("Error occurred while applying Pangu spacing: {}",
                             Throwables.getStackTraceAsString(e));

src/main/java/top/howiehz/halo/plugin/extra/api/service/basic/post/render/pangu/PanguSinglePageContentRenderHandler.java

@@ -27,7 +27,7 @@
 @Component
 @RequiredArgsConstructor
 public class PanguSinglePageContentRenderHandler implements ReactiveSinglePageContentHandler {
-    
+
     private final PanguSpacingService panguSpacingService;
     private final Supplier<Mono<PanguConfig>> panguConfigSupplier;
 
@@ -47,20 +47,20 @@ public Mono<SinglePageContentContext> handle(@NotNull SinglePageContentContext c
                     log.debug("Pangu auto-render is disabled, skipping processing");
                     return Mono.just(contentContext);
                 }
-                
+
                 return Mono.fromCallable(() -> {
                     try {
                         String originalContent = contentContext.getContent();
-                        
+
                         // 对 <p> 标签应用 Pangu 空格处理
                         String processedContent = panguSpacingService.spacingElementByTagName(
                             originalContent, "p");
-                        
+
                         contentContext.setContent(processedContent);
-                        
+
                         log.debug("Successfully applied Pangu spacing to single page content");
                         return contentContext;
-                        
+
                     } catch (Exception e) {
                         log.error("Error occurred while applying Pangu spacing: {}",
                             Throwables.getStackTraceAsString(e));

src/main/java/top/howiehz/halo/plugin/extra/api/service/basic/post/render/pangu/PanguSpacingService.java

@@ -18,7 +18,7 @@ public interface PanguSpacingService {
      * 对 HTML 内容中的指定标签元素应用 Pangu 空格。
      *
      * @param htmlContent the HTML content to process / 要处理的 HTML 内容
-     * @param tagName     the tag name to process (e.g., "p", "div") / 要处理的标签名称（例如 "p"、"div"）
+     * @param tagName the tag name to process (e.g., "p", "div") / 要处理的标签名称（例如 "p"、"div"）
      * @return processed HTML content / 处理后的 HTML 内容
      */
     String spacingElementByTagName(String htmlContent, String tagName);
@@ -28,7 +28,7 @@ public interface PanguSpacingService {
      * 对 HTML 内容中具有指定 ID 的元素应用 Pangu 空格。
      *
      * @param htmlContent the HTML content to process / 要处理的 HTML 内容
-     * @param id          the element ID to process / 要处理的元素 ID
+     * @param id the element ID to process / 要处理的元素 ID
      * @return processed HTML content / 处理后的 HTML 内容
      */
     String spacingElementById(String htmlContent, String id);
@@ -38,7 +38,7 @@ public interface PanguSpacingService {
      * 对 HTML 内容中具有指定 class 的元素应用 Pangu 空格。
      *
      * @param htmlContent the HTML content to process / 要处理的 HTML 内容
-     * @param className   the class name to process / 要处理的 class 名称
+     * @param className the class name to process / 要处理的 class 名称
      * @return processed HTML content / 处理后的 HTML 内容
      */
     String spacingElementByClassName(String htmlContent, String className);