Protobuf 与 gRPC 契约：二进制 Schema 怎样安全演进

高谷深陵大约 13 分钟约 3841 字

Protobuf 消息用字段编号保存成员身份，gRPC 用服务名和方法名定位远程操作。.proto 同时声明这两部分后，编译器生成消息类与服务存根；客户端调用存根，服务端接收字节并执行具体实现。

字段编号、消息往返与 RPC 生命周期

字段怎样从 Schema 变成字节

一份最小定义

syntax = "proto3";
package contract;
option java_package = "example.contract.rpc";
option java_multiple_files = true;

message OrderRequest { string id = 1; }
message OrderV2 {
  string id = 1;
  optional int32 priority = 2;
  string note = 3;
}
service Orders {
  rpc GetOrder(OrderRequest) returns (OrderV2);
}

package contract 参与 Protobuf 类型与 RPC 服务的完整名称；java_package 控制生成 Java 类的位置，二者用途不同。java_multiple_files 影响 Java 文件组织，不改变线上字段编号。客户端通过生成的 OrdersGrpc 存根调用 GetOrder，网络方法名包含 /contract.Orders/GetOrder。

optional int32 priority = 2
├─ optional       显式记录有没有设置该字段
├─ int32          逻辑类型及适用的编码方式
├─ priority       源码访问器和 JSON 名称的基础
└─ 2              二进制字段身份，不能随业务名称重用

字段的 tag 编码由字段号和 wire type 组成，值随后按对应格式编码。消息中通常不反复携带 priority 这样的完整名称，这也是二进制表示较紧凑的原因。数字、字符串和嵌套消息采用不同 wire type；字段号相同但业务单位变了，解析器仍可能读出值并执行错误逻辑。Protobuf 编码说明解释字节层结构。

常用类型与缺省值

声明	用途与约束
int32/int64、uint32/uint64	整数范围不同；金额还需约定最小单位和币种
sint32/sint64	对负数采用 ZigZag 编码，与普通有符号整数字段不能随意替换
fixed32/fixed64、float/double	固定宽度或浮点值；浮点不适合直接表示精确金额
string / bytes	UTF-8 文本与任意字节分开；Base64 是 JSON 表示时的另一个层次
repeated	多个同类型值；未提供时表现为空集合，不单独记录缺失集合
map	键值集合；迭代顺序不应成为协议承诺
enum	数值编码，需定义零值及未知值处理
oneof	一组字段中至多一个生效，可表示明确的互斥输入
message	嵌套对象，具有自己的字段身份和存在性

proto3 普通标量的隐式 presence 会把未设置与类型零值合并。optional int32 priority 则可以区分“未给出”和“明确设置为 0”，Java 生成类相应提供 hasPriority()。在局部更新中，这个差异决定是否修改已有值；字段掩码 FieldMask 可进一步描述需要更新的路径。Field Presence详细比较这些情况。

enum 的零值适合表达未指定状态，例如 STATUS_UNSPECIFIED，而不是让缺省输入直接意味着已支付。新增枚举值时，旧 Java 代码可能得到 UNRECOGNIZED，并可通过数值访问器取得原始数字；客户端应保留未知状态或拒绝不支持的动作，不把它映射成某个真实已知状态。

字段演进和未知字段

删除字段后，将编号和名称都写入 reserved：

message RetiredOrder {
  string id = 1;
  reserved 2;
  reserved "priority";
}

旧数据可能仍保存在消息队列、缓存或客户端。若把编号 2 改成另一个兼容 wire type 的字段，旧字节可能被解释为新含义；即使解析成功也已经改变了业务语义。字段更新规则见 proto3 指南。

标准 Protobuf 二进制解析通常保留未知字段，旧程序读取新消息、原样重新序列化后，新程序还可能读回新字段。但逐字段复制到另一个对象、转成不包含未知成员的业务模型，或者经过 JSON 中转，会改变这一性质。ProtoJSON 默认拒绝未知字段；选择忽略时，未知字段不会作为二进制 unknown fields 被保留。ProtoJSON还定义了整数、bytes、枚举和时间类型的 JSON 形式。

proto2、proto3 与 Editions 是语法/特性体系。Edition 编号控制特性默认值，protoc 和各语言 runtime 则有自己的发行版本。采用 Editions 前应核对所有生产者和消费者工具链支持情况，不能根据编号相似推断二者兼容。Editions 概览和运行时版本保证可用于核对具体组合。

RPC 调用包含哪些运行约定

Channel、Stub 与四种调用

Channel 负责目标地址、连接、名称解析和调用配置；Stub 是生成的客户端接口；服务实现处理生成的请求对象并产生响应。长生命周期 Channel 通常复用，不应每个请求新建后立即销毁。gRPC 使用 HTTP/2，但普通 HTTP/JSON 客户端不能只改路径就理解它的消息封装和状态。

