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