Netty：ByteBuf 与内存管理原理

一、ByteBuf 是什么

ByteBuf 是 Netty
提供的字节缓冲区抽象，用于保存网络通信中的入站数据和出站数据。TCP
传输的是字节流，Netty 收到数据后，通常会将数据放入 ByteBuf，再交给
Pipeline 中的解码器和业务 Handler 处理。

@Override
public void channelRead(ChannelHandlerContext ctx, Object msg) {
    try {
        ByteBuf buf = (ByteBuf) msg;
        while (buf.isReadable()) {
            System.out.println(buf.readByte());
        }
    } finally {
        // 当前 Handler 消费消息且不再向下传递时，负责释放
        ReferenceCountUtil.release(msg);
    }
}

ByteBuf
不只是字节数组包装类，还提供独立读写索引、容量管理、派生缓冲区和引用计数等能力。

二、ByteBuf 与 ByteBuffer 的区别

Java NIO 的 ByteBuffer 使用 position 和 limit
管理读写位置，通常通过 flip() 在写模式和读模式之间切换。

Netty 的 ByteBuf 使用两个独立索引：

readerIndex：下一次读取数据的位置。
writerIndex：下一次写入数据的位置。
capacity：当前缓冲区容量。

对比项 Java NIO ByteBuffer Netty ByteBuf

读写位置 position、limit readerIndex、writerIndex

读写模式通常通过 flip() 切换读写索引独立，不需要 flip()

容量创建后固定部分实现支持动态扩容

引用计数不提供 Netty 式引用计数支持引用计数

派生视图 slice()、duplicate() slice()、duplicate()、retainedSlice()
等

内存分配堆内或直接内存支持堆内、直接内存及池化分配器

核心区别：ByteBuffer 通常通过一个 position 配合 limit
管理读写状态；ByteBuf 将读索引和写索引分开管理。

三、ByteBuf 的核心索引

1. 内存布局

假设创建一个容量为 10 字节的缓冲区，并写入 5 个字节：

ByteBuf buf = Unpooled.buffer(10);

buf.writeByte(10);
buf.writeByte(20);
buf.writeByte(30);
buf.writeByte(40);
buf.writeByte(50);

此时：

readerIndex = 0
writerIndex = 5
capacity    = 10

逻辑布局：

已读取区域       可读取区域          可写区域
[             | 10 20 30 40 50 |  _  _  _  _  _ ]
              0                5              10
              readerIndex      writerIndex

2. 读取与写入

buf.readByte();       // 读取一个字节，readerIndex + 1
buf.writeByte(100);   // 写入一个字节，writerIndex + 1

buf.getByte(0);       // 读取指定下标，不改变 readerIndex
buf.setByte(0, 100);  // 修改指定下标，不改变 writerIndex

readXxx()：读取数据，并移动 readerIndex。
getXxx(index)：按指定下标读取，不移动读索引。
writeXxx()：写入数据，并移动 writerIndex。
setXxx(index, value)：修改指定下标，不移动写索引。

3. 可读和可写字节数

int readable = buf.readableBytes();
int writable = buf.writableBytes();

计算关系：

readableBytes = writerIndex - readerIndex
writableBytes = capacity - writerIndex

例如：

readerIndex = 2
writerIndex = 5
capacity    = 10

readableBytes = 3
writableBytes = 5

协议解析时，可以先判断剩余可读字节是否足够：

if (buf.readableBytes() < 4) {
    return;
}

注意：这段判断只适用于当前缓冲区已经包含完整解析上下文的情况。自定义解码器必须正确保留或累积不完整数据，不能简单丢弃半包数据。

4. 索引边界

通常需要满足：

0 <= readerIndex <= writerIndex <= capacity

读取数据前应检查 isReadable() 或 readableBytes()，避免越界读取。

四、堆内存与直接内存

Netty 的 ByteBuf 可以使用堆内存或直接内存。

1. 堆内存

ByteBuf buf = Unpooled.buffer(1024);

堆内存位于 JVM 管理的 Java 堆中。

特点：

分配和访问方式与普通 Java 对象相近。
由 JVM 垃圾回收器管理底层堆内存。
在某些 Socket IO
路径中，可能需要将堆内数据复制到直接缓冲区后再交给原生 IO。

2. 直接内存

ByteBuf buf = Unpooled.directBuffer(1024);

直接内存位于普通 Java 堆之外，通过 ByteBuffer.allocateDirect()
等机制分配。

特点：

不属于普通 Java 堆的数据存储区域。
在某些网络 IO 场景中，可以减少堆内存与原生 IO 缓冲区之间的额外复制。
分配、释放成本通常较高，常与内存池配合使用。
直接内存使用量需要单独监控，不能只看 Java Heap。

