GateWeave 是一个基于 Java 17、Netty、Spring Boot 和 Dubbo 实现的 API 网关项目。HTTP 请求进入 Netty 后会被转换为应用命令,再根据路由配置调用对应的 Dubbo 服务。链路跑通以后,一个新的问题变得明显:路由匹配、请求转换、引用解析和 RPC 调用都集中在同一个应用服务中。

这段代码并不长,但它同时受到几种变化影响。路由规则变化时要修改它,调用参数变化时要修改它,接入新协议时仍然要修改它。代码行数不是主要问题,不同变化方向汇聚在同一处才是问题。

应用服务知道了太多事情

最初的 DefaultGatewayRequestService 直接持有路由表和泛化引用解析函数。收到请求后,它先查找路由,再取得 IGenericReference,把 HTTP 请求体转换成字符串,最后执行 RPC 调用:

1
2
3
4
5
6
7
8
9
10
11
public CompletionStage<GatewayResponse> handle(GatewayRequestCommand command) {
return routeTable.match(command.method(), command.uri())
.map(route -> invoke(command, route))
.orElseGet(() -> CompletableFuture.completedFuture(GatewayResponse.text(404, "Route Not Found")));
}

private CompletionStage<GatewayResponse> invoke(GatewayRequestCommand command, GatewayRoute route) {
IGenericReference reference = genericReferenceResolver.apply(route.target());
String argument = new String(command.body(), StandardCharsets.UTF_8);
return reference.$invoke(argument).thenApply(result -> GatewayResponse.text(200, result));
}

从请求进入网关到结果返回,各层之间的关系如下。

IGenericReference 没有暴露 Dubbo SDK 类型,但它仍然是一种面向 RPC 泛化调用的抽象。应用服务直接依赖它,意味着应用层已经默认“路由命中后一定执行 RPC”。如果再增加 HTTP 或 gRPC 出口,就需要继续扩大解析函数,或者在应用服务中根据协议增加分支。

请求流程需要按照变化原因拆开,而不是继续向应用服务添加条件判断。

GatewaySession 是一次请求的路由快照

路由匹配的结果不只是一个 GatewayRoute。后面的模型转换还需要原始请求,两者在本次调用期间必须保持一致。GatewaySession 用一个不可变记录保存这组关系:

1
2
3
4
5
6
7
public record GatewaySession(GatewayRequestCommand command, GatewayRoute route) {

public GatewaySession {
Objects.requireNonNull(command, "command must not be null");
Objects.requireNonNull(route, "route must not be null");
}
}

这里的 Session 不是登录状态,也不是 Netty Channel 的包装。它没有跨请求共享的可变属性,只表示“这个请求已经命中这条路由”。请求命令和路由快照绑定以后,后续组件不需要重复查询路由,也不会在调用中途拿到另一份配置。

建立会话的职责交给 GatewaySessionFactory:

1
2
3
4
public interface GatewaySessionFactory {

Optional<GatewaySession> openSession(GatewayRequestCommand command);
}

路由未命中属于正常业务结果,因此返回 Optional.empty(),而不是用异常表达。应用服务只需要决定空结果对应 404,路由表的查询方式仍然封装在工厂实现中。

调用插件不应该读取领域路由

GatewayRoute 和 InvocationTarget 属于数据面的领域模型,插件不应该依赖它们。否则插件会随着领域模型一起变化,插件模块也会反向依赖网关引擎。

跨过应用层与插件层边界前,InvocationRequestMapper 会把会话转换成稳定的调用契约:

1
2
3
4
5
6
7
8
9
10
11
12
public record InvocationRequest(
String requestId,
String routeId,
String protocol,
String service,
String operation,
List<String> parameterTypes,
Duration timeout,
Map<String, String> headers,
Map<String, String> attributes,
byte[] payload) {
}

这个对象放在 gateweave-contract 模块,只包含 JDK 类型。Netty 的 FullHttpRequest、领域层的 GatewayRoute 和 Dubbo 的 GenericService 都不会越过边界。

