一个低级错误引发Netty编码解码中文异常

最近在调研 Netty 的使用，在编写编码解码模块的时候遇到了一个中文字符串编码和解码异常的情况，后来发现是笔者犯了个低级错误。这里做一个小小的回顾。

错误重现

在设计 Netty 的自定义协议的时候，发现了字符串类型的属性，一旦出现中文就会出现解码异常的现象，这个异常并不一定出现了 Exception ，而是出现了解码之后字符截断出现了人类不可读的字符。编码和解码器的实现如下：

// 实体
@Data
public class ChineseMessage implements Serializable {

    private long id;
    private String message;
}

// 编码器  - <错误示范，不要拷贝>
public class ChineseMessageEncoder extends MessageToByteEncoder<ChineseMessage> {

    @Override
    protected void encode(ChannelHandlerContext ctx, ChineseMessage target, ByteBuf out) throws Exception {
        // 写入ID
        out.writeLong(target.getId());
        String message = target.getMessage();
        int length = message.length();
        // 写入Message长度
        out.writeInt(length);
        // 写入Message字符序列
        out.writeCharSequence(message, StandardCharsets.UTF_8);
    }
}

// 解码器
public class ChineseMessageDecoder extends ByteToMessageDecoder {

    @Override
    protected void decode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) throws Exception {
        // 读取ID
        long id = in.readLong();
        // 读取Message长度
        int length = in.readInt();
        // 读取Message字符序列
        CharSequence charSequence = in.readCharSequence(length, StandardCharsets.UTF_8);
        ChineseMessage message = new ChineseMessage();
        message.setId(id);
        message.setMessage(charSequence.toString());
        out.add(message);
    }
}

简单地编写客户端和服务端代码，然后用客户端服务端发送一条带中文的消息：

// 服务端日志
接收到客户端的请求:ChineseMessage(id=1, message=张)
io.netty.handler.codec.DecoderException: java.lang.IndexOutOfBoundsException: readerIndex(15) + length(8) exceeds writerIndex(21) ......
// 客户端日志
接收到服务端的响应:ChineseMessage(id=2, message=张)
io.netty.handler.codec.DecoderException: java.lang.IndexOutOfBoundsException: readerIndex(15) + length(8) exceeds writerIndex(21) ......

其实，问题就隐藏在编码解码模块中。由于笔者前两个月一直996，在疯狂编写 CRUD 代码，业余在看 Netty 的时候，有一些基础知识一时短路没有回忆起来。笔者带着这个问题在各大搜索引擎中搜索，有可能是姿势不对或者关键字不准，没有得到答案，加之，很多博客文章都是照搬其他人的 Demo ，而这些 Demo 里面恰好都是用英文编写消息体例子，所以这个问题一时陷入了困局（2019年国庆假期之前卡住了大概几天，业务忙也没有花时间去想）。

灵光一现

2019年国庆假期前夕，由于团队一直在赶进度做一个前后端不分离的 CRUD 后台管理系统，当时有几个同事在做一个页面的时候讨论一个乱码的问题。在他们讨论的过程中，无意蹦出了两个让笔者突然清醒的词语：乱码和 UTF-8 。笔者第一时间想到的是刚用 Cnblogs 的时候写过的一篇文章：《小伙子又乱码了吧-Java字符编码原理总结》（现在看起来标题起得挺二的）。当时有对字符编码的原理做过一些探究，想想有点惭愧，1年多前看过的东西差不多忘记得一干二净。

直接说原因： UTF-8 编码的中文，大部分情况下一个中文字符长度占据3个字节（3 byte，也就是32 x 3或者32 x 4个位），而 Java 中字符串长度的获取方法 String#length() 是返回 String 实例中的 Char 数组的长度。但是我们多数情况下会使用 Netty 的字节缓冲区 ByteBuf ，而 ByteBuf 读取字符序列的方法需要预先指定读取的长度 ByteBuf#readCharSequence(int length, Charset charset); ，因此，在编码的时候需要预先写入字符串序列的长度。但是有一个隐藏的问题是： ByteBuf#readCharSequence(int length, Charset charset) 方法底层会创建一个 length 长度的 byte 数组作为缓冲区读取数据，由于 UTF-8 中 1 char = 3 or 4 byte ，因此 ChineseMessageEncoder 在写入字符序列长度的时候虽然字符个数是对的，但是每个字符总是丢失2个-3个 byte 的长度，而 ChineseMessageDecoder 在读取字符序列长度的时候总是读到一个比原来短的长度，也就是最终会拿到一个不完整或者错误的字符串序列。

