一、起源:跨服务调用的选择问题

进程之间的通信最终都要落到字节流与协议之上,区别只在于"由谁来负责把方法调用翻译成字节"。这一层翻译的承担者不同,就形成了 HTTP 调用与 RPC 调用两条技术路线。

1. 两条路线的出发点

HTTP 路线的出发点是通用性。HTTP 是公开标准,所有语言、所有平台都有成熟客户端;请求与响应是文本(或文本化的 JSON),可以用浏览器、curl、抓包工具直接观察;代理、负载均衡、网关、缓存、认证、访问日志这些基础设施天然围绕 HTTP 构建。用 HTTP 做服务间调用,几乎不需要额外的协议知识。

代价出现在三个地方:

开销来源 具体表现
文本协议的解析成本 报文需要按文本规则切分与转义,头部与正文都要做字符编码处理,解析器需要处理引号、转义、空白与大小写
头部与字段名的冗余 每个请求都携带完整的头部;JSON 的键名重复出现在每一条消息中,键名占用的字节数常常超过值本身
请求与响应的粒度 HTTP/1.1 一条连接同一时刻只处理一个请求,并发只能靠多条连接堆叠,连接建立与头部重复的开销被放大

RPC 路线的出发点是让远程调用在代码层面接近本地调用。调用方看到的是一段生成出来的客户端代码,方法签名、参数类型、返回类型都由接口定义文件(IDL)推导而来,序列化与网络传输被框架隐藏。契约在编写代码之前就已固定,参数类型错误在编译期就会暴露。

代价同样明确:

耦合来源 具体表现
协议耦合 服务端与客户端必须使用同一套 IDL,否则无法通信;协议不再是通用标准,而是框架约定
代码生成耦合 构建流程中多出代码生成环节,生成代码的版本、存放位置、与业务代码的关系都需要约定
工具链耦合 调试不能直接靠浏览器或 curl,需要专门的支持反射的客户端工具;抓包看到的是二进制帧,需要解码器才能阅读
生态耦合 网关、代理、负载均衡必须支持底层协议(通常是 HTTP/2),纯 HTTP/1.1 的基础设施无法直接复用

2. 契约的强度差异

两条路线最本质的差别不在性能,而在契约出现的时间点。

维度 HTTP + JSON RPC + IDL
契约载体 文档、OpenAPI 描述文件,或代码本身 接口定义文件(.proto 等)
契约校验时机 运行时(反序列化失败或字段缺失时) 编译期(生成代码不匹配时无法构建)
字段类型约束 弱(数字可能是字符串,缺字段与 null 难以区分) 强(字段类型与编号由 IDL 固定)
契约漂移风险 高(接口变更靠文档同步与人自觉维护) 低(不更新 IDL 就无法调用新字段)
演进方式 后端兼容(宽松反序列化、忽略未知字段) 前向与后向兼容由字段编号规则保证

契约弱不等于落后。对外接口面向不可控的调用方,必须允许"先能调通、再逐步完善"的演进方式,文档与运行时容忍度是必要的缓冲;内部服务面向可控的调用方,强契约带来的编译期保护能显著减少联调成本与线上字段错配。

两者的差别只在风格上:HTTP 的接口风格、方法与幂等语义见 HTTP API,其中也列出了 RESTful、RPC、GraphQL、gRPC 等风格在数据格式与协议上的定位。

3. 选型需要考虑的维度

维度 需要回答的问题 偏向 HTTP 偏向 gRPC
性能 单机 QPS 与延迟目标是多少;序列化与网络开销占比多大 请求量中等、报文较大、延迟要求宽松 高频小报文、延迟敏感、连接数多
契约与演进 调用方是否可控;类型错误能否等到运行时才发现 调用方不可控、需要宽松兼容 调用方可控、希望编译期校验
调试便利 是否经常需要人工构造请求验证;是否有非开发人员参与联调 需要浏览器、curl 直接调试 团队具备 gRPC 工具链与反射服务
生态与网关 现有网关、负载均衡、服务网格是否支持底层协议 全部基础设施可直接复用 需要支持 HTTP/2 与 trailers 的组件
团队成本 是否愿意承担 IDL 维护、代码生成、构建改造的成本 无额外学习成本 需要约定 IDL 组织与生成流程
流式需求 是否需要服务端推送、双向流、大结果集流式返回 需要额外机制(SSE、WebSocket) 原生支持四种调用方式

判断的顺序应当是先确认调用方是否可控与是否需要流式,再确认性能是否真的构成瓶颈,最后看基础设施能否承载。性能收益可以通过压测验证,而契约与工具链的成本是从第一天就开始支付的。

底层 IO 的组织方式(NIO 的多路复用、Reactor 与 Netty 的事件循环、粘包与背压的实现机制)决定了这些客户端与服务端的运行成本,其原理见 IO 模型与 Netty 第二部分,本文不重复 IO 模型本身,只讨论协议之上的调用组织与工程实践。


二、原理

1. 协议层对比

1.1 HTTP/1.1 的结构与限制

HTTP/1.1 报文是文本格式,由起始行、头部字段、空行与消息体构成:

POST /internal/inventory/deduct HTTP/1.1
Host: inventory-service:8080
Content-Type: application/json
Content-Length: 84
Authorization: Bearer <token>

{"skuId":"SKU-1001","quantity":2,"orderNo":"ORD-20260923-0001"}

它的三个限制直接影响服务间调用的成本:

限制 成因 后果
每连接一次一个请求 协议规定响应必须与请求严格配对,服务器按请求顺序返回 并发必须靠多条 TCP 连接;连接数随并发上升,握手与慢启动开销重复支付
队头阻塞 前一个响应未完成时,后续响应不能在连接上先行返回 慢请求会拖住同连接上的其他请求
头部重复且冗长 每个请求都要携带完整头部,文本形式不做压缩(除非启用头部压缩扩展) 小请求的头部开销可能超过消息体

管线化(pipelining)在理论上允许连续发送多个请求,但由于队头阻塞仍未解决、且中间代理支持不一致,实践中未被采用。

1.2 HTTP/2 的四项变化

HTTP/2 保留 HTTP 的语义(方法、状态码、头部字段),但把传输层从文本改为二进制分帧:

HTTP/1.1                         HTTP/2
┌──────────────────┐             ┌─────────────────────────────────┐
│ 一条连接          │             │ 一条连接                        │
│ ┌──────────────┐ │             │ ┌───────┐ ┌───────┐ ┌───────┐   │
│ │ 请求1 → 响应1 │ │             │ │Stream1│ │Stream3│ │Stream5│   │
│ ├──────────────┤ │             │ │ 帧 帧  │ │ 帧 帧  │ │ 帧 帧  │   │
│ │ 请求2 → 响应2 │ │             │ └───────┘ └───────┘ └───────┘   │
│ └──────────────┘ │             │ 帧可在一条连接上交错发送          │
└──────────────────┘             └─────────────────────────────────┘
能力 机制 对服务间调用的意义
二进制分帧 报文被切分为 HEADERS 帧、DATA 帧等,每帧带类型、标志与流标识 解析不再依赖文本规则,边界明确,解析成本更低
多路复用 不同请求分配不同的 Stream ID,帧在连接上交错传输,接收端按 Stream ID 重组 一条连接承载成百上千个并发请求,连接数与并发数解耦
头部压缩 HPACK 维护静态表与动态表,重复头部只发送索引 小报文的头部开销大幅下降
流控 连接级与流级两个窗口,接收方通告可接收的字节数 背压从"靠 TCP 缓冲"变为"显式通告窗口"
服务端推送 服务端可主动为某个请求推送关联资源 在 RPC 场景中基本不用,浏览器场景收益也有限
消息尾部(trailers) 在 DATA 帧之后可以发送额外的头部块 允许"先返回数据、再返回状态",这是流式 RPC 能携带结束状态的前提

多路复用的代价是连接级队头阻塞依然存在:由于 HTTP/2 的帧必须在同一条 TCP 连接上按序到达,任何一个 TCP 段丢失都会阻塞该连接上所有 Stream 的交付。因此"HTTP/2 消除了队头阻塞"这个说法只在应用层成立,传输层的问题被 TCP 的有序性继承下来。这也是 HTTP/3 改用 QUIC(基于 UDP)的动机。

HTTP/2 的明文版本(h2c)与 TLS 版本(h2)需要明确区分:浏览器只在 TLS 之上使用 HTTP/2,而内网服务间调用为了省去证书环节常使用 h2c。网关、代理、负载均衡必须显式支持对应的模式,否则会出现"客户端与服务端都是 HTTP/2,中间组件却按 HTTP/1.1 解析"的故障。

1.3 gRPC 在 HTTP/2 之上的复用方式

gRPC 没有另造传输协议,而是把 HTTP/2 当成承载层使用:

gRPC 概念 HTTP/2 中的对应物
调用的服务与方法 :path 伪头部,格式为 /包名.服务名/方法名
调用的内容类型 content-type: application/grpc+proto(或 application/grpc)
请求与响应消息 DATA 帧,每条消息前带 5 字节前缀(1 字节压缩标志 + 4 字节大端长度)
调用是否成功与错误码 grpc-status 与 grpc-message,一元调用放在 trailers,流式调用在结束帧中发送
超时预算 grpc-timeout 请求头,携带带单位的时长(如 3S、500m)
自定义元数据 普通头部字段(自定义键通常以 x- 或业务前缀开头)
压缩 grpc-encoding 与 grpc-accept-encoding 头部,以及对 DATA 帧的压缩

这个映射关系解释了 gRPC 的几个特性来源:

  1. 一元调用本质上是一次"半关闭的流":客户端发送一条消息后结束发送方向,服务端返回一条消息与结束状态,语义接近请求-响应,但复用了流机制。
  2. 流式调用是同一个流上多次消息往返:服务端流式在同一个 Stream 上连续发送多条 DATA 帧,最终以 trailers 携带状态结束。
  3. 错误码有两套:传输层的 HTTP 状态码(如 200、503)与业务层的 grpc-status。gRPC 约定传输层返回 200 并在 trailers 中给出 grpc-status,因此只看 HTTP 状态码无法判断 gRPC 调用是否成功,这一点是抓包与网关排障时最容易出错的地方。
  4. 中间组件必须透传 trailers:只处理 HTTP/1.1 头部、或把响应完全缓冲后转发的代理会丢掉 trailers,表现为"调用挂起后超时"或"状态丢失"。

1.4 文本与二进制的取舍

