《Netty 高性能网络编程》附录 A Netty 常用 API 速查
按 Bootstrap、Channel、EventLoop、Pipeline、ByteBuf、编解码、HTTP、WebSocket、HTTP/2 与连接池十组,列出 Netty 4.2 常用类、正确包名、方法签名与对应章节,并标出容易记错的常量与重载差异,供写 linkd-v2 时直接查表。
category
按 Bootstrap、Channel、EventLoop、Pipeline、ByteBuf、编解码、HTTP、WebSocket、HTTP/2 与连接池十组,列出 Netty 4.2 常用类、正确包名、方法签名与对应章节,并标出容易记错的常量与重载差异,供写 linkd-v2 时直接查表。
本节只写 Linux 部署侧:EpollEventLoopGroup 与 EpollServerSocketChannel 的配置、SO_REUSEPORT 与 TCP_FASTOPEN 的内核前提、classifier 与 glibc 兼容性,以及 Epoll.isAvailable() 为 false 时的回退。全部为部署说明,不是本机实测。
isAvailable() 为 true 不等于 server 真的跑在 kqueue 上。本节用本机探针打印 serverChannel 与 eventLoop 的实际类名,给出 KQueueEventLoopGroup 启动代码、Apple Silicon classifier,并处理 JDK 25 对 System.loadLibrary 的受限方法警告。
NIO、Epoll、KQueue 三套 transport 不是三个开关,而是同一组接口的三份实现。本节讲清 Epoll.isAvailable() 与 KQueue.isAvailable() 的探测、classifier 构件选择、NativeEventLoops 的回退顺序,以及原生传输为什么不保证更快。
gRPC 不是又一个网络框架,而是 HTTP/2、protobuf 与生成代码的组合。本节用 linkd-v2 的 9092 端口拆开这三层,给出 pom 依赖、linkd.proto、LinkdServiceImpl 与 NettyServerBuilder 服务端、NettyChannelBuilder 客户端和 deadline,并说明 shaded Netty 的版本隔离边界。
把 11.1 的 pipeline 变成 9091 上可运行的 h2c 服务端。本节给出 ServerBootstrap、Http2FrameCodec、Http2MultiplexHandler 与子 channel 的完整装配,讲 HEADERS/DATA 如何创建和关闭 stream、GOAWAY 与流量控制窗口怎么处理,并用 curl --http2-prior-knowledge 验证。
HTTP/2 帧分连接级与 stream 级两层。本节用 linkd-v2 的 9091 端口拆开 Http2FrameCodec 与 Http2MultiplexHandler 的分工,说明 preface、SETTINGS、HEADERS、DATA、WINDOW_UPDATE、GOAWAY 归谁处理,对比 h2c prior-knowledge 与 ALPN,并给出多路复用与连接池的取舍。
连接多了以后,回显要变成广播。本节用 ChannelGroup 管理会话,用 AttributeKey 绑定 userId,用 IdleStateHandler 加 ping/pong 清理死连接,给出 /ws/broadcast 的完整 WebSocketHub,并说明慢客户端过滤、广播风暴与按房间分组的扩展边界。
升级之后,入站的都是 WebSocketFrame。本节分清文本、二进制、ping、pong、close 五类帧在 WebSocketServerProtocolHandler 里的去向,讲 continuation 分片与 WebSocketFrameAggregator 的位置和上限,给出 /ws/echo 的文本与二进制回显代码,以及大帧带来的内存与背压问题。
WebSocket 仍以 HTTP/1.1 Upgrade 开始。本节按 HttpServerCodec、HttpObjectAggregator、WebSocketServerProtocolHandler 的顺序装配 9090 端口,讲路径匹配、握手完成事件与 400 失败分支,并给出可运行的 WebSocketServer 与 curl 验证命令。
AUTO_READ 默认开启时,Netty 读完一轮就自动继续读,业务队列满也不会停。本节用本机输出验证手动 read() 的一轮边界,讲清 channelReadComplete 的恢复时机、慢消费者队列上限与 RCVBUF_ALLOCATOR 的边界,并给出 linkd-v2 的 ReadBackpressureHandler 与流量整形取舍。
write() 与 writeAndFlush() 的差别不在名字,而在 ChannelFuture 什么时候完成。本节用本机输出验证入队与 flush 的分界,解释批量写后一次 flush 的收益、待写队列在不可写状态下继续增长的风险,并给出 linkd-v2 广播发布器的批量写与监听器重试、丢弃策略。
WriteBufferWaterMark 的两个参数到底在统计什么?本节用 linkd-v2 的 WritabilityPump 拆开 Channel.isWritable 的判定、channelWritabilityChanged 的触发与 4.2 默认的 32/64 KiB 水位,给出生产者暂停与恢复的完整 handler,并用本机输出核对 config 打印值与状态迁移。
关闭一条连接有 close、disconnect、shutdownOutput 三种语义,半关闭处理错会留下永远不释放的连接。本节说明 ALLOW_HALF_CLOSURE 与 ChannelInputShutdownEvent 的配合,用 ChannelGroup 批量关闭,给出 linkd-v2 GracefulShutdown 的步骤与期限,以及 SO_LINGER 触发 RST 的边界。
连接池的关键不是池化本身,而是何时借、何时还、何时判定连接已坏。本节拆开 FixedChannelPool 的三个生命周期回调,配合 ChannelHealthChecker 与获取超时,用 AbstractChannelPoolMap 按 host:port 建池,并用 Little 定律说明池大小以及 HTTP/1.1 与 HTTP/2 的取舍。
客户端重连的难点不在 connect 调用,而在失败路径、触发时机与退避节奏。本节拆开 Bootstrap.connect 的拒绝、超时与握手失败三种结果,用 closeFuture 触发重连,给出 linkd-v2 ReconnectHandler 的状态机、指数退避、0.8 到 1.2 抖动、排队上限与惊群规避。
9093 上任何能连上的客户端都能发 REQUEST。本节用 HELLO/token 三态握手把未认证连接挡在业务 handler 之前:AttributeKey 与 Channel 绑定、MessageDigest.isEqual 比较 token、10 秒认证超时、失败即 ERROR 加 close。
连接空闲时双方都不知道对端是否还活着。本节拆开 IdleStateHandler 的三种空闲与 IdleStateEvent.state(),给出服务端 30 秒发 PING、客户端回 PONG、连续两轮无响应关闭的完整 handler,并说明心跳为什么替代不了业务超时。
16 字节头里的每个字段都有代价。本节讲清 magic 为什么不是安全措施、version 怎么兼容、type 与 flags 留了多少扩展位、requestId 的无符号语义和 1 MiB 上限,并给出 LinkdFrame 与两个编解码器的完整实现。
解码失败不是一句 catch 就能收尾。本节讲 DecoderException、TooLongFrameException、CorruptedFrameException 在 pipeline 里的传播路径,给出 linkd-v2 的 ERROR 帧与关闭策略、HTTP decoderResult 的 400 处理,并说明 exceptionCaught 吞掉异常后连接为什么会半死。