SpringBoot集成Netty自研TCP/UDP服务端：从粘包拆包到生产级实践

1. 项目定位与整体设计思路

1.1 为什么物联网通信首选Netty自研服务端

做物联网开发的人基本都绕不开一个需求：设备端（温湿度传感器、智能电表、车载GPS终端、充电桩桩体）要往服务端上报数据，服务端要下发控制指令。这个场景下最常见的通信协议就是TCP和UDP，而服务端的通信底座用什么做，直接决定了后面能支撑多少设备、出问题时好不好排查。

很多团队初期会直接选MQTT Broker（比如EMQX、Mosquitto），用现成的消息中间件来解决通信问题。这种做法胜在快，几行配置就能上线。但用到后面就会出现几个让人头疼的情况：私有协议的定长帧或自定义报文头没地方做解析、设备的状态在线维护做得不够细、需要对某些特定设备做透传转发时被Broker的Topic模型绑死了手脚。这时候你就需要一套自己能掌控的TCP/UDP服务端，Netty就是做这件事最成熟的选择。

那为什么又一定要把Netty嵌到SpringBoot里？原因很实在。Netty本身是一个独立的网络框架，不依赖Spring也能跑，但在一个标准的企业级项目里，设备上报的数据最终要落到数据库、要触发业务告警、要通知前端WebSocket推送，这些能力SpringBoot生态里全都有现成的。把Netty的服务端作为Spring容器中的一个受管Bean，让它跟SpringBoot共享一套配置体系、一套依赖注入、一套生命周期管理，工程上才算完整。

这套方案我前前后后在智能充电桩和冷链运输监控两个项目上验证过。单机撑过三五千个TCP长连接、每秒转发几千条UDP报文都还算稳，关键是遇到问题能在代码层面去定位，心里有底。这篇文章就把从零搭建到生产可用的完整路子捋一遍，代码和配置都直接可抄。

1.2 核心目标拆解：不止是“能通”而是“能扛”

如果只是写一个Demo级别的服务端，网上示例一大把，但那些示例多数活不过生产环境。这篇文章要解决的是三个层面的问题：第一个层面是把TCP和UDP服务端跑起来，接收数据、返回响应；第二个层面是解决Netty开发里最容易出问题的粘包和半包，让每个数据包都能被业务层完整拿到；第三个层面是把服务端生命周期交给SpringBoot管理，应用重启、发版、宕机恢复时连接不残留、端口不冲突。

围绕这三个目标，整个项目的模块划分是这样的：

这个结构拆出来之后，TCP的代码和UDP的代码互相不掺和，各自独立启动独立监听。后面想扩展其他端口、其他协议，照着这个模式继续加模块就行，不会动到已有功能。

2. 环境准备与工程依赖选型

2.1 SpringBoot版本与JDK版本的取舍建议

Netty和SpringBoot的配合在版本上没有特别苛刻的要求，但我在两个项目里实际踩过不同的坑，给你一个比较稳妥的组合方案：SpringBoot 2.7.x系列配JDK 8或JDK 11，Netty 4.1.x系列。这个组合有两个好处：一是SpringBoot 2.7是2.x时代的成熟稳定版本，网上能搜到的资料最多，遇到问题最容易找到答案；二是Netty 4.1.x本身维护周期非常长，从4.1.0到现在的4.1.9x一直持续迭代，API层面高度稳定，不会有频繁的破坏性变更。

如果你的团队已经上了JDK 17，那可以考虑SpringBoot 3.x系列，对应Netty依赖也升级到4.1.x以上的较新版本。但注意SpringBoot 3的jakarta命名空间改动比较大，很多老教程里的javax导入会直接编译报错，新手不建议从3.x起步。

搜索热词里有个“springboot版本太高”不是没有原因的。有些同事用了SpringBoot 3.3甚至更高版本，引入Netty之后偶尔会出现netty-handler和netty-transport版本冲突的问题。我的建议是：能锁版本就不要用传递依赖，直接在pom里显式声明netty-all。

2.2 引入Netty依赖：一个依赖还是按需引入

