目录

本指南按照学习路径将 27 个子模块分为 6 个阶段，从入门到高级特性逐一讲解。每个模块包含：原理说明、核心代码、配置要点和注意事项。

阶段	主题	模块数	关键技能
一、网络编程基础	Netty 入门、Java IO、Reactor	3	Hello World、BIO/NIO/AIO、线程模型
二、Netty 核心概念	Channel、ByteBuf、Codec	3	Pipeline、内存管理、帧处理
三、常用编解码器	序列化、XML/JSON、压缩、Handler	4	Protobuf、压缩、心跳、限速
四、网络协议实战	TCP/UDP/HTTP/WebSocket/SSL	6	回显、文件传输、WebSocket、TLS 1.3
五、高级特性 (Netty 4.2)	io_uring、QUIC、性能调优	3	Linux 原生 I/O、HTTP/3、调优
六、工程化与生态	RPC/Spring/Reactive/gRPC	8	完整工程化落地

一、网络编程基础 — 快速开始

1.1 HelloWorldServer — 第一个 Netty 服务器

模块定位：这是整个 Netty 学习系列的入口示例，展示了一个最简 Netty 回显服务器的结构。它不依赖任何额外的编解码器，只使用 StringEncoder / StringDecoder，是理解 Netty "管道模型"理念的最佳起点。

文件结构

核心代码 — 服务器端

HelloWorldServer.java 展示了 Netty 服务器的核心组件：

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

@SuppressWarnings("unused")
public class HelloWorldServer {

    private static final int PORT = 8080;

    public static void main(String[] args) throws InterruptedException {
        // 1. 创建事件循环组：Boss 负责接受连接，Worker 负责读写
        EventLoopGroup bossGroup = new NioEventLoopGroup(1);
        EventLoopGroup workerGroup = new NioEventLoopGroup();

        try {
            // 2. 创建服务器启动引导器
            ServerBootstrap bootstrap = new ServerBootstrap();
            bootstrap.group(bossGroup, workerGroup)
                    .channel(NioServerSocketChannel.class)
                    .childHandler(new ChannelInitializer<SocketChannel>() {
                        @Override
                        protected void initChannel(SocketChannel ch) {
                            ChannelPipeline pipeline = ch.pipeline();
                            pipeline.addLast(new StringDecoder());
                            pipeline.addLast(new StringEncoder());
                            pipeline.addLast(new EchoHandler());
                        }
                    })
                    .bind(PORT)
                    .sync();

            System.out.println("Netty Hello World Server started on port " + PORT);
            ChannelFuture future = bootstrap.serverChannel().closeFuture();
            future.sync();

        } finally {
            bossGroup.shutdownGracefully();
            workerGroup.shutdownGracefully();
        }
    }
}

核心组件说明

组件	作用
ServerBootstrap	Netty 服务器启动引导器，配置 Boss/Worker 线程组
NioServerSocketChannel	NIO 非阻塞服务器端 Socket 通道
NioEventLoopGroup	事件循环线程组，Boss 负责 accept，Worker 负责读写
ChannelPipeline	处理器管道，Inbound 从 Head 向 Tail，Outbound 从 Tail 向 Head
ChannelInitializer	连接建立后回调，配置 Channel 的 Pipeline

核心代码 — 业务 Handler

EchoHandler.java 继承 SimpleChannelInboundHandler<String>，自动管理消息释放：

import io.netty.channel.ChannelHandlerContext;
import io.netty.channel.SimpleChannelInboundHandler;

public class EchoHandler extends SimpleChannelInboundHandler<String> {

    @Override
    protected void channelRead0(ChannelHandlerContext ctx, String msg) {
        System.out.println("Server received: " + msg);
        ctx.writeAndFlush(msg);  // 回显：原样返回给客户端
    }

    @Override
    public void channelActive(ChannelHandlerContext ctx) {
        System.out.println("Client connected: " + ctx.channel().remoteAddress());
    }

    @Override
    public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) {
        cause.printStackTrace();
        ctx.close();
    }
}

核心代码 — 客户端

HelloWorldClient.java 展示了 Netty 客户端的启动方式：

import io.netty.bootstrap.Bootstrap;
import io.netty.channel.ChannelFuture;
import io.netty.channel.ChannelInitializer;
import io.netty.channel.EventLoopGroup;
import io.netty.channel.nio.NioEventLoopGroup;
import io.netty.channel.socket.SocketChannel;
import io.netty.channel.nio.NioSocketChannel;

public class HelloWorldClient {

    private static final String HOST = "127.0.0.1";
    private static final int PORT = 8080;

    public static void main(String[] args) throws InterruptedException {
        EventLoopGroup group = new NioEventLoopGroup();

        try {
            Bootstrap bootstrap = new Bootstrap();
            bootstrap.group(group)
                    .channel(NioSocketChannel.class)
                    .handler(new ChannelInitializer<SocketChannel>() {
                        @Override
                        protected void initChannel(SocketChannel ch) {
                            ch.pipeline().addLast(new StringDecoder());
                            ch.pipeline().addLast(new StringEncoder());
                            ch.pipeline().addLast(new EchoClientHandler());
                        }
                    });

            ChannelFuture future = bootstrap.connect(HOST, PORT).sync();
            future.channel().closeFuture().sync();

        } finally {
            group.shutdownGracefully();
        }
    }
}

运行方式

# 先启动服务器
mvn exec:java -Dexec.mainClass=com.osrepo.netty.guide.quickstart.HelloWorldServer

# 再启动客户端
mvn exec:java -Dexec.mainClass=com.osrepo.netty.guide.quickstart.HelloWorldClient

1.2 Java IO 演进 — BIO / NIO / AIO

