# Netty 自定义编码器实战：从粘包半包到 Protubuf 消息识别

## 一、为什么需要自定义消息协议

在 IM 系统中，客户端和服务端通过 WebSocket 进行通信。TCP 是流式协议，没有消息边界，可能出现：

1.粘包：多条消息被合并成一个数据包

2.半包：一个数据包被拆分成多个数据包

因此需要自定义消息协议来确定消息边界。

## 二、协议格式设计

```
+------------------+------------------+---------------------+
|  消息长度(4字节)   |  消息指令(2字节)  |  消息内容(Protobuf) |
+------------------+------------------+---------------------+
```

* 消息长度（4 字节）：Protobuf 消息体的字节数，用于判断是否接收完整
* 消息指令（2 字节）：消息类型编号，用于识别消息类型
* 消息内容：Protobuf 序列化后的消息体

## 三、编码器实现
编码器将 Protobuf 消息对象编码为二进制数据：

```java
@Component
@ChannelHandler.Sharable
public class MessageDecoder extends MessageToMessageDecoder<BinaryWebSocketFrame> {
    private static final Logger LOGGER = LoggerFactory.getLogger(MessageEncoder.class);
    @Resource
    private MessageRecognizer recognizer;
    
    @Override
    protected void encode(ChannelHandlerContext ctx, GeneratedMessageV3 msg, List<Object> list) {
        // 1. 根据消息类型获取指令编号
        int msgCommand = recognizer.getMsgCommandByMsgClazz(msg.getClass());
        if (msgCommand < 0) {
            LOGGER.error("无法识别的消息, msgClazz = {}", msg.getClass().getSimpleName());
            return;
        }
        
        // 2. 将 Protobuf 消息序列化为字节数组
        byte[] msgBody = msg.toByteArray();
        
        // 3. 分配 ByteBuf 缓冲区
        ByteBuf byteBuf = ctx.alloc().buffer();
        
        // 4. 写入消息长度（4字节）
        byteBuf.writeInt(msgBody.length);
        
        // 5. 写入消息指令（2字节）
        byteBuf.writeShort((short) msgCommand);
        
        // 6. 写入消息内容
        byteBuf.writeBytes(msgBody);
        
        // 7. 封装为 BinaryWebSocketFrame
        list.add(new BinaryWebSocketFrame(byteBuf));
    }
}
```
要点：
* 使用 `ctx.alloc().buffer()` 分配 ByteBuf，由 netty 管理内存
* 先写长度，再写指令，最后写内容
* 封装为 BinaryWebSocketFrame 用于 WebSocket 传输

## 四、解码器实现（解决粘包/半包）
解码器从二进制数据中解析出消息对象，并处理粘包/半包

```java
@Component
@ChannelHandler.Sharable
public class MessageDecoder extends MessageToMessageDecoder<BinaryWebSocketFrame> {

    private static final Logger LOGGER = LoggerFactory.getLogger(MessageDecoder.class);
    
    @Resource
    private MessageRecognizer recognizer;
    
    @Override
    protected void decode(ChannelHandlerContext ctx, BinaryWebSocketFrame msg, List<Object> list) {
        ByteBuf byteBuf = msg.content();
        
        // 1. 检查是否有足够的数据读取头部（至少4字节长度+2字节指令）
        if (byteBuf.readableBytes() < 6) {
            return; // 数据不足，等待下次数据到达
        }
        
        // 2. 标记当前读取位置，用于半包处理
        byteBuf.markReaderIndex();
        
        // 3. 读取消息长度（4字节）
        int msgLength = byteBuf.readInt();
        
        // 4. 读取消息指令（2字节）
        short command = byteBuf.readShort();
        
        // 5. 检查是否有足够的数据读取消息体（半包处理）
        if (byteBuf.readableBytes() < msgLength) {
            // 数据不完整，重置读取位置，等待下次数据到达
            byteBuf.resetReaderIndex();
            return;
        }
        
        // 6. 根据指令获取对应的 Protobuf Builder
        Message.Builder builder = recognizer.getMsgBuilderByMsgCommand(command);
        if (builder == null) {
            LOGGER.error("无法识别的消息, command = {}", command);
            byteBuf.resetReaderIndex();
            return;
        }
        
        // 7. 读取消息体
        byte[] msgBody = new byte[msgLength];
        byteBuf.readBytes(msgBody);
        
        // 8. 反序列化为 Protobuf 消息对象
        builder.clear();
        builder.mergeFrom(msgBody);
        Message message = builder.build();
        
        if (message != null) {
            list.add(message);
        }
    }
}
```
半包处理：
* 使用 `markReaderIndex()` 标记位置
* 数据不足时，`resetReaderIndex()` 回退，等待下次数据
* 通过消息长度字段判断是否完整

