企业官网建设流程全解析

长连接服务这东西，刚上手时容易想简单，觉得不就是开个端口收字节。真到了要跟几万台设备打交道、或者要顶住每秒几万条消息的时候，问题就全冒出来了。我做过几个项目，凡是需要服务端主动推送、需要自己控制报文头、需要把每一条消息的开销压到最低的场景，最后基本都落到同一个组合上：Spring Boot 负责工程化那一层，Netty 负责扛住连接和字节流。这篇就把我搭一套带自定义协议的 Netty 服务端的过程完整捋一遍，包括协议怎么定、编解码器怎么写、Spring 的 Bean 怎么接进 Handler、心跳鉴权怎么做，以及那些只有真踩过才知道的坑。文章里涉及的所有代码片段都可以直接拿去改，参数计算过程我也会一步步写清楚。读者最好是已经有 Java 和 Spring Boot 基础，了解 TCP 大概怎么回事，如果你连 Netty 的 Channel、Pipeline 都还没概念，也能看，我会把关键概念用生活化的例子补上。

1. 需求倒推设计：先搞清楚为什么要自研协议

1.1 长连接场景里 HTTP 的几个硬伤

大多数业务用 HTTP 就够了，请求响应一来一回，简单直接。但一旦碰到设备上报、实时推送、IM 这类场景，HTTP 的短板就很明显。第一是头太大，一个简单的上报消息体可能就二十字节，HTTP 的头加上去几百字节，带宽浪费几十倍，设备端流量是要算钱的。第二是服务端没法主动推，HTTP 是客户端发起的模型，服务端想推消息只能靠长轮询或者 WebSocket，而 WebSocket 又要多一层握手和帧格式。第三是无状态带来的重复开销，每次请求都要带 token、带各种头，鉴权链路被反复执行。第四是没法复用连接做业务级的双向交互，比如一次连接建立后既收上报又发指令。

这些痛点堆在一起，结论就很清楚了：需要长连接、需要高频双向通信、对报文体积敏感的场景，用一个二进制或者紧凑文本的自定义协议更合适。所谓自定义协议，说白了就是双方约定好一段字节序列里第几个字节表示什么含义，服务端和客户端严格按这个格式来解析。它不是什么高深的东西，本质就是一套约定，难点在于约定要定得够严谨，还要考虑未来怎么扩展。

1.2 Spring Boot 与 Netty 的职责边界

很多人会问，既然用了 Netty，还要 Spring Boot 干什么。答案是把两件事分开看。Netty 擅长的是网络 IO，负责 accept 连接、读写字节、管理 Pipeline，它是事件驱动的，跑在自己的 EventLoop 线程组上。Spring Boot 擅长的是工程化，依赖注入、配置管理、连接池、事务、监控埋点、运维接口，这些是它的强项。把两者拼起来的核心思路就是：让 Netty 管网络层，让 Spring 管业务层和生命周期，Netty 的 Handler 通过依赖注入拿到 Spring 容器里的 Service。

一个典型的边界划分是这样的：Netty 的 Pipeline 里放编解码器和一些轻量的连接级 Handler，负责把字节变成 Java 对象、把连接状态映射成事件；真正耗时的业务处理丢给 Spring 管理的 Service，通常再配一个业务线程池，避免阻塞 IO 线程。这个划分听起来简单，但实际项目里最容易出的问题就是有人在 Handler 里直接查数据库，把 Netty 的 IO 线程堵死，一个慢查询能把整个 EventLoop 上挂着的一批连接全卡住。

1.3 自研协议的成本账

在动手之前，得先老老实实算一笔账。自研协议意味着客户端和服务端要各自实现一套编解码，意味着没有现成的抓包工具能直接看懂你的报文，意味着协议一旦上线就很难改，因为存量设备不会跟着你升级。我见过有项目因为长度字段设计错了，只能靠魔数嗅探做兼容，代码里堆了一堆历史包袱。