模块定位：Netty 建立在 Java NIO 之上，理解 BIO → NIO → AIO 的演进历史，有助于深入理解 Netty 的设计哲学和性能优势。

BIO (Blocking IO) — 阻塞 I/O

BIO 是 Java 最早的 IO 模型，每个客户端连接需要一个独立线程处理：

import java.io.*;
import java.net.ServerSocket;
import java.net.Socket;

public class BioServer {
    private static final int PORT = 9090;

    public static void main(String[] args) throws IOException {
        ServerSocket server = new ServerSocket(PORT);
        while (true) {
            Socket client = server.accept();  // 阻塞等待连接
            new Thread(new BioHandler(client)).start();  // 每客户端一线程
        }
    }
}

特性	BIO
阻塞模式	是（accept/read/write 都阻塞）
线程模型	每连接一线程
并发能力	低（1000 连接 = 1000 线程）
适用场景	低并发、简单场景

NIO (Non-blocking IO) — 非阻塞 I/O

NIO 通过 Selector 多路复用器，单个线程可以管理多个连接：

import java.nio.channels.*;

public class NioServer {
    public static void main(String[] args) throws IOException {
        Selector selector = Selector.open();
        ServerSocketChannel serverChannel = ServerSocketChannel.open();
        serverChannel.configureBlocking(false);  // 关键：非阻塞模式
        serverChannel.bind(new InetSocketAddress(PORT));
        serverChannel.register(selector, SelectionKey.OP_ACCEPT);

        while (true) {
            selector.select();  // 阻塞等待事件
            for (SelectionKey key : selector.selectedKeys()) {
                if (key.isAcceptable()) { handleAccept(key, selector); }
                else if (key.isReadable()) { handleRead(key); }
                key.remove();  // 必须手动移除
            }
        }
    }
}

特性	NIO 三要素
Selector	多路复用器，监听多个 Channel 的事件
Channel	双向数据通道（BIO 的 Stream 是单向的）
Buffer	数据缓冲区（BIO 没有显式 Buffer）

AIO (Asynchronous IO / NIO.2) — 异步 I/O

AIO 由操作系统负责通知读写完成，通过回调处理：

import java.nio.channels.AsynchronousServerSocketChannel;
import java.nio.channels.CompletionHandler;

public class AioServer {
    public static void main(String[] args) throws IOException {
        AsynchronousServerSocketChannel server = AsynchronousServerSocketChannel.open();
        server.bind(new InetSocketAddress(PORT));
        server.accept(null, new AcceptCompletionHandler(server));
        Thread.currentThread().join();
    }
}

class AcceptCompletionHandler
        implements CompletionHandler<AsynchronousSocketChannel, Object> {
    @Override
    public void completed(AsynchronousSocketChannel client, Object attachment) {
        server.accept(null, this);  // 注册下一个连接回调
        ByteBuffer buffer = ByteBuffer.allocate(1024);
        client.read(buffer, buffer, new ReadCompletionHandler(client));
    }
}

对比	NIO	AIO
模型	轮询 (select) 检查就绪 → 主动查询	操作系统通知回调 → 被动回调
Linux 支持	优秀 (epoll)	差（无真正异步 Socket）
Netty 策略	Linux 上使用 Epoll 模拟 AIO 效果，Windows 上 AIO 性能较好

1.3 Reactor 线程模型

模块定位：Netty 默认采用「主从多线程 Reactor」模型，理解三种 Reactor 模型的演进是掌握 Netty 的核心。

单线程 Reactor

一个线程处理所有 I/O 事件 + 业务逻辑，适用于小并发场景：

// 单线程 Reactor：一个线程处理所有 I/O + 业务
Selector selector = Selector.open();
ServerSocketChannel server = ServerSocketChannel.open();
server.configureBlocking(false);
server.register(selector, SelectionKey.OP_ACCEPT);

while (true) {
    selector.select();
    for (SelectionKey key : selector.selectedKeys()) {
        if (key.isAcceptable()) {
            SocketChannel client = server.accept();
            client.register(selector, SelectionKey.OP_READ);
        } else if (key.isReadable()) {
            handleRead(key);  // 业务逻辑 + I/O 在同一线程
        }
    }
}

特性	单线程 Reactor
适用场景	小并发、简单场景
缺点	单点故障；业务逻辑阻塞会影响 I/O

多线程 Reactor（主从模型）

Boss 线程只接受连接，Worker 线程处理读写 + 业务逻辑：

// 主从 Reactor：Boss 接受，Worker 处理读写 + 业务
while (true) {
    selector.select();
    for (SelectionKey key : selector.selectedKeys()) {
        if (key.isAcceptable()) {
            SocketChannel client = server.accept();
            client.register(selector, SelectionKey.OP_READ);
        } else if (key.isReadable()) {
            handleReadWithThread(key);  // 交给工作线程处理
        }
    }
}

private static void handleReadWithThread(SelectionKey key) {
    new Thread(() -> {
        SocketChannel client = (SocketChannel) key.channel();
        // 业务逻辑在这里执行（不会阻塞 I/O 线程）
        client.write(buf, 0, n);
    }).start();
}

Netty 的 Reactor 实现

Netty 默认采用「主从多线程 Reactor」模型：

  ┌─────────────┐
  │   BossGroup  │  ← 多个线程（默认 CPU 核数 * 2）
  │  (Accept)   │     只负责 accept 新连接
  └──────┬──────┘
         │ 新连接
  ┌──────▼──────┐
  │  WorkerGroup  │  ← 多个线程（默认 CPU 核数）
  │ (Read/Write)  │     每个连接绑定到一个 EventLoop
  └──────────────┘

NettyReactorModel.java 展示了 Netty Reactor 的配置方式：

import io.netty.channel.nio.NioEventLoopGroup;

