gRPC · XB 现场笔记

Protobuf 演进只能在明确契约内保留含义

Sat, 26 Feb 2028 00:00:00 +0000

gRPC 滚动发布期间，旧生产方、新消费方与中间服务可能同时运行。Protobuf 通过字段编号和线上类型识别二进制内容，帮助这些版本交换消息。但能读懂格式，并不等于应用已经兼容：消息完全可以解析成功，消费方却误解数值、忽略新指令，或者丢掉“未提供”和“显式设置为零”的区别。审阅时需要把这些承诺分别列出来。

分开编号、含义与字节

二进制标签由字段编号与线上类型组合而成，字段名不在这个标签里传输。保持编号和类型不变而改名，可以保留二进制解码能力，但仍会改变生成代码的访问器，也可能改变 JSON 或文本接口。gRPC 的方法名与服务名属于另一层契约，不能因为字段编号没有变化，就认为任意接口改名都不影响调用。

已经退役的编号绝不能拿来表达另一种意思。不同声明类型可能共享相同线上类型，例如有符号与无符号整数都使用变长整数编码，但负数可能被另一种解释读成很大的正数。解析成功不是语义验证。删除字段后，应在 schema 中保留对应编号与名称的 reserved 声明，让后续声明无法意外占用；它是禁止使用的范围，不是留待日后激活的占位字段。

未知字段可以在二进制解析后重新序列化的转发路径中保留，但只复制已知字段，或中途转换为 JSON，都可能丢掉它们。保留解码信息也不保证每次序列化的字节完全相同，字段顺序与编码选择可能随实现或版本变化。兼容测试应比较必要取值和存在状态，不能把普通重新序列化当成跨版本规范化摘要算法。即使一次小样本碰巧字节相等，也不能推广成所有消息的承诺。

存在性承载另一层含义

在 proto3 中，没有 optional 修饰的单值标量通常采用隐式存在性，正常接口无法区分默认值与未提供。显式可选标量则记录字段是否被设置，即便取值为零也能保留这个事实。消息字段与 oneof 成员本来就具有存在性；重复字段和映射不能区分空集合与没有提供。因此，不能把所有 proto3 字段都归为同一种默认规则。

单值字段在隐式与显式存在性之间变化，可能仍然可以二进制互读，却改变转发后的结果。一个知道该字段、但仍用隐式存在性解释它的旧读方，可以读入显式零，然后在重新编码时把默认值省略。仅在一端加上 optional，不会迫使每个中间节点保留这一区别。需要测试实际修改或转发消息的整条路径，而不是只比较两个最终端点。

坏掉的样子

新版消费方可能要求一个旧写方从未提供的字段。虽然 proto3 不支持 required 声明，应用层校验仍然可以制造同样的滚动升级故障。应先约定缺失时的行为，或安排好发布顺序，再开始强制要求这个值。可选语法本身不会定义合理默认值，不会授权某个操作，也不会让旧服务突然实现新功能。这些决定必须由业务契约给出。

还应覆盖已保存消息、延迟任务以及可能回滚到的版本，它们的存活时间可能远长于发布窗口。只比较紧邻的上一个版本，会漏掉仍然可能重新出现的旧记录。即便当前流量已经不使用某个字段，退役编号仍然需要保留。重新投递旧任务与读取历史数据，都不能被当成无关的边缘情况。

快速验证

在 Python 环境中准备 Google 的 protobuf 7.36.2 包，再运行下面完整程序。本次使用 Python 3.12.14。独立描述符池创建真实的新旧消息类，不依赖编译器，不创建磁盘样本，不启动 gRPC 服务，也不建立网络连接。它验证 Python 二进制运行时，不能代替跨语言互操作或生成客户端兼容性测试。

from google.protobuf import descriptor_pb2 as schema, descriptor_pool, message_factory


def message(fields, explicit=()):
 file = schema.FileDescriptorProto(name='probe.proto', package='probe', syntax='proto3')
 record = file.message_type.add(name='Record')
 for name, number, kind in fields:
 field = record.field.add(name=name, number=number, type=kind, label=1)
 if name in explicit:
 field.oneof_index = len(record.oneof_decl)
 record.oneof_decl.add(name='_' + name)
 field.proto3_optional = True
 pool = descriptor_pool.DescriptorPool()
 pool.Add(file)
 return message_factory.GetMessageClass(pool.FindMessageTypeByName('probe.Record'))


INT32 = schema.FieldDescriptorProto.TYPE_INT32
UINT32 = schema.FieldDescriptorProto.TYPE_UINT32
STRING = schema.FieldDescriptorProto.TYPE_STRING
Old = message([('id', 1, INT32), ('name', 2, STRING)])
New = message([('event_id', 1, INT32), ('name', 2, STRING), ('count', 3, INT32)], ('count',))
Implicit = message([('event_id', 1, INT32), ('name', 2, STRING), ('count', 3, INT32)])

