Netty 源码全景:一次请求如何穿过五大核心组件(源码系列第1篇)

Netty 的复杂并不来自 API 数量，而来自它把网络连接、线程调度、事件传播、内存管理和异步结果拆成了相互协作的对象。真正有效的源码阅读方式，是先抓住 Channel、EventLoop、ChannelPipeline、ByteBuf、ChannelFuture 五个核心抽象，再沿一次请求的生命周期观察它们如何接力。

很多人第一次阅读 Netty 源码，会从 ServerBootstrap 开始一路点进去。很快就会遇到 ChannelFactory、ChannelConfig、Unsafe、EventLoopGroup、ChannelPromise、ChannelHandlerContext 等几十个概念。每个类单独看都能理解，但放在一起就像走进一座没有地图的城市：知道每条街叫什么，却不知道自己为什么来到这里。

Netty 源码的正确打开方式不是“记住所有类”，而是先回答一个更朴素的问题：一个 TCP 请求从网卡到达之后，Netty 到底做了哪些事情？

如果把异常分支和协议细节先收起来，主路径可以压缩成一句话：

EventLoop 从 Selector 得到就绪事件  -> Channel 从 Socket 读取字节到 ByteBuf  -> ChannelPipeline 把入站事件交给 Handler  -> 业务 Handler 产生响应  -> 出站 Pipeline 编码消息  -> Channel 把 ByteBuf 写回 Socket  -> ChannelFuture 通知异步操作结果

这条链就是整个系列的主干。后续无论研究服务端启动、内存池、编解码、背压还是优雅停机，本质上都在解释这条主干的某一段。

本文源码基线：

• 项目：Netty
• 版本：netty-4.1.135.Final
• Commit：f05f765d81460799c53123a207f665bf3b465171
• 仓库：https://github.com/netty/netty
• 核心模块：transport、buffer、codec、common

1. ServerBootstrap 是装配器，不是服务器本身

阅读 Netty 示例时，最显眼的对象通常是 ServerBootstrap：

ServerBootstrap bootstrap = new ServerBootstrap();bootstrap.group(bossGroup, workerGroup)    .channel(NioServerSocketChannel.class)    .childHandler(new ChannelInitializer<SocketChannel>() {        @Override        protected void initChannel(SocketChannel ch) {            ch.pipeline().addLast(new MyDecoder());            ch.pipeline().addLast(new BusinessHandler());        }    });ChannelFuture bindFuture = bootstrap.bind(8080).sync();

这段代码很容易制造一个错觉：好像 ServerBootstrap 持有端口、监听连接、读取数据并执行 Handler。实际上它更像 Spring 中的 Bean 装配器。它保存启动参数，并在 bind() 时把这些参数应用到真正的运行时对象上。

它主要完成五类配置：

配置	作用对象	典型内容
`group(parent, child)`	EventLoopGroup	Boss 接入线程组与 Worker I/O 线程组
`channel(...)`	ServerChannel	选择 NIO、Epoll、KQueue 等传输实现
`option(...)`	父 Channel	`SO_BACKLOG` 、接收缓冲等监听端配置
`childOption(...)`	子 Channel	`TCP_NODELAY` 、`SO_KEEPALIVE` 等连接配置
`handler/childHandler`	Pipeline	父 Channel 与每条连接的处理器

关键区别是：ServerBootstrap 在启动阶段最重要，但服务运行起来后，它不会参与每一次数据读写。监听端口的是 NioServerSocketChannel，接收连接的是 Boss EventLoop，处理连接数据的是 Worker EventLoop，业务逻辑则沿每条连接自己的 ChannelPipeline 传播。

因此，排查运行时延迟时盯着 Bootstrap 配置只能解决一部分问题。连接建立后的绝大多数性能问题，都要进入 Channel、EventLoop、Pipeline 和 Buffer 这一层观察。

2. Channel 是连接的对象化表达，也是所有能力的聚合根

Netty 的 Channel 常被翻译成“通道”，但这个词太轻，容易让人误以为它只是一个读写接口。更准确的理解是：Channel 是一条网络连接在 Netty 运行时中的对象化表达。

一条 Channel 至少聚合了以下信息：

• 底层 JDK 或 Native Socket。
• 自己归属的 EventLoop。
• 这条连接的 ChannelPipeline。
• 连接状态和地址信息。
• ChannelConfig 与各种 Option。
• 写侧的 ChannelOutboundBuffer。
• 用于执行底层操作的 Unsafe。

Channel 接口对用户暴露安全、稳定的操作，例如 write()、flush()、close()、pipeline() 和 eventLoop()。真正直接操作底层传输的能力被收进内部 Unsafe 接口。这不是说底层操作“不安全”到不能用，而是 Netty 有意把用户扩展面和传输实现面隔离开：