// BossGroup: 1 个线程处理连接
// WorkerGroup: CPU 核数个线程处理 I/O
NioEventLoopGroup bossGroup = new NioEventLoopGroup(1);
NioEventLoopGroup workerGroup = new NioEventLoopGroup();

// 配置示例：
// new NioEventLoopGroup(int nThreads)           // 指定线程数
// new NioEventLoopGroup(ThreadFactory)          // 自定义线程工厂
// new NioEventLoopGroup(int nThreads, Executor) // 自定义 Executor

关键特性	说明
连接绑定	一个 SocketChannel 只会被一个 EventLoop 处理
无锁化	单个 EventLoop 串行执行，无需同步
精准分配	EventLoop 内部无锁环形队列，高效处理事件
优雅关闭	shutdownGracefully() 等待所有任务完成

二、Netty 核心概念 — Channel & Pipeline

2.1 Channel 生命周期与 Pipeline

模块定位：Channel 是 Netty 网络操作的核心抽象，Pipeline 是 Handler 的载体。理解生命周期和管道编排是编写正确 Netty 应用的基础。

Channel 生命周期

  注册    → 激活    → 读入数据  → 写出数据  → 非激活  → 注销
  channelRegistered()
                    channelActive()
                                  channelInactive()
                                                    channelUnregistered()

ChannelLifecycleDemo.java 展示了生命周期监听器的实现：

import io.netty.channel.*;

static class LifecycleLoggerHandler extends ChannelInboundHandlerAdapter {

    @Override
    public void channelRegistered(ChannelHandlerContext ctx) {
        System.out.println("[Lifecycle] REGISTERED");
        ctx.fireChannelRegistered();
    }

    @Override
    public void channelActive(ChannelHandlerContext ctx) {
        System.out.println("[Lifecycle] ACTIVE");
        ctx.fireChannelActive();
    }

    @Override
    public void channelRead(ChannelHandlerContext ctx, Object msg) {
        System.out.println("[Lifecycle] READ");
        ctx.fireChannelRead(msg);
    }

    @Override
    public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) {
        System.out.println("[Lifecycle] EXCEPTION");
        ctx.close();
    }
}

Pipeline 执行流程

  Inbound 事件（从 Head 向 Tail 传递）:
    channelRead() → ... → channelReadComplete()

  Outbound 事件（从 Tail 向 Head 传递）:
    write() → ... → writeComplete()

Pipeline 编排示例

Handler 添加顺序决定了处理流程，顺序错误会导致协议解析失败：

// 错误示例：WebSocketServerProtocolHandler 在 HttpServerCodec 之前
pipeline.addLast("wsHandler", new WebSocketServerProtocolHandler("/ws"));
pipeline.addLast("codec", new HttpServerCodec());  // 太晚了！

// 正确顺序：先解码 HTTP，再处理 WebSocket
pipeline.addLast("codec", new HttpServerCodec());
pipeline.addLast("aggregator", new HttpObjectAggregator(65536));
pipeline.addLast("wsHandler", new WebSocketServerProtocolHandler("/ws"));
pipeline.addLast("handler", new MyWebSocketHandler());

正确管道配置（WebSocket 服务器）
Head → [SSL] → [HttpServerCodec] → [HttpObjectAggregator] → [WebSocketServerProtocolHandler] → [MyWebSocketHandler] → Tail

2.2 ByteBuf 内存管理

模块定位：ByteBuf 是 Netty 的数据容器，替代了 Java NIO 的 ByteBuffer。理解不同类型的 ByteBuf 和内存管理是高性能网络编程的关键。

ByteBuf 结构

  ┌──────────┬──────────────┬──────────┬──────────┐
  │discardable │  readable  │ unwritable │ discarding │
  │   bytes    │    bytes   │    bytes   │    bytes   │
  │          <──┴────────────┴───>        │
  │            readerIndex                │
  │                               writerIndex              │
  └──────────┴──────────────┴──────────┴──────────┘

ByteBufDemo.java 展示了 ByteBuf 的各种用法：

import io.netty.buffer.*;

// 堆内缓冲区 (HeapByteBuf) — 推荐
ByteBufAllocator allocator = PooledByteBufAllocator.DEFAULT;
ByteBuf buffer = allocator.buffer(256);
buffer.writeByte(0xde);
buffer.writeShort(0xcafe);
buffer.writeInt(0xbadface);
buffer.writeCharSequence("Netty", CharsetUtil.UTF_8);
// 读取
byte b = buffer.readByte();
short s = buffer.readShort();
buffer.release();  // 必须释放！

// 直接缓冲区 (DirectByteBuf) — 适合大文件 I/O
ByteBuf directBuffer = allocator.directBuffer(256);

// 复合缓冲区 (CompositeByteBuf) — 零拷贝合并
CompositeByteBuf composite = allocator.compositeBuffer();
composite.addComponent(buf1);
composite.addComponent(buf2);
// 无需拷贝，直接读取多个缓冲区的数据
composite.release();

ByteBuf 类型	存储位置	适用场景
HeapByteBuf	JVM 堆内存	小数据量，GC 友好
DirectByteBuf	堆外内存	网络 I/O，避免 JVM ↔ 内核拷贝
CompositeByteBuf	多个 ByteBuf 逻辑合并	零拷贝合并多个缓冲区

内存泄漏检测 (LeakDetector)

# JVM 启动参数：-Dio.netty.leakDetection.level=advanced

// 级别：
//   DISABLED    — 关闭检测（生产环境默认）
//   SIMPLE      — 简单检测（开销小）
//   ADVANCED    — 高级检测（推荐开发环境）
//   PARANOID    — 全检测（每次分配都检查，性能最差）

2.3 编解码基础 — 粘包/拆包处理

