5.1 拦截器与中间件模式

5.1 拦截器与中间件模式

本节摘要：拦截器是 gRPC 的横切机制——客户端拦截器在调用发出前后介入，服务端拦截器在方法分发前后把关。本节讲拦截器的执行顺序模型、四个典型实现（日志、鉴权、追踪注入、限流）的代码级结构，以及最容易被忽视的部分：拦截器的纪律边界——什么逻辑该进拦截器、什么逻辑进了反而害人。

阅读收获

阅读完本节，你应当能够：

1. 说明客户端与服务端拦截器的挂载位置与执行顺序；
2. 实现日志、鉴权、追踪注入三类基础拦截器；
3. 解释一元拦截器与流拦截器的区分及各自的适配方法；
4. 判断一段逻辑是否适合放进拦截器；
5. 组织多拦截器的注册顺序并预见实际执行次序。

一、没有拦截器的世界什么样

先看反例。一个没有横切机制的服务端，每个业务方法的开头都是同样的八股：取元数据里的令牌、调鉴权服务校验、写一条访问日志、把追踪标识塞进上下文、检查限流计数——五行样板 × 一百个方法 = 五百行复制粘贴。某天要给日志加个字段，改一百处；漏改三处，监控数据就缺一角。

拦截器把这五行样板收编为一次实现、全局生效。第 1 章讲过 gRPC 的架构哲学"复杂性留给框架、简洁性留给用户"，拦截器就是这句话在治理层的具体化。

结构上，4.1 与 4.2 节定位过它的挂载点：客户端拦截器位于 Stub 之下、Channel 之上，服务端拦截器位于方法分发之前。这个位置让它能看到每一次调用的完整上下文——方法名、元数据、状态、耗时——又不必侵入任何业务方法。

二、执行顺序：洋葱模型

多个拦截器注册后按洋葱模型执行：客户端按注册顺序由外到内（先注册的先执行请求侧、后执行响应侧），服务端同理。用一张时序图固化这个认知：

顺序设计的两条经验：日志放最外层（它要观察整条链路的最终结果与总耗时）；鉴权放服务端最内层紧贴业务（前面拦截器产生的上下文信息如追踪标识，鉴权时可能要用）。顺序错了不会报错，但语义会变形——比如追踪头还没注入、日志拦截器已经记录了一个没有追踪标识的条目。

三、四个典型实现的结构

日志拦截器是入门标准件。客户端侧：调用前记方法名与起始时间，调用返回后记录状态码、耗时、目标实例。服务端对称。两个实现要点：一，失败路径也要记（拦截器捕获异常后记录再重新抛出，别把异常吞了）；二，输出结构化字段而非自由文本——第 6 章的指标体系靠这些字段聚合。

鉴权拦截器是服务端安全的第一道闸。从调用元数据里取令牌（3.2 节讲过自定义认证头的传递），校验通过则把解析出的身份信息放进调用上下文向下传递，失败则直接以 UNAUTHENTICATED 状态短路——方法分发都不会发生。业务方法从上下文取身份，不自己碰令牌。5.4 节展开令牌本身的设计。

追踪注入拦截器成对出现：客户端把当前链路的追踪标识（trace id、span id）写进调用元数据；服务端读取并延续链路。配合 OpenTelemetry 这类标准库，几行代码就能把 gRPC 调用织进分布式追踪网络——第 6 章观测三支柱的重头内容在此埋点。

限流拦截器服务端形态居多：按调用方、按方法维度查限流计数器（令牌桶或滑动窗口），超限直接以 RESOURCE_EXHAUSTED 状态拒绝。它的价值在于保护执行流池（4.2 节的容量账本）：过载流量在进入业务前就被挡住，存量调用的服务质量得以维持。

四、一元与流：拦截器的两套接口

拦截器接口按调用形态分为两套：一元拦截器处理一元调用，签名简单（请求、上下文、继续执行句柄）；流拦截器处理三种流式调用，包装流的读写接口。

流拦截器的能力更强也更微妙：它能包装收发两侧的流对象，观察到每条消息的经过。代价是复杂度——一元拦截器的样板代码几行，流拦截器要正确实现流接口的全部代理方法，漏一个就是隐蔽 bug。实践纪律：能用一元拦截器覆盖的逻辑，不要为它专门写流拦截器；确实要管流消息（如按消息限流），务必用各语言提供的基础适配工具，别裸写代理类。