old = Old(id=7, name='alpha')
new_reader = New.FromString(old.SerializeToString())
assert new_reader.event_id == 7 and not new_reader.HasField('count')
# The added explicit zero is unknown to Old but retained in binary forwarding.
new_writer = New(event_id=7, name='alpha', count=0)
relay = Old.FromString(new_writer.SerializeToString())
returned = New.FromString(relay.SerializeToString())
assert returned.event_id == 7 and returned.HasField('count') and returned.count == 0
print('old/new binary values survive; unknown explicit zero survives the old relay')

# An implicit-presence reader knows field 3, so zero is omitted on serialization.
implicit_relay = Implicit.FromString(new_writer.SerializeToString())
lost_presence = New.FromString(implicit_relay.SerializeToString())
assert lost_presence.count == 0 and not lost_presence.HasField('count')
print('an implicit-presence relay preserves zero but loses its explicit presence')

Signed = message([('value', 1, INT32)])
Unsigned = message([('value', 1, UINT32)])
assert Unsigned.FromString(Signed(value=-1).SerializeToString()).value == 4294967295
# Distinct field order is legal; compare decoded meaning, not byte equality.
reordered = b'\x18\x00' + old.SerializeToString()
assert New.FromString(reordered) == new_writer
print('reusing an integer tag changes meaning; legal field orders decode equivalently')

第一行输出确认旧写方的数据仍然可读，而且旧二进制转发者会保留不认识的显式零。下一行展示另一种结果：当转发者认识该字段、却用隐式存在性处理它时，取值仍为零，但重新转发后 HasField 变成假。这是在回答两种不同的兼容问题，并不是运行时自相矛盾。

最后的断言把负一按不兼容的无符号解释读成 4294967295，同时接受另一种合法字段顺序。结果说明，线上可读不代表业务等价，也不代表字节具有唯一规范形式。这个描述符实验没有编译 reserved 声明；编译期约束、实际 gRPC 请求响应行为以及其他语言的转发路径，仍然需要在对应发布流程里单独验证，不能由这些本地断言代替。

来源

Protobuf：编码，标签、变长整数与序列化顺序，已核验 2026-10-15。
Protobuf：proto3 语言指南，二进制变更、退役字段与未知字段保留，已核验 2026-10-15。
Protobuf：字段存在性，转发中的隐式与显式存在性，已核验 2026-10-15。
Protobuf：该做与不该做，退役编号与兼容纪律，已核验 2026-10-15。

gRPC 用一条 HTTP/2 连接复用多条流

Sat, 16 Jan 2027 00:00:00 +0000

gRPC 的 HTTP/2 传输允许多个 RPC 尝试共享一条连接，同时保留每条流内部的消息顺序。这对短调用和长时间交换都可能有用，但并不意味着每个调用获得了一条无限且完全独立的传输通道。带宽、TCP 交付、连接级流控以及实现中的资源仍然共享，理解这些边界才能准确判断哪些阻塞能够隔离，哪些会影响其他调用。

让调用形式匹配实际工作

一次基于 HTTP/2 的 RPC 尝试占用一条流；重试会发起另一次尝试，而不是把字节重新写入已经结束的流。复用连接能够摊薄建连和 TLS 的成本，但一个 channel 可以管理多条连接，访问不同后端也不会自动共用同一个 TCP 端点。每次调用仍然包含序列化、元数据、帧处理、调度和业务工作，不能把额外成本说成只剩几个帧头。

gRPC 提供单次请求响应、客户端流、服务器流和双向流四类方法。只有双向流允许双方在同一次 RPC 内独立发送消息序列。每个方向的消息顺序得以保留，但不要求每条请求消息都对应一条回复。应当根据应用契约选择调用形式，而不是认为只要采用 gRPC，所有方法就自然具备双向持续推送能力；什么时候读取和写入，仍需应用合理安排。

HTTP/1.1 可以复用持久连接，WebSocket 本身也支持双向消息，二者都不要求每发送一条应用消息就重新握手。因此，不能用虚构的“一次消息一次连接”来证明 gRPC 总是更省。更有意义的比较包括 RPC 契约、生成接口、状态模型和 HTTP/2 多路复用，再结合完整负载和运维约束测量，才能判断实际延迟、内存和连接开销。

分开调用期限与共享传输

截止时间属于某次 RPC，并不会自动成为同一连接上所有流的统一期限。应通过语言支持的上下文机制向下游传递剩余预算；每经过一层就重新领取完整超时，可能让工作持续到调用方早已不愿等待之后。取消还需要业务代码配合停止工作，已经提交的副作用不会因此自动回滚，客户端未收到成功也不等于服务端没有完成修改。

HTTP/2 对 DATA 帧同时实施流级和连接级流控。某条流的窗口耗尽时，只要连接信用仍足够，其他流就可能继续传输。某个方向的连接信用耗尽，则会限制该方向上各条流继续发送 DATA，但并不禁止所有控制帧。接收端实现可以独立补充连接信用，所以一个慢读者并不必然拖到整条连接都没有额度；应观察真实实现如何管理缓冲和更新。