维度 文本协议(HTTP + JSON) 二进制协议(gRPC + Protobuf)
可读性 直接可读,日志与抓包即可定位 需要 schema 与解码工具
体积 字段名与引号占空间,数字按文本存储 字段用编号表示,数字用变长编码
解析成本 需要字符解析、转义处理、字符串到数字的转换 按长度与类型直接读取,无转义
容错性 解析器宽容,缺字段与类型不符可由代码兜底 严格按 schema 解析,未知字段被保留但不参与逻辑
适用场景 对外开放接口、前后端交互、调试与联调频繁的链路 内部高频调用、流式传输、跨语言强契约场景

值得注意的是"二进制更快"这个结论的成立条件:当消息体很小(几百字节以内)且网络往返占主导时,序列化格式的差异对端到端延迟的影响有限,此时选择 gRPC 的收益主要来自 HTTP/2 的复用与流控,而不是编码格式;当消息体较大(数十 KB 以上)或单机 QPS 很高时,序列化与解析的 CPU 占比上升,二进制编码的优势才会明显体现。

2. 接口定义与代码生成

2.1 接口描述语言与消息定义

gRPC 使用 Protobuf 的 IDL 描述接口。一个典型的定义包含消息(数据结构)与服务(方法集合)两部分:

syntax = "proto3";

package inventory.v1;

option java_package = "com.example.inventory.v1";
option java_multiple_files = true;
option java_outer_classname = "InventoryProto";

// 领域消息:字段编号一旦发布不可更改
message DeductRequest {
  string order_no = 1;
  string sku_id = 2;
  int32 quantity = 3;
}

message DeductResponse {
  bool success = 1;
  string trace_no = 2;
}

// 服务定义:四种调用方式都可以在此声明
service InventoryService {
  rpc Deduct(DeductRequest) returns (DeductResponse);
  rpc Query(QueryRequest) returns (stream StockSnapshot);
  rpc Upload(stream StockChange) returns (UploadResult);
  rpc Sync(stream SyncRequest) returns (stream SyncResponse);
}
// 声明字段编号已被占用,防止后续误用
message DeductRequest {
  reserved 4, 5;
  reserved "legacy_channel";
  string order_no = 1;
  string sku_id = 2;
  int32 quantity = 3;
}

三个必须遵守的约定:

  1. 字段编号是契约的一部分,不能重排或复用。编号决定线上编码,一旦发布就固定;删除字段时必须用 reserved 标记编号与名称,避免后续有人复用同一编号导致旧客户端解析出错。
  2. proto3 与 proto2 的语义不同。proto3 取消了 required,所有标量字段都有隐式默认值(数字为 0、字符串为空串、布尔为 false),因此无法区分"未设置"与"设置为默认值"。需要区分时使用 optional 关键字(生成 hasXxx() 方法)或包装类型。
  3. 包名与文件名承载版本信息。常见做法是在包名中带版本(inventory.v1),使新旧接口可以并存于同一进程,而不必依赖方法名后缀。

2.2 代码生成的产物与构建集成

Protobuf 编译器(protoc)配合 gRPC 的 Java 插件为每个 service 生成三类主要产物:

产物 作用
消息类(DeductRequest、DeductResponse 等) 不可变的数据载体,含构建器、序列化方法、parseFrom
阻塞式存根(InventoryServiceBlockingStub) 同步调用,方法返回响应对象,适合在业务线程中顺序调用
异步存根(InventoryServiceStub) 基于回调或 StreamObserver,是一元异步与流式调用的唯一入口
服务端基类(InventoryServiceImplBase) 需要继承并实现方法,覆写其中一个方法即可作为服务端实现
<!-- Maven 中的生成配置:protoc 插件调用编译器,grpc 插件生成存根 -->
<build>
    <extensions>
        <extension>
            <groupId>kr.motd.maven</groupId>
            <artifactId>os-maven-plugin</artifactId>
            <version>1.7.1</version>
        </extension>
    </extensions>
    <plugins>
        <plugin>
            <groupId>org.xolstice.maven.plugins</groupId>
            <artifactId>protobuf-maven-plugin</artifactId>
            <version>0.6.1</version>
            <configuration>
                <protocArtifact>
                    com.google.protobuf:protoc:3.25.5:exe:${os.detected.classifier}
                </protocArtifact>
                <pluginId>grpc-java</pluginId>
                <pluginArtifact>
                    io.grpc:protoc-gen-grpc-java:1.68.1:exe:${os.detected.classifier}
                </pluginArtifact>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>compile</goal>
                        <goal>compile-custom</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

工程上需要约定的事项:

事项 常见做法 理由
proto 文件的位置 独立模块或独立仓库统一存放,业务模块以依赖方式引入 契约需要单一来源,避免各服务各存一份副本后逐渐漂移
生成代码是否入库 不入库,构建时生成 生成产物随编译器版本变化,入库会造成大量无意义 diff 与冲突
生成代码是否手工修改 禁止修改,改动一律回到 proto 重新生成会覆盖手工改动,且行为与 IDL 不一致
protoc 与插件版本 在父级配置中锁定版本,禁止各模块自选 版本不一致会造成生成代码差异与运行时 NoSuchMethodError
生成代码的包隔离 生成到独立包(如 *.v1),业务代码不与其混淆 便于依赖管理与版本并存
IDEA 识别 把生成目录标记为源码目录 避免大量"找不到符号"的误报

2.3 生成代码的版本与兼容管理

IDL 与生成代码之间的关系类似于接口与实现,其版本管理遵循三条规则:

  1. IDL 向后兼容是发布前提。服务端可以先行发布(新增字段、新增方法),旧客户端继续使用旧字段;只有在确认所有调用方已升级后,才允许废弃字段。
  2. 新增方法对旧客户端不可见。旧客户端不会调用新方法,但若服务端移除了旧方法,旧客户端会在调用时收到 UNIMPLEMENTED。移除方法的正确顺序是:先停止调用、观察监控确认无流量、再从 IDL 中删除。
  3. 同一个 proto 包不可在两处定义。同名消息在两个模块中重复生成会导致类冲突;需要共享的消息应下沉到公共 proto 模块。

2.4 与 OpenAPI 的关系

OpenAPI 与 IDL 解决的是不同的问题,虽然都叫"接口描述":

维度 OpenAPI Protobuf IDL
描述对象 HTTP 接口(路径、方法、状态码、请求响应体) RPC 方法(消息类型、字段编号)
生成方向 生成文档、SDK、服务端骨架、测试用例 生成消息类与客户端存根
校验时机 构建期或运行期(取决于工具链) 编译期
契约来源 通常由代码或注解反向生成,也可先写描述再生成代码 以 IDL 为唯一来源
生态 HTTP 工具链、Mock、文档站点 gRPC 工具链、多语言存根

两者可以共存:gRPC 服务通过 grpc-gateway 或独立的 HTTP 适配层同时暴露 REST 接口,再由 IDL 或适配层生成 OpenAPI 描述,使内部走 gRPC、对外走 REST 的架构拥有统一的文档入口。接口风格与 REST 的语义约束见 HTTP API。

3. 序列化与兼容性

3.1 Protobuf 的编码特点

Protobuf 的编码单位是"字段",每个字段在字节流中由标签、类型与内容构成:

字段编号(3) 与 类型(3) 组合成一个 varint 标签   字段 1 的值
┌──────────────────────────────┐   ┌──────────────────────────┐
│ tag = (field_number << 3) | wire_type                        │
└──────────────────────────────┘   └──────────────────────────┘

wire_type:0 = varint(int32/int64/bool/enum)
           1 = 64 位固定长度(fixed64/double)
           2 = 长度前缀(string/bytes/嵌套消息)
           5 = 32 位固定长度(fixed32/float)

由此得到三项与体积相关的特性:

特性 机制 影响
字段名不参与编码 用字段编号代替字段名 消息中不重复出现键名,小消息的体积优势主要来自此处
整数用变长编码 数值越小占用字节越少(1 字节可表示 0~127) 小数值的整数开销极低;int32 表示负数时会占用 10 字节,负数场景应使用 sint32(ZigZag 编码)
默认值不参与编码 值为默认值(0、空串、false)的字段不写入字节流 空消息体积极小,但同时也意味着无法区分"未设置"与"设置为默认值"

体积优势的来源需要与 JSON 对照才清晰:同一个"订单号 + SKU + 数量"的结构,JSON 需要重复写入键名与引号,Protobuf 只写入编号与值。字段数量越多、字段名越长、消息条数越多,差距越明显;对于只有两三个短字段的消息,差距有限。各类序列化方案的完整对比(体积、速度、Schema、跨语言、安全)见 序列化与反序列化 第五章,本文不重复该对比表。

3.2 字段编号与兼容规则

Protobuf 的兼容性由字段编号机制保证,各类变更的安全性如下:

变更类型 是否兼容 说明
新增字段 兼容 旧客户端不解析未知字段;新客户端读到旧数据时字段为默认值,业务必须能接受该语义
删除字段 谨慎兼容 旧数据中的该字段被忽略;必须用 reserved 占位编号,防止复用
重命名字段 兼容 字段名不参与二进制编码,只影响生成的代码与 JSON 映射
int32 / int64 / uint32 / uint64 / bool 之间变更 部分兼容 都属于 varint,编码相容但数值可能溢出或语义改变,跨符号变更(如 int32 改 uint32)会出错
string 与 bytes 之间变更 部分兼容 当 bytes 内容恰好是合法 UTF-8 时可互通,否则反序列化失败
fixed32 与 sfixed32 之间变更 兼容 同属 wire_type 5
字段编号重排或复用 不兼容 会破坏既有数据的解析语义,属于最严重的错误
标量改为 message(或反向) 不兼容 wire_type 改变
新增必填语义 不兼容 proto3 无 required,业务校验不能替代协议层约束

3.3 枚举与默认值的处理要点

问题 表现 处理方式
枚举值未定义的处理 旧客户端遇到新枚举值时会保留原始数字,若代码用 switch 且未覆盖默认分支,会走入未定义行为 枚举的第一个值固定为 *_UNSPECIFIED = 0,所有 switch 必须有默认分支并记录告警
枚举值删除后复用 已删除的枚举值若被赋予新含义,旧客户端会把新值解释为旧语义 删除的枚举值用 reserved 占位,永不复用编号
无法区分"未设置"与"默认值" 数值字段为 0 时既可能是"调用方传了 0"也可能是"调用方没传" 需要使用 optional 或包装类型;对"清空字段"的语义要单独定义
集合字段为空 repeated 字段为空与未设置无法区分 通常不需要区分;若需要,用嵌套消息包裹
未识别字段被保留 proto3 会保留未知字段并在重新序列化时写回 一般无需干预,但若消息在中间层被重建,需确认保真性

