登录验证、订单通知、营销触达,都可能用到短信。把云服务接口直接写进业务方法,开始时省事,后面改模板、处理异常或排查重复发送时,往往要在多个模块里找代码。封装一个阿里云短信发送类,可以把客户端初始化、请求组装和响应检查集中起来,让业务模块只负责决定收件人和短信内容。
本文以 Java 服务为例说明设计方式。阿里云 SDK 的版本、接口字段和控制台配置可能变化,落地时要对照项目实际使用的短信服务文档和 SDK 版本检查。
发送类要负责哪些事
一个实用的发送类,至少要管理访问凭证、组装请求、检查接口响应,并把失败情况交给调用方处理。手机号和模板参数也需要做基础校验;发送频率控制、日志脱敏等工作,则应放在合适的业务或基础设施层统一处理。
可以把短信能力分成配置、发送服务和业务调用三部分:配置层提供地域、签名、模板等信息;发送服务负责调用阿里云 SDK;业务层通过统一接口发送验证码或通知。这样调整模板或替换 SDK 时,不必分别修改用户、订单等业务模块。
先准备短信资源和凭证
编码前,要在阿里云控制台开通短信服务,并完成所需的资质审核。短信发送通常依赖可用的签名和已审核通过的模板,不同用途对签名、模板及变量的要求可能不同。资源没准备好时,代码即使能够发出请求,也可能因为签名或模板配置不匹配而失败。
AccessKey 等凭证应从环境变量、密钥管理服务或项目配置中心注入,不要提交到代码仓库。测试环境和生产环境也要使用各自的配置,避免测试代码调用真实短信资源。日志中不要记录密钥、完整手机号和验证码;排查问题时,保留请求编号、模板类型及脱敏后的号码通常更合适。
阿里云短信发送类示例
下面的示例展示了基本封装:构造对象时初始化客户端,发送方法检查手机号、组装请求并判断响应。配置读取方式可按 Spring Boot、容器环境或团队使用的配置中心调整。
public class AliyunSmsSender {
private final com.aliyun.dysmsapi20170525.Client client;
private final String signName;
public AliyunSmsSender(String accessKeyId,
String accessKeySecret,
String signName) throws Exception {
com.aliyun.teaopenapi.models.Config config =
new com.aliyun.teaopenapi.models.Config()
.setAccessKeyId(accessKeyId)
.setAccessKeySecret(accessKeySecret);
config.endpoint = "dysmsapi.aliyuncs.com";
this.client = new com.aliyun.dysmsapi20170525.Client(config);
this.signName = signName;
}
public void send(String phone, String templateCode,
String templateParam) throws Exception {
if (phone == null || !phone.matches("^1\\\\d{10}$")) {
throw new IllegalArgumentException("手机号格式不正确");
}
com.aliyun.dysmsapi20170525.models.SendSmsRequest request =
new com.aliyun.dysmsapi20170525.models.SendSmsRequest()
.setPhoneNumbers(phone)
.setSignName(signName)
.setTemplateCode(templateCode)
.setTemplateParam(templateParam);
com.aliyun.dysmsapi20170525.models.SendSmsResponse response =
client.sendSms(request);
if (response == null || response.getBody() == null
|| !"OK".equals(response.getBody().getCode())) {
throw new IllegalStateException("短信发送请求未成功");
}
}
}
调用时,模板参数通常以 JSON 字符串传入。例如模板变量名为 code,可以传 {"code":"583921"}。变量名要与模板定义一致,参数值也要符合模板内容和平台规则。不要把未经检查的用户输入直接拼进参数;应校验内容并限制长度。
这段示例省略了具体异常类型、超时设置和详细响应记录。项目使用时,需要根据对应 SDK 版本补齐依赖,并检查响应中的状态码和错误信息。接口返回请求成功,不代表短信已经送达;号码状态、运营商通道等因素仍可能影响最终结果。
登录验证码:处理发送顺序与重试
以电商应用的登录验证码为例,接口收到手机号后,可以先按手机号检查发送间隔和每日上限,再生成验证码、写入缓存并调用发送类。限流条件应结合实际业务设置,也可同时考虑账号和 IP,降低误操作或恶意刷短信的风险。
缓存和发送的先后顺序要提前想清楚。若先发短信再写缓存,缓存写入失败时,用户可能收到一条无法验证的验证码;若先写缓存而短信发送失败,则要删除验证码或将它标记为不可用。可以给验证码设置状态,在发送结果明确后更新,避免验证逻辑把未成功发送的验证码当作有效值。
接口超时也不等于短信一定没发出。此时直接重试,用户可能收到两条验证码。可以为每次发送生成业务请求编号并记录状态,再使用有次数上限的重试策略;同时设置冷却时间,避免故障期间不断重复触发发送。
上线前检查配置、错误和调用方式
- 检查输入:校验手机号、模板参数和必填配置,让格式问题在调用云服务前暴露。
- 限制频率:按账号、手机号或 IP 设置限流规则,并根据验证码场景设置发送间隔和每日上限。
- 区分错误:分别处理配置错误、参数错误、频率限制和网络异常,避免把所有失败都当成同一种问题。
- 保护日志:记录请求编号、模板类型和处理结果,不写入密钥、完整验证码等敏感内容。
- 留出替换空间:业务层依赖统一的短信接口,避免直接依赖具体云厂商的 SDK 类,方便测试和后续迁移。
短信属于外部服务调用,应设置合理的超时时间,避免用户请求线程无限等待。发送量较大时,可以先把任务写入消息队列,再由独立消费者调用发送类;队列方式便于平滑流量、记录处理状态和安排失败重试。小型项目可以先使用简单服务类,等短信场景和发送量增加后,再加入队列、发送记录或厂商适配层。