MooTool next-compose F03 格式化验收:JVM 解析器驱动的 Nginx/Java/XML/HTML 多语言格式化实战

原创2026-10-15 14:27:391,986 阅读
文章标签:开发工具桌面应用MCP 服务

MooTool next-compose F03 格式化验收:JVM 解析器驱动的 Nginx/Java/XML/HTML 多语言格式化实战

本篇围绕 MooTool next-compose(Jetpack Compose for Desktop 产品线)F03「格式化」功能的验收记录展开:它如何在不依赖 Node/Prettier 的前提下,用 JavaParser、JAXP 与 Jsoup 实现四种语言的格式化引擎,并通过文本/文件双 Tab、后台线程 generation 守卫、语法错误行列定位、另存不覆盖等完整 UI 语义对齐 Electron 版行为。读完本篇,你可以掌握一个桌面端多语言 formatter 从依赖选型、引擎实现到界面接线与测试验收的完整技术链路。

验收范围:F03 格式化(P3 本地算法)

本次验收的阶段与条目为 F03 格式化(P3 本地算法),工作树限定为 next-compose/ 子目录,即 Compose 桌面版产品线;Electron 版(next/)仅作参考实现,不参与本次构建。

关键事实如下:

  • 依赖:com.github.javaparser:javaparser-core:3.26.4、org.jsoup:jsoup:1.18.3,版本由 版本目录 统一管理(javaParser = "3.26.4"、jsoup = "1.18.3");
  • 参考:Electron 的 reformatTools.ts 与 ReformatTool.tsx,其中 Nginx tokenizer 按 Electron 版逐逻辑移植;
  • 已执行:在 JAVA_HOME 指向 Zulu 21.0.12.1 的环境下运行 ./gradlew :composeApp:desktopTest,56/56 全部通过,其中 ReformatEngineTest 贡献 6 个用例;
  • 差异声明:DIFF-005(JavaParser / JAXP / Jsoup,不使用 Prettier);
  • 未测项:窗口截图、大文件、真实保存失败路径的手工对话框、分离窗口手工验证、重启 UI;
  • 下一轮计划:F06 配置转换或 F07 Protobuf;F04 Git 仍待做。

功能语义覆盖:文本/文件 Tab;Nginx/Java/XML/HTML 四种类型;缩进 2–6;格式化在后台线程执行,按 generation 丢弃过期结果;语法错误保留原文并显示行列;保存走另存对话框,默认不覆盖原文件;写入失败可重试;历史与 Cmd/Ctrl+Shift+F 快捷键;分离窗口支持。

DIFF-005:为什么用 JVM 解析器而不是 Prettier

架构差异记录见 005-reformat-jvm.md,其核心决策是:Compose 版不复用 Electron 的 prettier/standalone 运行时。Electron 版中 Java 走 prettier-plugin-java、XML 走 @prettier/plugin-xml(xmlWhitespaceSensitivity: preserve)、HTML 走 prettier/plugins/html,语法错误由 Prettier 抛出,Nginx 则是自写 tokenizer 不经 Prettier。

Compose 版的选择理由:架构要求独立声明的 Java 语法处理器和专用 HTML/XML/Nginx 实现,禁止把 Electron 的 Prettier 当运行时依赖——这意味着使用者无需安装 Node。具体映射如下:

语言 Electron 实现 Compose 实现 关键行为
Nginx 自写 tokenizer 移植 tokenizeNginx / formatNginx 引号、注释、转义、块层级与 Electron 一致
Java prettier-plugin-java javaparser-core 3.26.4 + PrettyPrinter 缩进 1–8 空格生效;语法错误抛出行列,不改原文
XML @prettier/plugin-xml JAXP 解析(禁用 DTD/外部实体)+ 自写缩进 元素子节点缩进,混合文本节点保持同行;DOCTYPE 拒绝
HTML prettier/html Jsoup 解析 + 同规则缩进 Jsoup 会修复残缺 HTML 树,因此不把修复当失败

受影响范围同样被明确记录:Java 换行/空行风格与 prettier-plugin-java 不同,输出语义由 AST 重印决定;畸形 HTML 可能被 Jsoup 修好后输出,而不是保留原文报错;含 DOCTYPE 的 XML 被直接拒绝(防 XXE),而 Electron Prettier 可能仍能格式化。

引擎实现:ReformatEngine 的四个格式化器

引擎主体在 ReformatEngine.kt,对外暴露统一入口:

enum class ReformatType { Nginx, Java, Xml, Html }

class ReformatException(
    val code: String,   // 固定为 "syntax"
    message: String,
    val line: Int = -1,
    val column: Int = -1
) : RuntimeException(message)

