Netty-LengthFieldBasedFrameDecoder-解决拆包粘包问题的解码器-摩杜云开发者社区

构造器参数

maxFrameLength：指定解码器所能处理的数据包的最大长度，超过该长度则抛出 TooLongFrameException 异常；
lengthFieldOffset：指定长度字段的起始位置；
lengthFieldLength：指定长度字段的长度：目前支持1(byte)、2(short)、3(3个byte)、4(int)、8(Long)
lengthAdjustment：指定长度字段所表示的消息长度值与实际长度值之间的差值，可以用于调整解码器的计算和提高灵活性。
initialBytesToStrip：指定解码器在将数据包分离出来后，跳过的字节数，因为这些字节通常不属于消息体内容，而是协议头或其他控制信息。

单元测试Demo

有关使用方法和方式参考测试Demo即可。

package com.netty.framework.core.channel;

import io.netty.buffer.ByteBuf;
import io.netty.buffer.Unpooled;
import io.netty.channel.ChannelHandlerContext;
import io.netty.channel.ChannelInboundHandlerAdapter;
import io.netty.channel.embedded.EmbeddedChannel;
import io.netty.handler.codec.LengthFieldBasedFrameDecoder;
import org.junit.Test;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.nio.charset.StandardCharsets;

/**
 * @author BugsHunter
 * 
 * @date 2023/7/7
 * @time 16:10
 */
public class LengthFieldBasedFrameDecoderTest {
    private static final Logger LOGGER = LoggerFactory.getLogger(LengthFieldBasedFrameDecoderTest.class);

    // 用于输出内容
    private final ChannelInboundHandlerAdapter handlerAdapter = new ChannelInboundHandlerAdapter() {
        @Override
        public void channelRead(ChannelHandlerContext ctx, Object msg) throws Exception {
            LOGGER.debug("handlerAdapter-接收到信息：{}", msg);
            super.channelRead(ctx, msg);
        }
    };

    /**
     * 二进制数据结构
     * lengthFieldOffset   = 0
     * lengthFieldLength   = 4
     * lengthAdjustment    = 0
     * initialBytesToStrip = 0 (不跳过长度字段长度信息读取)
     * 编码前 (16 bytes)                     编码后 (16 bytes)
     * +------------+----------------+      +------------+----------------+
     * |   Length   | Actual Content |----->|   Length   | Actual Content |
     * | 0x0000000C | "Hello, World" |      | 0x0000000C | "Hello, World" |
     * +------------+----------------+      +------------+----------------+
     */
    @Test
    public void test00() {
        class LengthFieldDecoder extends LengthFieldBasedFrameDecoder {
            public LengthFieldDecoder() {
                super(1024, 0, 4, 0, 0);
            }

            @Override
            protected Object decode(ChannelHandlerContext ctx, ByteBuf in) throws Exception {
                // 解码，得到解码后的字节数据（frame length=数据帧的长度）
                ByteBuf byteBuf = (ByteBuf) super.decode(ctx, in);
                LOGGER.debug("长度读取前readerIndex={}", byteBuf.readerIndex());

                // readInt会更新readerIndex值
                int lengthField = byteBuf.readInt();
                LOGGER.debug("长度字段[LengthField]的值={},即（Hello, World）的二进制长度。", lengthField);
                LOGGER.debug("长度读取后readerIndex={}", byteBuf.readerIndex());

                // toString方法根据readerIndex最新值开始解码
                return byteBuf.toString(StandardCharsets.UTF_8);
            }
        }

        LengthFieldBasedFrameDecoder decoder = new LengthFieldDecoder();
        EmbeddedChannel channel = new EmbeddedChannel(decoder, handlerAdapter);

        byte[] bytes = "Hello, World".getBytes(StandardCharsets.UTF_8);
        ByteBuf byteBuf = Unpooled.buffer();
        byteBuf.writeInt(bytes.length);
        byteBuf.writeBytes(bytes);

        channel.writeInbound(byteBuf);
    }


