深度解析 3GPP TS 29.501：附录 D/E：精通API设计的“微操艺术”

本文技术原理深度参考了3GPP TS 29.501 V18.7.0 (2024-12) Release 18规范中，内容涵盖信息性附录 Annex D (Example of an OpenAPI specification file for Patch) 和 Annex E (Considerations for handling of JSON arrays)。在前篇中，我们掌握了API设计师的“三大法宝”（模板、变更规则、建模范式）。本文将带领读者深入API设计中最精细、也最容易出错的两个领域：如何优雅地实现资源的部分更新（PATCH），以及如何安全地操作JSON数组。

我们的API设计师小王，手握着Nniaf_Analytics服务的设计蓝图，已经胸有成竹。然而，当他开始细化“修改一个分析任务”这一功能时，他遇到了两个棘手的“拦路虎”，这也是无数API设计师都会面临的经典难题：

“修改”的艺术：用户只想修改任务的priority（优先级），难道要他把整个几十个字段的AnalyticsJob对象都PUT回来吗？这不仅效率低下，而且容易出错。小王需要一种更外科手术式的“部分更新”方法。
“数组”的陷阱：AnalyticsJob对象中有一个notificationUris数组，用于配置任务完成后的通知地址列表。用户希望能单独增加或删除其中的一个地址。但小王敏锐地意识到，对数组元素进行操作充满了“并发”和“数据不一致”的陷阱。

幸运的是，TS 29.501的附录D和E，正是为解决这两个“微操”难题而准备的“高级攻略”。安全架构师老李再次出现，他拍了拍小王的肩膀说：“小王，细节决定成败。一个API的优雅与健壮，往往就体现在对PATCH和array的处理上。附录D是‘招式大全’，教你怎么做；附录E是‘内功心法’，教你为什么要小心翼翼地做。让我们开始吧。”

1. 附录 D: Example of an OpenAPI specification file for Patch - PATCH操作的“招式大全”

PATCH方法是HTTP协议中用于对资源进行部分修改的“手术刀”。与PUT（用新的完整表示替换整个资源）不同，PATCH旨在用一组“变更指令”来修改资源，效率更高，意图也更清晰。然而，如何描述这些“变更指令”，业界存在多种标准。

规范原文引用 (Clause 4.6.1.1.3.2 Usage of HTTP PATCH):

The format of the PATCH message body shall be specified for each resource where the PATCH method is supported using one or several of the following encodings:

The “JSON Merge Patch” encoding of changes defined in IETF RFC 7396.

The “JSON Patch” encoding of changes defined in IETF RFC 6902.

The HTTP multipart message with the multipart/mixed content-type as described in IETF RFC 2046.

附录D通过一个详尽的OpenAPI示例，展示了如何在一个API中同时支持这两种最主流的JSON PATCH格式。

1.1 PATCH的“两大流派”：JSON Merge Patch vs. JSON Patch

老李首先给小王讲解了这两种PATCH格式的核心区别。

流派一：JSON Merge Patch (RFC 7396)
- Content-Type: application/merge-patch+json
- 核心思想: “所见即所得的合并”。PATCH的请求体是一个JSON对象，它描述了资源修改后的样子。服务器收到后，会递归地将这个“补丁”合并到原始资源上。
- 优点: 非常简单、直观。
- 缺点: 功能有限。例如，它无法对数组中的单个元素进行增、删、改，只能用一个新的数组完整替换掉旧的数组。
- 示例:
  - 原始资源: { "priority": "LOW", "description": "Initial job" }
  - Merge Patch: { "priority": "HIGH" }
  - 结果: { "priority": "HIGH", "description": "Initial job" }
流派二：JSON Patch (RFC 6902)
- Content-Type: application/json-patch+json
- 核心思想: “精确指令集”。PATCH的请求体是一个JSON数组，数组中的每个元素都是一个描述具体操作的指令对象。
- 指令结构: {"op": "...", "path": "...", "value": "..."}
  - op: 操作类型，如add, remove, replace, move, copy, test。
  - path: 一个**JSON Pointer (RFC 6901)**字符串，用于精确定位要操作的字段，如/priority或/notificationUris/0（数组的第一个元素）。
  - value: 操作所需的值。
- 优点: 功能极其强大，可以对JSON文档进行任何原子级的精细操作。
- 缺点: 语法相对复杂。

小王的设计思考：

小王决定，他的Nniaf_Analytics服务应该同时支持这两种PATCH格式，以提供最大的灵活性。