顺带一个实现层面的常见疑问：**服务端拦截器怎么同时注册两种形态？**多数语言允许一元拦截器与流拦截器分别注册、各自生效于对应形态的调用——写一个通用逻辑（如鉴权）想同时覆盖两种调用时，标准做法是"共享实现函数，两个薄壳拦截器分别调用它"，而不是在一个拦截器里判断调用形态再走分支。判断式的写法在语言接口层面往往行不通，而且把形态差异藏进运行时分支，测试矩阵反而更难铺。

五、纪律边界：什么不该进拦截器

拦截器是利器也是陷阱，以下几类逻辑放进去弊大于利：

业务逻辑。拦截器里写"订单金额超过 X 走特殊分支"——方法名与参数的耦合让它变成隐形的地雷：新方法加了没进拦截器条件、老方法改了参数含义，拦截器都在静默地按旧逻辑行事。拦截器只做与具体方法无关的横切逻辑。

重业务化状态。拦截器里维护复杂业务缓存、跨调用的业务会话——拦截器是无状态设计意图的组件，塞进状态后测试与并发问题成倍增长。

静默改写语义。拦截器吞掉错误"假装成功"、篡改响应内容——排障时会怀疑人生：方法明明返回 A，客户端收到 B。拦截器要改写行为时，必须在元数据或日志里留下显式痕迹。

过度叠加。十层拦截器套娃，每层几毫秒，叠加起来调用路径多了几十毫秒固定开销；更糟的是排障时要脑内模拟十层洋葱。拦截器数量保持个位数，每层职责单一可命名。

再补一个实践中的灰度地带："按方法名做条件分支"的拦截器。比如"仅对查询类方法跳过鉴权缓存"——它介于横切与业务之间，方法名列表硬编码在拦截器里后，新方法上线时没人记得更新这个列表，行为就悄悄不一致了。如果确实需要按方法分类的行为，把分类元数据放进 proto 注释或服务配置（机器可读的方法分组），拦截器读配置而不是硬编码名字——配置的可见性比代码里的 if 高得多，漏配的概率随之下降。

⚠️ 常见坑：拦截器里抛出实现语言的运行时异常（而不是返回 gRPC 状态），不同语言的框架处理不一致——轻则对端收到 UNKNOWN，重则服务端执行流泄漏。纪律：拦截器内的所有错误路径都要收敛为规范的状态返回。

💡 关键直觉：判断一段逻辑是否该进拦截器的试金石——换一个服务、换一批方法，这段逻辑还成立吗。成立的是横切逻辑（鉴权、日志、追踪）；不成立的是业务逻辑，回到业务层去。

常见问题

问：拦截器能修改请求或响应内容吗？
技术上部分场景可以（一元拦截器能替换消息对象），但这是一条危险的路——内容的静默变更破坏"所见即所得"的调试直觉。确需变换（如协议适配）时，放到网关层做并显式记录。

问：拦截器里怎么拿到"我是谁在调用"？
标准姿势是服务端拦截器从调用元数据取认证令牌（第 5.4 节的传递机制），解析出身份后放进本次调用的上下文对象——各语言实现都提供了调用上下文的读写接口，业务方法再从上下文取用。要避免的反模式是把身份存进线程局部变量：线程会被下一个请求复用，串号的灵异故障就这么来的。

问：客户端拦截器能做重试吗？
能，但要避开已在 Channel 层配置的重试造成叠加放大。语言实现的内置重试（服务配置里声明）与拦截器手工重试二选一，5.3 节展开完整的重试设计。

问：拦截器里的异步操作怎么处理？
各语言都有对应的异步拦截器形态（返回 future 或挂起函数）。关键是"继续执行句柄"必须且只能被调用一次——调用零次是吞调用，调用两次是重复执行，都是事故级 bug。

要点串联

• 拦截器是横切逻辑的唯一挂载点：客户端在 Stub 与 Channel 之间，服务端在分发之前，覆盖全部调用。
• 执行顺序是洋葱模型：客户端与服务端各自由外到内，日志放最外、鉴权放最内是稳妥默认。
• 四个标准件：日志（失败也记、结构化字段）、鉴权（失败短路、身份进上下文）、追踪注入（成对埋点）、限流（保护执行流池）。
• 流拦截器是重武器：只在需要逐消息观察时使用，实现要基于框架适配工具。
• 三类逻辑别进拦截器：业务逻辑、有状态缓存、静默改写——试金石是"换个服务还成立吗"。
• 错误路径收敛为状态码：抛运行时异常的行为在不同语言实现下不可预测。

拦截器这个挂载点就位后，下一节填第一个重头内容：地址从哪来（服务发现）、流量往哪放（负载均衡），以及 gRPC 特色的客户端均衡路线与代理路线之争。