所以我的建议是：能不用自研就不用。像 MQTT、CoAP 这类成熟的物联网协议，生态完整、工具齐全，优先考虑。只有当你有极致的性能诉求，或者协议要承载的东西和现有协议都对不上，才自己定。真到这一步，就要在协议里留好版本号字段、留好扩展位，第一版就别想着一步到位。下面这套设计是我在一个设备接入项目里用过的，结构简单、扩展性也够。

2. 报文格式设计：把每个字节的用途定死

2.1 固定头加变长体的结构

协议最怕的就是含糊。我的做法是固定长度头加变长体，头里带上体的长度，接收方先读固定长度的头，拿到长度后再读对应字节数的体。这种结构解决的是 TCP 的粘包和半包问题，也是绝大多数二进制协议的通用做法。具体字段设计如下表，这是经过几轮迭代后比较顺手的一版：

固定头合计 16 字节，body 长度由 length 字段决定。这个结构的好处是解码器只要读满 16 字节就能知道后面还要等多少字节，不用猜。requestId 是个容易被忽略但很实用的字段，异步场景下服务端处理完请求要回给客户端，客户端得知道这是哪条请求的响应，靠这个字段配对。

注意：length 字段一定要明确它表示的是 body 长度还是整包长度，这个约定含糊不清是后期最大的隐患之一，客户端和服务端两边理解不一致会直接导致解码错位。

2.2 字段语义与字节序约定

字节序是另一个必须写进文档的点。Java 默认是大端序（Big Endian），Netty 的 ByteBuf 默认也是大端，所以推荐统一用大端，别混着来。如果客户端是某些嵌入式平台，小端更自然，那就在文档里强制写清楚，解码时用 ByteBuf 的 order 方法做转换，别指望两边默认一致。

魔数我用的是一组固定字节，用来在连接建立初期做一次合法性判断。设备侧如果不小心连错了端口，服务端读到的前四个字节大概率对不上魔数，可以直接关连接。这里有个细节：魔数校验不通过的时候不要急着抛异常，先看是不是收到了某些扫描流量，直接关闭就行，日志按需打。我在生产环境见过有服务端每次收到非法连接都打一条 ERROR 加完整堆栈，结果日志被刷爆，磁盘直接写满，清理起来非常麻烦。

version 字段第一版可能没什么用，但一定要留。将来协议升级，服务端可以根据 version 做分支处理，兼容老设备。这个字段只需要一个字节，成本极低，收益极大。serializer 字段则是为了应对序列化方案切换，比如早期用 JSON 图方便，后期为了省带宽换 Protobuf，老设备还发 JSON，新设备发 Protobuf，服务端两个解码分支都留着，平滑过渡。

2.3 序列化选型与版本兼容

body 里放什么，是自定义协议里最需要权衡的地方。常见三类选择各有各的适用面。

JSON 胜在可读、调试方便，Java 侧用 Jackson 或者 Fastjson 都能很快接上，缺点是体积大、解析慢。中小消息量、开发效率优先的场景，JSON 完全够用。Protobuf 是二进制编码，体积大概是 JSON 的三分之一到五分之一，解析也快，缺点是要维护 proto 文件，前后端要一起生成代码，改字段有流程成本。JDK 原生序列化最省事但最不推荐，体积大、跨语言差、还有安全问题，生产环境基本不要考虑。

我的做法是在 serializer 字段上预留多个枚举值，服务端写一个序列化工厂，根据这个字节选择对应的序列化器。这样一来，协议本身不用动，切换序列化方式只是换个标识。工厂类的结构大概是这样：

public interface Serializer { byte getType(); byte[] serialize(Object obj); <T> T deserialize(byte[] bytes, Class<T> clazz); }

然后根据 type 注册到 Map 里，用的时候查表。这个模式看起来多写了几行，但后面换实现的时候你就知道值了，业务代码一行都不用改。还有一个容易踩的坑是序列化器的线程安全问题，像 Jackson 的 ObjectMapper 是线程安全的，可以复用；有些自定义的序列化器不是，那就得用 ThreadLocal 或者每次新建，这个要看具体实现，别想当然。

3. 编解码落地：半包、粘包一次说透

