Java短信API集成实战：Spring Boot对接阿里云短信SDK完整示例

做Java开发这几年，几乎每个项目都会撞上同一个需求：在业务里塞一条短信验证码或通知。短信这个东西，听起来简单，但真要自己从零对接运营商协议、维护通道，那绝对是给自己挖坑。大多数时候我们的正确姿势是接入云厂商提供的短信API，做好签名模板、写好调用代码，剩下的可靠性交给服务商。这篇文章就围绕“java短信API示例代码”这个主题，分享一套我实际用过的、可以快速集成短信发送功能的完整方案，适合Spring Boot项目、需要验证码或通知场景的开发者直接参考。

我不打算堆一堆官方文档式的废话，直接把我的设计思路、代码结构、参数细节和踩过的坑写出来。你照着做，至少能在半天内把“发一条短信”跑通。

1. 项目整体设计与需求拆解

1.1 先分清你的短信使用场景

不要一上来就写代码，先想清楚你的短信功能属于哪一类。不同场景对接口选型、并发要求、合规要求差别很大。

我一般把业务里的短信分成三类：

• 验证码类：注册、登录、找回密码，用户主动触发，对到达时效要求高，一条短信通常1到2秒内要送到。
• 通知类：订单支付成功、审核结果通知，由系统事件触发，允许有一点延迟。
• 营销类：活动通知、优惠券提醒，一般是运营人员手动触发或定时任务触发，这需要用户提前授权，合规要求最严格。

大部分项目最需要的是验证码和通知这两类。营销类短信如果你所在业务没有专门的运营团队，我不建议在项目第一阶段就做，否则签名模板审核都可能卡你很久。

需求和场景定下来之后，再决定使用哪个服务商、选什么模板、怎么设置限流。比如验证码接口一定要做图形验证码和发送频控，否则一天下来你的账户余额会被脚本刷光，这种事我在生产环境见过不止一次。

1.2 技术方案选型：为什么直接接API而不是自建短信通道

有些刚接触短信的开发者会想：“我是不是可以买一个短信猫硬件，插在服务器上发短信？”可以，但只适合极低量级的内部测试场景。短信猫依赖SIM卡，并发特别低，而且通道稳定性很看当地信号，真正生产环境没人这么干。

我的建议是直接接云厂商短信API，像阿里云短信、腾讯云短信都属于这一类。本质上是把短信发送请求通过HTTP/SDK提交到服务商，由服务商调度运营商通道完成下行到达，再通过回调把状态回传给你。这样做有三个好处：

• 通道稳：服务商跟各运营商有专用通道，并发和到达率比自己拼装强太多。
• 运维省：你不需要关心运营商协议、SMPP协议、网关链路健康检查。
• 计费透明：按条计费，控制台能查看发送记录和回执，方便对账。

技术栈方面，我这里直接用Spring Boot 2.7 + JDK 8 + Redis + 阿里云短信SDK。选择这套组合的原因很简单：企业里存量Java项目大部分还是JDK 8，Spring Boot生态成熟，Redis存验证码和频控数据非常好用。

整体调用链路设计成：Controller接收请求，Service处理业务逻辑并组装参数，SDK封装外部通信，Redis负责验证码存储和频控。这样做的核心原因是隔离变化。如果哪一天你想换服务商，只需要重写ServiceImpl，上层的业务代码和Controller完全不用动。

2. 短信服务商选型与API准备

2.1 服务商怎么选，别只看价格

市面上的短信服务商很多，主流的就那么几家。我这些年用得最多的是阿里云短信，也帮朋友调过腾讯云。选型我一般看四个点：

• 官方SDK的维护频率和API文档质量：SDK长期不更新的，多半大家也都在用老接口，问题不好排查。
• 签名模板审核效率：审核慢会直接卡住你的测试流程。
• 控制台的发送记录和回执展示：出了问题能自己查，而不是傻等客服。
• 价格：短信本身很便宜，千万不要为了几分钱的差价牺牲稳定性。

如果只是个人项目或小企业内部系统，阿里云和腾讯云都可以。如果你公司比较大、对账体系复杂，优先看能否走企业版合同和独立客服通道，这部分不是代码问题，但对后续运维影响很大。

2.2 签名和模板审核：最容易被忽视的等待项

调用短信API之前，必须先完成两个前置条件：申请签名和申请模板。

签名就是短信内容开头【】里的内容，比如【某某科技】。签名需要提供证明材料，企业用户用营业执照主体，个人开发者一般只能申请与个人实名认证一致的签名，限制比较严格。

