MooTool Next 版 JSON 工具 Java Parity 对齐实战解析：功能清单、实现原理与验证证据

• 桌面应用
• 开发工具

本篇技术指南以仓库文档 next/doc/parity/json.md 为骨架，全面梳理 MooTool Next（Electron + React）版本 JSON 工具与 Java 基线版本（github-develop-ts分支）之间的功能对齐（Parity）工作：包括 16 项核心功能清单、三栏布局视觉要求、自动化证据体系以及剩余人工出口条件。通过结合 jsonTools.ts、jsonVaultRepository.ts、vaultGitService.ts 等源码实现，读者将能理解每一项能力的底层实现原理、配置参数含义与验证方式。

1. Parity 文档背景与阶段定位

该 Parity Checklist 文档记录了 JSON 工具在 Next 版本中的实现状态，属于项目 Java Parity 迁移计划 的一个组成部分，覆盖阶段为P2 + P7。文档状态为“实现完成，待 Java 人工布局签收”，最后更新于 2026-07-16。

从文档结构可以看出，这是一份典型的对照签收清单：以 Java 版 JSON 工具为基线，逐项核对 Next 版功能是否对齐。其核心价值在于：

• 以功能清单（第 1 节）锁定行为等价；
• 以布局视觉要求（第 2 节）锁定交互心智一致；
• 以自动化证据（第 3 节）锁定质量可回归；
• 以人工出口条件（第 4 节）锁定最终签收门槛。

2. 功能清单：16 项 JSON 能力及其源码实现

功能清单表是文档的主体，从“Java 基线”与“Next 当前状态”两列展示了每一项能力的对齐情况。下面结合源码逐一展开其实现细节。

2.1 格式化/压缩与自动换行

Java 基线提供缩进与压缩两种操作；Next 当前状态支持 2/4 空格缩进、自定义格式，以及从编辑器设置读取换行状态。

核心实现位于 jsonTools.ts：

• formatJson(input, t, spaces = 2)：调用JSON.stringify(parseJson(input, t), null, spaces)完成缩进格式化，默认 2 空格；
• compressJson(input, t)：调用JSON.stringify(parseJson(input, t))去掉所有空白；
• formatJsonAdvanced(input, t, options)：支持JsonFormatOptions组合（spaces、sortKeys、ignoreCase、checkDuplicateKeys），并会在启用checkDuplicateKeys时先行检测重复 Key。

换行状态wrap由编辑器设置settings.editor.softWrap初始化，并通过工具栏按钮切换，写入会话级 UI 状态（见 JsonTool.tsx）。

2.2 复制/清空

工具栏提供复制与清空操作，复制成功/失败通过 Tooltip 与 Toast 反馈（copyState：idle | copied | failed），清空则重置编辑器内容。相关事件绑定在 JsonToolbar.tsx 的onCopy与onClear。

2.3 JSON/字符串转义

Java 基线支持转义、还原；Next 当前状态区分了两条路径：

• JSON 字符串路径：escapeJsonString（JSON.stringify(input)）、unescapeJsonString（校验解析结果为字符串后还原）；
• Java 字符串路径：escapeJavaString将\、\b、\f、\n、\r、\t、"逐一转义为 Java 字面量写法；unescapeJsonText先消费已存在的转义对以保持引号完整，再包上双引号交给JSON.parse还原。

测试 jsonTools.test.ts 覆盖了含中文引号、C:\Users\bob\、\u0041实际换行/制表符、\"与\\"等边界输入，并验证非法序列（\x、尾部悬空\）会抛错。

2.4 语法校验

validateJson(input, t)返回三态JsonStatus：输入为空时为idle；解析成功时区分Array / Object / 标量类型并返回valid；解析失败时返回error与错误消息。UI 层通过useMemo实时驱动状态栏图标（CheckCircle2 / XCircle / FileJson），见 JsonTool.tsx。

2.5 Key 排序 / 忽略大小写

formatJsonAdvanced在sortKeys开启时调用sortJsonKeys(parsed, ignoreCase)递归排序：

• 数组元素逐个递归；
• 对象按 Key 排序：ignoreCase开启时使用localeCompare(..., { sensitivity: 'base' })，否则普通字典序；
• 排序后的对象通过Object.fromEntries重建，保持值结构不变。

