API 网关 HTTP 接入层:从 Netty Pipeline 到应用用例
GateWeave 是一个基于 Java 17、Netty 和 Spring Boot 实现的 API 网关项目。本文先处理其中的 HTTP 接入层:接收请求,把 Netty 消息转换成应用命令,再把执行结果写回连接。路由匹配和 RPC 调用不放在这一层。
一次请求从进入网关到返回响应,会依次经过 HTTP 解码、消息聚合、模型转换、应用处理和响应编码,完整链路如下。
一次 HTTP 请求经过了什么
flowchart LR
subgraph ClientLane[HTTP 客户端]
direction TB
Send[发送 HTTP 请求]
Receive[接收 HTTP 响应]
end
subgraph NettyLane[Netty 入站适配器]
direction TB
Decode[HttpServerCodec<br/>解码请求]
Aggregate[HttpObjectAggregator<br/>聚合完整消息]
MapRequest[NettyGatewayRequestMapper<br/>复制并转换数据]
MapResponse[NettyGatewayResponseMapper<br/>编码响应]
Write[NettyGatewayRequestHandler<br/>写回连接]
end
subgraph ApplicationLane[应用层]
direction TB
Command[GatewayRequestCommand]
UseCase[HandleGatewayRequestUseCase<br/>执行网关用例]
Response[GatewayResponse]
end
Send -->|HTTP 字节流| Decode
Decode -->|HttpRequest / HttpContent| Aggregate
Aggregate -->|FullHttpRequest| MapRequest
MapRequest -->|脱离 Netty 的数据快照| Command
Command --> UseCase
UseCase -->|CompletionStage| Response
Response --> MapResponse
MapResponse -->|FullHttpResponse| Write
Write --> Receive
style ClientLane fill:#fff7e6,stroke:#d48806
style NettyLane fill:#e6f4ff,stroke:#1677ff
style ApplicationLane fill:#f6ffed,stroke:#52c41a
图中间有一条很重要的分界线:Netty 对象只存在于入站适配器中。进入应用层的请求已经变成GatewayRequestCommand,返回时应用层也只产生 GatewayResponse。网络框架负责传输,应用层负责用例,两者不共享技术对象。
Pipeline 决定 Handler 能收到什么
每个新连接建立后,GatewayChannelInitializer 会按顺序装配三个节点:
1 | channel.pipeline() |
HttpServerCodec 负责 HTTP 消息和网络字节之间的转换。此时一次请求仍可能被拆成 HttpRequest、多个HttpContent 和一个 LastHttpContent。HttpObjectAggregator 继续把这些片段聚合为 FullHttpRequest,后面的Handler 才能一次拿到请求行、请求头和完整请求体。
所以 Pipeline 的顺序不是随意排列的。把自定义 Handler 放在聚合器之前,它面对的就是分段消息;放在聚合器之后,它面对的才是完整请求。EmbeddedChannel 很适合验证这类行为,因为不需要真的打开端口,就能把一条请求送进 Pipeline,再检查处理器顺序和输出消息。
聚合完整请求的代价是内存占用。这里给 HttpObjectAggregator 设置了 1 MiB 上限:
1 | gateweave: |
这个配置不能被理解为越大越好。普通 JSON 请求适合先聚合再处理;文件上传、流式代理等场景更适合逐段消费内容,否则并发请求会把大量完整请求体同时留在内存中。
为什么不能把 FullHttpRequest 传入应用层
FullHttpRequest 很方便,方法、URI、请求头和请求体都能直接读取。但它同时把应用层绑定到了 Netty:更换入口协议时,应用服务也要跟着修改;编写测试时,还要为业务逻辑构造 Netty 对象。
NettyGatewayRequestMapper 在入口处完成一次转换:
| Netty 请求数据 | 应用层数据 |
|---|---|
HttpMethod |
String method |
| 请求 URI 字符串 | URI uri |
Netty HttpHeaders |
JDK HttpHeaders |
ByteBuf |
byte[] body |
X-Request-Id |
String requestId |
上游带有 X-Request-Id 时继续使用它,没有时再生成 UUID。这个标识会跟随应用命令进入后续链路,处理失败时日志可以直接关联到原始请求。
请求模型使用 record,但这并不代表内部数据天然不可变。byte[] 仍然可以被修改,因此构造命令时复制一次,调用body() 时再返回副本。这样外部代码既不能通过原始数组修改命令,也不能通过访问器拿到内部数组。
ByteBuf 为什么必须在异步调用前复制
NettyGatewayRequestHandler 继承 SimpleChannelInboundHandler<FullHttpRequest>。它有一个容易被忽略的行为:channelRead0 返回后,Netty 会自动释放收到的请求。
应用用例返回的却不是同步结果,而是:
1 | CompletionStage<GatewayResponse> handle(GatewayRequestCommand command); |
如果命令中继续保存请求的 ByteBuf,异步任务稍后读取数据时,请求对象可能已经释放。Java 引用虽然还在,底层缓冲区却已经失效,最终会出现引用计数异常。
因此请求映射不是简单地换一个类型,而是一次所有权交接:Handler 还持有 FullHttpRequest 时,把后续需要的数据复制出来;channelRead0 返回后,Netty 可以安全释放原请求,异步应用也拥有独立的数据快照。
Handler 如何衔接同步事件与异步结果
Netty 把入站事件交给 Handler 时,当前代码运行在 EventLoop 线程上。Handler 先保存请求的协议版本和 Keep-Alive 状态,完成请求映射后调用应用用例,再通过 whenComplete 等待异步结果。
它没有在 EventLoop 上阻塞等待结果,也没有在这里决定路由或调用下游服务。成功时,GatewayResponse 交给响应映射器;失败时,日志记录异常堆栈和请求 ID,客户端只收到 500 Internal Server Error。内部服务地址和异常详情不会进入响应体。
请求本身不合法时,处理方式不同。URI 无法解析说明请求还没有形成有效的应用命令,此时返回 400 Bad Request,并关闭这条连接。Pipeline 中出现无法恢复的异常时,也直接关闭 Channel,避免在未知状态下继续复用连接。
写出响应后再决定是否关闭连接
GatewayResponse 只描述状态码、响应头和字节数组,不依赖 Netty。返回网络之前,NettyGatewayResponseMapper 才把它转换为 FullHttpResponse。
转换过程中有几个容易漏掉的细节:
- 响应沿用请求的 HTTP 协议版本;
- 文本按照 UTF-8 编码;
Content-Length必须等于最终字节数;- 已知完整长度时关闭分块传输;
- 是否保持连接由原请求的 Keep-Alive 语义决定。
对于非持久连接,不能调用 writeAndFlush 后马上执行 close()。写操作此时可能还在队列里,提前关闭会让响应发送不完整。关闭监听器通过 ChannelFutureListener.CLOSE 挂到写操作上,等响应真正写完后再关闭连接。
这类传输细节同样可以用 EmbeddedChannel 观察:发送带有 Connection: close 的请求后,先读到完整响应,再看到 Channel进入关闭状态。测试验证的是协议行为,而不是某个私有方法是否被调用。
谁创建线程,谁负责释放
服务器启动后长期持有 boss EventLoop、worker EventLoop 和监听 Channel。它们的生命周期如果分散在不同类里,很容易出现端口已经关闭但线程仍存活,或者同一资源被重复销毁的问题。
资源所有权分成两层:
1 | Spring 装配层 |
NettyGatewayServer 不擅自销毁外部传入的 EventLoopGroup,只管理自己保存的监听 Channel。它的 start() 和 close()保持幂等:重复启动不会再次绑定端口,未启动或已经关闭时再次关闭也不会制造新的异常。
在测试服务器生命周期时使用随机端口,比写死 7397 更可靠。测试可以确认服务器确实完成绑定、重复启动仍使用同一个监听地址,并在关闭后释放端口;Spring 上下文测试则继续确认 EventLoop 线程最终退出。
从 HTTP 入口走向真正的网关
完成这一层之后,请求已经能够进入应用用例,但应用服务还不知道它应该访问哪个下游服务。后续加入路由表和 RPC 调用时,Netty Handler 不需要感知 Dubbo 的 GenericService、注册中心或服务版本。
HTTP 入口只负责把网络世界转换成应用世界。下一篇会从 GatewayRequestCommand 继续向内推进,让方法和路径匹配到InvocationTarget,再通过 Dubbo 泛化调用访问真正的 Provider。