对于OAM等需要进行简单字段修改的客户端，可以使用简单的JSON Merge Patch。
对于需要精细管理notificationUris数组的客户端，则可以使用强大的JSON Patch。

1.2 在OpenAPI中定义多格式PATCH

附录D的核心价值，在于展示了如何在OpenAPI 3.0的requestBody中，为同一个PATCH操作定义多个不同的Content-Type及其对应的schema。

规范原文引用 (Annex D - OpenAPI YAML snippet):

 

patch:

summary: patch inventory item

…

requestBody:

required: true

content:

  application/json-patch+json:

    schema:

      $ref: '#/components/schemas/PatchInventoryItem'

  application/merge-patch+json:

    schema:

      $ref: '#/components/schemas/MergePatchInventoryItem'

深度解析：

这个结构清晰地告诉了API的使用者和工具链：

当你的PATCH请求Content-Type头是application/json-patch+json时，你的请求体必须符合PatchInventoryItem这个schema的定义。
当Content-Type是application/merge-patch+json时，请求体则必须符合MergePatchInventoryItem的定义。

1.3 精雕细琢的Schema设计

附录D的示例还展示了如何为这两种PATCH格式设计精确的schema，这不仅仅是定义数据类型，更是对允许操作的严格约束。

MergePatchInventoryItem (for Merge Patch):

这个schema通常是原始资源schema的一个子集，只包含允许被修改的字段。并且，为了支持“删除”一个字段，可以将该字段标记为nullable: true。当客户端在Merge Patch中将一个字段的值设为null时，服务器就应该删除该字段。
PatchInventoryItem (for JSON Patch):

这个schema的设计更为精巧。它不是一个描述资源的对象，而是描述“操作指令数组”的schema。附录D的例子使用了anyOf和oneOf，将允许的JSON Patch操作限定在一个非常小的、安全的集合内。

规范原文引用 (Annex D - PatchInventoryItem snippet):
```
 
```
PatchInventoryItem:

type: array

description: A JSON PATCH body schema to Patch selected parts…

items:
```
anyOf:
```
```
  - oneOf:
```
```
    - type: object
```
```
      description: Modifies the URL of a Manufacturer
```
```
      properties:
```
```
        op: { type: string, enum: [ "add", "remove", "replace" ] }
```
```
        path: { type: string, pattern: '^\/manufacturer\/homePage$' }
```
```
        value: { type: string, format: url }
```
深度解析：

这个schema定义了items（数组中的每个元素）必须是anyOf（任何一个）以下几种指令之一。其中一个oneOf块精确地定义了“修改制造商主页”这个操作：
- op只能是add, remove, replace。
- path必须严格匹配/manufacturer/homePage这个JSON Pointer。
- value必须是一个URL格式的字符串。
这种设计方式，使得API的契约变得极其严格。客户端发送的JSON Patch指令如果op或path不在此schema的定义范围内，就会被OpenAPI校验工具或API网关在第一时间拦截，极大地提升了API的安全性。

小王的最终设计：

小王豁然开朗。他为PATCH /analytics-jobs/{jobId}也设计了类似的schema。

MergePatchAnalyticsJob: 只包含priority, description等几个允许修改的字段。
PatchAnalyticsJob: 定义为一个items为指令的数组，其中精确定义了允许的操作，如：
- 允许replace /priority字段，value必须是JobPriority枚举。
- 允许add, remove /notificationUris/-（数组末尾）或/notificationUris/{index}，value必须是uri格式的字符串。

2. 附录 E: Considerations for handling of JSON arrays - JSON数组的“内功心法”

小王在设计完PatchAnalyticsJob的schema后，正准备庆祝。老李却及时泼了一盆冷水：“小王，你的‘招式’很漂亮，但‘内力’不足。你定义的JSON Patch允许通过索引（如/notificationUris/0）来操作数组元素。在并发环境下，这是一个巨大的隐患。附录E就是帮你修炼‘内功’，避免走火入魔的。”

2.1 问题的根源：索引的“相对性”

规范原文引用 (Annex E informative):

In these scenarios, it is critical that any JSON Pointer expression is applied by both client and server on the exact same array representation, since otherwise the indexes may vary, and the JSON Pointer will give unexpected results.

深度解析：

附录E的核心思想是：基于索引的数组操作是天生不安全的，因为它依赖于客户端和服务器对数组的“视图”完全一致。但在一个分布式、并发的系统中，这个前提常常被打破。

老李为小王演示了一个经典的“数据篡改”场景：