3.1 LengthFieldBasedFrameDecoder 五个参数怎么算

TCP 是字节流协议，它只保证字节顺序，不保证一次发送对应一次接收。客户端连续发了两条消息，服务端可能一次读到两条拼在一起，这叫粘包；也可能一次只读到半条，这叫半包。解决思路就是前面说的定长头带长度字段，而 Netty 已经把这件事封装好了，就是 LengthFieldBasedFrameDecoder。

这个类有五个构造参数，很多人第一次用都是靠试，其实按公式算就很清楚。设：

• maxFrameLength：单帧最大长度，防攻击用，我一般给 8MB。
• lengthFieldOffset：长度字段在报文里的起始位置，我们这个协议里它前面有 magic(4)+version(1)+serializer(1)+type(1)+status(1)+requestId(4)，合计 12 字节，所以是 12。
• lengthFieldLength：长度字段自身占几个字节，我们是 4。
• lengthAdjustment：长度值需要额外补多少字节才是整帧长度，公式是 lengthAdjustment = 整帧长度 - lengthFieldOffset - lengthFieldLength - length值。我们的 length 值等于 body 长度，整帧长度等于 16 + body 长度，代入得到 16 + body - 12 - 4 - body = 0。所以填 0。
• initialBytesToStrip：解码后往前跳过的字节数。填 0 表示把包含头的整帧交给下游，让自定义解码器自己读头；填 16 表示直接只给 body。因为后面的自定义解码器还需要读 type、serializer 这些头部字段，所以这里填 0。

构造出来就是：

new LengthFieldBasedFrameDecoder(8 * 1024 * 1024, 12, 4, 0, 0)

这个参数是整套服务里最容易配错的地方。配错的典型表现是消息时对时错，或者只有在低并发下正常、压测时乱掉。我建议是拿纸把报文结构画出来，标上每个字段的偏移量，然后逐个代入公式验算一遍，别凭感觉。

3.2 自定义解码器与魔数校验

帧拆好了，接下来要把 ByteBuf 变成 Java 对象。这一步我用一个继承自 ByteToMessageDecoder 的解码器来做。注意继承这个类而不是 MessageToMessageDecoder，原因是我们需要拿到原始字节，做头部的二次校验和按需读取。

处理逻辑分几步走：先判断可读字节数是否够一个头（16 字节），不够就 return，等下一次数据；然后读魔数，对不上就抛异常并关闭连接；接着挨个读 version、serializer、type、status、requestId、length；再判断可读字节是否够 length 个，不够就 resetReaderIndex 后 return，等数据补齐；最后把 body 读出来，反序列化成对象，封装成 Message 交给下游。

这里有个必须强调的细节，就是 resetReaderIndex。如果发现 body 还没收全，记得把读指针回退到读头之前的位置，否则下一次进来的数据会被当成新头来解析，逻辑就全乱了。这个 bug 我栽过，现象是消息越大越容易出错，小消息反而正常，排查了很久。代码骨架大概是：

public class MessageDecoder extends ByteToMessageDecoder { @Override protected void decode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) { if (in.readableBytes() < HEADER_LENGTH) { return; } in.markReaderIndex(); int magic = in.readInt(); if (magic != PROTOCOL_MAGIC) { ctx.close(); return; } byte version = in.readByte(); byte serializer = in.readByte(); byte type = in.readByte(); byte status = in.readByte(); int requestId = in.readInt(); int length = in.readInt(); if (in.readableBytes() < length) { in.resetReaderIndex(); return; } byte[] body = new byte[length]; in.readBytes(body); Message msg = new Message(); msg.setType(type); msg.setSerializer(serializer); msg.setRequestId(requestId); msg.setBody(SerializerFactory.get(serializer).deserialize(body, MsgBody.class)); out.add(msg); } }

写完这段最好写几个单元测试，用 EmbeddedChannel 直接喂字节，验证半包、粘包、魔数错误三种情况都能正确处理。Netty 自带的 EmbeddedChannel 就是干这个的，比启动真实服务省事得多，也更容易覆盖边界。

3.3 编码器实现与 ByteBuf 的释放责任

