簡介面向Java短信網關開發(fā)者的CMPP3.0協議實現參考包圍繞中國移動CMPP3.0規(guī)范覆蓋短信提交、接收、狀態(tài)查詢等核心業(yè)務可直接作為短信服務接入與二次開發(fā)的基礎示例。壓縮包共17個文件以14個Java源文件為主輔以properties配置文件與2個txt說明文檔整體僅23KB代碼量精簡但模塊劃分清晰common包封裝公共處理邏輯msg包處理消息業(yè)務定時器示例配合心跳機制使用。實現中重點演示了TCP長連接與心跳保持、GBK編碼轉換、多線程處理并發(fā)請求、異常重試與短信狀態(tài)跟蹤等關鍵模塊與CMPP3.0十大學習要點一一對應說明文檔對配置項和運行方式也給出必要引導。目前已有949人學習適合具備一定Java基礎、正在對接短信網關或需要快速理解CMPP3.0報文格式與收發(fā)流程的開發(fā)者通過閱讀源碼與配置可掌握Java環(huán)境下CMPP3.0的落地結構并據此擴展自己的生產級實現。1. cmpp3.0_JAVA_實現為什么你的短信網關項目繞不開這組關鍵詞做短信網關對接的 Java 工程師十有八九都在項目里見過“cmpp3.0_JAVA_實現”這組關鍵詞。它不是什么高深算法而是中國移動短信網關 CMPP3.0 協議的接入落地用 Java 寫一個能收發(fā)短信、能收狀態(tài)報告、能扛住一定并發(fā)的客戶端模塊。網上資料零散協議文檔又是十六進制黑話導致很多人卡在登錄報文和滑動窗口上連上就斷、發(fā)了沒響應。這篇文章我按自己的落地路徑講清楚協議怎么拆、代碼怎么組織、哪些參數不能亂調最后把最容易翻車的坑挨個點出來。適合正在接短信通道、或者被派去維護老短信系統的讀者新手能照著寫熟手可以拿避坑清單當檢查項。2. CMPP3.0 協議先立住四種消息、無符號整數和滑動窗口2.1 四種消息類型和 Java 里的命令字CMPP3.0 的通信不是 HTTP是一條 TCP 長連接上的二進制消息流。雖然文檔里有十幾種消息但 Java 實現里真正高頻的只有四組Connect登錄鑒權、Submit下發(fā)短信、Deliver上行短信和狀態(tài)報告、ActiveTest心跳。真正斷開連接用的 Terminate 在客戶端主動退出時才會用到。先把命令字整理成表后面寫解碼器會反復用到消息作用Command_Id建議常量名登錄請求0x00000001CMPP_CONNECT登錄響應0x80000001CMPP_CONNECT_RESP下發(fā)短信請求0x00000002CMPP_SUBMIT下發(fā)短信響應0x80000002CMPP_SUBMIT_RESP上行/狀態(tài)報告請求0x00000003CMPP_DELIVER上行/狀態(tài)報告響應0x80000003CMPP_DELIVER_RESP心跳請求0x00000004CMPP_ACTIVE_TEST心跳響應0x80000004CMPP_ACTIVE_TEST_RESP注意 Command_Id 的規(guī)律請求的最高位是 0響應最高位是 1。這個規(guī)律在調試時很有用看到 0x8 開頭就知道是網關回包。但在 Java 里有個小坑0x80000001 超過了 int 的正數范圍讀出來可能是負數。我一般用 long 或者 Integer.compareUnsigned 來做比較避免“這個數怎么是負的”這種問題。2.2 消息頭、字節(jié)序和 Sequence_IdCMPP3.0 每條消息開頭固定 12 字節(jié)的消息頭三個 int 字段全部是大端序Total_Length、Command_Id、Sequence_Id。Total_Length 是整個消息的長度包含這 12 字節(jié)本身Sequence_Id 是流水號從 0 開始累加用來匹配請求和響應。協議里幾乎全是無符號整數Java 的 int 也是 32 位但最高位是符號位。好消息是用 Netty 的 ByteBuf 寫入時 writeInt 只是按位寫Java 正負數不影響網絡字節(jié)序壞消息是從 ByteBuf 讀的時候要用 readUnsignedInt 才能拿到正確的 0-4294967295 范圍值。我習慣把消息頭獨立封裝出來避免每個消息體都重復處理粘包和半包。public class CMPPMessageHeader { public int totalLength; public int commandId; public int sequenceId; public void encode(ByteBuf out) { out.writeInt(totalLength); out.writeInt(commandId); out.writeInt(sequenceId); } public void decode(ByteBuf in) { totalLength in.readInt(); commandId in.readInt(); sequenceId (int) in.readUnsignedInt(); } }這段代碼里的關鍵點是 sequenceId 讀取。協議里 Sequence_Id 是無符號如果直接 readInt 會讀到負數后續(xù)用這個值做 key 匹配響應時容易出問題。網絡字節(jié)序方面ByteBuf 默認就是大端和 CMPP 協議一致不需要額外調 ByteOrder。參數上sequenceId 用 AtomicInteger 生成就夠了。注意它最大到 0xFFFFFFFF到達上限后要歸零。如果用了 readUnsignedInt就不會因為符號問題導致回繞判斷錯誤。這里再說一句別用 synchronized 保護一個 int 自增AtomicInteger 足夠網關接口是長連接請求量上來后鎖競爭會拖慢整個發(fā)送鏈路。2.3 滑動窗口并發(fā)發(fā)送前的第一個控制參數CMPP3.0 的滑動窗口機制簡單說就是同一時刻最多能有多少條 Submit 消息沒收到 Submit_Resp。窗口大小規(guī)范默認是 16具體值由網關側配置決定客戶端必須遵守。如果客戶端無限往里灌網關會直接斷開連接而且不會告訴你原因。Java 里實現窗口最干凈的方式是信號量。每條 Submit 發(fā)送前 acquire收到 Submit_Resp 后 release。這樣發(fā)送線程會被自然阻塞而不是把消息堆進無界隊列后內存爆掉。private final Semaphore window new Semaphore(16); public void acquireWindow() throws InterruptedException { if (!window.tryAcquire(3, TimeUnit.SECONDS)) { throw new IllegalStateException(滑動窗口已滿網關響應過慢); } } public void releaseWindow() { window.release(); }窗口大小為什么是 16 而不是 100這是協議設計好的背壓閾值超過閾值網關會認為客戶端失控。我用 tryAcquire 而不是 acquire是為了在窗口長期占滿時讓發(fā)送線程快速失敗而不是無限阻塞否則故障時線程池會被卡滿。3 秒超時是個經驗值真實網關一般幾十毫秒到幾百毫秒就回 Submit_Resp如果 3 秒都沒窗口說明響應鏈路已經不正常應該告警而不是繼續(xù)等。2.4 用 Java 對象建模協議字段定長字符串的坑CMPP3.0 的消息體里大量使用定長字符串比如 Source_Addr 固定 6 字節(jié)Service_Id 固定 10 字節(jié)。協議規(guī)定不足部分按位補 0不是補空格。很多人把 String 直接 getBytes 塞進去結果長度不夠多出來的隨機數據導致網關解析錯亂。我一般先封裝一個定長編碼方法統一處理這種情況public static byte[] fixedString(String value, int length, Charset charset) { byte[] raw value.getBytes(charset); if (raw.length length) { throw new IllegalArgumentException(字段超長當前值 value); } byte[] out new byte[length]; System.arraycopy(raw, 0, out, 0, raw.length); return out; }補充說明定長字段在 CMPP 文檔里通常標注“字符串”但具體是 ASCII 還是 GBK要看字段類型。比如 Source_Addr 和 Msg_Src 是數字組成的企業(yè)代碼用 ASCII 就可以Service_Id 可能是字母加數字也建議 ASCII。Msg_Content 的業(yè)務內容才根據 Msg_Fmt 用 UCS2 或 GBK。用 charset 參數顯式傳入能避免將來換服務器后平臺默認編碼變了導致亂碼。這個細節(jié)就是 CMPP3.0_Java 實現里最常見的“看著代碼沒問題一上線就出事”的源頭。3. 從零搭一個 CMPP3.0 Java 客戶端五個可復現的步驟3.1 選型Netty 還是原生 SocketCMPP3.0 是二進制協議必然涉及粘包、半包、字節(jié)序轉換。原生 Socket 也能做但所有協議解析都要自己寫還要自己管理線程池。Netty 的優(yōu)勢在于 ByteBuf、ChannelPipeline 和內置的定時任務能讓代碼結構干凈很多。Mina 也見過人用但近年新項目選 Netty 更多社區(qū)資料也全。選型對比可以按這個參考方案協議解析線程模型維護成本原生 Socket自己處理容易漏字節(jié)每連接一線程擴展麻煩低依賴但出問題全得自己扛Mina自帶解碼器有 IoHandler 模型老項目多新資料少NettyByteBuf 解碼器EventLoop 異步模型需要一點學習曲線我選 Netty。下面是客戶端初始化的最小骨架EventLoopGroup group new NioEventLoopGroup(2); Bootstrap bootstrap new Bootstrap(); bootstrap.group(group) .channel(NioSocketChannel.class) .option(ChannelOption.TCP_NODELAY, true) .option(ChannelOption.SO_KEEPALIVE, true) .handler(new ChannelInitializerSocketChannel() { Override protected void initChannel(SocketChannel ch) { ch.pipeline().addLast(new CMPPDecoder()); ch.pipeline().addLast(new CMPPHandler()); } }); ChannelFuture future bootstrap.connect(host, port).sync(); Channel channel future.channel();TCP_NODELAY 必須設為 true否則小字節(jié)的 CMPP 包會被 Nagle 算法合并導致網關側響應延遲明顯變大。SO_KEEPALIVE 只是內核級保活不能替代業(yè)務心跳這個后面會專門說。CMPPDecoder 要做的事就是讀前 4 字節(jié)的 Total_Length再按長度讀完整包解決粘包半包。NioEventLoopGroup 線程數我用 2一個負責 IO一個留給協議處理實際連接數和消息量上來后再調。3.2 登錄鑒權CMPP_CONNECT 的 Java 實現登錄是第一個坑點。CMPP_CONNECT 消息體包含 Source_Addr、AuthenticatorSource、Version、Timestamp 四個字段。其中 AuthenticatorSource 是 MD5 結果16 字節(jié)算法是MD5(Source_Addr 9字節(jié)0 sharedSecret Timestamp)。這里 9 字節(jié) 0 很容易漏掉漏了網關回你 3認證失敗。private ByteBuf buildConnectRequest(String spCode, String sharedSecret, int timestamp) { ByteBuf buf Unpooled.buffer(); int totalLength 12 6 16 1 4; int sequenceId sequenceIdGenerator.incrementAndGet(); buf.writeInt(totalLength); buf.writeInt(0x00000001); buf.writeInt(sequenceId); buf.writeBytes(fixedString(spCode, 6, StandardCharsets.ASCII)); buf.writeBytes(buildAuthenticatorSource(spCode, sharedSecret, timestamp)); buf.writeByte(0x30); // Version 3.0 buf.writeInt(timestamp); return buf; } private byte[] buildAuthenticatorSource(String spCode, String sharedSecret, int timestamp) throws Exception { byte[] spBytes spCode.getBytes(StandardCharsets.ASCII); byte[] secretBytes sharedSecret.getBytes(StandardCharsets.ASCII); ByteBuffer input ByteBuffer.allocate(spBytes.length 9 secretBytes.length 4); input.put(spBytes); input.put(new byte[9]); input.put(secretBytes); input.putInt(timestamp); return MessageDigest.getInstance(MD5).digest(input.array()); }timestamp 不是常見的時間戳而是 MMDDHHMMSS 格式比如 4 月 15 日 14 時 30 分 05 秒就是 0415143005作為 int 寫入。組裝時注意 Source_Addr 固定 6 字節(jié)如果 spCode 不足 6 位用 fixedString 補 0。Version 是 0x30表示 3.0不是 3。很多文檔寫“版本為30”結果有人直接寫 3網關也能連上但某些網關上功能受限我遇到過。3.3 心跳與重連CMPP_ACTIVE_TEST 和指數退避CMPP 網關一般要求 30 秒內至少有一次業(yè)務報文或心跳否則會斷開連接。我習慣用一個 ScheduledExecutorService 固定每 30 秒發(fā)一次 ActiveTest即使剛發(fā)送過 Submit 也照發(fā)邏輯簡單不會因為忘記重置計時器而被踢下線。private ScheduledExecutorService heartBeatScheduler Executors.newSingleThreadScheduledExecutor(); public void startHeartBeat() { heartBeatScheduler.scheduleAtFixedRate(() - { if (channel ! null channel.isActive()) { channel.writeAndFlush(new CMPPActiveTestRequest(sequenceIdGenerator.incrementAndGet())); } }, 30, 30, TimeUnit.SECONDS); }收到心跳響應用一個 AtomicInteger 記錄最近一次響應時間如果連續(xù) 3 次心跳沒響應就判定連接已死主動關閉并觸發(fā)重連。重連不要寫死循環(huán)用指數退避第一次等待 1 秒第二次 2 秒最多 30 秒避免網關恢復期間客戶端高頻重連把網關打崩。另外心跳線程一定要獨立不能和業(yè)務線程共用如果業(yè)務線程被滑動窗口阻塞心跳還能繼續(xù)發(fā)這個隔離能救很多次。3.4 發(fā)送 CMPP_SUBMIT組裝報文和控制窗口Submit 是項目里流量最大的部分。消息體字段多但關鍵的就幾個Msg_Id8 字節(jié)本地填 0響應里回填、Pk_total、Pk_number、Registered_Delivery、Msg_Fmt、Msg_Src、Src_Id、Msg_Length、Msg_Content。Registered_Delivery 設為 1才能收到狀態(tài)報告Msg_Fmt 這里先按 ASCII 處理中文短信用 UCS2后面長短信拆分再細講。發(fā)送前必須走窗口信號量。完整發(fā)送代碼如下public void sendSubmit(CMPPSubmitRequest request) throws InterruptedException { acquireWindow(); ByteBuf buf Unpooled.buffer(); request.encode(buf); channel.writeAndFlush(buf).addListener((ChannelFuture future) - { if (!future.isSuccess()) { releaseWindow(); log.error(submit 發(fā)送失敗, future.cause()); } }); } public void onSubmitResp(CMPPSubmitResp resp) { releaseWindow(); if (resp.getStatus() ! 0) { log.warn(submit 返回錯誤 status{}, msgId{}, resp.getStatus(), resp.getMsgId()); } else { log.info(submit 成功 msgId{}, resp.getMsgId()); } }注意 writeAndFlush 失敗時也要 releaseWindow否則窗口會被永久占用。onSubmitResp 里只做 window 釋放和日志記錄具體業(yè)務更新放在另一個異步線程池避免阻塞 Netty 的 EventLoop。如果在這個 Handler 里直接操作數據庫網關并發(fā)一高EventLoop 卡住心跳就發(fā)不出去緊接著就是連接斷開這是很多壓測翻車的直接原因。3.5 Spring Boot 里的配置組織項目里我不會把協議代碼和業(yè)務配置混在一起。用 Spring Boot 的話連接參數、窗口大小、心跳間隔全放 application.ymlcmpp: host: 192.168.10.20 port: 3150 sp-code: 100001 shared-secret: test123 window-size: 16 heartbeat-interval-sec: 30 reconnect-max-wait-sec: 30然后寫一個 CMPPProperties 類用 ConfigurationProperties 綁定。服務啟動時創(chuàng)建 CMPPClient用 SmartLifecycle 控制啟動順序應用關閉時先發(fā) Terminate 再釋放連接。這里要提醒一句連接建立不等于登錄成功登錄成功報文是 CONNECT_RESP這里的 Status 字段 0 才表示認證通過。我見過有的項目只檢測了 TCP 是否連接就對外報通道可用結果狀態(tài)監(jiān)控一片綠短信一條都發(fā)不出去。4. 消息路由與長短信拆分Java 實現里的高頻業(yè)務點4.1 區(qū)分 Deliver 上行和狀態(tài)報告Is_Report 字段說了算網關推送的 CMPP_DELIVER 有兩類用戶上行短信和狀態(tài)報告。區(qū)分方式很簡單看消息體里的 Is_Report 字段。Is_Report0 是用戶上行需要往業(yè)務系統轉Is_Report1 是狀態(tài)報告要解析里面的 Stat 字段更新短信發(fā)送狀態(tài)。狀態(tài)報告的 Msg_Content 是一段格式化文本常見是空行分隔的字段比如stat:DELIVRD done_time:20250615143005 sub_time:20250615142930解析代碼不要寫復雜正則按行 split 再按冒號拆一次就夠了public static MapString, String parseStatusReport(byte[] msgContent, Charset charset) { String text new String(msgContent, charset); MapString, String result new HashMap(); for (String line : text.split(\\r?\\n)) { int idx line.indexOf(:); if (idx 0) { result.put(line.substring(0, idx).trim(), line.substring(idx 1).trim()); } } return result; }狀態(tài)報告常見 Stat 值就三種DELIVRD成功、EXPIRED過期、UNDELIV不可達。我建議建一個枚舉把未知狀態(tài)先按失敗處理并告警不要默默丟棄。另外狀態(tài)報告的消息體編碼不一定和上行短信一樣有的網關用 GBK。Java 里不要默認 new String(msgContent)顯式指定編碼否則 Linux 部署后中文編譯環(huán)境一變解析出來就亂。4.2 長短信拆分67 字一條不是 70 字中文短信一條最多 70 個漢字但這指的是不帶 UDHI 頭的普通短信。CMPP3.0 長短信需要在消息體前面加 6 字節(jié)的 UDHI 頭用來標識分片信息所以真正留給短信內容的只有 67 個漢字。拆分時如果按 70 切分片會超長網關要么拒絕要么用戶收到亂碼。一個可用的拆分方法public static ListCMPPSubmitRequest splitLongMessage(String content, String mobile) { int maxCharsPerPart 67; int total (int) Math.ceil(content.length() / (double) maxCharsPerPart); ListCMPPSubmitRequest result new ArrayList(); for (int i 0; i total; i) { int start i * maxCharsPerPart; int end Math.min((i 1) * maxCharsPerPart, content.length()); String part content.substring(start, end); CMPPSubmitRequest request new CMPPSubmitRequest(); request.setMobile(mobile); request.setPkTotal(total); request.setPkNumber(i 1); request.setTpUdhi(1); request.setMsgFmt(8); byte[] partBytes part.getBytes(StandardCharsets.UTF_16BE); byte[] udhi buildUdhiHeader(total, i 1); byte[] msgContent new byte[udhi.length partBytes.length]; System.arraycopy(udhi, 0, msgContent, 0, udhi.length); System.arraycopy(partBytes, 0, msgContent, udhi.length, partBytes.length); request.setMsgContent(msgContent); request.setMsgLength(msgContent.length); result.add(request); } return result; } private static byte[] buildUdhiHeader(int total, int number) { return new byte[]{0x05, 0x00, 0x03, 0x0A, (byte) total, (byte) number}; }拆分時按 Java 的 char 數切不是按字節(jié)切。UCS2 下每個漢字是一個 char每個 char 兩個字節(jié)67 個 char 正好 134 字節(jié)加 6 字節(jié) UDHI 頭是 140 字節(jié)。buildUdhiHeader 里 0x05 表示后面有 5 個長度字節(jié)0x00 0x03 是 TP_UDHI 的拆分標識0x0A 是參考號后兩字節(jié)分別是總條數和當前條數。參考號可以固定也可以每條消息用隨機數但總分片數不能超過 255因為這是 1 字節(jié)字段。這條邏輯里有個隱藏邊界如果內容里包含 emojiJava 的 String.length 會把一個 emoji 記成兩個 char按這個思路拆某些分片可能把代理對切半。遇到這種內容建議升級到按 CodePoint 切分或者直接限制用戶輸入短信場景里 emoji 本來就容易亂碼。4.3 去重、存儲和異?；謴蛿祿煳ㄒ凰饕亲詈蟮亩档證MPP 消息在網絡傳輸中可能重發(fā)。Deliver 上行、狀態(tài)報告如果重復處理會給業(yè)務方造成重復訂單或者錯誤狀態(tài)。常見的做法是在數據庫表里給網關消息 Msg_Id 加唯一索引入庫時捕獲 DuplicateKeyException直接忽略第二遍。CREATE TABLE sms_deliver_log ( id BIGINT PRIMARY KEY AUTO_INCREMENT, msg_id BIGINT NOT NULL, mobile VARCHAR(32) NOT NULL, is_report TINYINT NOT NULL, content TEXT, stat VARCHAR(20), receive_time DATETIME NOT NULL, UNIQUE KEY uk_msg_id (msg_id) );Java 端的處理邏輯要注意順序先查一次再插入不如直接插入靠唯一索引攔并發(fā)下后一種才能真正防重。數據庫層面的唯一約束是最靠譜的兜底應用層用 ConcurrentHashMap 做去重只能擋住單機 JVM 內的重復。發(fā)送側的異?；謴透v究。Submit 發(fā)出去了但沒收到 Submit_Resp這時不能一概重發(fā)。因為消息可能已經到達網關重發(fā)會重復下發(fā)。我會在發(fā)送前給每條消息生成一個業(yè)務批次號把 Submit_Resp、Deliver 狀態(tài)報告都關聯到同一條發(fā)送記錄重發(fā)前先查這條記錄有沒有任何回執(zhí)有就不發(fā)。這樣處理重啟應用后也不會造成大面積重復短信。5. CMPP3.0_JAVA_實現避坑指南5 個讓我翻車過的黑匣子CMPP3.0 的 Java 實現里最折磨人的往往不是代碼本身而是問題現象看起來像網絡玄學實際上都是協議細節(jié)。下面五條都是我在真實聯調里踩過的每一條都按現象、原因、解決的順序說。5.1 登錄后立刻被斷開先抓報文別猜現象TCP 連接已經建立也發(fā)送了 CMPP_CONNECT甚至收到了 CONNECT_RESPStatus 為 0但緊接著幾秒內連接被網關斷開。日志里沒有任何異常只有連接關閉。原因AuthenticatorSource 的 MD5 計算錯了。最常見的是漏掉 9 字節(jié)的 0 填充或者 Timestamp 格式寫成了 Unix 時間戳。網關認證通過但后續(xù)第一個 Submit 報文格式不對也可能被立刻斷開。解決先把收發(fā)的字節(jié)流打印出來用十六進制對比協議文檔。Java 里加一個工具方法public static String toHex(byte[] data) { StringBuilder sb new StringBuilder(data.length * 2); for (byte b : data) { sb.append(String.format(%02x , b)); } return sb.toString(); }在發(fā)送 CONNECT 前后各打一行。看 Total_Length 是不是 39Command_Id 是不是 00000001AuthenticatorSource 是不是 16 字節(jié)。如果和樣例報文不一致就別懷疑網關先修本地代碼。5.2 Submit 返回 Status0用戶卻收不到短信現象CMPP_SUBMIT_RESP 里 Status 是 0業(yè)務日志顯示發(fā)送成功但手機遲遲收不到短信狀態(tài)報告也始終不來。原因賬號配置和網關側分配不一致。常見的有 Source_Addr 的 SP 企業(yè)代碼填錯Msg_Src 和 Source_Addr 混用Src_Id 設置了不存在的擴展短號。網關只校驗來源認證不校驗這些業(yè)務字段所以認證能過但消息被內部路由丟棄。解決拿網關分配的開戶資料逐項核對。Source_Addr 是 6 位企業(yè)代碼Msg_Src 是 SP_CodeSrc_Id 是顯示主叫號碼通常是服務代碼或者擴展短號。先用最簡消息測一條純 ASCII 文本附帶 Registered_Delivery1確認狀態(tài)報告能回來再換成真實業(yè)務內容。不要直接灰度大批量發(fā)送否則收不到你得從成千上萬條記錄里排查。5.3 并發(fā)一上來就頻繁重連EventLoop 被業(yè)務代碼卡死了現象單條消息測試正常壓測到幾十條并發(fā)時開始出現 ACTIVE_TEST_RESP 超時然后連接斷開客戶端自動重連重連后又斷。原因Netty 的 EventLoop 線程被阻塞了。最常見的是在 ChannelHandler 里直接同步查數據庫、調用外部接口或者發(fā)送窗口沒有控制消息隊列積壓導致響應處理延遲。心跳也走同一個 EventLoop心跳響應沒人處理網關就判定超時斷開。解決把 IO 線程和業(yè)務線程嚴格分開。Netty 的 Handler 只做協議編解碼和窗口釋放業(yè)務處理丟給獨立線程池。窗口控制用前面寫的 Semaphore發(fā)送前 tryAcquire拿不到就快速失敗絕不無界堆積。另外檢查是否在 EventLoop 里調用了 channel.writeAndFlush 的大包同步等待應該用監(jiān)聽器異步回調。5.4 內存溢出從幾百 MB 漲到幾個 G無界隊列是元兇現象Java 進程啟動時內存正常運行一段時間后堆內存持續(xù)上漲最終拋出 OutOfMemoryError應用重啟后重復出現。原因發(fā)送線程和網關響應速度不匹配。網關響應慢提交到線程池的任務越來越多如果用的 LinkedBlockingQueue 沒設容量任務全部積壓在堆里。CMPP 消息內容一多內存直接被打滿。解決有界隊列加拒絕策略。不要用 Executors.newFixedThreadPool 里默認的無界隊列改成BlockingQueueRunnable queue new ArrayBlockingQueue(10000); ThreadPoolExecutor pool new ThreadPoolExecutor( 8, 16, 60, TimeUnit.SECONDS, queue, new ThreadPoolExecutor.CallerRunsPolicy());CallerRunsPolicy 讓提交線程自己執(zhí)行任務形成天然背壓比 AbortPolicy 更友好。JVM 啟動參數按機器內存來不要跟風配大我一般用 -Xms512m -Xmx1024m堆太大反而讓問題暴露得晚。5.5 Linux 上中文亂碼顯式指定字符集別吃平臺默認值現象本地 Windows 開發(fā)測試正常部署到 Linux 后發(fā)送的中文短信到手機變問號或者收到的狀態(tài)報告解析亂碼。原因CMPP3.0 的消息內容是編碼字節(jié)不攜帶字符集聲明。Java 代碼里用了 String.getBytes() 無參版本Windows 默認 GBKLinux 默認 UTF-8兩邊編碼不一致字節(jié)流自然不對。網關按協議里 Msg_Fmt 指定的編碼解析時數據已經錯了。解決Java 代碼里所有 CMPP 編解碼都顯式寫字符集參數。中文短信 Msg_Fmt8 時用 UTF-16BE狀態(tài)報告解析如果需要 GBK 就傳 GBK不要依賴默認環(huán)境。編譯時也固定編碼mvn clean package -Dfile.encodingUTF-8同時檢查 Spring Boot 的 server.servlet.encoding 配置雖然它影響不到這些字節(jié)流但統一 UTF-8 能減少其他環(huán)節(jié)的干擾。這個問題是血淚經驗曾經線上亂碼查了兩天最后就是一行 getBytes() 少了 charset 參數。6. 進階給 CMPP3.0 Java 客戶端加一個 Mock 網關做回歸驗證6.1 用 Netty 寫一個最小 Mock 網關真實網關不是隨便就能連的聯調要等工單、要排期出了問題兩邊還容易扯皮。我的習慣是在項目里保留一個 Mock 網關用來做自動化回歸測試。它能做的就是收到 CONNECT 回 CONNECT_RESP收到 SUBMIT 回 SUBMIT_RESP收到 ACTIVE_TEST 回 ACTIVE_TEST_RESP。這樣客戶端代碼改完跑一遍用例就可以確認協議層沒壞。一個最小 Mock 網關的核心邏輯可以這樣寫public class MockCMPPServer { public void start() throws InterruptedException { EventLoopGroup bossGroup new NioEventLoopGroup(1); EventLoopGroup workerGroup new NioEventLoopGroup(1); ServerBootstrap bootstrap new ServerBootstrap(); bootstrap.group(bossGroup, workerGroup) .channel(NioServerSocketChannel.class) .childHandler(new ChannelInitializerSocketChannel() { Override protected void initChannel(SocketChannel ch) { ch.pipeline().addLast(new CMPPDecoder()); ch.pipeline().addLast(new SimpleChannelInboundHandlerByteBuf() { Override protected void channelRead0(ChannelHandlerContext ctx, ByteBuf msg) { int commandId msg.getInt(4); if (commandId 0x00000001) { ctx.writeAndFlush(buildConnectResp(msg.getInt(8))); } else if (commandId 0x00000002) { ctx.writeAndFlush(buildSubmitResp(msg.getInt(8))); } else if (commandId 0x00000004) { ctx.writeAndFlush(buildActiveTestResp(msg.getInt(8))); } } }); } }); bootstrap.bind(3151).sync(); } }Mock 網關里不需要完整解析每個字段只需要讀 Command_Id 和 Sequence_Id然后按相同 Sequence_Id 回包。CMPP 客戶端一般用自己的流水號匹配響應所以 Mock 網關回包時把請求里的 Sequence_Id 原樣帶回去即可。這段代碼的邊界在于它不會校驗 AuthenticatorSource所以只適合做客戶端回歸測試不適合做協議正確性驗證。6.2 壓測參數建議用 Mock 網關做壓測時參數別隨便拍腦袋。最基礎的一組建議參數建議值說明發(fā)送線程數8不要超過窗口大小的 2 倍滑動窗口大小16與真實網關配置保持一致Submit 超時5 秒超過則記錄失敗壓測時長10 分鐘觀察內存和連接穩(wěn)定性心跳間隔30 秒模擬真實節(jié)奏壓測時重點看兩個指標成功發(fā)送的 TPS 和未響應消息積壓數。如果 TPS 上不去但窗口一直為空說明發(fā)送線程被網關響應延遲拖著先查 Mock 網關的日志如果窗口一直滿說明消費速度不夠調大線程池之前先確認數據庫寫入有沒有瓶頸。真實網關的響應時間和 Mock 網關差別很大正式上線前還是要用真實網關小流量跑一遍。我前兩年接一個新網關上來就急著聯調結果連不上折騰兩天發(fā)現是 MD5 里少補了 9 個字節(jié)。那次之后我養(yǎng)成了一個習慣每個 CMPP 客戶端項目都必須保留 Mock 網關協議層改動先跑回歸再上真實環(huán)境驗證。短信通道這東西不提前準備好后悔藥出事時連定位的抓手都沒有。希望幫到你。本文還有配套的精品資源點擊獲取 CMPP3.0 Java實現：協議拆解與避坑指南
簡介面向Java短信網關開發(fā)者的CMPP3.0協議實現參考包圍繞中國移動CMPP3.0規(guī)范覆蓋短信提交、接收、狀態(tài)查詢等核心業(yè)務可直接作為短信服務接入與二次開發(fā)的基礎示例。壓縮包共17個文件以14個Java源文件為主輔以properties配置文件與2個txt說明文檔整體僅23KB代碼量精簡但模塊劃分清晰common包封裝公共處理邏輯msg包處理消息業(yè)務定時器示例配合心跳機制使用。實現中重點演示了TCP長連接與心跳保持、GBK編碼轉換、多線程處理并發(fā)請求、異常重試與短信狀態(tài)跟蹤等關鍵模塊與CMPP3.0十大學習要點一一對應說明文檔對配置項和運行方式也給出必要引導。目前已有949人學習適合具備一定Java基礎、正在對接短信網關或需要快速理解CMPP3.0報文格式與收發(fā)流程的開發(fā)者通過閱讀源碼與配置可掌握Java環(huán)境下CMPP3.0的落地結構并據此擴展自己的生產級實現。1. cmpp3.0_JAVA_實現為什么你的短信網關項目繞不開這組關鍵詞做短信網關對接的 Java 工程師十有八九都在項目里見過“cmpp3.0_JAVA_實現”這組關鍵詞。它不是什么高深算法而是中國移動短信網關 CMPP3.0 協議的接入落地用 Java 寫一個能收發(fā)短信、能收狀態(tài)報告、能扛住一定并發(fā)的客戶端模塊。網上資料零散協議文檔又是十六進制黑話導致很多人卡在登錄報文和滑動窗口上連上就斷、發(fā)了沒響應。這篇文章我按自己的落地路徑講清楚協議怎么拆、代碼怎么組織、哪些參數不能亂調最后把最容易翻車的坑挨個點出來。適合正在接短信通道、或者被派去維護老短信系統的讀者新手能照著寫熟手可以拿避坑清單當檢查項。2. CMPP3.0 協議先立住四種消息、無符號整數和滑動窗口2.1 四種消息類型和 Java 里的命令字CMPP3.0 的通信不是 HTTP是一條 TCP 長連接上的二進制消息流。雖然文檔里有十幾種消息但 Java 實現里真正高頻的只有四組Connect登錄鑒權、Submit下發(fā)短信、Deliver上行短信和狀態(tài)報告、ActiveTest心跳。真正斷開連接用的 Terminate 在客戶端主動退出時才會用到。先把命令字整理成表后面寫解碼器會反復用到消息作用Command_Id建議常量名登錄請求0x00000001CMPP_CONNECT登錄響應0x80000001CMPP_CONNECT_RESP下發(fā)短信請求0x00000002CMPP_SUBMIT下發(fā)短信響應0x80000002CMPP_SUBMIT_RESP上行/狀態(tài)報告請求0x00000003CMPP_DELIVER上行/狀態(tài)報告響應0x80000003CMPP_DELIVER_RESP心跳請求0x00000004CMPP_ACTIVE_TEST心跳響應0x80000004CMPP_ACTIVE_TEST_RESP注意 Command_Id 的規(guī)律請求的最高位是 0響應最高位是 1。這個規(guī)律在調試時很有用看到 0x8 開頭就知道是網關回包。但在 Java 里有個小坑0x80000001 超過了 int 的正數范圍讀出來可能是負數。我一般用 long 或者 Integer.compareUnsigned 來做比較避免“這個數怎么是負的”這種問題。2.2 消息頭、字節(jié)序和 Sequence_IdCMPP3.0 每條消息開頭固定 12 字節(jié)的消息頭三個 int 字段全部是大端序Total_Length、Command_Id、Sequence_Id。Total_Length 是整個消息的長度包含這 12 字節(jié)本身Sequence_Id 是流水號從 0 開始累加用來匹配請求和響應。協議里幾乎全是無符號整數Java 的 int 也是 32 位但最高位是符號位。好消息是用 Netty 的 ByteBuf 寫入時 writeInt 只是按位寫Java 正負數不影響網絡字節(jié)序壞消息是從 ByteBuf 讀的時候要用 readUnsignedInt 才能拿到正確的 0-4294967295 范圍值。我習慣把消息頭獨立封裝出來避免每個消息體都重復處理粘包和半包。public class CMPPMessageHeader { public int totalLength; public int commandId; public int sequenceId; public void encode(ByteBuf out) { out.writeInt(totalLength); out.writeInt(commandId); out.writeInt(sequenceId); } public void decode(ByteBuf in) { totalLength in.readInt(); commandId in.readInt(); sequenceId (int) in.readUnsignedInt(); } }這段代碼里的關鍵點是 sequenceId 讀取。協議里 Sequence_Id 是無符號如果直接 readInt 會讀到負數后續(xù)用這個值做 key 匹配響應時容易出問題。網絡字節(jié)序方面ByteBuf 默認就是大端和 CMPP 協議一致不需要額外調 ByteOrder。參數上sequenceId 用 AtomicInteger 生成就夠了。注意它最大到 0xFFFFFFFF到達上限后要歸零。如果用了 readUnsignedInt就不會因為符號問題導致回繞判斷錯誤。這里再說一句別用 synchronized 保護一個 int 自增AtomicInteger 足夠網關接口是長連接請求量上來后鎖競爭會拖慢整個發(fā)送鏈路。2.3 滑動窗口并發(fā)發(fā)送前的第一個控制參數CMPP3.0 的滑動窗口機制簡單說就是同一時刻最多能有多少條 Submit 消息沒收到 Submit_Resp。窗口大小規(guī)范默認是 16具體值由網關側配置決定客戶端必須遵守。如果客戶端無限往里灌網關會直接斷開連接而且不會告訴你原因。Java 里實現窗口最干凈的方式是信號量。每條 Submit 發(fā)送前 acquire收到 Submit_Resp 后 release。這樣發(fā)送線程會被自然阻塞而不是把消息堆進無界隊列后內存爆掉。private final Semaphore window new Semaphore(16); public void acquireWindow() throws InterruptedException { if (!window.tryAcquire(3, TimeUnit.SECONDS)) { throw new IllegalStateException(滑動窗口已滿網關響應過慢); } } public void releaseWindow() { window.release(); }窗口大小為什么是 16 而不是 100這是協議設計好的背壓閾值超過閾值網關會認為客戶端失控。我用 tryAcquire 而不是 acquire是為了在窗口長期占滿時讓發(fā)送線程快速失敗而不是無限阻塞否則故障時線程池會被卡滿。3 秒超時是個經驗值真實網關一般幾十毫秒到幾百毫秒就回 Submit_Resp如果 3 秒都沒窗口說明響應鏈路已經不正常應該告警而不是繼續(xù)等。2.4 用 Java 對象建模協議字段定長字符串的坑CMPP3.0 的消息體里大量使用定長字符串比如 Source_Addr 固定 6 字節(jié)Service_Id 固定 10 字節(jié)。協議規(guī)定不足部分按位補 0不是補空格。很多人把 String 直接 getBytes 塞進去結果長度不夠多出來的隨機數據導致網關解析錯亂。我一般先封裝一個定長編碼方法統一處理這種情況public static byte[] fixedString(String value, int length, Charset charset) { byte[] raw value.getBytes(charset); if (raw.length length) { throw new IllegalArgumentException(字段超長當前值 value); } byte[] out new byte[length]; System.arraycopy(raw, 0, out, 0, raw.length); return out; }補充說明定長字段在 CMPP 文檔里通常標注“字符串”但具體是 ASCII 還是 GBK要看字段類型。比如 Source_Addr 和 Msg_Src 是數字組成的企業(yè)代碼用 ASCII 就可以Service_Id 可能是字母加數字也建議 ASCII。Msg_Content 的業(yè)務內容才根據 Msg_Fmt 用 UCS2 或 GBK。用 charset 參數顯式傳入能避免將來換服務器后平臺默認編碼變了導致亂碼。這個細節(jié)就是 CMPP3.0_Java 實現里最常見的“看著代碼沒問題一上線就出事”的源頭。3. 從零搭一個 CMPP3.0 Java 客戶端五個可復現的步驟3.1 選型Netty 還是原生 SocketCMPP3.0 是二進制協議必然涉及粘包、半包、字節(jié)序轉換。原生 Socket 也能做但所有協議解析都要自己寫還要自己管理線程池。Netty 的優(yōu)勢在于 ByteBuf、ChannelPipeline 和內置的定時任務能讓代碼結構干凈很多。Mina 也見過人用但近年新項目選 Netty 更多社區(qū)資料也全。選型對比可以按這個參考方案協議解析線程模型維護成本原生 Socket自己處理容易漏字節(jié)每連接一線程擴展麻煩低依賴但出問題全得自己扛Mina自帶解碼器有 IoHandler 模型老項目多新資料少NettyByteBuf 解碼器EventLoop 異步模型需要一點學習曲線我選 Netty。下面是客戶端初始化的最小骨架EventLoopGroup group new NioEventLoopGroup(2); Bootstrap bootstrap new Bootstrap(); bootstrap.group(group) .channel(NioSocketChannel.class) .option(ChannelOption.TCP_NODELAY, true) .option(ChannelOption.SO_KEEPALIVE, true) .handler(new ChannelInitializerSocketChannel() { Override protected void initChannel(SocketChannel ch) { ch.pipeline().addLast(new CMPPDecoder()); ch.pipeline().addLast(new CMPPHandler()); } }); ChannelFuture future bootstrap.connect(host, port).sync(); Channel channel future.channel();TCP_NODELAY 必須設為 true否則小字節(jié)的 CMPP 包會被 Nagle 算法合并導致網關側響應延遲明顯變大。SO_KEEPALIVE 只是內核級保活不能替代業(yè)務心跳這個后面會專門說。CMPPDecoder 要做的事就是讀前 4 字節(jié)的 Total_Length再按長度讀完整包解決粘包半包。NioEventLoopGroup 線程數我用 2一個負責 IO一個留給協議處理實際連接數和消息量上來后再調。3.2 登錄鑒權CMPP_CONNECT 的 Java 實現登錄是第一個坑點。CMPP_CONNECT 消息體包含 Source_Addr、AuthenticatorSource、Version、Timestamp 四個字段。其中 AuthenticatorSource 是 MD5 結果16 字節(jié)算法是MD5(Source_Addr 9字節(jié)0 sharedSecret Timestamp)。這里 9 字節(jié) 0 很容易漏掉漏了網關回你 3認證失敗。private ByteBuf buildConnectRequest(String spCode, String sharedSecret, int timestamp) { ByteBuf buf Unpooled.buffer(); int totalLength 12 6 16 1 4; int sequenceId sequenceIdGenerator.incrementAndGet(); buf.writeInt(totalLength); buf.writeInt(0x00000001); buf.writeInt(sequenceId); buf.writeBytes(fixedString(spCode, 6, StandardCharsets.ASCII)); buf.writeBytes(buildAuthenticatorSource(spCode, sharedSecret, timestamp)); buf.writeByte(0x30); // Version 3.0 buf.writeInt(timestamp); return buf; } private byte[] buildAuthenticatorSource(String spCode, String sharedSecret, int timestamp) throws Exception { byte[] spBytes spCode.getBytes(StandardCharsets.ASCII); byte[] secretBytes sharedSecret.getBytes(StandardCharsets.ASCII); ByteBuffer input ByteBuffer.allocate(spBytes.length 9 secretBytes.length 4); input.put(spBytes); input.put(new byte[9]); input.put(secretBytes); input.putInt(timestamp); return MessageDigest.getInstance(MD5).digest(input.array()); }timestamp 不是常見的時間戳而是 MMDDHHMMSS 格式比如 4 月 15 日 14 時 30 分 05 秒就是 0415143005作為 int 寫入。組裝時注意 Source_Addr 固定 6 字節(jié)如果 spCode 不足 6 位用 fixedString 補 0。Version 是 0x30表示 3.0不是 3。很多文檔寫“版本為30”結果有人直接寫 3網關也能連上但某些網關上功能受限我遇到過。3.3 心跳與重連CMPP_ACTIVE_TEST 和指數退避CMPP 網關一般要求 30 秒內至少有一次業(yè)務報文或心跳否則會斷開連接。我習慣用一個 ScheduledExecutorService 固定每 30 秒發(fā)一次 ActiveTest即使剛發(fā)送過 Submit 也照發(fā)邏輯簡單不會因為忘記重置計時器而被踢下線。private ScheduledExecutorService heartBeatScheduler Executors.newSingleThreadScheduledExecutor(); public void startHeartBeat() { heartBeatScheduler.scheduleAtFixedRate(() - { if (channel ! null channel.isActive()) { channel.writeAndFlush(new CMPPActiveTestRequest(sequenceIdGenerator.incrementAndGet())); } }, 30, 30, TimeUnit.SECONDS); }收到心跳響應用一個 AtomicInteger 記錄最近一次響應時間如果連續(xù) 3 次心跳沒響應就判定連接已死主動關閉并觸發(fā)重連。重連不要寫死循環(huán)用指數退避第一次等待 1 秒第二次 2 秒最多 30 秒避免網關恢復期間客戶端高頻重連把網關打崩。另外心跳線程一定要獨立不能和業(yè)務線程共用如果業(yè)務線程被滑動窗口阻塞心跳還能繼續(xù)發(fā)這個隔離能救很多次。3.4 發(fā)送 CMPP_SUBMIT組裝報文和控制窗口Submit 是項目里流量最大的部分。消息體字段多但關鍵的就幾個Msg_Id8 字節(jié)本地填 0響應里回填、Pk_total、Pk_number、Registered_Delivery、Msg_Fmt、Msg_Src、Src_Id、Msg_Length、Msg_Content。Registered_Delivery 設為 1才能收到狀態(tài)報告Msg_Fmt 這里先按 ASCII 處理中文短信用 UCS2后面長短信拆分再細講。發(fā)送前必須走窗口信號量。完整發(fā)送代碼如下public void sendSubmit(CMPPSubmitRequest request) throws InterruptedException { acquireWindow(); ByteBuf buf Unpooled.buffer(); request.encode(buf); channel.writeAndFlush(buf).addListener((ChannelFuture future) - { if (!future.isSuccess()) { releaseWindow(); log.error(submit 發(fā)送失敗, future.cause()); } }); } public void onSubmitResp(CMPPSubmitResp resp) { releaseWindow(); if (resp.getStatus() ! 0) { log.warn(submit 返回錯誤 status{}, msgId{}, resp.getStatus(), resp.getMsgId()); } else { log.info(submit 成功 msgId{}, resp.getMsgId()); } }注意 writeAndFlush 失敗時也要 releaseWindow否則窗口會被永久占用。onSubmitResp 里只做 window 釋放和日志記錄具體業(yè)務更新放在另一個異步線程池避免阻塞 Netty 的 EventLoop。如果在這個 Handler 里直接操作數據庫網關并發(fā)一高EventLoop 卡住心跳就發(fā)不出去緊接著就是連接斷開這是很多壓測翻車的直接原因。3.5 Spring Boot 里的配置組織項目里我不會把協議代碼和業(yè)務配置混在一起。用 Spring Boot 的話連接參數、窗口大小、心跳間隔全放 application.ymlcmpp: host: 192.168.10.20 port: 3150 sp-code: 100001 shared-secret: test123 window-size: 16 heartbeat-interval-sec: 30 reconnect-max-wait-sec: 30然后寫一個 CMPPProperties 類用 ConfigurationProperties 綁定。服務啟動時創(chuàng)建 CMPPClient用 SmartLifecycle 控制啟動順序應用關閉時先發(fā) Terminate 再釋放連接。這里要提醒一句連接建立不等于登錄成功登錄成功報文是 CONNECT_RESP這里的 Status 字段 0 才表示認證通過。我見過有的項目只檢測了 TCP 是否連接就對外報通道可用結果狀態(tài)監(jiān)控一片綠短信一條都發(fā)不出去。4. 消息路由與長短信拆分Java 實現里的高頻業(yè)務點4.1 區(qū)分 Deliver 上行和狀態(tài)報告Is_Report 字段說了算網關推送的 CMPP_DELIVER 有兩類用戶上行短信和狀態(tài)報告。區(qū)分方式很簡單看消息體里的 Is_Report 字段。Is_Report0 是用戶上行需要往業(yè)務系統轉Is_Report1 是狀態(tài)報告要解析里面的 Stat 字段更新短信發(fā)送狀態(tài)。狀態(tài)報告的 Msg_Content 是一段格式化文本常見是空行分隔的字段比如stat:DELIVRD done_time:20250615143005 sub_time:20250615142930解析代碼不要寫復雜正則按行 split 再按冒號拆一次就夠了public static MapString, String parseStatusReport(byte[] msgContent, Charset charset) { String text new String(msgContent, charset); MapString, String result new HashMap(); for (String line : text.split(\\r?\\n)) { int idx line.indexOf(:); if (idx 0) { result.put(line.substring(0, idx).trim(), line.substring(idx 1).trim()); } } return result; }狀態(tài)報告常見 Stat 值就三種DELIVRD成功、EXPIRED過期、UNDELIV不可達。我建議建一個枚舉把未知狀態(tài)先按失敗處理并告警不要默默丟棄。另外狀態(tài)報告的消息體編碼不一定和上行短信一樣有的網關用 GBK。Java 里不要默認 new String(msgContent)顯式指定編碼否則 Linux 部署后中文編譯環(huán)境一變解析出來就亂。4.2 長短信拆分67 字一條不是 70 字中文短信一條最多 70 個漢字但這指的是不帶 UDHI 頭的普通短信。CMPP3.0 長短信需要在消息體前面加 6 字節(jié)的 UDHI 頭用來標識分片信息所以真正留給短信內容的只有 67 個漢字。拆分時如果按 70 切分片會超長網關要么拒絕要么用戶收到亂碼。一個可用的拆分方法public static ListCMPPSubmitRequest splitLongMessage(String content, String mobile) { int maxCharsPerPart 67; int total (int) Math.ceil(content.length() / (double) maxCharsPerPart); ListCMPPSubmitRequest result new ArrayList(); for (int i 0; i total; i) { int start i * maxCharsPerPart; int end Math.min((i 1) * maxCharsPerPart, content.length()); String part content.substring(start, end); CMPPSubmitRequest request new CMPPSubmitRequest(); request.setMobile(mobile); request.setPkTotal(total); request.setPkNumber(i 1); request.setTpUdhi(1); request.setMsgFmt(8); byte[] partBytes part.getBytes(StandardCharsets.UTF_16BE); byte[] udhi buildUdhiHeader(total, i 1); byte[] msgContent new byte[udhi.length partBytes.length]; System.arraycopy(udhi, 0, msgContent, 0, udhi.length); System.arraycopy(partBytes, 0, msgContent, udhi.length, partBytes.length); request.setMsgContent(msgContent); request.setMsgLength(msgContent.length); result.add(request); } return result; } private static byte[] buildUdhiHeader(int total, int number) { return new byte[]{0x05, 0x00, 0x03, 0x0A, (byte) total, (byte) number}; }拆分時按 Java 的 char 數切不是按字節(jié)切。UCS2 下每個漢字是一個 char每個 char 兩個字節(jié)67 個 char 正好 134 字節(jié)加 6 字節(jié) UDHI 頭是 140 字節(jié)。buildUdhiHeader 里 0x05 表示后面有 5 個長度字節(jié)0x00 0x03 是 TP_UDHI 的拆分標識0x0A 是參考號后兩字節(jié)分別是總條數和當前條數。參考號可以固定也可以每條消息用隨機數但總分片數不能超過 255因為這是 1 字節(jié)字段。這條邏輯里有個隱藏邊界如果內容里包含 emojiJava 的 String.length 會把一個 emoji 記成兩個 char按這個思路拆某些分片可能把代理對切半。遇到這種內容建議升級到按 CodePoint 切分或者直接限制用戶輸入短信場景里 emoji 本來就容易亂碼。4.3 去重、存儲和異?；謴蛿祿煳ㄒ凰饕亲詈蟮亩档證MPP 消息在網絡傳輸中可能重發(fā)。Deliver 上行、狀態(tài)報告如果重復處理會給業(yè)務方造成重復訂單或者錯誤狀態(tài)。常見的做法是在數據庫表里給網關消息 Msg_Id 加唯一索引入庫時捕獲 DuplicateKeyException直接忽略第二遍。CREATE TABLE sms_deliver_log ( id BIGINT PRIMARY KEY AUTO_INCREMENT, msg_id BIGINT NOT NULL, mobile VARCHAR(32) NOT NULL, is_report TINYINT NOT NULL, content TEXT, stat VARCHAR(20), receive_time DATETIME NOT NULL, UNIQUE KEY uk_msg_id (msg_id) );Java 端的處理邏輯要注意順序先查一次再插入不如直接插入靠唯一索引攔并發(fā)下后一種才能真正防重。數據庫層面的唯一約束是最靠譜的兜底應用層用 ConcurrentHashMap 做去重只能擋住單機 JVM 內的重復。發(fā)送側的異?；謴透v究。Submit 發(fā)出去了但沒收到 Submit_Resp這時不能一概重發(fā)。因為消息可能已經到達網關重發(fā)會重復下發(fā)。我會在發(fā)送前給每條消息生成一個業(yè)務批次號把 Submit_Resp、Deliver 狀態(tài)報告都關聯到同一條發(fā)送記錄重發(fā)前先查這條記錄有沒有任何回執(zhí)有就不發(fā)。這樣處理重啟應用后也不會造成大面積重復短信。5. CMPP3.0_JAVA_實現避坑指南5 個讓我翻車過的黑匣子CMPP3.0 的 Java 實現里最折磨人的往往不是代碼本身而是問題現象看起來像網絡玄學實際上都是協議細節(jié)。下面五條都是我在真實聯調里踩過的每一條都按現象、原因、解決的順序說。5.1 登錄后立刻被斷開先抓報文別猜現象TCP 連接已經建立也發(fā)送了 CMPP_CONNECT甚至收到了 CONNECT_RESPStatus 為 0但緊接著幾秒內連接被網關斷開。日志里沒有任何異常只有連接關閉。原因AuthenticatorSource 的 MD5 計算錯了。最常見的是漏掉 9 字節(jié)的 0 填充或者 Timestamp 格式寫成了 Unix 時間戳。網關認證通過但后續(xù)第一個 Submit 報文格式不對也可能被立刻斷開。解決先把收發(fā)的字節(jié)流打印出來用十六進制對比協議文檔。Java 里加一個工具方法public static String toHex(byte[] data) { StringBuilder sb new StringBuilder(data.length * 2); for (byte b : data) { sb.append(String.format(%02x , b)); } return sb.toString(); }在發(fā)送 CONNECT 前后各打一行。看 Total_Length 是不是 39Command_Id 是不是 00000001AuthenticatorSource 是不是 16 字節(jié)。如果和樣例報文不一致就別懷疑網關先修本地代碼。5.2 Submit 返回 Status0用戶卻收不到短信現象CMPP_SUBMIT_RESP 里 Status 是 0業(yè)務日志顯示發(fā)送成功但手機遲遲收不到短信狀態(tài)報告也始終不來。原因賬號配置和網關側分配不一致。常見的有 Source_Addr 的 SP 企業(yè)代碼填錯Msg_Src 和 Source_Addr 混用Src_Id 設置了不存在的擴展短號。網關只校驗來源認證不校驗這些業(yè)務字段所以認證能過但消息被內部路由丟棄。解決拿網關分配的開戶資料逐項核對。Source_Addr 是 6 位企業(yè)代碼Msg_Src 是 SP_CodeSrc_Id 是顯示主叫號碼通常是服務代碼或者擴展短號。先用最簡消息測一條純 ASCII 文本附帶 Registered_Delivery1確認狀態(tài)報告能回來再換成真實業(yè)務內容。不要直接灰度大批量發(fā)送否則收不到你得從成千上萬條記錄里排查。5.3 并發(fā)一上來就頻繁重連EventLoop 被業(yè)務代碼卡死了現象單條消息測試正常壓測到幾十條并發(fā)時開始出現 ACTIVE_TEST_RESP 超時然后連接斷開客戶端自動重連重連后又斷。原因Netty 的 EventLoop 線程被阻塞了。最常見的是在 ChannelHandler 里直接同步查數據庫、調用外部接口或者發(fā)送窗口沒有控制消息隊列積壓導致響應處理延遲。心跳也走同一個 EventLoop心跳響應沒人處理網關就判定超時斷開。解決把 IO 線程和業(yè)務線程嚴格分開。Netty 的 Handler 只做協議編解碼和窗口釋放業(yè)務處理丟給獨立線程池。窗口控制用前面寫的 Semaphore發(fā)送前 tryAcquire拿不到就快速失敗絕不無界堆積。另外檢查是否在 EventLoop 里調用了 channel.writeAndFlush 的大包同步等待應該用監(jiān)聽器異步回調。5.4 內存溢出從幾百 MB 漲到幾個 G無界隊列是元兇現象Java 進程啟動時內存正常運行一段時間后堆內存持續(xù)上漲最終拋出 OutOfMemoryError應用重啟后重復出現。原因發(fā)送線程和網關響應速度不匹配。網關響應慢提交到線程池的任務越來越多如果用的 LinkedBlockingQueue 沒設容量任務全部積壓在堆里。CMPP 消息內容一多內存直接被打滿。解決有界隊列加拒絕策略。不要用 Executors.newFixedThreadPool 里默認的無界隊列改成BlockingQueueRunnable queue new ArrayBlockingQueue(10000); ThreadPoolExecutor pool new ThreadPoolExecutor( 8, 16, 60, TimeUnit.SECONDS, queue, new ThreadPoolExecutor.CallerRunsPolicy());CallerRunsPolicy 讓提交線程自己執(zhí)行任務形成天然背壓比 AbortPolicy 更友好。JVM 啟動參數按機器內存來不要跟風配大我一般用 -Xms512m -Xmx1024m堆太大反而讓問題暴露得晚。5.5 Linux 上中文亂碼顯式指定字符集別吃平臺默認值現象本地 Windows 開發(fā)測試正常部署到 Linux 后發(fā)送的中文短信到手機變問號或者收到的狀態(tài)報告解析亂碼。原因CMPP3.0 的消息內容是編碼字節(jié)不攜帶字符集聲明。Java 代碼里用了 String.getBytes() 無參版本Windows 默認 GBKLinux 默認 UTF-8兩邊編碼不一致字節(jié)流自然不對。網關按協議里 Msg_Fmt 指定的編碼解析時數據已經錯了。解決Java 代碼里所有 CMPP 編解碼都顯式寫字符集參數。中文短信 Msg_Fmt8 時用 UTF-16BE狀態(tài)報告解析如果需要 GBK 就傳 GBK不要依賴默認環(huán)境。編譯時也固定編碼mvn clean package -Dfile.encodingUTF-8同時檢查 Spring Boot 的 server.servlet.encoding 配置雖然它影響不到這些字節(jié)流但統一 UTF-8 能減少其他環(huán)節(jié)的干擾。這個問題是血淚經驗曾經線上亂碼查了兩天最后就是一行 getBytes() 少了 charset 參數。6. 進階給 CMPP3.0 Java 客戶端加一個 Mock 網關做回歸驗證6.1 用 Netty 寫一個最小 Mock 網關真實網關不是隨便就能連的聯調要等工單、要排期出了問題兩邊還容易扯皮。我的習慣是在項目里保留一個 Mock 網關用來做自動化回歸測試。它能做的就是收到 CONNECT 回 CONNECT_RESP收到 SUBMIT 回 SUBMIT_RESP收到 ACTIVE_TEST 回 ACTIVE_TEST_RESP。這樣客戶端代碼改完跑一遍用例就可以確認協議層沒壞。一個最小 Mock 網關的核心邏輯可以這樣寫public class MockCMPPServer { public void start() throws InterruptedException { EventLoopGroup bossGroup new NioEventLoopGroup(1); EventLoopGroup workerGroup new NioEventLoopGroup(1); ServerBootstrap bootstrap new ServerBootstrap(); bootstrap.group(bossGroup, workerGroup) .channel(NioServerSocketChannel.class) .childHandler(new ChannelInitializerSocketChannel() { Override protected void initChannel(SocketChannel ch) { ch.pipeline().addLast(new CMPPDecoder()); ch.pipeline().addLast(new SimpleChannelInboundHandlerByteBuf() { Override protected void channelRead0(ChannelHandlerContext ctx, ByteBuf msg) { int commandId msg.getInt(4); if (commandId 0x00000001) { ctx.writeAndFlush(buildConnectResp(msg.getInt(8))); } else if (commandId 0x00000002) { ctx.writeAndFlush(buildSubmitResp(msg.getInt(8))); } else if (commandId 0x00000004) { ctx.writeAndFlush(buildActiveTestResp(msg.getInt(8))); } } }); } }); bootstrap.bind(3151).sync(); } }Mock 網關里不需要完整解析每個字段只需要讀 Command_Id 和 Sequence_Id然后按相同 Sequence_Id 回包。CMPP 客戶端一般用自己的流水號匹配響應所以 Mock 網關回包時把請求里的 Sequence_Id 原樣帶回去即可。這段代碼的邊界在于它不會校驗 AuthenticatorSource所以只適合做客戶端回歸測試不適合做協議正確性驗證。6.2 壓測參數建議用 Mock 網關做壓測時參數別隨便拍腦袋。最基礎的一組建議參數建議值說明發(fā)送線程數8不要超過窗口大小的 2 倍滑動窗口大小16與真實網關配置保持一致Submit 超時5 秒超過則記錄失敗壓測時長10 分鐘觀察內存和連接穩(wěn)定性心跳間隔30 秒模擬真實節(jié)奏壓測時重點看兩個指標成功發(fā)送的 TPS 和未響應消息積壓數。如果 TPS 上不去但窗口一直為空說明發(fā)送線程被網關響應延遲拖著先查 Mock 網關的日志如果窗口一直滿說明消費速度不夠調大線程池之前先確認數據庫寫入有沒有瓶頸。真實網關的響應時間和 Mock 網關差別很大正式上線前還是要用真實網關小流量跑一遍。我前兩年接一個新網關上來就急著聯調結果連不上折騰兩天發(fā)現是 MD5 里少補了 9 個字節(jié)。那次之后我養(yǎng)成了一個習慣每個 CMPP 客戶端項目都必須保留 Mock 網關協議層改動先跑回歸再上真實環(huán)境驗證。短信通道這東西不提前準備好后悔藥出事時連定位的抓手都沒有。希望幫到你。本文還有配套的精品資源點擊獲取