注意：直接内存不等于完全零拷贝。数据在用户态和内核态之间传输时，仍可能发生复制。

3. 如何选择

不应简单认为直接内存永远优于堆内存。应结合数据处理方式、IO
路径、分配频率和性能测试决定。

对于 Netty 网络通信，通常优先通过当前 Channel 的分配器申请缓冲区：

ByteBuf buf = ctx.alloc().buffer(1024);

这样可以遵循当前 Channel
配置的分配器策略，而不是在业务代码中到处硬编码堆内或直接内存。

五、内存池化

频繁创建和释放缓冲区会带来分配与回收开销。内存池的核心思路是复用已经分配的内存：

申请内存
   ↓
使用 ByteBuf
   ↓
release()
   ↓
内存归还分配器 / 内存池
   ↓
后续分配时复用

示例：

ByteBuf buf = ctx.alloc().buffer(1024);

try {
    buf.writeInt(100);
    // 处理数据
} finally {
    buf.release();
}

注意：

release()
表示当前持有者释放引用，不代表底层内存一定立即归还操作系统。
池化分配器可能把内存保留起来供后续复用。
Netty
不同版本的默认分配器策略可能不同，不能把某个版本的默认行为当成所有版本的固定规则。
是否启用池化、使用哪种分配器，应结合 Netty
版本、配置和压测结果确认。

六、引用计数机制

1. 什么是引用计数

许多 Netty ByteBuf
实现支持引用计数。引用计数表示当前有多少个持有者仍在使用这块资源。

常用方法：

buf.refCnt();  // 查看引用计数
buf.retain();  // 增加引用计数
buf.release(); // 减少引用计数

普通新分配的引用计数 ByteBuf，初始引用计数通常为 1。

ByteBuf buf = Unpooled.buffer(10);

System.out.println(buf.refCnt()); // 1

buf.retain();
System.out.println(buf.refCnt()); // 2

buf.release();
System.out.println(buf.refCnt()); // 1

buf.release();
System.out.println(buf.refCnt()); // 0

引用计数降到 0 后，该缓冲区不应再被访问。继续访问或重复释放可能抛出：

io.netty.util.IllegalReferenceCountException

2. retain() 与 release()

retain()：表示增加一个持有引用。
release()：表示当前持有者不再使用该资源。
当引用计数降到 0，底层资源被释放，或归还给池化分配器。

不要机械地把 retain() 和 release()
理解成任意位置的一对调用。关键是明确资源所有权：谁取得额外引用，谁就需要在使用结束后释放该引用。

3. ChannelInboundHandlerAdapter 的释放规则

如果当前 Handler 消费消息且不再向下传递，通常由当前 Handler
负责释放引用计数对象：

@Override
public void channelRead(ChannelHandlerContext ctx, Object msg) {
    try {
        ByteBuf buf = (ByteBuf) msg;

        while (buf.isReadable()) {
            System.out.println(buf.readByte());
        }
    } finally {
        ReferenceCountUtil.release(msg);
    }
}

如果当前 Handler 将消息继续传递给下一个 Handler：

@Override
public void channelRead(ChannelHandlerContext ctx, Object msg) {
    ctx.fireChannelRead(msg);
}

此时通常是把消息所有权继续传递给下游，当前 Handler
不应再无条件释放同一条消息，否则下游可能访问已释放对象。

如果在传递前还需要自己保留一份引用，应明确调用
retain()，并保证额外引用最终得到释放。

4. SimpleChannelInboundHandler 的自动释放

public class MessageHandler
        extends SimpleChannelInboundHandler<ByteBuf> {

    @Override
    protected void channelRead0(
            ChannelHandlerContext ctx,
            ByteBuf msg) {

        System.out.println(msg.readableBytes());
    }
}

SimpleChannelInboundHandler
默认会在处理完成后自动释放匹配类型的引用计数消息。因此通常不需要再手动调用
msg.release()。

如果需要将消息交给异步线程处理，不能直接把即将自动释放的 msg
交出去。可以选择：

将需要的数据复制成 byte[] 或其他独立对象，再交给异步任务。
在异步任务使用前正确 retain()，并在异步任务结束时 release()。

七、slice()、duplicate() 与 copy()

这几个方法常用于协议解析和数据切片。

方法是否共享底层数据是否复制数据是否增加引用计数

slice() 是否否
duplicate() 是否否
copy() 否是新建独立缓冲区
retainedSlice() 是否是
retainedDuplicate() 是否是

1. slice()

slice() 创建原 ByteBuf 某一段区域的视图，不复制底层数据。

ByteBuf original =
        Unpooled.wrappedBuffer(new byte[]{10, 20, 30, 40});