    /**
     * 二进制数据结构
     * lengthFieldOffset   = 0
     * lengthFieldLength   = 4
     * lengthAdjustment    = 0
     * initialBytesToStrip = 4 (跳过长度字段长度信息读取)
     * 编码前 (16 bytes)                     编码后 (12 bytes)
     * +------------+----------------+      +--------+--------+
     * |   Length   | Actual Content |----->|  Actual Content |
     * | 0x0000000C | "Hello, World" |      |  "Hello, World" |
     * +------------+----------------+      +--------+--------+
     */
    @Test
    public void test01() {
        class LengthFieldDecoder extends LengthFieldBasedFrameDecoder {
            public LengthFieldDecoder() {
                super(1024, 0, 4, 0, 4);
            }

            @Override
            protected Object decode(ChannelHandlerContext ctx, ByteBuf in) throws Exception {
                ByteBuf byteBuf = (ByteBuf) super.decode(ctx, in);
                return byteBuf.toString(StandardCharsets.UTF_8);
            }
        }

        LengthFieldBasedFrameDecoder decoder = new LengthFieldDecoder();
        EmbeddedChannel channel = new EmbeddedChannel(decoder, handlerAdapter);

        byte[] bytes = "Hello, World".getBytes(StandardCharsets.UTF_8);
        ByteBuf byteBuf = Unpooled.buffer();
        byteBuf.writeInt(bytes.length);
        byteBuf.writeBytes(bytes);

        channel.writeInbound(byteBuf);
    }

    /**
     * 此处lengthField包含了消息头的长度，即：Length = lengthFieldLength + 消息字节长度(Hello, World的二进制长度)
     * lengthFieldOffset   =  0
     * lengthFieldLength   =  4
     * lengthAdjustment    = -4 (lengthField字段的长度)
     * initialBytesToStrip =  0
     * 编码前 (16 bytes)                     编码后 (16 bytes)
     * +------------+----------------+      +------------+----------------+
     * |   Length   | Actual Content |----->|   Length   | Actual Content |
     * | 0x0000000G | "Hello, World" |      | 0x0000000G | "Hello, World" |
     * +------------+----------------+      +------------+----------------+
     */
    @Test
    public void test02() {
        class LengthFieldDecoder extends LengthFieldBasedFrameDecoder {
            public LengthFieldDecoder() {
                super(1024, 0, 4, -4, 0);
            }

            @Override
            protected Object decode(ChannelHandlerContext ctx, ByteBuf in) throws Exception {
                ByteBuf byteBuf = (ByteBuf) super.decode(ctx, in);
                LOGGER.debug("长度读取前readerIndex={}", byteBuf.readerIndex());

                // readInt会更新readerIndex值
                int lengthField = byteBuf.readInt();
                LOGGER.debug("长度字段[LengthField]的值={},即（Hello, World）的二进制长度。", lengthField);
                LOGGER.debug("长度读取后readerIndex={}", byteBuf.readerIndex());

                // toString方法根据readerIndex最新值开始解码
                return byteBuf.toString(StandardCharsets.UTF_8);
            }
        }

        LengthFieldBasedFrameDecoder decoder = new LengthFieldDecoder();
        EmbeddedChannel channel = new EmbeddedChannel(decoder, handlerAdapter);

        byte[] bytes = "Hello, World".getBytes(StandardCharsets.UTF_8);
        ByteBuf byteBuf = Unpooled.buffer();
        // 4=int的字节长度
        byteBuf.writeInt(bytes.length + 4);
        byteBuf.writeBytes(bytes);

        channel.writeInbound(byteBuf);
    }