模块定位：TCP 是流式协议，没有消息边界。Netty 提供了四种帧解码器来解决粘包/拆包问题。

粘包/拆包问题

  发送方: [Message1][Message2]
  网络传输: [Message1][Messa|ge2]  ← 拆包
  接收方:   [Messag|e1][Message2]  ← 粘包

四种帧处理方案

FrameCodecDemo.java 展示了四种解决方案：

// 方案一：行分隔（适用于文本协议）
pipeline.addLast(new LineBasedFrameDecoder(65536));

// 方案二：自定义分隔符
ByteBuf delimiter = Unpooled.copiedBuffer("$_");
pipeline.addLast(new DelimiterBasedFrameDecoder(65536, delimiter));

// 方案三：固定长度
pipeline.addLast(new FixedLengthFrameDecoder(100));

// 方案四：长度字段帧解码器（工业级方案）⭐
pipeline.addLast(new LengthFieldBasedFrameDecoder(
    65536,    // maxFrameLength: 最大帧 64KB
    2,        // lengthFieldOffset: 长度字段从第 3 字节开始
    4,        // lengthFieldLength: 长度字段占 4 字节
    0,        // lengthAdjust: 长度不包含自身
    2         // initialBytesToSkip: 跳过 magic 数
));

自定义协议设计

  ┌─────────────┬──────────┬──────────────────────┐
  │  Magic(2B)  │ Length(4B) │    Payload(NB)       │
  │  0xABCD     │  0x00000064│    [实际数据]         │
  └─────────────┴──────────┴──────────────────────┘

// 手动编码：将协议组装为 ByteBuf
ByteBuf buffer = ByteBufAllocator.DEFAULT.buffer();
buffer.writeShort(0xABCD);       // Magic 数
buffer.writeInt(data.length);    // Payload 长度
buffer.writeBytes(data);         // Payload

// 手动解码：从 ByteBuf 提取协议内容
buffer.skipBytes(2);             // 跳过 Magic
int length = buffer.readInt();   // 读取长度
buffer.readBytes(data);          // 读取 Payload

解码器	适用场景	复杂度
LineBasedFrameDecoder	文本协议（Telnet、SMTP）	⭐
DelimiterBasedFrameDecoder	自定义分隔符	⭐⭐
FixedLengthFrameDecoder	定长协议	⭐
LengthFieldBasedFrameDecoder	工业级协议	⭐⭐⭐

三、常用编解码器 — 基础序列化

3.1 序列化方案对比

模块定位：网络传输需要字节序列，序列化是将对象转换为字节的过程。选择合适的序列化方案对性能和跨语言兼容性至关重要。

序列化方案对比

方案	性能	跨语言	体积	适用场景
Java Serializable	⭐⭐	❌	大	纯 Java 内部
Protobuf	⭐⭐⭐⭐	✅	小	高性能跨语言
JSON (Jackson)	⭐⭐	✅	中	Web API
Kryo	⭐⭐⭐⭐	❌	小	高性能纯 Java
MessagePack	⭐⭐⭐	✅	小	折中方案

Java 原生序列化

SerializationDemo.java 展示了 Java 原生序列化的实现：

import java.io.*;

static class User implements Serializable {
    private static final long serialVersionUID = 1L;
    private String name;
    private int age;

    byte[] serialize(User user) throws IOException {
        ByteArrayOutputStream baos = new ByteArrayOutputStream();
        try (ObjectOutputStream oos = new ObjectOutputStream(baos)) {
            oos.writeObject(user);
        }
        return baos.toByteArray();
    }

    User deserialize(byte[] bytes) throws IOException, ClassNotFoundException {
        try (ObjectInputStream ois = new ObjectInputStream(new ByteArrayInputStream(bytes))) {
            return (User) ois.readObject();
        }
    }
}

Protobuf 序列化（推荐 ⭐）

// .proto 定义示例：
// message Message {
//   required int32 id = 1;
//   required string content = 2;
//   optional int32 type = 3 [default = 0];
// }

// 编译后生成 Message.java，包含 Builder 模式：
Message msg = Message.newBuilder()
    .setId(1)
    .setContent("Hello")
    .setType(0)
    .build();

// Netty 管道中使用：
pipeline.addLast(new ProtobufEncoder());
pipeline.addLast(new ProtobufDecoder(Message.getDefaultInstance()));

序列化性能对比（参考值）

序列化方案	序列化耗时	反序列化耗时	序列化大小
Java	100ms	80ms	256 bytes
Protobuf	15ms	10ms	32 bytes
JSON	50ms	40ms	128 bytes
Kryo	10ms	8ms	48 bytes
MessagePack	12ms	9ms	40 bytes

3.2 XML / JSON 编解码

模块定位：XML 和 JSON 是最常用的两种数据交换格式，Netty 提供了内置的编解码器支持。

XML 编解码 (codec-xml)

// 管道配置：
pipeline.addLast(new XmlFrameDecoder(maxFrameLength));
pipeline.addLast(new XmlEncoder());
pipeline.addLast(new XmlDecoder());

// XML 消息示例：
<request>
  <id>123</id>
  <name>Netty</name>
  <type>framework</type>
</request>

JSON 编解码 (Jackson)

// 管道配置：
pipeline.addLast(new JsonFrameDecoder(maxFrameLength));
pipeline.addLast(new JsonEncoder());
pipeline.addLast(new JsonDecoder());

// JSON 消息示例：
{"id":123,"name":"Netty","type":"framework"}

// 自定义 JSON 序列化器：
ObjectMapper mapper = new ObjectMapper();
String json = mapper.writeValueAsString(object);
Object obj = mapper.readValue(json, Class);

特性	XML	JSON
可读性	⭐⭐⭐	⭐⭐⭐⭐
体积	大（标签冗余）	小
类型系统	强（XSD 约束）	弱
解析速度	慢	快
适用场景	企业级 API、配置文档	Web API、移动端