Netty的依赖管理有两种做法。第一种是引入全家桶netty-all，好处是省心，不用关心哪些模块需要哪些不需要，坏处是jar包体积偏大。第二种是按需引入netty-buffer、netty-transport、netty-codec、netty-handler这几个核心模块，工程会更干净。

我个人的习惯是直接用netty-all，原因很简单：物联网项目里后期大概率会用到新增的编解码器或SSL能力，把这些零散依赖一个一个补齐的时间成本不值当。在Maven里这样加：

xml复制<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-all</artifactId>
    <version>4.1.104.Final</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Netty 4.1.104.Final这个版本是2024年初发布的稳定版，我已经在好几个生产项目里用过了，没碰到过已知的重大缺陷。版本号记得不要漏掉Final后缀，Netty的版本约定里这个后缀表示正式发布版。

3. TCP服务端核心实现：从启动到粘包处理

3.1 ServerBootstrap配置的每一个参数都在解决什么问题

TCP服务端启动的逻辑全部放在TcpNettyServer这个类里。使用ServerBootstrap组装服务端，核心配置分三块：线程模型、Channel类型、ChannelHandler链。

先看线程模型。Netty的Reactor线程模型理解起来用餐厅做类比最合适：EventLoopGroup就是餐厅里的服务生团队，bossGroup是门口负责迎宾的服务生，只接待新来的客人（连接请求），workerGroup是厅里的服务生，负责给已经入座的客人上菜（读写事件）。迎宾和上菜分给两拨人，高峰期的接待能力才能上去。

java复制@Slf4j
@Component
public class TcpNettyServer {

    private EventLoopGroup bossGroup;
    private EventLoopGroup workerGroup;
    private Channel serverChannel;

    @Value("${netty.tcp.port:9100}")
    private int tcpPort;

    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, 1024)
                    .childOption(ChannelOption.TCP_NODELAY, true)
                    .childOption(ChannelOption.SO_KEEPALIVE, true)
                    .childHandler(new TcpServerInitializer());
            
            ChannelFuture future = bootstrap.bind(tcpPort).sync();
            serverChannel = future.channel();
            log.info("TCP服务端启动成功，端口：{}", tcpPort);
        } catch (Exception e) {
            log.error("TCP服务端启动失败", e);
            shutdown();
            throw e;
        }
    }
    
    public void shutdown() {
        if (serverChannel != null) {
            serverChannel.close();
        }
        if (bossGroup != null) {
            bossGroup.shutdownGracefully();
        }
        if (workerGroup != null) {
            workerGroup.shutdownGracefully();
        }
        log.info("TCP服务端已关闭");
    }
}

配置参数里有两个容易忽略但实际很重要的选项：SO_BACKLOG和TCP_NODELAY。SO_BACKLOG是操作系统层面的连接等待队列长度，也就是系统还没把连接交给Netty处理时，最多能排多少队。设备短时间内集中上线时这个值太小会丢连接。TCP_NODELAY是关闭Nagle算法，让每个小包都立刻发出去。控制指令这种报文通常只有几十字节，开了Nagle算法会把小包攒到一起再发送，直观感受就是指令下发有可感知的延迟，所以一定要设成true。

ChannelInitializer是每一路新连接创建时都会执行一次的逻辑，把编解码器和业务Handler组装成一条流水线。这里注意一个关键点：ChannelInitializer里new出来的Handler默认不是Spring容器里的Bean，如果你在Handler里直接@Autowired注入Service，得到的会是null。这是Netty和SpringBoot集成最经典的坑，后面单独开一节讲解决办法。

3.2 自定义Handler的职责划分与@Autowired失效问题

Handler链的职责划分很讲究，不要在同一个Handler里既做字节解析又做业务处理。我的标准做法是拆成两条链路：解码链路和业务链路。解码链路负责把ByteBuf变成业务对象，业务链路负责把业务对象转发给Spring的Service。