解决方案

UTF-8 编码的中文在大多数情况下占3个字节，在一些有生僻字的情况下可能占4个字节。可以暴力点直接让写入字节缓冲区的字符序列长度扩大三倍，只需修改编码器的代码：

public class ChineseMessageEncoder extends MessageToByteEncoder<ChineseMessage> {

    @Override
    protected void encode(ChannelHandlerContext ctx, ChineseMessage target, ByteBuf out) throws Exception {
        // 写入ID
        out.writeLong(target.getId());
        String message = target.getMessage();
        int length = message.length() * 3;      // <1> 直接扩大字节序列的预读长度
        // 写入Message长度
        out.writeInt(length);
        // 写入Message字符序列
        out.writeCharSequence(message, StandardCharsets.UTF_8);
    }
}

当然，这样做太暴力，硬编码的做法既不规范也不友好。其实 Netty 已经提供了内置的工具类 io.netty.buffer.ByteBufUtil ：

// 获取UTF-8字符的最大字节序列长度
public static int utf8MaxBytes(CharSequence seq){}

// 写入UTF-8字符序列，返回写入的字节长度 - 建议使用此方法
public static int writeUtf8(ByteBuf buf, CharSequence seq){}

我们可以先记录一下 writerIndex ，先写一个假的值（例如0），再使用 ByteBufUtil#writeUtf8() 写字符序列，然后根据返回的写入的字节长度，通过 writerIndex 覆盖之前写入的假值：

public class ChineseMessageEncoder extends MessageToByteEncoder<ChineseMessage> {

    @Override
    protected void encode(ChannelHandlerContext ctx, ChineseMessage target, ByteBuf out) throws Exception {
        out.writeLong(target.getId());
        String message = target.getMessage();
        // 记录写入游标
        int writerIndex = out.writerIndex();
        // 预写入一个假的length
        out.writeInt(0);
        // 写入UTF-8字符序列
        int length = ByteBufUtil.writeUtf8(out, message);
        // 覆盖length
        out.setInt(writerIndex, length);
    }
}

至此，问题解决。如果遇到其他 Netty 编码解码问题，解决的思路是一致的。

小结

Netty 学习过程中，编码解码占一半，网络协议知识和调优占另一半。

Netty 的源码很优秀，很有美感，阅读起来很舒适。

Netty 真好玩。

附录

引入依赖：

<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-all</artifactId>
    <version>4.1.41.Final</version>
</dependency>
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.10</version>
    <scope>provided</scope>
</dependency>

代码：

// 实体
@Data
public class ChineseMessage implements Serializable {

    private long id;
    private String message;
}

// 编码器
public class ChineseMessageEncoder extends MessageToByteEncoder<ChineseMessage> {


    @Override
    protected void encode(ChannelHandlerContext ctx, ChineseMessage target, ByteBuf out) throws Exception {
        out.writeLong(target.getId());
        String message = target.getMessage();
        int writerIndex = out.writerIndex();
        out.writeInt(0);
        int length = ByteBufUtil.writeUtf8(out, message);
        out.setInt(writerIndex, length);
    }
}

// 解码器
public class ChineseMessageDecoder extends ByteToMessageDecoder {

    @Override
    protected void decode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) throws Exception {
        long id = in.readLong();
        int length = in.readInt();
        CharSequence charSequence = in.readCharSequence(length, StandardCharsets.UTF_8);
        ChineseMessage message = new ChineseMessage();
        message.setId(id);
        message.setMessage(charSequence.toString());
        out.add(message);
    }
}

// 客户端
@Slf4j
public class ChineseNettyClient {