粘包处理：
* 每次只解析一条完整数据
* 剩余数据留在 ByteBuf 中，下次继续解析

## 五、消息识别器设计
通过反射自动建立消息类型与指令编号的映射
```java
@Component
public class MessageRecognizer implements InitializingBean {
    
    // 指令编号 -> 消息实例的映射（用于解码）
    private final Map<Integer, GeneratedMessageV3> msgCommandAndMsgBodyMap = new HashMap<>();
    
    // 消息类型 -> 指令编号的映射（用于编码）
    private final Map<Class<?>, Integer> msgClazzAndMsgCommandMap = new HashMap<>();
    
    @Override
    public void afterPropertiesSet() throws Exception {
        init();
    }
    
    public void init() {
        // 1. 获取 Protobuf 协议文件中的所有内部类
        Class<?>[] innerClazzArray = AQChatMsgProtocol.class.getDeclaredClasses();
        
        for (Class<?> innerClazz : innerClazzArray) {
            // 2. 过滤出消息类型（继承自 GeneratedMessageV3）
            if (!GeneratedMessageV3.class.isAssignableFrom(innerClazz)) {
                continue;
            }
            
            // 3. 获取类名并转换为小写（去掉下划线）
            String clazzName = innerClazz.getSimpleName().toLowerCase();
            
            // 4. 遍历消息指令枚举，匹配类名
            for (AQChatMsgProtocol.MsgCommand msgCommand : AQChatMsgProtocol.MsgCommand.values()) {
                String strMsgCode = msgCommand.name().replaceAll("_", "").toLowerCase();
                
                // 5. 类名匹配指令名（如 UserLoginCmd 匹配 USER_LOGIN_CMD）
                if (!strMsgCode.equals(clazzName)) {
                    continue;
                }
                
                try {
                    // 6. 通过反射调用 getDefaultInstance() 获取默认实例
                    Object returnObj = innerClazz.getDeclaredMethod("getDefaultInstance")
                        .invoke(innerClazz);
                    
                    // 7. 建立双向映射
                    msgCommandAndMsgBodyMap.put(msgCommand.getNumber(), (GeneratedMessageV3) returnObj);
                    msgClazzAndMsgCommandMap.put(innerClazz, msgCommand.getNumber());
                    
                    LOGGER.info("消息识别器初始化: {} => {}", innerClazz.getName(), msgCommand.getNumber());
                } catch (Exception ex) {
                    LOGGER.error(ex.getMessage(), ex);
                }
            }
        }
    }
    
    // 解码时：根据指令编号获取 Builder
    public Message.Builder getMsgBuilderByMsgCommand(int msgCommand) {
        GeneratedMessageV3 msg = msgCommandAndMsgBodyMap.get(msgCommand);
        if (msg == null) {
            return null;
        }
        return msg.newBuilderForType();
    }
    
    // 编码时：根据消息类型获取指令编号
    public int getMsgCommandByMsgClazz(Class<?> msgClazz) {
        Integer command = msgClazzAndMsgCommandMap.get(msgClazz);
        return command == null ? -1 : command;
    }
}
```
设计要点：
* 自动映射：通过类名匹配枚举名，无需手动维护
* 双向映射：支持编码和解码
* 反射机制：运行时建立映射关系