模板就是短信正文，里面允许使用变量，最常见的验证码模板长这样：

您的验证码为${code}，${minutes}分钟内有效。请勿向任何人泄露。

短信模板里的变量，不是随便写的。变量名通常只能用字母、数字和下划线，不能包含中文，而且模板里要有足够的场景说明，方便审核人员判断用途。你写“发送短信”这种模糊模板，大概率会被驳回。

我在项目启动时通常一次性把下面几个模板都申请好：

提醒一下，签名和模板审核通常需要几个小时到一天。如果项目排期紧，一定要在开发前先提交审核，不要等代码写完了才去申请。

2.3 密钥和权限准备

登录云控制台之后，在RAM访问控制里创建一个子账号，千万不要直接用主账号的AccessKey写代码。

子账号只需要授权短信服务的发送权限（SendSms）即可，不需要给它云主机、OSS之类的权限。然后通过控制台创建AccessKey ID和AccessKey Secret。

这两个值是你的凭证。AccessKey Secret一旦泄露，别人就可以拿你的账号发短信，产生费用。所以我习惯的做法是：配置写在环境变量或配置中心里，开发环境用测试Key，生产环境用正式Key，互不交叉。代码仓库里永远不要出现真实的AccessKey Secret。

3. 核心代码实现：从依赖到可运行的示例

3.1 Maven依赖和配置文件

我这里的示例使用阿里云短信SDK的经典方案：aliyun-java-sdk-core+aliyun-java-sdk-dysmsapi。虽然官方后来推出了新版SDK，但老版SDK在存量项目里基数大，资料多，问题也好搜，集成成本最低。

pom.xml里引入依赖：

<dependencies> <dependency> <groupId>com.alibaba</groupId> <artifactId>fastjson</artifactId> <version>1.2.83</version> </dependency> <dependency> <groupId>com.aliyun</groupId> <artifactId>aliyun-java-sdk-core</artifactId> <version>4.6.3</version> </dependency> <dependency> <groupId>com.aliyun</groupId> <artifactId>aliyun-java-sdk-dysmsapi</artifactId> <version>2.2.1</version> </dependency> </dependencies>

如果你不想用fastjson，换成Jackson也可以，但阿里巴巴官方文档里的示例大多用的是fastjson的JSON.toJSONString，我图省事就沿用这个。

application.yml配置如下：

sms: access-key-id: ${SMS_ACCESS_KEY_ID:your-access-key-id} access-key-secret: ${SMS_ACCESS_KEY_SECRET:your-access-key-secret} sign-name: "你的短信签名" template-code: "SMS_123456789" region-id: "cn-hangzhou" endpoint: "dysmsapi.aliyuncs.com"

这里我把密钥用环境变量占位符包了一下，本地环境没有环境变量时才会使用默认值。这样一来，项目在多个环境间切换配置时不会误提交真实的密钥。

然后写一个配置类，把配置项绑定到Java对象：