3.3 高级编解码器

模块定位：Netty 4.2 提供了丰富的编解码器模块，覆盖压缩、序列化、各种网络协议。

压缩编解码 (codec-compression)

// 管道配置：
pipeline.addLast(new Lz4Codec());           // LZ4 压缩
pipeline.addLast(new ZstdCodec());          // Zstandard 压缩
pipeline.addLast(new DeflateCodec());       // 标准 deflate
pipeline.addLast(new GzipCompressor);       // gzip 压缩

算法	压缩率	速度	适用场景
zstd	⭐⭐⭐⭐	⭐⭐	存储优化（Facebook 开源）
lz4	⭐⭐	⭐⭐⭐⭐	实时通信（速度最快）
deflate	⭐⭐⭐	⭐⭐⭐	通用场景
gzip	⭐⭐⭐	⭐⭐⭐	Web 传输

其他编解码器一览

模块名	协议/格式	用途
codec-marshalling	JBoss Marshalling	高性能序列化（比 Java 原生快，支持并发）
codec-redis	Redis Protocol	Redis 客户端/代理
codec-mqtt	MQTT	物联网 (IoT) 轻量级消息协议
codec-dns	DNS	自定义 DNS 服务器/客户端
codec-socks	SOCKS4/5	代理协议
codec-smtp	SMTP	邮件协议
codec-stomp	STOMP	消息队列（RabbitMQ）
codec-memcache	Memcache Protocol	缓存协议
codec-xml	XML (STAX)	XML 处理（流式）
codec-http3	HTTP/3 (QUIC)	下一代 Web 协议
codec-protobuf	Google Protobuf	高性能序列化
codec-haproxy	PROXY Protocol	负载均衡传递真实客户端信息

3.4 内置 Handler 家族

模块定位：Netty 提供了丰富的内置 Handler，覆盖日志、心跳、限速、压缩、SSL 等常见需求。

内置 Handler 一览

Handler	功能	方向
LoggingHandler	日志记录（开发调试利器）	In/Out
IdleStateHandler	空闲检测/心跳	In/Out
WriteRateHandler	写速率限制	Out
DeflateCodec / GzipCodec	压缩	In/Out
SslHandler	SSL/TLS 加密	In/Out
ProxyHandler	代理	In/Out
WebSocketServerProtocolHandler	WebSocket 握手	In/Out

心跳 Handler (IdleStateHandler)

// 管道配置：
pipeline.addLast(new IdleStateHandler(
    60,   // 读空闲超时 (秒)
    30,   // 写空闲超时 (秒)
    0     // 读写空闲超时 (秒)，0=不检测
));
pipeline.addLast(new HeartbeatHandler());

// 心跳 Handler 实现：
@Override
public void userEventTriggered(ChannelHandlerContext ctx, Object evt) {
    if (evt instanceof IdleStateEvent) {
        IdleStateEvent e = (IdleStateEvent) evt;
        if (e.state() == IdleState.WRITER_IDLE) {
            ctx.writeAndFlush(HeartbeatPacket.HEARTBEAT);  // 发送心跳包
        } else if (e.state() == IdleState.READER_IDLE) {
            ctx.close();  // 读空闲：客户端可能已断开
        }
    }
}

最佳管道顺序（从 Head 到 Tail）

  ┌─────────────────────────────────────────────────────┐
  │ 1. SslHandler          — SSL/TLS 加密              │
  │ 2. LoggingHandler      — 调试日志（开发环境）       │
  │ 3. IdleStateHandler    — 心跳检测                  │
  │ 4. FrameDecoder        — 帧解码（粘包/拆包）       │
  │ 5. Codec               — 编解码（JSON/Protobuf）   │
  │ 6. BusinessHandler     — 业务逻辑                  │
  └─────────────────────────────────────────────────────┘

四、网络协议实战 — TCP 协议

4.1 TCP 回显服务

模块定位：TCP 是最常用的传输层协议，回显服务是理解 TCP 网络编程的基础。

回显服务器

TcpProtocolDemo.java 展示了完整的 TCP 回显服务器：

import io.netty.bootstrap.ServerBootstrap;
import io.netty.channel.*;

ServerBootstrap bootstrap = new ServerBootstrap();
bootstrap.group(bossGroup, workerGroup)
        .channel(NioServerSocketChannel.class)
        .childHandler(new ChannelInitializer<SocketChannel>() {
            @Override
            protected void initChannel(SocketChannel ch) {
                ChannelPipeline pipeline = ch.pipeline();
                // 长度字段帧解码：4字节长度 + 数据
                pipeline.addLast(new LengthFieldBasedFrameDecoder(
                    65536, 0, 4, 0, 4));
                pipeline.addLast(new StringDecoder());
                pipeline.addLast(new StringEncoder());
                pipeline.addLast(new EchoHandler());
            }
        })
        .option(ChannelOption.SO_BACKLOG, 128)
        .childOption(ChannelOption.SO_KEEPALIVE, true)
        .childOption(ChannelOption.TCP_NODELAY, true)
        .bind(8080)
        .sync();

文件传输（零拷贝）

// 使用 FileRegion 零拷贝传输文件
FileRegion file = new DefaultFileRegion(file, 0, fileLength);
ctx.write(file);
ctx.writeAndFlush(Unpooled.EMPTY_BUFFER);

长连接 vs 短连接

特性	长连接	短连接
建立连接	一次，持续使用	每次请求新建
性能	高（无握手开销）	低（频繁握手）
适用场景	即时通讯、游戏、RPC	HTTP 1.0
断线处理	需要心跳保活	无需处理

TCP 参数调优