初始状态: job-a8b3f的notificationUris在服务器端是["uri-A", "uri-B", "uri-C"]。
客户端1 (AMF-1) 读取: AMF-1执行GET，拿到了这个数组。在它看来，uri-B的索引是1。
客户端2 (OAM) 修改: 在AMF-1思考的时候，OAM系统执行了一个PATCH，删除了uri-A。现在服务器端的数组变成了["uri-B", "uri-C"]。
客户端1 (AMF-1) 修改: AMF-1现在决定删除uri-B。它根据自己陈旧的“视图”，向服务器发送JSON Patch指令：

[{"op": "remove", "path": "/notificationUris/1"}]
灾难发生: NIAF服务器收到指令，忠实地执行了它。它在当前的数组["uri-B", "uri-C"]上，删除了索引为1的元素。被删除的不是uri-B，而是uri-C！

老李总结道：“看到了吗？一次看似无害的并发操作，导致了数据的静默损坏（Silent Corruption）。AMF-1以为自己删了B，结果删了C，而它自己毫不知情。这就是索引‘相对性’带来的巨大风险。”

2.2 解决方案：引入“绝对”参照物 - ETag

如何解决索引的“相对性”问题？答案是引入一个“绝对”的参照物，确保双方在操作时，基准版本是一致的。这个参照物就是ETag (Entity Tag)。

规范原文引用 (Annex E informative):

To achieve these, both NF Service Consumer and Producer … should ensure that any resource update takes place on a known and current resource representation, based on the content of ETag values sent along with resource representations by the resource owner.

深度解析：

ETag是HTTP协议中用于乐观锁 (Optimistic Locking)和缓存控制的标准机制。

服务器端: 当服务器返回一个资源表示时（GET或PUT/POST的响应），它会计算这个表示的一个“指纹”（如Hash值），并将其放在ETag响应头中返回，例如 ETag: "abcdef123"。
客户端: 当客户端需要修改这个资源时（PUT/PATCH/DELETE），它必须在请求头中带上If-Match，其值就是它之前收到的ETag值，例如 If-Match: "abcdef123"。
服务器端: 服务器在执行修改前，会先比较客户端传来的If-Match值和资源当前最新的ETag值。
- 如果匹配，说明从客户端读取资源到现在，资源没有被其他人修改过。服务器接受并执行该操作。
- 如果不匹配，说明资源已经被修改了，客户端的操作是基于一个“过时”的版本。服务器必须拒绝该操作，并返回412 Precondition Failed状态码。

老李指导小王重构“数据篡改”场景：

初始状态: 服务器端notificationUris是["uri-A", "uri-B", "uri-C"]，ETag是"v1"。
客户端1 (AMF-1) 读取: AMF-1 GET资源，收到数组和ETag: "v1"。
客户端2 (OAM) 修改: OAM PATCH删除uri-A（假设它也基于"v1"）。服务器执行成功，数组变为["uri-B", "uri-C"]，并将资源的ETag更新为"v2"。
客户端1 (AMF-1) 修改: AMF-1现在尝试删除它认为是uri-B的索引1。它发送PATCH请求，并带上它持有的ETag：

If-Match: "v1"

[{"op": "remove", "path": "/notificationUris/1"}]
保护机制生效: NIAF服务器收到请求，首先比较If-Match头里的"v1"和资源当前的ETag"v2"。发现不匹配！
NIAF拒绝该操作，并向AMF-1返回 HTTP/1.1 412 Precondition Failed。
客户端1 (AMF-1) 恢复: AMF-1收到412错误，就知道自己的本地视图已失效。它必须重新GET一遍资源，获取最新的数组["uri-B", "uri-C"]和最新的ETag"v2"。然后，它会发现uri-B的正确索引是0，于是它会基于新版本发起正确的PATCH请求。

老李说：“ETag就像给每一次资源快照盖上了一个‘版本戳’。所有修改都必须基于最新的版本戳，否则无效。这就从根本上杜绝了因数据过时而导致的并发修改问题。”

总结：从“能用”到“可靠”的飞跃

附录D和E，看似只是两个信息性的例子和建议，实际上却蕴含了构建一个企业级、高可靠性API系统的核心工程智慧。

附录D (PATCH招式)：教会了我们如何使用OpenAPI的强大能力，来支持多种PATCH格式，并为这些操作建立严格的“安全围栏”。它让“部分更新”这一功能，变得既灵活又安全。
附录E (数组内功)：深刻地揭示了分布式系统中一个最经典的并发问题——基于相对位置的操作的危险性，并给出了基于HTTP标准（ETag）的“最佳实践”解决方案。它教会我们，数据一致性远比功能本身更重要。