    public static void main(String[] args) throws Exception {
        EventLoopGroup workerGroup = new NioEventLoopGroup();
        Bootstrap bootstrap = new Bootstrap();
        try {
            bootstrap.group(workerGroup);
            bootstrap.channel(NioSocketChannel.class);
            bootstrap.option(ChannelOption.SO_KEEPALIVE, true);
            bootstrap.option(ChannelOption.TCP_NODELAY, Boolean.TRUE);
            bootstrap.handler(new ChannelInitializer<SocketChannel>() {

                @Override
                protected void initChannel(SocketChannel ch) throws Exception {
                    ch.pipeline().addLast(new LengthFieldBasedFrameDecoder(1024, 0, 4, 0, 4));
                    ch.pipeline().addLast(new LengthFieldPrepender(4));
                    ch.pipeline().addLast(new ChineseMessageEncoder());
                    ch.pipeline().addLast(new ChineseMessageDecoder());
                    ch.pipeline().addLast(new SimpleChannelInboundHandler<ChineseMessage>() {

                        @Override
                        protected void channelRead0(ChannelHandlerContext ctx, ChineseMessage message) throws Exception {
                            log.info("接收到服务端的响应:{}", message);
                        }
                    });
                }
            });
            ChannelFuture future = bootstrap.connect("localhost", 9092).sync();
            System.out.println("客户端启动成功...");
            Channel channel = future.channel();
            ChineseMessage message = new ChineseMessage();
            message.setId(1L);
            message.setMessage("张大狗");
            channel.writeAndFlush(message);
            future.channel().closeFuture().sync();
        } finally {
            workerGroup.shutdownGracefully();
        }
    }
}

// 服务端
@Slf4j
public class ChineseNettyServer {

    public static void main(String[] args) throws Exception {
        int port = 9092;
        ServerBootstrap bootstrap = new ServerBootstrap();
        EventLoopGroup bossGroup = new NioEventLoopGroup();
        EventLoopGroup workerGroup = new NioEventLoopGroup();
        try {
            bootstrap.group(bossGroup, workerGroup)
                    .channel(NioServerSocketChannel.class)
                    .childHandler(new ChannelInitializer<SocketChannel>() {

                        @Override
                        protected void initChannel(SocketChannel ch) throws Exception {
                            ch.pipeline().addLast(new LengthFieldBasedFrameDecoder(1024, 0, 4, 0, 4));
                            ch.pipeline().addLast(new LengthFieldPrepender(4));
                            ch.pipeline().addLast(new ChineseMessageEncoder());
                            ch.pipeline().addLast(new ChineseMessageDecoder());
                            ch.pipeline().addLast(new SimpleChannelInboundHandler<ChineseMessage>() {

                                @Override
                                protected void channelRead0(ChannelHandlerContext ctx, ChineseMessage message) throws Exception {
                                    log.info("接收到客户端的请求:{}", message);
                                    ChineseMessage chineseMessage = new ChineseMessage();
                                    chineseMessage.setId(message.getId() + 1L);
                                    chineseMessage.setMessage("张小狗");
                                    ctx.writeAndFlush(chineseMessage);
                                }
                            });
                        }
                    });
            ChannelFuture future = bootstrap.bind(port).sync();
            log.info("启动Server成功...");
            future.channel().closeFuture().sync();
        } finally {
            workerGroup.shutdownGracefully();
            bossGroup.shutdownGracefully();
        }
    }
}

（本文完 c-2-d e-a-20191003 国庆快乐 (*^▽^*) ）

错误重现

灵光一现

解决方案

小结

附录

Recommend

聊天机器人实战教程 | PyTorch专栏

大麦网抢票工具系列（一）

ACL 2019 | 将带推敲解码器的增量Transformer用于文档级知识对话

一文总结机器学习常见知识点

Cawbird is a GTK Twitter Client for Linux (That Should Look Very Familiar)

项目管理必备技能之：计划扑克

一次出人意料而名留青史的 DNS 投毒攻击

时间片，从多任务系统说起

世界第一超算跑深度学习模型，2.76万块V100 GPU将分布式训练扩展到极致 - 知乎

A data science approach to personality models

About Joyk