简介面向需要接入阿里云短信服务的后端开发者这份资源提供了一套可直接参考的接口开发示例覆盖从账号注册、AccessKey申请到短信发送调用的完整路径。压缩包内是以Visual Studio为载体的工程示例核心代码实现清晰并封装了阿里云短信SDK所需的核心DLL便于在业务系统中快速集成或二次修改适合初涉短信服务的开发者用于理解接口参数构造和调试流程。包体共92个文件以cs源码、DLL类库、工程配置文件与说明文档为主整体体积仅485KB轻量便于下载查阅。目前已有579人学习使用可作为掌握阿里云SendSms接口参数定义与调用方式的实用资料。通过学习示例可理清Action、PhoneNumbers、SignName、TemplateCode及TemplateParam等关键参数的组装方式同时借鉴SDK鉴权、HTTP请求发送和异常重试的处理思路。附带的DLL组件与配置说明减少了编译依赖成本有助于在实际项目中快速复现短信发送功能并规避账号、模板方面的常见配置问题。1. 阿里云短信接口开发从报错到跑通的一整套Java例子明明文档、SDK、示例代码都摆在那AccessKey也是对的签名和模板却总是差一点短信始终发不出去——这是大多数人做阿里云短信接口开发的第一课。这套开发例子是从真实项目里拆出来的覆盖了开通短信服务、RAM子账号密钥、签名模板审核、Java SDK发送、批量发送、回执查询到报错排查的完整链路。它不是一篇只贴调用代码的Demo而是把每个环节的选型理由和参数含义都讲清楚了。适合需要在自己系统里接入注册验证码、短信通知、告警推送的Java后端开发也适合第一次对接短信服务的人照着配置。2. 短信服务的前置准备RAM密钥、签名与模板审核细节做短信接口开发和普通接口最大的区别在于接口代码本身几分钟就能写完真正卡时间的反而是准备阶段。AccessKey、短信签名、短信模板这三样东西缺一样代码写得再标准也跑不动。这一章把三件事按顺序拆开讲。2.1 开通短信服务产品选型和计费方式先想清楚先到阿里云控制台搜索“短信服务”进入后选择开通。这里会看到国内文本短信、国际短信、语音短信等不同产品。如果只是给国内用户发验证码和通知选国内文本短信就够了有跨境业务再单独申请国际短信这两者是独立计费的。计费上分为按量付费和套餐包。作为个人项目或测试环境按量付费更灵活先不充值也能看控制台界面真正调用时会提示欠费线上业务量稳定了再买套餐包单价会低一些。我建议新项目一律先按量付费跑通流程等日均发送量到几百条以上再评估套餐。如果你以前接过云MAS平台那种HTTP(Java)接口文档的实现会发现流程都是相通的先申请账号、拿到签名和模板再拼参数调接口只是阿里云这边把HTTP细节封装进了SDK。开通时还要注意账号的认证状态。个人实名认证和企业实名认证在短信服务上的权益不同个人认证在签名数量、模板类型、日发送量上都有更严格的限制正式业务建议尽早做企业认证。签名和模板的审核时间通常在几小时到一天工作日内提交会快一些。控制台里提供“测试签名”和“测试模板”这两样东西方便归方便但有每日发送条数限制只适合开发联调不能用于生产。另外提醒一点短信签名和模板本身不收费审核通过之前调用接口会直接报错所以开通服务后的第一件事是去准备签名和模板而不是急着写代码。2.2 创建RAM子账号AccessKey权限只给到短信服务很多新手直接用自己的主账号AccessKey调接口。主账号AccessKey等于整个账号的通行证一旦写在代码里被泄露对方能操作你名下所有云资源。正确做法是去RAM访问控制里创建一个子用户只给它短信服务的权限。步骤上分三块RAM控制台左侧“用户”里创建用户访问方式勾选“OpenAPI调用访问”创建后拿到AccessKey ID和AccessKey Secret接着给这个用户添加权限搜“Dysmsapi”或“短信服务”选中系统策略AliyunDysmsFullAccess最后把这组Key配置到项目的配置中心或环境变量里别写死在代码库。关于密钥的配置位置我通常不写死在application.yml里而是从运行环境读取。比如Spring Boot里用Value(${SMS_ACCESS_KEY_ID})注入部署时在容器或服务器上配置环境变量这样代码仓库即使泄漏也不会把密钥带出去。权限策略方面如果团队运维规范要求更细可以自己写自定义策略只允许dysmsapi动作不要直接给AdministratorAccess。另外不要天真地以为AccessKey只在后端“隐藏”了就安全前端打包后的代码里所有字符串都能被扒出来AccessKey一旦出现在前端等于公开。这里有一个容易忽略的点提示AccessKey Secret只在创建时展示一次关闭弹窗就再也看不到了。没记住就直接删除这个AccessKey重新生成别在页面上翻来翻去找。RAM子账号的权限边界可以用表格先记录好后续排查权限问题时对照着看参数取值说明控制台入口RAM访问控制创建子用户和策略权限策略AliyunDysmsFullAccess短信服务完全访问权限也可以按需缩小密钥形式AccessKey ID Secret配置在服务端不要进前端代码安全建议定期轮换离职或泄露时立刻禁用并重建2.3 签名与模板审核规则和变量设计的坑短信签名指的是消息里“【】”中的内容例如“【某某科技】”。申请签名时个人用户需要提供对应场景的证明如果是网站要填网站域名和备案信息如果是App要提供应用商店的下载链接。名称会被平台逐一核对那些看起来像个人昵称、或者与业务无关的字样审核基本过不了。常见的被拒原因有两类一是签名用了公司简称但授权证明里盖的章和账号主体不一致二是网站类签名没有填备案号审核人员无法确认归属。解决思路是先确认账号主体签名名称要么用品牌全称要么用大家公认的简称授权书主体和账号实名主体保持完全一致。模板则要规范得多。验证码类模板的写法推荐是“您的验证码为${code}${time}分钟内有效。”这里有两个点容易踩坑第一模板正文里除了变量以外不要出现链接、微信号、QQ群这类信息第二变量名用有意义的英文单词比如code、product、time不要用${1}这种无意义占位。变量个数方面不同套餐和账号等级的上限不一样以控制台提示为准设计时尽量控制在两三个以内。验证码模板和通知模板不要混用验证码模板里写“您的验证码是”通知模板里写“您预约的服务已确认”营销类短信往往需要单独申请不能拿验证码模板去发活动推广。拿我当时申请的经验来说把模板说明写清楚会显著加快审核。比如在申请表单里注明“用于用户注册时接收验证码发送频率1分钟1条”审核人员不用猜你的场景通过率自然高。签名和模板在控制台的状态有“待审核”“通过”“拒绝”三种全部变成“通过”之后再进入下一步否则后面所有接口调试都是在报错。这里要特别强调签名和模板的审核状态与调用接口是强关联的只要有任意一个处于“待审核”或“拒绝”调用发送接口就会报错而且报错信息里不会直接告诉你问题出在签名还是模板容易让人误判成代码Bug。调试前先到控制台确认这两个对象的当前状态比反复改代码更高效。3. 用Java SDK发第一条短信依赖、代码与参数拆解准备阶段完成接下来是重头戏把第一条短信真正发出去。这里以Java为例因为阿里云短信SDK在Java生态里最成熟Spring Boot项目直接引入依赖就能用。如果项目是PHP、Go或NodeSDK设计思路基本一样只是语言写法不同。3.1 工程里的Maven配置依赖坐标与阿里云公共仓库在pom.xml里引入两个核心依赖一个负责底层HTTP调用另一个是短信服务的封装。版本号建议用当前较新的稳定版比如核心包4.6.3、短信包2.2.1及以上。dependency groupIdcom.aliyun/groupId artifactIdaliyun-java-sdk-core/artifactId version4.6.3/version /dependency dependency groupIdcom.aliyun/groupId artifactIdaliyun-java-sdk-dysmsapi/artifactId version2.2.1/version /dependency代码逻辑上不用特别解释就是两个Maven坐标。需要注意的倒是拉取速度在国内网络环境里Maven中央仓库有时候下载很慢我一般会在Maven的settings.xml里配置阿里云公共仓库镜像mirror idaliyunmaven/id mirrorOf*/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror配置这个镜像之后阿里云SDK及依赖几乎秒下。这里有一个值得说明的点mirrorOf写*表示所有仓库请求都走这个镜像如果你同时用了公司内部的私服就要把mirrorOf改成具体的仓库ID避免影响其他依赖源。依赖装好之后记得在IDE里重新导入一次Maven项目别让旧的依赖缓存干扰编译。3.2 发送短信的核心方法从验证码场景说开去依赖装好之后写一个最简的发送方法。我用的是老牌DefaultProfile初始化方式虽然新版本里也有用Client初始化但这一套在维护中的老项目里最常见也最容易排查。import com.aliyuncs.DefaultAcsClient; import com.aliyuncs.IAcsClient; import com.aliyuncs.dysmsapi.model.v20170525.SendSmsRequest; import com.aliyuncs.dysmsapi.model.v20170525.SendSmsResponse; import com.aliyuncs.exceptions.ClientException; import com.aliyuncs.profile.DefaultProfile; public class SmsSender { private static final String ACCESS_KEY_ID 你的AccessKey ID; private static final String ACCESS_KEY_SECRET 你的AccessKey Secret; public static boolean sendCode(String phone, String code) throws ClientException { // 初始化客户端region固定传cn-hangzhou短信服务在这个区域统一接入 DefaultProfile profile DefaultProfile.getProfile(cn-hangzhou, ACCESS_KEY_ID, ACCESS_KEY_SECRET); IAcsClient client new DefaultAcsClient(profile); // 组装发送请求 SendSmsRequest request new SendSmsRequest(); request.setPhoneNumbers(phone); request.setSignName(某某科技); // 必须是已审核通过的签名内容 request.setTemplateCode(SMS_123456789); // 控制台模板管理里的CODE request.setTemplateParam({\code\:\ code \}); // 与模板变量对应的JSON // 调用接口并判断结果 SendSmsResponse response client.getAcsResponse(request); if (OK.equals(response.getCode())) { System.out.println(发送成功, BizId response.getBizId()); return true; } System.err.println(发送失败, code response.getCode() , message response.getMessage()); return false; } }这段代码有几个参数需要重点说。DefaultProfile.getProfile的第一个参数region是地域短信服务不用跟着业务地域走统一用cn-hangzhou即可。SignName是签名内容本身不是签名的ID很多新手把这里传成了签名名称里的“【】”或者签名编号导致签名非法。TemplateParam必须是JSON格式的字符串key要和模板里的${code}完全一致不然SDK不报格式错但服务端会返回模板参数不匹配。在异常处理上ClientException包含请求参数问题和签名问题也就是后面要展开的报错ServerException则表示短信服务端出故障或限流理论上需要做重试。发送成功后返回的BizId要先记下来后面查回执要用。补充一点关于工程实践的细节IAcsClient建议定义成单例Bean不要每次发送都new一个。因为每次初始化都会做域名解析和连接建立高并发时会浪费大量资源IAcsClient实现本身是线程安全的可以放心复用。发送成功后把手机号、模板CODE、BizId、时间四个字段落一条日志表线上排查用户“没收到短信”时这些都是第一手证据。3.3 参数对照表与常见改法签名、模板、变量JSON把SendSmsRequest里最常用的几个参数单列出来方便照着改参数方法示例说明setPhoneNumbers13800138000国内手机号不带86前缀国际短信需加国家码如852setSignName某某科技与账号下审核通过的签名内容完全一致setTemplateCodeSMS_123456789模板CODE形如SMS_后跟一串数字setTemplateParam{code:123456}JSON字符串变量key与模板定义一致setSmsUpExtendCode自定义扩展码选填用于区分业务来源需要提前报备setOutIdorder_12345选填透传业务侧ID回执时原样带回来setTemplateParam是最容易写花的地方。比如模板里变量是“${code}”你传的JSON字符串里key写成“Code”或“code ”多了空格服务端都认为模板参数缺失。JSON里的value如果包含中文不需要额外处理SDK会做编码。如果模板里有多个变量比如“您的验证码为${code}${time}分钟内有效”JSON就写成{code:123456,time:5}注意外层是一个大括号包住全部key-value。如果业务里同一场景要换不同模板建议把模板CODE做成配置项不要硬编码在代码里产品调整文案时不用改代码发版。调试阶段有一件事要特别提醒不要用真实的用户手机号反复测试阿里云对同一个手机号的发送频率有限制测多了直接触发频控反而影响正式发送。我习惯用一个专用测试号配一条测试模板专门跑开发环境。4. 把短信接入业务链路批量发送、回执查询和验证码缓存单条发送通了接下来要解决的是真实业务里会碰到的三个场景批量通知一群人、确认短信到底送达没有、验证码在服务端如何做存储和频控。这些都绕过的话短信功能只是个能跑的Demo谈不上能上线。4.1 批量发送短信两条JSON数组的顺序必须一一对应给一批用户发同一条通知时不要写个for循环去调单发接口。一个是慢一个是容易被频控再一个是会产生大量日志。SDK提供了BatchSend接口一次调用同时发送多个号码。import com.aliyuncs.dysmsapi.model.v20170525.SendBatchSmsRequest; import com.aliyuncs.dysmsapi.model.v20170525.SendBatchSmsResponse; SendBatchSmsRequest request new SendBatchSmsRequest(); // 这三个JSON数组里的元素按顺序一一对应 request.setPhoneNumberJson([\13800138000\,\13900139000\]); request.setSignNameJson([\某某科技\,\某某科技\]); request.setTemplateCode(SMS_123456789); request.setTemplateParamJson( [{\code\:\123456\},{\code\:\654321\}]); SendBatchSmsResponse response client.getAcsResponse(request); if (OK.equals(response.getCode())) { System.out.println(批量发送成功, BizId response.getBizId()); }这里最核心也最容易翻车的一点手机号、签名、模板参数三个JSON数组下标必须一一对应。第一个手机号用第一个签名和第一个模板参数第二个手机号对应第二个……一旦长度不一致服务端会报参数错误。批量接口的号码数量上限以当前账号的权益为准我一般控制在100以内超过100就拆成多批每批之间休息几百毫秒。批量接口返回的BizId也是统一的后续可以按这个BizId查所有手机号的发送详情。如果想批量发同一条固定文案不需要每个用户单独变量那TemplateParamJson也要求每个元素都写一遍同样的JSON不能省略务必记得。4.2 回执查询用QuerySendDetails确认发送结果发送接口返回OK只代表短信服务接收成功不代表用户手机真的收到了。要确认最终状态得查回执。阿里云提供了查询接口按手机号和日期查。import com.aliyuncs.dysmsapi.model.v20170525.QuerySendDetailsRequest; import com.aliyuncs.dysmsapi.model.v20170525.QuerySendDetailsResponse; QuerySendDetailsRequest request new QuerySendDetailsRequest(); request.setPhoneNumber(13800138000); request.setSendDate(20240101); // 格式必须是YYYYMMDD request.setPageSize(10L); // 每页条数最大100 request.setCurrentPage(1L); QuerySendDetailsResponse response client.getAcsResponse(request); for (QuerySendDetailsResponse.SmsSendDetailDTO detail : response.getSmsSendDetailDTOs()) { // detail.getSendStatus(): 1代表成功2代表失败3代表未知 // detail.getErrCode(): 运营商回执错误码DELIVRD表示成功 System.out.println(detail.getPhoneNum() - detail.getSendStatus() / detail.getErrCode()); }这里的参数含义有几个需要注意。sendDate只支持YYYYMMDD格式跨天查询要传两次不支持时间范围。查询接口有数据保留期限超过一定天数的记录查不到所以要追溯很久以前的消息必须在发送时把BizId落到业务库里。getSendStatus返回的1、2、3分别对应成功、失败、未知未知状态下需要隔一段时间再查一次。实际业务里用户反馈“没收到验证码”时我第一件事就是拿这个手机号和发送日期查回执。如果运营商返回DELIVRD说明短信到手机端了问题出在用户手机拦截如果返回其他错误码再按码排查。这个排查顺序能省很多时间。回执查询结果建议定期落库按运营商维度统计送达率。比如某运营商送达率骤降很可能是通道问题或用户手机端大批量拦截数据不会说谎。这些统计同时也是后续和短信服务商核对消费的依据。4.3 验证码场景的设计缓存、过期时间和发送频控短信验证码是高并发场景里的典型用例同时也是最容易被人白嫖短信费的地方。你不能让用户无限次请求验证码也不能让验证码在服务端永久有效所以要把发送和校验做成一个闭环。先用伪代码描述一下我当时在项目里的做法// 发送验证码前的两个检查 String key sms:code: phone; if (redis.exists(key)) { return 发送太频繁请稍后再试; // 对应阿里云频控策略同号码1分钟1条 } // 生成6位随机码并缓存5分钟 String code String.format(%06d, ThreadLocalRandom.current().nextInt(1000000)); redis.setex(key, 300, code); // 调阿里云发送接口成功后返回 boolean sent SmsSender.sendCode(phone, code); if (!sent) { redis.del(key); // 发送失败要清掉缓存否则用户要等60秒才能重发 }这套逻辑的要点在两处。第一redis.setex同时设置了5分钟过期时间校验时也从这个key读读不到就提示“验证码已过期”服务端不需要额外记录每一条验证码。第二发送失败时要立刻删除redis里的验证码占位不然用户等一分钟再点“重新发送”明明还没收到验证码却被缓存挡住。校验逻辑同样走缓存// 校验验证码先取出缓存的code再与用户输入比对 String cachedCode redis.get(sms:code: phone); boolean valid cachedCode ! null cachedCode.equals(inputCode); if (valid) { redis.del(sms:code: phone); // 一次性校验用完即焚 }验证码用一次就删是关键否则同一串验证码可以反复校验防不住撞库。也建议把“发送验证码”和“校验验证码”两个接口都加上图形验证码或登录态前置校验防止脚本直接打这两个接口刷短信。图形验证码的成本极低但能挡住绝大多数批量调用。5. 短信发不出去阿里云短信API的五个典型坑位与排查做短信开发网上问得最多的就是“阿里云短信API发不出去”。看代码、看参数、看签名都对但接口返回的code和message总有一个在无情打脸。这一章把我自己踩过和帮别人排查过的五类高频问题按错误码列出来每条按现象、原因、解决的思路写照着对照就能定位。5.1 isv.SMS_SIGNATURE_ILLEGAL签名提示非法现象签名明明在控制台显示“已通过”但调用发送接口时返回这个错误码代码里SignName参数填的字面值和后台一模一样。原因排查下来基本是两类。一是SignName传的不是签名内容而是签名ID或带着“【】”的完整展示名二是从控制台复制签名时悄悄带进了空格或全角符号肉眼看不出来。阿里云对签名的匹配是强一致的多一个空格都算不匹配。解决到控制台打开签名详情把“签名内容”这个字段原样复制粘贴进代码不要手打用代码打印出实际字符串长度和预期长度对一下确保没有隐藏字符。严格来说代码里传的是括号内的纯文本不含“【】”本身。5.2 isv.INVALID_PARAMETERS请求参数中的某个字段格式不对现象返回这个错误码的同时message里会附带具体提示常见的是“The specified value of parameter TemplateParam is not valid”之类但新手往往只看第一行code就没了下文。原因大多数情况是TemplateParam的JSON格式不合法。有人把JSON里的双引号全写成了单引号传进去SDK不负责校验JSON语义服务端解析时就炸了。也有情况是模板变量个数和JSON的key对不上比如模板里有两个变量JSON只传了一个。解决把请求里的TemplateParam原样打印出来丢到任意JSON校验工具里看一眼。确认key和模板定义完全一致确认字符串两端没有多余空格确认是双引号包裹key和value。调试期可以把模板变量精简到一个减少变量组合的出错面。5.3 isv.MOBILE_NUMBER_ILLEGAL手机号格式被服务端拒绝现象手机号是从用户表单直接传上来的看起来是正常的11位数字接口却报手机号非法。原因可能手机号字符串带空格或被格式化成了“138 0013 8000”更隐蔽的是某些输入框允许输入“86 13800138000”服务端没有过滤直接拼到PhoneNumbers参数里。阿里云国内短信接口要求纯数字手机号不能带86或其他国家码。解决在入参校验层先用正则做一次清洗形如^1[3-9][0-9]{9}$把带86的字符串先去掉前缀再过滤中间空格。如果是国际短信要改用对应国际短信产品的接入方式并带上正确的国家码不能指望国内接口自动识别前缀。5.4 isv.BUSINESS_LIMIT_CONTROL触发发送频率限制现象测试阶段一直正常某天开始一批号码频繁报这个错而且不是全部失败是零散地失败。原因阿里云对短信发送有频控策略同一个手机号在1分钟、1小时、1天维度都有条数限制同一个签名也有并发和总量限制。开发时反复拿同几个测试号发消息最容易先触顶。解决两点配合。业务层在发短信前先用Redis计数器做节流同一手机号1分钟内不允许重复发同时在代码里把这个错误码当作可重试但需延时的信号不要无限重试。频控的具体阈值以账号当前权益为准不同等级不一样控制台“发送频率限制”页面能看到实时配置。5.5 模板审核不通过变量与文案设计问题现象模板提交后被拒绝拒绝理由写“含变量过多”或“变量价值不清晰”有的则提示文案里有违规词。原因模板里变量能随便放不代表可以滥用。比如把整句话都做成变量“${url}”平台会判定为无法管控内容文案里出现“测试”“试用”“加群”这些词也会被判为营销或违规。解决模板正文尽量把固定文案写死变量只保留动态变化的最小部分比如验证码数字、产品名。业务上需要发链接时可以把链接放进变量但变量值必须是白名单域名并且模板备注里说明清楚。模板被拒后不要反复提交同一版根据拒绝理由改完再提交审核一般比第一次快。以上五条基本覆盖了“按照文档照抄还发不出去”的主流原因。再补充一个小习惯报错时先看response里的message字段而不是只看code信息量大得多。6. 让短信链路可观测MNS回执订阅、上线自检与限流习惯短信发出去只是起点真正上线后更重要的是“能不能观测”。这一章讲三个我在实战里沉淀下来的做法都不复杂但能把短信功能从“能发”推进到“可控”。6.1 用MNS订阅回执替代频繁轮询之前第4章讲的是主动查询回执适合按需排查。生产环境里更推荐被动接收阿里云支持把短信回执推送到消息服务MNS的队列里业务方监听队列实时拿到每个手机号的最终状态。配置方式是在短信服务控制台的“回执消息”里选择MNS方式建一个队列拿到队列名称和对应的RAM授权即可。代码侧只需要写一个消费者从队列拉消息解析回执JSON里的phone和status字段。相比轮询这种方式延迟低也省掉了定时任务的复杂度。6.2 发送前加一道参数自检做过几次线上事故之后我在短信服务里加了一个自检方法发送前把必填参数全部校验一遍不过关直接抛业务异常不发起网络请求private void validateBeforeSend(String phone, String signName, String templateCode, MapString, String templateParam) { if (!phone.matches(^1[3-9][0-9]{9}$)) { throw new IllegalArgumentException(手机号格式不正确); } if (signName null || signName.trim().length() 0) { throw new IllegalArgumentException(签名不能为空); } if (templateParam null || templateParam.size() 0) { throw new IllegalArgumentException(模板参数不能为空); } // 按模板变量名逐一校验key写死在配置里 }这段逻辑说白了就是提前把第5章的坑挡在门外。参数有问题时错误信息直接显示在我们自己的系统里而不是等阿里云返回一串isv错误码再去翻译。校验规则里模板变量名清单来自数据库配置模板改版时同步更新配置即可。6.3 一个收尾习惯先验证再放量接触短信接口的这几次项目让我养成了一个固定流程。任何一次新接入或模板修改我都会先在测试环境用专用测试号发一条确认返回OK然后去查回执看到运营商标记成功最后再在预发环境用真实模板给白名单手机号发一遍观察自检日志和MNS回执全部通过才放量。短信这种功能一次翻车影响的是所有用户——验证码收不到用户进不了系统投诉立刻就来。这套例子里包含了完整的可运行代码和配置模板下载下来作为起点比从空项目开始搭要快得多。从那以后我每次接短信接口都强制走一遍这个流程也推荐你把它们固化到发布检查清单里。希望帮到你。本文还有配套的精品资源点击获取