    /**
     * lengthField在中间位置
     * lengthFieldOffset   = 2 (= the length of Header 1)
     * lengthFieldLength   = 4
     * lengthAdjustment    = 0
     * initialBytesToStrip = 0
     * <p>
     * BEFORE DECODE (18 bytes)                      AFTER DECODE (18 bytes)
     * +----------+----------+----------------+      +----------+----------+----------------+
     * | Header 1 |  Length  | Actual Content |----->| Header 1 |  Length  | Actual Content |
     * |  0xCAFE  | 0x00000C | "Hello, World" |      |  0xCAFE  | 0x00000C | "Hello, World" |
     * +----------+----------+----------------+      +----------+----------+----------------+
     */
    @Test
    public void test03() {
        class LengthFieldDecoder extends LengthFieldBasedFrameDecoder {
            public LengthFieldDecoder() {
                super(1024, 2, 4, 0, 0);
            }

            @Override
            protected Object decode(ChannelHandlerContext ctx, ByteBuf in) throws Exception {
                ByteBuf byteBuf = (ByteBuf) super.decode(ctx, in);
                LOGGER.debug("长度读取前readerIndex={}", byteBuf.readerIndex());

                // 读取header1
                short header1 = byteBuf.readShort();
                LOGGER.debug("header1={}", header1);

                // readInt会更新readerIndex值
                int lengthField = byteBuf.readInt();
                LOGGER.debug("长度字段[LengthField]的值={},即（Hello, World）的二进制长度。", lengthField);
                LOGGER.debug("长度读取后readerIndex={}", byteBuf.readerIndex());

                // toString方法根据readerIndex最新值开始解码
                return byteBuf.toString(StandardCharsets.UTF_8);
            }
        }

        LengthFieldBasedFrameDecoder decoder = new LengthFieldDecoder();
        EmbeddedChannel channel = new EmbeddedChannel(decoder, handlerAdapter);

        byte[] bytes = "Hello, World".getBytes(StandardCharsets.UTF_8);
        ByteBuf byteBuf = Unpooled.buffer();
        byteBuf.writeShort(99);
        byteBuf.writeInt(bytes.length);
        byteBuf.writeBytes(bytes);

        channel.writeInbound(byteBuf);
    }

    /**
     * lengthField在开始位置
     * lengthFieldOffset   = 0 (= the length of Header 1)
     * lengthFieldLength   = 4
     * lengthAdjustment    = 2
     * initialBytesToStrip = 0
     * BEFORE DECODE (18 bytes)                      AFTER DECODE (18 bytes)
     * +----------+----------+----------------+      +----------+----------+----------------+
     * |  Length  | Header 1 | Actual Content |----->|  Length  | Header 1 | Actual Content |
     * | 0x00000C |  0xCAFE  | "Hello, World" |      | 0x00000C |  0xCAFE  | "Hello, World" |
     * +----------+----------+----------------+      +----------+----------+----------------+
     */
    @Test
    public void test04() {
        class LengthFieldDecoder extends LengthFieldBasedFrameDecoder {
            public LengthFieldDecoder() {
                super(1024, 0, 4, 2, 0);
            }

            @Override
            protected Object decode(ChannelHandlerContext ctx, ByteBuf in) throws Exception {
                ByteBuf byteBuf = (ByteBuf) super.decode(ctx, in);
                LOGGER.debug("长度读取前readerIndex={}", byteBuf.readerIndex());

                // readInt会更新readerIndex值
                int lengthField = byteBuf.readInt();
                LOGGER.debug("长度字段[LengthField]的值={},即（Hello, World）的二进制长度。", lengthField);
                LOGGER.debug("长度读取后readerIndex={}", byteBuf.readerIndex());

                // 读取header1
                short header1 = byteBuf.readShort();
                LOGGER.debug("header1={}", header1);

                // toString方法根据readerIndex最新值开始解码
                return byteBuf.toString(StandardCharsets.UTF_8);
            }
        }

        LengthFieldBasedFrameDecoder decoder = new LengthFieldDecoder();
        EmbeddedChannel channel = new EmbeddedChannel(decoder, handlerAdapter);

        byte[] bytes = "Hello, World".getBytes(StandardCharsets.UTF_8);
        ByteBuf byteBuf = Unpooled.buffer();
        byteBuf.writeInt(bytes.length);
        byteBuf.writeShort(99);
        byteBuf.writeBytes(bytes);

        channel.writeInbound(byteBuf);
    }

