CMPP3.0协议Java实现全解析：从登录鉴权到长连接保活

简介cmpp3.0_JAVA_实现是一套基于Java的CMPP3.0短信协议源码面向需要接入中国移动短信网关、实现短信发送接收和状态查询的Java开发人员。CMPP3.0协议覆盖SUBMIT提交、DELIVER下发、QUERY状态查询等核心命令并涉及发送、接收、查询、心跳等操作适用于企业短信平台、验证码通知、营销触达等场景。压缩包共17个文件包括14个Java源文件、2个txt说明文档和1个properties配置文件Java代码实现了协议编解码、GBK字符处理、TCP长连接与心跳、多线程收发、异常重试、日志记录、定时器管理等关键模块配置文件用于设定网关地址、端口、企业代码等参数文档则对定时器和消息格式做了补充说明。整个包体仅23KB结构紧凑无冗余依赖适合直接阅读学习或作为二次开发基础。目前已有947人学习下载对于正在做短信网关对接的工程师来说这份源码可省去从零编写协议栈的麻烦快速理解命令格式、状态管理与重试策略并可直接移植到现有系统中。 做过企业短信接入的同学应该都清楚CMPP协议这套东西看起来不复杂但真要用Java从头实现一遍坑全藏在细节里。CMPP3.0是中国移动面向SP/企业客户提供的短信网关接入协议相比HTTP API这种上层接口它直接工作在TCP层意味着你需要自己处理二进制报文、登录鉴权、连接保活、消息重发这些脏活。这篇内容我会围绕一个完整的Java实现来拆解适合那些不想用商业短信SDK、打算自己掌控协议细节的团队参考。1. CMPP3.0的协议轮廓报文结构、命令字与状态机在写第一行Java代码之前建议先花半小时把CMPP3.0的协议文档翻一遍。这个协议本质上是一个自定义的二进制TCP协议所有交互都围绕消息头消息体展开而且每一个操作都有严格的时序要求。我见过不少团队一上来就写代码结果连登录都过不了问题往往不是加密算错而是根本不明白协议的状态流转。1.1 消息头是整个协议的骨架CMPP3.0的消息头固定12字节三个字段各占4字节Total_Length表示整个消息含消息头的字节数Command_Id是操作命令字Sequence_Id是消息序列号。这样一来接收方在TCP流上解析消息时逻辑非常清晰先读4字节拿到Total_Length再根据长度把整条消息读完整然后按Command_Id分发处理。用Java的DataInputStream包装一下Socket输入流就能实现不需要引入重型框架。1.2 核心命令字与业务含义协议中最常用的命令字有四个CMPP_CONNECT登录请求/响应、CMPP_SUBMIT提交短信、CMPP_DELIVER接收短信/状态报告、CMPP_ACTIVE_TEST链路检测。另外CMPP_TERMINATE用于正常断开连接。需要特别注意的是CMPP3.0的CONNECT登录报文中Version字段要填0x30如果填成CMPP2.0的0x20网关会直接判定协议版本不匹配返回错误码这个细节在联调阶段最容易栽跟头。1.3 连接生命周期是一个有限状态机CMPP连接不是建连就能发短信它有一个隐形的状态流转TCP建立后立即发送CONNECT请求收到成功的CONNECT响应后才进入已认证状态此时才能发送SUBMIT和DELIVER。如果链路长时间空闲还需要周期性地发送ACTIVE_TEST来保活。用Java实现时我建议用枚举定义连接状态INIT、AUTHENTICATED、CLOSED并在每个发送方法入口校验当前状态否则一旦在未认证状态下发了SUBMIT网关会直接断开连接排查起来很费劲。2. Java工程中的连接管理从BIO到连接池再到断线重连早期很多CMPP实现都是基于BIO的也就是一个连接一个线程简单直接。但如果你的短信平台需要同时接入多个SP账号或者要处理高吞吐的提交请求BIO模型很快就会暴露问题。我在项目里用的是Java原生NIO加自定义的Reactor线程模型既没有引入Netty那么重的依赖又能比较好地控制并发。2.1 为什么没有直接上NettyNetty确实强大但对CMPP这种命令字固定、消息边界清晰的协议来说有点杀鸡用牛刀。CMPP的二进制帧解析逻辑非常规整只需要一个ByteBuf累积读取器配合状态模式处理半包和粘包用NIO自己写完全可控。当然如果团队里没人熟悉NIO用Netty也完全可以只是你需要额外处理Netty自身的线程模型和CMPP状态机的配合问题。我的建议是连接数少、并发要求不高就选BIO代码最简单连接数多、需要高可用就选NIO自研或Netty。2.2 连接池的设计思路CMPP的连接并不是越多越好。网关侧通常会对同一个SP账号限制并发连接数超过限制的新连接会被拒绝。所以连接池的规模需要和网关确认一般每个账号维护1到2条长连接就足够了。连接池的核心逻辑有三个空闲连接的保活、连接异常的剔除、以及获取连接时的状态检查。我实现时用的是带过期时间的对象池获取连接前先ping一下状态如果连接处于CLOSED状态就重新建立。2.3 断线重连的注意点断线重连是稳定性设计的重头戏。网关在凌晨或者割接时偶尔会重启这时候客户端必须能感知到连接断开并自动重建。我在重连逻辑里加了指数退避策略第一次重连等1秒第二次等2秒依次翻倍最大不超过60秒。这样可以避免网关还在启动过程中客户端以极高频率发起连接造成网关连接风暴。另外重连成功后要立即重新做CONNECT鉴权不能只恢复TCP连接。3. 登录鉴权的Java实现MD5摘要、时间戳与常见的坑CONNECT登录是整个协议里最容易踩坑的环节。CMPP3.0的鉴权核心是生成一个16字节的AuthenticatorSource它的计算方式是MD5(Source_Addr 9字节密码 Timestamp)其中Source_Addr是企业代码Timestamp是格式为MMDDHHMMSS的10位时间戳。这里有个特别容易忽略的细节参与MD5运算的密码是固定9字节如果密码不足9位要用0x00补齐如果超过9位则要确认网关侧的截断规则。3.1 一个正确的鉴权码生成代码示例public static byte[] buildAuthenticatorSource(String spId, String secret, String timestamp) { // 密码必须按9字节处理不足补0x00超过则截断 byte[] secretBytes new byte[9]; byte[] rawSecret secret.getBytes(StandardCharsets.UTF_8); System.arraycopy(rawSecret, 0, secretBytes, 0, Math.min(rawSecret.length, 9)); ByteBuffer buffer ByteBuffer.allocate(spId.length() 9 timestamp.length()); buffer.put(spId.getBytes(StandardCharsets.UTF_8)); buffer.put(secretBytes); buffer.put(timestamp.getBytes(StandardCharsets.UTF_8)); return DigestUtils.md5(buffer.array()); }这段代码的逻辑并不复杂但有几个点需要反复确认SP_ID的编码方式有的网关是ASCII有的可能是GBK密码字节的补齐规则以及Timestamp的时区。我遇到过最诡异的问题就是服务器时区设置为UTC导致生成的Timestamp比北京时间早了8小时网关鉴权一直失败排查了很久才找到根因。3.2 序列号Sequence_Id的生成策略Sequence_Id是消息头里的第三个字段它必须保证在每条连接上唯一尤其是SUBMIT和DELIVER这类需要追踪的消息序列号会用于后续的状态报告匹配。简单方案是用AtomicLong从1开始递增但我建议把序列号设计成连接标识自增序号的组合这样在排查问题时能一眼看出消息来自哪条连接。不要用UUID截断也不要每次重连都重置序列号否则网关可能因为重复序列号丢弃消息。3.3 登录响应的处理网关返回的CONNECT响应里有一个Status字段0表示成功非0表示失败。常见错误码包括1表示消息结构错误、2表示非法源地址、3表示鉴权失败、4表示版本太高、5表示IP校验失败。这里要注意登录失败后网关不一定会立即断开TCP连接客户端必须根据Status字段主动决定是否关闭连接不能傻等。4. SUBMIT消息组装与长短信拆分核心业务逻辑的细节SUBMIT是CMPP协议中字段最多的一个命令涉及Msg_Type、Need_Report、Priority、Service_Id、Fee_Type、Fee_Code、Src_Id、Dest_Terminal_Id、Msg_Content等几十个字段。Java实现时建议写一个独立的SubmitMessage类字段顺序严格按协议文档定义用ByteBuffer按偏移量填充千万不要用HashMap去拼字段否则很容易漏字段。4.1 长短信拆分的正确姿势短信内容的长度限制是140字节按ASCII算约160字符按中文算约70字符。超过这个长度就必须拆分。CMPP3.0没有在协议层强制规定拆分方式但标准做法是使用UDHI头在Msg_Content前面加6字节的TP_udhi头其中包含消息参考号、总条数和当前条数。Java实现时我的做法是先按编码方式GBK或UTF-8把内容转字节数组然后按134字节140字节减去6字节UDHI头切分每条短信补上UDHI头再分别组装成SUBMIT消息。这里要特别强调拆分后的每条短信必须使用相同的Msg_Id和UDHI头参考号否则手机端无法合并。4.2 状态报告与Msg_Id的关联SUBMIT响应中会返回一个Msg_Id这是网关生成的唯一消息标识。后续的状态报告通过DELIVER命令下发里会带上这个Msg_Id和相应的状态码DELIVRD表示成功UNDELIV表示失败等。Java实现里我维护了一个并发Mapkey是Msg_Idvalue是业务订单号收到状态报告后从Map里取出并更新业务状态。这个Map必须设置过期时间否则长时间未回的短信会导致内存泄漏。4.3 超时重发与去重短信网关偶尔会丢包所以SUBMIT需要有超时重发机制。但重发一个极端危险的陷阱如果第一次SUBMIT已经到达网关只是响应丢了重发会导致用户收到重复短信。为了解决这个问题我引入了业务层的消息唯一ID在组装SUBMIT时把这个ID写入Msg_Content的扩展字段里网关侧或服务端幂等表来去重。没有幂等机制的话宁可超时后先查询状态也不要贸然重发。5. DELIVER消息接收上行短信与状态报告的双重处理DELIVER命令承载两类数据用户上行短信和短信状态报告。Java实现中需要在解析DELIVER消息体的前几个字段后判断类型再分流处理。状态报告的判读逻辑比较统一上行短信则要按业务类型转发到不同的业务处理器。5.1 消息体的分流解析DELIVER消息体中的IsReport字段可以区分这两种类型1表示状态报告0表示上行短信。如果是状态报告后续字段是Msg_Id、Stat、SubmitTime、DoneTime等如果是上行短信后续字段是Src_Terminal_Id、Dest_Terminal_Id、Msg_Content等。建议在解析时先构造成统一的DeliverMessage对象再交给对应的处理器这样后续加新业务时不需要改动协议层。5.2 上行短信的主动推送模式CMPP是长连接协议意味着网关会把上行短信主动推送到你的客户端不需要轮询。但有些团队基于HTTP习惯了可能会做定时拉取这在CMPP场景下是完全多余的。你需要做的是把DELIVER的处理逻辑挂在NIO的读事件上消息一到就解析入库。注意处理完DELIVER后必须给网关回一个DELIVER_RESP否则网关会认为客户端没收到反复重推。5.3 处理速度和TCP窗口的平衡如果上行短信量很大处理速度跟不上TCP接收缓冲区会被占满网关推消息的速度也会自动降下来。这是TCP的流量控制机制但它掩盖了业务处理的性能问题。我在实际项目里会监控DELIVER消息从接收到处理完成的耗时一旦平均值超过500毫秒就要考虑优化入库逻辑或异步化。CMPP本身对处理耗时没有硬性要求但拖太久会导致消息积压延迟上升。6. ACTIVE_TEST心跳与稳定性保障让长连接真正长起来长连接最怕什么不是消息量大而是长时间空闲后被中间设备断开。运营商机房里往往有各种防火墙和NAT设备空闲连接超过一定时间就会被静默回收客户端还以为连接正常实际已经死了。CMPP协议专门设计了ACTIVE_TEST命令来解决这个问题。6.1 心跳发送的时间策略心跳间隔建议设置为30秒到60秒之间。如果太频繁会白白消耗网关资源如果太久又可能被中间设备切断。我实现时用的是每隔30秒发一个ACTIVE_TEST请求如果连续3次都没收到响应就判定连接已死亡触发断线重连。这个3次判定很关键因为网络抖动可能导致个别心跳包丢失不能因为一次失败就断开。6.2 在NIO线程模型里集成心跳如果用NIO自研心跳可以做成一个ScheduledExecutorService任务定时扫描所有连接的状态发现空闲超过阈值就发送ACTIVE_TEST。注意不要在NIO的IO线程里直接做阻塞操作心跳包的发送应该提交到任务队列由IO线程统一写出去。Netty里则是用IdleStateHandler配置readerIdleTime和writerIdleTime事件触发后由用户处理器发送心跳逻辑会更加简单。6.3 网关无响应时的处理有一个特别容易踩的坑网关收到ACTIVE_TEST后可能不响应但连接仍然健在此时客户端如果在等待响应可能会误判连接死亡。所以心跳超时判定最好用累计连续失败次数而不是单次超时。我见过有的实现用CompletableFuture等心跳响应结果因为网关偶发不响应每几分钟就重连一次搞得网关侧频繁产生登录日志这就是设计不合理。7. 排错实战从连接失败到消息发不出去的定位思路协议联调阶段最痛苦的就是排错。我把这几年CMPP接入过程中遇到的高频问题整理成一个排查表格直接照着检查能省很多时间。现象可能原因检查方法CONNECT鉴权失败Timestamp时区不对用System.currentTimeMillis换算北京时间CONNECT鉴权失败密码补齐方式错误确认不足9字节补0x00CONNECT返回版本错误Version字节填错确认CMPP3.0填0x30SUBMIT无响应未在认证状态发送检查连接状态机状态报告收不到DELIVER_RESP未回复抓包确认响应包已发长连接被断开心跳间隔太长改为30秒心跳3次超时判定7.1 抓包工具的使用排查CMPP问题抓包是最直接的手段。Wireshark可以过滤TCP端口然后逐条解析CMPP报文。虽然Wireshark自带的CMPP解析器不算完善但十六进制视图已经足够定位问题了。我一般会把报文读写单独封装一层日志开关上线后如果遇到问题开DEBUG级别日志把发送和收到的报文都以Hex字符串打印出来对照协议文档逐字节核对。7.2 长短信拆分后丢失部分短信这个问题排查起来很隐蔽。拆分的多条短信如果发送间隔过长或者某条在网关侧排队用户就可能只收到其中一部分。解决思路有两个一是把拆分后的每条短信尽量连续提交二是通过Msg_Id关联和状态报告来监控每一分片的投递结果。如果发现某个分片失败至少要能在日志里把这个分片和同组的其他分片关联起来避免用户问起来时无从查起。7.3 压测时出现的连接复位压测阶段经常遇到连接被RST的情况原因往往是QPS过高导致某个线程在写Socket时出现了未捕获异常被动关闭连接。这种问题的定位方式要看两端日志客户端会报Broken pipe或者Connection reset网关侧一般不会记录客户端主动断开的原因。最终我是在所有Socket写操作外层加了异常兜底并且把写失败和连接关闭事件做了关联才定位到是半包处理逻辑中的数组越界导致线程异常退出。给所有底层IO操作加统一的异常处理在做长连接项目时是一个必须的健壮性要求。8. 一个可落地的Java工程结构建议如果你准备在自己的项目里集成CMPP3.0推荐按模块化思路组织代码把协议层、会话层、业务层彻底分开。这是我自己在项目里最终沉淀下来的结构可维护性比一开始一坨代码要好得多。cmpp-gateway/ ├── protocol/ # 协议层负责报文编解码 │ ├── CmppMessageHeader.java │ ├── CmppConnectRequest.java │ ├── CmppSubmitRequest.java │ └── CmppDeliverRequest.java ├── session/ # 会话层负责连接生命周期 │ ├── CmppSession.java │ ├── CmppConnectionPool.java │ └── CmppHeartbeatTask.java ├── handler/ # 业务层负责消息处理 │ ├── SubmitHandler.java │ ├── DeliverHandler.java │ └── ReportHandler.java └── common/ # 工具类 ├── SequenceGenerator.java └── CmppConstants.java协议层只做字节和Java对象的互相转换不包含任何业务逻辑会话层管理连接状态、心跳、重连业务层处理SUBMIT、DELIVER和状态报告。这样分层的最大好处是当网关协议从3.0升级到其他版本时只需要替换protocol包上层几乎不用动。关于线程模型我的建议是一个连接分配一个读线程、一个写线程心跳任务由全局调度器统一驱动。如果使用NIO则把读事件和写事件挂在同一个Selector上需要注意的是写半包的处理避免多线程同时写同一个SocketChannel导致数据错乱。9. 上线之后还要盯的几个指标代码写完、联调通过不代表事情结束了。CMPP网关对接是一个持续运营的过程建议上线后至少监控这几项指标连接存活状态、SUBMIT平均响应时间、SUBMIT成功率、状态报告回执率、上行短信处理延迟。尤其是状态报告回执率它能反映消息到底有没有真正到达用户手机这是短信业务最核心的质量指标。根据我个人的实际体验CMPP3.0接入最消耗精力的往往不是协议本身而是各种网络异常、网关侧偶发故障以及运营商割接导致的连接抖动。所以工程上的稳定性设计比如心跳自适应、断线重连、幂等去重比重现协议报文要重要得多。最后再分享一个小技巧在测试环境对接时可以把网关IP、端口、SP账号、密码都做成可配置项配合Spring Boot的Profile机制区分环境这样从联调到上线切换环境只需要改配置不用改代码能省下不少重复劳动。本文还有配套的精品资源点击获取