public interface Channel extends AttributeMap, ChannelOutboundInvoker, Comparable<Channel> {    EventLoop eventLoop();    Channel parent();    ChannelConfig config();    boolean isOpen();    boolean isActive();    ChannelPipeline pipeline();    Unsafe unsafe();}

源码位置：

• 文件：transport/src/main/java/io/netty/channel/Channel.java
• 类：io.netty.channel.Channel
• 链接：https://github.com/netty/netty/blob/netty-4.1.135.Final/transport/src/main/java/io/netty/channel/Channel.java

为什么要把这么多能力挂在 Channel 上？因为网络事件天然以连接为边界。读到的数据属于某条连接，Pipeline 是某条连接的，写缓冲积压也是某条连接的，关闭和异常同样只影响某条连接。Channel 因而成为查找运行时上下文的入口。

这里还要区分两种 Channel：

1. NioServerSocketChannel：代表监听端口的父 Channel，关注 OP_ACCEPT。
2. NioSocketChannel：代表一条已建立的 TCP 连接，关注 OP_READ、OP_WRITE、OP_CONNECT。

服务端只有一个监听 Channel，却可能有几十万条子 Channel。option() 配置父 Channel，childOption() 配置子 Channel，正是因为它们承担的职责不同。

3. EventLoop 的本质不是线程池，而是“连接与单线程执行器”的绑定

很多教程把 NioEventLoopGroup 简化为线程池，这个说法方便入门，但不足以解释 Netty 的并发语义。更准确地说：

• EventLoopGroup 是一组 EventLoop 的管理和选择器。
• EventLoop 是一个长期运行的单线程事件执行器。
• Channel 注册后，通常会在生命周期内固定绑定一个 EventLoop。

这一点决定了 Netty 最重要的线程安全保证：同一条 Channel 上的大多数 I/O 事件和 Pipeline 回调，会被同一个 EventLoop 串行执行。

假设同一连接先后收到两个数据包 A、B，EventLoop 不会同时在两个线程中调用该 Channel 的 channelRead()。它会按事件循环顺序处理。这让很多 Handler 可以避免围绕连接状态加锁。例如协议解析器可以把半包保存在成员变量里，因为对同一 Channel 的回调天然串行。

但“单线程”不等于“整个 Netty 只有一个线程”。一个 Worker Group 通常有多个 EventLoop，每个 EventLoop 管理一批 Channel：

Worker EventLoop 1 -> Channel A, D, G ...Worker EventLoop 2 -> Channel B, E, H ...Worker EventLoop 3 -> Channel C, F, I ...

这种绑定同时带来优势和风险。

优势是减少锁竞争、保持事件顺序、提高 CPU Cache 局部性。风险是某个 Handler 一旦在 EventLoop 中执行阻塞操作，不只会拖慢当前请求，还会拖慢同一 EventLoop 管理的全部连接。数据库慢查询、同步 HTTP 调用、Thread.sleep()、大文件计算都可能让一组看似无关的连接一起抖动。

所以“业务 Handler 不要阻塞 EventLoop”不是一句泛泛的性能建议，而是由 Channel 与 EventLoop 的绑定关系直接推导出的稳定性约束。

4. ChannelPipeline 不是过滤器列表，而是一条带方向的事件总线

每个 Channel 创建时都会拥有自己的 ChannelPipeline。默认实现 DefaultChannelPipeline 内部维护一条双向链表，链表两端是系统节点 HeadContext 和 TailContext，用户添加的 Handler 会被包装成 ChannelHandlerContext 插入其中。

为什么不直接存 List<ChannelHandler>？因为 Netty 不只需要“按顺序调用 Handler”，还需要解决四个问题：

1. 入站事件与出站事件的传播方向相反。
2. 每个 Handler 可能绑定不同的执行器。
3. Handler 需要从当前位置继续传播事件。
4. Pipeline 需要支持运行时动态添加和删除节点。

ChannelHandlerContext 因此非常关键。它既持有 Handler，也持有前后节点、所属 Pipeline、执行器和事件传播能力。Handler 是业务逻辑，Context 是 Handler 在某条 Pipeline 中的运行时座位。

入站事件通常从 Head 向 Tail：

Head -> Decoder -> AuthHandler -> BusinessHandler -> Tail

出站事件通常从 Tail 向 Head：

Tail -> Business outbound -> Encoder -> Head -> Socket

这解释了一个常见疑问：为什么解码器通常放前面，编码器的执行方向却像“倒着走”？因为网络读取发生在 Head，入站数据自然向后传播；业务写出通常从当前 Context 或 Pipeline 尾部发起，出站事件向前寻找能处理它的节点，最终到 Head 执行底层写操作。

