GateWeave 是一个基于 Java 17、Netty、Spring Boot 和 Dubbo 实现的 API 网关项目。它的 HTTP 接入层会把 Netty 请求转换为 GatewayRequestCommand,再交给应用服务。要让 /sayHi 真正访问 RPC 服务,还需要确定它对应哪个接口、哪个方法和哪个版本。

如果在 Handler 中直接写 GenericService 调用,每增加一个接口都要修改网关代码。调用信息需要配置化,网关再通过泛化调用按运行时元数据访问服务。不过,接口元数据从哪里来、如何与 HTTP 路由绑定、服务引用如何复用,仍然需要单独设计。

一个请求如何抵达 Dubbo Provider

这条链路跨越了三个边界:Netty 负责 HTTP 协议,应用服务负责用例编排,RPC 插件负责 Dubbo 调用。GenericService、ReferenceConfig 等 Dubbo 类型不会进入应用层。

路由不是一个方法名

如果只用 sayHi 标识服务,不同接口或不同版本出现同名方法时,网关就无法判断应该调用哪一个。一个可执行的目标需要描述协议、服务接口、操作、参数类型、超时和协议扩展信息:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
gateweave:
routing:
routes:
- route-id: route-say-hi
path: /sayHi
method: GET
service-id: activity-service
target:
protocol: dubbo
service: example.rpc.GreetingService
operation: sayHi
parameter-types: [java.lang.String]
timeout: 3s
attributes:
version: 1.0.0

其中 path + method 描述 HTTP 入口,service + operation + parameterTypes + version 描述 RPC 出口。两部分组合起来,才形成一次完整的绑定。

配置不会直接进入领域逻辑。YAML 先绑定为 RouteConfiguration 和 InvocationTargetConfiguration,再由GatewayRouteConfigurationMapper 转换为 GatewayRoute 和 InvocationTarget。前者表达外部配置格式,后者表达网关内部的路由语义,配置结构发生变化时不会直接冲击领域模型。

应用服务只负责把几段能力串起来

DefaultGatewayRequestService 收到命令后,先根据 HTTP 方法和 URI 查询路由表:

1
2
3
return routeTable.match(command.method(), command.uri())
.map(route -> invoke(command, route))
.orElseGet(() -> completedFuture(GatewayResponse.text(404, "Route Not Found")));

没有匹配路由时直接得到 404。匹配成功后,应用服务从路由中取得 InvocationTarget,解析统一的泛化引用,再把当前实现接收的字符串参数交给它。异步 RPC 结果最终被转换为 GatewayResponse。

应用层看到的调用端口很小:

1
2
3
public interface IGenericReference {
CompletionStage<String> $invoke(String argument);
}

这个接口没有出现任何 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
2
3
4
5
gateweave:
rpc:
application-name: gateweave-engine
registry-address: zookeeper://127.0.0.1:2181
discovery-mode: INTERFACE

这不是所有项目都应该照搬的默认答案。Provider 如何注册、是否处于 Dubbo 2 到 Dubbo 3 的迁移阶段,才是选择发现模式的依据。

注册中心连通以后,Provider 仍然可能不存在

只启动 ZooKeeper 和网关、不启动目标 Provider 时,网关仍然能够完成注册中心连接和服务订阅。订阅结果中可用 Invoker数量为 0,但这不妨碍 HTTP 服务器启动。

真正请求 /sayHi 时,Dubbo 才会抛出 No provider available。异常沿着异步调用链回到 Netty Handler:服务端日志保留请求 ID 和完整堆栈,HTTP 客户端只看到:

1
2
3
4
HTTP/1.1 500 Internal Server Error
Content-Type: text/plain; charset=UTF-8

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,数据面的匹配和调用过程不必推翻重写。

参考资料