RPC 形式	请求与响应	常见场景
Unary	一个请求，一个响应	查询、命令提交
Server streaming	一个请求，多个响应消息	连续结果、订阅
Client streaming	多个请求消息，一个响应	分批上传、汇总
Bidirectional streaming	双方各自发送多条消息	双向协作、实时交换

流内消息按发送顺序交付，但双向流中两条方向的推进相对独立。长流还需处理背压、发送许可、消息大小、取消和服务端排空；一次 onNext 调用完成不代表对端业务已经持久化了该消息。gRPC 核心概念说明了各种调用的生命周期。

元数据、身份与失败状态

Metadata 承载认证令牌、调用关联信息等元数据。TLS 保护通道，服务端仍要检查当前身份是否有权访问请求中的订单；拦截器可以集中处理身份和记录调用，但不应把任意外部 Header 直接当成可信租户。

gRPC 状态与 HTTP 状态是两个层面。正常建立 HTTP/2 传输后，RPC 仍可因参数、权限或业务条件失败；客户端应读取 gRPC Status，而不是只检查底层 HTTP 200。典型状态的下一步如下，完整定义见 Status Codes。

状态	处理方向
INVALID_ARGUMENT	修复与当前系统状态无关的参数错误
FAILED_PRECONDITION	先改变不满足要求的业务状态
ABORTED	常需从更高层重新执行并发事务或操作
UNAUTHENTICATED / PERMISSION_DENIED	分别处理身份认证与权限
RESOURCE_EXHAUSTED	检查配额、容量或消息限制
UNAVAILABLE	服务当前不可用；结合幂等性和预算考虑重试
DEADLINE_EXCEEDED	客户端等待预算耗尽，业务结果可能仍需查询
CANCELLED	调用已取消，不代表之前的副作用自动撤销

错误说明只包含允许客户端看到的信息。需要结构化业务错误时可定义消息或采用支持的 richer error model，同时核对代理和各语言客户端能否读取它，不能让 SQL 异常文本成为对外错误协议。

截止时间与取消

客户端设置 deadline 后，gRPC 在截止时结束等待；Java 中常用 stub.withDeadlineAfter(...) 给某次调用配置预算。服务端调用下游时需传播剩余预算，在同一个 gRPC Context 中的 Java 调用有相应传播支持；异步切线程或自行重建 Context 时要重新核对。Deadlines解释了传播与时钟差异处理。

取消通过 Context 通知服务处理逻辑。库无法替业务安全撤销已经提交的数据库事务，也不会自动中断所有第三方阻塞调用。计算循环可检查取消状态，外部 I/O 要有自身超时，资源在停止后关闭。Cancellation区分了通知和应用停止工作的职责。

重试也有边界：状态允许重试、方法业务幂等、请求可以重放、总 deadline 仍有预算，几项条件要同时成立。服务端发送响应或提交业务后发生连接故障，不能靠换一个 request ID 再调用来猜结果。流式 RPC 还要明确已发送或已确认消息的恢复位置。

生成消息和存根，执行真实网络调用

编译与运行环境

下载 gRPC 契约实验，在 Linux amd64 上解压进入 contract-rpc。宿主需要 Docker、Bash、unzip 和当前目录写权限，构建使用宿主 UID/GID。实验固定 Maven 3.9.12、gRPC Java 1.75.0、protoc 与 Protobuf Java 4.31.1，Java 编译目标为 17。

unzip contract-rpc-lab.zip
cd contract-rpc
bash run-docker.sh

Maven 先识别 Linux x86_64，下载对应 protoc 与 gRPC Java 插件，再从 src/main/proto/orders.proto 生成消息类和 OrdersGrpc。随后编译源码并执行两个测试方法。正常结果是 Tests run: 2, Failures: 0, Errors: 0。不同平台需要存在对应编译器发行文件；解析不到 classifier 时，应处理工具平台支持，而不是编辑生成 Java 类。

工程也可使用 JDK 25 构建：

BUILD_IMAGE=maven:3.9.12-eclipse-temurin-25 bash run-docker.sh

两个镜像的实际 JDK 分别为 Temurin 17.0.18 和 25.0.2。JDK 25 下依赖可能打印 Unsafe 或 native access 警告，它们与测试是否成功分别判断；升级依赖或调整原生访问配置时重新核对运行时要求，不能用屏蔽日志代替兼容检查。官方 Java 接入结构可查 gRPC Java Basics。

新字段经过旧程序的两种结果

测试中的 OrderV1 只知道字段 1、2；OrderV2 增加字段 3 的 note。先构造并序列化新消息：

var fresh = OrderV2.newBuilder()
    .setId("o-1").setPriority(0).setNote("new field").build();
var old = OrderV1.parseFrom(fresh.toByteArray());
var roundTrip = OrderV2.parseFrom(old.toByteArray());