    /**
     * lengthFieldOffset   = 1 (= the length of HDR1)
     * lengthFieldLength   = 4
     * lengthAdjustment    = 1 (= the length of HDR2)
     * initialBytesToStrip = 5 (= the length of HDR1 + LEN)
     * BEFORE DECODE (18 bytes)                       AFTER DECODE (13 bytes)
     * +------+--------+------+----------------+      +------+----------------+
     * | HDR1 | Length | HDR2 | Actual Content |----->| HDR2 | Actual Content |
     * | 0xCA | 0x000C | 0xFE | "Hello, World" |      | 0xFE | "Hello, World" |
     * +------+--------+------+----------------+      +------+----------------+
     */
    @Test
    public void test05() {
        class LengthFieldDecoder extends LengthFieldBasedFrameDecoder {
            public LengthFieldDecoder() {
                super(1024, 1, 4, 1, 5);
            }

            @Override
            protected Object decode(ChannelHandlerContext ctx, ByteBuf in) throws Exception {
                ByteBuf byteBuf = (ByteBuf) super.decode(ctx, in);
                LOGGER.debug("长度读取前readerIndex={}", byteBuf.readerIndex());

                // 读取header2
                short header2 = byteBuf.readByte();
                LOGGER.debug("header2={}", header2);

                // toString方法根据readerIndex最新值开始解码
                return byteBuf.toString(StandardCharsets.UTF_8);
            }
        }

        LengthFieldBasedFrameDecoder decoder = new LengthFieldDecoder();
        EmbeddedChannel channel = new EmbeddedChannel(decoder, handlerAdapter);

        byte[] bytes = "Hello, World".getBytes(StandardCharsets.UTF_8);
        ByteBuf byteBuf = Unpooled.buffer();
        byteBuf.writeByte(1);
        byteBuf.writeInt(bytes.length);
        byteBuf.writeByte(9);
        byteBuf.writeBytes(bytes);

        channel.writeInbound(byteBuf);
    }


    /**
     * lengthFieldOffset   =  1
     * lengthFieldLength   =  4 (整个消息的长度 = HDR1 + Length + HDR2 + Centent)
     * lengthAdjustment    = -5 (HDR1 + LEN的负值)
     * initialBytesToStrip =  5
     * BEFORE DECODE (18 bytes)                       AFTER DECODE (13 bytes)
     * +------+--------+------+----------------+      +------+----------------+
     * | HDR1 | Length | HDR2 | Actual Content |----->| HDR2 | Actual Content |
     * | 0xCA | 0x0010 | 0xFE | "Hello, World" |      | 0xFE | "Hello, World" |
     * +------+--------+------+----------------+      +------+----------------+
     */
    @Test
    public void test06() {
        class LengthFieldDecoder extends LengthFieldBasedFrameDecoder {
            public LengthFieldDecoder() {
                super(1024, 1, 4, -5, 5);
            }

            @Override
            protected Object decode(ChannelHandlerContext ctx, ByteBuf in) throws Exception {
                ByteBuf byteBuf = (ByteBuf) super.decode(ctx, in);
                LOGGER.debug("长度读取前readerIndex={}", byteBuf.readerIndex());

                // 读取header2
                short header2 = byteBuf.readByte();
                LOGGER.debug("header2={}", header2);

                // toString方法根据readerIndex最新值开始解码
                return byteBuf.toString(StandardCharsets.UTF_8);
            }
        }

        LengthFieldBasedFrameDecoder decoder = new LengthFieldDecoder();
        EmbeddedChannel channel = new EmbeddedChannel(decoder, handlerAdapter);

        byte[] bytes = "Hello, World".getBytes(StandardCharsets.UTF_8);
        ByteBuf byteBuf = Unpooled.buffer();
        byteBuf.writeByte(1);
        // 6=lengthField的长度+HEADER1的长度+HEADER2的长度
        byteBuf.writeInt(bytes.length + 6);
        byteBuf.writeByte(2);
        byteBuf.writeBytes(bytes);

        channel.writeInbound(byteBuf);
    }
}

源码解读-LengthFieldBasedFrameDecoder

decode方法

