feat: add JNI HTML minify web filter and harden plugin config defaults (#90)

Author: HowieHz

CONTRIBUTING.md

@@ -24,6 +24,13 @@ pnpm dev
 ./gradlew build
 ```
 
+## 配置约定
+
+- 默认值设定由 `src/main/resources/extensions/settings.yaml` 统一定义。
+- 配置类、`fallbackConfig()`、配置提供方（Supplier）和运行时初始化逻辑中，不要重复写同一份业务默认值。
+- 设置缺失、读取失败或对象为空时，可以返回最小可用的兜底配置；但兜底配置不应再维护一份和 `settings.yaml` 并行的业务默认值。
+- 如果某个配置项在运行时可能出现非法值，并且会导致初始化失败，或者旧数据、脏数据可能绕过界面约束，应在消费前校验，必要时修正为可用值，而不是在配置类中再补一套默认值。
+
 ### 资源处理任务
 
 - __processUiResources__ - 处理UI前端资源，将ui子项目的构建输出复制到console目录
@@ -44,6 +51,19 @@ pnpm dev
 
 构建完成后，可以在 `build/libs` 目录找到插件 jar 文件。
 
+## 已知问题
+
+以下问题属于当前架构和上游依赖形态带来的限制，开发时需要明确认知。
+
+### HTML 页面压缩的响应体改写不是流式的
+
+- 相关实现：
+  - `src/main/java/top/howiehz/halo/plugin/extra/api/service/interop/web/filter/htmlminify/HtmlMinifyWebFilter.java`
+- 当前 HTML 页面压缩功能依赖 Halo 的附加 Web 过滤器扩展点（`AdditionalWebFilter`）完整读取并重写响应体。
+- 这意味着在压缩前必须先聚合完整的 HTML 响应内容，再交给 `minify-html` 处理。
+- 因此该功能天然会带来一次额外的内存占用和复制成本，无法像真正的流式转换那样边读边压。
+- 这不是当前实现的疏漏，而是 Halo 附加 Web 过滤器扩展点（`AdditionalWebFilter`）的接入方式和 `minify-html` 接口形态共同决定的限制。
+
 ## 如何添加新的嵌入式 JS 模块
 
 本项目将 JavaScript 工具嵌入到 Java 运行时中，并将其预加载到 Javet V8 运行时中。按照以下步骤添加对新 JS 模块的支持。
@@ -70,13 +90,13 @@ MARKED("marked", "marked.umd.js", JsModuleType.UMD),
 - 文件：`src/main/java/top/howiehz/halo/plugin/extra/api/service/interop/runtime/engine/CustomJavetEngine.java`
 - 引擎当前在 `preloadModules()` 中预加载 `Shiki`
 - 使用 `JsModule.MARKED.getSourceCode()` 读取资源，使用 `v8Runtime.getExecutor(code).executeVoid()` 执行。
-- 加载后，验证预期的函数是否暴露在 `globalThis`（或其他入口点）上。保持预加载对错误的容忍性，避免引擎创建失败。
+- 加载后，验证预期的函数是否暴露在 `globalThis` 这类全局入口上。保持预加载对错误的容忍性，避免引擎创建失败。
 
 ### 暴露 Java 服务来调用模块
 
 - 在 `service/interop/runtime/adapters/<module>` 下创建服务接口（示例 `service/interop/runtime/adapters/marked/MarkedService.java`），定义您需要的操作。
 - 使用 Spring `@Service` 类实现接口，该类使用现有的 `V8EnginePoolService` 对运行时执行调用，类似于 `ShikiHighlightServiceImpl`。
-- 优先读取 `globalThis` 函数（例如 `parseMarkdown`）或 `globalThis.<lib>.parse`。
+- 优先读取 `globalThis` 上的方法（例如 `parseMarkdown`）或 `globalThis.<lib>.parse`。
 
 ### 验证
 
@@ -85,7 +105,7 @@ MARKED("marked", "marked.umd.js", JsModuleType.UMD),
 
 ### 模块类型和自定义解析器
 
-- JsModuleType.UMD：直接执行脚本（UMD 通常附加到 globalThis）。
+- JsModuleType.UMD：直接执行脚本（UMD 通常会挂到 `globalThis` 上）。
 - JsModuleType.ESM：`CustomV8ModuleResolver` 编译并为 ESM 模块返回 IV8Module。
 - JsModuleType.CJS：CommonJS 模块使用模拟的 `module.exports` 对象执行，导出作为模块对象返回。
 
@@ -103,5 +123,5 @@ gradlew.bat clean assemble -x test
 
 - 保持嵌入的 JS 文件相对较小，以保持 jar 大小可管理。
 - 优先选择精简或压缩的 UMD 构建版本进行嵌入。
-- 如果库暴露异步 API（promises），Java 实现应该使用 Javet Promise 助手或 V8ValuePromise 轮询来等待 promise 结果。
+- 如果库暴露异步接口（Promise），Java 实现应使用 Javet 的 Promise 辅助工具或 `V8ValuePromise` 轮询等待结果。
 - 添加单元测试，使用模拟或引擎池来验证解析/高亮行为。

README.md

@@ -50,65 +50,20 @@
 - 无需主题适配即可使用的功能：
     - [中英文混排格式化处理器](#中英文混排格式化处理器)
     - [代码高亮处理器](#代码高亮处理器)（仅全量版可用）
+    - [HTML 页面压缩处理器](#html-页面压缩处理器)（仅全量版可用）
 - 提供给主题开发者使用的 Finder API：
     - [插件本体信息相关 API](#插件本体信息相关-api)
     - [文章字数统计 API（单篇/全站）](#文章字数统计-api)
     - [HTML 内容字数统计 API](#html-内容字数统计-api)
     - [中英文混排格式化 API](#中英文混排格式化-api)
     - [代码高亮 API](#代码高亮-api)（仅全量版可用）
 
-未来将实现的功能：[TODO](#todo)
-
 欢迎为此插件提 [Issue](https://github.com/HowieHz/halo-plugin-extra-api/issues/new)，任何你需要的功能都可以在此处提出，我将在能力范围内尽力实现。
 
 💖 支持本项目: 如果你觉得这个插件有用，点个 [Star](https://github.com/HowieHz/halo-plugin-extra-api) 就是对我最大的鼓励!
 
 感谢所有支持本项目的用户和开发者，也特别感谢 Halo CMS 团队为插件生态提供的优秀平台。
 
-## 文档目录
-
-- [API 扩展包](#api-扩展包)
-  - [简介](#简介)
-  - [核心理念](#核心理念)
-  - [功能介绍](#功能介绍)
-  - [文档目录](#文档目录)
-  - [Finder API 文档](#finder-api-文档)
-    - [文档类型定义](#文档类型定义)
-    - [插件本体信息相关 API](#插件本体信息相关-api)
-      - [检测本插件是否启用](#检测本插件是否启用)
-      - [插件版本检测 API](#插件版本检测-api)
-    - [统计信息 API](#统计信息-api)
-      - [文章字数统计 API](#文章字数统计-api)
-      - [HTML 内容字数统计 API](#html-内容字数统计-api)
-    - [渲染 API](#渲染-api)
-      - [中英文混排格式化 API](#中英文混排格式化-api)
-    - [渲染 API（需要 JS 运行时）](#渲染-api需要-js-运行时)
-      - [代码高亮 API](#代码高亮-api)
-  - [处理器文档](#处理器文档)
-    - [中英文混排格式化处理器](#中英文混排格式化处理器)
-      - [功能说明](#功能说明)
-      - [配置选项](#配置选项)
-      - [补充说明](#补充说明)
-    - [代码高亮处理器](#代码高亮处理器)
-      - [特点](#特点)
-      - [配置选项](#配置选项-1)
-      - [支持的主题](#支持的主题)
-      - [补充说明](#补充说明-1)
-  - [版本说明](#版本说明)
-    - [轻量版的优势](#轻量版的优势)
-    - [轻量版本缺少的功能](#轻量版本缺少的功能)
-  - [全量版使用须知](#全量版使用须知)
-    - [基本使用要求](#基本使用要求)
-    - [全量版已知问题](#全量版已知问题)
-      - [问题一解决方案](#问题一解决方案)
-  - [下载和安装](#下载和安装)
-    - [稳定版](#稳定版)
-    - [开发版](#开发版)
-      - [下载步骤](#下载步骤)
-  - [开发指南/贡献指南](#开发指南贡献指南)
-  - [TODO](#todo)
-  - [许可证](#许可证)
-
 ## Finder API 文档
 
 ### 文档类型定义
@@ -202,7 +157,7 @@ extraApiPluginInfoFinder.isJavaScriptAvailable()
     - 解释：轻量版时返回 true，全量版时返回 false
 - `getVersionType()`
     - 类型：`string`
-    - 解释：返回 "full" 或 "lite"
+    - 解释：返回 `"full"`（全量版）或 `"lite"`（轻量版）
 - `isJavaScriptAvailable()`
     - 类型：`boolean`
     - 解释：JavaScript 功能可用时返回 true
@@ -212,7 +167,7 @@ extraApiPluginInfoFinder.isJavaScriptAvailable()
 - 检测原理
     - 通过检查 `V8EnginePoolService` 类是否存在来判断版本类型：
         - 全量版：包含 JavaScript 运行时，V8EnginePoolService 类存在
-        - 轻量版：构建时排除 interop 包下所有类，V8EnginePoolService 类不存在
+        - 轻量版：构建时排除原生运行时相关包（`interop` 包）下所有类，`V8EnginePoolService` 类不存在
 - 应用场景
     - 主题兼容性：主题可以根据插件版本提供不同的功能体验
     - 用户提示：向用户说明当前版本的功能限制
@@ -638,7 +593,7 @@ extraApiJsRenderFinder.highlightCodeInHtml(htmlContent)
 此处理器默认启用。开箱即用，无需额外配置。
 
 在“插件设置 - 中英文混排格式化”提供以下配置项：
-- 自动渲染: 启用之后会自动处理文章和单页中段落标签的中英文混排格式，在中日韩字符与英文、数字、符号之间自动插入空格。注：Finder API 渲染不受此配置项影响。
+- 自动渲染：启用后会自动处理文章和单页中段落标签的中英文混排格式，在中日韩字符与英文、数字、符号之间自动插入空格。通过 Finder 接口调用时不受此配置项影响。
 
 #### 补充说明
 
@@ -680,19 +635,19 @@ extraApiJsRenderFinder.highlightCodeInHtml(htmlContent)
 #### 配置选项
 
 在“插件设置 - 代码高亮（仅全量版可用）”提供以下配置项：
-- 自动渲染: 启用之后会自动渲染文章和单页中的代码块。注：Finder API 渲染不受此配置项影响。
-- 自定义注入 CSS 样式：启用自动渲染时将在页面 head 注入样式以优化 Shiki 渲染效果，默认值提供了边距调整/行号显示/基于媒体查询的明暗切换功能。
-    - 额外注入规则: 指定额外的页面路径规则，支持通配符。
-        - 默认包含: `/moments/**`, `/docs/**`
+- 自动渲染：启用后会自动渲染文章和单页中的代码块。通过 Finder 接口调用时不受此配置项影响。
+- 自定义注入 CSS 样式：启用自动渲染时，会在页面 `head` 标签中注入样式，以优化 Shiki 渲染效果。默认值提供了边距调整、行号显示，以及基于媒体查询的明暗切换功能。
+    - 额外注入规则：指定额外的页面路径规则，支持通配符。
+        - 默认包含：`/moments/**`, `/docs/**`
         - 支持自定义路径，如 `/custom/**`
 - 明暗双倍渲染模式切换：
-    - 单主题模式:
-        - 主题: 选择单个代码高亮主题
-    - 双主题模式:
-        - 亮色主题: 浅色模式使用的主题
-        - 暗色主题: 深色模式使用的主题
-        - 亮色主题代码块类名: 浅色代码块的 CSS 类名
-        - 暗色主题代码块类名: 深色代码块的 CSS 类名
+    - 单主题模式：
+        - 主题：选择单个代码高亮主题
+    - 双主题模式：
+        - 亮色主题：浅色模式使用的主题
+        - 暗色主题：深色模式使用的主题
+        - 亮色主题代码块类名：浅色代码块的 CSS 类名
+        - 暗色主题代码块类名：深色代码块的 CSS 类名
 
 #### 支持的主题
 
@@ -731,11 +686,66 @@ extraApiJsRenderFinder.highlightCodeInHtml(htmlContent)
 - 补充说明：
     - 双主题模式会生成两个并列的 div 元素
 
+### HTML 页面压缩处理器
+
+插件提供了自动化的 HTML 页面压缩处理器，无需在模板中手动调用，即可在服务端对前台 HTML 响应进行整体压缩。
+
+此功能通过 [minify-html](https://github.com/wilsonzlin/minify-html) 的 Java JNI 绑定实现，仅在[全量版](#版本说明)中可用。
+
+#### 特点
+
+- 压缩范围：
+    - 仅处理 `GET` 请求返回的 HTML 页面响应
+    - 仅处理 `text/html` 且未经过 `gzip/br` 等编码的响应
+    - 默认跳过后台、API、静态资源等路径，避免误处理非页面响应
+- 安全边界：
+    - 非 UTF-8 响应会自动跳过，避免字符集被破坏
+    - 已编码响应会自动跳过，避免破坏上游压缩结果
+    - 压缩失败时自动回退原始 HTML，不影响页面正常返回
+- 性能说明：
+    - 处理器会完整读取并重写 HTML 响应体，因此会带来一定 CPU 与内存开销
+    - 压缩工作会切换到 Reactor 的弹性线程池（`boundedElastic`），避免阻塞处理请求的线程
+    - 更适合体积较大、访问量稳定、希望进一步压缩 HTML 传输体积的站点
+
+#### 配置选项
+
+在“插件设置 - HTML 页面压缩（仅全量版可用）”提供以下配置项：
+
+- 自动压缩：启用之后会在服务端对前台 HTML 页面响应做整体压缩。
+- 排除路径规则：
+    - 支持 Ant 风格路径匹配，支持 `*` 和 `**`
+    - 默认包含：`/console/**`、`/uc/**`、`/login/**`、`/signup/**`、`/logout/**`、`/themes/**`、`/plugins/**`、`/actuator/**`、`/api/**`、`/apis/**`、`/upload/**`
+- 常规安全压缩选项：
+    - 压缩内联 CSS
+    - 压缩内联 JavaScript
+    - 保留花括号模板语法
+    - 保留 `<% %>` 模板语法
+    - 保留可省略闭合标签
+    - 保留 HTML 注释
+    - 保留 `html/head` 起始标签
+    - 保留 `input[type=text]` 属性
+    - 保留 SSI 注释
+    - 移除 Bang 声明
+    - 移除处理指令
+- 更激进的压缩选项（默认关闭），这些选项可能生成无法通过严格 HTML 校验、但仍可被主流浏览器按 WHATWG 解析规范正确渲染的输出：
+    - 压缩 DOCTYPE
+    - 允许非规范无引号属性值
+    - 允许更激进的实体优化
+    - 允许移除属性间空格
+
+关于配置项的原始文档可参考 [minify_html](https://docs.rs/minify-html/latest/minify_html/struct.Cfg.html)。
+
+#### 补充说明
+
+- 此功能使用 [minify-html](https://github.com/wilsonzlin/minify-html) 库实现
+- 处理器只影响页面响应输出，不会修改数据库中的原始内容
+- 如果站点已由 CDN、反向代理或上游网关统一处理 HTML 压缩，请避免重复启用
+
 ## 版本说明
 
 插件提供两个版本：
 
-- **全量版**：包含所有功能，包括代码高亮等依赖 JS 的相关功能。
+- **全量版**：包含所有功能，包括代码高亮、HTML 页面压缩等依赖原生运行时的功能。
 - **轻量版**：轻量级版本，不包含 JS 相关功能和相关依赖。
 
 ### 轻量版的优势
@@ -749,6 +759,7 @@ extraApiJsRenderFinder.highlightCodeInHtml(htmlContent)
 ### 轻量版本缺少的功能
 
 - 代码高亮（Shiki.js 渲染）
+- HTML 页面压缩（minify-html JNI）
 
 <!-- - 图表渲染（Mermaid）
 - 公式渲染（KaTeX） -->
@@ -912,18 +923,6 @@ ERROR - JavetException: Javet library is not loaded because <null>
 
 参见 [CONTRIBUTING.md](./CONTRIBUTING.md)
 
-## TODO
-
-<details><summary>展开折叠内容</summary>
-
-- [ ] 提供随机文章 API
-- [ ] 提供预计阅读时间 API，及相关配置项
-- [ ] 提供图表渲染 API
-- [ ] 提供公式渲染 API
-- [ ] 分离 Node.js 环境支持为可选前置插件（预计 4.0 版本实现）
-
-</details>
-
 ## 许可证
 
 [AGPL-3.0](./LICENSE) © HowieHz

build.gradle

@@ -43,6 +43,35 @@ def platforms = [
     'Windows-x86_64': ['windows-x86_64']
 ]
 
+def minifyHtmlNativeLibsByVariant = [
+    'Linux-arm64'   : 'linux-aarch64.nativelib',
+    'Linux-x86_64'  : 'linux-x64.nativelib',
+    'Macos-arm64'   : 'mac-aarch64.nativelib',
+    'Macos-x86_64'  : 'mac-x64.nativelib',
+    'Windows-x86_64': 'win-x64.nativelib'
+]
+
+def runtimeClasspathTrees = { configuration, String selectedMinifyHtmlNativeLib = null ->
+    configuration.resolvedConfiguration.resolvedArtifacts.collect { artifact ->
+        def artifactFile = artifact.file
+        if (artifactFile.isDirectory()) {
+            return artifactFile
+        }
+        def artifactTree = zipTree(artifactFile)
+        if (artifact.moduleVersion.id.group == 'in.wilsonl.minifyhtml'
+            && artifact.name == 'minify-html'
+            && selectedMinifyHtmlNativeLib != null) {
+            return artifactTree.matching {
+                exclude { details ->
+                    details.path.endsWith('.nativelib')
+                        && details.path != selectedMinifyHtmlNativeLib
+                }
+            }
+        }
+        return artifactTree
+    }
+}
+
 // 为每个平台创建专用配置，继承 runtimeClasspath 以保证依赖一致性
 platforms.each { variant, platformList ->
     configurations.create("javet${variant}") {
@@ -64,6 +93,11 @@ configurations {
     javetAllPlatforms {
         extendsFrom configurations.runtimeClasspath
     }
+    liteRuntimeClasspath {
+        extendsFrom configurations.runtimeClasspath
+        exclude group: 'com.caoccao.javet'
+        exclude group: 'in.wilsonl.minifyhtml', module: 'minify-html'
+    }
 }
 
 dependencies.add('javetAllPlatforms', 'com.caoccao.javet:javet:5.0.6')
@@ -80,6 +114,7 @@ dependencies {
 
     // JavaScript 引擎 - 为什么选择 Javet：支持 Node.js 模块，性能好，维护活跃
     implementation 'com.caoccao.javet:javet:5.0.6'
+    implementation 'in.wilsonl.minifyhtml:minify-html:0.18.1'
 
     // Pangu - 自动在中日韩字符和英文、数字、符号之间添加空格，提升可读性
     implementation 'ws.vinta:pangu:1.1.0'
@@ -245,10 +280,8 @@ afterEvaluate {
             exclude 'js/**'
             exclude 'extensions/extension-definitions*.yaml' // 变体扩展定义由专门任务生成
         }
-        // 排除 Javet 依赖 - 轻量版不需要 interop 运行时，减少 JAR 大小
-        from configurations.runtimeClasspath.filter { 
-            !it.name.contains('javet')
-        }.collect { 
+        // 排除部分依赖 - 轻量版不需要 interop 运行时，减少 JAR 大小
+        from configurations.liteRuntimeClasspath.collect {
             it.isDirectory() ? it : zipTree(it)
         }
         into('extensions') {
@@ -276,9 +309,7 @@ afterEvaluate {
             exclude 'extensions/extension-definitions-core.yaml'
             exclude 'extensions/extension-definitions-interop.yaml'
         }
-        from configurations.javetAllPlatforms.collect {
-            it.isDirectory() ? it : zipTree(it)
-        }
+        from(runtimeClasspathTrees(configurations.javetAllPlatforms))
         into('extensions') {
             from generateFullExtensionDefinitionsTask
             rename { 'extension-definitions.yaml' }
@@ -299,6 +330,7 @@ afterEvaluate {
         def configName = "javet${variant}"
         def archiveName = "extra-api-full-${variant.toLowerCase()}-${project.version}.jar"
         def indexTaskName = "generatePluginComponentsIdx${taskName.capitalize()}"
+        def minifyHtmlNativeLib = minifyHtmlNativeLibsByVariant[variant]
 
         tasks.register(taskName, Jar) {
             group = 'build'
@@ -309,9 +341,7 @@ afterEvaluate {
                 exclude 'extensions/extension-definitions-core.yaml'
                 exclude 'extensions/extension-definitions-interop.yaml'
             }
-            from configurations.getByName(configName).collect {
-                it.isDirectory() ? it : zipTree(it)
-            }
+            from(runtimeClasspathTrees(configurations.getByName(configName), minifyHtmlNativeLib))
             into('extensions') {
                 from generateFullExtensionDefinitionsTask
                 rename { 'extension-definitions.yaml' }