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