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