try {
    ByteBuf slice = original.slice(1, 2);

    System.out.println(slice.getByte(0)); // 20

    slice.setByte(0, 99);

    System.out.println(original.getByte(1)); // 99
} finally {
    original.release();
}

原始数据发生变化，是因为两个 ByteBuf 共享底层内存。

普通 slice() 不增加引用计数，不能在原始 ByteBuf 已释放后继续安全使用。

2. duplicate()

duplicate() 创建一个共享全部底层数据的视图，但具有独立的读写索引。

修改其中的数据内容，会影响另一个视图；移动一个视图的 readerIndex 或
writerIndex，不会同步改变另一个视图的索引。

普通 duplicate() 不增加引用计数。

3. copy()

copy() 会复制数据，创建独立的缓冲区：

ByteBuf original =
        Unpooled.wrappedBuffer(new byte[]{10, 20, 30});

ByteBuf copied = original.copy();

try {
    copied.setByte(0, 99);

    System.out.println(original.getByte(0)); // 10
    System.out.println(copied.getByte(0));   // 99
} finally {
    copied.release();
    original.release();
}

修改 copied 不会影响 original，但复制会产生额外内存和 CPU 开销。

4. retainedSlice()

如果需要将一段共享数据交给其他组件或异步任务继续使用，可以考虑：

ByteBuf part = original.retainedSlice(0, 4);

它会增加共享引用计数，使派生视图在原始持有者释放后仍可继续使用。

使用完成后必须释放：

part.release();

八、生产环境中的 ByteBuf 内存泄漏

1. 常见原因

使用 ChannelInboundHandlerAdapter 消费消息后忘记释放。
调用 retain() 后没有在合适时机释放。
将 ByteBuf 交给异步线程，但没有正确管理引用计数。
对 SimpleChannelInboundHandler 自动释放的消息再次手动释放。
使用普通 slice() 或
duplicate()，却误以为它们拥有独立内存或独立生命周期。

2. 错误示例

@Override
public void channelRead(ChannelHandlerContext ctx, Object msg) {
    ByteBuf buf = (ByteBuf) msg;

    byte[] bytes = new byte[buf.readableBytes()];
    buf.readBytes(bytes);

    // 消息已经消费，但忘记释放
}

如果当前 Handler 不再向下传递消息，就可能造成引用计数泄漏。

3. 推荐写法

@Override
public void channelRead(ChannelHandlerContext ctx, Object msg) {
    try {
        ByteBuf buf = (ByteBuf) msg;

        byte[] bytes = new byte[buf.readableBytes()];
        buf.readBytes(bytes);

        // 使用独立的 byte[] 处理数据
        process(bytes);

    } finally {
        ReferenceCountUtil.release(msg);
    }
}

这里将需要的数据复制到独立的 byte[]，随后释放
ByteBuf。复制后的数组不依赖原 ByteBuf 的生命周期。

4. 开启内存泄漏检测

JVM 启动参数：

-Dio.netty.leakDetection.level=advanced

常见等级：

等级说明

DISABLED 禁用检测
SIMPLE 抽样检测
ADVANCED 抽样检测并记录更多访问线索
PARANOID 尽可能检查每次分配，开销较大

排查时可以临时提高检测等级。PARANOID
检测开销较大，不建议未经评估就长期用于高吞吐生产环境。

5. 排查思路

查看 Netty 是否输出 LEAK: ByteBuf.release() was not called
等泄漏提示。
检查 ChannelInboundHandlerAdapter 中消息是否被正确释放或传递。
检查 retain()、release() 是否与资源所有权匹配。
检查异步任务是否访问已经自动释放的消息。
同时观察 JVM 堆、直接内存、进程 RSS 和 Netty
分配器指标，区分真实泄漏与内存池保留内存。

九、生产开发建议

优先通过 ctx.alloc() 分配 ByteBuf，遵循当前 Channel 的分配器配置。
消费消息后，要么正确释放，要么继续向下游传递，明确所有权。
使用 SimpleChannelInboundHandler 时，牢记默认自动释放规则。
不要把普通 slice()、duplicate() 当成独立副本。
跨线程使用 ByteBuf
时，优先考虑复制必要数据；确需共享时，正确管理引用计数。
不要为了减少复制而滥用 retain()，否则会增加生命周期管理复杂度。
发生直接内存不足时，不要只检查 JVM Heap，还要检查直接内存和 Netty
内存池指标。
性能优化应以压测数据为依据，不要仅凭"直接内存更快"或"池化一定更好"作判断。

十、重点总结

知识点核心结论

