# JsonXmlCompare **Repository Path**: joininjoy/json-xml-compare ## Basic Information - **Project Name**: JsonXmlCompare - **Description**: 这是一款rust写的json和xml格式化,以及文本对比的工具。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-13 - **Last Updated**: 2026-11-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # JSON / XML Compare 一个面向 Windows 的免安装 JSON / XML 工具,同时提供**文本比较**,一套核心、两种形态: | 形态 | 程序 | 技术栈 | 体积 | | --- | --- | --- | --- | | 桌面版 | `JsonXmlCompare.exe` | Rust + eframe/egui,原生 OpenGL | 5.21 MiB | | 网页版 | `JsonXmlCompareWeb.exe` | Rust 本地后台服务 + 浏览器界面 | 1.06 MiB | 两者共用 `jsonxml-compare-core`:解析、格式化、压缩、校验、互转、树模型**以及文本差异引擎**只有一份实现,结果逐字节一致。 ![网页版(深色)](docs/screenshot-dark.png) ![文本比较(网页版)](docs/screenshot-compare-dark.png) ## 功能 ### JSON / XML 工具 - **格式化**:自动识别 JSON / XML,按 2 空格缩进输出。 - **压缩**:去掉无意义空白,生成紧凑文本。 - **校验**:只检查语法,不改变当前结果;错误会定位到行列并显示上下文片段。 - **JSON → XML / XML → JSON**:支持根节点名称、属性约定、数组、`null`、转义字符、注释保留。 - **树形视图**:对象 / 数组 / XML 元素均可折叠,虚拟化渲染,90k 节点也不卡顿。 - **文件操作**:打开、保存、拖拽文件;支持 UTF-8 / UTF-16 文本。 - **深色 / 浅色主题**、可拖拽分栏、响应式布局。 - **中文界面**;网页版不需要 Node、WebView2、.NET 或安装器。 ### 文本比较 - **两种模式**:菜单 / 工具栏分段按钮(桌面)或顶部页签(网页)切换,切换时两侧内容都不丢。 - **严格行对齐**:相同行左右 y 坐标一致;插入 / 删除在另一侧显示斜纹占位行。 - **整行底色 + 行内片段**:修改行琥珀色,删除行红色,新增行绿色,行内改动再叠加高亮。 - **左右都是输入框**:可直接输入、粘贴、打开文件、拖拽(1 个文件进左栏,2 个文件进左右两栏)。 - **自动比较**:输入停止约 0.3 秒后自动出结果;`Ctrl+Enter` 立即重算。 - **差异导航**:`F7` / `Shift+F7` 逐处跳转,当前差异有描边,状态栏显示「第 k 处 / 共 n 处」。 - **单侧查找(桌面)**:工具栏查找框 + 左/右切换 + `Aa` + 上一处/下一处(`F3`/`Shift+F3`),命中片段高亮。 - **忽略选项**:行尾/行首/全部空白、大小写、空行、行内差异开关、Tab 宽度。 - **不保存比较结果**:需要留档时直接截图到工作群即可(与需求一致)。 ## 两种模式 | 模式 | 网页地址 | 说明 | | --- | --- | --- | | JSON / XML 工具 | `http://127.0.0.1:17890/` | 格式化、校验、互转、树形浏览 | | 文本比较 | `http://127.0.0.1:17890/compare` | 左右两栏比较;`/compare/` 会 308 跳到 `/compare` | - 单端口、单服务进程:两个视图共享同一个前端与 API,切换模式用 `history.replaceState` 同步地址,不刷新页面、不新增历史记录。 - 桌面版:`视图 → 模式` 菜单、工具栏分段按钮、`Ctrl+1` / `Ctrl+2` 三种方式切换;命令行 `--compare` 可直接以比较模式启动。 ## 网页版(JsonXmlCompareWeb) ### 快速开始 ```powershell .\dist-web\JsonXmlCompareWeb.exe ``` 程序会在后台启动本地服务,并打开默认浏览器访问 `http://127.0.0.1:17890/`(文本比较:`/compare`)。 - 只监听 `127.0.0.1`,不对局域网开放。 - 所有数据只在本地内存中处理,不上传、不写临时文件。 - 关闭浏览器不会停止服务;用下面的方式退出。 ### 命令行 | 命令 | 行为 | | --- | --- | | `JsonXmlCompareWeb.exe` | 启动服务并打开浏览器;已运行则只打开页面 | | `JsonXmlCompareWeb.exe --background` | 只启动服务,不打开浏览器(开机启动使用) | | `JsonXmlCompareWeb.exe --open` | 打开浏览器;服务未运行时先启动 | | `JsonXmlCompareWeb.exe --port 17890` | 指定端口(也可写成 `--port=17890`) | | `JsonXmlCompareWeb.exe --install-autostart` | 写入当前用户开机启动项(无需管理员权限) | | `JsonXmlCompareWeb.exe --uninstall-autostart` | 删除开机启动项 | | `JsonXmlCompareWeb.exe --stop` | 通知正在运行的实例退出(不会弹窗,适合脚本) | | `JsonXmlCompareWeb.exe --version` / `--help` | 版本 / 帮助 | `dist-web\` 中附带双击即用的脚本: - `install-autostart.cmd` / `uninstall-autostart.cmd` - `停止服务.cmd` - `打开网页版.url`(`http://127.0.0.1:17890/`) - `打开文本比较.url`(`http://127.0.0.1:17890/compare`) ### 开机启动 只写入当前用户注册表,不需要管理员权限: ```text HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run 名称: JsonXmlCompareWeb 值: "…\JsonXmlCompareWeb.exe" --background ``` 默认**不**自动开启,由用户显式安装;移动程序目录后需要重新运行安装脚本。如果启动时检测到注册表路径与当前路径不一致,会写日志并在交互式启动时提示。 ### 停止、日志与数据目录 - 停止:`JsonXmlCompareWeb.exe --stop` 或 `停止服务.cmd`。 - 日志:`%LOCALAPPDATA%\JsonXmlCompareWeb\service.log`(单文件 1 MiB,保留 2 个备份)。 - 日志只记录启动、端口、状态码、差异规模的字节数/行数/耗时,**不记录输入/输出正文、文件名或剪贴板内容**。 - 没有托盘图标(v1 取舍);需要常驻时建议配合开机启动,退出用 `--stop`。 ### 安全设计 - 只绑定 `127.0.0.1`;校验 `Host` 必须是 `127.0.0.1:` 或 `localhost:`,防止 DNS rebinding。 - 不返回 CORS 头;带 `Origin` 的跨源请求被拒绝;API 只接受 `application/json`。 - 请求体上限 32 MiB;转换/比较并发 2、队列 8,超限返回 `429`;静态资源不占配额。 - 比较接口额外限制左右合计 16 MiB、20 万行(超出时只比较前 20 万行并在结果里标注)。 - 静态资源内嵌在 exe 中,按白名单扩展名查找并拒绝路径穿越。 - 响应头带 CSP、`X-Content-Type-Options`、`Referrer-Policy`、`X-Frame-Options`。 - 不提供“服务端读写任意文件”的接口;文件由浏览器选择和下载。 ### 网页版界面说明 - 顶部:品牌、本地服务状态、主题、帮助;其下是「JSON / XML 工具 | 文本比较」页签。 - 工具模式:格式化 / 压缩 / 校验 / 双向转换 / 根节点 / 打开 / 保存 / 复制 / 回填 / 清空;中间是输入编辑器与输出区(树形视图 / 只读文本)。 - 比较模式:重新比较 / 上一处 / 下一处 / 交换 / 清空 / 打开左侧 / 打开右侧 / 示例 / 选项;中间是左右两个可编辑的 CodeMirror,整行底色与行内高亮由装饰实现,占位用块级 widget(`N 行 × 21 px`),两侧行高严格一致。 - 滚动同步:两侧行高一致,按像素同步 `scrollTop`;窄屏(< 960 px)堆叠时关闭同步,改为「左侧 / 右侧」页签 + 下一处自动切页。 - 查找:网页版使用浏览器自带的 `Ctrl+F`(CodeMirror 只渲染可见行,因此只能命中当前视口附近);跨全文查找请用桌面版的单侧查找框。 - 输入超过 2 MiB 关闭语法高亮与折叠;超过 8 MiB 显示“大文件模式”;超过 32 MiB 直接拒绝。 - 比较自动执行上限 50,000 行;超过后需手动「重新比较」,服务端上限 200,000 行。 - 树节点超过 200,000 时服务端省略树,只返回文本结果并给出提示。 - 只持久化主题、分栏比例、输出标签、模式与比较选项;不在 localStorage 中保存正文。 ### 前端开发 前端源码在 `web/`(Preact + TypeScript + CodeMirror 6,Vite 构建)。生产环境不需要 Node。 ```powershell cd web npm.cmd ci # 首次 npm.cmd run dev # 开发服务器(需要同时运行 JsonXmlCompareWeb.exe 或用代理) npm.cmd run build # 产物在 web/dist,由 build-web.ps1 复制进 crates/web/webdist npm.cmd test # vitest 单元测试 ``` ## 桌面版 直接运行 `dist\JsonXmlCompare.exe`。 - 在左侧粘贴 JSON / XML,点击「格式化」,右侧树形视图和文本结果会同步生成。 - 拖入 `.json`、`.xml`、`.txt` 文件,或使用「打开」按钮。 - 也可以把文件路径作为第一个参数传入: ```powershell .\JsonXmlCompare.exe .\examples\sample.json .\JsonXmlCompare.exe --compare # 直接以文本比较模式启动 .\JsonXmlCompare.exe --compare-demo # 以比较模式启动并载入示例(冒烟/演示用) ``` ### 桌面版文本比较 - 工具栏:`JSON / XML 工具 | 文本比较` 分段按钮、查找框(左/右、`Aa`、上一处/下一处)、重新比较、上一处、下一处、交换、清空、打开左侧/右侧、示例、选项。 - 两栏共用一个垂直 `ScrollArea`,因此垂直滚动天然同步;长行用 `Shift+滚轮` 或栏底细滚动条横向滚动,两侧各自独立。 - 行号列等宽,差异行整行底色 + 行首 3 px 竖条,修改行再叠加行内片段高亮;插入/删除在另一侧画斜纹占位。 - `F7` / `Shift+F7` 跳转差异,`Ctrl+Enter` 重新比较,`Ctrl+F` 定位查找框,`F3` / `Shift+F3` 上/下一处匹配,`Ctrl+Shift+X` 交换,`Ctrl+L` 清空。 - 比较结果**不提供保存**:状态栏与「复制差异摘要」足够日常使用,留档请直接截图。 桌面版其它特性:默认最大化、`F11` 全屏、Windows 原生标题栏跟随主题、内置示例、文件拖拽。 ## 快捷键 网页版工具模式: | 快捷键 | 功能 | | --- | --- | | `Ctrl+Enter` | 格式化 | | `Ctrl+Shift+M` | 压缩 | | `Ctrl+O` | 打开文件(浏览器文件选择) | | `Ctrl+S` | 下载结果 | | `Ctrl+L` | 清空(需确认) | | `Ctrl+Shift+I` | 输出回填输入 | | `Ctrl+Shift+C` | 复制结果 | | `Ctrl+Alt+1` / `Ctrl+Alt+2` | 切换工具模式 / 文本比较 | | `Esc` | 关闭对话框 / 错误面板 | 网页版比较模式:`F7` / `Shift+F7` 差异导航、`Ctrl+Enter` 重新比较、`Ctrl+Shift+X` 交换、`Ctrl+L` 清空、`Ctrl+Shift+E` 载入示例、`Ctrl+F` 浏览器查找。 桌面版:工具模式 `Ctrl+Enter` 格式化、`Ctrl+Shift+M` 压缩、`Ctrl+O`/`Ctrl+S` 打开/保存、`Ctrl+L` 清空、`Ctrl+Shift+I` 回填、`F11` 全屏、`Esc` 关闭帮助;比较模式见上一节。 ## JSON ↔ XML 转换约定 两种形态使用同一套规则(由 `crates/core` 的黄金测试锁定): - JSON 对象属性 → XML 子元素。 - JSON 键 `@name` → 当前元素的 XML 属性 `name`。 - JSON 键 `#text` → 当前元素的文本内容。 - JSON 数组 → 一个同名元素,内部使用 `` 子项: ```json {"tags": ["a", "b"]} ``` ```xml a b ``` - JSON `null` → `xsi:nil="true"`,并在根元素声明 `xmlns:xsi`。 - XML 中全为 `` 的子元素、重复的同名元素 → JSON 数组。 - XML 文本会尝试推断数字、布尔和 `null`;无法推断时保留字符串。 - XML 根元素名不额外嵌套进 JSON,而是写入「根节点」输入框。 - 空数组和空对象在 XML 中都表现为空元素,回转统一为空字符串。 - XML 注释在格式化/压缩时保留,转 JSON 时忽略;自定义 DTD 实体不支持;嵌套深度上限 512。 ## 文本比较算法(`core::diff`) - **行级**:先去掉公共前缀/后缀,再用 patience(两侧唯一行锚点 + 最长递增子序列)切分大区间;小区间用精确 LCS(`n*m ≤ 2,000,000`)求最小编辑脚本。预算(默认 20,000 次编辑)耗尽时剩余区间按整块替换,并在 `stats.truncated` 标记。 - **行内**:替换行按词元做 LCS——英文/数字按单词,CJK 按单字,空白与标点各自成词元;区间合并、两端空白收缩后映射回原始字节。 - **对齐模型**:`rows` 每行左右各一个槽位,`None` 表示该侧占位;两侧行都被覆盖且只覆盖一次。 - **偏移单位**:core 与桌面用 **UTF-8 字节**;网页 API 在该行内转换成 **UTF-16 码元**(`utf16_offsets`),所以中文/emoji 的区间不会错位。 - **忽略选项**:CRLF/LF/CR 永远等价;行尾/行首/全部空白、大小写、空行可忽略;`忽略全部空白` 时不做行内片段(只整行标记),把位置映射回原文会碎片化。 - **上限**:自动比较 20,000 行(超过关闭行内高亮),50,000 行以上需手动,服务端硬上限 200,000 行;单行超过 2,000 字符只做整行标记。 ## 构建 ### 环境 - Windows 10/11 x64,Rust 1.94.1 + MSVC。 - Node.js 22+ 仅在构建网页前端时需要;运行不需要。 - `windres` 可选,用于把图标和版本信息嵌入 exe;缺失时构建仍成功。 ### 命令 ```powershell # 只构建桌面版(产物 dist\JsonXmlCompare.exe) .\build.ps1 # 只构建网页版(产物 dist-web\JsonXmlCompareWeb.exe + 便携 zip) .\build-web.ps1 # 全量:workspace 测试 + 两个产物 + /health、/api/v1/diff、/compare 冒烟 .\build-all.ps1 ``` 对应的双击脚本:`build.cmd`、`build-web.cmd`、`build-all.cmd`。 ### 目录结构 ```text JsonXmlCompare/ ├─ src/ # 桌面版(main / app / jsonxml_view / compare_view / dialogs / widgets / theme) │ └─ compare/ # 比较状态、LayoutJob、绘制、导航 ├─ crates/ │ ├─ core/ # jsonxml-compare-core:convert / tree / text / diff / search + 契约测试 │ └─ web/ # jsonxml-compare-web:HTTP、API(process + diff)、DTO、日志、开机启动、Win32 ├─ web/ # Preact + TypeScript + CodeMirror 6 源码(含 compare/ 与样式) ├─ deploy/ # 发布用 cmd / url 脚本(含 打开文本比较.url) ├─ tools/ # 图标、E2E(verify-web / verify-compare)、性能脚本(bench-web / bench-page / bench-diff) ├─ docs/ # 截图、性能记录、历史方案 ├─ assets/ # 图标源文件 ├─ build.ps1 / build-web.ps1 / build-all.ps1 └─ dist/ dist-web/ # 构建产物 ``` 核心分层: ```text jsonxml-compare-core(无 UI、无 HTTP、无 Win32) ├── JsonXmlCompare.exe (桌面,egui:工具模式 + 比较模式) └── JsonXmlCompareWeb.exe (Web,tiny_http + rust-embed:/ 与 /compare) ``` ## 性能与体积 实测(本机,详见 [docs/perf.md](docs/perf.md)): | 指标 | 结果 | | --- | --- | | `JsonXmlCompare.exe` | 5.21 MiB | | `JsonXmlCompareWeb.exe` | 1.06 MiB | | 差异计算(2,000 行) | 服务端 0.6 ms / 往返 7 ms | | 差异计算(20,000 行) | 服务端 7.8 ms / 往返 20 ms | | 差异计算(50,000 行) | 服务端 17.7 ms / 往返 48 ms | | 差异计算(200,000 行) | 服务端 87 ms / 往返 204 ms(core 基准 101 ms) | | 空闲 RSS / CPU | ≈ 10 MiB / 0.00% | ## 测试 ```powershell cargo test --workspace # core 单元 + 差异契约 + 黄金契约 + Web HTTP 契约 cd web && npm.cmd test # 前端树模型 / 工具函数 / 装饰与路由单测 node tools/verify-web.mjs # 真实浏览器 E2E:工具模式(需先启动服务) node tools/verify-compare.mjs # 真实浏览器 E2E:文本比较(对齐、占位、导航、滚动同步) ``` - 差异引擎契约测试覆盖:空文档、全相同、单词改动、首/中/尾增删、CRLF、行尾空白、大小写、空行、中文、emoji、Tab、超长行、行数上限、预算降级、随机对拍(用 rows 重建原文)与 20 万行基准。 - 桌面端单元测试还验证了「同一 diff 在真实 egui 排版下两侧总高度严格等于 `行数 × 行高`」,这是严格对齐的硬条件。 - `tools/verify-compare.mjs` 断言:模式页签、两侧编辑器、占位块存在、行顶坐标一致、两侧 `scrollHeight` 相等、`F7` 导航、输入后自动重算、滚动同步、窄屏页签、模式切换改写 URL,并生成 `docs/screenshot-compare-*.png`。 ## 与 JsonXmlStudio 1.0 的关系 - 本工程由 `JsonXmlStudio` 复制改名而来:`jsonxml-core` → `jsonxml-compare-core`、`jsonxml-web` → `jsonxml-compare-web`、端口仍为 **17890**、日志目录 `%LOCALAPPDATA%\JsonXmlCompareWeb`、互斥量/停止事件/开机启动值名全部改名。 - 旧目录 `JsonXmlStudio` 一个字节都没有改动,可继续对照回退;两个版本不能同时监听 17890,需要并存时给新版加 `--port 17891`。 - 转换行为与 1.0.0 完全一致:黄金契约测试未做任何更新,改名只改 crate 引用。 - 新增:文本比较(桌面 + 网页)、`POST /api/v1/diff`、`/compare` 直达页、`打开文本比较.url`、单侧查找(桌面)。 ## 已知限制 - 网页版没有托盘图标;退出请用 `--stop` 或脚本。 - 只允许本机访问;不提供账号、HTTPS、局域网或云端存储。 - 不提供“服务端保存到任意路径”的 API;文件通过浏览器选择和下载。 - 网页版查找依赖浏览器 `Ctrl+F`,只能命中 CodeMirror 已渲染的可见行;需要全文查找请用桌面版。 - 文本比较结果不落盘(与需求一致):刷新页面或关闭程序后,两侧文本与比较结果都不会保留。 - 5 MB / 320k 节点的 XML 峰值内存约 144 MiB,受当前逐元素 `XmlDoc` 模型限制;超大 XML 建议用桌面版或拆分。 - 50,000 行比较的响应约 2.1 MiB(200,000 行约 8.7 MiB);若体积成为问题,可改用紧凑数组编码(`[kind, left, right, leftSpans, rightSpans]`),当前版本未启用。 - 浏览器标签页自身的内存(常见 80–150 MiB)不属于服务进程预算。 - 自定义 DTD 实体不支持;支持内置实体和数字字符引用。 - 文本类型推断可能把 XML 中原本是字符串的 `"123"` 转为数字;这是 XML 缺少类型信息的常见取舍。 ## 许可 MIT,见 [LICENSE](LICENSE)。