3.4 与 JSON 的取舍

场景 推荐格式 原因
内部高频服务间调用 Protobuf 体积与解析成本低,契约由 IDL 固定
对外开放接口、前后端交互 JSON 可读、可调试、调用方无需 IDL
需要人工排查链路的日志与调试通道 JSON 可直接阅读与检索
大报文与流式传输 Protobuf + 流式 避免整体序列化带来的内存峰值

JSON 一侧的兼容实践与 Protobuf 不同,主要依赖反序列化器的宽容度:忽略未知字段、缺失字段保留默认值、字段名变更通过别名映射、时间与金额用字符串表示。这些做法的共同目标是"让旧代码能读新报文"。

4. gRPC 调用方式

4.1 四种调用方式的语义

方式 IDL 声明 语义 适用场景
一元(Unary) rpc M(Req) returns (Resp) 一次请求一次响应,语义接近普通方法调用 绝大多数业务接口
服务端流(Server streaming) rpc M(Req) returns (stream Resp) 一次请求,服务端返回多条消息 大结果集分页推送、进度上报、订阅变更、日志拉取
客户端流(Client streaming) rpc M(stream Req) returns (Resp) 客户端发送多条消息,服务端返回一条汇总结果 批量上传、分片写入、聚合统计
双向流(Bidirectional streaming) rpc M(stream Req) returns (stream Resp) 双向都可以连续发送消息 会话式交互、实时同步、需要服务端按需应答的场景
// 一元调用:同步存根,适合在业务线程顺序调用
DeductResponse response = blockingStub
        .withDeadlineAfter(800, TimeUnit.MILLISECONDS)
        .deduct(request);

// 异步存根:一元调用在回调线程中完成
asyncStub.deduct(request, new StreamObserver<DeductResponse>() {
    @Override
    public void onNext(DeductResponse value) { /* 处理响应 */ }

    @Override
    public void onError(Throwable t) { /* 处理失败,t 为 StatusRuntimeException */ }

    @Override
    public void onCompleted() { /* 正常结束 */ }
});
// 服务端流:客户端用同一个 StreamObserver 接收多条消息
Iterator<StockSnapshot> it = blockingStub.query(queryRequest);   // 阻塞式迭代
while (it.hasNext()) {
    handle(it.next());
}

// 客户端流:写完后调用 onCompleted 触发服务端返回汇总结果
StreamObserver<StockChange> upstream = asyncStub.upload(new StreamObserver<UploadResult>() {
    @Override
    public void onNext(UploadResult value) { /* 汇总结果 */ }

    @Override
    public void onError(Throwable t) { /* 失败 */ }

    @Override
    public void onCompleted() { /* 结束 */ }
});
for (StockChange change : changes) {
    upstream.onNext(change);        // 逐条发送
}
upstream.onCompleted();             // 必须调用,否则服务端不会返回结果

4.2 流控与背压

gRPC 的流控建立在 HTTP/2 的窗口机制之上,但应用层还有一层"消息级"的控制:

应用层:StreamObserver 的消息投递
   ├── onNext 写入的消息进入发送队列
   ├── ServerCallStreamObserver.isReady() 表示队列有空间
   └── setOnReadyHandler 在队列由满转空时回调
HTTP/2 层:流窗口与连接窗口
   └── 接收方按窗口通告可接收字节数,窗口耗尽时发送方暂停
TCP 层:接收缓冲区与拥塞窗口

三层机制的分工与作用:

层次 机制 触发条件 应用侧应做的事
TCP 接收窗口与拥塞窗口 网络拥塞或对端读取慢 无需干预
HTTP/2 流窗口与连接窗口 单流或整条连接的未确认数据达到窗口上限 无需干预,框架自动更新窗口
gRPC 应用层 isReady() 与 onReady 事件 单条流上的发送队列积压超过阈值 必须显式处理:不判断可写性而持续 onNext,会在内存中堆积直至 OOM

背压的正确实现方式是在不可写时暂停数据来源,而不是丢弃或无限缓冲:

// 服务端流式接口:不可写时暂停上游,出现 onReady 时恢复
public void query(QueryRequest request,
                  StreamObserver<StockSnapshot> responseObserver) {
    ServerCallStreamObserver<StockSnapshot> observer =
            (ServerCallStreamObserver<StockSnapshot>) responseObserver;

    observer.setOnReadyHandler(() -> {
        while (observer.isReady() && source.hasNext()) {
            observer.onNext(source.next());         // 只在可写时投递
        }
        if (!source.hasNext()) {
            observer.onCompleted();
        }
    });
}

客户端侧的流式读取同样需要控制:阻塞式迭代器(blockingStub 返回的 Iterator)天然提供背压,因为只有调用 next() 时才会拉取下一条;而异步回调方式下,框架会持续投递消息,若回调内做耗时处理,会积压在回调线程中,需要通过自定义 Executor 把处理移出或使用 ClientResponseObserver 的 beforeStart 控制请求速率。

4.3 截止时间与取消传播

gRPC 的截止时间(deadline)不是"读超时",而是从调用发起到完成的绝对时间预算:

概念 含义 相关状态码
截止时间 客户端设定的完成期限,到达期限时框架主动取消调用 DEADLINE_EXCEEDED
取消 调用方主动终止调用(如用户请求已断开、上游已超时) CANCELLED
传播 截止时间通过 grpc-timeout 头部传给下游,剩余预算逐跳递减 —

关键性质是截止时间逐跳递减:客户端设定 1 秒预算,服务端 A 收到时剩余预算已扣除网络耗时,A 再调用 B 时会把剩余预算继续传递。这带来两个工程结论:

  1. 超时预算必须在链路各层之间分配,而不是每层独立设定一个固定值。若每层都设 1 秒,最坏情况下总耗时是 1 秒乘以层数。
  2. 服务端必须感知取消。客户端取消后,服务端若继续执行(继续查询数据库、继续计算),资源被白白消耗。服务端应通过 Context.current().isCancelled() 或 ServerCallStreamObserver.isCancelled() 定期检查并提前退出。
// 服务端感知取消:在耗时循环中检查,及时释放资源
public void longRunning(LongTaskRequest request,
                        StreamObserver<LongTaskResponse> responseObserver) {
    Context context = Context.current();
    for (Chunk chunk : chunkSource) {
        if (context.isCancelled()) {
            return;                     // 调用方已放弃,不再继续消耗资源
        }
        process(chunk);
    }
    responseObserver.onNext(buildResponse());
    responseObserver.onCompleted();
}

4.4 元数据与拦截器

元数据(metadata)是附着在调用上的键值对,一元与流式调用都可用,分为客户端发送的请求元数据与服务端返回的响应元数据。它承担三类职责:传递认证凭据、传递上下文(追踪标识、租户、灰度标签)、传递框架级参数。

项 客户端 服务端
键的命名 小写,使用 x- 或业务前缀避免与框架冲突 同左
传输方式 作为 HTTP/2 头部随首次请求发送 作为响应头部或 trailers 返回
二进制值 键以 -bin 结尾,值按 Base64 编码 同左
大小限制 默认受 HTTP/2 头部大小限制(服务端可配 maxInboundMetadataSize) 同左

拦截器是横切逻辑的统一入口,其位置与职责和 HTTP 中的过滤器类似:

// 客户端拦截器:统一注入认证与追踪元数据
public class AuthClientInterceptor implements ClientInterceptor {

    @Override
    public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(
            MethodDescriptor<ReqT, RespT> method,
            CallOptions callOptions,
            Channel next) {

        return new ForwardingClientCall.SimpleForwardingClientCall<>(
                next.newCall(method, callOptions)) {

            @Override
            public void start(Listener<RespT> responseListener, Metadata headers) {
                headers.put(Metadata.Key.of("authorization",
                        Metadata.ASCII_STRING_MARSHALLER), "Bearer " + currentToken());
                headers.put(Metadata.Key.of("x-trace-id",
                        Metadata.ASCII_STRING_MARSHALLER), currentTraceId());
                super.start(responseListener, headers);
            }
        };
    }
}
拦截器职责 客户端侧实现要点 服务端侧实现要点
鉴权 从上下文中取令牌注入元数据,不缓存在实例字段中 校验元数据、设置 Context,失败时以 UNAUTHENTICATED 结束调用
日志 记录方法名、状态码、耗时,避免打印完整消息体 同左,并记录调用方标识
追踪 从当前上下文提取追踪标识写入元数据 从元数据恢复上下文,跨线程时显式传递
超时 统一设置默认截止时间,业务侧可用 withDeadlineAfter 覆盖 读取 grpc-timeout 预算,超过处理能力的请求提前拒绝
指标 统计调用次数、失败次数、延迟直方图,按方法名区分 统计入站请求与并发数
限流 对特定下游限制并发(信号量) 按调用方或方法限流,超限返回 RESOURCE_EXHAUSTED

拦截器的顺序即执行顺序,且客户端拦截器在外层、服务端拦截器在内层,链上任何一环抛出异常都会中断调用。涉及 Context 的拦截器必须使用 Contexts.interceptCall 包装,否则上下文会在异步回调中丢失。服务间调用的身份模型、内部凭据形态与令牌校验位置(网关集中校验与服务自校验的取舍)见 Java 认证授权与接口安全。

5. HTTP 客户端机制

5.1 连接池与连接复用

HTTP/1.1 的并发靠多连接堆叠,因此连接池是所有生产级 HTTP 客户端的必备组件。连接池的核心参数与含义:

参数 含义 设置过小的后果 设置过大的后果
每路由最大连接数 对同一个主机与端口允许建立的最大连接数 并发请求排队等待连接,表现为"耗时等于排队时间加处理时间" 下游瞬时并发上升,可能压垮下游或触发对端连接数限制
总最大连接数 连接池整体上限,通常为每路由上限乘以路由数 多下游场景下互相挤占 本进程 fd 与内存占用上升
获取连接等待时间 从池中取不到连接时的最大等待时长 快速失败,可能把下游的短暂抖动放大为错误 线程被长时间占用,故障时线程池被拖满
空闲连接存活时间 空闲连接在多长时间后被回收 频繁重建连接,重复握手开销 连接长期指向已下线的实例,出现"连接陈旧"错误
连接有效性校验 借用连接前或空闲期检测连接是否可用 使用已关闭的连接,出现 NoHttpResponseException 类错误 校验本身带来开销