编码是反向操作，继承 MessageToMessageEncoder，把 Message 对象按协议格式写成 ByteBuf。写的时候注意顺序不能错，magic、version 这些字段一个都不能漏，否则对端解析必然失败。一般用 ctx.alloc().buffer() 申请缓冲区，然后按顺序 write。

内存释放是 Netty 里最容易出事故的地方。Netty 的 ByteBuf 用的是引用计数，谁申请谁释放是基本原则。简单说，继承 SimpleChannelInboundHandler 的 Handler 会自动释放消息，而继承 ChannelInboundHandlerAdapter 的需要自己手动 release。如果你把消息对象从 IO 线程传到业务线程池，跨线程传递过程中引用计数的归属就变得复杂，处理不好就是内存泄漏，表现是堆外内存一路涨，最后 OOM。

我的做法是尽量在 Handler 里就把消息解析成普通 POJO，把 ByteBuf 的生命周期控制在最窄的范围内，不要带着 ByteBuf 到处传。如果确实需要传，用 retain 明确增加计数，用完 release。排查泄漏的时候，可以给 JVM 加上堆外内存的追踪参数，配合 Netty 自带的泄漏检测级别调到 PARANOID，能在日志里看到是哪一行申请没释放。这个参数线上别开，性能损耗不小，只在测试环境排查用。

4. Spring Boot 集成 Netty 的完整启动链路

4.1 依赖与线程组配置

依赖上没什么特别的，一个 spring-boot-starter 加 netty-all 就够了。要注意版本对齐，如果你同时还引了别的框架自带了 Netty，可能会出现版本冲突，通过 mvn dependency:tree 看一眼，冲突就排除掉，避免出现类找不到或者行为诡异的兼容问题。

NioEventLoopGroup 分两个，boss 组负责接收连接，worker 组负责处理读写。boss 组的线程数一般给 1 就够，因为它只处理 accept 事件，给多了浪费。worker 组默认是 CPU 核数乘 2，这个值对 IO 密集型的服务够用，如果你的业务逻辑在 IO 线程里做得比较多，可以适当调大，但更推荐的做法是把业务逻辑挪出去，而不是无脑加线程数。线程数越大，上下文切换的开销也越大。

4.2 启动、端口绑定与优雅停机

服务端启动的流程是：构造 ServerBootstrap，设置两个线程组，指定 NioServerSocketChannel，配置 ChannelOption，设置 childHandler 里的 Pipeline，最后 bind 端口。这里有两个 ChannelOption 值得关注。SO_BACKLOG 表示连接队列长度，压测时如果看到大量连接被拒，多半是这个值太小。SO_KEEPALIVE 开启 TCP 层面的保活，但它的探测周期由操作系统决定，通常是两小时，对你的业务来说太慢了，所以真正的保活还得靠应用层心跳。

优雅停机是很多项目忽略的一点。直接 System.exit 或者 kill -9 会导致正在处理的请求被掐断，客户端收到连接重置。正确的做法是拿到 Channel 和 EventLoopGroup，调用 shutdownGracefully，给一个静默期，让正在飞的消息处理完，同时不再接收新连接。Spring Boot 里可以监听 ContextClosedEvent，在事件回调里做这件事。这个细节在测试环境几乎看不出来，上线滚动发布的时候就是它保证用户体验。

端口占用报错也是高频问题，Address already in use 通常不是端口真被占了，而是上一次的服务没停干净，或者你在同一个 JVM 里启动了两个实例。有个小技巧是设置 SO_REUSEADDR，让重启时能立刻复用处于 TIME_WAIT 状态的端口，避免等待。

4.3 Handler 与 Spring Bean 的桥接

这是 Spring Boot 集成 Netty 最关键的一环。Netty 的 Handler 是每次连接建立时 new 出来的，不是 Spring 容器管理的 Bean，所以你不能在 Handler 里用 @Autowired。常见的做法有两种。

一种是写一个 Spring 的配置类，实现 ApplicationContextAware，把 ApplicationContext 存到静态变量里，Handler 里通过 getBean 拿。这种做法能用，但破坏了依赖注入的清晰性，测试也麻烦。

