如何规范化JSON文档更新以通过Kafka等消息代理发布文档变更

选方案的核心判断依据是你的业务场景：是只需要简单传递变更值，还是需要支持字段删除、数组操作、并发冲突校验这类复杂场景。你自己想的两个思路都能跑，但都有明显的坑，属于无统一标准下的自研思路，生产环境用很容易出兼容问题。

两种自研方案的优劣势 #

• 方案1：保留原JSON结构仅传变更字段
  好处是结构和原文档完全对齐，上手简单，消费方拿过去做个合并就能更新本地数据。
  坑非常多：首先没法区分「把字段值设为null」和「删除这个字段」，遇到数组元素增删、字段移动这类操作完全没法表达；其次嵌套层级深的时候，只改最内层一个字段也要把外层所有结构都写一遍，冗余度很高；最麻烦的是没有统一规则约束的话，不同消费方写的合并逻辑可能不一致——有人做浅合并，有人做深合并，最后同一份消息更新出来的数据不一样，排错成本极高。
• 方案2：自定义字段路径+更新内容的结构
  好处是结构紧凑，要改哪个字段路径写得很明确，不会有合并歧义。
  本质是重复造轮子：你得自己定路径解析规则，比如数组下标怎么表示？字段名本身带点怎么转义？后面要支持删字段、数组操作、多操作原子执行，你还得不停给结构加字段补规则，最后搞出一套只有自己团队看得懂的自定义规范，后续维护、新接入方的学习成本都很高。

生产环境通用的标准化方案 #

这类JSON增量更新的场景已经有IETF发布的正式RFC标准，全行业通用，各种主流编程语言都有现成的解析、处理库，完全不需要自己从零设计：

1. JSON Patch（RFC 6902） #

这个是灵活性最高的标准，专门用来描述JSON文档的所有类型变更，和你想的方案2结构类似，但做了全场景的标准化约定：

• 每个变更项明确标注操作类型op，支持add（新增/替换字段）、remove（删除字段）、replace（替换值）、move（移动字段路径）、copy（复制字段）、test（执行更新前校验字段值符合预期，用来解决并发更新冲突）
• 字段路径path统一用JSON Pointer（RFC 6901）规则，特殊字符、数组下标都有标准转义方式，不会出现解析歧义

你提到的街道名称变更场景，对应的消息格式如下：

{
  "id": 12,
  "event_type": "document_updated",
  "version": 3,
  "patch": [
    {"op": "replace", "path": "/address/street", "value": "new street name"}
  ]
}

如果要同时删除address.code字段、给tags数组追加一个标签，直接在patch数组里追加操作项即可，不需要改结构：

{
  "id": 12,
  "event_type": "document_updated",
  "version": 3,
  "patch": [
    {"op": "replace", "path": "/address/street", "value": "new street name"},
    {"op": "remove", "path": "/address/code"},
    {"op": "add", "path": "/tags/-", "value": "home"}
  ]
}

消费方拿到消息之后，直接调用对应语言的JSON Patch库，就能把本地存储的旧版本文档自动更新到新版本，不需要自己写路径解析、合并逻辑，不会出现逻辑不一致的问题。

2. JSON Merge Patch（RFC 7396） #

这个标准和你想的方案1逻辑完全对齐，结构和原文档保持一致，仅传递变更字段，标准里明确约定了合并规则：

• 消息里出现的字段直接替换原值
• 字段值传null代表删除对应字段
• 遇到数组直接整体替换，不做递归合并

你提到的街道变更场景，对应的消息格式就是你设计的结构：

{
  "id": 12,
  "event_type": "document_updated",
  "version": 3,
  "merge_patch": {
    "address": {
      "street": "new street name"
    }
  }
}

这个方案的优势是结构极其简单，哪怕没看过规范的开发也能快速理解，适合业务简单、很少涉及数组操作和字段删除的场景。

Kafka场景的额外设计建议 #

• 不管选哪种规范，消息里必须带上文档唯一标识（你例子里的id）、文档版本号（递增整数或者更新时间戳），方便消费方处理乱序消息——如果收到的消息版本比本地存储的文档版本还旧，直接丢弃即可，避免旧变更覆盖新数据。
• 如果消费方数量多、场景差异大，建议消息里同时携带「变更后的完整文档快照」+「标准化补丁」：需要全量数据的消费方直接用快照，不需要自己做合并计算；需要做增量同步、变更审计的消费方直接用补丁，兼顾两类需求。
• 不要自己发明自定义的更新语法，尽量用上面提到的两个通用标准，省掉后续维护自定义规则、兼容不同消费方逻辑的隐性成本。

内容的提问来源于stack exchange，提问作者user3579222