ChannelOption	推荐值	说明
SO_BACKLOG	128	连接等待队列长度
SO_KEEPALIVE	true	TCP 心跳保活
TCP_NODELAY	true	禁用 Nagle 算法
SO_RCVBUF	65536	接收缓冲区大小
SO_SNDBUF	65536	发送缓冲区大小

4.2 UDP 协议

模块定位：UDP 是无连接协议，速度快但不可靠。适用于视频流、DNS 查询、游戏等场景。

UDP 回显服务器

UdpProtocolDemo.java 展示了 UDP 服务器的实现：

import io.netty.bootstrap.Bootstrap;
import io.netty.channel.socket.DatagramChannel;
import io.netty.channel.socket.nio.NioDatagramChannel;

Bootstrap bootstrap = new Bootstrap();
bootstrap.group(group)
        .channel(NioDatagramChannel.class)
        .option(ChannelOption.SO_BROADCAST, true)  // 支持广播
        .handler(new ChannelInitializer<DatagramChannel>() {
            @Override
            protected void initChannel(DatagramChannel ch) {
                ch.pipeline().addLast(new UdpEchoHandler());
            }
        })
        .bind(9090)
        .sync();

特性	TCP	UDP
连接	面向连接	无连接
可靠性	可靠（重传/排序）	不可靠
顺序	有序	无序
速度	较慢（握手/确认）	快
适用场景	HTTP、RPC、文件传输	视频流、DNS、游戏

4.3 HTTP / WebSocket

模块定位：HTTP 是 Web 的基础协议，WebSocket 提供了全双工通信能力，适用于实时聊天、推送等场景。

HTTP 服务器

// HTTP 管道配置：
pipeline.addLast(new HttpServerCodec());           // HTTP 编解码
pipeline.addLast(new HttpObjectAggregator(65536));  // 分块传输聚合
pipeline.addLast(new HttpHandler());               // 业务处理

// 创建响应：
FullHttpResponse response = new DefaultFullHttpResponse(
    HttpVersion.HTTP_1_1,
    HttpResponseStatus.OK,
    Unpooled.copiedBuffer("Hello, HTTP!", CharsetUtil.UTF_8)
);
response.headers().set(HttpHeaderNames.CONTENT_TYPE, "text/plain");
response.headers().set(HttpHeaderNames.CONTENT_LENGTH, response.content().readableBytes());

WebSocket 聊天室

// WebSocket 管道配置：
pipeline.addLast(new HttpServerCodec());
pipeline.addLast(new HttpObjectAggregator(65536));
pipeline.addLast(new WebSocketServerProtocolHandler("/ws"));
pipeline.addLast(new WebSocketChatHandler());

// 聊天 Handler：群聊实现
private static final ChannelGroup channels = new DefaultChannelGroup(GlobalEventExecutor.INSTANCE);

@Override
public void channelActive(ChannelHandlerContext ctx) {
    channels.add(ctx.channel());
    broadcast("New user: " + ctx.channel().id());
}

private void broadcast(String text) {
    channels.forEach(ch ->
        ch.writeAndFlush(new TextWebSocketFrame("[Server] " + text))
    );
}

特性	HTTP	WebSocket
通信模式	请求-响应	全双工
方向	客户端 → 服务器	双向
握手	HTTP 请求	HTTP 升级
适用场景	REST API、页面加载	实时聊天、游戏、推送

4.4 HTTP/2 & HTTP/3 (QUIC)

模块定位：HTTP/2 和 HTTP/3 是新一代 Web 协议，Netty 4.2 提供了完整支持。

HTTP/2 核心特性

特性	说明
多路复用 (Multiplexing)	一个连接多个请求，无需多个 TCP 连接
二进制分帧	更高效的协议格式
头部压缩 (HPACK)	减少传输体积
服务器推送 (Server Push)	主动推送资源到客户端
请求优先级	控制资源分配

// HTTP/2 管道配置：
pipeline.addLast(new Http2Codec());
pipeline.addLast(new Http2ConnectionHandler(connection));
pipeline.addLast(new Http2ServerHandler());

// 多路复用：一个 TCP 连接同时处理多个 HTTP 请求
// 流 ID: 1, 3, 5, 7... (客户端) / 0, 2, 4, 6... (服务端)

HTTP/3 (QUIC) — Netty 4.2 新特性 ⭐

特性	TCP (HTTP/2)	QUIC (HTTP/3)
传输层	TCP	UDP
握手延迟	3-way + TLS (2RTT)	0-RTT / 1-RTT
队头阻塞	有 (TCP 层)	无 (流级别)
连接迁移	不支持	支持 (Connection ID)
浏览器支持	✅ (所有)	✅ (Chrome/FF)

HTTP 版本演进

版本	年份	关键特性	传输层
HTTP/0	1996	基础请求-响应	TCP
HTTP/1.0	1996	Keep-Alive	TCP
HTTP/1.1	1997	Pipeline, Chunked, Caching	TCP
HTTP/2	2015	多路复用, 头部压缩, 服务器推送	TCP
HTTP/3	2022	无队头阻塞, 0-RTT, 连接迁移	QUIC

4.5 SSL/TLS 安全通信

模块定位：SSL/TLS 是网络安全的基石，Netty 提供了完整的 SSL 支持。

TLS 版本对比

版本	安全性	状态
SSL 3.0	❌	已废弃 (POODLE 攻击)
TLS 1.0	❌	已废弃 (PCI DSS 不合规)
TLS 1.1	❌	已废弃
TLS 1.2	✅	广泛使用
TLS 1.3	✅✅	推荐 ⭐

单向认证配置