连接复用的前提是服务端与中间组件不会主动断开空闲连接。常见的断连来源有三类:负载均衡或网关的空闲超时(如 60 秒)、服务端的 keepalive 超时、NAT 网关的会话老化。客户端侧对应的处理是把空闲连接存活时间设置为小于中间组件的空闲超时,并在借用时做有效性校验。

连接数上限的估算方式是以并发量为输入:

所需连接数 ≈ 目标并发请求数 / 单连接可承载的并发(HTTP/1.1 为 1,HTTP/2 为多路复用后的流数上限)
所需连接数还需满足:连接数 × 单请求平均耗时 ≤ 目标 QPS × 目标响应时间

对 HTTP/2 客户端而言,一条连接即可承载大量并发流,连接池的意义从"提供并发"变为"提供容错与负载分散",每路由的连接数通常个位数即可。

5.2 超时参数的分层

HTTP 客户端的超时不是单一参数,而是一组,混淆它们是配置错误的主要来源:

超时类型 覆盖范围 典型参数名
连接超时 TCP 三次握手阶段 connectTimeout
从池中获取连接的等待超时 连接池借出连接前的排队时间 connectionRequestTimeout(Apache HttpClient)、pendingAcquireTimeout(Reactor Netty)
读超时(socket 超时) 连接建立后,两次数据到达之间的最大间隔 socketTimeout / readTimeout
写超时 写入请求体的最大时长 部分客户端提供
总超时(响应超时) 从发起到收到完整响应的整体时长 responseTimeout(Reactor Netty)、callTimeout(OkHttp)
整体调用预算 应用层为一次业务操作设定的总预算,包含重试 业务侧自行实现

四者的关系是总超时应当大于等于各分项之和的上限,而业务层的调用预算应当大于等于客户端的总超时乘以最大重试次数。若这个不等式被打破,会出现"客户端还在重试、上层已经放弃"的无效等待。

读超时与总超时的差别在流式响应场景中最明显:使用读超时时,只要服务端持续发送数据就不会超时,适合长连接推送;使用总超时时,无论是否有数据到达,到达期限即中断,适合有明确完成时间的调用。

5.3 重试与幂等

客户端重试的判定条件包含三类:连接类失败(连接被拒绝、连接重置、连接超时)、可读的响应类失败(特定的 5xx 状态码、429)、以及白名单化的异常类型。业务错误(4xx)不应重试,因为同样的请求会得到同样的结果。

重试与幂等的关系与三个约束:

操作类型 是否可自动重试 前提
查询类(GET) 可 无
幂等写(PUT、删除、状态置为固定值) 可 服务端实现真正幂等
非幂等写(POST 创建、扣减、追加) 仅在幂等机制就位后 幂等键唯一约束或条件更新
不确定是否已执行的调用(写超时) 需谨慎 写超时意味着请求可能已到达并执行,盲目重试可能造成重复写入

重试的放大效应需要定量理解:若单个请求重试 3 次,链路上有 3 跳都开启重试,则最坏情况下一次用户请求在下游放大为 3 的 3 次方,即 27 次调用。因此工程上通行两条约束:

  1. 只在链路的某一层开启重试,通常是离用户最近的一层(网关或入口服务),内部各跳不重复重试。
  2. 重试必须退避且带抖动,避免下游故障恢复瞬间被同步的重试流量再次打垮。

5.4 重定向与压缩

重定向在服务间调用中通常不被期望:出现 3xx 往往意味着网关配置变更、接口路径迁移或认证跳转。自动跟随重定向存在两个风险:跨域重定向会把认证信息带到非预期的目标;重定向后的请求可能是非幂等的。因此生产客户端通常关闭自动跟随,把 3xx 作为错误上报,由配置层显式处理。

压缩(Accept-Encoding: gzip)用于降低网络传输量,代价是两端的 CPU 消耗:

维度 影响
适用条件 报文可压缩率高(文本、JSON、日志类),且网络带宽相对 CPU 更紧张
不适用条件 报文已是压缩格式(图片、视频、已压缩的二进制),压缩率接近 1 却要付出 CPU
客户端的隐含成本 压缩响应在解压时需在内存中展开,若对响应体大小没有上限,"压缩炸弹"可造成巨额内存占用
中间组件 网关与代理可能已开启压缩,客户端侧再开启会产生重复压缩与重复解压

5.5 同步、异步与响应式客户端的选择

客户端 模型 适用 注意
HttpURLConnection 同步阻塞 简单的脚本式调用,依赖为零 无连接池,功能少,不推荐用于业务链路
Apache HttpClient 同步阻塞,连接池成熟 传统同步业务链路,需要精细控制连接池与重试 配置项多,需要理解各超时参数的分工
OkHttp 同步与异步并存 需要简单 API 与良好默认值 连接池与拦截器体系与 gRPC 风格接近
JDK HttpClient 同步与异步(CompletableFuture) 新项目,希望减少第三方依赖 HTTP/2 支持完善,但生态与可观测接入不如主流客户端丰富
Spring RestClient / WebClient 同步 / 响应式 Spring 项目中调用其他服务 底层对应不同连接池实现,超时配置方式不同
Feign 等声明式客户端 同步接口 + 注解 需要统一契约与拦截器时 超时与重试由底层客户端承担,配置需要落到具体实现

选择的关键是与调用链路的线程模型一致:调用链路是同步阻塞的(典型的 Servlet 加 JDBC 组合),使用同步客户端最简单,阻塞的成本由线程池承担;调用链路是响应式的,必须使用响应式客户端,否则在事件循环线程中调用阻塞客户端会拖垮整个事件循环。关于同步与响应式模型在 Web 层的取舍见 Java Web 与 IO 模型与 Netty 第三部分第 5 小节。

6. 稳定性设计

6.1 超时、重试与熔断的组合

三者的分工是:超时限定单次调用的等待上限,重试缓解偶发失败,熔断在下游持续失败时停止发送流量。组合时存在一组必须满足的关系:

业务层调用预算 ≥ 客户端总超时 × 最大重试次数 + 退避总时长
客户端总超时 ≥ 连接超时 + 读超时
单跳超时预算 ≤ 上游剩余预算(逐跳递减)

若业务层预算小于客户端可能消耗的最长时间,会出现"上游已超时返回失败、下游仍在继续处理"的无效工作;若客户端总超时小于下游的典型处理时间,会出现"正常请求被判为失败并重试",把流量放大并进一步拖慢下游。

熔断、限流、降级与隔离的完整原理(状态机、判定参数、隔离方式、降级策略)见 Spring Cloud 微服务 第 2.6 节,本节只讨论与通信客户端直接相关的组合约束。

6.2 重试放大与雪崩

重试是故障放大器的机制如下:

下游变慢
  → 客户端超时
  → 触发重试(同一请求再次进入下游)
  → 下游负载上升,变得更慢
  → 更多请求超时
  → 重试次数继续增加
  → 下游被自己的重试流量压垮

切断这个正反馈的手段有四条:

手段 作用点 实现
只在一层重试 减少重复放大 网关或入口层开启,内部各跳关闭
重试预算(比例限制) 限制重试流量占比 客户端把重试次数限制为总请求数的一定比例(如 10%),超出则不再重试
熔断 停止发送流量 失败率达到阈值后直接拒绝,不产生真实调用
并发限制与排队上限 限制在途请求数 信号量或限流器限制对单个下游的并发,超限快速失败而非排队

6.3 并发限制与排队

连接池的队列与限流器的信号量是两类不同的排队:

机制 排队对象 排队位置 超时表现
连接池等待队列 等待获得连接的请求 客户端进程内 获取连接超时(如 ConnectionPoolTimeoutException)
限流器等待队列 等待获得许可的请求 客户端进程内 排队超时或直接拒绝
服务端线程池队列 已到达服务端的请求 服务端进程内 服务端处理延迟上升,从客户端看是读超时
服务端连接队列 等待 accept 的连接 服务端内核 客户端连接超时

排队的本质是把故障从快速失败转换为慢速失败,因此排队上限与等待超时必须同时设置。排队上限过大、等待超时过长,会让故障表现为"所有请求都慢"而不是"部分请求失败",影响面更大。

6.4 降级返回

降级的返回方式必须与业务语义匹配:展示类查询可以返回缓存值或空结果,涉及金额与状态的写操作必须快速失败而不能返回兜底值。降级实现需要注意两点:降级分支中记录的日志必须能区分"降级触发"与"真实结果",否则会掩盖问题;降级返回值要在接口契约中显式定义,不能依赖调用方的容错。

7. 服务端侧关注点

7.1 线程模型与阻塞

gRPC 的 Java 服务端默认使用一个共享的线程池执行服务实现,ServerBuilder.executor() 可以替换;HTTP 服务端(Servlet 容器)则使用容器的工作线程池。两者的共同约束是在服务方法中执行阻塞操作会占用承载网络事件的线程资源。

服务端类型 默认执行模型 阻塞操作的处理
gRPC Java 服务端 共享线程池,默认线程数随 CPU 变化 通过 executor() 指定独立业务线程池;流式接口的回调同样在其上执行
Servlet 容器 每请求一个工作线程 阻塞属正常模型,但线程池大小决定并发上限;需要配置虚拟线程或异步 Servlet
响应式服务端 事件循环线程 禁止阻塞,阻塞调用必须切换到独立的调度器

gRPC 服务端还有一个特有约束:StreamObserver 的调用不是线程安全的,一个流上的 onNext 不能从多个线程并发调用,否则会出现帧交错或 IllegalStateException。流式接口若需要并发产生数据,必须把结果汇总到同一线程或串行化后投递。

7.2 请求大小与流式处理

默认的消息大小限制是防止单条报文耗尽内存的第一道防线:

组件 参数 默认值 说明
gRPC 服务端 maxInboundMessageSize 4 MB 超过上限的入站消息以 RESOURCE_EXHAUSTED 拒绝
gRPC 客户端 maxInboundMessageSize 4 MB 限制接收到的响应消息大小
HTTP 容器 最大请求体大小 视容器而定 超限返回 413
HTTP 容器 最大请求头大小 视容器而定 超限返回 431 或直接断开
网关 请求与响应体上限 视产品而定 常见的隐形限制来源

大报文的处理方式与"是否流式"直接相关:整体传输意味着序列化后的完整字节数组与反序列化后的对象同时在内存中存在,峰值内存约为报文的数倍;流式传输把报文切分为多条消息,峰值内存与单条消息大小成正比,但要求上下游都支持流式,且中间不能有做全量缓冲的组件。批量传输的接口设计建议(分页、引用传递、流式返回)见 Spring Cloud 微服务 第 3.3.4 节。

