《Netty 高性能网络编程》附录 A Netty 常用 API 速查

这张表怎么用

这不是教程，是把正文里出现过的类、包名和方法签名压成一张可查的表。写 linkd-v2 时先在这里定位类，再回到对应章节看为什么这样用。

约定如下：

• 版本固定为 Netty 4.2.19.Final，JDK 25。方法签名省略返回值类型，只保留参数，避免表格过宽；需要返回值时看「用途」一列。
• 「包」一列是完整包名。Netty 的类分散在 netty-transport、netty-buffer、netty-codec-http 等模块里，netty-all 只是聚合 POM，import 写错包是编译期最常见的错误。
• 「章节」指向正文的节号，附录不重复解释机制。
• 表格里的 ... 表示可变参数或省略的重载，不是可以照抄的省略号。

包名先单独记四个容易混的：

ChannelGroup 不在 io.netty.channel 下，这一点在 IDE 自动补全时经常被选错；Epoll 与 KQueue 都只在对应平台的 native 构件存在时才可用，import 能通过不代表运行期能加载。

Bootstrap 与启动

ServerBootstrap 管服务端，Bootstrap 管客户端。两者的方法名高度对称，区别在服务端要分 boss/worker 两组线程、要设 childHandler 和 childOption，客户端只有一个 handler。bind 与 connect 都返回 ChannelFuture，但不要在 EventLoop 线程里对它调用 sync()。

option 与 childOption 的分工可以用一句话判断：连接建立之前就要生效的（ backlog、地址复用）放 option；每条连接自己的（TCP_NODELAY、水位线、AUTO_READ）放 childOption。把 TCP_NODELAY 写到 option 里，编译能过，运行期不生效。

一个最小服务端骨架，把上表串起来：

import io.netty.bootstrap.ServerBootstrap;
import io.netty.channel.ChannelFuture;
import io.netty.channel.ChannelInitializer;
import io.netty.channel.ChannelOption;
import io.netty.channel.WriteBufferWaterMark;
import io.netty.channel.nio.NioEventLoopGroup;
import io.netty.channel.socket.SocketChannel;
import io.netty.channel.socket.nio.NioServerSocketChannel;

public final class BootstrapSketch {
    public static void start() throws InterruptedException {
        ServerBootstrap b = new ServerBootstrap();
        b.group(new NioEventLoopGroup(1), new NioEventLoopGroup())
                .channel(NioServerSocketChannel.class)
                .option(ChannelOption.SO_BACKLOG, 1024)
                .childOption(ChannelOption.TCP_NODELAY, true)
                .childOption(ChannelOption.WRITE_BUFFER_WATER_MARK,
                        new WriteBufferWaterMark(32 * 1024, 64 * 1024))
                .childHandler(new ChannelInitializer<SocketChannel>() {
                    @Override
                    protected void initChannel(SocketChannel ch) {
                        // 这里挂 LinkdFrameDecoder / LinkdFrameEncoder
                    }
                });
        ChannelFuture f = b.bind(9093).sync();
        f.channel().closeFuture().sync();
    }
}

这段代码只演示装配顺序，没有挂真实 handler。bind(...).sync() 在主线程调用没问题；如果把它搬进某个 handler 的 channelRead 里，就会卡住该 Channel 所属的 EventLoop。

Channel、Future 与 Socket 参数

Channel 是连接的门面：读写、关闭、取 pipeline、取 EventLoop 都从这里进。ChannelFuture 是异步结果，sync() 只适合启动线程和测试线程；在 EventLoop 线程里用 addListener。ChannelOption 是强类型常量，不是字符串，写 option("TCP_NODELAY", true) 编译不过。

SO_RCVBUF 与 WRITE_BUFFER_WATER_MARK 经常被混为一谈。前者是内核 socket 缓冲区，后者是 Netty 用户态写队列的阈值，Channel.isWritable() 反映的是后者。调小后者不会让内核少收数据，只会更早告诉业务层「别再写了」。

EventLoop 与线程

EventLoop 是单线程执行器，一个 Channel 注册后终身绑定同一个 EventLoop。NioEventLoopGroup(int nThreads) 的 nThreads 是组内 EventLoop 数，不是「每个连接一个线程」；传 0 或不传时走默认值，默认值受 -Dio.netty.eventLoopThreads 影响。

在 macOS 上 Epoll.isAvailable() 返回 false 是正常结果，不是依赖损坏。反过来，KQueue.isAvailable() 返回 false 时通常意味着 osx-aarch_64 或 osx-x86_64 的 classifier 没被带进来，代码要回退 NioEventLoopGroup。

Pipeline 与 Handler

Pipeline 的入站事件从 head 到 tail，出站事件从 tail 到 head。ctx.writeAndFlush() 从当前 handler 向前找出站 handler，ctx.channel().writeAndFlush() 从 tail 开始，两者经过的 handler 可能不同。SimpleChannelInboundHandler 默认自动释放入站消息，ByteToMessageDecoder 不释放入参。

@Sharable 只适合没有可变成员状态的 handler。WebSocketHub 持有 ChannelGroup，这个成员本身是线程安全的，但如果在 handler 里又加了 int count 或 Map<Channel, ...> 这样的可变字段，就不能标 @Sharable，否则多个连接会同时改同一份状态。