java复制public class TcpServerInitializer extends ChannelInitializer<SocketChannel> {

    @Override
    protected void initChannel(SocketChannel ch) {
        ChannelPipeline pipeline = ch.pipeline();
        // 解码器：处理粘包和拆包，输出byte[]或自定义对象
        pipeline.addLast(new ByteBufToMessageDecoder());
        // 业务Handler：解析出的完整报文会走到这里
        pipeline.addLast(new TcpBusinessHandler(SpringContextUtils.getBean(DeviceDataService.class)));
        // 异常处理Handler：统一收拢异常避免连接泄漏
        pipeline.addLast(new ExceptionHandler());
    }
}

这里SpringContextUtils.getBean()是解决@Autowired为null的关键手段。本质原因是：ChannelHandler的实例化发生在Netty自身的线程模型里，由ChannelInitializer内部的initChannel方法new出来，压根不走Spring的IoC容器。所以不能在字段上用@Autowired做依赖注入，必须主动从Spring容器上下文里获取Bean。

写一个工具类：

java复制@Component
public class SpringContextUtils implements ApplicationContextAware {

    private static ApplicationContext applicationContext;

    @Override
    public void setApplicationContext(ApplicationContext context) {
        applicationContext = context;
    }

    public static <T> T getBean(Class<T> clazz) {
        return applicationContext.getBean(clazz);
    }
}

这个类本身要交给Spring管理，通过ApplicationContextAware拿到容器引用，然后静态方法全局共享。在Handler里需要什么Service就从里面取什么Service。这种写法在Spring官方文档里虽然不算推荐方式，但在Netty这类脱离Spring容器管理的组件里属于通用实践，实际用下来没有任何问题。

3.3 粘包拆包的原理与LengthFieldBasedFrameDecoder参数计算

握手和心跳都好处理，粘包才是网络上传输中最容易踩坑的地方。粘包的根本原因要从TCP的流式传输说起。TCP像一根自来水管，数据是源源不断流过去的水，TCP自己不知道“一条消息”的边界在哪。发送方连续发送两条消息时，接收方可能一次就读到了两条，这叫粘包；如果一条消息被拆成多个TCP段传输，接收方第一次只读到半条，这叫半包。UDP是报文协议不存在这个问题，TCP必须自己解决。

解决粘包的办法就叫“拆包”，核心思路是在每个消息里带上长度字段，接收方根据长度字段来切分数据。Netty提供的LengthFieldBasedFrameDecoder就是做这个的。假设设备上报的报文格式是：2字节的消息头0xAA 0x55，2字节的消息体长度，接下来是消息体。那解码器应该这样写：

java复制public class ByteBufToMessageDecoder extends ByteToMessageDecoder {

    private static final int HEADER_LENGTH = 2;
    private static final int MAX_FRAME_LENGTH = 1024 * 1024;

    @Override
    protected void decode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) {
        // 添加LengthFieldBasedFrameDecoder到pipeline时通常会做，但这里我们选择直接继承ByteToMessageDecoder
        // 实际项目中推荐直接在TcpServerInitializer里加LengthFieldBasedFrameDecoder
    }
}

更标准的做法是在TcpServerInitializer里直接把LengthFieldBasedFrameDecoder加进pipeline，然后后面接自己的业务解码器。参数计算方式如下：

java复制pipeline.addLast(new LengthFieldBasedFrameDecoder(
        1024 * 1024,   // maxFrameLength: 最大帧长度，超过这个长度会抛出异常，防止内存被恶意占用
        2,             // lengthFieldOffset: 长度字段起始位置的偏移量，跳过2字节的消息头
        2,             // lengthFieldLength: 长度字段本身的字节数，这里是2字节表示长度
        0,             // lengthAdjustment: 长度字段值是否需要修正。如果长度字段值包含了消息头的2字节，这里需要设成-2
        0              // initialBytesToStrip: 解码后需要跳过的字节数。如果下发指令需要用到消息头，这里设0保留完整报文
));

这套参数要对照着设备的报文协议文档一个一个确认。很多新手在这里凭感觉填，结果就是要么拿到的数据全乱了，要么一堆TooLongFrameException堆在日志里。设备消息格式如果长度字段表示的是“整个报文的总长度”，那么lengthAdjustment要填负数，把消息头的长度减掉；如果表示的是“长度字段之后的字节数”，那lengthAdjustment就是0。