工具栏/高级面板中对应两个复选框选项（见 JsonInspector.tsx）。

2.6 重复 Key 检查

文档描述为“保留路径的重复检测”。实现为独立的DuplicateKeyParser类（jsonTools.ts）：它不依赖 JSON.parse 的对象覆盖语义，而是手写递归解析器逐层扫描源文本，遇到重复 Key 即把包含完整路径的条目（如$.A、$.child.x）追加进结果数组；ignoreCase开启时先做小写归一化再比较。非法 Key 字符会以$.key["..."]括号下标形式输出路径。测试验证了'{"a":1,"A":2,"child":{"x":1,"x":2}}'在忽略大小写下可同时报出$.A与$.child.x。

2.7 Key/Value 互换

swapJsonKeysAndValues要求输入顶层是对象，然后对对象递归执行互换：数组值序列化为 JSON 字符串作为新 Key，非对象值String(item)作为新 Key，原 Key 作为新 Value。测试示例{"first":"one","second":2}互换后得到{one:"first", "2":"second"}。

2.8 JSON/XML 双向转换

基于fast-xml-parser库：

• jsonToXml：使用XMLBuilder，配置format: true（美化输出）、ignoreAttributes: false、suppressEmptyNode: true，并包一层root节点；
• xmlToJson：使用XMLParser，配置ignoreAttributes: false、parseTagValue: true、parseAttributeValue: true、trimValues: true，输出 2 空格缩进的 JSON。

2.9 JavaBean 双向转换

这是 JSON 工具与 Java 生态对接的核心能力，文档描述为“字段提取与合法嵌套 Java 类生成”：

• JavaBean → JSON（javaBeanToJson）：用字段正则匹配public/protected/private、static/final/transient/volatile修饰符后的类型与字段名，跳过serialVersionUID；再通过mockJavaValue生成类型化默认值——[]（数组/List/Set/Collection/Iterable）、{}（Map 族）、false（布尔）、0（数值/BigDecimal/BigInteger）、''（字符/String/CharSequence），未知类型为null；
• JSON → JavaBean（jsonToJavaBean）：根类名默认Root（可自定义className），按 JSON 推断 Java 类型——String → String、Boolean → Boolean、整数 →Long、浮点 →Double、数组 →List<T>（对象元素按单数化规则生成子类名，如books → List<Book>）、对象 → 嵌套public static class；非法标识符（数字开头、特殊字符）自动转换为合法 Java 命名（toPascalCase、toJavaIdentifier）。

测试验证了生成的类包含public class ToolConfig、private Profile profile;、public static class Profile且以合法}收尾（jsonTools.test.ts）。

2.10 JSON Path 查询与可视化选择器

• 查询：queryJsonPath(input, path, t)基于jsonpath-plus库，wrap: false直接返回匹配值；字符串值输出为 JSON 字符串字面量，undefined输出为undefined，其余美化输出；
• 可视化选择器：listJsonPaths递归收集全部节点为JsonPathEntry（path、label、value、depth）。合法标识符 Key 用.key连接，非法 Key 用[JSON.stringify(key)]下标。UI 上由 JsonPathPicker.tsx 渲染为树 + 路径 + 值预览三区弹窗，单击选中、双击直接应用路径。

2.11 文件导入/导出

工具栏通过受限 typed IPC 通道调用主进程：window.mootool.openTextFile('json')与window.mootool.saveTextFile({ kind: 'json', defaultName: 'mootool.json', content })。主进程侧 index.ts 对读写内容均做20 MB 上限校验（第 882、914 行），超出直接拒绝。

2.12 查找/替换

Ctrl/Cmd + F（或Ctrl/Cmd + R）唤起查找替换栏，展示匹配计数，支持回车下一个、循环查找（含环绕提示）、替换与全部替换；选中文本会自动带入查找框。相关实现见 JsonTool.tsx 与共享的findReplace模块。

2.13 历史记录（SQLite，Java 兼容）

Next 版历史记录使用 SQLite，并沿用 Java 版的t_func_history表结构，由 historyRepository.ts 实现：

• 建表含t_func_history（id / func_type / summary / input_text / output_text / extra_data / create_time）与t_tool_draft两张表，附(func_type, create_time DESC)索引；
• 打开 WAL 日志模式并设置busy_timeout = 3000；
• 写入时按func_type清理，每类只保留最近 200 条；空输入与空输出均不落库；summary 缺省时取 input 前 40 字符作为预览；
• 查询支持关键字跨 summary/input/output/extra_data 模糊匹配。

