# @greatcloak/json-patch 中文文档

规范地址：https://npmcn.com/package/%40greatcloak/json-patch/

版本：4\.0\.0
npm 元数据更新时间：2026-05-15T20:00:40.626Z
中文译文更新时间：2026-11-17T01:10:11.790Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40greatcloak/json-patch
原文对照：https://npmcn.com/package/%40greatcloak/json-patch/?lang=original
项目主页：https://github.com/greatcloak/json-patch
源码仓库：https://github.com/greatcloak/json-patch

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：64.3 kB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-05-15T20:00:39.894Z
- 最新版本发布：2026-05-15T20:00:40.046Z
- 近 30 天下载量：12134（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 1 个）

## 中文简介

现代(sm)版本快活-json-patch. 快速实施JSON-Patch(RFC-6902),具有双层(观察变化)能力

## 安装

```sh
npm install @greatcloak/json-patch
```

也可以使用：`pnpm add @greatcloak/json-patch`、`yarn add @greatcloak/json-patch`、`bun add @greatcloak/json-patch`

## README

# @greatcloak/json-patch (英语)

> 一个叉子 [快速编程](https://github.com/Starcounter-Jack/JSON-Patch) 与现代esm配置.

这种叉子的目标是维持一个安全而现代化的快活-Json-patch版本,用于我们的产品.

-   保持粗糙的相容性,无论旧的打字符设置、模块包装格式等是否必要,都不应被打破
-   欢迎速度、错误和安全修复
-   对共同的现实世界问题来说,方便使用是鼓励的.

推测这个项目现在与vitest和现代角测试设置相兼容.

带着JSON-Patch,你可以:

-   **应用** jS 对象上的补丁( 阵列) 和单项操作
-   **验证** 补丁序列
-   **观察** 更改和 **生成** 检测到变化时补丁
-   **比较** 获取差异的两个对象

在Firefox、Chrome、Edge、Safari、IE11、Deno和Node.js测试

## 为什么要用 JSON -Patch

JSON- Patch 游戏 [(RFC6902) (中文(简体) )](http://tools.ietf.org/html/rfc6902) 是标准格式 允许您通过发送更改而不是整个文档来更新 JSON 文档. JSON Patch在HTTP PATCH动词(方法)和REST风格编程上表现良好.

马克诺丁汉有一个 [不错的博客](http://www.mnot.net/blog/2012/09/05/patch) 关于它.

## 安装

```sh
# NPM
npm install @greatcloak/json-patch --save
```

## 添加到您的项目中

### 在节点.js

在Webpack(当然还有基于Babel的其他捆绑器)中,以下代码使用这个库作为ECMAScript模块:

```js
import * as jsonpatch from '@greatcloak/json-patch'
import { applyOperation } from '@greatcloak/json-patch'
```

## 目录

此包中使用的目录 :

-   `dist/` - 包含网络浏览器的ES5文件
-   `commonjs/` - 包含普通JS模块和打字
-   `module/` - 包含ECMAScript模块和打字
-   `src/` - 包含类型Script源文件

## API 密码

#### `function applyPatch<T>(document: T, patch: Operation[], validateOperation?: boolean | Validator<T>, mutateDocument: boolean = true, banPrototypeModifications: boolean = true): PatchResult<T>`

应用 `patch` 阵列在 `obj`。 。 。 .

-   `document` 要补丁的文档
-   `patch` a 应用JSON-Patch系列操作
-   `validateOperation` 布尔用于是否用默认验证器验证每个操作, 或是通过验证器回调
-   `mutateDocument` 是否在应用前对原始文档进行突变或复制
-   `banPrototypeModifications` 是否禁止修改 `__proto__`,默认为 `true`。 。 。 .

无效的补丁导致丢出错误( 见 `jsonpatch.validate` 关于错误对象的更多信息.

它修改了 `document` 对象和 `patch` - 它通过参考得到数值. 请不要碰你 `patch` 数组值, 复制它们 : `jsonpatch.applyPatch(document, jsonpatch.deepClone(patch))`。 。 。 .

返回数组 [`OperationResult`](https://npmcn.com/package/%40greatcloak/json-patch/#readme-operationresult-type) 对象 - 每个项目在 `patches`,每个项目都是对象 `{newDocument: any, test?: boolean, removed?: any}`。 。 。 .

-   `test` - 测试的布尔结果
-   `remove`, (中文(简体) ), `replace` 财务报告和审定财务报表 `move` - 已删除的原始对象
-   `add` (仅在添加到数组时) - 插入项目所在的索引(在使用时有用) `-` (别名)

-   \*\* 注:投出 `TEST_OPERATION_FAILED` 错误,如果 `test` 操作失败 。 页:1
    
-   \*\* 注意 二: 返回的数组有 `newDocument` 属性,可以用作补丁文档的最后状态\*\*.
    
-   \*\* 附注三:默认情况下 `banPrototypeModifications` 实值 `true`,该方法将 `TypeError` 当你试图修改一个对象的原型时.
    
-   见 [审定说明](https://npmcn.com/package/%40greatcloak/json-patch/#readme-validation-notes)。 。 。 .
    

示例

```js
var document = { firstName: 'Albert', contactDetails: { phoneNumbers: [] } }
var patch = [
  { op: 'replace', path: '/firstName', value: 'Joachim' },
  { op: 'add', path: '/lastName', value: 'Wester' },
  {
    op: 'add',
    path: '/contactDetails/phoneNumbers/0',
    value: { number: '555-123' },
  },
]
document = jsonpatch.applyPatch(document, patch).newDocument
// document == { firstName: "Joachim", lastName: "Wester", contactDetails: { phoneNumbers: [{number:"555-123"}] } };
```

#### `function applyOperation<T>(document: T, operation: Operation, validateOperation: boolean | Validator<T> = false, mutateDocument: boolean = true, banPrototypeModifications: boolean = true, index: number = 0): OperationResult<T>`

应用单个操作对象 `operation` 打开 `document`。 。 。 .

-   `document` 要补丁的文档
-   `operation` 申请行动
-   `validateOperation` 是否验证操作, 还是通过验证符回调
-   `mutateDocument` 是否在应用前对原始文档进行突变或复制
-   `banPrototypeModifications` 是否禁止修改 `__proto__`,默认为 `true`。 。 。 .
-   `index` 您补丁阵列中的操作索引 。 当操作失败时, 用于更好的错误报告 .

它修改了 `document` 对象和 `operation` - 它通过参考得到数值. 如果你想避免触摸你的价值观,请复制: `jsonpatch.applyOperation(document, jsonpatch.deepClone(operation))`。 。 。 .

返回 a [`OperationResult`](https://npmcn.com/package/%40greatcloak/json-patch/#readme-operationresult-type) 对象 `{newDocument: any, test?: boolean, removed?: any}`。 。 。 .

-   \*\* 注:投出 `TEST_OPERATION_FAILED` 错误,如果 `test` 操作失败 。 页:1
    
-   \*\* 附注二:默认情况下 `banPrototypeModifications` 实值 `true`,该方法将 `TypeError` 当你试图修改一个对象的原型时.
    
-   见 [审定说明](https://npmcn.com/package/%40greatcloak/json-patch/#readme-validation-notes)。 。 。 .
    

示例

```js
var document = { firstName: 'Albert', contactDetails: { phoneNumbers: [] } }
var operation = { op: 'replace', path: '/firstName', value: 'Joachim' }
document = jsonpatch.applyOperation(document, operation).newDocument
// document == { firstName: "Joachim", contactDetails: { phoneNumbers: [] }}
```

#### `jsonpatch.applyReducer<T>(document: T, operation: Operation, index: number): T`

**理想为 `patch.reduce(jsonpatch.applyReducer, document)`**。 。 。 .

应用单个操作对象 `operation` 打开 `document`。 。 。 .

返回已修改的文档.

注意: 它抛出 `TEST_OPERATION_FAILED` 错误,如果 `test` 操作失败 .

示例

```js
var document = { firstName: 'Albert', contactDetails: { phoneNumbers: [] } }
var patch = [
  { op: 'replace', path: '/firstName', value: 'Joachim' },
  { op: 'add', path: '/lastName', value: 'Wester' },
  {
    op: 'add',
    path: '/contactDetails/phoneNumbers/0',
    value: { number: '555-123' },
  },
]
var updatedDocument = patch.reduce(applyReducer, document)
// updatedDocument == { firstName:"Joachim", lastName:"Wester", contactDetails:{ phoneNumbers[ {number:"555-123"} ] } };
```

#### `jsonpatch.deepClone(value: any): any`

返回深克隆值 .

#### `jsonpatch.escapePathComponent(path: string): string`

返回已逃出路径 .

#### `jsonpatch.unescapePathComponent(path: string): string`

返回未脱逃路径.

#### `jsonpatch.getValueByPointer(document: object, pointer: string)`

用 JSON 指针从 JSON 文档中获取一个值 .

返回该值.

#### `jsonpatch.observe(document: any, callback?: Function): Observer`

设置一个深入的观察者 关于 `document` 用于聆听对象树的变化。 当检测到变化时,可选 以生成的补丁数组作为参数调用回调.

回返 `observer`。 。 。 .

#### `jsonpatch.generate(document: any, observer: Observer, invertible = false): Operation[]`

如果待修改,则 `obj`,并同步返回它们。 如果有的话 `callback` 定义于 `observe` 方法,它也会同步被触发。 若为 `invertible` ,然后在每次修改之前先进行值的测试操作.

如果没有待处理的变动 `obj`,返回空数组(长度为0).

示例

```js
var document = {
  firstName: 'Joachim',
  lastName: 'Wester',
  contactDetails: { phoneNumbers: [{ number: '555-123' }] },
}
var observer = jsonpatch.observe(document)
document.firstName = 'Albert'
document.contactDetails.phoneNumbers[0].number = '123'
document.contactDetails.phoneNumbers.push({ number: '456' })
var patch = jsonpatch.generate(observer)
// patch  == [
//   { op: "replace", path: "/firstName", value: "Albert"},
//   { op: "replace", path: "/contactDetails/phoneNumbers/0/number", value: "123" },
//   { op: "add", path: "/contactDetails/phoneNumbers/1", value: {number:"456"}}
// ];
```

对第一个对象中值进行测试操作生成补丁的示例:

```js
var document = {
  firstName: 'Joachim',
  lastName: 'Wester',
  contactDetails: { phoneNumbers: [{ number: '555-123' }] },
}
var observer = jsonpatch.observe(document)
document.firstName = 'Albert'
document.contactDetails.phoneNumbers[0].number = '123'
document.contactDetails.phoneNumbers.push({ number: '456' })
var patch = jsonpatch.generate(observer, true)
// patch  == [
//   { op: "test", path: "/firstName", value: "Joachim"},
//   { op: "replace", path: "/firstName", value: "Albert"},
//   { op: "test", path: "/contactDetails/phoneNumbers/0/number", value: "555-123" },
//   { op: "replace", path: "/contactDetails/phoneNumbers/0/number", value: "123" },
//   { op: "add", path: "/contactDetails/phoneNumbers/1", value: {number:"456"}}
// ];
```

#### `jsonpatch.unobserve(document, observer)`

```typescript
jsonpatch.unobserve(document: any, observer: Observer): void

type JsonableObj = { [key:string]: Jsonable };
type JsonableArr = Jsonable[];
type Jsonable = JsonableArr | JsonableObj | string | number | boolean | null;
```

摧毁在 `document`。 。 。 .

任何剩余更改均同步交付(如 `jsonpatch.generate`) (中文(简体) ). 注:这与ES6/7不同 `Object.unobserve`,可以同步实现剩余变化.

#### `jsonpatch.compare(document1, document2, invertible)`

```typescript
jsonpatch.compare(document1: Jsonable, document2: Jsonable, invertible = false): Operation[]

type JsonableObj = { [key:string]: Jsonable };
type JsonableArr = Jsonable[];
type Jsonable = JsonableArr | JsonableObj | string | number | boolean | null;
```

比较对象树 `document1` 财务报告和审定财务报表 `document2` 与 `document1` 作为补丁数组。 若为 `invertible` ,然后在每次更改之前,先对数值进行测试操作 `document1`。 。 。 .

如果没有差异,则返回一个空数组(长为0).

示例

```js
var documentA = { user: { firstName: 'Albert', lastName: 'Einstein' } }
var documentB = { user: { firstName: 'Albert', lastName: 'Collins' } }
var diff = jsonpatch.compare(documentA, documentB)
//diff == [{op: "replace", path: "/user/lastName", value: "Collins"}]
```

将两个对象树与第一个对象值的测试操作进行比较的例子:

```js
var documentA = { user: { firstName: 'Albert', lastName: 'Einstein' } }
var documentB = { user: { firstName: 'Albert', lastName: 'Collins' } }
var diff = jsonpatch.compare(documentA, documentB, true)
//diff == [
//   {op: "test", path: "/user/lastName", value: "Einstein"},
//   {op: "replace", path: "/user/lastName", value: "Collins"}
// ];
```

#### `jsonpatch.validate(patch: Operation[], document?: any, validator?: Function): JsonPatchError`

见 [审定说明](https://npmcn.com/package/%40greatcloak/json-patch/#readme-validation-notes)

验证一系列操作。 若为 `document` 提供了参数,序列会针对对象树进行额外的验证.

如果没有出错, 返回未定义 。 如果存在错误,返回具有以下属性的 JsonPatchError 对象:

-   `name` 字符串 - 短错误代码
-   `message` 字符串 - 长可读错误消息
-   `index` 数字 - 序列中操作的索引
-   `operation` 对象 - 操作的引用
-   `tree` 对象 - 树的引用

可能的错误 :

| 错误名称 | 错误消息 |
| --- | --- |
| 安全性 NOT AN ARRAY | 补丁序列必须是数组 |
| 操作 NOT AN OBJECT | 操作不是一个对象 |
| 操作 OP 评估 | 运行 `op` 属性不是 RFC-6902 定义的操作之一 |
| 操作 PATH 评估 | 运行 `path` 属性不是一个有效的字符串 |
| 操作 FROM REQUIED | 运行 `from` 属性不存在(适用于 `move` 财务报告和审定财务报表 `copy` 业务) |
| 操作 评估 完成 | 运行 `value` 属性不存在,或 `undefined` (适用于 `add`, (中文(简体) ), `replace` 财务报告和审定财务报表 `test` 业务) |
| 操作 VALUE CANNOT CONANDINED | 运行 `value` 属性对象至少有一个 `undefined` 值(适用于 `add`, (中文(简体) ), `replace` 财务报告和审定财务报表 `test` 业务) |
| 操作 PATH CANNOT ADD | 无法执行 `add` 运行在理想路径 |
| 无法操作 | 无法在不存在的路径上执行操作 |
| 无法操作 | 无法从不存在的路径执行操作 |
| 操作 PATH ILLLEGAL ARRAY INDEX | 期望一个没有符号的 Base- 10 整数值, 使新的引用值成为以零为基础的索引的数组元素 |
| 行动 评价 OUT OF BOUNDS | 指定的索引 MUST 不大于数组中的元素数 |
| 测试 测试 测试 | 当操作是 `test` 测试失败,则适用于 `applyReducer`。 。 。 . |

示例

```js
var obj = { user: { firstName: 'Albert' } }
var patches = [
  { op: 'replace', path: '/user/firstName', value: 'Albert' },
  { op: 'replace', path: '/user/lastName', value: 'Einstein' },
]
var errors = jsonpatch.validate(patches, obj)
if (errors.length == 0) {
  //there are no errors!
} else {
  for (var i = 0; i < errors.length; i++) {
    if (!errors[i]) {
      console.log('Valid patch at index', i, patches[i])
    } else {
      console.error('Invalid patch at index', i, errors[i], patches[i])
    }
  }
}
```

## `OperationResult` 类型

职能 `applyPatch` 财务报告和审定财务报表 `applyOperation` 双向返回 `OperationResult` 对象。 此对象为:

```ts
{newDocument: any, test?: boolean, removed?: any}
```

地点:

-   `newDocument`:应用补丁/操作后文档的新状态.
-   `test`: 如果操作是 `test` 操作。 这将是它的结果.
-   `removed`: 包含文档中已删除、已移动或替换的值 `remove`, (中文(简体) ), `move` 或者说 `replace` 操作.

## 校正说明

职能 `applyPatch`, (中文(简体) ), `applyOperation`,以及 `validate` 接受一个 `validate`编号 : `validator` 参数 :

-   如果 `validateOperation` 参数设置为 `false`,不会进行验证.
-   如果设置为 `true`,该补丁在应用jsonpatch的默认验证之前被广泛验证.
-   如果设置为 `function` 调回,补丁使用此函数验证 .

如果你通过一个验证器,它将被调用 四个参数每个操作, `function(operation, index, tree, existingPath)` 并有望投出 `JsonPatchError` 当你的条件没有满足.

-   `operation` 操作它自己.
-   `index` `operation`补丁数组中的索引( 如果应用) .
-   `tree` 应补丁的对象.
-   `existingPath` 路径 `operation` 指点.

## 重叠和 `move` 运行

当移动操作的目标已经存在时,它会被缓存,被深克隆并返回为 `removed` 内 `OperationResult`。 。 。 .

## `undefined`s(JS至JSON投影)

作为 `undefined` 类型在JSON不存在,它也不是JSON补丁操作的有效值. 因此 `jsonpatch` 将不生成 JSON 补丁设置到 `undefined`。 。 。 .

当一个值设定为 `undefined` jSON-Patch方法 `generate` 财务报告和审定财务报表 `compare` 将类似于 JavaScript 方法 [`JSON.stringify` (MDN) (韩语)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) 治疗他们:

> 若为 `undefined` 在转换过程中遇到(.),它要么被省略(当在对象中发现时),要么被审查到 `null` (当它在一个阵列中被发现时).

见 [ECMAScript 光谱](http://www.ecma-international.org/ecma-262/6.0/index.html#sec-json.stringify) 详细情况.

## 光谱/测试

-   [在浏览器中运行](http://starcounter-jack.github.io/JSON-Patch/test/)

## [捐款](https://npmcn.com/package/%40greatcloak/json-patch/CONTRIBUTING.md)

## 更改日志

要查看最近更改的清单,见 [释放](https://github.com/greatcloak/json-patch/releases)。 。 。 .

## 脚印

4 KB 变焦并被克齐克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克

## 业绩

##### [`add` 基准](https://run.perf.zone/view/JSON-Patch-Add-Operation-1535541298893)

![image](https://user-images.githubusercontent.com/17054134/44784357-aa422480-ab8d-11e8-8a7e-037e692dd842.png)

##### [`replace` 基准](https://run.perf.zone/view/JSON-Patch-Replace-Operation-1535540952263)

![image](https://user-images.githubusercontent.com/17054134/44784275-5fc0a800-ab8d-11e8-8a90-e87b8d5409d0.png)

于2018年8月29日被试. 比较库 :

-   [恒星对接杰克/JSON-Patch](https://www.npmjs.com/package/fast-json-patch) 2.0.6 联合国
-   [bruth/jsonpatch-js (英语)](https://www.npmjs.com/package/json-patch) 0.7.0 (简体中文)
-   [dharmafly/jsonpatch.js (英语)](https://www.npmjs.com/package/jsonpatch) 3.0.1 (中文(简体) )
-   [齐夫](https://www.npmjs.com/package/jiff) 0.7.3 (中文(简体) )
-   [RFC6902 (法语)](https://www.npmjs.com/package/rfc6902) 2.4.0 (中文(简体) )

我们的目标是公平测试。 我们的图书馆将表演作为一号优先,而其他图书馆可以有不同的优先. 如果你想更新基准 或增加一个图书馆, 请叉出 [每区](https://perf.zone/) 将上述基准联系起来,并开启一个包括新成果的问题.

## 许可证

麻省理工学院

## 常见问题

### @greatcloak/json-patch 是什么？

现代\(sm\)版本快活-json-patch\. 快速实施JSON-Patch\(RFC-6902\),具有双层\(观察变化\)能力

### 如何安装 @greatcloak/json-patch？

在项目目录运行 npm install @greatcloak/json-patch，或使用 pnpm add / yarn add / bun add。

### @greatcloak/json-patch 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @greatcloak/json-patch 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @greatcloak/json-patch 可以商用吗？

@greatcloak/json-patch 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @greatcloak/json-patch 的下载量有多少？

根据 npm 官方下载统计，@greatcloak/json-patch 在 2026/10/17 – 2026/11/15 这 30 天内被下载 12,134 次，日均约 404 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @greatcloak/json-patch 还在维护吗？

最新版本 4\.0\.0 发布于 2026/05/16（6 个月前）；至今共发布 1 个版本，其中过去 12 个月发布了 1 个；首次发布于 2026/05/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