真实断言检查 old 的 hasPriority() 为 true、数值为 0，unknown fields 中存在编号 3，roundTrip 的 note 仍为 new field。另一个未调用 setPriority 的消息，hasPriority() 为 false。这里同时看到了零值存在性和未知字段保留。

再把 fresh 转成 ProtoJSON，交给旧消息构造器：

String json = JsonFormat.printer().print(fresh);
JsonFormat.parser().merge(json, OrderV1.newBuilder());

默认解析抛出 InvalidProtocolBufferException，因为旧类型不认识 note。若改用 ignoringUnknownFields()，解析能够完成，但再次转换为 OrderV2 时 note 已变为空字符串。JSON 路径丢掉了未知成员；测试同时检查拒绝类型和忽略后的实际结果，没有把忽略未知字段当成无损中转。

调用成功、参数失败、deadline 与后续恢复

网络测试使用 NettyServerBuilder 绑定 127.0.0.1 随机端口，再创建真实 ManagedChannel。只在回环网络使用明文，测试完成后关闭 Channel 和 Server，并等待终止，不向宿主公布固定 RPC 端口。

var stub = OrdersGrpc.newBlockingStub(channel);
var result = stub.withDeadlineAfter(3, TimeUnit.SECONDS)
    .getOrder(OrderRequest.newBuilder().setId("o-1").build());

结果中的 note 是 ready。空 ID 请求则得到 INVALID_ARGUMENT，测试精确检查 status code。接着向 slow ID 发请求：服务处理函数已经进入，注册 Context 取消监听后暂不返回响应；客户端的一秒 deadline 到期，得到 DEADLINE_EXCEEDED，服务端监听也必须收到取消通知。

客户端                                服务端
GetOrder(o-1) ──────────────────────→  返回 ready
GetOrder(空 ID) ────────────────────→  INVALID_ARGUMENT
GetOrder(slow, deadline=1s) ─────────→  进入处理，等待取消
deadline 本地到期 ──取消通知────────→  Context 通知处理逻辑
GetOrder(o-2) ──────────────────────→  再次返回 ready

测试依次确认 slow 抵达服务端、服务端收到取消通知、o-2 调用成功。这样可以区分“请求未能抵达”和“处理中的调用被取消”。当前处理函数没有数据库写入，不涉及事务回滚或外部 API 撤销。

升级与排错从哪个对象开始

区分四类兼容性

二进制 wire 兼容检查字段号与编码；ProtoJSON 还受字段名、枚举名和未知字段策略影响；生成代码兼容检查方法签名、包名和类型；业务兼容检查单位、状态和动作含义。字段改名有时不影响二进制，却会改变 JSON 名称及源码访问器，应分别验证。

拆分或合并 oneof 也需谨慎。旧端无法理解新 oneof 成员时，可能把当前分支看成未设置；随后设置另一个分支并重写消息，会改变新端恢复出的选择。新增字段应先让读取者具备容忍策略，再安排写入者启用；删除字段则经历停写、旧数据与客户端迁移、观察后保留 reserved。

生成代码与运行时要作为一组保存。部署前从同一份 .proto、固定 protoc 和插件重新构建，编译老调用代码，并回放历史二进制与 JSON 样本。只保存最新 .proto 不足以复现旧 SDK。跨服务部署顺序和回退见版本与契约测试。

根据失败位置采取下一步

现象	重点核对	恢复验证
protoc 或插件无法执行	classifier、可执行文件、文件权限、编译器版本	清理生成目录后重新生成与编译
NoSuchMethodError、版本检查失败	生成代码与 runtime 的实际依赖树	固定兼容版本，重跑旧新消息样本
UNIMPLEMENTED	完整 service/method 名称、服务注册和代理路由	从同一 Schema 的存根调用已注册方法
UNAVAILABLE	名称解析、端口、HTTP/2、TLS/证书和服务状态	有预算的只读调用恢复，核对端点
DEADLINE_EXCEEDED	排队、连接、服务及下游耗时，剩余预算	缩短工作或调整合理预算，再确认取消生效
消息过大或流停住	消息限制、发送许可、接收读取、流控和缓冲	有界小消息成功，积压恢复后不持续增长
字段看起来“恢复默认值”	presence、未知枚举、JSON 中转、字段复制	检查 has 字段与原始值，再读历史输入

如果启用了 Server Reflection，可用支持它的调试工具列出服务；没有启用时需要提供 .proto 或 descriptor set。Reflection 暴露服务描述，管理接口和生产访问应按授权范围开放。对只支持 HTTP/1.1 或未正确转发 trailers 的中间代理，应先核对 gRPC 支持能力，而不是把所有 UNAVAILABLE 归为后端业务异常。

排错日志可先记录方法、状态、耗时和关联标识，令牌与完整消息体按数据访问政策控制。具有副作用的调用超时后，先按原操作身份查询结果，再决定是否重试。

权威资料与规范地址