：協(xié)議拆解與避坑指南)
簡介面向Java短信網(wǎng)關(guān)開發(fā)者的CMPP3.0協(xié)議實現(xiàn)參考包圍繞中國移動CMPP3.0規(guī)范覆蓋短信提交、接收、狀態(tài)查詢等核心業(yè)務(wù)可直接作為短信服務(wù)接入與二次開發(fā)的基礎(chǔ)示例。壓縮包共17個文件以14個Java源文件為主輔以properties配置文件與2個txt說明文檔整體僅23KB代碼量精簡但模塊劃分清晰common包封裝公共處理邏輯msg包處理消息業(yè)務(wù)定時器示例配合心跳機制使用。實現(xiàn)中重點演示了TCP長連接與心跳保持、GBK編碼轉(zhuǎn)換、多線程處理并發(fā)請求、異常重試與短信狀態(tài)跟蹤等關(guān)鍵模塊與CMPP3.0十大學(xué)習(xí)要點一一對應(yīng)說明文檔對配置項和運行方式也給出必要引導(dǎo)。目前已有949人學(xué)習(xí)適合具備一定Java基礎(chǔ)、正在對接短信網(wǎng)關(guān)或需要快速理解CMPP3.0報文格式與收發(fā)流程的開發(fā)者通過閱讀源碼與配置可掌握Java環(huán)境下CMPP3.0的落地結(jié)構(gòu)并據(jù)此擴展自己的生產(chǎn)級實現(xiàn)。1. cmpp3.0_JAVA_實現(xiàn)為什么你的短信網(wǎng)關(guān)項目繞不開這組關(guān)鍵詞做短信網(wǎng)關(guān)對接的 Java 工程師十有八九都在項目里見過“cmpp3.0_JAVA_實現(xiàn)”這組關(guān)鍵詞。它不是什么高深算法而是中國移動短信網(wǎng)關(guān) CMPP3.0 協(xié)議的接入落地用 Java 寫一個能收發(fā)短信、能收狀態(tài)報告、能扛住一定并發(fā)的客戶端模塊。網(wǎng)上資料零散協(xié)議文檔又是十六進制黑話導(dǎo)致很多人卡在登錄報文和滑動窗口上連上就斷、發(fā)了沒響應(yīng)。這篇文章我按自己的落地路徑講清楚協(xié)議怎么拆、代碼怎么組織、哪些參數(shù)不能亂調(diào)最后把最容易翻車的坑挨個點出來。適合正在接短信通道、或者被派去維護老短信系統(tǒng)的讀者新手能照著寫熟手可以拿避坑清單當(dāng)檢查項。2. CMPP3.0 協(xié)議先立住四種消息、無符號整數(shù)和滑動窗口2.1 四種消息類型和 Java 里的命令字CMPP3.0 的通信不是 HTTP是一條 TCP 長連接上的二進制消息流。雖然文檔里有十幾種消息但 Java 實現(xiàn)里真正高頻的只有四組Connect登錄鑒權(quán)、Submit下發(fā)短信、Deliver上行短信和狀態(tài)報告、ActiveTest心跳。真正斷開連接用的 Terminate 在客戶端主動退出時才會用到。先把命令字整理成表后面寫解碼器會反復(fù)用到消息作用Command_Id建議常量名登錄請求0x00000001CMPP_CONNECT登錄響應(yīng)0x80000001CMPP_CONNECT_RESP下發(fā)短信請求0x00000002CMPP_SUBMIT下發(fā)短信響應(yīng)0x80000002CMPP_SUBMIT_RESP上行/狀態(tài)報告請求0x00000003CMPP_DELIVER上行/狀態(tài)報告響應(yīng)0x80000003CMPP_DELIVER_RESP心跳請求0x00000004CMPP_ACTIVE_TEST心跳響應(yīng)0x80000004CMPP_ACTIVE_TEST_RESP注意 Command_Id 的規(guī)律請求的最高位是 0響應(yīng)最高位是 1。這個規(guī)律在調(diào)試時很有用看到 0x8 開頭就知道是網(wǎng)關(guān)回包。但在 Java 里有個小坑0x80000001 超過了 int 的正數(shù)范圍讀出來可能是負數(shù)。我一般用 long 或者 Integer.compareUnsigned 來做比較避免“這個數(shù)怎么是負的”這種問題。2.2 消息頭、字節(jié)序和 Sequence_IdCMPP3.0 每條消息開頭固定 12 字節(jié)的消息頭三個 int 字段全部是大端序Total_Length、Command_Id、Sequence_Id。Total_Length 是整個消息的長度包含這 12 字節(jié)本身Sequence_Id 是流水號從 0 開始累加用來匹配請求和響應(yīng)。協(xié)議里幾乎全是無符號整數(shù)Java 的 int 也是 32 位但最高位是符號位。好消息是用 Netty 的 ByteBuf 寫入時 writeInt 只是按位寫Java 正負數(shù)不影響網(wǎng)絡(luò)字節(jié)序壞消息是從 ByteBuf 讀的時候要用 readUnsignedInt 才能拿到正確的 0-4294967295 范圍值。我習(xí)慣把消息頭獨立封裝出來避免每個消息體都重復(fù)處理粘包和半包。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(); } }這段代碼里的關(guān)鍵點是 sequenceId 讀取。協(xié)議里 Sequence_Id 是無符號如果直接 readInt 會讀到負數(shù)后續(xù)用這個值做 key 匹配響應(yīng)時容易出問題。網(wǎng)絡(luò)字節(jié)序方面ByteBuf 默認就是大端和 CMPP 協(xié)議一致不需要額外調(diào) ByteOrder。參數(shù)上sequenceId 用 AtomicInteger 生成就夠了。注意它最大到 0xFFFFFFFF到達上限后要歸零。如果用了 readUnsignedInt就不會因為符號問題導(dǎo)致回繞判斷錯誤。這里再說一句別用 synchronized 保護一個 int 自增AtomicInteger 足夠網(wǎng)關(guān)接口是長連接請求量上來后鎖競爭會拖慢整個發(fā)送鏈路。2.3 滑動窗口并發(fā)發(fā)送前的第一個控制參數(shù)CMPP3.0 的滑動窗口機制簡單說就是同一時刻最多能有多少條 Submit 消息沒收到 Submit_Resp。窗口大小規(guī)范默認是 16具體值由網(wǎng)關(guān)側(cè)配置決定客戶端必須遵守。如果客戶端無限往里灌網(wǎng)關(guān)會直接斷開連接而且不會告訴你原因。Java 里實現(xiàn)窗口最干凈的方式是信號量。每條 Submit 發(fā)送前 acquire收到 Submit_Resp 后 release。這樣發(fā)送線程會被自然阻塞而不是把消息堆進無界隊列后內(nèi)存爆掉。private final Semaphore window new Semaphore(16); public void acquireWindow() throws InterruptedException { if (!window.tryAcquire(3, TimeUnit.SECONDS)) { throw new IllegalStateException(滑動窗口已滿網(wǎng)關(guān)響應(yīng)過慢); } } public void releaseWindow() { window.release(); }窗口大小為什么是 16 而不是 100這是協(xié)議設(shè)計好的背壓閾值超過閾值網(wǎng)關(guān)會認為客戶端失控。我用 tryAcquire 而不是 acquire是為了在窗口長期占滿時讓發(fā)送線程快速失敗而不是無限阻塞否則故障時線程池會被卡滿。3 秒超時是個經(jīng)驗值真實網(wǎng)關(guān)一般幾十毫秒到幾百毫秒就回 Submit_Resp如果 3 秒都沒窗口說明響應(yīng)鏈路已經(jīng)不正常應(yīng)該告警而不是繼續(xù)等。2.4 用 Java 對象建模協(xié)議字段定長字符串的坑CMPP3.0 的消息體里大量使用定長字符串比如 Source_Addr 固定 6 字節(jié)Service_Id 固定 10 字節(jié)。協(xié)議規(guī)定不足部分按位補 0不是補空格。很多人把 String 直接 getBytes 塞進去結(jié)果長度不夠多出來的隨機數(shù)據(jù)導(dǎo)致網(wǎng)關(guān)解析錯亂。我一般先封裝一個定長編碼方法統(tǒng)一處理這種情況public static byte[] fixedString(String value, int length, Charset charset) { byte[] raw value.getBytes(charset); if (raw.length length) { throw new IllegalArgumentException(字段超長當(dāng)前值 value); } byte[] out new byte[length]; System.arraycopy(raw, 0, out, 0, raw.length); return out; }補充說明定長字段在 CMPP 文檔里通常標注“字符串”但具體是 ASCII 還是 GBK要看字段類型。比如 Source_Addr 和 Msg_Src 是數(shù)字組成的企業(yè)代碼用 ASCII 就可以Service_Id 可能是字母加數(shù)字也建議 ASCII。Msg_Content 的業(yè)務(wù)內(nèi)容才根據(jù) Msg_Fmt 用 UCS2 或 GBK。用 charset 參數(shù)顯式傳入能避免將來換服務(wù)器后平臺默認編碼變了導(dǎo)致亂碼。這個細節(jié)就是 CMPP3.0_Java 實現(xiàn)里最常見的“看著代碼沒問題一上線就出事”的源頭。3. 從零搭一個 CMPP3.0 Java 客戶端五個可復(fù)現(xiàn)的步驟3.1 選型Netty 還是原生 SocketCMPP3.0 是二進制協(xié)議必然涉及粘包、半包、字節(jié)序轉(zhuǎn)換。原生 Socket 也能做但所有協(xié)議解析都要自己寫還要自己管理線程池。Netty 的優(yōu)勢在于 ByteBuf、ChannelPipeline 和內(nèi)置的定時任務(wù)能讓代碼結(jié)構(gòu)干凈很多。Mina 也見過人用但近年新項目選 Netty 更多社區(qū)資料也全。選型對比可以按這個參考方案協(xié)議解析線程模型維護成本原生 Socket自己處理容易漏字節(jié)每連接一線程擴展麻煩低依賴但出問題全得自己扛Mina自帶解碼器有 IoHandler 模型老項目多新資料少NettyByteBuf 解碼器EventLoop 異步模型需要一點學(xué)習(xí)曲線我選 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 必須設(shè)為 true否則小字節(jié)的 CMPP 包會被 Nagle 算法合并導(dǎo)致網(wǎng)關(guān)側(cè)響應(yīng)延遲明顯變大。SO_KEEPALIVE 只是內(nèi)核級?；畈荒芴娲鷺I(yè)務(wù)心跳這個后面會專門說。CMPPDecoder 要做的事就是讀前 4 字節(jié)的 Total_Length再按長度讀完整包解決粘包半包。NioEventLoopGroup 線程數(shù)我用 2一個負責(zé) IO一個留給協(xié)議處理實際連接數(shù)和消息量上來后再調(diào)。3.2 登錄鑒權(quán)CMPP_CONNECT 的 Java 實現(xiàn)登錄是第一個坑點。CMPP_CONNECT 消息體包含 Source_Addr、AuthenticatorSource、Version、Timestamp 四個字段。其中 AuthenticatorSource 是 MD5 結(jié)果16 字節(jié)算法是MD5(Source_Addr 9字節(jié)0 sharedSecret Timestamp)。這里 9 字節(jié) 0 很容易漏掉漏了網(wǎng)關(guān)回你 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”結(jié)果有人直接寫 3網(wǎng)關(guān)也能連上但某些網(wǎng)關(guān)上功能受限我遇到過。3.3 心跳與重連CMPP_ACTIVE_TEST 和指數(shù)退避CMPP 網(wǎng)關(guān)一般要求 30 秒內(nèi)至少有一次業(yè)務(wù)報文或心跳否則會斷開連接。我習(xí)慣用一個 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); }收到心跳響應(yīng)用一個 AtomicInteger 記錄最近一次響應(yīng)時間如果連續(xù) 3 次心跳沒響應(yīng)就判定連接已死主動關(guān)閉并觸發(fā)重連。重連不要寫死循環(huán)用指數(shù)退避第一次等待 1 秒第二次 2 秒最多 30 秒避免網(wǎng)關(guān)恢復(fù)期間客戶端高頻重連把網(wǎng)關(guān)打崩。另外心跳線程一定要獨立不能和業(yè)務(wù)線程共用如果業(yè)務(wù)線程被滑動窗口阻塞心跳還能繼續(xù)發(fā)這個隔離能救很多次。3.4 發(fā)送 CMPP_SUBMIT組裝報文和控制窗口Submit 是項目里流量最大的部分。消息體字段多但關(guān)鍵的就幾個Msg_Id8 字節(jié)本地填 0響應(yīng)里回填、Pk_total、Pk_number、Registered_Delivery、Msg_Fmt、Msg_Src、Src_Id、Msg_Length、Msg_Content。Registered_Delivery 設(shè)為 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è)務(wù)更新放在另一個異步線程池避免阻塞 Netty 的 EventLoop。如果在這個 Handler 里直接操作數(shù)據(jù)庫網(wǎng)關(guān)并發(fā)一高EventLoop 卡住心跳就發(fā)不出去緊接著就是連接斷開這是很多壓測翻車的直接原因。3.5 Spring Boot 里的配置組織項目里我不會把協(xié)議代碼和業(yè)務(wù)配置混在一起。用 Spring Boot 的話連接參數(shù)、窗口大小、心跳間隔全放 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 綁定。服務(wù)啟動時創(chuàng)建 CMPPClient用 SmartLifecycle 控制啟動順序應(yīng)用關(guān)閉時先發(fā) Terminate 再釋放連接。這里要提醒一句連接建立不等于登錄成功登錄成功報文是 CONNECT_RESP這里的 Status 字段 0 才表示認證通過。我見過有的項目只檢測了 TCP 是否連接就對外報通道可用結(jié)果狀態(tài)監(jiān)控一片綠短信一條都發(fā)不出去。4. 消息路由與長短信拆分Java 實現(xiàn)里的高頻業(yè)務(wù)點4.1 區(qū)分 Deliver 上行和狀態(tài)報告Is_Report 字段說了算網(wǎng)關(guān)推送的 CMPP_DELIVER 有兩類用戶上行短信和狀態(tài)報告。區(qū)分方式很簡單看消息體里的 Is_Report 字段。Is_Report0 是用戶上行需要往業(yè)務(wù)系統(tǒng)轉(zhuǎn)Is_Report1 是狀態(tài)報告要解析里面的 Stat 字段更新短信發(fā)送狀態(tài)。狀態(tài)報告的 Msg_Content 是一段格式化文本常見是空行分隔的字段比如stat:DELIVRD done_time:20250615143005 sub_time:20250615142930解析代碼不要寫復(fù)雜正則按行 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)報告的消息體編碼不一定和上行短信一樣有的網(wǎng)關(guān)用 GBK。Java 里不要默認 new String(msgContent)顯式指定編碼否則 Linux 部署后中文編譯環(huán)境一變解析出來就亂。4.2 長短信拆分67 字一條不是 70 字中文短信一條最多 70 個漢字但這指的是不帶 UDHI 頭的普通短信。CMPP3.0 長短信需要在消息體前面加 6 字節(jié)的 UDHI 頭用來標識分片信息所以真正留給短信內(nèi)容的只有 67 個漢字。拆分時如果按 70 切分片會超長網(wǎng)關(guān)要么拒絕要么用戶收到亂碼。一個可用的拆分方法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 數(shù)切不是按字節(jié)切。UCS2 下每個漢字是一個 char每個 char 兩個字節(jié)67 個 char 正好 134 字節(jié)加 6 字節(jié) UDHI 頭是 140 字節(jié)。buildUdhiHeader 里 0x05 表示后面有 5 個長度字節(jié)0x00 0x03 是 TP_UDHI 的拆分標識0x0A 是參考號后兩字節(jié)分別是總條數(shù)和當(dāng)前條數(shù)。參考號可以固定也可以每條消息用隨機數(shù)但總分片數(shù)不能超過 255因為這是 1 字節(jié)字段。這條邏輯里有個隱藏邊界如果內(nèi)容里包含 emojiJava 的 String.length 會把一個 emoji 記成兩個 char按這個思路拆某些分片可能把代理對切半。遇到這種內(nèi)容建議升級到按 CodePoint 切分或者直接限制用戶輸入短信場景里 emoji 本來就容易亂碼。4.3 去重、存儲和異常恢復(fù)數(shù)據(jù)庫唯一索引是最后的兜底CMPP 消息在網(wǎng)絡(luò)傳輸中可能重發(fā)。Deliver 上行、狀態(tài)報告如果重復(fù)處理會給業(yè)務(wù)方造成重復(fù)訂單或者錯誤狀態(tài)。常見的做法是在數(shù)據(jù)庫表里給網(wǎng)關(guān)消息 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ā)下后一種才能真正防重。數(shù)據(jù)庫層面的唯一約束是最靠譜的兜底應(yīng)用層用 ConcurrentHashMap 做去重只能擋住單機 JVM 內(nèi)的重復(fù)。發(fā)送側(cè)的異常恢復(fù)更講究。Submit 發(fā)出去了但沒收到 Submit_Resp這時不能一概重發(fā)。因為消息可能已經(jīng)到達網(wǎng)關(guān)重發(fā)會重復(fù)下發(fā)。我會在發(fā)送前給每條消息生成一個業(yè)務(wù)批次號把 Submit_Resp、Deliver 狀態(tài)報告都關(guān)聯(lián)到同一條發(fā)送記錄重發(fā)前先查這條記錄有沒有任何回執(zhí)有就不發(fā)。這樣處理重啟應(yīng)用后也不會造成大面積重復(fù)短信。5. CMPP3.0_JAVA_實現(xiàn)避坑指南5 個讓我翻車過的黑匣子CMPP3.0 的 Java 實現(xiàn)里最折磨人的往往不是代碼本身而是問題現(xiàn)象看起來像網(wǎng)絡(luò)玄學(xué)實際上都是協(xié)議細節(jié)。下面五條都是我在真實聯(lián)調(diào)里踩過的每一條都按現(xiàn)象、原因、解決的順序說。5.1 登錄后立刻被斷開先抓報文別猜現(xiàn)象TCP 連接已經(jīng)建立也發(fā)送了 CMPP_CONNECT甚至收到了 CONNECT_RESPStatus 為 0但緊接著幾秒內(nèi)連接被網(wǎng)關(guān)斷開。日志里沒有任何異常只有連接關(guān)閉。原因AuthenticatorSource 的 MD5 計算錯了。最常見的是漏掉 9 字節(jié)的 0 填充或者 Timestamp 格式寫成了 Unix 時間戳。網(wǎng)關(guān)認證通過但后續(xù)第一個 Submit 報文格式不對也可能被立刻斷開。解決先把收發(fā)的字節(jié)流打印出來用十六進制對比協(xié)議文檔。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é)。如果和樣例報文不一致就別懷疑網(wǎng)關(guān)先修本地代碼。5.2 Submit 返回 Status0用戶卻收不到短信現(xiàn)象CMPP_SUBMIT_RESP 里 Status 是 0業(yè)務(wù)日志顯示發(fā)送成功但手機遲遲收不到短信狀態(tài)報告也始終不來。原因賬號配置和網(wǎng)關(guān)側(cè)分配不一致。常見的有 Source_Addr 的 SP 企業(yè)代碼填錯Msg_Src 和 Source_Addr 混用Src_Id 設(shè)置了不存在的擴展短號。網(wǎng)關(guān)只校驗來源認證不校驗這些業(yè)務(wù)字段所以認證能過但消息被內(nèi)部路由丟棄。解決拿網(wǎng)關(guān)分配的開戶資料逐項核對。Source_Addr 是 6 位企業(yè)代碼Msg_Src 是 SP_CodeSrc_Id 是顯示主叫號碼通常是服務(wù)代碼或者擴展短號。先用最簡消息測一條純 ASCII 文本附帶 Registered_Delivery1確認狀態(tài)報告能回來再換成真實業(yè)務(wù)內(nèi)容。不要直接灰度大批量發(fā)送否則收不到你得從成千上萬條記錄里排查。5.3 并發(fā)一上來就頻繁重連EventLoop 被業(yè)務(wù)代碼卡死了現(xiàn)象單條消息測試正常壓測到幾十條并發(fā)時開始出現(xiàn) ACTIVE_TEST_RESP 超時然后連接斷開客戶端自動重連重連后又斷。原因Netty 的 EventLoop 線程被阻塞了。最常見的是在 ChannelHandler 里直接同步查數(shù)據(jù)庫、調(diào)用外部接口或者發(fā)送窗口沒有控制消息隊列積壓導(dǎo)致響應(yīng)處理延遲。心跳也走同一個 EventLoop心跳響應(yīng)沒人處理網(wǎng)關(guān)就判定超時斷開。解決把 IO 線程和業(yè)務(wù)線程嚴格分開。Netty 的 Handler 只做協(xié)議編解碼和窗口釋放業(yè)務(wù)處理丟給獨立線程池。窗口控制用前面寫的 Semaphore發(fā)送前 tryAcquire拿不到就快速失敗絕不無界堆積。另外檢查是否在 EventLoop 里調(diào)用了 channel.writeAndFlush 的大包同步等待應(yīng)該用監(jiān)聽器異步回調(diào)。5.4 內(nèi)存溢出從幾百 MB 漲到幾個 G無界隊列是元兇現(xiàn)象Java 進程啟動時內(nèi)存正常運行一段時間后堆內(nèi)存持續(xù)上漲最終拋出 OutOfMemoryError應(yīng)用重啟后重復(fù)出現(xiàn)。原因發(fā)送線程和網(wǎng)關(guān)響應(yīng)速度不匹配。網(wǎng)關(guān)響應(yīng)慢提交到線程池的任務(wù)越來越多如果用的 LinkedBlockingQueue 沒設(shè)容量任務(wù)全部積壓在堆里。CMPP 消息內(nèi)容一多內(nèi)存直接被打滿。解決有界隊列加拒絕策略。不要用 Executors.newFixedThreadPool 里默認的無界隊列改成BlockingQueueRunnable queue new ArrayBlockingQueue(10000); ThreadPoolExecutor pool new ThreadPoolExecutor( 8, 16, 60, TimeUnit.SECONDS, queue, new ThreadPoolExecutor.CallerRunsPolicy());CallerRunsPolicy 讓提交線程自己執(zhí)行任務(wù)形成天然背壓比 AbortPolicy 更友好。JVM 啟動參數(shù)按機器內(nèi)存來不要跟風(fēng)配大我一般用 -Xms512m -Xmx1024m堆太大反而讓問題暴露得晚。5.5 Linux 上中文亂碼顯式指定字符集別吃平臺默認值現(xiàn)象本地 Windows 開發(fā)測試正常部署到 Linux 后發(fā)送的中文短信到手機變問號或者收到的狀態(tài)報告解析亂碼。原因CMPP3.0 的消息內(nèi)容是編碼字節(jié)不攜帶字符集聲明。Java 代碼里用了 String.getBytes() 無參版本W(wǎng)indows 默認 GBKLinux 默認 UTF-8兩邊編碼不一致字節(jié)流自然不對。網(wǎng)關(guān)按協(xié)議里 Msg_Fmt 指定的編碼解析時數(shù)據(jù)已經(jīng)錯了。解決Java 代碼里所有 CMPP 編解碼都顯式寫字符集參數(shù)。中文短信 Msg_Fmt8 時用 UTF-16BE狀態(tài)報告解析如果需要 GBK 就傳 GBK不要依賴默認環(huán)境。編譯時也固定編碼mvn clean package -Dfile.encodingUTF-8同時檢查 Spring Boot 的 server.servlet.encoding 配置雖然它影響不到這些字節(jié)流但統(tǒng)一 UTF-8 能減少其他環(huán)節(jié)的干擾。這個問題是血淚經(jīng)驗曾經(jīng)線上亂碼查了兩天最后就是一行 getBytes() 少了 charset 參數(shù)。6. 進階給 CMPP3.0 Java 客戶端加一個 Mock 網(wǎng)關(guān)做回歸驗證6.1 用 Netty 寫一個最小 Mock 網(wǎng)關(guān)真實網(wǎng)關(guān)不是隨便就能連的聯(lián)調(diào)要等工單、要排期出了問題兩邊還容易扯皮。我的習(xí)慣是在項目里保留一個 Mock 網(wǎng)關(guān)用來做自動化回歸測試。它能做的就是收到 CONNECT 回 CONNECT_RESP收到 SUBMIT 回 SUBMIT_RESP收到 ACTIVE_TEST 回 ACTIVE_TEST_RESP。這樣客戶端代碼改完跑一遍用例就可以確認協(xié)議層沒壞。一個最小 Mock 網(wǎng)關(guān)的核心邏輯可以這樣寫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 網(wǎng)關(guān)里不需要完整解析每個字段只需要讀 Command_Id 和 Sequence_Id然后按相同 Sequence_Id 回包。CMPP 客戶端一般用自己的流水號匹配響應(yīng)所以 Mock 網(wǎng)關(guān)回包時把請求里的 Sequence_Id 原樣帶回去即可。這段代碼的邊界在于它不會校驗 AuthenticatorSource所以只適合做客戶端回歸測試不適合做協(xié)議正確性驗證。6.2 壓測參數(shù)建議用 Mock 網(wǎng)關(guān)做壓測時參數(shù)別隨便拍腦袋。最基礎(chǔ)的一組建議參數(shù)建議值說明發(fā)送線程數(shù)8不要超過窗口大小的 2 倍滑動窗口大小16與真實網(wǎng)關(guān)配置保持一致Submit 超時5 秒超過則記錄失敗壓測時長10 分鐘觀察內(nèi)存和連接穩(wěn)定性心跳間隔30 秒模擬真實節(jié)奏壓測時重點看兩個指標成功發(fā)送的 TPS 和未響應(yīng)消息積壓數(shù)。如果 TPS 上不去但窗口一直為空說明發(fā)送線程被網(wǎng)關(guān)響應(yīng)延遲拖著先查 Mock 網(wǎng)關(guān)的日志如果窗口一直滿說明消費速度不夠調(diào)大線程池之前先確認數(shù)據(jù)庫寫入有沒有瓶頸。真實網(wǎng)關(guān)的響應(yīng)時間和 Mock 網(wǎng)關(guān)差別很大正式上線前還是要用真實網(wǎng)關(guān)小流量跑一遍。我前兩年接一個新網(wǎng)關(guān)上來就急著聯(lián)調(diào)結(jié)果連不上折騰兩天發(fā)現(xiàn)是 MD5 里少補了 9 個字節(jié)。那次之后我養(yǎng)成了一個習(xí)慣每個 CMPP 客戶端項目都必須保留 Mock 網(wǎng)關(guān)協(xié)議層改動先跑回歸再上真實環(huán)境驗證。短信通道這東西不提前準備好后悔藥出事時連定位的抓手都沒有。希望幫到你。本文還有配套的精品資源點擊獲取 CMPP3.0 Java實現(xiàn)：協(xié)議拆解與避坑指南
簡介面向Java短信網(wǎng)關(guān)開發(fā)者的CMPP3.0協(xié)議實現(xiàn)參考包圍繞中國移動CMPP3.0規(guī)范覆蓋短信提交、接收、狀態(tài)查詢等核心業(yè)務(wù)可直接作為短信服務(wù)接入與二次開發(fā)的基礎(chǔ)示例。壓縮包共17個文件以14個Java源文件為主輔以properties配置文件與2個txt說明文檔整體僅23KB代碼量精簡但模塊劃分清晰common包封裝公共處理邏輯msg包處理消息業(yè)務(wù)定時器示例配合心跳機制使用。實現(xiàn)中重點演示了TCP長連接與心跳保持、GBK編碼轉(zhuǎn)換、多線程處理并發(fā)請求、異常重試與短信狀態(tài)跟蹤等關(guān)鍵模塊與CMPP3.0十大學(xué)習(xí)要點一一對應(yīng)說明文檔對配置項和運行方式也給出必要引導(dǎo)。目前已有949人學(xué)習(xí)適合具備一定Java基礎(chǔ)、正在對接短信網(wǎng)關(guān)或需要快速理解CMPP3.0報文格式與收發(fā)流程的開發(fā)者通過閱讀源碼與配置可掌握Java環(huán)境下CMPP3.0的落地結(jié)構(gòu)并據(jù)此擴展自己的生產(chǎn)級實現(xiàn)。1. cmpp3.0_JAVA_實現(xiàn)為什么你的短信網(wǎng)關(guān)項目繞不開這組關(guān)鍵詞做短信網(wǎng)關(guān)對接的 Java 工程師十有八九都在項目里見過“cmpp3.0_JAVA_實現(xiàn)”這組關(guān)鍵詞。它不是什么高深算法而是中國移動短信網(wǎng)關(guān) CMPP3.0 協(xié)議的接入落地用 Java 寫一個能收發(fā)短信、能收狀態(tài)報告、能扛住一定并發(fā)的客戶端模塊。網(wǎng)上資料零散協(xié)議文檔又是十六進制黑話導(dǎo)致很多人卡在登錄報文和滑動窗口上連上就斷、發(fā)了沒響應(yīng)。這篇文章我按自己的落地路徑講清楚協(xié)議怎么拆、代碼怎么組織、哪些參數(shù)不能亂調(diào)最后把最容易翻車的坑挨個點出來。適合正在接短信通道、或者被派去維護老短信系統(tǒng)的讀者新手能照著寫熟手可以拿避坑清單當(dāng)檢查項。2. CMPP3.0 協(xié)議先立住四種消息、無符號整數(shù)和滑動窗口2.1 四種消息類型和 Java 里的命令字CMPP3.0 的通信不是 HTTP是一條 TCP 長連接上的二進制消息流。雖然文檔里有十幾種消息但 Java 實現(xiàn)里真正高頻的只有四組Connect登錄鑒權(quán)、Submit下發(fā)短信、Deliver上行短信和狀態(tài)報告、ActiveTest心跳。真正斷開連接用的 Terminate 在客戶端主動退出時才會用到。先把命令字整理成表后面寫解碼器會反復(fù)用到消息作用Command_Id建議常量名登錄請求0x00000001CMPP_CONNECT登錄響應(yīng)0x80000001CMPP_CONNECT_RESP下發(fā)短信請求0x00000002CMPP_SUBMIT下發(fā)短信響應(yīng)0x80000002CMPP_SUBMIT_RESP上行/狀態(tài)報告請求0x00000003CMPP_DELIVER上行/狀態(tài)報告響應(yīng)0x80000003CMPP_DELIVER_RESP心跳請求0x00000004CMPP_ACTIVE_TEST心跳響應(yīng)0x80000004CMPP_ACTIVE_TEST_RESP注意 Command_Id 的規(guī)律請求的最高位是 0響應(yīng)最高位是 1。這個規(guī)律在調(diào)試時很有用看到 0x8 開頭就知道是網(wǎng)關(guān)回包。但在 Java 里有個小坑0x80000001 超過了 int 的正數(shù)范圍讀出來可能是負數(shù)。我一般用 long 或者 Integer.compareUnsigned 來做比較避免“這個數(shù)怎么是負的”這種問題。2.2 消息頭、字節(jié)序和 Sequence_IdCMPP3.0 每條消息開頭固定 12 字節(jié)的消息頭三個 int 字段全部是大端序Total_Length、Command_Id、Sequence_Id。Total_Length 是整個消息的長度包含這 12 字節(jié)本身Sequence_Id 是流水號從 0 開始累加用來匹配請求和響應(yīng)。協(xié)議里幾乎全是無符號整數(shù)Java 的 int 也是 32 位但最高位是符號位。好消息是用 Netty 的 ByteBuf 寫入時 writeInt 只是按位寫Java 正負數(shù)不影響網(wǎng)絡(luò)字節(jié)序壞消息是從 ByteBuf 讀的時候要用 readUnsignedInt 才能拿到正確的 0-4294967295 范圍值。我習(xí)慣把消息頭獨立封裝出來避免每個消息體都重復(fù)處理粘包和半包。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(); } }這段代碼里的關(guān)鍵點是 sequenceId 讀取。協(xié)議里 Sequence_Id 是無符號如果直接 readInt 會讀到負數(shù)后續(xù)用這個值做 key 匹配響應(yīng)時容易出問題。網(wǎng)絡(luò)字節(jié)序方面ByteBuf 默認就是大端和 CMPP 協(xié)議一致不需要額外調(diào) ByteOrder。參數(shù)上sequenceId 用 AtomicInteger 生成就夠了。注意它最大到 0xFFFFFFFF到達上限后要歸零。如果用了 readUnsignedInt就不會因為符號問題導(dǎo)致回繞判斷錯誤。這里再說一句別用 synchronized 保護一個 int 自增AtomicInteger 足夠網(wǎng)關(guān)接口是長連接請求量上來后鎖競爭會拖慢整個發(fā)送鏈路。2.3 滑動窗口并發(fā)發(fā)送前的第一個控制參數(shù)CMPP3.0 的滑動窗口機制簡單說就是同一時刻最多能有多少條 Submit 消息沒收到 Submit_Resp。窗口大小規(guī)范默認是 16具體值由網(wǎng)關(guān)側(cè)配置決定客戶端必須遵守。如果客戶端無限往里灌網(wǎng)關(guān)會直接斷開連接而且不會告訴你原因。Java 里實現(xiàn)窗口最干凈的方式是信號量。每條 Submit 發(fā)送前 acquire收到 Submit_Resp 后 release。這樣發(fā)送線程會被自然阻塞而不是把消息堆進無界隊列后內(nèi)存爆掉。private final Semaphore window new Semaphore(16); public void acquireWindow() throws InterruptedException { if (!window.tryAcquire(3, TimeUnit.SECONDS)) { throw new IllegalStateException(滑動窗口已滿網(wǎng)關(guān)響應(yīng)過慢); } } public void releaseWindow() { window.release(); }窗口大小為什么是 16 而不是 100這是協(xié)議設(shè)計好的背壓閾值超過閾值網(wǎng)關(guān)會認為客戶端失控。我用 tryAcquire 而不是 acquire是為了在窗口長期占滿時讓發(fā)送線程快速失敗而不是無限阻塞否則故障時線程池會被卡滿。3 秒超時是個經(jīng)驗值真實網(wǎng)關(guān)一般幾十毫秒到幾百毫秒就回 Submit_Resp如果 3 秒都沒窗口說明響應(yīng)鏈路已經(jīng)不正常應(yīng)該告警而不是繼續(xù)等。2.4 用 Java 對象建模協(xié)議字段定長字符串的坑CMPP3.0 的消息體里大量使用定長字符串比如 Source_Addr 固定 6 字節(jié)Service_Id 固定 10 字節(jié)。協(xié)議規(guī)定不足部分按位補 0不是補空格。很多人把 String 直接 getBytes 塞進去結(jié)果長度不夠多出來的隨機數(shù)據(jù)導(dǎo)致網(wǎng)關(guān)解析錯亂。我一般先封裝一個定長編碼方法統(tǒng)一處理這種情況public static byte[] fixedString(String value, int length, Charset charset) { byte[] raw value.getBytes(charset); if (raw.length length) { throw new IllegalArgumentException(字段超長當(dāng)前值 value); } byte[] out new byte[length]; System.arraycopy(raw, 0, out, 0, raw.length); return out; }補充說明定長字段在 CMPP 文檔里通常標注“字符串”但具體是 ASCII 還是 GBK要看字段類型。比如 Source_Addr 和 Msg_Src 是數(shù)字組成的企業(yè)代碼用 ASCII 就可以Service_Id 可能是字母加數(shù)字也建議 ASCII。Msg_Content 的業(yè)務(wù)內(nèi)容才根據(jù) Msg_Fmt 用 UCS2 或 GBK。用 charset 參數(shù)顯式傳入能避免將來換服務(wù)器后平臺默認編碼變了導(dǎo)致亂碼。這個細節(jié)就是 CMPP3.0_Java 實現(xiàn)里最常見的“看著代碼沒問題一上線就出事”的源頭。3. 從零搭一個 CMPP3.0 Java 客戶端五個可復(fù)現(xiàn)的步驟3.1 選型Netty 還是原生 SocketCMPP3.0 是二進制協(xié)議必然涉及粘包、半包、字節(jié)序轉(zhuǎn)換。原生 Socket 也能做但所有協(xié)議解析都要自己寫還要自己管理線程池。Netty 的優(yōu)勢在于 ByteBuf、ChannelPipeline 和內(nèi)置的定時任務(wù)能讓代碼結(jié)構(gòu)干凈很多。Mina 也見過人用但近年新項目選 Netty 更多社區(qū)資料也全。選型對比可以按這個參考方案協(xié)議解析線程模型維護成本原生 Socket自己處理容易漏字節(jié)每連接一線程擴展麻煩低依賴但出問題全得自己扛Mina自帶解碼器有 IoHandler 模型老項目多新資料少NettyByteBuf 解碼器EventLoop 異步模型需要一點學(xué)習(xí)曲線我選 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 必須設(shè)為 true否則小字節(jié)的 CMPP 包會被 Nagle 算法合并導(dǎo)致網(wǎng)關(guān)側(cè)響應(yīng)延遲明顯變大。SO_KEEPALIVE 只是內(nèi)核級?；畈荒芴娲鷺I(yè)務(wù)心跳這個后面會專門說。CMPPDecoder 要做的事就是讀前 4 字節(jié)的 Total_Length再按長度讀完整包解決粘包半包。NioEventLoopGroup 線程數(shù)我用 2一個負責(zé) IO一個留給協(xié)議處理實際連接數(shù)和消息量上來后再調(diào)。3.2 登錄鑒權(quán)CMPP_CONNECT 的 Java 實現(xiàn)登錄是第一個坑點。CMPP_CONNECT 消息體包含 Source_Addr、AuthenticatorSource、Version、Timestamp 四個字段。其中 AuthenticatorSource 是 MD5 結(jié)果16 字節(jié)算法是MD5(Source_Addr 9字節(jié)0 sharedSecret Timestamp)。這里 9 字節(jié) 0 很容易漏掉漏了網(wǎng)關(guān)回你 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”結(jié)果有人直接寫 3網(wǎng)關(guān)也能連上但某些網(wǎng)關(guān)上功能受限我遇到過。3.3 心跳與重連CMPP_ACTIVE_TEST 和指數(shù)退避CMPP 網(wǎng)關(guān)一般要求 30 秒內(nèi)至少有一次業(yè)務(wù)報文或心跳否則會斷開連接。我習(xí)慣用一個 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); }收到心跳響應(yīng)用一個 AtomicInteger 記錄最近一次響應(yīng)時間如果連續(xù) 3 次心跳沒響應(yīng)就判定連接已死主動關(guān)閉并觸發(fā)重連。重連不要寫死循環(huán)用指數(shù)退避第一次等待 1 秒第二次 2 秒最多 30 秒避免網(wǎng)關(guān)恢復(fù)期間客戶端高頻重連把網(wǎng)關(guān)打崩。另外心跳線程一定要獨立不能和業(yè)務(wù)線程共用如果業(yè)務(wù)線程被滑動窗口阻塞心跳還能繼續(xù)發(fā)這個隔離能救很多次。3.4 發(fā)送 CMPP_SUBMIT組裝報文和控制窗口Submit 是項目里流量最大的部分。消息體字段多但關(guān)鍵的就幾個Msg_Id8 字節(jié)本地填 0響應(yīng)里回填、Pk_total、Pk_number、Registered_Delivery、Msg_Fmt、Msg_Src、Src_Id、Msg_Length、Msg_Content。Registered_Delivery 設(shè)為 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è)務(wù)更新放在另一個異步線程池避免阻塞 Netty 的 EventLoop。如果在這個 Handler 里直接操作數(shù)據(jù)庫網(wǎng)關(guān)并發(fā)一高EventLoop 卡住心跳就發(fā)不出去緊接著就是連接斷開這是很多壓測翻車的直接原因。3.5 Spring Boot 里的配置組織項目里我不會把協(xié)議代碼和業(yè)務(wù)配置混在一起。用 Spring Boot 的話連接參數(shù)、窗口大小、心跳間隔全放 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 綁定。服務(wù)啟動時創(chuàng)建 CMPPClient用 SmartLifecycle 控制啟動順序應(yīng)用關(guān)閉時先發(fā) Terminate 再釋放連接。這里要提醒一句連接建立不等于登錄成功登錄成功報文是 CONNECT_RESP這里的 Status 字段 0 才表示認證通過。我見過有的項目只檢測了 TCP 是否連接就對外報通道可用結(jié)果狀態(tài)監(jiān)控一片綠短信一條都發(fā)不出去。4. 消息路由與長短信拆分Java 實現(xiàn)里的高頻業(yè)務(wù)點4.1 區(qū)分 Deliver 上行和狀態(tài)報告Is_Report 字段說了算網(wǎng)關(guān)推送的 CMPP_DELIVER 有兩類用戶上行短信和狀態(tài)報告。區(qū)分方式很簡單看消息體里的 Is_Report 字段。Is_Report0 是用戶上行需要往業(yè)務(wù)系統(tǒng)轉(zhuǎn)Is_Report1 是狀態(tài)報告要解析里面的 Stat 字段更新短信發(fā)送狀態(tài)。狀態(tài)報告的 Msg_Content 是一段格式化文本常見是空行分隔的字段比如stat:DELIVRD done_time:20250615143005 sub_time:20250615142930解析代碼不要寫復(fù)雜正則按行 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)報告的消息體編碼不一定和上行短信一樣有的網(wǎng)關(guān)用 GBK。Java 里不要默認 new String(msgContent)顯式指定編碼否則 Linux 部署后中文編譯環(huán)境一變解析出來就亂。4.2 長短信拆分67 字一條不是 70 字中文短信一條最多 70 個漢字但這指的是不帶 UDHI 頭的普通短信。CMPP3.0 長短信需要在消息體前面加 6 字節(jié)的 UDHI 頭用來標識分片信息所以真正留給短信內(nèi)容的只有 67 個漢字。拆分時如果按 70 切分片會超長網(wǎng)關(guān)要么拒絕要么用戶收到亂碼。一個可用的拆分方法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 數(shù)切不是按字節(jié)切。UCS2 下每個漢字是一個 char每個 char 兩個字節(jié)67 個 char 正好 134 字節(jié)加 6 字節(jié) UDHI 頭是 140 字節(jié)。buildUdhiHeader 里 0x05 表示后面有 5 個長度字節(jié)0x00 0x03 是 TP_UDHI 的拆分標識0x0A 是參考號后兩字節(jié)分別是總條數(shù)和當(dāng)前條數(shù)。參考號可以固定也可以每條消息用隨機數(shù)但總分片數(shù)不能超過 255因為這是 1 字節(jié)字段。這條邏輯里有個隱藏邊界如果內(nèi)容里包含 emojiJava 的 String.length 會把一個 emoji 記成兩個 char按這個思路拆某些分片可能把代理對切半。遇到這種內(nèi)容建議升級到按 CodePoint 切分或者直接限制用戶輸入短信場景里 emoji 本來就容易亂碼。4.3 去重、存儲和異常恢復(fù)數(shù)據(jù)庫唯一索引是最后的兜底CMPP 消息在網(wǎng)絡(luò)傳輸中可能重發(fā)。Deliver 上行、狀態(tài)報告如果重復(fù)處理會給業(yè)務(wù)方造成重復(fù)訂單或者錯誤狀態(tài)。常見的做法是在數(shù)據(jù)庫表里給網(wǎng)關(guān)消息 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ā)下后一種才能真正防重。數(shù)據(jù)庫層面的唯一約束是最靠譜的兜底應(yīng)用層用 ConcurrentHashMap 做去重只能擋住單機 JVM 內(nèi)的重復(fù)。發(fā)送側(cè)的異常恢復(fù)更講究。Submit 發(fā)出去了但沒收到 Submit_Resp這時不能一概重發(fā)。因為消息可能已經(jīng)到達網(wǎng)關(guān)重發(fā)會重復(fù)下發(fā)。我會在發(fā)送前給每條消息生成一個業(yè)務(wù)批次號把 Submit_Resp、Deliver 狀態(tài)報告都關(guān)聯(lián)到同一條發(fā)送記錄重發(fā)前先查這條記錄有沒有任何回執(zhí)有就不發(fā)。這樣處理重啟應(yīng)用后也不會造成大面積重復(fù)短信。5. CMPP3.0_JAVA_實現(xiàn)避坑指南5 個讓我翻車過的黑匣子CMPP3.0 的 Java 實現(xiàn)里最折磨人的往往不是代碼本身而是問題現(xiàn)象看起來像網(wǎng)絡(luò)玄學(xué)實際上都是協(xié)議細節(jié)。下面五條都是我在真實聯(lián)調(diào)里踩過的每一條都按現(xiàn)象、原因、解決的順序說。5.1 登錄后立刻被斷開先抓報文別猜現(xiàn)象TCP 連接已經(jīng)建立也發(fā)送了 CMPP_CONNECT甚至收到了 CONNECT_RESPStatus 為 0但緊接著幾秒內(nèi)連接被網(wǎng)關(guān)斷開。日志里沒有任何異常只有連接關(guān)閉。原因AuthenticatorSource 的 MD5 計算錯了。最常見的是漏掉 9 字節(jié)的 0 填充或者 Timestamp 格式寫成了 Unix 時間戳。網(wǎng)關(guān)認證通過但后續(xù)第一個 Submit 報文格式不對也可能被立刻斷開。解決先把收發(fā)的字節(jié)流打印出來用十六進制對比協(xié)議文檔。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é)。如果和樣例報文不一致就別懷疑網(wǎng)關(guān)先修本地代碼。5.2 Submit 返回 Status0用戶卻收不到短信現(xiàn)象CMPP_SUBMIT_RESP 里 Status 是 0業(yè)務(wù)日志顯示發(fā)送成功但手機遲遲收不到短信狀態(tài)報告也始終不來。原因賬號配置和網(wǎng)關(guān)側(cè)分配不一致。常見的有 Source_Addr 的 SP 企業(yè)代碼填錯Msg_Src 和 Source_Addr 混用Src_Id 設(shè)置了不存在的擴展短號。網(wǎng)關(guān)只校驗來源認證不校驗這些業(yè)務(wù)字段所以認證能過但消息被內(nèi)部路由丟棄。解決拿網(wǎng)關(guān)分配的開戶資料逐項核對。Source_Addr 是 6 位企業(yè)代碼Msg_Src 是 SP_CodeSrc_Id 是顯示主叫號碼通常是服務(wù)代碼或者擴展短號。先用最簡消息測一條純 ASCII 文本附帶 Registered_Delivery1確認狀態(tài)報告能回來再換成真實業(yè)務(wù)內(nèi)容。不要直接灰度大批量發(fā)送否則收不到你得從成千上萬條記錄里排查。5.3 并發(fā)一上來就頻繁重連EventLoop 被業(yè)務(wù)代碼卡死了現(xiàn)象單條消息測試正常壓測到幾十條并發(fā)時開始出現(xiàn) ACTIVE_TEST_RESP 超時然后連接斷開客戶端自動重連重連后又斷。原因Netty 的 EventLoop 線程被阻塞了。最常見的是在 ChannelHandler 里直接同步查數(shù)據(jù)庫、調(diào)用外部接口或者發(fā)送窗口沒有控制消息隊列積壓導(dǎo)致響應(yīng)處理延遲。心跳也走同一個 EventLoop心跳響應(yīng)沒人處理網(wǎng)關(guān)就判定超時斷開。解決把 IO 線程和業(yè)務(wù)線程嚴格分開。Netty 的 Handler 只做協(xié)議編解碼和窗口釋放業(yè)務(wù)處理丟給獨立線程池。窗口控制用前面寫的 Semaphore發(fā)送前 tryAcquire拿不到就快速失敗絕不無界堆積。另外檢查是否在 EventLoop 里調(diào)用了 channel.writeAndFlush 的大包同步等待應(yīng)該用監(jiān)聽器異步回調(diào)。5.4 內(nèi)存溢出從幾百 MB 漲到幾個 G無界隊列是元兇現(xiàn)象Java 進程啟動時內(nèi)存正常運行一段時間后堆內(nèi)存持續(xù)上漲最終拋出 OutOfMemoryError應(yīng)用重啟后重復(fù)出現(xiàn)。原因發(fā)送線程和網(wǎng)關(guān)響應(yīng)速度不匹配。網(wǎng)關(guān)響應(yīng)慢提交到線程池的任務(wù)越來越多如果用的 LinkedBlockingQueue 沒設(shè)容量任務(wù)全部積壓在堆里。CMPP 消息內(nèi)容一多內(nèi)存直接被打滿。解決有界隊列加拒絕策略。不要用 Executors.newFixedThreadPool 里默認的無界隊列改成BlockingQueueRunnable queue new ArrayBlockingQueue(10000); ThreadPoolExecutor pool new ThreadPoolExecutor( 8, 16, 60, TimeUnit.SECONDS, queue, new ThreadPoolExecutor.CallerRunsPolicy());CallerRunsPolicy 讓提交線程自己執(zhí)行任務(wù)形成天然背壓比 AbortPolicy 更友好。JVM 啟動參數(shù)按機器內(nèi)存來不要跟風(fēng)配大我一般用 -Xms512m -Xmx1024m堆太大反而讓問題暴露得晚。5.5 Linux 上中文亂碼顯式指定字符集別吃平臺默認值現(xiàn)象本地 Windows 開發(fā)測試正常部署到 Linux 后發(fā)送的中文短信到手機變問號或者收到的狀態(tài)報告解析亂碼。原因CMPP3.0 的消息內(nèi)容是編碼字節(jié)不攜帶字符集聲明。Java 代碼里用了 String.getBytes() 無參版本W(wǎng)indows 默認 GBKLinux 默認 UTF-8兩邊編碼不一致字節(jié)流自然不對。網(wǎng)關(guān)按協(xié)議里 Msg_Fmt 指定的編碼解析時數(shù)據(jù)已經(jīng)錯了。解決Java 代碼里所有 CMPP 編解碼都顯式寫字符集參數(shù)。中文短信 Msg_Fmt8 時用 UTF-16BE狀態(tài)報告解析如果需要 GBK 就傳 GBK不要依賴默認環(huán)境。編譯時也固定編碼mvn clean package -Dfile.encodingUTF-8同時檢查 Spring Boot 的 server.servlet.encoding 配置雖然它影響不到這些字節(jié)流但統(tǒng)一 UTF-8 能減少其他環(huán)節(jié)的干擾。這個問題是血淚經(jīng)驗曾經(jīng)線上亂碼查了兩天最后就是一行 getBytes() 少了 charset 參數(shù)。6. 進階給 CMPP3.0 Java 客戶端加一個 Mock 網(wǎng)關(guān)做回歸驗證6.1 用 Netty 寫一個最小 Mock 網(wǎng)關(guān)真實網(wǎng)關(guān)不是隨便就能連的聯(lián)調(diào)要等工單、要排期出了問題兩邊還容易扯皮。我的習(xí)慣是在項目里保留一個 Mock 網(wǎng)關(guān)用來做自動化回歸測試。它能做的就是收到 CONNECT 回 CONNECT_RESP收到 SUBMIT 回 SUBMIT_RESP收到 ACTIVE_TEST 回 ACTIVE_TEST_RESP。這樣客戶端代碼改完跑一遍用例就可以確認協(xié)議層沒壞。一個最小 Mock 網(wǎng)關(guān)的核心邏輯可以這樣寫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 網(wǎng)關(guān)里不需要完整解析每個字段只需要讀 Command_Id 和 Sequence_Id然后按相同 Sequence_Id 回包。CMPP 客戶端一般用自己的流水號匹配響應(yīng)所以 Mock 網(wǎng)關(guān)回包時把請求里的 Sequence_Id 原樣帶回去即可。這段代碼的邊界在于它不會校驗 AuthenticatorSource所以只適合做客戶端回歸測試不適合做協(xié)議正確性驗證。6.2 壓測參數(shù)建議用 Mock 網(wǎng)關(guān)做壓測時參數(shù)別隨便拍腦袋。最基礎(chǔ)的一組建議參數(shù)建議值說明發(fā)送線程數(shù)8不要超過窗口大小的 2 倍滑動窗口大小16與真實網(wǎng)關(guān)配置保持一致Submit 超時5 秒超過則記錄失敗壓測時長10 分鐘觀察內(nèi)存和連接穩(wěn)定性心跳間隔30 秒模擬真實節(jié)奏壓測時重點看兩個指標成功發(fā)送的 TPS 和未響應(yīng)消息積壓數(shù)。如果 TPS 上不去但窗口一直為空說明發(fā)送線程被網(wǎng)關(guān)響應(yīng)延遲拖著先查 Mock 網(wǎng)關(guān)的日志如果窗口一直滿說明消費速度不夠調(diào)大線程池之前先確認數(shù)據(jù)庫寫入有沒有瓶頸。真實網(wǎng)關(guān)的響應(yīng)時間和 Mock 網(wǎng)關(guān)差別很大正式上線前還是要用真實網(wǎng)關(guān)小流量跑一遍。我前兩年接一個新網(wǎng)關(guān)上來就急著聯(lián)調(diào)結(jié)果連不上折騰兩天發(fā)現(xiàn)是 MD5 里少補了 9 個字節(jié)。那次之后我養(yǎng)成了一個習(xí)慣每個 CMPP 客戶端項目都必須保留 Mock 網(wǎng)關(guān)協(xié)議層改動先跑回歸再上真實環(huán)境驗證。短信通道這東西不提前準備好后悔藥出事時連定位的抓手都沒有。希望幫到你。本文還有配套的精品資源點擊獲取