映射时还有一个容易混淆的细节:GatewayRoute 和 InvocationTarget 都有扩展属性。路由属性描述网关自身的行为,例如优先级;调用目标属性描述具体协议,Dubbo 的 version 就属于后者。因此 InvocationRequest.attributes 必须来自 target.attributes(),不能把两组属性混在一起。

请求体也在契约创建时复制。这样插件拿到的是稳定快照,不会受到 Netty 引用计数对象释放或调用方修改字节数组的影响。

协议分派器把选择规则集中起来

每种出口协议实现同一个扩展契约:

1
2
3
4
5
6
public interface ProtocolInvoker {

String protocol();

CompletionStage<String> invoke(InvocationRequest request);
}

protocol() 返回稳定协议标识,例如 dubbo。invoke() 接收统一调用请求,并保持异步返回。接口依赖 CompletionStage,而不是要求实现必须创建 CompletableFuture,调用方只依赖继续编排异步结果所需的能力。

ProtocolInvocationDispatcher 在启动时把所有实现组织成不可变索引。协议名统一转换为小写,重复协议直接阻止启动;请求到来后,根据 InvocationRequest.protocol() 完成一次查找:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
public CompletionStage<String> invoke(InvocationRequest request) {
ProtocolInvoker invoker = invokers.get(request.protocol());
if (invoker == null) {
return CompletableFuture.failedFuture(
new IllegalStateException("No protocol invoker registered for: " + request.protocol()));
}

try {
CompletionStage<String> resultStage = invoker.invoke(request);
return Objects.requireNonNull(resultStage, "protocol invoker must not return null");
} catch (RuntimeException exception) {
return CompletableFuture.failedFuture(exception);
}
}

这个类并不是给 Map#get 换一个名字。它还定义了插件注册和失败语义:重复协议在启动时暴露,未知协议表现为失败的异步阶段,插件同步抛出的提交异常也进入同一条异步错误链。Netty 入口因此不需要分别理解每种插件的错误方式。

分派器也不遍历调用器执行 supports()。协议是配置中的唯一选择键,在初始化阶段建立索引更直接,也能提前发现两个插件争用同一协议的问题。

DubboProtocolInvoker 收拢协议细节

Dubbo 的调用适配放在 gateweave-plugin 模块。DubboProtocolInvoker 不重新实现引用缓存,而是组合第二章已经存在的几个组件:

1
2
3
4
5
6
7
public CompletionStage<String> invoke(InvocationRequest request) {
DubboReferenceOptions options = DubboReferenceOptions.from(request.attributes());
IGenericReference reference = referenceRegistry.getGenericReference(
request.service(), request.operation(), options.version());
String argument = new String(request.payload(), StandardCharsets.UTF_8);
return reference.$invoke(argument);
}

DubboReferenceOptions 负责从扩展属性解析并校验版本,GenericReferenceRegistry 负责查找和复用服务引用,IGenericReference 负责执行已经绑定的方法。适配器只完成这几段已有能力的组合,没有再增加一份缓存,也没有在 InvocationRequest 上增加 Dubbo 专属便利方法。

当前示例调用的方法只接收一个字符串参数,所以适配器将 UTF-8 请求体转换为 String。InvocationRequest 已经保留参数类型和原始负载;以后支持多个参数时,应统一演进调用契约和泛化代理,而不是在适配器里根据接口名称写特殊分支。

分治后的请求链路

完成拆分后,请求仍然从同一个 Netty Handler 进入,也仍然返回 GatewayResponse。变化发生在应用服务内部:它不再理解具体协议,只负责安排几个组件的执行顺序。

两条链路处理的是同一个请求,职责归属已经发生变化:

变化点 分治前 分治后
路由匹配 应用服务直接查询路由表 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 插件都不需要增加协议分支。请求链路的扩展点由此落在明确边界上,而不是重新回到一个不断增长的中心类中。

参考资料