7.3 超时与取消的服务端感知

服务端必须能感知两类中断:

中断来源 gRPC 的感知方式 HTTP 的感知方式
客户端超时或取消 Context.isCancelled()、ServerCallStreamObserver.isCancelled() 连接已断开(写入时异常),异步 Servlet 的超时回调
服务端自身超时 在业务逻辑中设置处理期限 异步请求超时、线程池任务超时

处理原则是在耗时段落之间检查中断标志:数据库查询、循环计算、外部调用前后都应检查,代价很低而收益明确。若服务端完全不感知取消,会出现"客户端已放弃、服务端仍在满负荷计算"的资源浪费,在批量或流式接口上尤其明显。

7.4 gRPC 与网关、负载均衡的兼容性

这是 gRPC 落地中最容易出问题的环节,原因是 gRPC 依赖 HTTP/2 的若干特性,而中间组件的支持程度不一:

组件能力 要求 不支持时的表现
HTTP/2 支持 网关必须支持 h2 或 h2c 请求被按 HTTP/1.1 解析,返回 400 或直接失败
trailers 透传 必须保留响应 trailers grpc-status 丢失,表现为调用挂起至超时,或状态被误判为成功
流式转发 不能对响应做全量缓冲 流式接口退化为"等全部数据生成完才返回",延迟与内存同时恶化
空闲超时配置 空闲超时应大于客户端的 keepalive 间隔 长连接被中间组件静默断开,客户端出现 UNAVAILABLE
七层负载均衡 需要按 HTTP/2 流做分发 连接级均衡会因长连接而分布不均,部分实例过载
健康检查 网关需要调用 gRPC 健康检查协议 网关无法判断实例可用性,可能把流量路由到未就绪实例

负载均衡有两种放置方式,各有前提:

方式 机制 前提 特点
服务端侧(集中式) 客户端连接负载均衡器,由其转发到实例 负载均衡器支持 HTTP/2 多路复用并做流级分发 客户端简单;负载均衡器成为必须高可用的组件
客户端侧 客户端从注册中心获取实例列表,直接连接实例 客户端具备名称解析与服务发现能力 少一跳,延迟低;客户端需要感知实例变化

客户端侧负载均衡在长连接场景下需要额外注意:连接建立后不会随实例列表变化自动重连到新实例,若采用"每目标一条长连接"的简单策略,新增实例不会分担流量。解决办法是使用带子通道池的实现(如 gRPC 的 round_robin 策略会为每个后端地址维护子通道),或缩短连接存活时间。


三、实现

1. 选型落地建议

1.1 分场景的推荐

场景 推荐方案 主要理由
内部服务间高频调用 gRPC + Protobuf 契约强、体积小、支持流式、连接复用充分
内部服务间低频调用 HTTP + JSON 调用量低时序列化收益不显著,调试与排障成本更低
对外开放接口 HTTP + JSON(OpenAPI 描述) 调用方不可控,需要可读、可调试、工具链通用
前后端交互 HTTP + JSON(REST 风格) 浏览器与移动端生态天然支持,缓存与调试能力完备
需要服务端推送或大结果集 gRPC 服务端流,或 HTTP 的 SSE 避免轮询;gRPC 原生支持,HTTP 侧需要长连接支持
已有大量 HTTP 基础设施且改造受限 HTTP + JSON 网关、日志、监控链路无需改造

1.2 混合协议下的网关策略

同时存在两种协议时,网关是唯一需要同时理解两者的组件,其职责应当明确:

职责 做法 注意
协议转换 对外暴露 REST,内部转为 gRPC 错误码需要在转换层做映射,避免把 gRPC 状态码直接暴露给外部
协议分流 按路径前缀或 content-type 分流 分流规则必须与客户端约定一致,避免同一接口被两种协议同时访问
流式适配 gRPC 服务端流转换为 SSE 或分块响应 转换层不能缓冲整个响应,需要逐条透传
元数据透传 把 HTTP 头部映射为 gRPC 元数据 只透传白名单,身份类头部必须由网关重新写入
大小限制 统一设置请求与响应体上限 网关的默认上限常常小于应用配置,是"看起来配置正确但请求失败"的常见原因

1.3 迁移路径

从 HTTP 迁移到 gRPC 的过程可以分四步,每步都可独立上线与回滚:

  1. 建立契约层。把现有 HTTP 接口的请求与响应结构翻译为 proto 定义,此时不改变通信方式,只让契约成为可编译的单一来源。
  2. 双协议共存。服务端同时暴露 HTTP 与 gRPC 接口,同一份业务逻辑由两个入口调用,通过协议转换层复用校验与领域逻辑。
  3. 按调用方逐步切换。先切换内部调用方(可控、易回滚),观察指标(成功率、延迟分位、错误码分布)稳定后再切换下一批。
  4. 下线旧协议。确认监控无流量后移除 HTTP 入口,同时清理网关路由与文档。

高危 切换通信协议或序列化方式(HTTP + JSON 改为 gRPC + Protobuf,或反向切换)

  • 影响范围:链路两端必须同时具备新协议能力,任何一端未就绪即调用失败;网关、负载均衡、服务网格、日志与追踪组件都需要支持新协议,否则表现为请求失败、链路断链或指标缺失;错误码体系随之变化,原有依赖 HTTP 状态码的告警与熔断判定全部失效;序列化方式切换后,报文不可读,排障从"看日志"变为"需要工具解码"。
  • 回滚方式:保留双协议入口是回滚的前提,切换期间不要把旧协议入口一并移除;客户端侧通过配置开关切换协议实现,回滚时下发旧配置并重启或触发配置刷新;若已下线旧入口,需要重新发布旧版本;契约侧不得在切换过程中删除原有字段编号与枚举值,否则回滚后旧客户端无法解析新报文。
  • 前置要求:先在预发环境用真实流量验证完整链路(含网关、负载均衡、追踪、日志);确认所有调用方已完成升级;准备好回归到旧协议的配置开关与操作步骤;切换按调用方分批进行,每批之间保留观察窗口。

2. gRPC 实践

2.1 服务定义与生成代码的组织

推荐的组织方式是"契约模块 + 生成代码 + 服务端实现 + 客户端封装"四层分离:

inventory-contract/                # 只放 .proto,产出 Java 库
└── src/main/proto/inventory/v1/inventory.proto
inventory-service/                 # 服务端:依赖 contract,实现 ImplBase
└── .../InventoryServiceImpl.java
inventory-client/                  # 客户端:依赖 contract,封装 Stub 与管理连接
└── .../InventoryClient.java

客户端封装层的职责是把 Stub 与连接管理收敛到一处,业务代码不直接持有 ManagedChannel:

public class InventoryClient implements AutoCloseable {

    private final ManagedChannel channel;
    private final InventoryServiceBlockingStub stub;

    public InventoryClient(String target, Executor executor) {
        this.channel = ManagedChannelBuilder.forTarget(target)
                .usePlaintext()                                   // 内网可用;跨网必须使用 TLS
                .executor(executor)                               // 不阻塞默认共享线程池
                .keepAliveTime(30, TimeUnit.SECONDS)              // 小于中间组件空闲超时
                .keepAliveWithoutCalls(false)                     // 无调用时不发心跳,避免被判定为异常流量
                .maxInboundMessageSize(16 * 1024 * 1024)          // 与业务报文上限匹配
                .intercept(new AuthClientInterceptor(), new TraceClientInterceptor())
                .build();
        this.stub = InventoryServiceGrpc.newBlockingStub(channel);
    }

    public DeductResponse deduct(DeductRequest request, Duration timeout) {
        return stub.withDeadlineAfter(timeout.toMillis(), TimeUnit.MILLISECONDS)
                .deduct(request);
    }

    @Override
    public void close() {
        channel.shutdown();
        try {
            if (!channel.awaitTermination(5, TimeUnit.SECONDS)) {
                channel.shutdownNow();                       // 超时后强制关闭
            }
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            channel.shutdownNow();
        }
    }
}

要点说明:

要点 说明
ManagedChannel 应当复用 它内部管理连接与子通道,每次调用都新建会重复握手且耗尽 fd
显式指定 executor 默认共享线程池被阻塞回调占满时会影响同一 JVM 内其他 gRPC 调用
不使用 blockingStub 的默认截止时间 不设截止时间意味着调用可能无限等待,必须由拦截器或调用点统一设置
usePlaintext 仅限受控内网 跨网段、跨集群必须使用 TLS;这是安全要求而非性能取舍
关闭顺序 先 shutdown(拒绝新调用、等待在途完成),再 awaitTermination,最后 shutdownNow

2.2 拦截器实现要点

关注点 要点
鉴权 令牌从请求级上下文获取,不放入拦截器实例字段;拦截器可能被多线程并发复用
日志 记录方法名、状态码、耗时、调用方标识;不打印完整消息体,大报文场景会显著增加日志量并可能记录敏感数据
追踪 使用 Contexts.interceptCall 包装,保证 Context 在异步回调中可用;元数据键与团队约定统一
超时 统一设置默认截止时间,并允许调用点覆盖;服务端侧读取剩余预算,不足时以 DEADLINE_EXCEEDED 快速失败
指标 按方法名与服务名打标签,统计调用次数、失败次数、延迟直方图;标签基数需要控制
异常转换 把 StatusRuntimeException 中的 Status 转换为业务异常,业务层不直接依赖 gRPC 类型
顺序 鉴权、追踪应在最外层(先建立上下文),日志与指标在其内层(记录真实耗时),异常转换在最内层

2.3 流式接口的使用注意

环节 风险 做法
客户端读取阻塞式迭代器 未读完的流占用连接与服务端资源 使用 try 结构或显式取消;不完整读取时必须 cancel
服务端流写入 不判断 isReady() 持续 onNext 造成内存堆积 使用 setOnReadyHandler,按可写性暂停数据来源
双向流的线程安全 多线程并发 onNext 造成帧交错 同一流上的写入串行化
流未正常结束 忘记调用 onCompleted,服务端一直等待 客户端流与双向流的发送侧必须在结束发送时显式完成
流式接口的错误处理 中途失败后连接状态不明 失败时以 onError 结束,并明确流是否可重建
长流与中间组件 网关或负载均衡的空闲超时切断长时间无数据的流 配置心跳消息或与中间组件的空闲超时对齐
流的生命周期 客户端重启后流未关闭,服务端资源泄漏 服务端注册流到统一管理器,在连接终止事件中清理

2.4 错误状态码的约定与映射