ByteBuf Netty 的字节缓冲区抽象
readerIndex 下一次读取的位置
writerIndex 下一次写入的位置
readByte() 读取并移动读索引
getByte() 按下标读取，不移动读索引
HeapByteBuf 使用堆内存
DirectByteBuf 使用直接内存
内存池化复用已分配内存，减少分配开销
refCnt() 查看引用计数
retain() 增加引用计数
release() 减少引用计数
slice() 共享底层数据的局部视图
duplicate() 共享底层数据的完整视图
copy() 创建独立的数据副本
retainedSlice() 创建共享数据且增加引用计数的视图

十一、常见问题与答案

1. ByteBuf 为什么不需要 flip()？

因为 ByteBuf 使用独立的 readerIndex 和 writerIndex
管理读写位置，不需要像 ByteBuffer 那样通过 position 和 limit
切换读写模式。

2. ByteBuf 的 release() 是不是直接释放 JVM 内存？

不一定。引用计数归零表示当前 ByteBuf
不再被持有。若使用池化分配器，底层内存通常会归还给内存池供后续复用，不一定立即归还操作系统。

3. slice() 和 copy() 有什么区别？

slice() 共享底层数据，不复制内容；copy() 创建独立的数据副本。普通
slice() 不增加引用计数。

4. 为什么异步使用 ByteBuf 需要特别注意？

因为当前 Handler
可能在异步任务执行之前就释放原始消息，导致异步线程访问已释放的
ByteBuf。需要复制数据，或者正确增加引用计数并在异步任务完成后释放。

5. SimpleChannelInboundHandler 是否需要手动 release()？

默认情况下，它会自动释放匹配类型且被消费的引用计数消息。通常不需要再次手动释放，否则可能发生重复释放。

6. 直接内存是不是完全没有数据复制？

不是。直接内存可能减少某些堆缓冲区到原生 IO
缓冲区之间的复制，但不代表网络通信全过程没有数据复制。

7. 内存池中的 ByteBuf release() 后，内存会立即归还操作系统吗？

通常不会。池化分配器可能保留底层内存，以便后续分配复用。因此进程内存没有立即下降，不一定意味着发生了泄漏。

十二、学习测试

问题 1

ByteBuf 当前
readerIndex = 2、writerIndex = 6、capacity = 10。执行一次
readByte() 后，三个属性分别是多少？

答案：

readerIndex = 3
writerIndex = 6
capacity = 10

原因：readByte() 只移动 readerIndex。

问题 2

一个 ByteBuf 初始 refCnt = 1，依次执行
retain()、release()，最终引用计数是多少？

答案：

refCnt = 1

原因：先从 1 增加到 2，再从 2 减少到 1。

问题 3

在默认自动释放的 SimpleChannelInboundHandler<ByteBuf>
中，需要将消息交给异步任务处理，应该注意什么？

答案：

不能直接把即将自动释放的原始 ByteBuf
交给异步线程。可以复制需要的数据后异步处理，或者在异步任务使用前正确
retain()，并确保任务结束后 release()。

本篇核心结论：

ByteBuf
的关键不只是读写数据，而是理解独立读写索引、内存分配方式和引用计数生命周期。生产环境中，尤其要明确消息由谁持有、由谁释放，以及异步任务是否仍在使用该缓冲区。

Cloud_Drift's Blog

Netty：ByteBuf 与内存管理原理

一、ByteBuf 是什么

二、ByteBuf 与 ByteBuffer 的区别

内存分配 堆内或直接内存 支持堆内、直接内存及池化分配器

三、ByteBuf 的核心索引

1. 内存布局

2. 读取与写入

3. 可读和可写字节数

4. 索引边界

四、堆内存与直接内存

1. 堆内存

2. 直接内存

3. 如何选择

五、内存池化

六、引用计数机制

1. 什么是引用计数

2. retain() 与 release()

3. ChannelInboundHandlerAdapter 的释放规则

4. SimpleChannelInboundHandler 的自动释放

七、slice()、duplicate() 与 copy()

1. slice()

2. duplicate()

3. copy()

4. retainedSlice()

八、生产环境中的 ByteBuf 内存泄漏

1. 常见原因

2. 错误示例

3. 推荐写法

4. 开启内存泄漏检测

5. 排查思路

九、生产开发建议

十、重点总结

十一、常见问题与答案

1. ByteBuf 为什么不需要 flip()？

2. ByteBuf 的 release() 是不是直接释放 JVM 内存？

3. slice() 和 copy() 有什么区别？

4. 为什么异步使用 ByteBuf 需要特别注意？

5. SimpleChannelInboundHandler 是否需要手动 release()？

6. 直接内存是不是完全没有数据复制？

7. 内存池中的 ByteBuf release() 后，内存会立即归还操作系统吗？

十二、学习测试

问题 1

问题 2

问题 3

支持与分享

评论

内存分配堆内或直接内存支持堆内、直接内存及池化分配器