API 网关 RPC 代理:从 HTTP 路由到 Dubbo 泛化调用
GateWeave 是一个基于 Java 17、Netty、Spring Boot 和 Dubbo 实现的 API 网关项目。它的 HTTP 接入层会把 Netty 请求转换为 GatewayRequestCommand,再交给应用服务。要让 /sayHi 真正访问 RPC 服务,还需要确定它对应哪个接口、哪个方法和哪个版本。
如果在 Handler 中直接写 GenericService 调用,每增加一个接口都要修改网关代码。调用信息需要配置化,网关再通过泛化调用按运行时元数据访问服务。不过,接口元数据从哪里来、如何与 HTTP 路由绑定、服务引用如何复用,仍然需要单独设计。
一个请求如何抵达 Dubbo Provider
flowchart LR
subgraph ClientLane[HTTP 客户端]
direction TB
Send[GET /sayHi]
Receive[接收 HTTP 结果]
end
subgraph HttpLane[HTTP 入站适配器]
direction TB
RequestCommand[构造 GatewayRequestCommand]
HttpResponse[编码 GatewayResponse]
end
subgraph ApplicationLane[应用编排]
direction TB
Match[DefaultGatewayRequestService<br/>匹配路由]
Resolve[解析泛化引用]
Invoke[发起异步调用]
BuildResponse[构造 GatewayResponse]
end
subgraph DomainLane[领域路由]
direction TB
RouteTable[GatewayRouteTable]
Target[GatewayRoute + InvocationTarget]
end
subgraph PluginLane[Dubbo 插件]
direction TB
Registry[GenericReferenceRegistry]
Proxy[IGenericReference 代理]
GenericService[Dubbo GenericService]
RpcResult[转换异步结果]
end
subgraph ProviderLane[RPC Provider]
direction TB
Provider[执行目标方法]
end
Send --> RequestCommand
RequestCommand --> Match
Match --> RouteTable
RouteTable -->|返回调用目标| Target
Target --> Resolve
Resolve --> Registry
Registry -->|返回统一调用端口| Proxy
Proxy --> Invoke
Invoke --> GenericService
GenericService -->|Dubbo RPC| Provider
Provider -->|调用结果| RpcResult
RpcResult --> BuildResponse
BuildResponse --> HttpResponse
HttpResponse --> 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 PluginLane fill:#f9f0ff,stroke:#722ed1
style ProviderLane fill:#fff1f0,stroke:#cf1322
这条链路跨越了三个边界:Netty 负责 HTTP 协议,应用服务负责用例编排,RPC 插件负责 Dubbo 调用。GenericService、ReferenceConfig 等 Dubbo 类型不会进入应用层。
路由不是一个方法名
如果只用 sayHi 标识服务,不同接口或不同版本出现同名方法时,网关就无法判断应该调用哪一个。一个可执行的目标需要描述协议、服务接口、操作、参数类型、超时和协议扩展信息:
1 | gateweave: |
其中 path + method 描述 HTTP 入口,service + operation + parameterTypes + version 描述 RPC 出口。两部分组合起来,才形成一次完整的绑定。
配置不会直接进入领域逻辑。YAML 先绑定为 RouteConfiguration 和 InvocationTargetConfiguration,再由GatewayRouteConfigurationMapper 转换为 GatewayRoute 和 InvocationTarget。前者表达外部配置格式,后者表达网关内部的路由语义,配置结构发生变化时不会直接冲击领域模型。
应用服务只负责把几段能力串起来
DefaultGatewayRequestService 收到命令后,先根据 HTTP 方法和 URI 查询路由表:
1 | return routeTable.match(command.method(), command.uri()) |
没有匹配路由时直接得到 404。匹配成功后,应用服务从路由中取得 InvocationTarget,解析统一的泛化引用,再把当前实现接收的字符串参数交给它。异步 RPC 结果最终被转换为 GatewayResponse。
应用层看到的调用端口很小:
1 | public interface IGenericReference { |
这个接口没有出现任何 Dubbo 类型。以后增加 HTTP、MQ 或其他调用插件时,应用服务仍然可以围绕自己的调用目标和返回类型进行编排,而不是同时承担多个厂商 SDK 的差异。
泛化调用为什么还需要一层代理
Dubbo 的 GenericService 已经可以根据方法名、参数类型和参数值发起调用:
1 | genericService.$invokeAsync(methodName, parameterTypes, arguments); |
但让应用层直接使用它,Dubbo 依赖仍然会穿过插件边界。RPC 插件使用 JDK 动态代理实现 IGenericReference,InvocationHandler 再把统一调用转换成 $invokeAsync。
这里不需要代理某个具体类,也不需要动态生成业务接口,JDK Proxy 已经满足要求。额外使用 CGLIB 不会增加新的能力,反而会多出依赖和字节码生成成本。
代理还承担返回值契约检查。当前网关约定 RPC 结果为字符串,如果 Provider 返回其他对象,异步结果会以明确异常结束,不会让错误类型一路流到 HTTP 编码阶段。
服务引用不能按方法名缓存
创建 Dubbo ReferenceConfig 会建立服务引用和相关连接,不应该在每次 HTTP 请求到来时重复创建。注册器通过SimpleReferenceCache 复用 GenericService,再缓存对应的代理工厂。
缓存键使用:
1 | interfaceName + methodName + version |
example.UserService#sayHi:1.0.0 和 example.OrderService#sayHi:1.0.0 因此属于不同目标,而同一个目标重复注册时会复用已经创建的服务引用。这类键看起来只是实现细节,实际上决定了网关能否正确承载大量拥有同名方法的服务。
ReferenceConfig 的组装也集中在注册器内部。应用名称、注册中心、服务接口、版本、泛化模式和发现策略都在插件边界完成,领域模型只保留项目自己的 InvocationTarget。
Dubbo 3 的地址发现需要明确选择
Dubbo 3 引入了应用级服务发现,同时保留接口级地址发现用于兼容。消费端到底订阅哪类地址,不能只看注册中心是否连通。配置将发现策略收敛为三个模式:
| 网关配置 | Dubbo 迁移模式 | 注册模式 | 行为 |
|---|---|---|---|
INTERFACE |
FORCE_INTERFACE |
interface |
只使用接口级地址 |
APPLICATION_FIRST |
APPLICATION_FIRST |
默认模式 | 优先应用级,同时兼容接口级 |
APPLICATION |
FORCE_APPLICATION |
instance |
只使用应用级地址 |
设置单个服务引用时,代码复用 Dubbo 的 MIGRATION_STEP_KEY,而不是在项目里重新声明 migration.step。消费端还关闭了Dubbo QoS,避免网关进程额外监听 22222 管理端口。
示例环境采用接口级发现:
1 | gateweave: |
这不是所有项目都应该照搬的默认答案。Provider 如何注册、是否处于 Dubbo 2 到 Dubbo 3 的迁移阶段,才是选择发现模式的依据。
注册中心连通以后,Provider 仍然可能不存在
只启动 ZooKeeper 和网关、不启动目标 Provider 时,网关仍然能够完成注册中心连接和服务订阅。订阅结果中可用 Invoker数量为 0,但这不妨碍 HTTP 服务器启动。
真正请求 /sayHi 时,Dubbo 才会抛出 No provider available。异常沿着异步调用链回到 Netty Handler:服务端日志保留请求 ID 和完整堆栈,HTTP 客户端只看到:
1 | 500 Internal Server Error |
因此,“网关启动成功”“注册中心连接成功”和“RPC 服务可以调用”是三个不同的状态。前两个状态不能替代 Provider 的端到端验证;没有 Provider 时,也不应该虚构一次成功调用,而应该让失败安全、清晰地返回。
后续引入统一错误契约时,可以继续区分无 Provider、调用超时、熔断和内部编程错误。当前入口先保证内部异常不会直接暴露给客户端。
关闭服务引用时遇到的竞态
网关停止时,Spring 会调用 Bean 的销毁方法,Dubbo 自己也注册了 ShutdownHook。两个关闭路径可能先后销毁同一批服务引用,最初因此出现过 invoker has already destroyed 告警。
注册器没有简单捕获并吞掉所有异常,而是先用 AtomicBoolean 保证主动关闭幂等,再检查 Dubbo ScopeModel 是否已经销毁。如果框架已经完成关闭,就不再重复释放引用;如果模型仍然存活而销毁失败,则恢复关闭状态并继续抛出异常,调用方仍有机会重试。
修正后的关闭过程会注销订阅、关闭 ZooKeeper 会话并释放线程资源。网关作为消费者不会监听 20880,QoS 已关闭也不会监听 22222;停止后 HTTP 端口 7397 同样被释放。
静态绑定只是控制面的起点
到这里,HTTP 请求已经能够经过路由表抵达 Dubbo 泛化调用,Netty 入口仍然没有感知任何 RPC 细节。当前路由暂时来自本地 YAML,它适合验证完整链路,却还不能支持运行时发布和多节点同步。
当控制面开始管理服务、接口和路由时,只需要把新的配置来源转换为同样的 GatewayRoute 与 InvocationTarget,数据面的匹配和调用过程不必推翻重写。