Pipeline 还有一个非常实用的隔离效果：Handler 可以只关心自己处理的事件。解码器只把字节变成消息，鉴权 Handler 只判断身份，业务 Handler 只处理领域逻辑，编码器只负责把响应变回字节。复杂协议因此能够以组合而不是继承的方式构建。

5. ByteBuf 是性能设计的中心，不只是 ByteBuffer 的替代品

如果只把 ByteBuf 理解为“更好用的 ByteBuffer”，会漏掉 Netty 内存设计最重要的部分。ByteBuf 同时承担四个角色：

• 数据容器：保存网络读写的字节。
• 读写游标模型：readerIndex 与 writerIndex 分离。
• 内存视图：slice()、duplicate()、compositeBuffer() 减少复制。
• 生命周期对象：通过引用计数决定何时释放或归还内存池。

JDK ByteBuffer 使用一个 position 同时服务读写，常常需要 flip() 切换模式。ByteBuf 把可读区、可写区和已废弃区明确区分：

0 -------- readerIndex -------- writerIndex -------- capacity| 已读区域 |      可读区域       |      可写区域       |

更重要的是，Netty 默认可以使用池化直接内存。直接内存减少了某些 Socket I/O 场景下的额外复制，池化则减少频繁申请和释放大块内存的成本。但性能收益伴随着更严格的所有权要求：谁最后消费 ByteBuf，谁通常就要负责释放；如果把对象异步传到别处，需要先 retain()；如果创建共享视图，要理解它是否共享引用计数。

这也是 Netty 最常见、最隐蔽的线上问题之一：业务功能完全正确，压测一段时间后直接内存持续增长，最终出现 OutOfDirectMemoryError。根因不是 GC 调优，而是某条异常分支没有 release()，或者异步任务在引用计数归零后继续访问 Buffer。

6. ChannelFuture 把“发起操作”和“操作完成”彻底分离

网络操作天然是异步的。bind(8080) 被调用时，端口不一定已经完成绑定；connect() 返回时，TCP 握手不一定完成；writeAndFlush() 返回时，数据也不一定已经进入对端应用。

Netty 使用 ChannelFuture 表示这些操作的未来结果：

ChannelFuture future = channel.writeAndFlush(message);future.addListener(f -> {    if (!f.isSuccess()) {        log.error("send failed", f.cause());    }});

这里最容易犯的错误，是把“方法已返回”当成“操作已成功”。例如：

channel.writeAndFlush(msg);ReferenceCountUtil.release(msg); // 可能提前释放

如果消息所有权已经交给 Netty，通常不应再由调用方立即释放。又例如在 EventLoop 内部调用 future.sync() 等待同一个 EventLoop 才能完成的操作，可能制造死锁或至少触发 Netty 的阻塞保护。

ChannelPromise 是可写的 Future，由执行操作的一方设置成功或失败；ChannelFuture 是读取结果的视图，由调用方监听。这个区分让异步完成事件可以沿 Pipeline、EventLoop 和调用线程安全传播。

7. 一次请求的端到端接力

现在把五个核心对象串起来。假设客户端向 Netty 服务端发送一个带长度字段的二进制请求。

第一步，TCP 连接建立。Boss EventLoop 监听 NioServerSocketChannel 的 OP_ACCEPT，收到就绪事件后调用 JDK accept() 创建 SocketChannel，Netty 把它包装成 NioSocketChannel。

第二步，连接注册。ServerBootstrapAcceptor 为新 Channel 应用 childHandler、childOption 和属性，然后把它注册到 Worker EventLoop。注册完成后，这条连接通常固定由该 Worker 处理。

第三步，读事件到达。Worker EventLoop 的 Selector 返回 OP_READ，调用 Channel 的 Unsafe 读取数据。RecvByteBufAllocator 决定本轮分配多大的 ByteBuf，底层 Socket 把字节写入 ByteBuf 的可写区域。

第四步，入站传播。Channel 触发 pipeline.fireChannelRead(byteBuf)。长度字段解码器先判断数据是否足够组成完整帧；如果只是半包，就把字节保留在累积缓冲区；如果完整，就切出一帧向后传播。

第五步，业务处理。业务 Handler 收到的不再是任意字节，而是协议消息。它执行业务逻辑，构造响应并调用 ctx.writeAndFlush(response)。

第六步，出站传播。出站事件从当前 Context 向 Head 方向传播。Encoder 把响应对象编码成 ByteBuf，HeadContext 最终调用 Channel Unsafe，把消息加入 ChannelOutboundBuffer 并尝试写入 Socket。