gRPC 的状态码是跨语言的固定集合,其语义与处理建议如下:

状态码 数值 语义 是否可重试 常见成因
OK 0 成功 — —
CANCELLED 1 调用被取消 视原因 上游已超时或客户端主动取消
UNKNOWN 2 未知错误 否 服务端抛出未映射的异常,或状态未返回
INVALID_ARGUMENT 3 参数非法 否 客户端传参错误、校验失败
DEADLINE_EXCEEDED 4 超出截止时间 谨慎 服务端处理超时或网络延迟
NOT_FOUND 5 资源不存在 否 查询目标不存在
ALREADY_EXISTS 6 资源已存在 否 重复创建
PERMISSION_DENIED 7 无权限 否 授权失败
RESOURCE_EXHAUSTED 8 资源耗尽 谨慎 限流触发、消息超过大小上限、配额用尽
FAILED_PRECONDITION 9 前置条件不满足 否 状态不允许该操作
ABORTED 10 操作被中止 可(事务类) 并发冲突、序列号不匹配
OUT_OF_RANGE 11 超出范围 否 分页游标越界、数值越界
UNIMPLEMENTED 12 方法未实现 否 服务端未部署该方法、版本不匹配
INTERNAL 13 内部错误 否 服务端内部异常
UNAVAILABLE 14 服务不可用 可 连接断开、实例下线、负载均衡无可用后端
DATA_LOSS 15 数据丢失 否 数据损坏、解码失败
UNAUTHENTICATED 16 未认证 否 凭据缺失或过期

约定与映射的两条实践:

  1. 业务错误与系统错误要分开。业务错误(INVALID_ARGUMENT、NOT_FOUND、FAILED_PRECONDITION)不应触发熔断与重试,系统错误(UNAVAILABLE、DEADLINE_EXCEEDED、INTERNAL)才纳入。这要求服务端严格选择状态码,而不是把所有异常都返回 UNKNOWN。
  2. 对外暴露时要做映射。gRPC 状态码与 HTTP 状态码不是一一对应关系,网关需要显式映射(如 INVALID_ARGUMENT 映射为 400、UNAUTHENTICATED 映射为 401、PERMISSION_DENIED 映射为 403、NOT_FOUND 映射为 404、RESOURCE_EXHAUSTED 映射为 429、UNIMPLEMENTED 映射为 501、UNAVAILABLE 映射为 503、DEADLINE_EXCEEDED 映射为 504),否则外部调用方会看到无意义的 200 或 500。

2.5 健康检查与反射服务

能力 作用 启用方式
健康检查 供网关、负载均衡、编排平台判断实例是否可用 注册标准的健康检查服务,并实现"服务级就绪"与"进程级存活"的区分
反射服务 允许客户端在无 proto 文件的情况下发现服务与方法 在非生产环境或受控环境启用;生产环境开放会暴露接口结构
通道状态查询 客户端判断连接是否就绪 通过 ManagedChannel.getState(true) 观察 READY、TRANSIENT_FAILURE 等状态

健康检查需要注意"就绪"的定义:进程存活不等于可以接收流量。依赖的数据库、缓存、下游未就绪时,健康检查应返回未就绪,使编排平台不把流量路由到该实例。

3. HTTP 客户端实践

3.1 连接池参数的设置依据

参数 设置依据 参考区间
每路由最大连接数 目标并发除以单连接可承载的并发;同时不超过下游的承载能力 HTTP/1.1 常见 20~200;HTTP/2 常见 2~10
总最大连接数 所有下游的路由数乘以每路由上限,并核对进程 fd 限制 与 ulimit -n 一起核算
获取连接等待超时 应小于客户端总超时,通常在数百毫秒到 1 秒 200 ms ~ 1 s
空闲连接存活时间 小于中间组件与对端的空闲超时 30 s ~ 5 min
空闲连接校验间隔 小于中间组件的空闲超时,用于剔除失效连接 与存活时间配合
连接超时 内网通常在数百毫秒内可完成三次握手 200 ms ~ 3 s

高危 调整连接池上限(每路由最大连接数、总最大连接数)

  • 影响范围:上调会直接提高对下游的瞬时并发,若下游的连接数上限、线程池或数据库连接池小于该值,会把下游推入排队甚至拒绝状态,故障从调用方传导至下游及其所有调用方;下调会使并发请求在客户端排队,表现为延迟上升与获取连接超时,若等待超时设置过长,故障表现为整体变慢而非局部失败。
  • 回滚方式:按最小粒度原则先只调整单个下游的配置,保留原配置值以便回退;回滚时恢复原参数并观察连接池活跃数、等待队列长度与下游错误率是否回落;若已引发下游过载,优先摘除流量并降低并发,再回退参数。
  • 前置要求:先核对下游的连接上限与承载能力,确认横向扩容后的总量与上限的关系;变更在低峰执行并观察连接池指标(活跃连接数、等待次数、获取连接耗时分位);配合压测确认目标并发下的实际需求,而不是按经验值设定。

3.2 超时参数的分层设置

以下以 JDK HttpClient 与 Reactor Netty 为例说明配置的落点:

// JDK HttpClient:连接超时在客户端上设置,读超时在请求上设置
HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofMillis(500))                 // 连接超时
        .version(HttpClient.Version.HTTP_2)                      // 显式指定协议版本
        .executor(businessExecutor)                              // 回调线程与业务线程隔离
        .build();

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("http://inventory-service:8080/internal/inventory/deduct"))
        .timeout(Duration.ofMillis(800))                          // 整体响应超时
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(json))
        .build();
# Reactor Netty 客户端:连接、响应、获取连接与空闲检测分别配置
spring:
  cloud:
    gateway:
      httpclient:
        connect-timeout: 500                # 连接超时(毫秒)
        response-timeout: 3s                # 整体响应超时
        pool:
          max-connections: 500              # 总连接上限
          max-idle-time: 30s                # 空闲连接回收时间
          acquire-timeout: 800ms            # 获取连接的等待上限

分层的判断方法:先确定业务层预算,再倒推各分项。若业务层为一次请求预留 1 秒,客户端总超时应设为 800 毫秒左右,连接超时应设为 300 毫秒以内,剩余预算留给业务逻辑与序列化;重试若开启,则单次超时需要再除以预期重试次数。

3.3 重试策略与幂等判定

// 重试必须同时满足三个条件:可重试的异常、幂等的操作、有次数与退避上限
RetryPolicy<HttpResponse<String>> retryPolicy = RetryPolicy.<HttpResponse<String>>builder()
        .handle(ConnectException.class, SocketTimeoutException.class)     // 连接类失败
        .handleResult(response -> response.statusCode() == 503
                || response.statusCode() == 429)                          // 明确的可用性失败
        .withBackoff(Duration.ofMillis(100), Duration.ofSeconds(1))       // 指数退避
        .withJitter(0.5)                                                  // 抖动,避免同步重试
        .withMaxRetries(2)                                                // 次数上限
        .onRetry(e -> metrics.recordRetry(e.getAttemptCount()))           // 重试必须计入指标
        .build();

幂等判定的落地方式:

判定方式 说明 适用
按 HTTP 方法判定 GET、PUT、DELETE 视为幂等,POST 默认不幂等 通用约定
按接口注解或白名单 显式标注可重试的接口清单 存在非幂等语义的 PUT 或幂等的 POST 时
按幂等键判定 请求携带幂等键,服务端据其去重 非幂等写操作开启重试的唯一安全方式

写超时是最需要谨慎的情形:请求已发出但未收到响应,无法确定服务端是否执行成功。处理方式是给请求带幂等键并在服务端实现去重,或把这类操作改为"先受理再查询结果"的两阶段模式。

高危 修改超时与重试策略(增减重试次数、调整超时阈值、开启或扩大重试范围)

  • 影响范围:重试次数上调会把失败请求的流量成倍放大到下游,在下游已经过载时加速其崩溃;超时阈值下调会把正常的慢请求判为失败并触发重试,同样放大流量;超时阈值上调会让调用方线程被更长时间占用,在故障时线程池与连接池被拖满,故障从"部分接口失败"升级为"整个服务不可用";重试范围扩大(把 4xx 或业务错误纳入重试)会使确定失败的请求反复执行。
  • 回滚方式:参数通常通过配置中心下发,回滚即恢复原配置并触发刷新;确认回滚生效的方式是观察重试次数指标回到基线、下游错误率与延迟回落;若已引发下游过载,需要先降低对该下游的并发或熔断,再逐步恢复参数。
  • 前置要求:变更前记录当前的重试率、超时率与下游延迟分位基线;确认重试只开在链路的一层;确认被重试的接口具备幂等能力或已带幂等键;变更先在预发验证,再按最小作用范围(单接口、单调用方)灰度,观察窗口内同时对上游与下游指标做核对。

3.4 请求与响应体大小限制

位置 限制项 处理
客户端 请求体大小 序列化前校验,超限直接失败而不是发出后等待超时
客户端 响应体大小 设置最大可接收字节数,防止异常响应耗尽内存
客户端 解压后大小 若启用压缩,需限制解压后的体积,不能只限制压缩后的字节数
服务端 请求体大小 与业务上限一致,超限返回明确的错误码
网关 请求与响应体大小 与客户端和服务端的配置对齐,避免中间层成为实际瓶颈

3.5 压缩与批量

场景 压缩 说明
JSON 文本报文(大于数 KB) 开启 压缩率通常较高,网络收益超过 CPU 成本
已压缩的二进制(图片、压缩包) 关闭 压缩率接近 1,只付出 CPU
内网高带宽、低延迟链路 视情况 网络不是瓶颈时压缩收益有限
小报文(数百字节以内) 关闭 压缩与解压的固定开销可能超过节省的字节

批量传输的原则是批量大小由下游的写入能力与超时预算决定,而不是由"减少请求次数"单方面决定。批量过大导致单次请求接近超时,反而会因为重试使总耗时更长。

高危 启用或调整请求与响应压缩(开启 gzip 压缩、调高压缩级别、扩大压缩的生效范围)

  • 影响范围:压缩与解压消耗 CPU,在高 QPS 链路上会显著增加延迟与 CPU 使用率;解压后的报文在内存中展开,若响应体大小没有上限,可能因异常响应或压缩率极高的报文造成内存占用激增;中间组件(网关、代理)可能已开启压缩,两端同时开启会造成重复压缩;压缩后若日志或追踪记录了压缩体,会给排障带来额外成本。
  • 回滚方式:压缩通常由客户端头部或框架配置开关控制,回滚即移除该配置并重新发布或刷新配置;回滚后核对 CPU 使用率、P99 延迟与出口带宽是否回到基线。
  • 前置要求:先核对中间组件是否已开启压缩,避免重复;确认报文类型具备可压缩性;为响应体与解压后体积设定上限;在压测环境对比开启前后的延迟分位与带宽占用,确认收益明确后再上线。