// 管道配置：
SSLContext ctx = SSLContext.getInstance("TLSv1.3");
KeyStore ks = KeyStore.getInstance("PKCS12");
ks.load(new FileInputStream("server.p12"), "password".toCharArray());
KeyManagerFactory kmf = KeyManagerFactory.getInstance("SunX509");
kmf.init(ks, "password".toCharArray());
ctx.init(kmf.getKeyManagers(), null, null);
pipeline.addLast(new SslHandler(ctx.createSSLEngine()));

双向认证 (mTLS) — 推荐 ⭐

// mTLS 配置：
SSLContext ctx = SSLContext.getInstance("TLSv1.3");
// 服务器密钥
KeyStore serverKs = KeyStore.getInstance("PKCS12");
serverKs.load(new FileInputStream("server.p12"), "password".toCharArray());
// 客户端信任库
KeyStore trustStore = KeyStore.getInstance("JKS");
trustStore.load(new FileInputStream("truststore.jks"), "password".toCharArray());
ctx.init(
    KeyManagerFactory.getInstance("SunX509").init(serverKs, "password"),
    TrustManagerFactory.getInstance("SunX509").init(trustStore),
    null);
SSLEngine engine = ctx.createSSLEngine();
engine.setNeedClientAuth(true);  // 需要客户端认证
pipeline.addLast(new SslHandler(engine));

证书生成命令

# 生成自签名证书 (开发环境)
keytool -genkeypair -alias server -keyalg EC -keysize 256 \
        -keystore server.p12 -storetype PKCS12 -validity 3650

# 生成 CA 证书
keytool -genkeypair -alias ca -keyalg EC -keysize 256 \
        -keystore ca.p12 -storetype PKCS12

# 生成客户端证书
keytool -genkeypair -alias client -keyalg EC -keysize 256 \
        -keystore client.p12 -storetype PKCS12

4.6 其他协议

模块定位：Netty 支持多种常用网络协议，覆盖代理、邮件、消息队列、缓存等场景。

协议	端口	用途	Netty 模块
SOCKS4/5	1080	代理	codec-socks
SMTP	25/587	邮件	codec-smtp
STOMP	61613	消息队列 (RabbitMQ)	codec-stomp
Memcache	11211	缓存	codec-memcache
Redis	6379	缓存	codec-redis
MQTT	1883	IoT 消息	codec-mqtt
DNS	53	域名解析	codec-dns
HTTP/1	80/443	Web	codec-http
HTTP/2	443	高性能 Web	codec-http2
HTTP/3	443	下一代 Web	codec-http3

五、高级特性 (Netty 4.2) — 原生传输

5.1 io_uring / epoll / kqueue 原生传输

模块定位：Netty 4.2 引入了对 Linux io_uring、epoll 和 macOS/iOS kqueue 的原生传输支持，大幅提升高性能场景下的 I/O 性能。

传输方式对比

传输方式	平台	性能	说明
NIO (NioServerSocketChannel)	跨平台	⭐⭐	默认，兼容所有平台
Epoll (EpollServerSocketChannel)	Linux	⭐⭐⭐	Linux epoll，零拷贝
kqueue (KQueueServerSocketChannel)	macOS/iOS	⭐⭐⭐	macOS/iOS kqueue
io_uring (IoUringServerSocketChannel)	Linux 5.1+	⭐⭐⭐⭐	新一代异步 I/O（Netty 4.2 新特性）

Epoll 配置示例

import io.netty.channel.epoll.EpollServerSocketChannel;
import io.netty.channel.epoll.EpollEventLoopGroup;

// Linux 平台使用 Epoll 原生传输
ServerBootstrap bootstrap = new ServerBootstrap();
bootstrap.group(new EpollEventLoopGroup())
        .channel(EpollServerSocketChannel.class)
        .childHandler(new ChannelInitializer<SocketChannel>() {
            @Override
            protected void initChannel(SocketChannel ch) {
                ch.pipeline().addLast(new MyHandler());
            }
        })
        .bind(8080);

5.2 QUIC 支持

模块定位：QUIC (Quick UDP Internet Connections) 是 Google 提出的新一代传输协议，Netty 4.2 提供了完整的 QUIC 支持。

QUIC vs TCP 对比

特性	TCP	QUIC
握手延迟	3-way handshake + TLS (2RTT)	0-RTT / 1-RTT
队头阻塞	有（连接级别）	无（流级别隔离）
连接迁移	IP 变化需重建连接	Connection ID 支持无缝迁移
加密	TLS 可选	QUIC 层强制 TLS 1.3

Netty 4.2 QUIC 配置

// 需要添加 netty-codec-native-quic 依赖
// 配合 codec-http3 使用
pipeline.addLast(new QuicCodec());
pipeline.addLast(new Http3Codec());

5.3 性能调优

模块定位：Netty 性能调优涉及内存管理、线程配置、参数设置等多个方面。

ByteBuf 性能优化

优化手段	效果
PooledByteBufAllocator	内存池化，减少 GC 压力（推荐）
DirectBuffer	堆外内存，避免 JVM ↔ 内核拷贝
CompositeByteBuf	零拷贝合并多个缓冲区
LeakDetector (ADVANCED)	开发环境检测内存泄漏

SSL 性能优化

优化手段	效果
SSLSessionCache	复用会话，减少握手
AlignedBufferAllocator	对齐内存，提升加解密
OpenSSLEngine	OpenSSL 原生实现（更快）
TLS 1.3	减少握手往返 (0-RTT)

线程配置建议

场景	BossGroup	WorkerGroup
一般 Web 服务	1	CPU 核数 * 2
高并发长连接	CPU 核数	CPU 核数 * 4
I/O 密集型	1	CPU 核数 * 2 ~ 4
CPU 密集型	1	CPU 核数 + 1

六、工程化与生态 — RPC 框架实现

6.1 基于 Netty 的 RPC 框架