第七步，异步完成。如果一次没有写完，Netty 注册 OP_WRITE，等 Socket 再次可写时继续发送。全部写出后，对应 Promise 完成，业务注册的 Listener 被通知。

这条时序里有三个值得特别记住的事实：

1. 业务 Handler 不直接读取 Socket，它接收 Pipeline 传播的事件。
2. writeAndFlush() 不等于数据已经到达客户端，它只是发起异步写。
3. 同一 Channel 的事件串行，不代表不同 Channel 互不影响；它们可能共享同一个 EventLoop。

8. 源码分层决定了阅读顺序

Netty 仓库模块很多，但前 10 篇主要围绕四个模块：

模块	关注点	代表类
`transport`	Channel、EventLoop、Pipeline、Bootstrap、NIO	`AbstractChannel` 、`NioEventLoop`
`buffer`	ByteBuf、Allocator、池化内存	`PooledByteBufAllocator`
`codec`	字节与消息转换、协议帧处理	`ByteToMessageDecoder`
`common`	Future、Promise、并发队列、工具	`DefaultPromise`

推荐的源码阅读方式是“纵向主链 + 横向抽象”。

先纵向走通一次服务端请求：bind()、Accept、Register、Read、Pipeline、Write。走通后再横向比较接口与实现，例如 Channel 与 AbstractChannel，EventLoop 与 NioEventLoop，ByteBuf 与池化实现。反过来如果一开始就研究继承树，很容易在大量模板方法和平台分支中迷路。

还要刻意区分三类方法：

• 用户 API：例如 Channel.writeAndFlush()。
• Pipeline 传播方法：例如 ctx.write()、fireChannelRead()。
• 传输实现方法：例如 doReadBytes()、doWrite()。

它们可能都叫“write”或“read”，但职责完全不同。API 发起操作，Pipeline 负责寻找处理节点，底层方法才执行系统调用。

9. 这套架构最容易引发的四类线上问题

理解架构最终要回到排障。Netty 线上问题大多能映射到以下四类边界。

第一类是 EventLoop 被阻塞。表现为一批连接同时延迟升高、定时任务延迟、心跳误判超时。检查 Handler 是否执行同步 RPC、数据库查询、锁等待或大计算，并结合线程栈确认 EventLoop 停在哪里。

第二类是 ByteBuf 生命周期错误。泄漏时直接内存持续增长，开启 ResourceLeakDetector 后出现访问记录；提前释放时则出现 IllegalReferenceCountException。重点检查异常分支、异步转交、Decoder 产出和自定义 Message 是否持有 Buffer。

第三类是写缓冲失控。慢客户端或网络拥塞使 ChannelOutboundBuffer 积压，isWritable() 变为 false。如果业务仍无限生产消息，最终会把内存耗尽。需要监听 channelWritabilityChanged，并把背压传回生产者。

第四类是 Pipeline 传播中断。某个入站 Handler 忘记 ctx.fireChannelRead(msg)，后续 Handler 永远收不到消息；某个分支吞掉异常却不释放 Buffer，也会形成泄漏。Pipeline 的自由度很高，因此所有权和传播责任必须明确。

10. 建立源码地图后，再进入细节

如果只记住本文一个结论，我希望是：Netty 不是一个“封装了 Selector 的网络库”，而是一套围绕 Channel 构建的单线程事件运行时。

ServerBootstrap 负责装配，Channel 表达连接，EventLoop 提供串行执行环境，Pipeline 组织事件处理，ByteBuf 承载数据，Future/Promise 表达异步结果。它们不是六个孤立概念，而是一次请求的六个接力棒。

接下来第 2 篇会从最熟悉的 bootstrap.bind(8080) 开始，拆解 Channel 创建、Pipeline 初始化、EventLoop 注册和真正端口绑定之间的先后关系。理解这条启动链之后，ServerBootstrap 的各种配置项就不再是需要死记的 API，而会变成可以从运行时对象模型自然推导出的设计。

参考资料

1. Netty 官方仓库：https://github.com/netty/netty
2. Netty 4.1 用户指南：https://netty.io/wiki/user-guide-for-4.x.html
3. Channel.java：https://github.com/netty/netty/blob/netty-4.1.135.Final/transport/src/main/java/io/netty/channel/Channel.java
4. DefaultChannelPipeline.java：https://github.com/netty/netty/blob/netty-4.1.135.Final/transport/src/main/java/io/netty/channel/DefaultChannelPipeline.java
5. NioEventLoop.java：https://github.com/netty/netty/blob/netty-4.1.135.Final/transport/src/main/java/io/netty/channel/nio/NioEventLoop.java
6. ByteBuf.java：https://github.com/netty/netty/blob/netty-4.1.135.Final/buffer/src/main/java/io/netty/buffer/ByteBuf.java