小王将这两大“微操艺术”融入了他的Nniaf_Analytics服务设计之中。他不仅提供了强大的PATCH功能，还为所有可能被并发修改的资源都启用了ETag保护。他的API，至此才真正可以说，从一个“能用”的原型，飞跃到了一个“可靠”的工业级产品。

FAQ

Q1：我应该总是为我的API启用ETag吗？

A1：强烈推荐为所有支持PUT/PATCH/DELETE的资源启用ETag。它是一种轻量级且标准化的并发控制机制，可以极大地提升数据的一致性和API的健壮性。虽然会增加少量服务器开销（计算ETag）和一次网络往返（当412发生时），但与可能发生的数据静默损坏相比，这点代价是完全值得的。对于只读资源（只支持GET），ETag主要用于缓存控制，也是推荐使用的。

Q2：除了使用JSON Patch操作数组索引，还有其他更安全的方式来修改数组元素吗？

A2：有。如果数组中的元素本身具有唯一的标识符，那么最好的方式是将数组建模为Map（在JSON中是Object）。例如，notificationUris可以设计为：

 
"notificationEndpoints": {
 
  "endpoint-01": { "uri": "uri-A", "retryPolicy": "..." },
 
  "endpoint-02": { "uri": "uri-B", "retryPolicy": "..." }
 
}

这样，要删除uri-A，JSON Patch指令就变成了{"op": "remove", "path": "/notificationEndpoints/endpoint-01"}。这里的endpoint-01是一个唯一的、不因其他元素增删而改变的键。这种方式完全避免了索引的相对性问题，是操作集合成员的更健壮的设计模式。

Q3：JSON Merge Patch和JSON Patch，在实际项目中应该如何选择？

A3：选择取决于API的业务需求和对客户端的要求。

优先选择JSON Merge Patch：因为它足够简单直观，能满足80%的字段更新需求。客户端实现起来也非常容易。
当需要精细操作时，引入JSON Patch：特别是当需要对数组元素进行原子操作（增/删/改/移动），或者需要test操作（确保某个字段是某个值之后才执行修改，实现事务性）时，JSON Patch是唯一的选择。
同时支持两者：如附录D所示，为一个API同时提供两种格式是最佳实践，它给了不同需求的客户端最大的灵活性。

Q4：附录E中提到的“stateless NF Service Consumer”是什么意思？为什么它在处理数组通知时有问题？

A4：“stateless NF Service Consumer”（无状态NF服务消费者）指的是那些不保存或不缓存其交互的资源状态的客户端。例如，一个简单的事件处理服务，它只是接收通知并触发一个动作，但它自己并不维护AnalyticsJob的完整对象。当它收到一个JSON Patch格式的通知，说“请将/notificationUris/2的值替换为uri-X”时，因为它没有本地副本，它完全不知道索引2之前是什么，也无法验证这个操作的上下文。因此，附录E建议，在向这类无状态消费者发送通知时，应该发送完整的、替换后的新数组，而不是一个patch指令，以避免歧义。

Q.5: ETag的值应该是如何生成的？

A.5: 规范没有强制规定ETag的生成算法，但通常有两种方式：

强ETag (Strong ETag)：要求资源内容逐字节完全相同时，ETag才相同。通常是对资源表示（如JSON字符串）进行一次哈希计算（如MD5, SHA-1）得到。例如：ETag: "f8cdb2c8914d187e1132204a779b8f52"。这是最常用的方式，能提供最强的并发控制保证。
弱ETag (Weak ETag)：只要求资源在语义上等价时，ETag就相同。通常以W/作为前缀，例如ETag: W/"v1.2"。这适用于那些内容上可能有微小差异（如生成时间戳不同）但逻辑上是同一版本的资源。

对于保证数据一致性的并发控制场景，必须使用强ETag。

51学通信

探索

深度解析 3GPP TS 29.501：附录 DE：精通API设计的“微操艺术”

深度解析 3GPP TS 29.501：附录 D/E：精通API设计的“微操艺术”

1. 附录 D: Example of an OpenAPI specification file for Patch - PATCH操作的“招式大全”

1.1 PATCH的“两大流派”：JSON Merge Patch vs. JSON Patch

1.2 在OpenAPI中定义多格式PATCH

1.3 精雕细琢的Schema设计

2. 附录 E: Considerations for handling of JSON arrays - JSON数组的“内功心法”

2.1 问题的根源：索引的“相对性”

2.2 解决方案：引入“绝对”参照物 - ETag

总结：从“能用”到“可靠”的飞跃

FAQ

关系图谱

目录