模块定位：Netty 是构建高性能 RPC 框架的首选网络层方案。Dubbo、gRPC-Java 等知名 RPC 框架都使用 Netty 作为默认传输层。

RPC 框架核心组件

组件	职责
Netty 传输层	处理 TCP 连接、心跳、重连
序列化器	对象 ↔ 字节序列（Protobuf 推荐）
协议编解码	自定义 RPC 协议（魔数 + 版本 + 序列号 + 数据）
服务注册中心	Zookeeper / Nacos / Consul
负载均衡	RoundRobin、Random、LeastConnections
容错机制	重试、熔断、降级

RPC 协议设计

  ┌─────────────┬──────────┬──────────┬──────────┬──────────────┐
  │ Magic(2B)   │ Version  │ SequenceId │ Type     │ Payload(NB)  │
  │ 0xDEAD      │ 1B       │ 4B         │ 1B       │ [实际数据]   │
  └─────────────┴──────────┴──────────┴──────────┴──────────────┘

6.2 Spring Boot 集成

模块定位：将 Netty 服务集成到 Spring Boot 生态，实现自动配置、依赖注入和监控。

Spring Boot 自动配置

集成方式	说明
spring-boot-starter-webflux	Spring WebFlux 内置 Netty 作为默认服务器
自定义 Starter	封装 Netty 服务器为 Spring Bean
Netty AutoConfiguration	自动配置端口、线程数、Handler

自定义 Netty Starter

// META-INF/spring.factories 或 org.springframework.boot.autoconfigure.AutoConfiguration
// 自动配置类：

@Configuration
@EnableConfigurationProperties(NettyProperties.class)
public class NettyAutoConfiguration {

    @Bean
    public NettyServer nettyServer(NettyProperties properties) {
        return new NettyServer(properties.getPort());
    }

    @Bean
    public ApplicationListener<ContextClosedEvent> shutdownHook(NettyServer server) {
        return event -> server.shutdown();
    }
}

6.3 响应式编程

模块定位：Netty 4.2 与 Project Reactor 深度集成，支持响应式编程模型。

Netty + Reactor 集成

特性	说明
Flux/Mono API	Netty 响应式 HTTP 服务器提供 Flux/Mono API
背压支持	响应式流天然支持背压 (Backpressure)
非阻塞	全链路非阻塞，高吞吐低延迟
错误处理	响应式错误处理（onErrorResume、onErrorReturn）

6.4 gRPC 原理

模块定位：gRPC 是 Google 开源的高性能 RPC 框架，底层使用 Netty 作为可选传输层。

gRPC 架构

层级	技术
传输层	HTTP/2（Netty 实现）
序列化	Protobuf
服务定义	.proto 文件
特性	双向流式、服务端流、客户端流、全双工

6.5 中间件中的 Netty

模块定位：Netty 被广泛应用于各种中间件和框架中。

中间件	Netty 用途
Dubbo	默认网络传输层（TCP 长连接）
RocketMQ	RPC 通信层
Elasticsearch	节点间通信 (Netty4 传输)
RabbitMQ	AMQP 协议处理（3.0+）
Zookeeper	新版使用 Netty 替代 Apache MINA
Redis (Jedis/Lettuce)	Lettuce 客户端使用 Netty
Kafka (KafkaClient)	新版客户端使用 Netty
MongoDB (MongoClient)	MongoDB Java 驱动使用 Netty

6.6 测试与调试

模块定位：Netty 应用的测试和调试技巧。

测试策略

测试类型	工具/方法
单元测试	EmbeddedChannel（内嵌 Channel，无需真实网络）
集成测试	启动真实 Netty 服务器，使用 JUnit + Testcontainers
压力测试	JMeter / wrk / ab 压测
性能分析	jstack / jmap / Arthas / Async-Profiler

EmbeddedChannel 测试示例

import io.netty.channel.embedded.EmbeddedChannel;

@Test
public void testEchoHandler() {
    EmbeddedChannel channel = new EmbeddedChannel(
        new LengthFieldBasedFrameDecoder(65536, 0, 4, 0, 4),
        new StringDecoder(),
        new EchoHandler()
    );

    channel.writeInbound(Unpooled.copiedBuffer("Hello", CharsetUtil.UTF_8));
    String result = channel.readInbound();
    assertEquals("Hello", result);

    assertThat(channel.finish(), is(true));
}

6.7 常见问题与最佳实践

模块定位：Netty 开发中常见问题的解决方案和最佳实践总结。

常见问题 (FAQ)

问题	原因	解决方案
内存泄漏	ByteBuf 未释放	使用 LeakDetector，确保 release()
线程阻塞	业务逻辑在 IO 线程执行	使用 EventExecutorGroup 切换业务线程池
粘包/拆包	TCP 流式特性	使用 LengthFieldBasedFrameDecoder
连接泄漏	未正确关闭 Channel	在 channelInactive 中清理资源
死锁	Handler 间互相等待	避免跨 Channel 同步操作
大文件传输 OOM	一次性加载大文件到内存	使用 FileRegion 零拷贝

最佳实践清单

#	最佳实践
1	使用 PooledByteBufAllocator（默认已启用）
2	开发环境开启 -Dio.netty.leakDetection.level=ADVANCED
3	业务逻辑不要放在 IO 线程，使用 EventExecutorGroup 切换线程池
4	使用 LengthFieldBasedFrameDecoder 处理粘包/拆包
5	使用 IdleStateHandler 实现心跳保活
6	使用 ChannelGroup 管理批量 Channel（如 WebSocket 群聊）
7	优雅关闭：shutdownGracefully() 等待所有任务完成
8	异常处理：exceptionCaught 中记录日志并关闭 Channel
9	大文件传输使用 FileRegion 零拷贝
10	序列化优先选择 Protobuf（高性能 + 跨语言）