1. 短信接口是整個系統(tǒng)里最不像技術(shù)問題的技術(shù)問題做 Java 后端的人遲早會碰上一件事產(chǎn)品經(jīng)理在需求評審上說就加一個驗證碼很簡單。然后你打開 SDK 文檔看著SendSmsRequest這個類心里想的是這不就三行代碼嗎。真正把 Java 版本的短信服務(wù) SDK 接進(jìn)去、上線跑上幾個月以后你會發(fā)現(xiàn)這條鏈路的代碼量確實很小但它牽扯的東西比很多核心業(yè)務(wù)模塊都多——涉及外部網(wǎng)絡(luò)、涉及錢、涉及用戶體驗而且出問題的時候往往是在半夜。這篇東西不打算復(fù)述官方文檔而是把我在多個項目里接 Java 短信 SDK 的完整路徑攤開從依賴引入、客戶端初始化、發(fā)送封裝到錯誤碼分層、冪等設(shè)計、限流降級和監(jiān)控埋點把每一步為什么這么做講清楚。先說清楚范圍。這里討論的短信服務(wù) SDK 的 Java 版本指的是主流云服務(wù)商提供的那套 HTTP 客戶端封裝庫核心能力就三件事調(diào)用發(fā)送接口、解析返回結(jié)構(gòu)、附帶簽名鑒權(quán)。它不是什么重量級中間件本質(zhì)是一個帶重試和序列化的 HTTP 客戶端。但正因為本質(zhì)簡單大多數(shù)人接的時候很隨意直接在主線程里new一個客戶端發(fā)送方法裸調(diào)返回值打印一下就完事。這種寫法在測試環(huán)境永遠(yuǎn)不會出問題因為測試環(huán)境不會觸發(fā)流控、不會出現(xiàn)簽名不匹配、不會因為一條長短信被拆成三條計費。我見過一個挺典型的場景某公司的登錄模塊在活動期間被刷驗證碼單機(jī) QPS 打滿短信接口開始返回觸發(fā)流控的錯誤碼業(yè)務(wù)代碼沒做任何判斷直接把異常吞掉用戶界面顯示驗證碼已發(fā)送實際上一條都沒發(fā)出去。排查的時候日志里全是同一句send failed沒有錯誤碼、沒有手機(jī)號脫敏后的追蹤 ID、沒有耗時統(tǒng)計只能靠猜。這個坑的根本原因不是短信 SDK 難用而是接入的時候把調(diào)用當(dāng)成了集成。調(diào)用只要求你寫出一行能跑通的代碼集成要求你考慮失敗、重復(fù)、延遲、成本和可觀測性。1.1 為什么這條鏈路總在非工作時間暴露問題短信是典型的強(qiáng)外部依賴它跨越了你和運營商之間的整條鏈路你的應(yīng)用 → SDK 的 HTTP 客戶端 → 云服務(wù)商網(wǎng)關(guān) → 運營商通道 → 用戶手機(jī)。任何一段抖動都會以發(fā)送失敗或延遲到達(dá)的形式反映到你的業(yè)務(wù)層。而這條鏈路的穩(wěn)定性特點是平時很穩(wěn)波動很突然白天工作時段運營商通道資源相對寬松夜間批量任務(wù)和營銷短信集中下發(fā)通道壓力大系統(tǒng)級錯誤出現(xiàn)的概率明顯上升。更麻煩的是很多團(tuán)隊把短信發(fā)送放在同步鏈路里。用戶點擊獲取驗證碼請求線程一直阻塞等待短信接口返回讀超時設(shè)成了默認(rèn)值。一旦上游網(wǎng)關(guān)慢下來你的 Tomcat 線程池會以肉眼可見的速度被占滿然后整個登錄接口跟著掛掉——短信發(fā)不出去是小事把整個應(yīng)用的線程資源拖死才是大事。我在一個項目里就吃過這個虧壓測的時候沒模擬短信接口超時上線后遇到一次網(wǎng)關(guān)抖動二十幾個線程卡在 read 上接口平均響應(yīng)從 80ms 漲到 3 秒。所以這篇文章的第一個觀點很明確接短信 SDK 的第一步不是寫發(fā)送代碼而是想清楚它在你的系統(tǒng)拓?fù)淅锾幱谑裁次恢?。它?yīng)該是可失敗、可降級、可異步、可觀測的邊緣依賴而不是一個同步阻塞的關(guān)鍵路徑節(jié)點。后面的所有章節(jié)無論是超時配置、異常映射還是限流降級都是圍繞這個定位展開的。1.2 三個反直覺的特性決定了代碼的寫法短信發(fā)送有三點和普通內(nèi)部 RPC 調(diào)用完全不同的特性理解了這三點很多設(shè)計選擇就變得順理成章。第一它是有成本的。每發(fā)一條都計費長短信按條拆分計費。這意味著你不能像調(diào)內(nèi)部服務(wù)那樣無腦重試一次網(wǎng)絡(luò)抖動觸發(fā)的盲目重試可能產(chǎn)生雙倍費用更糟糕的是用戶會收到兩條一模一樣的驗證碼體驗和風(fēng)控都會出問題。第二它是不可撤回的。數(shù)據(jù)庫寫錯了可以改消息發(fā)錯了可以補(bǔ)償短信發(fā)出去就收不回來了。所以發(fā)送之前的校驗必須做足手機(jī)號格式、模板參數(shù)合法性、頻率限制、內(nèi)容合規(guī)。所有這些校驗都應(yīng)該在調(diào)用 SDK 之前完成把無效請求擋在外面既能省錢又能減少無效調(diào)用。第三它的返回結(jié)果不等于送達(dá)結(jié)果。發(fā)送接口返回成功只代表云服務(wù)商網(wǎng)關(guān)受理了這個請求不代表用戶手機(jī)收到了。真正的送達(dá)狀態(tài)要靠回執(zhí)上行/下行報告異步推回來。如果你的業(yè)務(wù)邏輯強(qiáng)依賴用戶一定收到那就得把回執(zhí)鏈路也接上這是很多項目遺漏的部分。2. 動手之前先把四個模型概念對齊憑證、簽名、模板、回執(zhí)很多人接 SDK 卡住不是因為 Java 代碼寫不出來而是因為沒搞明白短信服務(wù)的四個核心概念之間的關(guān)系。這四個東西在控制臺里分散在不同菜單在 SDK 里又分別對應(yīng)不同的字段第一次接觸很容易混。概念控制臺里的位置SDK 字段是否必填常見誤解訪問憑證賬號安全/密鑰管理AccessKeyId / AccessKeySecret必填用主賬號密鑰圖省事簽名短信簽名管理SignName必填以為可以隨便填模板短信模板管理TemplateCode TemplateParam必填把整段內(nèi)容當(dāng)參數(shù)傳回執(zhí)消息回執(zhí)/事件訂閱回調(diào)地址可選以為返回 OK 就是送達(dá)2.1 憑證管理別用主賬號密鑰這是最容易埋雷的地方SDK 初始化需要一對密鑰通常叫 AccessKeyId 和 AccessKeySecret。我在不止一個項目里看到過有人直接拿主賬號密鑰寫進(jìn)配置文件然后提交到了代碼倉庫。這個習(xí)慣的風(fēng)險等級很高主賬號密鑰往往擁有全量權(quán)限一旦泄露損失的不只是短信費用。正確的做法是走子賬號RAM 用戶路線創(chuàng)建一個專用于短信服務(wù)的子賬號只授予短信發(fā)送相關(guān)的權(quán)限策略然后把這對密鑰注入到配置中心或環(huán)境變量里絕不進(jìn)代碼倉庫。密鑰的存放位置我一般按環(huán)境區(qū)分開發(fā)環(huán)境用配置中心的加密配置項測試和生產(chǎn)用 KMS 或配置中心的加密能力容器化部署的話直接用 Secret 掛載成環(huán)境變量。有一個細(xì)節(jié)容易被忽略密鑰輪換。密鑰不是設(shè)一次就永遠(yuǎn)不管的東西尤其是人員流動之后。我的做法是在配置里同時支持主密鑰和備用密鑰兩個字段SDK 客戶端初始化時優(yōu)先讀主密鑰發(fā)送返回鑒權(quán)類錯誤時自動切到備用密鑰并打告警。這樣輪換的時候可以先把新密鑰寫進(jìn)備用位觀察一段時間無異常后再把主密鑰替換掉實現(xiàn)無停機(jī)切換。2.2 簽名與模板上線前的兩道審批別等到發(fā)布前才想起簽名是你發(fā)給用戶的那條短信開頭的【某某系統(tǒng)】模板是預(yù)先審核過的內(nèi)容格式。這兩個東西都需要提前提交審核審核需要時間而且模板內(nèi)容有明確的規(guī)范限制。我遇到過最尷尬的情況是功能開發(fā)完了聯(lián)調(diào)也過了發(fā)布前一天才發(fā)現(xiàn)模板還沒審核通過硬生生拖了兩天。模板的變量用占位符表示發(fā)送時通過 TemplateParam 傳一個 JSON 字符串。這里有兩個高頻錯誤。第一個是把整個短信內(nèi)容塞進(jìn)參數(shù)里比如傳{content:您的驗證碼是123456}這會被直接拒絕因為模板是固定的變量只能填內(nèi)容片段。第二個是 JSON 轉(zhuǎn)義問題參數(shù)值里包含引號、反斜杠、中文特殊符號的時候手工拼 JSON 字符串極容易出錯一定要用 JSON 序列化庫生成不要用字符串拼接。提示驗證碼類模板的變量只放純數(shù)字不要放任何其他字符。營銷或通知類模板的變量內(nèi)容也要避免出現(xiàn)可能觸發(fā)內(nèi)容審核的詞否則會出現(xiàn)模板審核通過但發(fā)送時被攔截的情況。另外要提醒的是簽名的數(shù)量限制和命名規(guī)范。多數(shù)平臺對單個賬號下的簽名數(shù)量有上限簽名的名稱也有格式要求通常要求能體現(xiàn)業(yè)務(wù)歸屬。我的建議是按業(yè)務(wù)線劃分簽名而不是按項目劃分否則簽著簽著就超限了而且用戶手機(jī)上看到的簽名五花八門也不利于品牌統(tǒng)一。2.3 回執(zhí)發(fā)送成功和送達(dá)成功是兩回事發(fā)送接口返回的成功語義是請求已被受理。用戶手機(jī)有沒有收到取決于后續(xù)的通道投遞。回執(zhí)機(jī)制就是把這個投遞結(jié)果異步推回給你通常是通過配置一個回調(diào)地址云服務(wù)商在狀態(tài)變化時 POST 過來。回執(zhí)要不要接取決于業(yè)務(wù)對送達(dá)結(jié)果的敏感度。驗證碼場景一般不接用戶沒收到會自己點重發(fā)。但如果是重要的通知類短信比如訂單狀態(tài)變更、審批結(jié)果業(yè)務(wù)可能需要對未送達(dá)的號碼做二次觸達(dá)這時候回執(zhí)就必須接。接回執(zhí)有兩個工程上的注意點。第一回調(diào)接口必須做冪等同一條消息可能被推送多次。第二回調(diào)接口必須快速返回不要在回調(diào)里做耗時業(yè)務(wù)邏輯正確做法是把回調(diào)數(shù)據(jù)落庫或丟進(jìn)消息隊列異步處理。第三回調(diào)接口要能防偽造多數(shù)平臺提供了簽名校驗機(jī)制這個校驗一定要開否則任何人都能往你的回調(diào)地址灌假數(shù)據(jù)。3. 第一行代碼依賴引入與客戶端初始化概念對齊了開始寫代碼。這一節(jié)講的是從零跑通第一條短信的完整路徑包括依賴、配置、初始化和調(diào)用以及那些文檔里不太強(qiáng)調(diào)但實際很關(guān)鍵的參數(shù)。3.1 依賴引入與版本選擇的取舍Java SDK 通常以 Maven 依賴的形式提供坐標(biāo)以廠商官方文檔為準(zhǔn)。引入的時候有一個常見糾結(jié)用最新版還是用穩(wěn)定版。我的經(jīng)驗是跟隨官方推薦版本不要自己升到最新。短信 SDK 的版本迭代經(jīng)常涉及底層 HTTP 客戶端的替換比如從某個 HTTP 庫換到另一個大版本升級可能帶來傳遞依賴沖突尤其是在你已經(jīng)引入了多個網(wǎng)絡(luò)庫的項目里。!-- 坐標(biāo)以官方文檔為準(zhǔn)這里僅示意結(jié)構(gòu) -- dependency groupIdcom.example.sms/groupId artifactIdsms-sdk-java/artifactId versionx.y.z/version exclusions !-- 如果項目已統(tǒng)一使用某 HTTP 客戶端可以排除 SDK 自帶的以減小包體 -- exclusion groupIdcom.example.http/groupId artifactIdhttp-client/artifactId /exclusion /exclusions /dependency排除傳遞依賴這件事要慎重SDK 內(nèi)部如果直接調(diào)用了被排除庫的類運行時就會拋 NoClassDefFoundError。穩(wěn)妥的做法是先不排除用mvn dependency:tree看看有沒有版本沖突有沖突再針對性處理。我在一個老項目里就因為盲目排除了一個 JSON 庫導(dǎo)致 SDK 內(nèi)部序列化參數(shù)時報錯排查了半天才發(fā)現(xiàn)是依賴被剝掉了。3.2 客戶端初始化超時和連接池是重點客戶端對象應(yīng)該全局單例不要每次發(fā)送都 new 一個。SDK 內(nèi)部維護(hù)著 HTTP 連接池頻繁創(chuàng)建銷毀客戶端等于放棄了連接復(fù)用在高并發(fā)下會顯著增加延遲和文件句柄占用。正確的做法是用 Spring 的Bean或者靜態(tài)單例持有它。Configuration public class SmsClientConfig { Value(${sms.access-key-id}) private String accessKeyId; Value(${sms.access-key-secret}) private String accessKeySecret; Value(${sms.endpoint}) private String endpoint; Bean(destroyMethod shutdown) public SmsClient smsClient() { ClientConfig config new ClientConfig() .setAccessKeyId(accessKeyId) .setAccessKeySecret(accessKeySecret) .setEndpoint(endpoint) // 連接超時建連階段建議 2-3 秒 .setConnectTimeoutMillis(3000) // 讀超時等響應(yīng)的階段建議 5 秒左右 .setReadTimeoutMillis(5000) // 連接池上限按你的并發(fā)量估 .setMaxIdleConnections(50) .setMaxConnections(200) // 開啟自動重試要謹(jǐn)慎見下一節(jié) .setAutoRetry(false); return new SmsClient(config); } }這幾個參數(shù)值得展開說。連接超時設(shè)短一點因為建連失敗通常是網(wǎng)絡(luò)層面的問題等再久也沒用快速失敗對業(yè)務(wù)更友好。讀超時設(shè)長一點但也不能太長5 秒是個比較平衡的值——太短會誤殺正常但稍慢的請求太長會把調(diào)用線程拖住。連接池上限要根據(jù)你的實際并發(fā)估算假設(shè)峰值每秒 200 條每條平均耗時 200ms那么并發(fā)連接數(shù)大約是 200 × 0.2 40留兩倍余量設(shè)成 80 到 100 比較合適。setAutoRetry(false)這一項是我踩過坑之后的固定選擇。SDK 自帶的自動重試通常是針對網(wǎng)絡(luò)異常配置的但短信是外部副作用操作重試意味著可能重復(fù)發(fā)送。寧可自己在業(yè)務(wù)層做可控的重試也不要讓 SDK 在背后悄悄重試。后面第 5 章會講重試的正確邊界。3.3 跑通第一條短信與返回結(jié)構(gòu)的解讀public SendResult send(String phone, String templateCode, String paramJson, String bizId) { SendSmsRequest request new SendSmsRequest() .setPhoneNumbers(phone) .setSignName(signName) .setTemplateCode(templateCode) .setTemplateParam(paramJson) // 業(yè)務(wù)流水號用于對賬和追蹤強(qiáng)烈建議傳 .setOutId(bizId); SendSmsResponse response smsClient.sendSms(request); return SendResult.builder() .requestId(response.getRequestId()) .bizId(response.getBizId()) .code(response.getCode()) .message(response.getMessage()) .build(); }返回結(jié)構(gòu)里有四個字段值得關(guān)注。Code是業(yè)務(wù)狀態(tài)碼OK代表受理成功其余都是失敗具體錯誤碼見第 5 章。Message是描述信息給人看的不要用它做程序判斷。RequestId是本次請求的唯一標(biāo)識出問題找云服務(wù)商排查時必須提供這個。BizId是這條短信在服務(wù)端的回執(zhí) ID接了回執(zhí)鏈路的話回執(zhí)推送里會帶上這個 ID用它來關(guān)聯(lián)發(fā)送記錄和送達(dá)結(jié)果。提示日志里一定要打 RequestId 和 BizId但手機(jī)號必須脫敏。常見做法是保留前三后四中間用星號替代或者干脆只打手機(jī)號的哈希值。手機(jī)號屬于敏感信息明文落盤在合規(guī)上是有問題的。4. 把裸調(diào)用封裝成可維護(hù)的發(fā)送服務(wù)直接調(diào) SDK 的代碼寫起來最快但三個月后維護(hù)起來最痛苦。我見過的所有短信相關(guān)的事故復(fù)盤里幾乎都有一條共性發(fā)送邏輯散落在各個業(yè)務(wù)模塊每個地方對返回碼的處理方式都不一樣有的判斷了有的沒判斷有的判斷了但把錯誤吞掉了。所以第二步是把發(fā)送能力收攏成一個服務(wù)層。4.1 校驗前置把無效請求擋在調(diào)用之前調(diào)用 SDK 之前應(yīng)該做一輪完整的本地校驗包括手機(jī)號格式、模板參數(shù)、頻率限制、黑名單。這些校驗的意義不只是防止報錯更重要的是省錢——每一次無效調(diào)用都是白花花的費用。手機(jī)號校驗我一般分兩層。第一層是格式層用正則判斷位數(shù)和號段這個成本極低。第二層是歸一化去掉空格、橫線、加號前綴、國家碼前綴統(tǒng)一成純數(shù)字格式。我遇到過用戶從通訊錄復(fù)制號碼帶上了不可見字符導(dǎo)致發(fā)送失敗日志里看起來號碼一模一樣實際上是編碼不同。歸一化的時候順手把這類字符過濾掉。private static final Pattern CN_MOBILE Pattern.compile(^1[3-9]\\d{9}$); private String normalize(String raw) { if (raw null) return null; String s raw.replaceAll([\\s\\-()], ) .replaceAll(\\u00A0, ) // 不換行空格 .replaceAll(\\uFEFF, ); // BOM if (s.startsWith(86) s.length() 13) { s s.substring(2); } return CN_MOBILE.matcher(s).matches() ? s : null; }模板參數(shù)的校驗同樣重要。驗證碼類的參數(shù)必須是純數(shù)字長度和模板里定義的位數(shù)一致通知類的參數(shù)要檢查長度因為參數(shù)過長會導(dǎo)致短信被拆成多條長短信費用翻倍用戶體驗也差。我一般會在服務(wù)層設(shè)一個參數(shù)總長度的硬上限超過直接拒絕并打日志這樣可以及時發(fā)現(xiàn)調(diào)用方傳了異常內(nèi)容。4.2 異常映射把三種失敗區(qū)分開SDK 調(diào)用可能產(chǎn)生三類失敗這三類的處理方式完全不同混在一起處理是很多 bug 的根源。第一類是業(yè)務(wù)校驗失敗比如手機(jī)號非法、模板不存在、簽名不匹配、余額不足。這類失敗重試也沒用必須把明確的錯誤原因反饋給調(diào)用方讓它去修正參數(shù)或提示用戶。第二類是觸發(fā)流控也就是短時間內(nèi)發(fā)送頻率超限。這類失敗是有可能自愈的等一會兒再發(fā)可能就成功了但絕不能立刻重試立刻重試只會讓情況更糟。第三類是系統(tǒng)級失敗包括網(wǎng)絡(luò)超時、服務(wù)端 5xx、網(wǎng)關(guān)異常。這類失敗是唯一值得重試的類別但必須有次數(shù)上限和退避策略。public enum SmsErrorType { BIZ_ERROR, // 參數(shù)/配置問題不重試 RATE_LIMITED, // 流控延遲后再試 SYSTEM_ERROR, // 網(wǎng)絡(luò)/服務(wù)端問題可有限重試 UNKNOWN } public SmsErrorType classify(String code) { if (code null) return SmsErrorType.UNKNOWN; if (OK.equalsIgnoreCase(code)) return SmsErrorType.UNKNOWN; if (code.startsWith(isv.)) { // 業(yè)務(wù)側(cè)錯誤多數(shù)不可重試 return code.toLowerCase().contains(limit) ? SmsErrorType.RATE_LIMITED : SmsErrorType.BIZ_ERROR; } if (code.startsWith(isp.)) { return SmsErrorType.SYSTEM_ERROR; } return SmsErrorType.UNKNOWN; }把錯誤分類邏輯獨立出來好處是后續(xù)所有調(diào)用方都復(fù)用同一套判斷不會出現(xiàn)有的地方重試有的地方不重試。這個分類方法建議配單元測試把每個錯誤碼對應(yīng)的分類固定下來將來錯誤碼有新增時至少能保證已有邏輯不被改壞。4.3 發(fā)送結(jié)果對象給上層一個穩(wěn)定的契約不要讓業(yè)務(wù)層直接接觸 SDK 的 Response 對象。這有兩層原因一是 SDK 對象字段多、含義雜業(yè)務(wù)層用不上二是將來換服務(wù)商的時候如果業(yè)務(wù)層到處引用了 SDK 類型遷移成本會非常高。我通常定義這樣一個結(jié)果對象public class SendResult { private boolean success; // 是否成功受理 private String requestId; // 請求追蹤 ID private String bizId; // 回執(zhí)關(guān)聯(lián) ID private SmsErrorType errorType; // 錯誤分類 private String errorCode; // 原始錯誤碼 private String errorMessage; // 原始錯誤描述 private long costMillis; // 本次調(diào)用耗時 }這個對象里我特意加了耗時字段。短信接口的響應(yīng)時間分布很有參考價值正常情況下 P99 應(yīng)該在幾百毫秒內(nèi)如果某段時間整體拉長了往往意味著上游網(wǎng)關(guān)在承壓是個早期預(yù)警信號。把耗時打進(jìn)日志配合日志平臺做聚合比事后追查要省事得多。5. 錯誤碼逐個拆從返回字符串到可執(zhí)行動作錯誤碼是短信集成里信息密度最高的部分。文檔里通常給了一張大表但實際做的時候真正重要的不是背下來而是知道每個錯誤碼背后應(yīng)該采取什么動作。這一節(jié)按我實際遇到的頻率排個序。5.1 高頻錯誤碼與處置動作對照錯誤碼示意含義觸發(fā)原因處置動作OK受理成功正常記錄 bizId等待回執(zhí)isv.MOBILE_NUMBER_ILLEGAL號碼非法格式錯誤、空號段不重試提示用戶檢查isv.SMS_TEMPLATE_ILLEGAL模板不合法模板 ID 錯、未審核、已下線不重試告警檢查配置isv.SMS_SIGNATURE_ILLEGAL簽名不合法簽名未審核或拼寫不一致不重試告警isv.BUSINESS_LIMIT_CONTROL觸發(fā)流控單號碼或全局頻率超限延遲重試檢查限流配置isv.AMOUNT_NOT_ENOUGH余額不足賬戶欠費不重試立即告警到人isp.SYSTEM_ERROR服務(wù)端異常上游系統(tǒng)抖動有限次重試這張表里最值得說的是BUSINESS_LIMIT_CONTROL和AMOUNT_NOT_ENOUGH。流控錯誤的坑在于它有可能是單號碼級別的也可能是全局級別的返回的錯誤碼是同一個但處理方式完全不同。判斷方法很簡單如果同一時刻所有號碼都失敗那就是全局流控需要檢查自己的賬號配額和發(fā)送速率如果只有某一個號碼反復(fù)失敗那就是針對這個號碼的頻控。我的做法是在限流邏輯里對號碼維度單獨計數(shù)發(fā)送失敗時先查本地計數(shù)能快速定位是哪一類。余額不足這個錯誤是最容易造成靜默失敗的。因為它是業(yè)務(wù)錯誤很多代碼邏輯會把它歸到不重試的類別里然后打一行日志就結(jié)束了。結(jié)果就是賬戶欠費三天所有驗證碼都發(fā)不出去直到有用戶投訴才被發(fā)現(xiàn)。我的建議是余額不足、簽名非法、模板非法這三個錯誤碼必須觸發(fā)即時告警通過釘釘、企業(yè)微信或者郵件推到值班人而不是只寫日志。5.2 排查一條發(fā)送失敗的正確順序線上反饋收不到驗證碼的時候很多人的第一反應(yīng)是去翻應(yīng)用日志但更高效的做法是從外往里查。第一步看發(fā)送接口的返回碼。這是最快的一步直接決定問題在上游還是在下游。如果返回碼不是 OK按上表處置基本十分鐘內(nèi)能定位。如果返回 OK說明請求已經(jīng)被受理問題在投遞環(huán)節(jié)繼續(xù)下一步。第二步用 RequestId 或 BizId 去服務(wù)商控制臺查發(fā)送記錄。控制臺能看到這條短信的完整狀態(tài)流轉(zhuǎn)已提交、已發(fā)送、已送達(dá)、發(fā)送失敗。如果控制臺顯示發(fā)送成功但用戶說沒收到那問題在終端側(cè)可能是手機(jī)號輸錯了、手機(jī)裝了攔截軟件、或者用戶手機(jī)欠費停機(jī)。第三步如果控制臺顯示發(fā)送失敗且原因是空號或停機(jī)這就是業(yè)務(wù)數(shù)據(jù)問題需要在注冊或下單環(huán)節(jié)加強(qiáng)對號碼有效性的校驗。這個順序看起來簡單但實際排查的時候經(jīng)常被跳過。我見過有同事直接從檢查代碼邏輯開始查查了兩個小時最后發(fā)現(xiàn)是模板被下線了返回碼早就寫清楚了。5.3 重試的邊界到底在哪重試的設(shè)計有三條原則每一條都是踩坑換來的。第一只對系統(tǒng)級錯誤重試。業(yè)務(wù)錯誤重試是純粹的浪費還會放大日志噪音。流控錯誤可以重試但必須延遲而且要區(qū)分是單號碼頻控還是全局頻控——單號碼頻控重試沒有意義用戶等一會兒自己會點重發(fā)。第二重試次數(shù)必須有硬上限。我一般設(shè) 2 次最多 3 次。每次重試間隔用指數(shù)退避比如 200ms、600ms、1.8s?？偤臅r控制在讀超時的兩倍以內(nèi)避免線程被長時間占用。第三重試必須有冪等保護(hù)。這一條最容易被忽略。如果第一次請求實際上已經(jīng)成功只是響應(yīng)在網(wǎng)絡(luò)中丟失了你的重試會導(dǎo)致用戶收到兩條短信。解決辦法是給每次業(yè)務(wù)發(fā)送分配一個唯一的 OutId并且在下游做去重——但短信服務(wù)端一般不會基于 OutId 去重所以更實際的做法是在應(yīng)用層做重試之前先查一下本地發(fā)送記錄如果這條業(yè)務(wù)流水已經(jīng)標(biāo)記為成功就不再重試。public SendResult sendWithRetry(SmsCommand cmd) { SendResult last null; long backoff 200L; for (int i 0; i MAX_RETRY; i) { last doSend(cmd); if (last.isSuccess()) return last; if (last.getErrorType() ! SmsErrorType.SYSTEM_ERROR) return last; if (i MAX_RETRY) break; sleepQuietly(backoff); backoff * 3; } return last; }6. 生產(chǎn)加固冪等、限流、異步、降級跑通了、封裝了、錯誤碼也處理了代碼看起來沒問題了。但在真實流量下還差四道加固。這一節(jié)講的是從能用到敢在大促期間用的距離。6.1 冪等設(shè)計從業(yè)務(wù)流水號到發(fā)送記錄冪等的核心是給每一次用戶意圖分配一個唯一的業(yè)務(wù)標(biāo)識然后保證同一個標(biāo)識只會真正觸發(fā)一次發(fā)送。這個標(biāo)識通常由業(yè)務(wù)側(cè)生成比如登錄驗證碼 用戶 ID 時間窗口的組合哈?；蛘咧苯佑靡粋€全局唯一的請求 ID。落地方式是在發(fā)送前先查一次記錄表發(fā)送成功后寫入記錄。這張表要能支撐高頻寫入字段包括業(yè)務(wù)標(biāo)識、手機(jī)號哈希、模板碼、狀態(tài)、RequestId、BizId、創(chuàng)建時間。狀態(tài)分為發(fā)送中、成功、失敗發(fā)送中的記錄要設(shè)過期時間避免因為進(jìn)程崩潰導(dǎo)致記錄一直卡在中間狀態(tài)。這里有個細(xì)節(jié)值得注意狀態(tài)表不能用手機(jī)號做唯一鍵要用業(yè)務(wù)標(biāo)識做唯一鍵。因為同一個手機(jī)號在不同業(yè)務(wù)場景下發(fā)送是允許的比如一分鐘內(nèi)既能收到登錄驗證碼又能收到支付驗證碼用手機(jī)號做唯一鍵會誤殺。6.2 限流三層限流缺一不可短信的限流要做三層少一層都可能出問題。第一層是賬號級限流防止整體用量超過配額導(dǎo)致被平臺限速。這一層通常用令牌桶實現(xiàn)速率按你的套餐額度和業(yè)務(wù)峰值設(shè)置。第二層是場景級限流登錄驗證碼、注冊驗證碼、通知類短信分別設(shè)置不同的速率上限。這樣即使某一類場景被刷也不會影響其他場景。這層是防止單點故障擴(kuò)散的關(guān)鍵。第三層是用戶級限流同一個手機(jī)號在時間窗口內(nèi)的發(fā)送次數(shù)限制這層既是成本控制也是風(fēng)控。常見的規(guī)則是同號碼 1 分鐘內(nèi)最多 1 條1 小時內(nèi)最多 5 條24 小時內(nèi)最多 10 條。// 用戶級限流示意用本地緩存或 Redis 計數(shù)器都行 public boolean allowSend(String phone) { String keyMinute sms:min: md5(phone); String keyHour sms:hour: md5(phone); String keyDay sms:day: md5(phone); if (counter.get(keyMinute) 1) return false; if (counter.get(keyHour) 5) return false; if (counter.get(keyDay) 10) return false; counter.incrementAll(keyMinute, keyHour, keyDay); return true; }用 Redis 做計數(shù)器的時候要注意過期時間的設(shè)置以及原子性。用INCR加EXPIRE兩步操作會有競態(tài)推薦用 Lua 腳本或者帶過期參數(shù)的原子命令。6.3 異步化把發(fā)送從用戶請求線程里挪出去這個改造對用戶體驗的提升是最直接的。原來的流程是用戶點發(fā)送驗證碼請求線程同步調(diào)用短信接口用戶要等接口返回才能看到已發(fā)送提示。改造后變成請求線程只做校驗、限流、生成任務(wù)、投遞到線程池或消息隊列立刻返回后臺消費者實際調(diào)用 SDK 發(fā)送。異步化之后短信接口的抖動就不會傳導(dǎo)到用戶請求上了。但異步也帶來了新的問題發(fā)送失敗怎么辦答案是把發(fā)送記錄的狀態(tài)維護(hù)好失敗時按策略重試或標(biāo)記失敗用戶點重新發(fā)送的時候能看到真實狀態(tài)。線程池的配置要單獨隔離不要和業(yè)務(wù)的公共線程池混用。核心線程數(shù)按發(fā)送峰值估算隊列要有界拒絕策略用 CallerRuns 或者直接丟棄并打日志——絕不能用無界隊列那等于把內(nèi)存當(dāng)緩沖出問題是遲早的。6.4 降級與多通道容災(zāi)單一服務(wù)商總有不可用的時候尤其是大促期間。降級方案有兩個層次。輕量級的做法是配置降級開關(guān)當(dāng)短信發(fā)送失敗率超過閾值比如連續(xù) 1 分鐘失敗率超過 30%自動切換到降級模式驗證碼場景改為純語音播報或者干脆在頁面上給出明確提示短信通道繁忙請稍后再試避免用戶在那里干等。重量級的做法是雙服務(wù)商容災(zāi)同時接入兩家的 SDK主通道失敗時自動切到備用通道。這個方案的工程成本不低因為兩家的模板、簽名都要各自申請返回碼體系也不同需要做一層統(tǒng)一的抽象。但對短信強(qiáng)依賴的業(yè)務(wù)來說這是必要的投入。實現(xiàn)上可以定義一個SmsProvider接口兩個實現(xiàn)類分別包裝兩家的 SDK用一個路由策略決定走哪個通道。7. 驗證碼之外批量通知、可觀測性與成本接完主鏈路剩下的是一些容易被忽略但影響很大的工程細(xì)節(jié)。這一節(jié)講三塊批量發(fā)送的正確姿勢、監(jiān)控指標(biāo)怎么設(shè)計、成本怎么摳。7.1 批量發(fā)送不要用循環(huán)單發(fā)通知類短信經(jīng)常是批量場景比如給一批用戶發(fā)活動通知。最常見的錯誤寫法是 for 循環(huán)調(diào)用單發(fā)接口一千個用戶就是一千次 HTTP 請求耗時不說還容易觸發(fā)賬號級流控。SDK 一般提供了批量發(fā)送接口支持一次傳入多個號碼用逗號分隔但要注意三個限制。第一單次批量有號碼數(shù)量上限通常是幾百到一千個超過要自己分批。第二批量發(fā)送的模板參數(shù)是共享的如果每個用戶的內(nèi)容不同就不能用批量接口只能在應(yīng)用層并發(fā)單發(fā)。第三批量接口的返回是全成功或全失敗不提供逐個號碼的結(jié)果需要單獨查詢。所以實際做法是內(nèi)容相同的場景用批量接口分批調(diào)用每批之間加一點間隔避免瞬時壓力內(nèi)容不同的場景用單發(fā)但要控制并發(fā)度用一個固定大小的線程池或者信號量限流不要把下游打爆。7.2 監(jiān)控指標(biāo)四個必須埋的點短信鏈路的監(jiān)控我一般埋四組指標(biāo)缺一不可。第一組是發(fā)送量與成功率按場景、按模板、按小時聚合。成功率突然下跌是最直接的問題信號。第二組是錯誤碼分布尤其要關(guān)注幾個高危錯誤碼的出現(xiàn)次數(shù)余額不足、簽名非法、模板非法。這三個指標(biāo)應(yīng)該配置成零容忍告警出現(xiàn)一次就通知到人。第三組是調(diào)用耗時分布重點看 P95 和 P99。耗時的突然拉長往往預(yù)示著上游網(wǎng)關(guān)承壓是故障的早期信號。第四組是被限流攔截的請求數(shù)包括平臺側(cè)返回的流控錯誤和本地限流攔截的數(shù)量。本地攔截數(shù)量突增通常意味著有人在刷驗證碼需要聯(lián)動風(fēng)控。這幾個指標(biāo)用 Micrometer 埋點接到 Prometheus 上看板就行成本很低但收益很大。我的經(jīng)驗是有了這四組指標(biāo)絕大多數(shù)短信問題都能在用戶投訴之前被發(fā)現(xiàn)。7.3 成本控制長短信和無效號碼是最大的兩個坑短信成本有兩塊很容易失控。第一塊是長短信。一條普通短信的計費長度是 70 字含簽名超過 70 字會按長短信拆分每 67 字計一條費。如果你的模板參數(shù)里塞了 URL 或者長段文字很容易把一條變成三條成本直接翻三倍。控制方法是在模板設(shè)計階段就把內(nèi)容控制在 70 字以內(nèi)參數(shù)只放必要信息URL 用短鏈。第二塊是無效號碼?？仗?、停機(jī)、錯號發(fā)出去照樣計費所以號碼有效性校驗很關(guān)鍵。除了本地格式校驗還可以接號碼檢測能力把明顯無效的號碼在入庫階段就過濾掉。另外對發(fā)送返回號碼非法的記錄做定期統(tǒng)計如果某個業(yè)務(wù)線的非法率異常高說明上游數(shù)據(jù)源有問題需要從源頭治理。第三塊是重發(fā)。用戶頻繁點重新發(fā)送會顯著增加成本前端應(yīng)該做按鍵倒計時后端要做頻控兜底。這兩道防線都必須在只靠前端是不夠的接口可以被直接調(diào)用。提示成本監(jiān)控建議做成日報把每日發(fā)送量、失敗量、拆分率、活躍號碼數(shù)做成趨勢圖。成本異常往往不是一天漲上去的而是慢慢爬坡日報能讓你在一周內(nèi)發(fā)現(xiàn)異常而不是一個月后發(fā)現(xiàn)賬單翻倍。8. 我在這條鏈路上交過的兩次學(xué)費第一次是把發(fā)送放在了事務(wù)里。當(dāng)時的實現(xiàn)是注冊接口里先插用戶表再發(fā)驗證碼兩個操作在一個Transactional方法里。短信發(fā)送失敗拋異常事務(wù)回滾用戶注冊失敗這看起來合理實際上非常糟糕短信已經(jīng)發(fā)出去了但數(shù)據(jù)庫回滾了用戶收到驗證碼卻無法完成注冊重新注冊又會收到第二條。這個設(shè)計錯誤的本質(zhì)是把外部副作用和本地事務(wù)混在一起。正確做法是把發(fā)短信挪到事務(wù)提交之后用TransactionSynchronizationManager的 afterCommit 回調(diào)或者事務(wù)事件監(jiān)聽。第二次是被短信回執(zhí)坑了。當(dāng)時以為發(fā)送返回 OK 就萬事大吉沒有接回執(zhí)結(jié)果在一次通道故障中大量短信顯示發(fā)送成功但用戶普遍反映沒收到。事后追溯才發(fā)現(xiàn)那段時間該通道的下行投遞大面積失敗控制臺里有一堆已提交未送達(dá)的記錄但我們沒有任何告警。接了回執(zhí)之后這種情況就能通過提交成功但回執(zhí)失敗率上升及時發(fā)現(xiàn)。如果現(xiàn)在讓我重新接一遍我會按這樣的順序做先理清場景和模板把簽名和模板提前審核然后搭好服務(wù)層把校驗、錯誤分類、結(jié)果對象、冪等和限流一次性做進(jìn)去接著配置監(jiān)控和告警確保余額、簽名、模板三類問題能第一時間知道最后才是異步化和多通道容災(zāi)這些優(yōu)化項。順序很重要因為前兩步是地基后面所有優(yōu)化都建立在它們之上。至于代碼本身有多簡單其實不重要——難的一直都不是那幾行調(diào)用。