接手真实的设备接入项目时第一次需要把 Spring Boot 和 Netty 组合起来用自定义 TCP 协议做服务端。刚开始那几天网上翻到的资料要么只讲 Netty 单独跑通的 Demo要么只贴一堆配置没有业务落地的细节真正能把“自定义协议”这件事从报文设计讲到联调排错的太少了。这篇文章是我完整跑通一版服务端的全过程复盘包括协议格式怎么定、编解码器怎么写、Spring 容器怎么和 Netty 生命周期衔接、以及联调阶段遇到的各种稀奇古怪的问题。如果你正准备在 Spring Boot 工程里接入 Netty 做自定义二进制协议的服务端这篇文章应该能帮你把那些需要自己踩一遍才知道的坑提前排掉。1. 项目背景与整体设计思路1.1 这套组合解决的是什么问题先聊一个很多人问过的选择问题为什么要用自定义 TCP 协议而不是直接用 Spring Boot 自带的 HTTP JSON服务端开发默认走 HTTP 没问题但它有根深蒂固的浪费。对于物联网设备上报这类场景一条数据可能只有几十字节包装成 HTTP 请求后光请求头就好几百字节带宽和流量被大量冗余信息吃掉。设备端往往是低配的 MCU、弱网环境、流量敏感一套紧凑的二进制协议远比 HTTP 合适。另外 HTTP 是请求-响应模型服务端要主动向设备推送消息就很别扭要么设备轮询、要么迁就 WebSocket而原生的 TCP 长连接天然支持双向实时通信。再往下走一层用 TCP 就意味着要自己处理连接生命周期、粘包拆包、字节序这些底层问题。直接用 JDK 原生的 NIO 可以写但要自己维护事件循环、处理半包堆积、应对各种平台差异这些成本在企业项目里很容易失控。Netty 把这些基础设施抽象好了它提供的高性能 ByteBuf、完善的 ChannelHandler 链、现成的半包粘包处理组件比如 LengthFieldBasedFrameDecoder能让我把精力集中在协议和业务上而不是重新发明轮子。Spring Boot 在这套架构里承担另一层职责管理依赖注入、配置加载、业务对象的生命周期。Netty 的 ChannelHandler 是网络层的组件但它们里面要调用的业务逻辑——查数据库、缓存设备状态、推送告警消息——所有这些需要 Spring 容器来组装。两者的结合方式并不是把 Spring Boot 当成 Netty 的附属品而是各管一段Netty 负责高并发的网络 IOSpring Boot 负责业务代码的组织和运行。我实际项目里的接入连接量不算特别夸张峰值大概几万条长连接。这个量级下传统的阻塞式 IO 每连接一线程的模型基本撑不住而 Netty 的异步非阻塞模型能轻松扛住内存和线程开销都小一个量级。1.2 服务端架构与模块划分动手编码之前我先把模块边界划清楚。这是我在这个项目里比较满意的一个决定把协议编解码、网络启动、业务处理和连接管理四块拆开互不掺和。最后形成的工程结构大概长这样com.example.server ├── NettyServer.java // 服务启动与关闭 ├── codec │ ├── ProtocolMessage.java // 自定义报文实体 │ ├── ProtocolDecoder.java // 自定义解码器 │ └── ProtocolEncoder.java // 自定义编码器 ├── handler │ ├── ServerInitializer.java // 管道装配 │ ├── BusinessHandler.java // 业务分发入口 │ └── HeartbeatHandler.java // 心跳与空闲检测 ├── session │ └── SessionManager.java // 连接会话管理 └── startup └── NettyStartupRunner.java // 随 Spring Boot 启动每个模块的职责单一后面几节会按这个结构逐个展开。拆成独立模块带来的一个直接好处是编解码器可以脱离网络服务单独做单元测试业务处理器可以在不启动 Netty 的情况下用普通的 Spring 测试验证。对于自定义协议这种容错率低的环节这个拆法让测试成本低了很多。2. 自定义协议设计从需求到报文格式落地2.1 报文格式的字段规划自定义协议的核心就是那张报文格式表所有编解码逻辑都是对它的一种翻译。我设计的第一版协议包含以下字段字段字节数偏移说明magic 魔数10固定 0x5A用于快速识别有效报文version 版本11协议版本号初始为 1command 命令字22业务类型如 0x0001 注册、0x0002 数据上报sequence 序列号44消息序号用于请求响应匹配length 长度48payload 部分字节数body 报文体N12业务数据checksum 校验位212N对 body 的校验值魔数人如其名就是一个魔法数字。设备端和服务端约定好报文第一字节固定为 0x5A我在解码器里首先检查它不是 0x5A 直接关闭连接。这个设计在真实场景里非常管用能快速拦截掉路由探测、端口扫描、或者设备端串口发送过来的垃圾数据避免后续解析流程被乱七八糟的字节流搞崩。version 字段平时很少被关注但它是协议演进的生命线。我一开始就没校验版本号目的就是向前兼容——老设备固件不可能一夜之间全升级完新老版本并存是常态。后续如果协议做不兼容升级服务端可以根据 version 分发到不同的解析链路老连接还能继续跑一段。command 用 2 个字节最多支持 65535 种业务类型对绝大多数设备接入场景绰绰有余。1 个字节的 command 也能用但扩展性太紧新增几十种业务指令后很容易后悔。sequence 主要解决异步消息的对应问题服务端收到请求后处理完响应里带上相同的 sequence设备端就能知道这条响应对应之前哪个请求。2.2 字节序、长度策略与通用解码方案字节序是协议设计里最容易被忽视的坑。网络协议传统上使用大端字节序Big-Endian也就是高字节在前。Java 语言本身也默认大端Netty 的 ByteBuf 默认读写顺序同样是大端所以我在协议里直接采用大端Java 端实现起来不用做任何翻转。但如果设备端用的是小端 MCU这块就必须在协议文档里写死编解码时手动做反转两边不一致的后果是字段解析出来的全是天文数字。长度字段用 4 字节理论上可以描述最大约 2GB 的报文体。有人觉得浪费但 4 字节长整型在 Java 端处理起来最顺手而且对大报文场景留足了空间。如果真的追求极致带宽用 2 字节长度字段也行但报文体必须限制在 65535 字节以内这是个硬性约束文档里必须写清楚。关于长度还要聊一下解码框架选型。自定义 TCP 协议服务端最大的敌人是粘包和半包TCP 是流式协议没有消息边界多条报文可能拼在一起到达粘包一条报文也可能被拆成几段分别到达半包。我的解码器自己实现了一套完整的拆包逻辑public class ProtocolDecoder extends ByteToMessageDecoder { private static final int HEADER_LENGTH 12; private static final int CHECKSUM_LENGTH 2; private static final int MAX_FRAME_LENGTH 64 * 1024; private static final byte MAGIC 0x5A; Override protected void decode(ChannelHandlerContext ctx, ByteBuf in, ListObject out) { // 1. 先凑够 12 字节头部 if (in.readableBytes() HEADER_LENGTH) { return; } // 2. 标记读指针位置后续数据不够时可以回退 in.markReaderIndex(); byte magic in.readByte(); byte version in.readByte(); short command in.readShort(); int sequence in.readInt(); int length in.readInt(); // 3. 校验魔数与非法长度 if (magic ! MAGIC) { log.warn(magic not match, close channel); ctx.close(); return; } if (length 0 || length MAX_FRAME_LENGTH) { log.warn(invalid length: {}, close channel, length); ctx.close(); return; } // 4. 还没收到完整的 body checksum回退等待 if (in.readableBytes() length CHECKSUM_LENGTH) { in.resetReaderIndex(); return; } // 5. 读取完整报文并输出 byte[] payload new byte[length]; in.readBytes(payload); short checksum in.readShort(); if (checksum(payload) ! checksum) { log.warn(checksum mismatch, discard this frame); return; } ProtocolMessage message new ProtocolMessage(); message.setMagic(magic); message.setVersion(version); message.setCommand(command); message.setSequence(sequence); message.setPayload(payload); message.setChecksum(checksum); out.add(message); } private short checksum(byte[] data) { short sum 0; for (byte b : data) { sum (short) (b 0xFF); } return sum; } }我用的是最直接的自定义拆包方案先 markReaderIndex数据不够时 resetReaderIndex让 ByteToMessageDecoder 内部的累积缓冲继续等待后续数据。这样每个 channel 只保留一个可增长的累积缓冲区由 Netty 统一管理不会出现数据错位的问题。如果不想手动维护这些细节Netty 也提供了现成的 LengthFieldBasedFrameDecoder。我的表结构里长度字段偏移是 8、长度字节数是 4、报文尾部还有 2 字节校验位所以对应的参数是这样pipeline.addLast(new LengthFieldBasedFrameDecoder( 64 * 1024, // 最大帧长 8, // 长度字段偏移 4, // 长度字段字节数 2, // 长度调整值把尾部 2 字节校验位也算进帧里 0 // 不剥离头部 ));两种方案的差异在于LengthFieldBasedFrameDecoder 帮你把粘包半包问题处理干净输出的是完整帧后续解码器只需要解析固定字段而自己写 ByteToMessageDecoder好处是完全可控遇到魔数不匹配、校验失败等异常情况时能按自定义策略处理。我的原则是协议越标准越推荐直接上 LengthFieldBasedFrameDecoder协议里像我这样塞了魔数和校验位的自己写拆包逻辑也不复杂反而更好雕琢。3. Spring Boot 集成 Netty 的核心代码实现3.1 工程依赖与基础配置Spring Boot 工程接入 Netty 的依赖项很简单我在 pom.xml 里加了 netty-alldependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter/artifactId /dependency dependency groupIdio.netty/groupId artifactIdnetty-all/artifactId version4.1.100.Final/version /dependencynetty-all 把 transport、codec、handler、buffer 等模块打成一个大包开发期图省事没问题本来就是标准的做法。如果对包体大小敏感可以拆成具体的模块依赖不过收益有限大多数项目直接上 netty-all 就够了。端口这类环境相关的参数放进 application.yml用 Value 注入netty: port: 8081之所以不像很多 Demo 那样把端口硬编码在代码里是因为 Netty 服务运行在同一套 Spring Boot 应用中端口需要跟随环境配置走测试环境、灰度环境、生产环境很可能各不相同。3.2 协议实体与编解码器实现报文实体是编解码器之间传递的数据载体我最初只把它定义成包含协议头字段和原始字节数组的 POJO业务层拿到 payload 后再按 command 做二次解析public class ProtocolMessage { private byte magic; private byte version; private short command; private int sequence; private byte[] payload; private short checksum; // getter/setter 省略实际项目请用 lombok 或者手写 }解码器的实现上一节已经完整展示了核心点在于等待完整帧到达前不消费头部字节必须 mark 和 reset 配合使用。这里有新手容易犯的大误区——发现数据不足直接 return 而不重置读指针等下一轮数据到达时头部字节已经被读过一次没了整个报文解析就错位了而且这种错位非常隐蔽日志和业务上都不容易察觉。编码器相对简单得多它拿到的是已经组装好的 ProtocolMessage按协议格式原样写入 ByteBufpublic class ProtocolEncoder extends MessageToByteEncoderProtocolMessage { Override protected void encode(ChannelHandlerContext ctx, ProtocolMessage msg, ByteBuf out) { byte[] payload msg.getPayload() null ? new byte[0] : msg.getPayload(); out.writeByte(msg.getMagic()); out.writeByte(msg.getVersion()); out.writeShort(msg.getCommand()); out.writeInt(msg.getSequence()); out.writeInt(payload.length); out.writeBytes(payload); out.writeShort(checksum(payload)); } }这里有一个关于 ByteBuf 的常识需要强调MessageToByteEncoder 会自动管理输出 ByteBuf 的生命周期写完后 Netty 负责释放业务代码不需要手动 release。反过来如果业务里自己 unpooled 创建了 ByteBuf用完必须手动释放否则直接内存会持续增长最后被系统警告甚至 OOM。3.3 业务处理器、会话管理与 Spring Bean 整合业务处理器是整个链路里和 Spring 容器打交道最多的环节。先看代码Component ChannelHandler.Sharable public class BusinessHandler extends SimpleChannelInboundHandlerProtocolMessage { Autowired private SessionManager sessionManager; Override public void channelActive(ChannelHandlerContext ctx) throws Exception { super.channelActive(ctx); log.info(channel active: {}, ctx.channel().remoteAddress()); } Override protected void channelRead0(ChannelHandlerContext ctx, ProtocolMessage msg) { // 按命令字分发到不同的业务方法 dispatch(ctx, msg); } Override public void channelInactive(ChannelHandlerContext ctx) throws Exception { // 连接断开时清理会话 sessionManager.removeByChannel(ctx.channel()); super.channelInactive(ctx); } Override public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) { log.error(handler exception, cause); ctx.close(); } }这里有几个关键点。第一为什么 BusinessHandler 用 Component 标记因为 Netty 的 ChannelHandler 默认是在 ServerInitializer 里面 new 出来的这样它就脱离了 Spring 容器管理我们想在里面注入 SessionManager、业务 Service 就会拿到 null。把 BusinessHandler 变成 Spring Bean再注入到 ServerInitializer 的 Pipeline 装配逻辑里依赖就通了。第二Sharable 注解的含义。这个注解告诉 Netty同一个 handler 实例可以被安全地添加到多个 ChannelPipeline 中。Spring 的 Component 默认是单例也就是说这个 BusinessHandler 只有一个实例全局所有连接共享它。对于我这种无状态的纯分发处理器这是完全没问题的。但如果业务处理器内部保存了某个连接的专属状态比如把 deviceId 存在成员变量里那多连接共享这个实例就会串数据这种情况下就不能标 Sharable必须为每个连接 new 一个独立的 handler。第三设备级的会话状态放在哪。我的做法是放在 Channel 的 Attribute 里通过 SessionManager 统一管理Component public class SessionManager { private static final AttributeKeyString DEVICE_ID AttributeKey.valueOf(deviceId); private final ConcurrentHashMapString, Channel channelMap new ConcurrentHashMap(); public void add(String deviceId, Channel channel) { channelMap.put(deviceId, channel); channel.attr(DEVICE_ID).set(deviceId); } public void removeByChannel(Channel channel) { String deviceId channel.attr(DEVICE_ID).get(); if (deviceId ! null) { channelMap.remove(deviceId); } } public Channel getChannel(String deviceId) { return channelMap.get(deviceId); } public int sessionCount() { return channelMap.size(); } }设备注册的逻辑很简单设备上线后先发一条注册指令服务端从 payload 里解析出设备 ID然后写入 SessionManager。之后服务端要主动给设备推送数据时直接根据设备 ID 拿到 Channel调用 writeAndFlush 即可。SessionManager 用 ConcurrentHashMap 保证高并发下的线程安全这是 Netty 多线程事件循环模型下的底线要求。3.4 服务启动流程与优雅关闭Netty 服务启动流程一般走 ServerBootstrap我在 NettyServer 组件里封装了启动和关闭两个方法Component public class NettyServer { Value(${netty.port:8081}) private int port; Autowired private ServerInitializer serverInitializer; private EventLoopGroup bossGroup; private EventLoopGroup workerGroup; private Channel serverChannel; public void start() throws InterruptedException { bossGroup new NioEventLoopGroup(1); workerGroup new NioEventLoopGroup(); try { ServerBootstrap bootstrap new ServerBootstrap(); bootstrap.group(bossGroup, workerGroup) .channel(NioServerSocketChannel.class) .option(ChannelOption.SO_BACKLOG, 128) .option(ChannelOption.SO_REUSEADDR, true) .childOption(ChannelOption.TCP_NODELAY, true) .childOption(ChannelOption.SO_KEEPALIVE, true) .childHandler(serverInitializer); ChannelFuture future bootstrap.bind(port).sync(); serverChannel future.channel(); log.info(netty server started on port {}, port); } catch (InterruptedException e) { Thread.currentThread().interrupt(); throw e; } } public void shutdown() { if (serverChannel ! null) { serverChannel.close(); } if (bossGroup ! null) { bossGroup.shutdownGracefully(); } if (workerGroup ! null) { workerGroup.shutdownGracefully(); } } }两个线程组的职责分配是 Netty 的经典模型bossGroup 只负责接收新连接线程数 1 就够因为 accept 操作本身很轻workerGroup 负责处理所有连接的读写事件线程数默认是 CPU 核数的两倍一般不需要手动指定。SO_KEEPALIVE 打开能让操作系统层面帮忙探测死连接TCP_NODELAY 关闭了 Nagle 算法降低小报文的发送延迟对设备上报这种频繁小包场景非常重要。ServerInitializer 的职责是把解码器、编码器、心跳处理器和业务处理器组装进 PipelineComponent public class ServerInitializer extends ChannelInitializerSocketChannel { Autowired private BusinessHandler businessHandler; Override protected void initChannel(SocketChannel ch) { ChannelPipeline pipeline ch.pipeline(); pipeline.addLast(protocolDecoder, new ProtocolDecoder()); pipeline.addLast(protocolEncoder, new ProtocolEncoder()); pipeline.addLast(idleHandler, new IdleStateHandler(90, 0, 0, TimeUnit.SECONDS)); pipeline.addLast(heartbeatHandler, new HeartbeatHandler()); pipeline.addLast(businessHandler, businessHandler); } }启动的时机也要讲究。我一开始用了 PostConstruct 在 Bean 初始化阶段启动 Netty后来遇到了 Spring 上下文尚未完全初始化导致业务 Bean 注入不完整的问题。改成实现 ApplicationRunner 接口在 Spring 容器启动完成后执行Component public class NettyStartupRunner implements ApplicationRunner { Autowired private NettyServer nettyServer; Override public void run(ApplicationArguments args) { nettyServer.start(); } }优雅关闭同样不能忽略。在 NettyServer 里增加 PreDestroy 方法让 Spring Boot 应用关闭时能主动释放 Netty 的资源PreDestroy public void onDestroy() { nettyServer.shutdown(); }shutdownGracefully 会等待已注册的 IO 事件处理完再退出避免强行 kill 线程导致半写状态的连接把 Socket 数据弄脏。这在生产环境做滚动发布时能明显减少设备端的异常断线重连。4. 联调实测典型问题与排查记录4.1 粘包、半包和恶意长度联调阶段遇到的第一个问题也是最经典的问题设备端多个数据帧连续发送时服务端一次拿到的字节流可能包含多帧数据或者只包含半帧。我用自定义解码器配合in.readableBytes() length CHECKSUM_LENGTH的判断等待完整帧问题得到控制但排查过程还是花了不少时间。最典型的一个低级失误出现在我早期的版本里在检测到数据不足时我只写了return而没有先resetReaderIndex()。第一次运行发现解析出来的命令字和序列号全是乱的打日志才意识到读指针已经越过了头部字段。这个错误让我深刻理解了 markReaderIndex 和 resetReaderIndex 在拆包逻辑里的不可替代性——它们就像一个书签数据没齐之前我们把页停在原文位置等下一页内容到齐了再重新开始读。还有一个必须防御的场景是恶意的长度字段。如果设备端因为固件 bug 或者被恶搞发送了一个很大的 length 值解码器直接申请那么大的一块 byte[]内存立刻被打满。我的处理方式是设定 MAX_FRAME_LENGTH 上限超出直接关闭连接。生产环境里这个值要根据业务报文的最大尺寸去定我这边最大单帧不超过 1KB所以给了 64KB 的上限留了足够余量又不至于被撑爆。如果你用了 LengthFieldBasedFrameDecoder它内部的 maxFrameLength 参数会自动帮我们做这层防护这也是它比完全手写拆包更省心的原因之一。4.2 IO 线程阻塞与业务线程池隔离联调中遇到第二个让我头疼的问题是设备并发上报时整体吞吐量突然掉下去。登录量特别大的那段时间CPU 使用率猛涨但处理能力反而下降部分设备的请求明显延迟。排查过程用了 Netty 的 handler 事件断点最后定位出来的根因是我在 BusinessHandler 里直接执行了数据库写入和缓存更新。Netty 的 worker 线程本质上是事件循环它在执行一个 channel 的 channelRead0 时如果方法内做了耗时的同步操作这个线程就会被牢牢占据无法继续处理其它 channel 的 IO 事件。一个慢请求拖慢的是同一个 worker 线程上的所有连接。解决办法是引入独立的业务线程池把耗时的业务逻辑从 IO 线程里剥离开。Netty 提供的 DefaultEventExecutorGroup 可以直接挂在 Pipeline 上private static final EventExecutorGroup BUSINESS_GROUP new DefaultEventExecutorGroup(16); Override protected void initChannel(SocketChannel ch) { ChannelPipeline pipeline ch.pipeline(); pipeline.addLast(protocolDecoder, new ProtocolDecoder()); pipeline.addLast(protocolEncoder, new ProtocolEncoder()); pipeline.addLast(idleHandler, new IdleStateHandler(90, 0, 0, TimeUnit.SECONDS)); pipeline.addLast(heartbeatHandler, new HeartbeatHandler()); pipeline.addLast(businessGroup, BUSINESS_GROUP, businessHandler); }把 businessHandler 挂到独立的 EventExecutorGroup 之后IO 线程只负责编解码和字节流的搬运channelRead0 里的数据库操作全部在业务线程组执行吞吐问题立刻缓解。这里有个重要的细节同一 channel 内的事件比如 channelRead0 和 channelInactive在同一个业务线程上还是有序执行的所以单连接的会话清理逻辑不会因为多线程出现竞态但不同 channel 之间不再保证顺序如果你的业务依赖跨连接的消息顺序需要自己在代码里加锁或排队。4.3 心跳、空闲检测与断线重连TCP 长连接有一个天然问题它不是实时感知对方状态的。设备直接断电、网络闪断TCP 连接可能不会立刻报错服务端会一直认为这条连接是健康的。时间一长服务端堆积大量半死连接设备侧又不断重连SessionManager 里的 channelMap 会被占据大量无效连接。我的方案是在 Pipeline 里加 IdleStateHandler并在其后加一个心跳处理器public class HeartbeatHandler extends ChannelInboundHandlerAdapter { Override public void userEventTriggered(ChannelHandlerContext ctx, Object evt) throws Exception { if (evt instanceof IdleStateEvent) { IdleStateEvent event (IdleStateEvent) evt; log.warn(channel idle, state{}, remote{}, event.state(), ctx.channel().remoteAddress()); ctx.close(); } else { super.userEventTriggered(ctx, evt); } } }IdleStateHandler 的三个参数分别是读空闲时间、写空闲时间和全部空闲时间我配置的是 90 秒内没有收到设备数据就触发 READER_IDLE。设备端的机制是每 30 秒发一次心跳包所以 90 秒的阈值给了足够余量。当 HeartbeatHandler 捕获到空闲事件直接关闭这条连接。设备端有个配套的断线重连机制按退避策略指数递增重连间隔从 1 秒开始最大不超过 60 秒。这套机制跑下来服务端的无效连接数基本归零。4.4 常见问题速查表把联调和中后期维护阶段遇到最多的几类问题整理成了一张表方便后面排查现象可能原因处理方式客户端发数据服务端无响应解码器半包等待导致消息未到业务层确认 Pipeline 顺序打日志观察 decode 是否输出消息Spring Bean 注入为 nullChannelHandler 手动 new 导致脱离容器改用 Component 注入或在构造函数中接收依赖业务逻辑阻塞导致整体吞吐下降数据库等耗时操作占用了 IO 线程使用 DefaultEventExecutorGroup 隔离业务线程大量半死连接无法清理缺少心跳和空闲检测配置 IdleStateHandler超时关闭连接服务重启时设备大量掉线未做优雅关闭PreDestroy 调用 shutdownGracefully解码字节错位、解析出异常字段半包时未重置读指针markReaderIndex/resetReaderIndex 成对使用这张表里的每一条都是我真实踩过的坑。自定义协议服务端的问题往往不会直接报错而是以数据错乱、连接异常、内存波动这些隐晦的形式出现。遇到问题不要上来就搜答案先把 Pipeline 里每一层 handler 的输入输出都打上日志定位到具体层再展开排查效率反而最高。5. 拓展思路与经验沉淀5.1 用 EmbeddedChannel 做单元测试自定义协议里最怕两件事编解码逻辑悄悄出错、边界条件没人验证。手动起服务再拿客户端联调每次都要准备设备模拟器、反复发数据成本很高。Netty 提供的 EmbeddedChannel 可以像单元测试一样直接验证编解码器我在写好编解码器之后就立刻补了一组测试Test public void testDecoderCompleteFrame() { EmbeddedChannel channel new EmbeddedChannel(new ProtocolDecoder()); byte[] body hello.getBytes(StandardCharsets.UTF_8); ByteBuf buf Unpooled.buffer(); buf.writeByte(0x5A); buf.writeByte(0x01); buf.writeShort(0x0001); buf.writeInt(1); buf.writeInt(body.length); buf.writeBytes(body); buf.writeShort(checksum(body)); channel.writeInbound(buf); ProtocolMessage msg channel.readInbound(); assertNotNull(msg); assertEquals(0x5A, msg.getMagic()); assertEquals(1, msg.getSequence()); } Test public void testDecoderHalfFrame() { EmbeddedChannel channel new EmbeddedChannel(new ProtocolDecoder()); byte[] body hello.getBytes(StandardCharsets.UTF_8); ByteBuf buf Unpooled.buffer(); // 构造一个只包含头部 body 前 2 字节的半包 buf.writeByte(0x5A); buf.writeByte(0x01); buf.writeShort(0x0001); buf.writeInt(1); buf.writeInt(body.length); buf.writeBytes(body, 0, 2); channel.writeInbound(buf); // 半包情况下不应有消息输出 assertNull(channel.readInbound()); // 补齐剩余字节 ByteBuf rest Unpooled.buffer(); rest.writeBytes(body, 2, body.length - 2); rest.writeShort(checksum(body)); channel.writeInbound(rest); assertNotNull(channel.readInbound()); }这个测试覆盖了最关键的半包场景。写它的时候我踩过一个值得记录的细节EmbeddedChannel 的 writeInbound 会把 ByteBuf 按顺序写入多条 writeInbound 调用之间是累积关系所以半包后补包的行为能精确模拟真实网络。建议每个字符级字段的边界值也多测测比如 length 为 0 的空报文、body 恰好等于最大长度的报文这些都是最容易出问题的分界线。5.2 后续扩展方向这套架构跑通之后还有几个方向上可以继续做深。TLS 加密设备接入公网场景明文协议肯定是不行的。Netty 的 SslContextBuilder 可以在 Pipeline 最前面加一层 SSL 处理器加密对上层编解码器完全透明这是性价比最高的安全加固手段。协议演进version 字段现在派上了用场可以针对不同版本注册不同的解码器链。设备固件升级是分批的新协议和旧协议并行跑很长一段时间这是必须考虑的现实约束。监控指标接入 Micrometer把当前连接数、每秒解包数、协议错误数、心跳超时数这些指标暴露出来配合监控大盘做告警。我在压测时发现协议错误数这个指标能在问题爆发前提前暴露设备端固件的异常行为。WebSocket 兼容如果一部分接入方是浏览器端可以在同一个 Netty 服务里同时挂 TCP 和 WebSocket 两条 Pipeline。业务逻辑收敛到同一个 dispatcher 里两边共用一套 SessionManager代码不需要重复维护。有个一起做项目的朋友问过我这套自定义协议服务端最值钱的点在哪。我想了想不在 Netty 本身而在最开始那几张协议字段表和模块拆分。协议字段定得够完整后面接新设备型号、加业务命令基本只需要动 dispatcher 和 payload 解析服务端框架的代码一版都没改过。能做到这一点这套自定义协议服务端就算是真正立住了。