fun format(input: String, type: ReformatType, indent: Int = 4): String {
    if (input.trim().isEmpty()) return ""
    val tabWidth = indent.coerceIn(1, 8)   // 引擎层钳制 1–8,UI 层只暴露 2–6
    return when (type) { /* 分发到四个格式化器 */ }
}

Nginx:手工 tokenizer + 块层级计数

formatNginx 的策略是把整份配置切成「按行分发的 token」再按块层级重新缩进:

val tokens = tokenizeNginx(input)
var level = 0
for (token in tokens) {
    if (token == "}") level = maxOf(0, level - 1)
    if (token.isNotEmpty()) lines += "${" ".repeat(level * tabWidth)}$token"
    if (token.endsWith("{")) level += 1
}

tokenizeNginx 是一个单遍状态机,显式维护 quote(单/双引号配对)、escaped(反斜杠转义)、comment(# 行注释到换行)三个状态,保证引号内的花括号、注释内的分号都不会被误切成边界;{、}、;、换行符触发 flush。测试用例特意覆盖了 set $msg "brace { inside }";、return 200 'ok\'d';、中文注释 # 端口 和 emoji 头 Moo工具 😺,并断言二次格式化结果幂等,验证了与 Electron fixture 的逐字一致性。

Java:JavaParser AST 重印 + 缩进与错误定位

val configuration = DefaultPrinterConfiguration()
    .addOption(DefaultConfigurationOption(ConfigOption.INDENTATION, Indentation(Indentation.IndentType.SPACES, indent)))
    .addOption(DefaultConfigurationOption(ConfigOption.END_OF_LINE_CHARACTER, "\n"))
val printer = DefaultPrettyPrinter(configuration)
val unit = try {
    StaticJavaParser.parse(input)
} catch (error: ParseProblemException) {
    val problem = error.problems.firstOrNull()
    val begin = problem?.location?.orElse(null)?.begin?.range?.orElse(null)?.begin
    throw ReformatException("syntax", ..., line = begin?.line ?: -1, column = begin?.column ?: -1)
}

缩进通过 DefaultPrinterConfiguration 的 INDENTATION 选项注入空格宽度,换行符固定为 \n;解析失败时从 ParseProblemException 的第一条问题中提取位置,抛出携带 line/column 的 ReformatException("syntax", ...),UI 层据此在状态栏显示行列,且不修改原文。

XML:JAXP 安全解析 + 自写缩进

XML 路径的核心是 secureDocumentBuilder(),它显式加固解析器以防 XXE:

factory.isExpandEntityReferences = false
factory.isXIncludeAware = false
runCatching { factory.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true) }
runCatching { factory.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true) }
runCatching { factory.setFeature("http://xml.org/sax/features/external-general-entities", false) }
runCatching { factory.setFeature("http://xml.org/sax/features/external-parameter-entities", false) }
runCatching { factory.setAttribute(XMLConstants.ACCESS_EXTERNAL_DTD, "") }

disallow-doctype-decl 即验收记录中「DOCTYPE 拒绝」的来源;解析错误由 SAXParseException 直接映射为带 lineNumber/columnNumber 的 ReformatException。缩进逻辑区分三种情形:无元素子节点时内联输出(如 <item>moo 文本</item> 保持一行);含非空白文本或 CDATA 的混合节点保持同行;纯元素子节点才逐层缩进换行。XML 声明 <?xml ...?> 会按解析后的 version/encoding 重建输出。

HTML:Jsoup 修复树 + 同规则缩进

formatHtml 用 Jsoup.parse(input, "", Parser.htmlParser()) 解析后关闭 prettyPrint,自行按与 XML 相同的规则遍历 body().childNodes() 输出。关键差异在于 Jsoup 对残缺 HTML 会修复 DOM 树(例如补齐闭合标签),因此设计上不把修复当失败——代价是无法像 Prettier 那样对全部畸形 HTML 给出语法错误行列。script、style 与含文本的子节点一律内联,避免破坏内容。

UI 接线:双 Tab、generation 守卫与错误语义