getDraft还能从旧t_func_content历史记录中恢复 Java 时代的编辑器草稿。集成测试 historyRepository.integration.test.ts 覆盖增删查、关键字搜索、按类型隔离与 200 条上限。

2.14 JSON Vault 基础与高级

Vault 是 JSON 文件的本地工作区，由 JsonVaultPanel.tsx（前端）与 jsonVaultRepository.ts（主进程）协同实现：

基础能力：嵌套路径树、打开、新建、保存、删除；打开未保存文件时会显示未保存保护（脏标记•、阻止切换、自动保存）。

高级能力：

• 文件夹创建、重命名（自动补.json扩展名与sanitizeName清洗非法字符）；
• 复制（duplicate自动分配唯一名xxx Copy (n).json）、移动（禁止移入自身，见canMoveJsonVaultEntry）；
• 拖拽排序（HTML5 DnD，自定义 MIME 类型application/x-mootool-vault-path）；
• 忽略规则：读取 Vault 根目录.gitignore生成ignore匹配器，hideIgnored时过滤；
• 文件系统 watcher：主进程变更事件触发面板重载、磁盘内容回读与 Git 变更计数刷新。

安全边界（集成测试 jsonVaultRepository.integration.test.ts 验证）：

• 路径归一化：拒绝绝对路径、..、隐藏段、超长段（>180 字符）、NUL 字符；
• 所有写路径经assertInsideRoot校验，realpath拒绝符号链接穿越；
• 文件上限 20 MB、目录深度上限 16、条目总数上限 2000；
• 删除/移动/重命名前校验目标不为自身或自身子路径。

2.15 Git 主流程与高级

Vault 内置 Git 面板，主进程实现为 vaultGitService.ts：

• 主流程：init（初始化 + 默认.gitignore+ 首次提交Initial MooTool Vault setup）、configure-remote、commit、fetch --prune、pull --no-rebase、push -u origin HEAD、history（git log解析 hash/作者/日期/消息）、diff（工作区对 HEAD、commit 对父提交，支持重命名-M -C与 512 KB 预览截断、二进制判定）；
• 高级能力：discard（暂存+工作区还原，必要时clean -f）、abort-merge（依次尝试merge --abort/rebase --abort）、resolve-conflict（checkout --ours|--theirs后add）、continue-operation（rebase/merge 续跑）、automaticCheckpoint（自动提交 + 自动推送）；
• 工程细节：所有仓库操作按 root 串行排队（enqueueRepositoryOperation），防 index.lock 竞争；命令带GIT_TERMINAL_PROMPT=0、60 秒超时；自动注入user.name（默认MooTool）与user.email（默认mootool@local）；凭据通过GIT_ASKPASS脚本透传 token。

UI 层 VaultGitDialog.tsx 提供变更/历史双标签页、内嵌 Diff 预览与冲突动作入口，变更数徽标每 5 秒刷新。

2.16 Java 旧数据迁移

文档描述为“只读扫描、备份、事务导入、行级幂等、回滚”，实现在 legacyMigrationService.ts：

• 扫描：读取旧版config/config.setting（INI 解析），定位MooTool.db、Quick Note Vault 与 JSON Vault 目录；只读打开 SQLite 计数各类数据；
• 备份：迁移前将旧数据复制到独立备份目录；
• 事务导入：目标库BEGIN IMMEDIATE，中途失败ROLLBACK并回删已创建文件；
• 行级幂等：每行记录t_next_migration_row（source_path/source_table/source_id 主键），重复迁移自动跳过；整库指纹记录在t_next_migration_run，避免重复全量导入；
• 专项表：t_json_beauty库内 JSON 落盘为独立.json文件；Vault 文件按相对路径复制；Quick Note 元数据以 YAML front matter 保存；
• 设置映射：将旧版各 section 的 key-value 映射为 Next 的SettingsPatch（主题、字体、代理、Vault 远程与自动提交参数等），并给出differentVaultRemotes、secretsSkipped两类警告。

集成测试 legacyMigrationService.integration.test.ts 覆盖扫描、映射、幂等、路径边界与回滚。