另一种更干净的做法是把业务 Service 通过构造方法传给 ChannelInitializer。因为 ChannelInitializer 本身是可以做成 Spring Bean 的，它持有 Service 的引用，在 initChannel 回调里 new 业务 Handler 时把 Service 传进去。这样依赖关系是显式的，也好测。我一般用第二种，代码结构大概是这样：

@Component public class ServerChannelInitializer extends ChannelInitializer<SocketChannel> { private final BizService bizService; public ServerChannelInitializer(BizService bizService) { this.bizService = bizService; } @Override protected void initChannel(SocketChannel ch) { ChannelPipeline p = ch.pipeline(); p.addLast(new IdleStateHandler(60, 0, 0, TimeUnit.SECONDS)); p.addLast(new LengthFieldBasedFrameDecoder(8 * 1024 * 1024, 12, 4, 0, 0)); p.addLast(new MessageDecoder()); p.addLast(new MessageEncoder()); p.addLast(new BizHandler(bizService)); } }

注意：Pipeline 里 Handler 的添加顺序就是执行顺序，解码器必须在业务 Handler 之前，编码器放在哪影响不大但一般紧跟解码器。顺序错了会出现业务 Handler 收到的是 ByteBuf 而不是 Message，然后一路 ClassCastException。

5. 连接管理：心跳、鉴权与在线会话

5.1 IdleStateHandler 的三种空闲检测

长连接不可能一直有数据，中间经过 NAT 网关、防火墙，空闲时间长了连接会被静默断开，双方都不知道。解决办法就是心跳。Netty 提供了 IdleStateHandler，三个参数分别是读空闲、写空闲、读写都空闲的时间阈值，单位可以指定。触发后会抛出一个 IdleStateEvent，你在 Handler 的 userEventTriggered 方法里处理。

我的配置是读空闲 60 秒。如果 60 秒没收到客户端任何数据，就认为连接不健康，主动发一个心跳请求过去，如果连续几次都没有回应，就关闭连接。为什么不直接用写空闲？因为写空闲是基于服务端有没有往外发数据，而服务端可能长时间只收不发，这种情况写空闲不会触发。读空闲更贴近真实需求。

客户端侧也要做对称的心跳发送，一般是 30 秒发一次。服务端 60 秒没收到就判定异常，这个时间差给了容忍度，避免因为一次网络抖动就误判。心跳包本身要尽量小，就是一个只有头、body 长度为 0 的报文，用 type 字段区分。

5.2 会话上下文与鉴权流程

连接建立之后需要一个地方存这个连接的状态，比如是否已鉴权、绑定的设备 ID、最近一次心跳时间。我用的是 AttributeKey 挂到 Channel 上，这是 Netty 官方推荐的做法。每个 Channel 可以理解成一个独立的会话，Channel 关闭时属性自动回收，不用你手动清理。

鉴权流程上，我建议第一条消息必须是鉴权消息，带设备 ID 和令牌。服务端校验通过后在 Channel 的 AttributeKey 里打标，后续消息进来先检查这个标记，没鉴权的直接拒绝并关闭连接。这样做的好处是防止未授权连接占用资源，也避免业务 Handler 里到处写鉴权判断。校验逻辑如果涉及查数据库或者远程调用，一定要考虑超时和失败降级，不能因为鉴权服务挂了就把所有设备连接都堵住。

会话管理还有一个绕不开的组件：在线连接表。做服务端推送的时候，需要根据设备 ID 找到对应的 Channel。用一个 ConcurrentHashMap 维护 deviceId 到 Channel 的映射，连接关闭时记得移除，否则会造成内存泄漏，时间长了这个 Map 会无限膨胀。移除的逻辑放在 channelInactive 里做，这个回调在连接断开时一定会触发。

5.3 耗时业务与 IO 线程隔离