3.6 异步客户端的线程与回调

问题 表现 处理
回调线程被阻塞 回调中执行数据库访问或同步调用,吞吐骤降 把耗时处理提交到独立业务线程池
回调线程中访问 ThreadLocal 追踪标识、安全上下文、MDC 丢失 显式传播上下文(包装任务或在回调入口恢复)
自定义执行器与框架执行器混用 线程数失控、任务排队位置不可预期 只配置一个业务执行器,回调统一切换到该执行器
超时后回调仍执行 上层已放弃,回调仍处理结果 回调中先判断是否已超时或已取消
未等待完成即返回 请求未发送完进程退出 关闭时等待在途请求或使用优雅关闭流程

异步模型的收益只有在整条链路都非阻塞时才成立:若异步回调最终仍要等待同步资源(JDBC、同步 RPC),只是把阻塞从调用线程转移到了回调线程,收益有限且复杂度上升。相关取舍见 Java Web 与 IO 模型与 Netty 第三部分第 5 小节。

4. 序列化与兼容实践

4.1 字段演进与双版本兼容

字段演进的基本规则是"新增安全、删除谨慎、编号不复用"。双版本兼容的落地做法:

阶段 服务端 客户端 兼容验证
新增字段 先写新字段(用于返回),旧字段继续填充用于兼容 旧客户端忽略新字段 用旧版本客户端调用新版本服务端,确认无解析错误
双写 服务端同时维护新旧字段一段时间 新客户端读取新字段 核对新旧字段的数据一致性
切换读 服务端停止填充旧字段,保留字段声明 新客户端只读新字段 确认旧字段无读取流量后执行
删除 用 reserved 占位后再从代码中移除 — 确认无调用方依赖后执行

JSON 一侧的等价做法是增加字段而非改名、保留旧字段并同时写入、用别名兼容历史字段名、配置反序列化器忽略未知字段。两类格式的共同原则是不要原地改变语义。

4.2 枚举与默认值的坑

坑 后果 规避方式
枚举值 0 未定义为"未指定" 无法表达"未设置",并可能把 0 解释为业务有效值 强制第一个枚举值为 *_UNSPECIFIED = 0
代码用 switch 未覆盖默认分支 遇到新枚举值进入未定义行为 所有枚举分支处理必须有默认分支并记录告警
数值默认值 0 被当作有效值 未传字段被解释为"数量为 0" 使用 optional 或包装类型,或业务层显式校验必填
布尔默认值 false 无法区分"未设置"与"显式 false" 同上
JSON 中数值与字符串混用 反序列化失败或数值精度丢失 统一类型约定,金额与 ID 用字符串
枚举名参与 JSON 序列化 改名即破坏兼容 JSON 场景下枚举用稳定的字符串代号,或有明确的别名策略

4.3 大报文与流式传输

场景 整体传输 流式传输
内存峰值 序列化字节数组与对象同时存在,约为报文的数倍 与单条消息大小成正比
超时风险 高(序列化与传输时间集中在一次调用中) 低(分片传输,每片独立超时)
实现复杂度 低 高(需要处理背压、中途失败、断点续传)
对中间组件的要求 只要大小限制足够 不能有全量缓冲的组件
适用 中等大小的批量数据 导出、同步、日志与变更流

4.4 时间与金额等类型的表示约定

类型 推荐表示 理由
时间点 Protobuf 使用 google.protobuf.Timestamp(秒与纳秒,UTC);JSON 使用 ISO-8601 带时区偏移的字符串 避免本地时区与格式化差异;数值时间戳可读性差
日期 使用字符串 yyyy-MM-dd 或专门的日期消息 避免把日期表示为时间点带来的时区漂移
时长 Protobuf 使用 google.protobuf.Duration;JSON 使用带单位的字段(如 timeoutMs) 单位显式,避免秒与毫秒混淆
金额 使用最小货币单位(分)的整数,或"整数部分 + 小数部分"的字符串;不使用浮点数 浮点数无法精确表示十进制小数,累加会产生误差
标识符 字符串 长整型 ID 在 JSON 中可能因精度丢失,数字类型在跨语言时也可能溢出
比率与百分比 明确约定基准(0~1 还是 0~100)并写入字段名或注释 单位歧义是最常见的数据错误来源

时间与时区处理的语言层细节见 时间与字符编码。

5. 观测与排障

5.1 调用指标的采集重点

指标 维度 用途
调用总数与成功率 服务名、方法名、状态码 判断影响面与错误类型分布
延迟分位(P50/P95/P99) 服务名、方法名 判断是普遍变慢还是长尾变慢
重试次数与重试率 服务名、方法名、重试原因 重试率上升往往是下游劣化的最早信号
超时次数 按超时类型(连接、读、总时长) 区分网络问题与服务端处理慢
连接池指标 活跃连接数、空闲连接数、等待获取连接的次数与耗时分位 判断并发是否受连接数限制
队列指标 等待队列长度、拒绝次数 判断排队是否已成为延迟主因
流式调用指标 活跃流数量、单流消息数、流平均存活时长 定位流泄漏与长流问题
上游取消次数 按方法名 反映上游超时预算是否合理

指标的分层、命名规范与埋点方式见 可观测性埋点与指标 第 2 章与第 3.2 节。

5.2 链路追踪的接入

调用链路的追踪需要覆盖三类出口:HTTP 客户端、gRPC 客户端、消息生产者。gRPC 的追踪集成方式与 HTTP 不同:追踪标识通过元数据传递,需要在客户端拦截器中写入、服务端拦截器中提取;跨线程与异步回调场景需要显式传播上下文,否则会出现"链路在异步边界处断裂"。

追踪埋点的边界确认(入口与出口是否全部覆盖、传播格式是否统一、跨线程传播是否有遗漏)与常见断链原因见 可观测性埋点与指标 第 3.4 节;追踪与指标、日志的关联查询路径同见该文第 3.4.4 小节。

5.3 抓包与延迟定位的配合

当指标显示延迟上升而应用侧看不出原因时,需要把延迟拆解到网络与应用两段:

步骤 手段 结论
确认服务是否监听与端口是否可达 ss -lntp、nc -zv 排除服务未启动或绑定地址错误
确认 TCP 建连耗时 抓包观察 SYN 与 SYN-ACK 的时间差 建连慢指向网络 RTT 或监听队列积压
确认请求发出到首字节返回的耗时 抓包观察请求报文与首个响应报文的时间差 该段耗时包含服务端处理时间与网络往返
确认是否存在重传 netstat -s 的重传统计、抓包中的重复段 重传指向链路质量或缓冲区不足
确认连接是否被中间组件断开 抓包观察 RST 或 FIN 的来源 定位到具体的超时配置
区分长尾是否来自队列 对照服务端的处理时间指标 客户端耗时远大于服务端处理时间说明时间消耗在排队或网络

抓包过滤表达式的写法、连通性与端口诊断、DNS 解析排查、连接状态分析见 网络诊断与远程连接 第 2 章、第 4 章与第 5 章;TCP 建连、重传与窗口的协议层背景见 Linux 网络。

gRPC 场景下抓包有两个特殊注意点:一是明文(h2c)才能直接读懂帧结构,TLS 场景需要密钥日志或服务端侧解密;二是HTTP 状态码为 200 不代表调用成功,必须查看响应 trailers 中的 grpc-status。

5.4 连接池与队列指标的判读

现象 含义 方向
活跃连接数持续等于上限,等待次数上升 并发受连接数限制 评估上调连接数或降低并发(需先核对下游承载)
活跃连接数远低于上限但延迟高 瓶颈不在连接池 转查服务端处理时间与网络
空闲连接数长期为零 无复用机会,或空闲回收过快 检查请求分布与空闲存活时间
获取连接耗时分位上升 下游响应变慢导致连接归还延迟 与下游延迟指标对照
连接建立次数持续偏高 连接被频繁重建 检查空闲超时与中间组件的断连行为

6. 常见故障与排查

通信客户端的故障多表现为"延迟上升或调用失败",但根因分布在网络、下游服务、客户端配置与中间组件四处。以下按现象、定位顺序、处置方向组织,重点是从客户端可观测的现象收敛到根因所在的位置。

6.1 连接池耗尽或请求排队

现象:接口耗时上升,日志中出现获取连接超时;下游指标正常且延迟无变化。

定位顺序:
  1. 确认连接池指标:活跃连接数是否达到上限、等待队列长度与等待耗时
  2. 确认下游是否变慢:下游延迟上升会延长连接的占用时间,等效于缩小连接池
  3. 确认是否存在连接泄漏:未关闭的响应体、未消费的响应流会占用连接不归还
  4. 确认是否存在长耗时接口独占连接:大报文、流式响应、慢查询
  5. 确认是否有重试叠加:重试会使同一业务请求占用多个连接

处置方向:
  优先修复连接不归还(泄漏)与下游客量问题;
  仅在下游承载允许且确认并发需求真实存在时,才评估上调连接数上限。

6.2 超时设置不当导致的级联失败

现象:某个下游变慢后,上游服务整体不可用,表现为线程池占满、接口全面超时。

定位顺序:
  1. 确认上游的线程模型:同步调用会占用工作线程,线程池被占满即整体不可用
  2. 确认超时层级:客户端总超时是否大于业务预算;重试是否与长超时叠加
  3. 确认是否存在同步串行调用:一次请求串行调用多个下游,总耗时是各部分之和
  4. 确认熔断是否生效:下游持续失败时熔断是否打开

处置方向:
  收紧超时并有层次地分配预算;为下游设置独立的并发上限(隔离);
  对非核心依赖开启降级;确认熔断阈值与判定口径(业务错误不计入)。

6.3 重试导致下游压力放大

现象:下游流量高于上游入口流量,且失败请求在下游出现的次数多于一次。

定位顺序:
  1. 检索链路上的重试配置,确认是否只有一层开启
  2. 确认重试是否退避与带抖动
  3. 确认重试是否覆盖了确定失败的请求(4xx、业务错误)
  4. 确认是否有网关与服务双重试、或客户端与框架双重试

处置方向:
  重试收敛到一层;启用退避与抖动;排除业务错误;
  引入重试预算(重试请求数不超过总量的一定比例)。

6.4 gRPC 报错码的定位