3. 大文本性能策略：CodeMirror 6 虚拟视口

文档中“大文本”一行说明：Java 编辑区对应能力在 Next 中由CodeMirror 6 虚拟视口承接，1 MB 以上停用完整语法树。性能脚本 tests/electron/performance-p7.mjs 对打包后的 App 进行实测：

• 构造 55,000 字段（约 3 MB）JSON，粘贴后触发“格式化”，等待状态栏valid出现；
• 记录 JSON 格式化耗时与各阶段（基线 / JSON / 大文本 / GC 后）的进程工作集内存与渲染进程堆内存；
• 门槛值：startupMs ≤ 8000、jsonFormatMs ≤ 8000、quickNoteRoundTripMs ≤ 8000、峰值内存增幅≤ 400 MB、GC 后内存增幅≤ 200 MB；
• 结果写入doc/parity/p7-performance-results.json，超阈值即抛错失败。

这一设计说明 Next 版在大文件下通过虚拟滚动渲染可视行、按需构建语法树来控制内存峰值，属于对 Java 版编辑区的显式性能对齐承诺。

4. 布局与视觉：三栏心智保留

文档第 2 节锁定四条视觉验收项，均已在 Electron E2E 测试 tests/electron/app.spec.ts 中覆盖：

• 页面只保留主标题，无小标题或面包屑（visually-hidden隐藏辅助标题）；
• 左侧 Vault、中央编辑器、右侧高级工具三栏，保留 Java 版操作心智：默认布局为[190, 520, 280]，三栏最小宽度[150, 360, 220]，宽度经ResizableColumns持久化到json-three-pane/json-two-pane存储键（JsonTool.tsx）；
• 1440 宽屏三栏不溢出、工具栏不换行；
• 1080×720 下高级工具改为可关闭覆盖层：小于 1321px 时自动收起 inspector（window.matchMedia('(min-width: 1321px)')），功能不丢失、仅折叠进“更多”菜单；
• 浅色、深色、JSONPath 弹窗、Git 面板均已建立截图基线，存放于 next/doc/screenshots/json 目录。

5. 自动化证据体系

文档第 3 节给出了完整的质量证据矩阵，仓库内可逐一对号：

文档还记录了质量门槛：npm run typecheck、114 项 Vitest、16 项 Electron E2E、npm run build全部通过，React Doctor 评分 100/100。这些命令与测试文件均在 next 目录内可复现。

6. 剩余人工出口条件与签收路径

文档第 4 节列出当前状态：Vault 高级操作、Git 冲突/撤销/合并中止、Java 旧数据迁移、打包性能验证均已完成并打勾；剩余两项尚未完成：

1. 对照 Java 版逐个签收 JSON/Vault/Git 快捷键——需要人工在 Java 版与 Next 版之间逐键比对功能映射；
2. 补充 Java 版同尺寸对比截图并完成人工 parity sign-off——需要同分辨率（如 1440×920、1080×720）下 Java 与 Next 并排截图对比，最终完成人工签收。

这两项属于自动化难以完全替代的“心智一致性”验收，也是本 Parity 文档定位为“待 Java 人工布局签收”状态的原因。完成后的截图基线应与 next/doc/screenshots/json 现有基线保持一致口径。

7. 小结：从 Checklist 到实现证据的完整闭环

通过本文的展开可以看到，next/doc/parity/json.md 这份清单的每一行都能在仓库中找到对应实现与测试：

• 功能层：16 项能力集中在 jsonTools.ts 的纯函数与 JsonTool.tsx 的交互编排；
• 持久化层：SQLite 历史、JSON Vault 文件树、Git 仓库分别由historyRepository、jsonVaultRepository、vaultGitService承载，并统一走受限 typed IPC；
• 兼容层：t_func_history表结构沿用 Java 版、旧数据迁移保证行级幂等，是实现“Java Parity”而非重写的关键设计；
• 验证层：Vitest 集成测试、Playwright E2E 与打包性能脚本共同构成可回归的质量网。

对于希望把 Java 版功能迁移到 Electron/React 技术栈的团队，这份文档与其源码实现构成了一套可参考的对照清单 → 纯函数 + 服务层 → 自动化验证 → 人工签收的完整方法论。

• 桌面应用
• 开发工具