API 网关请求链路分治:会话、协议分派与插件边界
GateWeave 是一个基于 Java 17、Netty、Spring Boot 和 Dubbo 实现的 API 网关项目。HTTP 请求进入 Netty 后会被转换为应用命令,再根据路由配置调用对应的 Dubbo 服务。链路跑通以后,一个新的问题变得明显:路由匹配、请求转换、引用解析和 RPC 调用都集中在同一个应用服务中。
这段代码并不长,但它同时受到几种变化影响。路由规则变化时要修改它,调用参数变化时要修改它,接入新协议时仍然要修改它。代码行数不是主要问题,不同变化方向汇聚在同一处才是问题。
应用服务知道了太多事情
最初的 DefaultGatewayRequestService 直接持有路由表和泛化引用解析函数。收到请求后,它先查找路由,再取得 IGenericReference,把 HTTP 请求体转换成字符串,最后执行 RPC 调用:
1 | public CompletionStage<GatewayResponse> handle(GatewayRequestCommand command) { |
从请求进入网关到结果返回,各层之间的关系如下。
flowchart LR
subgraph ClientLane[HTTP 客户端]
direction TB
Send[发送 /sayHi]
Receive[接收 HTTP 响应]
end
subgraph HttpLane[Netty 入站适配器]
direction TB
MapCommand[转换 GatewayRequestCommand]
EncodeResponse[编码 GatewayResponse]
end
subgraph ApplicationLane[DefaultGatewayRequestService]
direction TB
MatchRoute[匹配 HTTP 路由]
ResolveReference[解析 IGenericReference]
ConvertPayload[请求体转换为 String]
InvokeReference[执行泛化调用]
BuildResponse[构造 200 响应]
BuildNotFound[构造 404 响应]
end
subgraph DomainLane[领域路由]
direction TB
RouteTable[GatewayRouteTable]
RouteTarget[GatewayRoute<br/>InvocationTarget]
end
subgraph DubboLane[Dubbo 插件]
direction TB
Options[DubboReferenceOptions]
Registry[GenericReferenceRegistry]
Reference[IGenericReference]
GenericService[Dubbo GenericService]
end
Send --> MapCommand
MapCommand --> MatchRoute
MatchRoute --> RouteTable
RouteTable -->|命中| RouteTarget
RouteTable -->|未命中| BuildNotFound
RouteTarget --> ResolveReference
ResolveReference --> Options
Options --> Registry
Registry -->|返回引用| Reference
Reference --> ConvertPayload
ConvertPayload --> InvokeReference
InvokeReference -->|$invoke| Reference
Reference --> GenericService
GenericService -->|CompletionStage| BuildResponse
BuildResponse --> EncodeResponse
BuildNotFound --> EncodeResponse
EncodeResponse --> Receive
style ClientLane fill:#fff7e6,stroke:#d48806
style HttpLane fill:#e6f4ff,stroke:#1677ff
style ApplicationLane fill:#f6ffed,stroke:#52c41a
style DomainLane fill:#fff0f6,stroke:#c41d7f
style DubboLane fill:#f9f0ff,stroke:#722ed1
IGenericReference 没有暴露 Dubbo SDK 类型,但它仍然是一种面向 RPC 泛化调用的抽象。应用服务直接依赖它,意味着应用层已经默认“路由命中后一定执行 RPC”。如果再增加 HTTP 或 gRPC 出口,就需要继续扩大解析函数,或者在应用服务中根据协议增加分支。
请求流程需要按照变化原因拆开,而不是继续向应用服务添加条件判断。
GatewaySession 是一次请求的路由快照
路由匹配的结果不只是一个 GatewayRoute。后面的模型转换还需要原始请求,两者在本次调用期间必须保持一致。GatewaySession 用一个不可变记录保存这组关系:
1 | public record GatewaySession(GatewayRequestCommand command, GatewayRoute route) { |
这里的 Session 不是登录状态,也不是 Netty Channel 的包装。它没有跨请求共享的可变属性,只表示“这个请求已经命中这条路由”。请求命令和路由快照绑定以后,后续组件不需要重复查询路由,也不会在调用中途拿到另一份配置。
建立会话的职责交给 GatewaySessionFactory:
1 | public interface GatewaySessionFactory { |
路由未命中属于正常业务结果,因此返回 Optional.empty(),而不是用异常表达。应用服务只需要决定空结果对应 404,路由表的查询方式仍然封装在工厂实现中。
调用插件不应该读取领域路由
GatewayRoute 和 InvocationTarget 属于数据面的领域模型,插件不应该依赖它们。否则插件会随着领域模型一起变化,插件模块也会反向依赖网关引擎。
跨过应用层与插件层边界前,InvocationRequestMapper 会把会话转换成稳定的调用契约:
1 | public record InvocationRequest( |
这个对象放在 gateweave-contract 模块,只包含 JDK 类型。Netty 的 FullHttpRequest、领域层的 GatewayRoute 和 Dubbo 的 GenericService 都不会越过边界。
映射时还有一个容易混淆的细节:GatewayRoute 和 InvocationTarget 都有扩展属性。路由属性描述网关自身的行为,例如优先级;调用目标属性描述具体协议,Dubbo 的 version 就属于后者。因此 InvocationRequest.attributes 必须来自 target.attributes(),不能把两组属性混在一起。
请求体也在契约创建时复制。这样插件拿到的是稳定快照,不会受到 Netty 引用计数对象释放或调用方修改字节数组的影响。
协议分派器把选择规则集中起来
每种出口协议实现同一个扩展契约:
1 | public interface ProtocolInvoker { |
protocol() 返回稳定协议标识,例如 dubbo。invoke() 接收统一调用请求,并保持异步返回。接口依赖 CompletionStage,而不是要求实现必须创建 CompletableFuture,调用方只依赖继续编排异步结果所需的能力。
ProtocolInvocationDispatcher 在启动时把所有实现组织成不可变索引。协议名统一转换为小写,重复协议直接阻止启动;请求到来后,根据 InvocationRequest.protocol() 完成一次查找:
1 | public CompletionStage<String> invoke(InvocationRequest request) { |
这个类并不是给 Map#get 换一个名字。它还定义了插件注册和失败语义:重复协议在启动时暴露,未知协议表现为失败的异步阶段,插件同步抛出的提交异常也进入同一条异步错误链。Netty 入口因此不需要分别理解每种插件的错误方式。
分派器也不遍历调用器执行 supports()。协议是配置中的唯一选择键,在初始化阶段建立索引更直接,也能提前发现两个插件争用同一协议的问题。
DubboProtocolInvoker 收拢协议细节
Dubbo 的调用适配放在 gateweave-plugin 模块。DubboProtocolInvoker 不重新实现引用缓存,而是组合第二章已经存在的几个组件:
1 | public CompletionStage<String> invoke(InvocationRequest request) { |
DubboReferenceOptions 负责从扩展属性解析并校验版本,GenericReferenceRegistry 负责查找和复用服务引用,IGenericReference 负责执行已经绑定的方法。适配器只完成这几段已有能力的组合,没有再增加一份缓存,也没有在 InvocationRequest 上增加 Dubbo 专属便利方法。
当前示例调用的方法只接收一个字符串参数,所以适配器将 UTF-8 请求体转换为 String。InvocationRequest 已经保留参数类型和原始负载;以后支持多个参数时,应统一演进调用契约和泛化代理,而不是在适配器里根据接口名称写特殊分支。
分治后的请求链路
完成拆分后,请求仍然从同一个 Netty Handler 进入,也仍然返回 GatewayResponse。变化发生在应用服务内部:它不再理解具体协议,只负责安排几个组件的执行顺序。
flowchart LR
subgraph ClientLane[HTTP 客户端]
direction TB
Send[发送 /sayHi]
Receive[接收 HTTP 响应]
end
subgraph HttpLane[Netty 入站适配器]
direction TB
MapCommand[转换 GatewayRequestCommand]
EncodeResponse[编码 GatewayResponse]
end
subgraph ApplicationLane[应用服务]
direction TB
Handle[DefaultGatewayRequestService<br/>编排请求]
BuildResponse[构造 200 响应]
BuildNotFound[构造 404 响应]
end
subgraph SessionLane[会话与模型转换]
direction TB
OpenSession[GatewaySessionFactory]
RouteTable[GatewayRouteTable]
Session[GatewaySession]
MapInvocation[InvocationRequestMapper]
InvocationRequest[InvocationRequest]
end
subgraph DispatchLane[协议分派]
direction TB
Dispatcher[ProtocolInvocationDispatcher]
SelectProtocol[根据 protocol 选择插件]
end
subgraph DubboLane[Dubbo 插件]
direction TB
DubboInvoker[DubboProtocolInvoker]
Options[DubboReferenceOptions]
Registry[GenericReferenceRegistry]
Reference[IGenericReference]
GenericService[Dubbo GenericService]
end
Send --> MapCommand
MapCommand --> Handle
Handle --> OpenSession
OpenSession --> RouteTable
RouteTable -->|命中| Session
RouteTable -->|未命中| BuildNotFound
Session --> MapInvocation
MapInvocation --> InvocationRequest
InvocationRequest --> Dispatcher
Dispatcher --> SelectProtocol
SelectProtocol -->|dubbo| DubboInvoker
DubboInvoker --> Options
Options --> Registry
Registry --> Reference
Reference --> GenericService
GenericService -->|CompletionStage| BuildResponse
BuildResponse --> EncodeResponse
BuildNotFound --> EncodeResponse
EncodeResponse --> Receive
style ClientLane fill:#fff7e6,stroke:#d48806
style HttpLane fill:#e6f4ff,stroke:#1677ff
style ApplicationLane fill:#f6ffed,stroke:#52c41a
style SessionLane fill:#fff0f6,stroke:#c41d7f
style DispatchLane fill:#f0f5ff,stroke:#2f54eb
style DubboLane fill:#f9f0ff,stroke:#722ed1
两条链路处理的是同一个请求,职责归属已经发生变化:
| 变化点 | 分治前 | 分治后 |
|---|---|---|
| 路由匹配 | 应用服务直接查询路由表 | GatewaySessionFactory |
| 请求与路由绑定 | 方法参数临时组合 | GatewaySession |
| 插件调用模型 | 应用服务自行提取 | InvocationRequestMapper |
| 协议选择 | 固定的泛化引用解析 | ProtocolInvocationDispatcher |
| Dubbo 属性解析 | 引用解析函数 | DubboProtocolInvoker |
| 新增出口协议 | 修改已有编排 | 新增 ProtocolInvoker 实现 |
| 应用层依赖 | 认识 IGenericReference |
只认识统一调用契约和分派器 |
GatewayEngineConfiguration 没有出现在泳道图里,因为它只在启动阶段创建和连接这些对象,不参与每次请求。运行时流程只依赖已经装配完成的组件。
依赖方向需要能够被持续检查
目录划分本身不能阻止边界退化。后续开发者仍然可能为了方便,在应用服务里直接引用 DubboProtocolInvoker,或者让插件读取 GatewayRoute。因此项目通过架构测试固定三条依赖规则:应用层不依赖插件实现,插件不反向依赖网关引擎,领域模型不依赖 Spring、Netty 和 Dubbo。
这些规则保护的是变化方向。Dubbo SDK 升级只影响插件,路由算法变化停留在领域和会话工厂,HTTP 编解码变化留在 Netty 适配器。应用服务只要继续接收同样的命令和调用契约,就不需要跟随外部技术一起修改。
如果接下来增加 HTTP 出口,只需要实现一个新的 ProtocolInvoker,将 InvocationRequest 转换为 HTTP 客户端请求,再把它注册到分派器。DefaultGatewayRequestService、GatewaySessionFactory 和现有 Dubbo 插件都不需要增加协议分支。请求链路的扩展点由此落在明确边界上,而不是重新回到一个不断增长的中心类中。







