接入短信服务时,调用接口的代码通常不难写,容易卡住的反而是签名、模板、权限和参数配置。下面以 Java 为例,按准备、发送和业务接入三个环节说明阿里云短信服务代码的基本写法,并用注册验证码场景讲清楚代码应该放在哪里。示例用于入门,具体依赖和调用方式请按项目使用的 SDK 版本及控制台配置核对。
调用前先准备配置
先在阿里云控制台开通短信服务,并准备好发送所需的信息。测试之前,最好确认签名和模板都已审核通过,否则代码参数正确也可能无法正常发送。
- AccessKey:供程序访问云服务。建议为应用创建 RAM 用户,并仅授予发送短信所需的权限;不要直接把主账号密钥用于程序。
- 短信签名:短信中显示的发送方名称,需要先提交审核。代码中的签名名称要与控制台配置一致。
- 短信模板:短信正文使用已审核通过的模板,发送时传入对应的模板编码。
- 接收号码:测试号码应符合短信服务要求。上线后还要对号码、账号或 IP 设置发送频率限制。
模板变量也要一一对应。例如模板内容为“您的验证码为${code},请勿泄露给他人”,传参时使用的变量名就应是 code。变量名称写错、模板尚未审核,或签名与模板配置不匹配,都可能造成发送失败。遇到问题时,可以先逐项核对这些控制台配置,再查代码。
Java 示例:调用 SendSms 发送短信
下面示例采用阿里云 Java SDK 中常见的 CommonRequest 调用方式。项目需要引入阿里云核心 SDK 依赖;使用 Maven 时,可根据阿里云官方 SDK 文档确认当前推荐版本,再加入 pom.xml。SDK 不同版本的依赖名称和调用细节可能有差异,实际项目应以对应版本的官方示例为准。
将签名名称、模板编码和手机号替换成自己的配置后,可以按下面的方式组装请求:
DefaultProfile profile = DefaultProfile.getProfile(“cn-hangzhou”, accessKeyId, accessKeySecret);
IAcsClient client = new DefaultAcsClient(profile);
CommonRequest request = new CommonRequest();
request.setSysMethod(MethodType.POST);
request.setSysDomain(“dysmsapi.aliyuncs.com”);
request.setSysVersion(“2017-05-25”);
request.setSysAction(“SendSms”);
request.putQueryParameter(“RegionId”, “cn-hangzhou”);
request.putQueryParameter(“PhoneNumbers”, “13800000000”);
request.putQueryParameter(“SignName”, “你的短信签名”);
request.putQueryParameter(“TemplateCode”, “你的模板编码”);
request.putQueryParameter(“TemplateParam”, “{\”code\”:\”482913\”}”);
CommonResponse response = client.getCommonResponse(request);
System.out.println(response.getData());
请求中需要指定 SendSms,并传入接收号码、短信签名、模板编码和模板变量。示例里的验证码是固定值,只适合验证接口链路;接入业务时,应由后端生成实际验证码,再填入模板参数。
收到接口响应后,不要只判断程序有没有抛出异常。网络请求完成,并不等于短信已经成功提交;还需要解析返回内容中的状态和业务信息,并保留必要的排查记录。RegionId、客户端地域配置、接口域名和版本号应按官方文档及项目配置填写,SDK 更新后也要重新核对。正式上线前,先在测试环境跑通完整流程。
注册验证码场景怎么接入
以电商网站注册为例,用户提交手机号后,后端先校验号码格式,再生成随机验证码,同时记录验证码、过期时间和发送状态。确认可以发送后,后端调用短信发送方法,把验证码放入模板参数。用户提交验证码并通过校验后,后端应立即作废它,避免再次使用。
前端不应直接调用阿里云短信接口。若把 AccessKey 放进浏览器或小程序代码,密钥可能被提取并滥用。更稳妥的做法是让前端请求自己的业务后端,由后端负责号码校验、频率控制、调用短信接口和记录结果。
频率限制也要放在业务流程里考虑。例如,可以限制同一手机号在短时间内的申请次数,并同时检查同一账号或 IP 的请求频率。验证码设置较短有效期,并限制连续输错次数。这样做不能替代接口配置检查,但能减少短信被反复申请或验证码被滥用的风险。
接入时容易忽略的问题
不要把密钥写进源码
AccessKey 不要明文提交到代码仓库,也不要打印到日志。可通过环境变量、密钥管理服务或受控配置中心提供凭证。若发现密钥已经泄露,应及时轮换。
检查模板参数格式
模板参数通常以 JSON 字符串传入,变量名必须与模板占位符一致。引号、中文和特殊字符也要正确转义。建议先用固定测试值验证参数格式,再接入动态验证码,排查时更容易分清是模板配置问题还是业务数据问题。
处理返回结果和异常
网络超时、权限不足以及签名或模板状态异常,都可能影响发送。代码应记录必要的请求标识和错误信息,便于排查,但不要记录密钥或完整验证码。遇到可重试错误时设置合理的重试条件,不要无条件重复发送,以免用户收到多条短信。
根据业务量选择调用方式
如果在页面请求中同步调用短信接口,接口响应时间会影响用户等待时间。业务量较大时,可以把发送任务放入消息队列,由后台消费者调用接口,并处理幂等和失败告警。简单项目可以先同步调用,但仍应设置超时,并对发送失败给出明确的业务处理。
上线前逐项核对
- 短信服务已开通,RAM 权限只覆盖应用需要的操作。
- 签名和模板已审核通过,模板变量名与传入参数一致。
- 测试环境验证过正常号码、错误号码和错误模板等情况。
- 已对手机号、账号或 IP 设置频率限制,并限制验证码有效期和输错次数。
- 日志保留必要的请求结果和排查信息,不记录密钥或完整验证码。
阿里云短信服务代码可以先从一条测试短信开始:确认权限、签名、模板和参数都能对应上,再封装成项目里的短信发送服务。上线前补齐超时、异常处理、频率限制和日志记录,后续排查会省事得多,也能降低密钥暴露和短信重复发送的风险。