加上解码器之后，业务Handler拿到的就是一个完整的ByteBuf，然后你可以按照业务协议去解析消息体中的设备编号、数据类型、数据值等字段。这样粘包问题从根上就被TCP层处理掉了。

3.4 心跳机制和用户主动下线处理

物联网设备在线状态维护是服务端必须做的功课。TCP长连接场景里经常出现“假死连接”——设备断电了、4G信号断了，TCP连接在操作系统层面没有及时探测到，服务端以为设备还在线。Netty提供了IdleStateHandler来做空闲检测：

java复制pipeline.addLast(new IdleStateHandler(60, 0, 0, TimeUnit.SECONDS));

第一个参数60表示60秒内既没有读也没有写操作时触发IdleStateEvent。在业务Handler里重写userEventTriggered方法，收到IdleStateEvent就代表这条连接已经空闲太久了，可以主动关闭，也可以先发一个心跳探测报文等对方回复，等不到再关。我用的是先发心跳报文、连续三次无响应再关闭的连接释放策略。

还有一个很容易忽略的点是channelInactive方法的处理。设备主动断开、网络异常断开，都会走到这个回调，在这里把设备标记为离线，并且把缓存在内存里的Channel对象移除。如果不移除，后面给设备下发指令时就会往一个已经失效的Channel上写数据，虽然Netty会吞掉异常，但日志里会时不时冒出NotYetConnectedException之类的东西干扰判断。

4. UDP服务端实现：轻量级通信的正确打开方式

4.1 TCP和UDP的选型依据

TCP长连接适合指令下发和状态上报都高频的场景，UDP则适合数据上报频率高、允许少量丢包、不需要服务端响应的场景。我做过的冷链运输监控项目就是典型的UDP适用场景：每台冷藏车上的温度采集终端每隔30秒发一条UDP报文上网关注册和上报温度，数据量小、频率稳定、丢几条也不影响业务判断，用TCP反而占用大量连接资源。

Netty的UDP服务端和TCP最大区别在于Channel类型和启动方式。UDP没有连接的概念，所以不需要ChildHandler那一套，直接在初始化时指定NioDatagramChannel：

java复制@Slf4j
@Component
public class UdpNettyServer {

    private EventLoopGroup group;
    private Channel serverChannel;

    @Value("${netty.udp.port:9200}")
    private int udpPort;

    public void start() throws InterruptedException {
        group = new NioEventLoopGroup();
        try {
            Bootstrap bootstrap = new Bootstrap();
            bootstrap.group(group)
                    .channel(NioDatagramChannel.class)
                    .option(ChannelOption.SO_BROADCAST, true)
                    .option(ChannelOption.SO_RCVBUF_SIZE, 1024 * 1024)
                    .handler(new UdpMessageHandler());
            
            ChannelFuture future = bootstrap.bind(udpPort).sync();
            serverChannel = future.channel();
            log.info("UDP服务端启动成功，端口：{}", udpPort);
        } catch (Exception e) {
            log.error("UDP服务端启动失败", e);
            shutdown();
            throw e;
        }
    }
    
    public void shutdown() {
        if (serverChannel != null) {
            serverChannel.close();
        }
        if (group != null) {
            group.shutdownGracefully();
        }
    }
}

SO_BROADCAST打开之后服务端才能向广播地址发送广播包。这在局域网设备发现场景很有用：设备上线时往255.255.255.255发一条广播报文，服务端收到后可以单播回复一个带服务器地址的报文，设备就能切换成正式上报模式。

4.2 UDP Handler的报文读取和响应发送

UDP的消息处理回调在channelRead0里，接收到的对象是DatagramPacket，里面封装了发送方的SocketAddress和数据内容。这个设计比TCP灵活得多——不需要维护一堆Channel连接，每次收到报文都能拿到对方的地址，想回包就new一个DatagramPacket发过去。