TCP 丢包仍然可能影响多个 HTTP/2 流共享的字节交付。队列、处理器和内存也会在协议流抽象之外造成耦合。应用向库写入成功，可能只是数据进入了库的缓冲，并不能证明已经送达对端或被业务消费。缓冲应当有界，并在实际客户端和服务器库上验证慢读者场景，不能仅凭连接仍然存活就认为吞吐和资源使用都正常。

坏掉的样子

过大的元数据可能超过实现或代理限制，使调用在业务处理器执行之前就被拒绝。gRPC 文档建议请求头默认限制可设为八 KiB，但这不是所有部署的固定上限，也不保证每一层都返回同一种错误状态。需要同时检查端点和中间代理，控制认证、追踪和其他元数据总量；原样重复一个过大的请求，通常不会解决拒绝原因。

长时间存在的流会停留在已经选中的后端。只按连接进行均衡，可能让很多流集中到少数实例；达到并发流上限后，新调用也可能只是排队，而不是自动另建连接或转移到空闲节点。应有意识地选择客户端或代理支持的均衡方式，观察各后端占用和重连行为。修改连接寿命或流数量限制，并不能单独证明负载已经重新分布。

快速验证

保存为 mux_sim.py，执行 python3 mux_sim.py。这个标准库模型包含三条有序队列，以及分别维护的流信用和连接信用。每条消息消耗一个自定义单位，并不是按真实字节计算的 HTTP/2 窗口，也没有编码协议帧。使用客户端式的奇数流标识，只是为了让结构容易辨认，不表示程序已经实现了完整线上协议。

from collections import deque

original = {1: ["a1", "a2", "a3"], 3: ["b1", "b2", "b3"], 5: ["c1", "c2"]}
streams = {sid: deque(items) for sid, items in original.items()}
credit = {1: 3, 3: 3, 5: 2}
connection_credit = 8
wire = []
delivered = {sid: [] for sid in streams}

def pump():
 global connection_credit
 progressed = False
 for sid in sorted(streams):
 if streams[sid] and credit[sid] > 0 and connection_credit > 0:
 payload = streams[sid].popleft()
 credit[sid] -= 1
 connection_credit -= 1
 wire.append((sid, payload))
 delivered[sid].append(payload)
 progressed = True
 return progressed

def drain():
 while pump():
 pass

assert pump()
assert wire == [(1, "a1"), (3, "b1"), (5, "c1")]
credit[3] = 0 # Model a receiver withholding this stream's credit.
drain()
assert delivered[1] == original[1] and delivered[5] == original[5]
assert delivered[3] == ["b1"] and len(wire) == 6
assert connection_credit == 2

credit[3] = 2
connection_credit = 0 # Independent negative control: no connection capacity.
assert not pump() and delivered[3] == ["b1"]
connection_credit = 2
drain()
assert delivered == original and len(wire) == 8
assert connection_credit == 0 and all(not queue for queue in streams.values())
print("wire:", wire)
print("PASS: stream credit isolates one stall; connection credit gates all modeled data")

第一次扫描后，停止补充三号流的信用，一号和五号流仍可完成，三号流则留下两条待发送消息。随后仅恢复三号流自己的额度，同时把连接额度设为零，程序不能再交付任何消息。最后恢复连接信用，八条消息全部送完，每条流中的内容都保持最初的顺序。两个对照将单流阻塞和共享连接容量不足明确分开，而不是只检查一份看似交错的日志。

这些断言验证的是模型自己声明的调度规则，不是真实 gRPC 库、HTTP/2 帧编码、TCP 丢包、TLS、截止时间传递、取消或负载均衡。线上验收仍需在实际栈中故意放慢某个消费者，并同时记录流级与连接级行为。只有把模型、库集成和部署流量三类证据分开，才不会从一条队列能够绕过另一条队列，错误推导出所有调用永远互不影响。

来源

gRPC 核心概念，定义基于 HTTP/2 的流，已核验 2026-06-01。
RFC 9113：HTTP/2，流、多路复用与流控，已核验 2026-09-09。
gRPC flow control，本次核对缓冲、调用预算、元数据或连接资源的对应边界，已核验 2026-10-15。
gRPC deadlines，本次核对缓冲、调用预算、元数据或连接资源的对应边界，已核验 2026-10-15。
gRPC metadata，本次核对缓冲、调用预算、元数据或连接资源的对应边界，已核验 2026-10-15。
gRPC performance guidance，本次核对缓冲、调用预算、元数据或连接资源的对应边界，已核验 2026-10-15。

gRPC · XB 现场笔记

Protobuf 演进只能在明确契约内保留含义

分开编号、含义与字节

存在性承载另一层含义

坏掉的样子

快速验证

来源

gRPC 用一条 HTTP/2 连接复用多条流

让调用形式匹配实际工作

分开调用期限与共享传输

坏掉的样子

快速验证

延伸阅读

来源