前面反复提到不要让业务拖住 IO 线程，具体怎么做。最简单的方式是在 Pipeline 里给业务 Handler 单独指定一个 EventExecutorGroup，这样 Handler 的执行就切换到另一个线程组，IO 线程可以立刻返回继续处理读写。代价是多一次线程切换，但比起被慢查询卡死整个连接组，这点代价完全值得。

另一种方式是在 Handler 里把任务丢给 Spring 管理的线程池，处理完再通过 Channel 写回结果。这种方式更灵活，可以做线程池隔离、可以做限流，但要特别注意 Channel 的线程安全。Channel 的 write 操作本身是线程安全的，它会自动把任务调度回对应的 EventLoop，所以你在业务线程里直接调 writeAndFlush 是没问题的，这一点可以放心。

线程池的参数要根据业务量算。假设单机要扛 5 万连接，每连接平均每 10 秒发一条消息，那就是每秒 5000 条，单条处理平均耗时 20 毫秒，那么并发处理需要的线程数大概是 5000 乘 0.02，等于 100 个线程。这是一个粗略估算，实际还要看峰值系数和下游承载能力。别把核心线程数设得过大，超过了后面排队比直接拒绝更糟，队列有界、拒绝策略明确，这是我一贯的做法。

6. 上线前后踩过的坑与排查手法

6.1 典型异常速查表

下面这张表是我这几年攒下来的，基本覆盖了自定义协议服务端最常见的问题。

排查的时候，抓包工具是最直接的。自己写个小的客户端脚本，把报文按十六进制打出来，跟协议文档逐字节对照，比盯着代码看快得多。另外日志里把 requestId 打全，一条请求从进来到出去能串起来，遇到偶发问题才有迹可循。

6.2 内存泄漏与引用计数

堆外内存泄漏是最难查的一类问题，因为它不进堆，普通的堆转储看不到。判断方法很简单：看进程的 RSS 是不是明显比堆内存大，而且随时间持续增长。如果确认是 Netty 的 ByteBuf 没释放，就要把泄漏检测级别开起来，会在日志里打出创建这个缓冲区的那一行代码，定位效率高很多。

常见的泄漏场景有这么几个。一是 Handler 继承错了，用了 ChannelInboundHandlerAdapter 却当成 SimpleChannelInboundHandler 那样不管释放，而且没在 finally 里 release。二是把 ByteBuf 存到成员变量或者静态集合里，连接断了也没清。三是在异常分支里没有释放，正常路径没问题，一出错就漏，这种最难发现。建议是在 Handler 里统一用一种风格，要么全程 SimpleChannelInboundHandler 自动释放，要么全程手动 release 并且在 finally 里写，别混着来。

6.3 压测与容量评估的做法

压测这块，我的经验是不要一上来就冲最大并发，先做阶梯式加压。比如从 1000 连接开始，每层跑 10 分钟，观察 CPU、内存、GC 频率、每条消息的 P99 延迟，找到指标开始明显劣化的拐点，那个点往下打八折才是比较安全的容量。

压测客户端要注意别自己成为瓶颈。用单机开几万个连接，光是客户端本身的线程和内存就先扛不住了，最好多机分布式压测。消息内容也要贴近真实，别发空包，空包跳过了序列化和业务处理，测出来的数据虚高。另外要专门测一下异常路径，比如消息体超长、字段非法、连接频繁中断重连，这些在真实环境里天天发生，但在压测里经常被忽略。

监控上最少要有这几个指标：当前连接数、每秒收发消息数、平均和 P99 处理耗时、事件队列的积压情况。Netty 的 EventLoop 如果出现任务积压，说明有阻塞操作混进来了，这是个很灵敏的信号。把这些指标接到现有的监控体系里，出问题的时候能第一时间定位到是哪一层的事。

最后分享一个我自己的习惯，就是把协议文档和代码放在一起维护，每改一个字段就同步更新文档里的偏移量表，并且在启动日志里打印当前协议的版本号和头长度。这样做的好处是，当线上出现版本不一致的时候，看一眼启动日志就能判断服务端跑的是哪版，比翻代码快多了。协议这东西，改起来最贵的是沟通成本，把文档和代码绑死，能省下大量扯皮的时间。