@Component @ConfigurationProperties(prefix = "sms") public class SmsProperties { private String accessKeyId; private String accessKeySecret; private String signName; private String templateCode; private String regionId; private String endpoint; // getter / setter 省略，项目里有 Lombok 的话直接加 @Data }

如果你项目里不想引入Lombok，手写getter和setter就行，这段代码没有技术含量。

3.2 发送短信的服务封装

接下来是核心。先定义接口SmsService：

public interface SmsService { /** * 发送短信 * * @param mobile 手机号 * @param params 模板变量 * @return 是否发送成功 */ boolean sendSms(String mobile, Map<String, String> params); }

接口的好处是上层业务不关心你用的是阿里云还是腾讯云，想换服务商就换实现类。

实现类代码如下：

@Service @Slf4j public class AliyunSmsServiceImpl implements SmsService { private final SmsProperties smsProperties; public AliyunSmsServiceImpl(SmsProperties smsProperties) { this.smsProperties = smsProperties; } @Override public boolean sendSms(String mobile, Map<String, String> params) { try { DefaultProfile profile = DefaultProfile.getProfile( smsProperties.getRegionId(), smsProperties.getAccessKeyId(), smsProperties.getAccessKeySecret()); IAcsClient client = new DefaultAcsClient(profile); SendSmsRequest request = new SendSmsRequest(); request.setPhoneNumbers(mobile); request.setSignName(smsProperties.getSignName()); request.setTemplateCode(smsProperties.getTemplateCode()); request.setTemplateParam(JSON.toJSONString(params)); SendSmsResponse response = client.getAcsResponse(request); if ("OK".equals(response.getCode())) { log.info("短信发送成功，手机号:{}，requestId:{}", maskMobile(mobile), response.getRequestId()); return true; } log.warn("短信发送失败，手机号:{}，code:{}，message:{}", maskMobile(mobile), response.getCode(), response.getMessage()); return false; } catch (Exception e) { log.error("短信发送异常，手机号:{}", maskMobile(mobile), e); return false; } } private String maskMobile(String mobile) { if (mobile == null || mobile.length() != 11) { return mobile; } return mobile.substring(0, 3) + "****" + mobile.substring(7); } }

这段代码里，SendSmsRequest的setTemplateParam接收的是JSON字符串。也就是说，如果你传入的是Map<String, String>，必须先转成JSON：

{"code":"123456","minutes":"5"}

很多新手写错的地方是直接把Map对象塞进去，或者把value写成数字类型，结果服务商解析不出来。模板变量value必须统一是字符串。

如果你不需要同步等待结果，也可以在接口里加一个异步方法，用@Async标记，配合Spring的ThreadPoolTaskExecutor。但这里我更推荐一个简单方案：调用方根据业务类型自行决定是否异步。一般来说，验证码发送由用户主动触发，你还要在响应里告诉用户“已发送”，所以同步调用没问题，只要把发送耗时控制住即可。

3.3 验证码发送与校验的完整闭环

短信服务封装好之后，我再写一个验证码的完整业务闭环，这是最常见的短信API使用场景。

Controller层提供一个获取验证码接口：

@RestController @RequestMapping("/api/sms") public class SmsController { private final SmsCodeService smsCodeService; public SmsController(SmsCodeService smsCodeService) { this.smsCodeService = smsCodeService; } @PostMapping("/code") public ApiResult sendCode(@RequestBody SmsCodeRequest request) { return smsCodeService.sendCode(request.getMobile()); } }

SmsCodeService负责业务逻辑，完整代码如下：

@Service @Slf4j public class SmsCodeService { private final StringRedisTemplate stringRedisTemplate; private final SmsService smsService; public SmsCodeService(StringRedisTemplate stringRedisTemplate, SmsService smsService) { this.stringRedisTemplate = stringRedisTemplate; this.smsService = smsService; } public ApiResult sendCode(String mobile) { // 1. 校验手机号格式 if (!Pattern.matches("^1\\d{10}$", mobile)) { return ApiResult.error("手机号格式不正确"); } // 2. 60秒内同一个手机号只能发一次 Boolean locked = stringRedisTemplate.opsForValue() .setIfAbsent("sms:limit:" + mobile, "1", Duration.ofSeconds(60)); if (!Boolean.TRUE.equals(locked)) { return ApiResult.error("请求过于频繁，请60秒后重试"); } try { // 3. 生成6位随机验证码 String code = String.format("%06d", new SecureRandom().nextInt(1000000)); // 4. 验证码存Redis，5分钟有效 stringRedisTemplate.opsForValue().set("sms:code:" + mobile, code, Duration.ofMinutes(5)); // 5. 调用短信服务 Map<String, String> params = new HashMap<>(); params.put("code", code); params.put("minutes", "5"); boolean success = smsService.sendSms(mobile, params); if (success) { log.info("验证码发送成功，手机号:{}", mobile); return ApiResult.success("验证码已发送"); } // 发送失败，把频控记录和验证码都删掉，允许用户重试 stringRedisTemplate.delete("sms:limit:" + mobile); stringRedisTemplate.delete("sms:code:" + mobile); return ApiResult.error("发送失败，请稍后重试"); } catch (Exception e) { stringRedisTemplate.delete("sms:limit:" + mobile); stringRedisTemplate.delete("sms:code:" + mobile); log.error("发送验证码异常，手机号:{}", mobile, e); return ApiResult.error("系统异常，请稍后重试"); } } public ApiResult verifyCode(String mobile, String code) { String cachedCode = stringRedisTemplate.opsForValue().get("sms:code:" + mobile); if (cachedCode == null) { return ApiResult.error("验证码已过期，请重新获取"); } if (!cachedCode.equals(code)) { // 记录连续失败次数，防止暴力破解 Long failCount = stringRedisTemplate.opsForValue().increment("sms:fail:" + mobile); stringRedisTemplate.expire("sms:fail:" + mobile, Duration.ofMinutes(5)); if (failCount != null && failCount >= 5) { stringRedisTemplate.delete("sms:code:" + mobile); stringRedisTemplate.delete("sms:fail:" + mobile); return ApiResult.error("错误次数过多，验证码已失效"); } return ApiResult.error("验证码错误"); } stringRedisTemplate.delete("sms:code:" + mobile); stringRedisTemplate.delete("sms:fail:" + mobile); return ApiResult.success("校验通过"); } }

这段代码里有几个非常关键的细节：

• setIfAbsent(key, value, Duration)可以边加锁边设置过期时间，不会出现同一个手机号同一秒内并发发多条的情况。
• 发送失败后要删除频控key，否则用户得白白等60秒。
• 验证码校验失败时用increment计数，达到5次就作废验证码，这个设计能防止脚本不断穷举验证码。

4. 实操过程中必须注意的关键细节

4.1 参数格式和模板变量的坑

短信接口的报错往往都不是网络问题，而是参数问题。

第一个坑是TemplateParam格式。服务商要求这是JSON字符串，而不是JSON对象。你用JSON.toJSONString(params)转出来是字符串，没问题；但如果你在Postman里直接调用HTTP接口，body必须写成{"code":"123456","minutes":"5"}，不能把某个value写成数字。模板里${code}对应的是String。

第二个坑是手机号格式。国内手机号直接传11位数字，不要带+86，不要带空格。如果你有国际化需求，部分服务商支持传86前缀或0086前缀，但这个要提前和服务商确认，不同平台规则不一样。

第三个坑是签名和模板的选择。一个AccessKey下可能有多个签名，一个签名下有多个模板。代码里配置的签名必须和模板归属的签名一致，否则返回isv.SMS_SIGNATURE_ILLEGAL。

第四个坑是模板变量不能多传也不能少传。比如模板里只有${code}，你传了包含code和minutes两个参数的JSON，服务商虽然不会报错，但其中minutes永远不被解析，容易给维护人员造成误解。我在排查线上问题时，就遇到过同事在模板里去掉了一个变量，但Java代码里还是传了三个变量，找了半天才发现是模板变更导致的。

4.2 频控一定要做多层，别指望服务商帮你兜底

服务商侧有频控限制，比如单个手机号每分钟最多1条、每小时最多5条、每天最多10条，不同账号阈值不同。但你的应用如果不做频控，等触发服务商频控返回isv.BUSINESS_LIMIT_CONTROL时，这条短信已经发不出去，对用户来说就是“收不到验证码”。

所以我在应用层做了三层控制：

• IP维度：同一个IP一小时内最多请求多少次验证码，防止单个IP刷接口。
• 手机号维度：60秒只能发一次，每天最多10次，这是刚需。
• 账号维度：如果项目有登录体系，限制未登录状态下的发送次数。

实现频控最偷懒的方式就是用Redis的increment配合expire。比如手机号维度的日配额：

String key = "sms:daily:" + mobile; Long count = stringRedisTemplate.opsForValue().increment(key); if (count != null && count == 1) { stringRedisTemplate.expire(key, Duration.ofDays(1)); } if (count != null && count > 10) { return ApiResult.error("今日短信发送次数已达上限"); }

但这个写法在并发下会有小概率多放一两条进来，因为先increment后判断不是原子操作。更严格的方案是用Lua脚本，把increment和expire和判断count > limit放在一个脚本里执行。对于短信验证码这个场景，我认为上面Redis方法已经足够，除非你的系统对精确性要求极高，否则不要再加分布式锁增加复杂度。

4.3 异步发送、事务和消息不丢失的问题

如果你在用户注册接口里同步发送短信，听起来没什么问题，但用户注册可能还要写数据库、积分、日志等一堆操作。一旦短信接口超时，整个注册请求被阻塞，轻则响应慢，重则用户以为注册失败。所以短信发送应该从主流程里拆出去。

最简单的拆法是在Spring Boot启动类上加@EnableAsync，然后在SmsService增加一个异步方法：

@Async("smsTaskExecutor") @Override public void sendSmsAsync(String mobile, Map<String, String> params) { sendSms(mobile, params); }

线程池最好用Spring的ThreadPoolTaskExecutor，不要直接用Executors.newFixedThreadPool，因为后者线程名称不好排查、拒绝策略也不好定制。参考配置：

@Bean("smsTaskExecutor") public Executor smsTaskExecutor() { ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor(); executor.setCorePoolSize(4); executor.setMaxPoolSize(8); executor.setQueueCapacity(200); executor.setThreadNamePrefix("sms-task-"); executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy()); executor.initialize(); return executor; }

CallerRunsPolicy的意思是，如果线程池满了，新任务会在调用线程里直接执行。这样虽然会阻塞主线程，但至少不会丢消息。

上面这套适合中小规模项目。如果项目里已经有消息队列，我建议走MQ：业务将发送任务写入MQ，消费者从MQ取任务发送。这样即使应用重启，消息还在MQ里，不会丢。

还有一个容易踩坑的点：不要在事务里同步发短信。比如你在一个@Transactional方法里调用了sendSms()，短信发出去了，但事务回滚了，用户收到一条短信，业务状态却还是失败。正确姿势是事务提交之后再发送。Spring里可以用TransactionSynchronizationManager.registerSynchronization：

TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() { @Override public void afterCommit() { smsService.sendSms(mobile, params); } });

4.4 日志、监控和合规习惯

短信是真实世界里的行为，比一般接口更需要注意合规和审计。

日志层面，手机号不要全量打印，我习惯封装一个maskMobile方法，日志里只记录138****1234。但业务表里你要存全量号码，方便客服查单。

监控层面，要关注两个指标：短信发送成功率和短信接口响应时间。如果发送成功率突然掉到90%以下，多半是签名被驳回、账户欠费或者服务商通道异常，需要立刻看控制台。

合规层面，不要采集用户通讯录，不要擅自给用户发营销短信。验证码短信需要在界面明示用途，获得手机号授权。这些虽然不是技术问题，但出了问题比技术故障麻烦得多。

5. 常见问题与排查技巧实录

5.1 高频错误码速查表

我整理了一份短信API接入过程中最常见的错误码，你直接对照处理就可以。

这里我想单独说一下SignatureDoesNotMatch，这个错误很多人第一反应是代码拼错了，其实多半是AccessKey Secret里混进了换行符或空格。你用IDE配置环境变量时，复制粘贴的多余空格也会导致签名不一致，检查时要特别注意。

5.2 线上排查问题的一般步骤

短信没收到，不要一上来就让用户换手机号。我一般按这个顺序排查：

1. 查业务日志，确认sendSms方法有没有被调用，参数是否正常。
2. 如果返回false，看响应里的code和message，对照错误码表处理。
3. 如果调用成功但用户没收到，把requestId记下来，到短信服务商控制台的发送记录里查这条短信的状态。
4. 控制台显示发送成功，但用户手机没收到，可能是被运营商拦截了。先让用户检查拦截短信，再看有没有做过短信退订，最后再联系服务商反馈。

很多人在第3步就卡住了，因为他们没有在代码里打印requestId。所以我在日志里专门把requestId记下来，这个ID是跟服务商沟通的凭证，千万不能省。

5.3 测试环境怎么调才不出乱子

测试环境最怕的一件事：误用生产AccessKey发真实短信，把用户手机炸了。

我默认的测试策略是：

• 测试环境用独立AccessKey，子账号授权范围不要包含生产短信签名。
• 短信模板优先用服务商提供的测试模板，这类模板发送不会产生费用，也不会真的到达手机。
• 如果一定要真实短信联调，只允许填自己的手机号，且单日量控制在一个很小的数。

有一个小技巧：在测试配置里把endpoint替换成本地Mock服务的地址，再配合一个假的SmsService实现，只打印日志不实际调用SDK。这样你可以在不动云资源的情况下把整个业务链路走通。真正联调的时候再切回真实服务商。

6. 从实际项目里沉淀的几点心得

这套短信API集成方案我在几个生产项目里都验证过，稳定性没什么问题。如果要说心得，我觉得最重要的一点是：先把一次简单发送跑通，再考虑花活。很多开发者一上来就设计MQ、回调、双通道容灾，结果最基本的一条验证码都发不出去，签名审核也没过，几天时间全耗在架构搭建上。正确的节奏是先申请签名模板，再写最小代码发通一条短信，最后再扩展异步、频控、多服务商切换这些能力。

另外，如果公司里有多个Java项目都要接短信，我建议把这个封装成公共模块或starter，把签名、模板、AccessKey管理统一收口。否则每个项目自己写一套sendSms，后续改服务商、改模板参数时，你会发现要改的点完全找不到。

最后再分享一个我调接口时的小习惯：每次发短信之前，我会先写个小单元测试调用一次真实的sendSms，但把手机号固定成自己的。这样既能验证AccessKey、签名、模板这一整条链路是否正常，又不会污染线上用户。一条短信几分钱，比调试半天冤枉时间便宜太多了。