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