界面实现位于 ReformatScreen.kt,验收记录中的每条语义都能在源码中找到对应:

  • 文本/文件 Tab:session.tab 为 "text" 或 "file"。文件 Tab 支持选择/拖拽导入(FileDropRow),导入后由 inferTypeFromFileName 按扩展名推断类型(conf/nginx→Nginx,java→Java,xml/xsd/svg→XML,html/htm→HTML),左右分栏展示原文与结果,分栏宽度可拖拽并持久化。
  • 缩进 2–6:工具栏菜单只暴露 listOf(2, 3, 4, 5, 6);SessionManager.kt 中 ReformatSession.restore 对快照缩进执行 coerceIn(2, 6),与引擎层的 1–8 钳制形成两级约束。
  • 后台线程 + generation 守卫:runFormat 先自增 session.formatGeneration 并快照当前 generation/type/indent/tab,在 container.scope.launch 中调用 ReformatWiringPresentation.runFormat,回到 Dispatchers.Swing 后执行 if (generation != session.formatGeneration) return@withContext——用户连点格式化或中途切换类型时,过期结果被直接丢弃,不会覆盖新输入。
  • 语法错误保留原文并显示行列:失败分支调用 formatErrorMessage,当 ReformatException.line >= 1 时选用 reformat.error.located 消息模板并填充 line/column 参数,否则回退 reformat.error.generic;原文始终未被引擎修改。
  • 另存不覆盖原文件:saveResult 走 chooseFileWithExportDirectory(save = true, ...) 弹另存对话框,默认文件名由 defaultSaveFileName 生成(源文件名去扩展名 + 按类型映射的 conf/java/xml/html),成功/失败均有 toast 与状态提示,写入失败可通过再次点击另存重试。
  • 历史与快捷键:每次成功格式化后以 ReformatHistoryMetadata.encode(type, tab, indent, fileName) 编码 options 存入历史;工具栏「历史」按钮打开 HistoryBrowser,恢复时 ReformatHistoryRestore.kt 解码 options 并回填 tab/type/indent/原文/结果。整屏注册了 Cmd/Ctrl+Shift+F 预览键事件触发格式化(IME 激活时不拦截)。
  • 分离窗口:detached 参数控制工具栏「分离」入口;分离状态下隐藏该入口并在状态栏标注 detached。

UI 守卫逻辑集中在 ReformatWiringPresentation.kt:formatActionEnabled 要求「不忙且有非空输入」,复制/另存按钮要求当前 Tab 有输出——与 Electron disabled={busy || !input.trim()} 的判定保持一致。历史 options 采用 type|tab|indent|fileName? 的管道编码(ReformatHistoryMetadata.kt),与 Electron ReformatTool 的历史格式对齐,便于两版历史互通。

测试证据:56/56 通过中的 6 个引擎用例

验收命令为 JAVA_HOME(Zulu 21.0.12.1)下 ./gradlew :composeApp:desktopTest,整任务 56/56 通过。其中 ReformatEngineTest.kt 的 6 个用例与 DIFF-005 的证据描述一一对应:

  1. formatsNginxBlocksAndStatementsLikeElectron:Electron Nginx fixture 逐字断言,2 空格缩进下的块层级输出与预期完全一致;
  2. keepsNginxQuotesCommentsEscapesAndUnicode:引号内花括号、中文注释、转义引号、Unicode emoji 保留,且二次格式化幂等;
  3. formatsJavaWithRealParserAndHonorsIndent:class Demo + System.out.println("moo"); 样本经真实解析器重印,2 空格缩进生效且幂等;
  4. formatsXmlAndHtmlAndKeepsTextNodes:XML <item id="1">moo 文本</item> 缩进与文本节点同行保持,HTML <strong>Moo</strong> 结构保留,均幂等;
  5. keepsOriginalOnJavaAndXmlSyntaxErrorsAndReportsLocation:非法 Java(void broken()与非法 XML(<root><item></root>)均抛出 code == "syntax" 且 line >= 1 的 ReformatException;
  6. returnsEmptyForBlankInput:空白输入返回空串。

此外 ReformatWiringPresentationTest 覆盖了 UI 守卫、默认另存文件名、扩展名推断等接线逻辑,acceptance.md 中 F03 条目的状态可参见 acceptance.md。

未测项与后续计划

验收记录如实标注了本轮未覆盖的验证:窗口截图、大文件性能、真实保存失败路径的手工对话框、分离窗口手工操作、以及应用重启后的 UI 状态。这些属于需要真实交互或环境的验证项,不在本次自动化测试范围内。

下一轮验收计划为 F06 配置转换或 F07 Protobuf;F04 Git 仍处于待做状态。从 acceptance.md 的 P3 阶段状态看,F03 属于「已有引擎单测与 UI」的本地算法工具集合之一,F04 Git(本地 CLI checkpoint 方案)是后续的关键缺口。

小结

F03 格式化验收展示了 Compose 产品线「对齐 Electron 语义、替换运行时实现」的典型做法:Nginx 移植自写 tokenizer 保证逐字一致,Java 交给 JavaParser 获得缩进控制与行列级错误定位,XML 用加固的 JAXP 解析器换取 XXE 防护与 DOCTYPE 拒绝,HTML 则接受 Jsoup 修复树的代价换取对残缺输入的宽容。引擎纯函数化(ReformatEngine)、接线逻辑可单测化(ReformatWiringPresentation)、UI 守卫与 generation 机制保证并发安全,配合 56/56 的 desktopTest 结果,构成了一条可复现、可追溯的多语言桌面格式化实现路径。

登录后查看全文
MooTool