ByteBuf 与引用计数

ByteBuf 有读索引和写索引，readXxx 移动读索引，getXxx 不移动，writeXxx 移动写索引，setXxx 不移动。slice/duplicate 共享底层内存但各自维护索引；带 retained 前缀的重载会增加引用计数，调用方负责释放。

readSlice 与 readRetainedSlice 的差别不是「省不省拷贝」，而是「引用计数加不加」。前者返回的切片在源缓冲区 release 后立刻失效，后者让源计数加 1，必须自己 release。ByteToMessageDecoder.decode 里的 in 由父类管理，不能 release；用 readRetainedSlice 取出的切片才归当前方法。

编解码器

解码器分两类：ByteToMessageDecoder 处理「字节到消息」，MessageToMessageDecoder 处理「消息到消息」。编码器对应 MessageToByteEncoder 与 MessageToMessageEncoder。长度域解码器是 ByteToMessageDecoder 的现成实现，参数顺序错一位就会得到「永远等不够」或「每帧多读几个字节」。

LengthFieldBasedFrameDecoder 的 lengthAdjustment 是「长度字段的值 + adjustment = 后续负载长度」。如果长度字段只记录负载、不包含头部，通常 lengthAdjustment = 0；如果长度字段记录了「头部 + 负载」，要减掉头部长度。initialBytesToStrip 决定交给下游的帧是否还带长度头。

HTTP/1.1

HTTP 的 pipeline 通常由三部分组成：HttpServerCodec 做请求/响应编解码，HttpObjectAggregator 把分块的 HttpContent 聚合成 FullHttpRequest，业务 handler 处理完整请求。聚合有内存代价，maxContentLength 必须显式设置。

FullHttpRequest 的 content() 是 ByteBuf，它的生命周期跟随请求对象。LinkdHttpHandler 继承 SimpleChannelInboundHandler<FullHttpRequest> 时，channelRead0 返回后请求会被释放，不能把 req 或 req.content() 存进会话表；要异步处理就先 retain()，任务结束再 release()。

WebSocket

WebSocket 服务端由 WebSocketServerProtocolHandler 完成握手与协议升级，业务 handler 只处理 TextWebSocketFrame、BinaryWebSocketFrame 等帧。握手完成会触发 ServerHandshakeStateEvent.HANDSHAKE_COMPLETE，会话表通常在这一刻登记连接。

文本帧的 text() 返回 String，每次调用都可能重新解码；广播时不要对同一帧反复取 text() 再重建，直接复用 TextWebSocketFrame 并配合 retainedDuplicate() 更稳妥。WebSocketHub 持有 ChannelGroup，关闭连接时要从组里移除，否则广播会一直命中已关闭的 Channel。

HTTP/2

HTTP/2 分两层：Http2FrameCodec 处理连接级帧，Http2MultiplexHandler 把每个 stream 变成子 Channel。业务代码通常挂在子 Channel 的 pipeline 上，用 Http2StreamFrameToHttpObjectCodec 把 Http2HeadersFrame/Http2DataFrame 转成 HttpRequest/HttpContent。

不要直接把 Http2HeadersFrame 当 FullHttpRequest 用。前者只有头，body 在后续 Http2DataFrame 里；需要完整请求时要么自己聚合，要么挂 Http2StreamFrameToHttpObjectCodec 再配 HttpObjectAggregator。

连接池

连接池的语义是「借出、归还」，不是「缓存 Channel 对象」。FixedChannelPool 限制最大连接数，SimpleChannelPool 不限制；ChannelPoolHandler 在创建、借出、归还三个时点回调，健康检查决定归还的连接还能不能用。

ChannelPool.release() 返回的 future 完成前，这条连接不能再次借出。异常路径上忘记 release，池子的可用连接会越来越少，表现为 acquire() 一直等不到结果；这类问题看 FixedChannelPool 的 pending 数量比看 GC 更直接。

签名与常量速记

下面这些差异在正文里分散出现过，集中列一次：

方法签名以 Netty 4.2.19.Final 的 javadoc 为准；本表省略了返回值与 throws，是为了在纸面上可读。真正拿不准时，用 IDE 跳转到 netty-transport-4.2.19.Final.jar 里的类，比搜索引擎可靠。

小结

• 先记包名：ChannelGroup 在 io.netty.channel.group，NioEventLoopGroup 在 io.netty.channel.nio，HTTP/2 全部在 io.netty.handler.codec.http2。
• 服务端用 ServerBootstrap 的 childHandler/childOption，客户端用 Bootstrap 的 handler/option；两组方法不要互相替换。
• ChannelFuture.sync() 只留给启动线程和测试；EventLoop 线程里用 addListener。
• Pipeline 的入站从 head 到 tail、出站从 tail 到 head；ctx.writeAndFlush 与 channel().writeAndFlush 起点不同。
• ByteBuf 的 readXxx/writeXxx 移动游标，getXxx/setXxx 不移动；带 retained 的切片归调用方释放。
• SimpleChannelInboundHandler 自动释放，ByteToMessageDecoder 不释放入参；这两条决定了大部分引用计数错误。
• HTTP 先聚合再处理，WebSocket 先握手再登记会话，HTTP/2 先分子 Channel 再谈请求对象。
• 连接池的核心是借还配对，异常路径不归还，池子会静默枯竭。