java复制@Slf4j
public class UdpMessageHandler extends SimpleChannelInboundHandler<DatagramPacket> {

    @Override
    protected void channelRead0(ChannelHandlerContext ctx, DatagramPacket packet) {
        ByteBuf content = packet.content();
        byte[] data = new byte[content.readableBytes()];
        content.readBytes(data);

        SocketAddress sender = packet.sender();
        log.info("收到UDP报文，来源：{}，数据：{}", sender, HexUtil.encodeHexStr(data));

        // 按业务协议解析数据，示例：前2字节是设备ID，第3字节是消息类型
        // 解析完成交给Service处理
        UdpMessageService messageService = SpringContextUtils.getBean(UdpMessageService.class);
        messageService.processMessage(data);

        // 需要响应时，构造响应报文返回
        ByteBuf responseBuf = Unpooled.wrappedBuffer(buildResponseMessage(data));
        ctx.writeAndFlush(new DatagramPacket(responseBuf, sender));
    }
}

UDP Handler有一个地方要特别注意：SimpleChannelInboundHandler会自动释放接收到的数据包的引用计数，如果你把数据包里的ByteBuf直接交给异步线程处理，异步线程里再用会报引用计数错误。标准做法是在Handler里把字节数组拷贝出来再传下去，就像上面代码做的那样，后面无论怎么处理都是安全的。

4.3 UDP多播场景的支撑方式

有些物联网项目会用到组播（Multicast），典型场景是局域网内批量升级设备固件，一条组播报文能给一组设备同时送达。Netty对组播的支持是开箱即用的，在Channel初始化时设置网络接口和组播地址即可。组播功能的开启依赖系统路由表的正确配置，路由器或交换机的IGMP Snooping如果没开，组播报文会被当成广播在所有端口扩散，这些都是现场调试时要留个心眼的经验。

5. SpringBoot生命周期管理与网关注册中心联动

5.1 启动注入与优雅关闭的正确姿势

Netty服务端要跟着SpringBoot应用一起启动一起关闭，这是“集成”的第二层意义。用ApplicationRunner接口可以在Spring容器初始化完成后、应用正式对外提供服务之前，把Netty服务端拉起来：

java复制@Component
public class NettyServerLifecycle implements ApplicationRunner {

    @Resource
    private TcpNettyServer tcpNettyServer;
    @Resource
    private UdpNettyServer udpNettyServer;

    @Override
    public void run(ApplicationArguments args) {
        try {
            tcpNettyServer.start();
            udpNettyServer.start();
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new RuntimeException("Netty服务启动失败", e);
        }
    }
}

关闭这里要细说。直接把SpringBoot应用Ctrl+C杀掉，Netty的EventLoopGroup如果不是守护线程，进程会卡在那里退不出去。正确做法是注册一个DisposableBean或者用@PreDestroy注解，在Spring容器销毁前主动释放Netty线程资源：

java复制@PreDestroy
public void destroy() {
    tcpNettyServer.shutdown();
    udpNettyServer.shutdown();
}

对于线上部署，kill命令发给应用的信号是SIGTERM，SpringBoot会触发@PreDestroy的执行，Netty优雅关闭时会把积压在网络缓冲区里的数据尽量处理完毕再释放线程，设备端短暂感知到连接断开后重新拨号连上来，整个过程基本无感知。

5.2 端口和线程数配置外置到application.yml

不要把这些参数硬编码在类里，全部放到application.yml：

yaml复制netty:
  tcp:
    port: 9100
  udp:
    port: 9200
  boss-thread-count: 1
  worker-thread-count: 8

worker-thread-count默认值是CPU核数的两倍。如果你的机器是2核4线程，默认就是8个worker线程，撑几万个长连接也够用了。但要注意一个最常见的性能陷阱：Handler里绝对不能写阻塞操作，比如直接查数据库、调第三方HTTP接口。一旦worker线程被阻塞，后面的所有连接事件处理都会排队卡住。真要执行耗时任务，用单独的线程池异步处理。

用@ConfigurationProperties把这些配置映射成配置类，比到处写@Value清爽得多：

