8.3 与JSON世界的互操作

8.3 与 JSON 世界的互操作：官方映射与转码

本节摘要：Protobuf 官方定义了与 JSON 的双向映射规范——字段名转驼峰、默认值省略、枚举用名字、64 位整数转字符串。本节拆解这些取舍点的成因、转码网关与命令行工具的正确用法、以及"对外 API 该不该暴露 protobuf"的架构裁决框架。读完你应当能解释 JSON 侧同事遇到的每个"protobuf 怪现象"，并设计合理的内外分界。

本章最后一个投影：互操作。第 1.3 节选型时说过"内部二进制加对外 JSON 的双轨制"是常见落点——本节讲的就是两条轨道之间的换乘设施。

官方映射的六个取舍点

proto3 起官方定义了 JSON 映射规范，每个规则都是明面的取舍，JSON 侧同事的"怪现象"基本都在这六条里：

第 5.3 节讲过 JSON 往返会丢未知字段——加一条这里的完整结论：proto→JSON→proto 的往返会丢未知字段、丢"显式零值"（输入的 0 变成缺省）、保留其余已知字段。凡是需要保真的链路，这条往返链是禁区。

三个换乘设施

设施一：运行时内置转换。 各语言运行时普遍自带 proto↔JSON 的转换 API（Marshal 到 JSON、从 JSON 解析），配置项与映射规范对齐。用途：服务内部的双格式出口（同一个 handler 按 Accept 头吐 JSON 或二进制）。

设施二：转码网关。 gRPC 生态提供 HTTP/JSON 到 gRPC 的协议转码——外部 HTTP 请求进网关，网关按 proto 契约（附注解标注 HTTP 路由与方法）把 JSON 转成 protobuf 字节调内部 gRPC 服务。配置形态是在 proto 里加 HTTP 注解（一种自定义 option，第 6.1 节机制的应用）：

service TrenchService {
  rpc GetTrench(GetTrenchRequest) returns (Trench) {
    option (google.api.http) = {
      get: "/v1/trenches/{id}"
    };
  }
}
​

网关的存在让"对外 JSON、对内 protobuf"不需要写转换代码——契约即路由，转换由网关层统一执行。

设施三：命令行工具。 grpcurl（gRPC 的 curl 等价物）与第 6.2 节的通用解析工具配合，覆盖调试场景：JSON 输入调 gRPC、gRPC 响应转 JSON 可读输出。

图 8-3 双轨制架构：内外分界与换乘设施

架构裁决：对外 API 暴露什么

"对外 API 该不该直接用 protobuf"是个老争论，裁决框架三条：

消费方可控性。内部 API 消费方是自家团队，发 SDK、控版本，二进制协议的复杂度可以内部消化；对外 API 的消费方背景不可控——要求第三方安装工具链才能调用，等于给接入设置门槛。默认裁决：对外 JSON、对内 protobuf、网关换乘。

性能敏感度。极高性能的对外场景（行情推送、游戏协议）存在例外——消费方愿意付接入成本换性能，此时 protobuf 直接对外合理，且第 7.3 节的入口加固清单必须全配（不信任输入）。

演进治理成本。对外契约的兼容义务比内部重一个量级（第 5 章规则在对外场景是公开承诺而非团队约定），JSON 世界的宽容解析（多字段忽略、类型弱校验）让小错不致命；protobuf 的严格解析则把每个契约问题都变成硬错误。对外暴露 protobuf 前，确认 buf breaking 的门禁（上一节）已覆盖对外契约集。

实战案例：给内部 gRPC 服务加对外 JSON 门面

背景：合作方要对接某内部 gRPC 服务，团队不想为外部对接另写一套接口层。操作：选转码网关方案——proto 里补 HTTP 注解（约 20 个 rpc 各加一条路由声明）；网关部署在服务前，配置 TLS 与限流；对外文档由第 4.3 节风格的插件从同一份契约生成（OpenAPI 形态），保证文档与契约同源；64 位 ID 字段的 JSON 字符串行为（取舍点表第 4 行）提前与合作方书面确认——对方是 Java 后端，字符串解析无障碍但要求文档显式标注。结果：两周上线，内部服务零改动；后续内部契约演进照常走 gRPC，对外兼容由网关的注解路由版本化（v1 路由冻结、v2 平行开放）。解读：方案的核心收益是门面层只有声明没有代码——路由、转换、文档全部从单一契约投影出来（本章金句的落地形态）；维护成本几乎为零，代价是网关这一跳的延迟（毫秒级，与业务收益权衡）。变式：如果外部调用量小且团队已有 HTTP 网关基建，用反向代理加轻量转换服务也能拼出同等门面——注解方案的独特优势在"契约同源"，没有文档漂移问题。

本节要点回顾

• 六个取舍点：驼峰名、零值省略、枚举名、64 位转字符串、base64、Any 展开——JSON 侧怪现象的完整出处；
• 往返禁区：proto→JSON→proto 丢未知字段与显式零值，保真链路禁止换乘；
• 三个设施：运行时转换（双格式出口）、转码网关（契约即路由）、命令行工具（调试）；
• 对外裁决三问：消费方可控吗、性能够敏感吗、演进治理跟得上吗——默认答案是对内 protobuf 对外 JSON；
• 门面无代码：路由与文档从契约投影，文档漂移结构性消失。

布展完成，全册只剩最后一站：综合遗址报告——微服务、移动端、游戏、大数据管道四个发掘现场的全部发现汇总成章。