protected Object decode(ChannelHandlerContext ctx, ByteBuf in) throws Exception {
        // 校验是否丢弃超过最大数据帧长的字节
        if (discardingTooLongFrame) {
            discardingTooLongFrame(in);
        }

        // 可读字节长度小于lengthField结束的位置
        if (in.readableBytes() < lengthFieldEndOffset) {
            return null;
        }

        // 计算lengthField实际开始位置：以当前可读指针位置+lengthField偏移量为准
        int actualLengthFieldOffset = in.readerIndex() + lengthFieldOffset;

        // 获取数据帧长度
        long frameLength = getUnadjustedFrameLength(in, actualLengthFieldOffset, lengthFieldLength, byteOrder);

        if (frameLength < 0) {
            failOnNegativeLengthField(in, frameLength, lengthFieldEndOffset);
        }

        // 数据帧长度：需要减去lengthField之前的字节长度
        // 如果lengthFieldLength包含了header和所有字节数据，则需要通过lengthAdjustment减去lengthField之前的字节长度和lengthField本身
        frameLength += lengthAdjustment + lengthFieldEndOffset;

        if (frameLength < lengthFieldEndOffset) {
            failOnFrameLengthLessThanLengthFieldEndOffset(in, frameLength, lengthFieldEndOffset);
        }

        // 数据帧长度大于最大限制
        if (frameLength > maxFrameLength) {
            exceededFrameLength(in, frameLength);
            return null;
        }

        // 因为maxFrameLength是int类型，实际数据长度肯定不会超过int最大值
        int frameLengthInt = (int) frameLength;

        // 可读字节长度小于数据帧长度则直接返回null
        if (in.readableBytes() < frameLengthInt) {
            return null;
        }

        // 略去字节大于数据帧字节长度
        if (initialBytesToStrip > frameLengthInt) {
            failOnFrameLengthLessThanInitialBytesToStrip(in, frameLength, initialBytesToStrip);
        }

        // 更新readerIndex：readerIndex = readerIndex + initialBytesToStrip
        in.skipBytes(initialBytesToStrip);

        // 重组数据
        // 1-读取当前最新readerIndex
        int readerIndex = in.readerIndex();

        // 2-数据帧真实长度需要减去略过initialBytesToStrip
        int actualFrameLength = frameLengthInt - initialBytesToStrip;

        // 3-新建ByteBuf，解码后的数据字节
        ByteBuf frame = extractFrame(ctx, in, readerIndex, actualFrameLength);

        // 4-原先ByteBuf不可读
        in.readerIndex(readerIndex + actualFrameLength);
        return frame;
    }

getUnadjustedFrameLength方法

/**
 * length==lengthFieldLength
 * offset如果设置不对会和真实数据相差甚大
 * 比如：
 * ByteBuf byteBuf = Unpooled.buffer();
 * byteBuf.writeInt(1);
 * byteBuf.getUnsignedInt(0)可以得到正确的数据：0  (00000000 00000000 00000000 00000001)
 * byteBuf.getUnsignedInt(1)则会得到错误的数据：256(00000000 00000000 00000001 00000000)
 */
protected long getUnadjustedFrameLength(ByteBuf buf, int offset, int length, ByteOrder order) {
        buf = buf.order(order);
        long frameLength;
        switch (length) {
        case 1:
            frameLength = buf.getUnsignedByte(offset);
            break;
        case 2:
            frameLength = buf.getUnsignedShort(offset);
            break;
        case 3:
            frameLength = buf.getUnsignedMedium(offset);
            break;
        case 4:
            frameLength = buf.getUnsignedInt(offset);
            break;
        case 8:
            frameLength = buf.getLong(offset);
            break;
        default:
            throw new DecoderException(
                    "unsupported lengthFieldLength: " + lengthFieldLength + " (expected: 1, 2, 3, 4, or 8)");
        }
        return frameLength;
    }

extractFrame方法

    protected ByteBuf extractFrame(ChannelHandlerContext ctx, ByteBuf buffer, int index, int length) {
        // 截取得到解码后的数据内容
        return buffer.retainedSlice(index, length);
    }