java复制@Component
@ConfigurationProperties(prefix = "netty")
@Data
public class NettyProperties {
    private Tcp tcp = new Tcp();
    private Udp udp = new Udp();
    
    @Data
    public static class Tcp {
        private int port = 9100;
        private int bossThreadCount = 1;
        private int workerThreadCount = 8;
    }
    
    @Data
    public static class Udp {
        private int port = 9200;
        private int threadCount = 4;
    }
}

5.3 设备上下线状态与在线维护

服务端收到设备上报后，除了把数据入库，通常还需要做在线状态维护。我在项目中维护了一张内存表加一张数据库表配合：内存表用ConcurrentHashMap<String, Channel>管理设备编号和Channel的映射，数据库表记录设备最新的在线时间。查询在线状态走内存表秒回，统计报表查数据库。Channel写入失败或触发channelInactive时，从内存表移除映射，异步更新数据库。

6. 生产环境常见问题排查与性能优化实录

6.1 部署到服务器后连接不上的排查清单

这个问题在Docker部署SpringBoot项目时出现频率最高。本地联调好好的，放到服务器上设备就是连不上，翻遍日志也没看见异常。标准排查顺序是：

还有一个容易被忽略的点：SpringBoot内嵌Tomcat默认端口是8080，Netty自己的端口是9100和9200，部署到云服务器时这三个端口都需要在安全组里放行。有些同事只放了8080，设备流量到了9100直接被云平台丢掉，现象就是连不上、还不报错。

6.2 @Autowired注入为null、连接池耗尽等典型问题速查表

这段把我在实际项目里踩过坑的高频问题整理成表格，每一个都是真实环境和别人问过我的：

CLOSE_WAIT这个问题很容易被忽略但后果很严重。设备端网络抖动后主动断开，服务端的Socket如果一直不关闭，系统资源会被慢慢耗尽，最终表现为新连接无法接入。排查时netstat看到大量CLOSE_WAIT，就得回头检查自己的Handler里有没有关闭连接。

6.3 性能优化：减少内存拷贝与批量处理

Netty性能优化有两个方向，一个方向是框架层面，另一个方向是代码层面。框架层面Netty已经通过零拷贝机制做了大量优化——FileRegion文件传输不走用户态内存、CompositeByteBuf组合缓冲区避免数据复制。代码层面最容易出效果的是减少ByteBuf的无谓复制：接收数据时按照解码器定义好的索引直接访问字段，而不是每次都copy()出一个新数组再解析。

高频上报场景下瓶颈往往在数据库写入。我做过一个GPS定位终端项目，每台车每5秒上报一次位置，几百台车同时跑起来每秒上千条写库请求。解决思路是先写入队列，批量攒一批再批量提交，能极大降低数据库压力。这个场景和热词里提到的项目全局过滤器处理上传文件场景不同，但思路相通——高频小操作用队列削峰。

从Netty层面保证线程模型不阻塞的同时，再把数据库写入削峰，单个4核8G的云服务器扛住每秒几千条的物联网报文是没问题的。

7. 我这个项目沉淀下来的工程化心得

项目做完整套TCP/UDP通信底座之后，有一个感受特别深：Netty这框架最难的地方不是写启动代码，而是你能不能在面对设备的私有协议时，把数据包稳定地处理好。粘包拆包、编解码器这些概念本质上都是在和设备协议打交道，协议文档里每个字节的含义是什么，映射到解码器参数里应该怎么算，这才是集成工作的核心分量。

从项目管理角度来看这套方案的收益非常直观。业务侧要加新功能，比如设备远程升级、指令下发优先级控制，只要在Handler链上增加对应的处理器就能完成，不需要改动通信底座。相对于每次需求变动就要动通信层的团队，这种按Handler划分职责的架构真的能让人省心很多。

最后分享一个我认为很有价值的小习惯：开发阶段记得在Handler里把收到的原始报文按十六进制打日志，上线后如果再出问题，就把线上日志和设备端的日志放在一起比对，绝大多数通信问题都能靠对端日志直接定位。物联网调试这件事，方法对了比经验多更重要。