## 六、Protobuf 协议定义
在 `.proto` 文件中定义消息类型和指令
```proto
syntax="proto3";

package chat_msg;
option java_package = "com.howcode.aqchat.message";

// 消息指令枚举
enum MsgCommand{
  USER_LOGIN_CMD = 0;      // 用户登录请求
  USER_LOGIN_ACK = 1;      // 用户登录响应
  SEND_MSG_CMD = 10;       // 发送消息请求
  SEND_MSG_ACK = 11;       // 发送消息响应
  BROADCAST_MSG_ACK = 12;  // 消息广播
  // ... 更多指令
}

// 用户登录请求消息
message UserLoginCmd{
  string userName = 1;
  string userAvatar = 2;
}

// 用户登录响应消息
message UserLoginAck{
  string userId = 1;
  string userName = 2;
  string userAvatar = 3;
}
```
命名规则：
* 请求消息：XxxCmd（如 `UserLoginCmd`）
* 响应消息：XxxAck（如 `UserLoginAck`）
* 通知消息：XxxNotify（如 `JoinRoomNotify`）

## 七、使用示例
发送消息（编码）
```java
// 构造 Protobuf 消息对象
AQChatMsgProtocol.UserLoginCmd loginCmd = AQChatMsgProtocol.UserLoginCmd.newBuilder()
    .setUserName("张三")
    .setUserAvatar("https://example.com/avatar.jpg")
    .build();

// 通过 Channel 发送，编码器会自动编码
ctx.writeAndFlush(loginCmd);
```
接收消息（解码）
```java
// 在 Handler 中接收，解码器已经自动解码为 Protobuf 对象
@Override
protected void channelRead0(ChannelHandlerContext ctx, Object msg) {
    if (msg instanceof AQChatMsgProtocol.UserLoginCmd) {
        AQChatMsgProtocol.UserLoginCmd cmd = (AQChatMsgProtocol.UserLoginCmd) msg;
        String userName = cmd.getUserName();
        // 处理登录逻辑...
    }
}
```

## 八、协议设计的优势
1.解决粘包/半包：通过长度字段明确消息边界

2.类型安全：Protobuf 编译时检查，减少运行时错误

3.性能优化：二进制协议，体积和速度优于 JSON

4.易于扩展：新增消息类型只需在 `.proto` 中定义

5.自动映射：消息识别器自动建立类型与指令的映射

## 九、总结
自定义消息协议的核心：
* 固定头部：长度 + 指令，用于识别消息边界和类型
* 可变体：Protobuf 消息体，灵活扩展
* 半包处理：通过 `markReaderIndex/resetReaderIndex` 实现
* 自动识别：通过反射自动建立消息类型与指令的映射

该设计在 AQChat 中支持 30+ 种消息类型，易于维护和扩展。

在 IM 系统中，客户端和服务端通过 WebSocket 进行通信。TCP 是流式协议，没有消息边界，可能出现：

Netty 自定义编码器实战：从粘包半包到 Protubuf 消息识别

网络与通信

后端

编程语言

Netty自定义编码器实战详解：通过4字节长度+2字节指令的协议设计解决TCP粘包/半包问题，结合Protobuf实现高效消息编解码。包含消息识别器自动映射、WebSocket传输优化等关键技术，适用于IM系统开发，提升通信性能与可维护性。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Netty 自定义编码器实战：从粘包半包到 Protubuf 消息识别-腾讯云开发者社区-腾讯云

Netty 自定义编码器实战：从粘包半包到 Protubuf 消息识别

Netty 自定义编码器实战：从粘包半包到 Protubuf 消息识别

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