簡(jiǎn)介這份壓縮包定位為阿里云短信服務(wù)在PHP環(huán)境中的集成示例面向需要快速接入短信驗(yàn)證碼、系統(tǒng)通知或營(yíng)銷消息的網(wǎng)站開發(fā)者。壓縮包整體大小約三點(diǎn)三五兆字節(jié)內(nèi)含阿里云官方短信服務(wù)的PHP開發(fā)包調(diào)用示例完整演示了從配置訪問(wèn)密鑰、初始化客戶端、調(diào)用發(fā)送短信接口到解析返回結(jié)果的流程同時(shí)梳理了短信模板變量替換、簽名審核規(guī)則、同步與異步調(diào)用差異、異常與錯(cuò)誤碼排查以及使用加密傳輸和妥善保管密鑰等安全注意事項(xiàng)知識(shí)點(diǎn)覆蓋全面。此外該開發(fā)包還支持查詢發(fā)送狀態(tài)、接收短信驗(yàn)證碼等擴(kuò)展操作便于開發(fā)者按業(yè)務(wù)需求二次開發(fā)。已有二百七十四人瀏覽學(xué)習(xí)借助該示例可以直觀理解接口參數(shù)含義與調(diào)試技巧在實(shí)際項(xiàng)目中快速完成短信功能對(duì)接有效減少踩坑與返工。1. 阿里云短信接口demo.zip一個(gè)壓縮包里藏著的完整調(diào)用鏈路做過(guò)對(duì)接短信功能的后端都懂第一次拿到阿里云短信接口demo.zip以為解壓就能跑通結(jié)果被AccessKey、簽名、模板、endpoint四個(gè)概念輪番勸退。這個(gè)壓縮包不大通常就是pom.xml、一個(gè)配置文件、一個(gè)發(fā)送示例類但它背后對(duì)應(yīng)的是完整的鏈路開通短信服務(wù)、申請(qǐng)簽名、申請(qǐng)模板、創(chuàng)建RAM子賬號(hào)、引入SDK、調(diào)SendSms、讀懂錯(cuò)誤碼。它能解決“如何在十分鐘內(nèi)把第一條短信發(fā)到手機(jī)”的問(wèn)題適合剛接手短信需求的后端開發(fā)也適合被產(chǎn)品催著“今天就上驗(yàn)證碼”的工程同學(xué)。這里把demo值得復(fù)用的部分拆開講透哪些要改、哪些別動(dòng)、發(fā)不出去先查哪里。2. 先看懂短信接口的調(diào)用模型再動(dòng)demo代碼很多人解壓demo就急著跑main這是新手階段最常見的動(dòng)作。我一般勸他們先花十分鐘看明白這個(gè)接口是怎么工作的——demo能跑通不代表業(yè)務(wù)能扛真實(shí)流量短信這種接口一旦上線發(fā)不出去挨罵的是你不是demo。2.1 一次短信發(fā)送只是“受理”不是“到達(dá)”阿里云短信接口的調(diào)用模型并不復(fù)雜客戶端拿著AccessKey構(gòu)造請(qǐng)求把手機(jī)號(hào)、簽名名、模板號(hào)、模板變量拼成參數(shù)調(diào)用SendSms這個(gè)Action請(qǐng)求發(fā)到dysmsapi.aliyuncs.com這個(gè)endpoint。阿里云后端校驗(yàn)請(qǐng)求合法性——這一步校驗(yàn)的是AccessKey簽名也叫請(qǐng)求簽名——再校驗(yàn)短信簽名和模板的歸屬與狀態(tài)都通過(guò)之后才把短信交給運(yùn)營(yíng)商下發(fā)。這里有個(gè)新手普遍會(huì)踩的認(rèn)知坑SendSms返回的Code等于OK只代表阿里云受理了這條消息不代表手機(jī)已經(jīng)收到。短信真正下發(fā)的狀態(tài)要等運(yùn)營(yíng)商回執(zhí)存儲(chǔ)在阿里云側(cè)需要用另一個(gè)接口QuerySendDetails按手機(jī)號(hào)和日期去查或者在控制臺(tái)看發(fā)送記錄。把“受理成功”當(dāng)成“發(fā)送成功”對(duì)外承諾是很多線上事故的起點(diǎn)。錯(cuò)誤碼也要提前建立認(rèn)知。阿里云短信返回的錯(cuò)誤碼分成幾類前綴不同含義完全不同常見的類型如下錯(cuò)誤碼前綴/樣式含義典型處理isv.*產(chǎn)品側(cè)參數(shù)或業(yè)務(wù)規(guī)則錯(cuò)誤檢查參數(shù)、簽名、模板、頻控isp.*服務(wù)側(cè)或運(yùn)營(yíng)商回執(zhí)錯(cuò)誤稍后重試或查具體子碼SignatureDoesNotMatchAccessKey或簽名算法錯(cuò)誤檢查密鑰和本地時(shí)間Throttling接口調(diào)用請(qǐng)求過(guò)于頻繁降低頻率稍后重試收到isv開頭的基本是代碼或配置問(wèn)題自己排查isp開頭的多半是短期故障重試比改代碼有效。這個(gè)分類能讓排錯(cuò)少走彎路。另一個(gè)關(guān)鍵點(diǎn)是AccessKey的權(quán)限模型。demo里通常用的主賬號(hào)AccessKey能跑通但風(fēng)險(xiǎn)極大。生產(chǎn)環(huán)境建議在RAM里開一個(gè)子賬號(hào)只授予短信服務(wù)相關(guān)權(quán)限把AccessKeyId和AccessKeySecret放到環(huán)境變量或密鑰管理服務(wù)不能讓它們出現(xiàn)在代碼倉(cāng)庫(kù)。這不是小題大做短信接口涉及資金和騷擾風(fēng)險(xiǎn)AccessKey一旦泄露后果比泄露數(shù)據(jù)庫(kù)密碼嚴(yán)重得多。短信簽名和模板也不是憑空就能用的。新賬號(hào)在控制臺(tái)申請(qǐng)簽名、申請(qǐng)模板后要等待審核通過(guò)才能發(fā)送。個(gè)人認(rèn)證賬號(hào)和企業(yè)認(rèn)證賬號(hào)可申請(qǐng)的簽名類型、模板內(nèi)容范圍不同營(yíng)銷類短信基本和企業(yè)認(rèn)證綁定。demo里自帶的測(cè)試簽名只能用于本地驗(yàn)證真實(shí)業(yè)務(wù)需要用自己的資質(zhì)重新申請(qǐng)。2.2 demo.zip里的常見文件布局阿里云官方給出的短信demo在國(guó)內(nèi)基本以zip形式分發(fā)解壓之后通常長(zhǎng)這樣。這里說(shuō)的是常見Java版本Python、PHP、Node.js的結(jié)構(gòu)大同小異demo.zip ├── pom.xml // Maven 依賴聲明 ├── src/main/resources/application.properties // 運(yùn)行時(shí)配置 ├── src/main/java/com/aliyun/demo/SendSmsDemo.java // 發(fā)送示例 └── README.txt // 配置說(shuō)明與申請(qǐng)入口pom.xml聲明短信SDK依賴Java版核心是dysmsapi20170525配套teaopenapi這類基礎(chǔ)庫(kù)。application.properties里放的是accessKeyId、accessKeySecret、signName、templateCode幾個(gè)運(yùn)行時(shí)參數(shù)。SendSmsDemo.java是主流程初始化客戶端、構(gòu)造請(qǐng)求、發(fā)送、打印響應(yīng)。為什么demo里用properties而不是yaml因?yàn)閐emo要跨框架復(fù)用Spring Boot工程里yaml需要特定解析器而properties是JDK原生支持的鍵值格式任何Java工程都能讀。你在自己工程里換成yaml沒問(wèn)題但理解它用properties是為了最大兼容。把demo導(dǎo)入IDEA時(shí)記得在Maven面板勾選自動(dòng)導(dǎo)入等依賴下載完成再打開SendSmsDemo.java否則會(huì)看到大量標(biāo)紅報(bào)錯(cuò)。Eclipse則是Import Existing Maven Project。依賴沒拉完之前不要急著運(yùn)行JDK版本也要確認(rèn)新版SDK要求JDK 8以上。我特別提醒一點(diǎn)很多demo為了方便演示把AccessKey和簽名模板直接寫在源碼里。你可以把demo當(dāng)作學(xué)習(xí)材料但生產(chǎn)環(huán)境必須把這些配置挪到環(huán)境變量或配置中心。之前有個(gè)同事圖省事把AccessKey提交到私有Git倉(cāng)庫(kù)后來(lái)倉(cāng)庫(kù)權(quán)限配置失誤被外部掃描到一夜之間被刷幾千條短信?？圪M(fèi)還在其次更麻煩的是簽名被投訴短期封禁業(yè)務(wù)全部受影響。這條血淚經(jīng)驗(yàn)記牢。2.3 為什么用demo而不是直接啃OpenAPI文檔OpenAPI文檔寫得再全對(duì)第一次接入的人也不夠友好。原因在于版本差異。阿里云短信接口的SDK有兩代實(shí)現(xiàn)老一代用DefaultProfile初始化新一代以teaopenapi為基礎(chǔ)用Config對(duì)象設(shè)置endpoint兩代代碼的包名、類名、調(diào)用方式完全不同。如果你搜到一個(gè)老博客照著寫跟新SDK對(duì)不上編譯都過(guò)不去。判斷demo代碼新舊有個(gè)簡(jiǎn)單辦法看pom里依賴的artifactId是dysmsapi20170525還是aliyun-java-sdk-core前者是新版后者是老版。新版代碼里設(shè)置endpoint用的是config.endpoint老版則是在request里setDomain。如果看的教程和你的demo不是同代直接放棄那篇教程以demo自帶的pom為準(zhǔn)。demo的價(jià)值在于它把“哪個(gè)版本配哪種初始化方式”這件事定死了。你解壓出來(lái)的pom和代碼是配套的先跑通再改業(yè)務(wù)邏輯比對(duì)著文檔一遍遍試要快得多。但它也有“負(fù)面價(jià)值”demo為了說(shuō)明問(wèn)題通常把異常處理簡(jiǎn)化成打印堆棧把配置硬編碼。直接拿demo上線是另一種翻車姿勢(shì)。正確用法是用demo打通鏈路然后把骨架搬到自己的工程補(bǔ)上日志、連接池、異常分級(jí)、失敗重試。實(shí)際上demo的定位更像地圖——告訴你路怎么走實(shí)際開車的是你的代碼。別把地圖當(dāng)車?？吹竭@里模型已經(jīng)立住了下面把demo跑起來(lái)。3. 把demo跑起來(lái)從Maven依賴到第一條短信理論模型看完了接下來(lái)動(dòng)手。這里從解壓demo開始把常見Java流程拆成三步配倉(cāng)庫(kù)、改配置、發(fā)短信。每一步我會(huì)標(biāo)注哪些參數(shù)必須改哪些是demo里帶過(guò)來(lái)但生產(chǎn)要格外小心的。3.1 用Maven配阿里云倉(cāng)庫(kù)把依賴?yán)奖镜貒?guó)內(nèi)直接用Maven中央倉(cāng)庫(kù)拉阿里云SDK有時(shí)候會(huì)很慢特別是第一次拉teaopenapi那一組依賴容易卡住。常見做法是在Maven的settings.xml里配置阿里云公共倉(cāng)庫(kù)鏡像地址是maven.aliyun.com/repository/public。這個(gè)鏡像同時(shí)聚合了中央倉(cāng)庫(kù)和阿里云的制品倉(cāng)庫(kù)短信SDK的坐標(biāo)能直接命中。mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共倉(cāng)庫(kù)/name urlhttps://maven.aliyun.com/repository/public/url /mirror把這段加到$MAVEN_HOME/conf/settings.xml的 節(jié)點(diǎn)里。如果你只在自己用戶目錄配了~/.m2/settings.xml效果一樣。mirrorOfcentral表示只鏡像中央倉(cāng)庫(kù)不影響你自己定義的私有倉(cāng)庫(kù)這是最穩(wěn)妥的寫法不建議寫成mirrorOf*把私有倉(cāng)庫(kù)也強(qiáng)制代理掉。配置完成后在pom.xml里聲明依賴。demo自帶的pom一般已經(jīng)寫好如果你自己新建工程坐標(biāo)寫法如下dependency groupIdcom.aliyun/groupId artifactIddysmsapi20170525/artifactId version以你拉取到的最新穩(wěn)定版為準(zhǔn)/version /dependency這里不寫死具體版本號(hào)因?yàn)榘姹驹诔掷m(xù)發(fā)布。公司有統(tǒng)一BOM管理的話這個(gè)依賴的版本可以交給BOM統(tǒng)一約束業(yè)務(wù)pom里不用寫version。拉取后用mvn dependency:tree看一眼確認(rèn)teaopenapi相關(guān)傳遞依賴都已就位。老項(xiàng)目里如果還留著aliyun-java-sdk-core的舊依賴避免新舊混用新版SDK會(huì)和老包沖突建議統(tǒng)一到新SDK。Spring Boot工程導(dǎo)入demo時(shí)如果IDEA識(shí)別不到依賴先執(zhí)行mvn clean install把依賴?yán)奖镜卦偎⑿隆＿€有一類常見問(wèn)題是本地Maven倉(cāng)庫(kù)損壞清理~/.m2/repository/com/aliyun目錄后重新拉取即可不用折騰全局配置。3.2 配置AccessKey、簽名名、模板號(hào)、手機(jī)號(hào)依賴?yán)聛?lái)下一步是填配置。demo里的application.properties給了四個(gè)核心配置項(xiàng)。其中AccessKeyId和AccessKeySecret最敏感不要寫死在文件里啟動(dòng)時(shí)從環(huán)境變量讀取更安全accessKeyId${ALIYUN_ACCESS_KEY_ID} accessKeySecret${ALIYUN_ACCESS_KEY_SECRET} signName你的短信簽名 templateCodeSMS_000000000${}語(yǔ)法是Spring占位符方式demo如果不用Spring直接在代碼里System.getenv()讀取也一樣。重點(diǎn)在于AccessKeyId和Secret必須來(lái)自安全環(huán)境不要在倉(cāng)庫(kù)出現(xiàn)真實(shí)值。signName是你在控制臺(tái)申請(qǐng)通過(guò)后看到的簽名名稱比如“某某科技”templateCode是模板批準(zhǔn)后的編號(hào)格式是SMS_加數(shù)字。這兩個(gè)值在控制臺(tái)菜單里都能找到。提示如果代碼里直接寫AccessKey并提交到Git倉(cāng)庫(kù)即使在私有倉(cāng)庫(kù)也存在泄露風(fēng)險(xiǎn)。建議用環(huán)境變量或配置中心管理并在啟動(dòng)時(shí)校驗(yàn)環(huán)境變量是否為空。AccessKey的獲取路徑需要說(shuō)清楚。常見做法是在阿里云控制臺(tái)進(jìn)入RAM訪問(wèn)控制創(chuàng)建一個(gè)子用戶勾選編程訪問(wèn)生成一對(duì)AccessKey。然后給子用戶添加權(quán)限策略短信服務(wù)相關(guān)的系統(tǒng)策略名稱一般是AliyunDysmsFullAccess。不建議直接拿主賬號(hào)AccessKey因?yàn)橹髻~號(hào)權(quán)限范圍太大一旦泄露影響面不可控。手機(jī)號(hào)也可以放到配置里但生產(chǎn)環(huán)境手機(jī)號(hào)是動(dòng)態(tài)入?yún)emo里填一個(gè)自己的號(hào)碼即可方便確認(rèn)是否真的收到。我一般會(huì)把手機(jī)號(hào)和signName、templateCode分開處理簽名和模板是相對(duì)固定的靜態(tài)配置手機(jī)號(hào)和模板參數(shù)是每次請(qǐng)求的動(dòng)態(tài)數(shù)據(jù)混在一起后面不好維護(hù)。3.3 發(fā)送第一條短信核心代碼與參數(shù)說(shuō)明配置就緒寫發(fā)送邏輯。新版SDK的初始化方式和老版區(qū)別很大建議直接跟demo保持一致。新版一般寫法如下import com.aliyun.dysmsapi20170525.Client; import com.aliyun.dysmsapi20170525.models.SendSmsRequest; import com.aliyun.dysmsapi20170525.models.SendSmsResponse; import com.aliyun.teaopenapi.models.Config; public class SendSmsDemo { public static void main(String[] args) throws Exception { // 1. 從環(huán)境變量讀取AccessKey避免硬編碼 String accessKeyId System.getenv(ALIYUN_ACCESS_KEY_ID); String accessKeySecret System.getenv(ALIYUN_ACCESS_KEY_SECRET); // 2. 初始化客戶端短信服務(wù)endpoint全局唯一 Config config new Config() .setAccessKeyId(accessKeyId) .setAccessKeySecret(accessKeySecret); config.endpoint dysmsapi.aliyuncs.com; Client client new Client(config); // 3. 構(gòu)造短信請(qǐng)求TemplateParam是JSON字符串 SendSmsRequest request new SendSmsRequest() .setPhoneNumbers(13800138000) .setSignName(你的短信簽名) .setTemplateCode(SMS_000000000) .setTemplateParam({\code\:\1234\}); // 4. 同步發(fā)送并輸出返回結(jié)果 SendSmsResponse response client.sendSms(request); System.out.println(response.getBody().getCode()); System.out.println(response.getBody().getMessage()); } }這段代碼的邏輯拆開看第一步從環(huán)境變量取AccessKey避免硬編碼第二步用Config對(duì)象設(shè)置endpoint短信接口所有region統(tǒng)一走dysmsapi.aliyuncs.com不像ECS那樣需要分地域域名第三步構(gòu)造SendSmsRequest四個(gè)入?yún)⑹顷P(guān)鍵第四步同步調(diào)用sendSms拿到響應(yīng)。四個(gè)參數(shù)的含義和邊界我整理了一張表參數(shù)類型說(shuō)明是否必須phoneNumbersString接收手機(jī)號(hào)只支持單個(gè)號(hào)碼不用加86是signNameString短信簽名需在控制臺(tái)審核通過(guò)是templateCodeString短信模板編號(hào)格式為SMS_開頭是templateParamStringJSON格式字符串key需與模板變量一致模板帶變量時(shí)必須最容易被搞混的是TemplateParam。它看起來(lái)像對(duì)象實(shí)際上是一個(gè)JSON格式的字符串而且JSON里的key必須和模板里聲明的變量名完全一致。模板內(nèi)容如果寫了“您的驗(yàn)證碼為${code}${minute}分鐘內(nèi)有效”那么TemplateParam必須是{code:1234,minute:5}多一個(gè)、少一個(gè)、大小寫不一樣都會(huì)直接報(bào)變量相關(guān)錯(cuò)誤。另一個(gè)容易踩的是引號(hào)轉(zhuǎn)義Java字符串里表示JSON的double quote必須加反斜杠所以我一般不用手拼字符串而是用Jackson或Gson序列化Map代碼更可讀也更安全。響應(yīng)體里的Code、Message、RequestId、BizId四個(gè)值都值得打日志。RequestId用于向阿里云提交工單時(shí)定位請(qǐng)求BizId是交易流水號(hào)查詢明細(xì)時(shí)要帶上。demo里只打印了Code和Message生產(chǎn)環(huán)境的日志要全量記錄這四個(gè)字段。到這里main方法跑通手機(jī)上應(yīng)該能收到測(cè)試短信。如果沒收到別急著懷疑代碼先看第五章的排錯(cuò)清單。4. 從demo到生產(chǎn)簽名、模板、參數(shù)與異步改造demo能發(fā)出短信只是第一步離生產(chǎn)可用還有四個(gè)必須處理的點(diǎn)。這一章聊的是把demo代碼拿去做真實(shí)業(yè)務(wù)時(shí)哪些參數(shù)要重新定義、哪些調(diào)用方式要換掉。4.1 region、endpoint、簽名、模板四者的對(duì)應(yīng)關(guān)系短信服務(wù)和ECS、OSS最大的差異在于短信接口的endpoint是全局唯一的dysmsapi.aliyuncs.com不分華東、華北、海外。但這不意味著沒有地域概念——需要在控制臺(tái)確認(rèn)短信服務(wù)開通在哪個(gè)地域以及RAM權(quán)限策略里是否限制了地域。多數(shù)情況下主賬號(hào)開通的短信服務(wù)可以在任意地域調(diào)用但如果用了RAM自定義策略可能被限定在cn-hangzhou這就是本地能發(fā)、線上403的原因之一。簽名和模板是綁在賬號(hào)上的資源不跟地域走但跟賬號(hào)類型走。個(gè)人認(rèn)證賬號(hào)和企業(yè)認(rèn)證賬號(hào)可申請(qǐng)的簽名類型、模板內(nèi)容范圍不同。個(gè)人賬號(hào)只能發(fā)驗(yàn)證碼和通知類營(yíng)銷類短信基本和企業(yè)認(rèn)證綁定。這意味著如果業(yè)務(wù)方要求發(fā)營(yíng)銷推廣短信demo里那套測(cè)試簽名肯定不行必須用企業(yè)資質(zhì)去申請(qǐng)。我一般會(huì)在工程里建一個(gè)短信配置常量類把簽名和模板集中管理用枚舉區(qū)分業(yè)務(wù)場(chǎng)景。驗(yàn)證碼模板是一個(gè)枚舉值通知模板是一個(gè)枚舉值避免業(yè)務(wù)代碼里到處裸寫模板編號(hào)。散落的配置一多改一個(gè)簽名名都要全局搜索實(shí)在痛苦。Spring Boot工程里還可以把這組枚舉交給Spring管理緩存到本地Map一次性加載每次發(fā)送只查內(nèi)存。4.2 TemplateParam的JSON轉(zhuǎn)義與變量約束短信模板的變量不是隨便傳的。每個(gè)變量有長(zhǎng)度限制驗(yàn)證碼類變量默認(rèn)不超過(guò)20個(gè)字符具體看模板審核結(jié)果。另外阿里云會(huì)對(duì)變量值做敏感詞過(guò)濾你傳了“免費(fèi)”兩個(gè)字很可能被系統(tǒng)攔截這類營(yíng)銷敏感詞會(huì)直接導(dǎo)致發(fā)送失敗。一個(gè)常見錯(cuò)誤是企業(yè)內(nèi)部發(fā)給會(huì)員的短信里帶“免費(fèi)領(lǐng)取”這類詞模板審核時(shí)通常通不過(guò)。第二個(gè)常見錯(cuò)誤是模板變量在代碼里拼JSON時(shí)引號(hào)轉(zhuǎn)義出錯(cuò)。我建議的做法是始終用Jackson序列化結(jié)構(gòu)體不要手寫字符串MapString, String paramMap new HashMap(); paramMap.put(code, randomCode); paramMap.put(minute, 5); String templateParam new ObjectMapper().writeValueAsString(paramMap);這段代碼的價(jià)值在于Map的key決定變量名value就是變量值序列化后天然是合法JSON不需要關(guān)心字符串里有沒有特殊符號(hào)。如果值本身是中文JSON庫(kù)也會(huì)自動(dòng)處理Unicode轉(zhuǎn)義省去一行行找引號(hào)的體力活。另一個(gè)隱蔽的坑是模板變量在控制臺(tái)審核時(shí)寫的是中文變量名而代碼里TemplateParam的key必須和模板變量完全一致。有些模板設(shè)置人員習(xí)慣在控制臺(tái)用“驗(yàn)證碼”作為變量名代碼里卻寫了“code”發(fā)送時(shí)就報(bào)變量不匹配。所以建立模板的時(shí)候我一般直接在變量列表里定義英文字段名從源頭避免編碼混亂。4.3 線程池發(fā)送驗(yàn)證碼異步與流控的平衡demo里用main方法同步調(diào)用sendSms一個(gè)請(qǐng)求幾秒內(nèi)返回看起來(lái)沒問(wèn)題。但放到Spring Boot里直接這么寫就麻煩了接口內(nèi)同步調(diào)短信用戶的請(qǐng)求會(huì)一直掛著短信服務(wù)端偶爾耗時(shí)超過(guò)2秒整個(gè)HTTP鏈路就感覺卡頓。常見做法是把發(fā)送拆成異步接收請(qǐng)求時(shí)只做參數(shù)校驗(yàn)和快速校驗(yàn)然后丟線程池發(fā)送讓接口立即返回。private final ExecutorService smsPool new ThreadPoolExecutor( 4, 8, 60L, TimeUnit.SECONDS, new LinkedBlockingQueue(1000)); public void sendCodeAsync(String phone, String code) { smsPool.execute(() - { // 組裝請(qǐng)求并調(diào)用sendSms SendSmsResponse resp client.sendSms(req); if (!OK.equals(resp.getBody().getCode())) { // 記錄錯(cuò)誤碼觸發(fā)告警 } }); }異步線程池的核心數(shù)不需要很大因?yàn)槎绦沤涌诒旧碛蓄l控。阿里云對(duì)短信接口有默認(rèn)的頻率限制控制臺(tái)或錯(cuò)誤碼說(shuō)明里有明確值但有個(gè)經(jīng)驗(yàn)性結(jié)論對(duì)同一個(gè)手機(jī)號(hào)發(fā)送驗(yàn)證碼通常一分鐘內(nèi)不能超過(guò)一條同一個(gè)簽名下的總量也有每日閾值。線程池開得再大也會(huì)被頻控卡住所以異步的目的是提高接口響應(yīng)速度不是為了無(wú)限并發(fā)。我習(xí)慣把頻控設(shè)計(jì)在業(yè)務(wù)側(cè)給同一手機(jī)號(hào)的驗(yàn)證碼發(fā)送加一個(gè)Redis分布式鎖或本地時(shí)間窗口判斷距離上次發(fā)送不到60秒直接拒絕讓頻控錯(cuò)誤不要打到阿里云上。這樣既保護(hù)自己也避免把賬號(hào)的發(fā)送額度燒光。隊(duì)列滿時(shí)要有策略一般是丟棄并提示稍后重試不能無(wú)限往阻塞隊(duì)列里塞內(nèi)存會(huì)爆。4.4 阿里云短信API與云MAS平臺(tái)接口的選擇并不是所有短信業(yè)務(wù)都必須走阿里云。很多企業(yè)和集團(tuán)客戶特別是運(yùn)營(yíng)商背景的甲方會(huì)要求使用中國(guó)移動(dòng)的云MAS平臺(tái)也就是常說(shuō)的“云MAS平臺(tái)http(java)接口文檔短信”。它的對(duì)接方式不同云MAS對(duì)外暴露的是HTTP接口Java側(cè)用HttpClient構(gòu)造表單請(qǐng)求就能提交不需要引入重量級(jí)SDK但鑒權(quán)方式、加密規(guī)則、狀態(tài)推送機(jī)制是另一套標(biāo)準(zhǔn)。什么時(shí)候選阿里云短信API什么時(shí)候選云MAS我從工程角度給判斷標(biāo)準(zhǔn)如果只是產(chǎn)品里的驗(yàn)證碼、通知追求接入速度和穩(wěn)定性選阿里云demo和文檔生態(tài)完整排錯(cuò)有據(jù)可循如果業(yè)務(wù)明確需要走移動(dòng)通道才能有更好的到達(dá)率或者合同指定云MAS那按它的http接口文檔實(shí)現(xiàn)也不復(fù)雜只是要做好通道切換的抽象。我見過(guò)不少項(xiàng)目在代碼里寫死廠商短信客戶端后來(lái)要換通道時(shí)只能大改。所以我會(huì)在業(yè)務(wù)代碼和廠商SDK之間加一層SmsSender接口阿里云和云MAS各自實(shí)現(xiàn)切換通道時(shí)只動(dòng)配置。這個(gè)抽象聽起來(lái)多寫幾個(gè)類但真的遇到通道故障要切換時(shí)能省一整夜的折騰。5. 阿里云短信api發(fā)不出去的排查清單五個(gè)高頻坑我把多年踩坑的記錄整理成排查清單。每一條都是“現(xiàn)象→原因→解決”三段寫法遇到問(wèn)題直接對(duì)照比翻文檔快。5.1 報(bào)錯(cuò)isv.SMS_SIGNATURE_ILLEGAL簽名不合法現(xiàn)象調(diào)用SendSms返回Codeisv.SMS_SIGNATURE_ILLEGALMessage提示簽名不合法或未審核。原因三選一。一是signName寫錯(cuò)了常見是把“某某科技”寫成“某科技”二是簽名還沒審核通過(guò)新申請(qǐng)的簽名有審核周期期間調(diào)用會(huì)被拒絕三是簽名被停用通常是內(nèi)容違規(guī)或投訴過(guò)多導(dǎo)致。解決先到控制臺(tái)“簽名管理”頁(yè)面看簽名狀態(tài)狀態(tài)必須為已審核通過(guò)。再看代碼里signName參數(shù)是否和控制臺(tái)完全一致包括括號(hào)、空格這類字符。在工程里執(zhí)行g(shù)rep -R signName src/能找到所有引用點(diǎn)逐一核對(duì)。如果簽名被停用只能重新申請(qǐng)所有引用舊簽名的代碼得一并改掉。5.2 報(bào)錯(cuò)isv.MOBILE_NUMBER_ILLEGAL手機(jī)號(hào)不被認(rèn)可現(xiàn)象參數(shù)里手機(jī)號(hào)是“13800138000”這種正常號(hào)段但接口返回手機(jī)號(hào)不合法。原因手機(jī)號(hào)字段傳了帶國(guó)家碼、帶空格、帶橫杠的格式或者變量在傳輸過(guò)程中被解析成數(shù)字導(dǎo)致精度丟失。我遇到過(guò)用Long類型傳手機(jī)號(hào)前導(dǎo)0被截?cái)嗟那闆r還有一次是業(yè)務(wù)方把多個(gè)手機(jī)號(hào)用逗號(hào)拼接傳進(jìn)來(lái)以為能群發(fā)其實(shí)SendSms一次只接受一個(gè)號(hào)碼。解決發(fā)送前做嚴(yán)格清洗統(tǒng)一用字符串接收手機(jī)號(hào)去掉86、空格、橫杠再用正則^1\d{10}$校驗(yàn)。打印入?yún)⒌淖止?jié)長(zhǎng)度看號(hào)碼里是否有肉眼看不見的零寬字符這類字符在復(fù)制粘貼時(shí)偶爾混進(jìn)來(lái)。群發(fā)需求不要用SendSms循環(huán)要用批量發(fā)送能力這屬于另一條產(chǎn)品線的能力。5.3 報(bào)錯(cuò)isv.TEMPLATE_MISSING_PARAMETER模板變量對(duì)不上現(xiàn)象模板審核內(nèi)容里有${code}和${minute}但代碼只傳了code接口報(bào)缺少參數(shù)。原因TemplateParam里的key集合和模板變量集合不匹配。多傳、少傳、key拼寫不一致都會(huì)觸發(fā)這一類錯(cuò)誤。有些模板變量被設(shè)置成中文代碼里卻是英文同樣報(bào)錯(cuò)。解決最直接的排查是把TemplateParam打印出來(lái)和模板內(nèi)容逐字對(duì)比。記住模板變量名是認(rèn)證時(shí)定義的代碼必須對(duì)齊認(rèn)證值而不是“我覺得叫什么就叫什么”。用JSON庫(kù)序列化參數(shù)Map減少轉(zhuǎn)義問(wèn)題的同時(shí)也方便打印日志核對(duì)。如果模板里變量很多可以寫個(gè)單元測(cè)試把模板變量枚舉和參數(shù)Map做差集校驗(yàn)漏傳了在發(fā)短信之前就報(bào)錯(cuò)。5.4 報(bào)錯(cuò)isv.BUSINESS_LIMIT_CONTROL流控觸發(fā)的玄學(xué)現(xiàn)象代碼沒變配置沒換突然批量發(fā)送時(shí)大量報(bào)BUSINESS_LIMIT_CONTROL。剛發(fā)完一條緊接著發(fā)第二條也報(bào)這個(gè)錯(cuò)。原因阿里云對(duì)單手機(jī)號(hào)、單簽名、單賬號(hào)均有頻率控制。驗(yàn)證碼場(chǎng)景尤其嚴(yán)格同一號(hào)碼在幾秒內(nèi)重復(fù)請(qǐng)求基本必然觸發(fā)流控。還有一些限制是賬戶維度的比如每天總量、高峰并發(fā)量控制臺(tái)不一定每個(gè)都能看到明確閾值。解決業(yè)務(wù)側(cè)加發(fā)送間隔控制驗(yàn)證碼場(chǎng)景通常對(duì)同一號(hào)碼限60秒一條。補(bǔ)發(fā)按鈕要有倒計(jì)時(shí)防止手抖點(diǎn)三次。真正常量發(fā)送的場(chǎng)景提前規(guī)劃號(hào)碼維度的時(shí)間窗分散提交。這個(gè)錯(cuò)誤的玄學(xué)在于閾值可能隨賬號(hào)風(fēng)控狀態(tài)調(diào)整所以要保留完整日志出問(wèn)題時(shí)方便申請(qǐng)解除限制。5.5 本地能發(fā)、線上掛環(huán)境與權(quán)限差異現(xiàn)象demo在本地用主賬號(hào)AccessKey發(fā)送一切正常上到測(cè)試環(huán)境就開始報(bào)Forbidden或InvalidAccessKeyId或者一直超時(shí)。原因線上環(huán)境可能沒加載環(huán)境變量AccessKey拉取為空也可能是運(yùn)維只給測(cè)試環(huán)境配了某個(gè)RAM角色角色沒有短信服務(wù)權(quán)限。還有一類是網(wǎng)絡(luò)層問(wèn)題測(cè)試環(huán)境沒有放通到dysmsapi.aliyuncs.com的HTTPS出口。解決登錄線上服務(wù)器執(zhí)行echo $ALIYUN_ACCESS_KEY_ID檢查環(huán)境變量確認(rèn)值存在且與本地一致。權(quán)限方面到RAM控制臺(tái)確認(rèn)角色的授權(quán)策略里包含短信服務(wù)相關(guān)權(quán)限或者直接配置子賬號(hào)AccessKey。網(wǎng)絡(luò)方面用curl -I https://dysmsapi.aliyuncs.com探測(cè)連通性如果出口被防火墻限制加白名單或配置公司出口網(wǎng)關(guān)。6. 從demo到工程化驗(yàn)證碼存儲(chǔ)、落庫(kù)與對(duì)賬demo的問(wèn)題是你發(fā)了第一條短信但不知道它后來(lái)怎么樣了。生產(chǎn)系統(tǒng)中驗(yàn)證碼要能校驗(yàn)、發(fā)送記錄要能查、狀態(tài)要能對(duì)賬。這章講三個(gè)工程化動(dòng)作把demo代碼變成可靠的短信子系統(tǒng)。6.1 驗(yàn)證碼有效期與Redis存儲(chǔ)驗(yàn)證碼發(fā)出去5分鐘有效這是業(yè)務(wù)常態(tài)。存儲(chǔ)在Redis里key的格式我用sms:code:{phone}value存驗(yàn)證碼過(guò)期時(shí)間300秒。校驗(yàn)時(shí)先取出來(lái)比對(duì)比對(duì)成功立即刪除防止同一個(gè)驗(yàn)證碼被重復(fù)使用。還需要記錄一個(gè)每手機(jī)號(hào)的發(fā)送時(shí)間key用來(lái)做60秒的發(fā)送間隔限制兩步鎖串起來(lái)就同時(shí)解決有效期和頻控。6.2 發(fā)送記錄落庫(kù)每次發(fā)送都要落庫(kù)字段設(shè)計(jì)不需要復(fù)雜一個(gè)發(fā)送日志表就夠了。核心字段包括手機(jī)號(hào)、模板號(hào)、參數(shù)JSON、請(qǐng)求返回的Code、Message、BizId、RequestId、發(fā)送時(shí)間。BizId是阿里云返回的業(yè)務(wù)IDQuerySendDetails的時(shí)候要用。落庫(kù)的時(shí)間點(diǎn)要選在拿到響應(yīng)之后避免把沒受理成功的記錄也寫進(jìn)去。狀態(tài)字段標(biāo)記為受理成功或受理失敗后續(xù)對(duì)賬時(shí)再更新為已到達(dá)或未到達(dá)。6.3 用QuerySendDetails做對(duì)賬短信的最終狀態(tài)以運(yùn)營(yíng)商回執(zhí)為準(zhǔn)QuerySendDetails接口能按手機(jī)號(hào)和發(fā)送日期查到明細(xì)。我一般做一個(gè)定時(shí)任務(wù)每小時(shí)掃描發(fā)送日志里狀態(tài)仍是已受理的記錄批量調(diào)QuerySendDetails更新終態(tài)。注意這個(gè)接口也有頻率限制按批處理、按序號(hào)排隊(duì)不要一張表全量掃一遍直接并發(fā)查詢。對(duì)賬能發(fā)現(xiàn)很多“假成功”用戶投訴沒收到時(shí)拿BizId去查往往發(fā)現(xiàn)短信被運(yùn)營(yíng)商攔截或手機(jī)號(hào)停機(jī)。我自己的習(xí)慣是所有AccessKey配置統(tǒng)一放環(huán)境變量并在啟動(dòng)時(shí)做一次顯式校驗(yàn)配不上就FailFast進(jìn)程不啟動(dòng)不讓錯(cuò)誤配置帶著跑。有一次線上驗(yàn)證碼大面積發(fā)不出去控制臺(tái)看簽名還在排查大半天結(jié)果是RAM子賬號(hào)AccessKey過(guò)期輪換后線上配置文件沒同步更新。從那以后凡是短信相關(guān)的密鑰變更我都會(huì)在變更單里強(qiáng)制加一條“啟動(dòng)自檢”步驟。這算是我在短信接口上最值得分享的一個(gè)習(xí)慣希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取