Diffson - JSON 差异对比工具

目录

特性

比较策略说明

左侧: { "name": "test", "items": [{id:1}, {id:2}] }
右侧: { "name": "test", "items": [{id:2}, {id:1}], "extra": true }

项目结构

json-diff-ts/
├── packages/
│ └── core/ # 核心库 @diffson/core
├── apps/
│ └── cli/ # 命令行工具 @diffson/cli
├── package.json # Monorepo 配置
└── turbo.json # Turborepo 配置

安装

Core 库

npm install @diffson/core
# 或
bun add @diffson/core

CLI 工具

# 全局安装
npm install -g @diffson/cli
# 或使用 npx(无需安装)
npx @diffson/cli

Core 库使用

快速开始

import { DiffService, PresetName } from '@diffson/core';
const diffService = new DiffService();
const left = { name: 'John', age: 30 };
const right = { name: 'John', age: 31 };
const results = diffService.diffElement(left, right);
console.log(results);
// [{ leftPath: 'age', rightPath: 'age', left: '30', right: '31', diffType: 'MODIFY' }]

API 参考

DiffService

// 创建实例,可选预设模式
const diffService = new DiffService(preset?: PresetName);

diffElement 方法

diffService.diffElement(left, right, options?)

diffJson 方法

diffService.diffJson(leftJson, rightJson, options?)

返回结果

interface Result {
 leftPath: string | null; // 左侧路径
 rightPath: string | null; // 右侧路径
 left: unknown; // 左侧值
 right: unknown; // 右侧值
 diffType: 'ADD' | 'DELETE' | 'MODIFY'; // 差异类型
}

使用示例

使用预设模式

import { DiffService, PresetName } from '@diffson/core';
// 顺序敏感比较
const orderedDiff = new DiffService(PresetName.FullOrdered);
const results = orderedDiff.diffElement([1, 2, 3], [1, 3, 2]);
// 仅比较左侧字段
const leftDiff = new DiffService(PresetName.LeftSmart);
const results2 = leftDiff.diffElement({ a: 1 }, { a: 1, b: 2 });
// 结果: [] (忽略右侧多出的 b 字段)

忽略路径

const diffService = new DiffService();
const left = { name: 'John', timestamp: 1000 };
const right = { name: 'John', timestamp: 2000 };
const results = diffService.diffElement(left, right, {
 ignorePaths: ['timestamp']
});
// 结果: [] (timestamp 被忽略)

数组 identity 路径

const left = {
 items: [{ id: 'a', label: 'x' }, { id: 'b', label: 'y' }]
};
const right = {
 items: [{ id: 'b', label: 'x' }, { id: 'a', label: 'y' }]
};
const results = diffService.diffElement(left, right, {
 arrayMatching: {
 identityPaths: ['items.id']
 }
});
// 智能数组比较会优先按 items.id 配对,再比较其他字段

解析嵌套 JSON

const left = { data: '{"nested":"value1"}' };
const right = { data: '{"nested":"value2"}' };
const results = diffService.diffElement(left, right, {
 parseNestedJson: true
});
// 结果: [{ leftPath: 'data.nested', ... }]

CLI 工具使用

快速开始

# 交互模式(默认)
diffson
# 比较 JSON 字符串
diffson '{"a":1,"b":2}' '{"a":1,"b":3}'
# 比较文件
diffson -f1 data1.json -f2 data2.json

命令行选项

基本选项

输入选项

比较选项

输出选项

使用示例

比较文件

diffson --file1 old-config.json --file2 new-config.json

使用预设模式

# 顺序敏感比较
diffson --preset fullOrdered -f1 data1.json -f2 data2.json
# 仅比较左侧字段
diffson --preset leftSmart -f1 base.json -f2 update.json

过滤差异类型

# 仅显示新增
diffson -f1 old.json -f2 new.json --filter add
# 仅显示删除和修改
diffson -f1 old.json -f2 new.json --filter delete,modify

忽略路径

# 忽略 timestamp 字段
diffson -f1 data1.json -f2 data2.json --ignore-path timestamp
# 忽略数组元素的 name 字段
diffson -f1 data1.json -f2 data2.json --ignore-path items.name

数组 identity 路径

# 智能数组比较时优先按 id 配对
diffson -f1 data1.json -f2 data2.json --array-identity-path items.id

JSON 格式输出

diffson --format json -f1 data1.json -f2 data2.json
# 输出到文件
diffson --format json -f1 data1.json -f2 data2.json -o result.json

输出示例

Found 2 differences:
+ newField
 + "new value"
~ modifiedField
 - "old value"
 + "new value"

[
 { "leftPath": null, "rightPath": "newField", "left": null, "right": "new value", "diffType": "ADD" },
 { "leftPath": "modifiedField", "rightPath": "modifiedField", "left": "old value", "right": "new value", "diffType": "MODIFY" }
]

路径格式

开发指南

环境要求

本地开发

# 克隆项目
git clone <repository-url>
cd json-diff-ts
# 安装依赖
bun install
# 构建所有包
bun run build
# 运行测试
bun run test
# 类型检查
bun run typecheck

项目脚本

发布

bun run publish

许可证