状态码 优先检查项
UNAVAILABLE 连接是否断开、实例是否下线、负载均衡是否无可用后端、中间组件空闲超时是否过短
DEADLINE_EXCEEDED 服务端处理时间、链路各层超时预算分配、是否存在逐跳重复计时
RESOURCE_EXHAUSTED 是否触发限流、消息是否超过大小上限、服务端是否达到并发上限
UNIMPLEMENTED 服务端版本是否包含该方法、方法名与包名是否一致、是否被网关注册
UNKNOWN 服务端是否抛出了未映射的异常、状态是否在流结束前返回
CANCELLED 上游是否已超时或主动取消、服务端是否感知并在处理中途退出
INTERNAL 服务端内部异常与服务端日志、序列化是否失败

其中 UNAVAILABLE 与 DEADLINE_EXCEEDED 需要区分:前者是"没连上或连接断了",后者是"连上了但没按时完成"。前者看连接与负载均衡,后者看处理时间与超时预算。

6.5 TLS 与证书问题

现象 可能原因 排查方向
握手失败,报证书不受信任 服务端证书签发链不完整、客户端信任库缺少 CA 用 openssl s_client 查看服务端返回的证书链
证书校验失败,报主机名不匹配 证书的 SAN 与客户端使用的地址不一致 核对访问地址与证书中的 SAN 列表
调用随机失败并伴随握手错误 证书即将或已经过期、多个实例的证书版本不一致 检查证书有效期与各实例证书指纹
单向认证正常但双向认证失败 客户端未提供证书或服务端信任库缺少客户端 CA 检查双向认证的信任链配置
使用明文客户端访问 TLS 端口 协议不匹配 抓包可见明文帧被服务端拒绝,修复配置

证书轮换属于需要提前规划的操作:客户端实例的信任库更新需要重启或动态加载,服务端证书更新需要确认所有客户端都已信任新签发链,否则会出现"部分实例调用失败"的中间状态。

6.6 大报文导致的内存与超时

现象:偶发 OOM 或长尾延迟;GC 频率上升;部分请求持续超时。

定位顺序:
  1. 确认报文大小分布:是否存在远大于平均值的请求或响应
  2. 确认大小限制配置:客户端、服务端、网关的上限是否一致,是否有组件未配置
  3. 确认序列化方式:整体序列化会产生数倍于报文的内存峰值
  4. 确认是否启用压缩:解压后的体积是否受限
  5. 确认日志与追踪是否记录了完整报文

处置方向:
  按接口设置大小上限并让超限快速失败;
  大结果集改为流式或分页;
  降噪日志(不记录完整报文);
  必要时为大报文接口单独设置超时预算。

6.7 负载均衡下长连接分布不均

现象:部分实例 CPU 与连接数明显高于其他实例,扩容后新实例流量很少。

定位顺序:
  1. 确认负载均衡层次:是连接级均衡还是请求级均衡
  2. 确认连接存活时间:长连接建立后不再重新分配
  3. 确认客户端是否按实例维护子通道:是否只有一条共享连接
  4. 确认扩容后是否触发连接重建:客户端是否感知实例列表变化

处置方向:
  使用具备流级分发能力或带子通道池的负载均衡方案;
  缩短连接存活时间使流量有机会重新分配(需与建连开销权衡);
  客户端侧负载均衡时确认实例列表刷新与子通道创建逻辑正确。

7. 规范与检查清单

7.1 接口定义规范

项 规范
包名与版本 包名携带版本(如 xxx.v1),不在方法名中混入版本后缀
方法命名 动词明确(Get、List、Create、Update、Delete),与 HTTP 语义无关但与业务语义一致
消息命名 请求以 Request 结尾,响应以 Response 结尾;复数资源使用 ListXxxRequest
字段编号 从 1 开始连续分配,删除的编号用 reserved 占位且永不复用
枚举 第一个值为 *_UNSPECIFIED = 0,删除的枚举值用 reserved 占位
默认值语义 需要区分"未设置"的字段使用 optional,并在 IDL 注释中写明语义
时间与金额 使用协议提供的标准消息类型或字符串约定,不使用浮点数表示金额
注释 每个服务、方法、字段都写明用途与约束,注释是契约文档的一部分
变更评审 IDL 变更必须经过评审,评审项包括编号是否复用、是否破坏兼容、调用方是否已升级

7.2 超时与重试的默认约定

项 约定
默认截止时间 所有对外调用必须有截止时间,禁止无限制等待;默认值按接口分档而非全局一个值
预算分配 业务层预算大于客户端总超时,客户端总超时大于各分项之和;跨服务时逐跳递减
重试层数 整条链路只允许一层重试,通常为入口层
重试条件 仅连接类失败与明确的可用性错误(503、429)可重试,业务错误不重试
重试参数 退避加抖动,次数上限明确,重试次数计入指标
幂等要求 非幂等写操作开启重试必须携带幂等键
变更管理 超时与重试参数变更需要走变更流程并记录基线

7.3 客户端配置的集中管理与分环境差异

项 做法
配置位置 每个下游的超时、重试、连接池参数集中在一处(配置类或配置中心),不散落在业务代码
客户端实例 每个下游一个客户端实例(对应一套连接池与配置),不共用全局实例
环境差异 内网与跨网段、同集群与跨集群的连接超时不同;测试环境可以更宽松,生产必须按预算设定
敏感配置 凭据、证书路径通过配置中心或密钥管理提供,不写入代码与镜像
变更生效 明确哪些参数支持动态刷新、哪些需要重启;连接池上限通常需要重启或重建客户端实例
默认值兜底 未显式配置的下游必须落到一个安全的默认值(较短的超时、不重试),而不是无限等待

7.4 上线前检查清单

分类 检查项
协议与契约 接口定义已评审;字段编号未复用;契约模块已发布且调用方已引入;文档与 IDL 一致
超时 每个下游都有明确的超时配置;各层预算关系成立;未配置的下游落到安全默认值
重试 只有一层开启重试;重试条件排除业务错误;退避与抖动已配置;幂等前提已确认
连接 连接池上限与下游承载能力核对;空闲存活时间小于中间组件空闲超时;连接有效性校验已开启
大小与压缩 客户端、服务端、网关的大小上限一致;压缩的适用性已评估;解压后体积受限
错误码 服务端的错误码选择符合语义;对外暴露的接口已完成状态码映射;业务错误不计入熔断
流式接口 背压已实现;流在异常与结束路径上都会释放;长流的空闲策略已与中间组件对齐
TLS 证书有效期与轮换计划明确;主机名与 SAN 一致;双向认证的信任链已核对
观测 调用指标(成功率、延迟分位、重试次数)已埋点;链路追踪覆盖全部出口;连接池与队列指标可见
治理 熔断与限流阈值已确认;降级策略与业务方确认;并发上限与排队上限已设置
发布与回滚 支持按调用方或按接口灰度;配置可快速回滚;回滚步骤已演练

四、总结

跨服务调用的选择问题,本质上是一个契约与开销的权衡问题:HTTP 用通用性换取宽松的契约与完备的生态,RPC 用强契约与代码生成换取更低的传输开销与编译期保护。两者都不是普适答案,判断的起点是调用方是否可控、是否需要流式、性能是否真的构成瓶颈,以及现有基础设施能否承载。

原理层面的关键结论:

  • HTTP/2 的价值在于把连接数与并发数解耦。多路复用让一条连接承载大量并发流,头部压缩降低了小报文的固定开销,但多路复用并没有消除 TCP 层的队头阻塞,流控也只是把背压从"靠 TCP 缓冲"变成"显式通告窗口"。
  • gRPC 是 HTTP/2 之上的一层约定,而不是另一套传输。方法体现为 :path,消息体现为带 5 字节前缀的 DATA 帧,状态体现为 trailers 中的 grpc-status。由此推出一条排障铁律:HTTP 状态码为 200 不代表 gRPC 调用成功。
  • IDL 把契约提前到编译期,代价是引入代码生成环节与工具链依赖。字段编号是契约的实体,新增安全、删除需 reserved 占位、编号永不复用,这是 Protobuf 兼容性的全部基础。
  • Protobuf 的体积优势来自"用编号替代字段名"与变长编码,而不是某种黑箱优化;当报文很小或网络往返占主导时,编码格式的收益有限,此时使用 gRPC 的主要收益来自连接复用与流控。
  • 四种调用方式的差别在于数据流向与结束时机,但背压的实现方式相同:判断可写性、暂停数据来源。无论是 gRPC 的 isReady() 还是 Netty 的 isWritable(),背压的本质都是把压力传回源头。
  • 截止时间是绝对预算而不是读超时,它在链路各跳之间逐跳递减;服务端必须感知取消,否则会出现"调用方已放弃、服务端仍在满负荷计算"的浪费。
  • HTTP 客户端的超时是一组参数而非一个。连接、获取连接、读、总时长各自覆盖不同阶段,只有把它们与业务层预算的关系理清,才能避免"上层已放弃、下层仍在重试"的无效等待。

工程层面的结论:

  • 重试是故障放大器。它缓解的是偶发失败,放大的是持续故障。约束只有三条:只在一层重试、必须退避加抖动、非幂等操作必须带幂等键;在此基础上再叠加"只重试系统错误"与"重试预算"两道闸门。
  • 连接池与并发上限都需要以下游承载能力为输入,而不是以"让本进程不排队"为目标。排队只是把快速失败换成慢速失败,排队上限与等待超时必须同时设置。
  • 协议与序列化的切换是双向锁定的操作,需要链路两端、中间组件与观测体系同时就绪。双协议共存是回滚的前提,契约中的字段编号与枚举值在切换期间不得删除。
  • 服务端侧的两个关注点是取消感知与大小限制:前者避免无效计算,后者避免单条报文耗尽内存;流式接口还多一条约束——同一流上的写入必须串行。
  • gRPC 的落地难点多数不在代码,而在中间组件。HTTP/2 支持、trailers 透传、流式转发、空闲超时、流级负载均衡、健康检查,任何一项缺失都会以"调用超时""状态丢失""分布不均"的形式暴露出来。
  • 观测的重点是重试率与连接池指标。成功率与延迟分位回答"是否异常",重试次数与连接池等待回答"异常为何被放大",两者结合才能在故障初期定位到是网络、下游还是配置。

选择的前提是理解代价。HTTP 的代价是每次调用都要重复支付协议开销与运行时校验,gRPC 的代价是从第一天起就要维护契约、构建与工具链。把这两笔账算清楚,选型就不再依赖框架热度,通信客户端的参数配置也不再是经验值的堆叠。