josephburnett/jd

jd - JSON 比较与修补工具

概述

jd 是一款轻量级命令行工具，专注于 JSON 数据的结构化比较（diff）和修补（patch）操作。与传统文本比对工具不同，jd 直接解析 JSON 数据结构，能够准确识别对象键值对、数组元素及嵌套结构的语义差异，并生成可复用的补丁文件，同时支持将补丁应用于目标 JSON 数据以实现精确更新。

核心功能与特性

• 结构化 JSON 比对：深入解析 JSON 语法结构，识别值类型（字符串、数字、布尔等）、对象键值对、数组元素及嵌套结构的差异，而非基于文本行的简单比对
• 补丁生成与应用：支持生成标准化 JSON 补丁文件，并可将补丁应用到源 JSON 数据，实现数据更新
• 灵活的比对规则：可配置忽略对象键顺序、数组元素顺序等非语义差异
• 多场景输出：提供人类可读的差异展示及机器可解析的补丁格式，适配开发调试与自动化流程
• 轻量高效：命令行驱动，无图形界面，启动快速，适合集成到脚本与 CI/CD 管道

使用场景

• 开发调试：比对 API 响应、配置文件或数据模型的 JSON 输出差异
• 版本控制：跟踪 JSON 配置文件或数据文件在版本迭代中的结构化变更
• 自动化测试：验证测试用例中预期 JSON 结果与实际输出的一致性
• 数据同步：生成 JSON 数据变更补丁，用于不同环境（开发/测试/生产）间的数据同步

使用方法与配置说明

前提条件

• 已安装 Docker 环境

获取镜像

bash
docker pull josephburnett/jd

基本命令格式

bash
docker run --rm -v $(pwd):/data josephburnett/jd [选项] <源文件路径> <目标文件路径>

• --rm：容器退出后自动清理
• -v $(pwd):/data：将当前工作目录挂载到容器内 /data 目录，实现本地 JSON 文件访问

常用命令示例

1. 比较两个 JSON 文件

比对当前目录下 a.json 与 b.json 的差异：

bash
docker run --rm -v $(pwd):/data josephburnett/jd /data/a.json /data/b.json

2. 生成 JSON 补丁文件

比对 a.json 与 b.json 并生成补丁文件 patch.json：

bash
docker run --rm -v $(pwd):/data josephburnett/jd -p /data/a.json /data/b.json > /data/patch.json

3. 应用补丁到 JSON 文件

将 patch.json 应用到 a.json 并输出更新结果：

bash
docker run --rm -v $(pwd):/data josephburnett/jd -u /data/a.json /data/patch.json

4. 忽略对象键顺序比对

比对时将 JSON 对象视为无序集合（忽略键的定义顺序）：

bash
docker run --rm -v $(pwd):/data josephburnett/jd -set /data/a.json /data/b.json

主要配置选项

注意事项

• jd 专注于 JSON 值的语义比较，会忽略格式差异（如空格、缩进、换行符）
• 对于超大 JSON 文件（GB 级），建议通过 -v 挂载时限制文件大小，避免内存溢出
• 数组比对默认按索引顺序，如需忽略顺序需显式添加 -array 选项

参考链接

• https://github.com/josephburnett/jd