Spring Boot 整合阿里云短信SMS对接文档本文档涵盖阿里云侧资质/签名/模板申请流程与后端整合、调用方式。⚠️ 文档中 AccessKey ID / AccessKey Secret 等敏感信息已脱敏真实值请以代码或配置中心为准。一、整体说明项说明云服务阿里云短信服务DysmsapiSDKaliyun-java-sdk-corealiyun-java-sdk-dysmsapiv1 版 SDK核心接口SendSms发送短信接入点cn-hangzhou/dysmsapi.aliyuncs.com工具类com.jxbd.fsgdzc.util.AliyunSms#sendSms发送方式通过status参数映射到不同短信模板模板变量为 JSONcode/orderNo/name调用链路业务代码(Service/Controller/Task) │ MapString,String paramtelNo / status / code / orderNo / name ▼ AliyunSms.sendSms(param, null) │ 1. 按 status 选择模板 ID │ 2. 组装模板变量 JSON │ 3. DefaultAcsClient.getAcsResponse(SendSmsRequest) ▼ 阿里云短信服务 → 运营商 → 用户手机二、阿里云侧开通与申请流程2.1 开通短信服务登录 阿里云控制台完成企业实名认证短信服务面向企业用户为主。搜索「短信服务」并开通免费开通按发送量计费。首次进入「短信服务控制台」会引导完成资质 签名 模板三件套全部审核通过后才能发送。经验值资质审核一般 1~2 个工作日签名/模板审核一般2 小时内工作日被驳回需按驳回原因修改后重新提交。2.2 申请资质短信资质阿里云自 2023 年起要求「先提交资质再申请签名/模板」。进入「短信服务控制台 → 国内消息 → 资质管理 → 新增资质」。选择资质类型企业资质需上传营业执照、法人身份证正反面、经办人身份证非法人办理时需授权书。个人资质仅可申请自用类签名/模板业务范围受限。填写企业名称、统一社会信用代码、归属行业等提交审核。审核通过后资质状态变为「审核通过」方可继续申请签名。材料准备清单企业材料要求营业执照彩色扫描件/照片清晰可辨且在有效期内法人身份证正反面四角完整经办人身份证 授权书仅当经办人非法人时需要行业证明部分行业医疗、金融等需提供对应经营许可2.3 申请签名短信签名是短信开头【】中的内容例如本项目使用的【友医伴健康】。进入「短信服务控制台 → 国内消息 → 签名管理 → 添加签名」。填写签名名称建议 2~12 个字与 App/公众号/网站/营业执照名称相关。签名来源App需提供应用商店链接 应用截图/ 公众号 / 小程序 / 网站 / 企业全称简称。适用场景验证码 / 短信通知 / 推广短信通知类与营销类需分开申请。关联资质选择 2.2 中审核通过的资质。提交后等待审核通过后状态为「审核通过」。记录签名名称配置到代码request.setSignName(...)。注意签名必须与业务主体一致否则易被驳回一个签名可被多个模板复用。2.4 新增模板进入「短信服务控制台 → 国内消息 → 模板管理 → 添加模板」。选择模板类型验证码您的验证码为${code}5分钟内有效。短信通知如订单支付成功、订单指派等。推广短信营销类需单独申请签名。填写模板内容变量使用${变量名}占位例如尊敬的客户您的订单${orderNo}已支付成功我们将尽快为您安排陪诊服务。填写变量说明说明每个变量的含义与示例值。提交审核通过后获得模板 CODE形如SMS_508125195。将模板 CODE 配置到代码的status → templateCode映射中。模板申请注意事项变量个数与顺序必须与代码里templateParam的 key 完全对应本项目为code/orderNo/name。模板中数字变量建议不要放在短信开头避免被运营商判定为垃圾短信。验证码类模板必须包含验证码 有效期说明。同一业务内容不要重复提交多个相似模板会被驳回。2.5 创建 AccessKeyRAM 子账号不要使用主账号 AccessKey建议创建 RAM 用户并授予最小权限。进入「RAM 访问控制 → 用户 → 创建用户」勾选「OpenAPI 调用访问」。创建后保存AccessKey ID与AccessKey SecretSecret 仅创建时展示一次。为该用户授权系统策略AliyunDysmsFullAccess或自定义仅含dysms:SendSms的策略。将 AccessKey 配置到项目中推荐通过配置中心/环境变量注入而非硬编码。2.6 计费与配额按发送条数计费可购买短信套餐包降低成本。默认有流控限制如同一手机号验证码类 1 分钟内 1 条、1 小时内 5 条等可在控制台申请调整。建议在控制台开启「发送量预警」避免异常刷量。三、后端整合3.1 引入依赖server/jxbd-fsgdzc/pom.xml!-- 阿里云 SDK 核心 --dependencygroupIdcom.aliyun/groupIdartifactIdaliyun-java-sdk-core/artifactIdversion3.3.1/version/dependency!-- 阿里云短信 SDK --dependencygroupIdcom.aliyun/groupIdartifactIdaliyun-java-sdk-dysmsapi/artifactIdversion1.0.0/version/dependency3.2 配置项建议改造为可配置当前实现将 AccessKey 与模板 ID硬编码在AliyunSms中不便于多环境切换与密钥轮换。建议改为读取配置# application-dev.ymlaliyun:sms:access-key-id:LTAI****************# RAM 用户 AccessKeyIdaccess-key-secret:************************# RAM 用户 AccessKeySecretregion-id:cn-hangzhouendpoint:dysmsapi.aliyuncs.comsign-name:友医伴健康# 短信签名templates:captcha:SMS_508015266# 0 验证码paid:SMS_508125195# 1 下单支付成功assigned:SMS_508160180# 2 订单指派给陪诊师back:SMS_507950246# 3 订单回退通知管理员canceled:SMS_507930223# 4 订单取消通知管理员和陪诊师remindToday:SMS_508015231# 5 开始陪诊前提前一天通知就诊人auditPass:SMS_508180014# 6 陪诊师资格审核通过通知用户timeoutUser:SMS_509425064# 7 订单超时15分钟通知陪诊师timeoutCustomer:SMS_509740055# 8 订单超时通知客户购买超时服务后续新增模板时只需在配置中增加一项 在映射中注册无需改动业务代码。3.3 工具类源码路径server/jxbd-fsgdzc/src/main/java/com/jxbd/fsgdzc/util/AliyunSms.javaAccessKey 已脱敏packagecom.jxbd.fsgdzc.util;importcom.alibaba.fastjson.JSONObject;importcom.aliyuncs.DefaultAcsClient;importcom.aliyuncs.IAcsClient;importcom.aliyuncs.dysmsapi.model.v20170525.SendSmsRequest;importcom.aliyuncs.dysmsapi.model.v20170525.SendSmsResponse;importcom.aliyuncs.exceptions.ClientException;importcom.aliyuncs.profile.DefaultProfile;importcom.aliyuncs.profile.IClientProfile;importcom.jxbd.common.core.domain.AjaxResult;importorg.slf4j.Logger;importorg.slf4j.LoggerFactory;importjavax.servlet.http.HttpSession;importjava.util.Map;publicclassAliyunSms{privatestaticfinalLoggerlogLoggerFactory.getLogger(AliyunSms.class);staticfinalStringproductDysmsapi;staticfinalStringdomaindysmsapi.aliyuncs.com;staticfinalStringaccessKeyIdLTAI****************;// 已脱敏staticfinalStringaccessKeySecret************************;// 已脱敏publicAliyunSms(){}publicstaticAjaxResultsendSms(MapString,Stringparams,HttpSessionsession)throwsClientException{Stringtel(String)params.get(telNo);Stringcode(String)params.get(code);StringorderNo(String)params.get(orderNo);Stringname(String)params.get(name);System.setProperty(sun.net.client.defaultConnectTimeout,10000);System.setProperty(sun.net.client.defaultReadTimeout,10000);IClientProfileprofileDefaultProfile.getProfile(cn-hangzhou,accessKeyId,accessKeySecret);DefaultProfile.addEndpoint(cn-hangzhou,cn-hangzhou,product,domain);IAcsClientacsClientnewDefaultAcsClient(profile);SendSmsRequestrequestnewSendSmsRequest();request.setPhoneNumbers(tel);request.setSignName(友医伴健康);Stringstatus(String)params.get(status);Stringtemplatenull;if(0.equals(status)){templateSMS_508015266;//验证码}elseif(1.equals(status)){templateSMS_508125195;//下单支付成功}elseif(2.equals(status)){// template SMS_508030056;//订单指派给陪诊师templateSMS_508160180;//订单指派给陪诊师}elseif(3.equals(status)){templateSMS_507950246;//订单回退通知管理员}elseif(4.equals(status)){templateSMS_507930223;//订单取消通知管理员和陪诊师}elseif(5.equals(status)){templateSMS_508015231;//开始陪诊前提前一天通知就诊人}elseif(6.equals(status)){templateSMS_508180014;//陪诊师资格审核通过后通知用户}elseif(7.equals(status)){templateSMS_509425064;//订单超时15分钟通知陪诊师让客户购买延时服务}elseif(8.equals(status)){templateSMS_509740055;//订单超时通知客户购买超时服务}request.setTemplateCode(template);log.info(模板id为template);JSONObjectobjnewJSONObject();obj.put(code,code);obj.put(orderNo,orderNo);obj.put(name,name);request.setTemplateParam(obj.toJSONString());try{SendSmsResponsesendSmsResponse(SendSmsResponse)acsClient.getAcsResponse(request);log.info(短信接口返回的数据--------start--------);log.info(CodesendSmsResponse.getCode());log.info(MessagesendSmsResponse.getMessage());log.info(RequestIdsendSmsResponse.getRequestId());log.info(BizIdsendSmsResponse.getBizId());log.info(短信接口返回的数据-------- end --------);}catch(ClientExceptionvar14){log.error(var14.getMessage());var14.printStackTrace();}returnAjaxResult.success();}}3.4 调用示例以「订单指派给陪诊师后发送通知」为例这里最好改成异步执行防止阻塞主流程影响性能与用户体验并且在阿里云短信控制台设置流控限制// 发送短信 TODOSysUsersysUsersysUserService.selectUserById(assignUserId);MapString,StringparamnewHashMap();param.put(telNo,sysUser.getPhonenumber());// param.put(name, sysUser.getNickName());param.put(orderNo,tOrder.getOrderNo());//指派订单模板param.put(status,2);//调用阿里云发送短信try{AliyunSms.sendSms(param,null);}catch(ClientExceptione){log.error(发送短信出错:e.getMessage());e.printStackTrace();}参数约定key是否必填说明telNo必填接收手机号多个号码用英文逗号分隔单次最多 1000 个status必填业务场景编码决定使用哪个模板见 4.1code场景相关验证码仅status0使用orderNo场景相关订单号name场景相关姓名当前部分场景已注释只有当前模板里声明过的变量才会生效工具类固定提交code/orderNo/name三个变量多余变量不影响发送缺失变量会导致发送失败。四、模板对照与调用点4.1status→ 模板对照表status模板 CODE用途使用的变量0SMS_508015266验证码code1SMS_508125195下单支付成功orderNo2SMS_508160180订单指派给陪诊师orderNo3SMS_507950246订单回退通知管理员orderNo4SMS_507930223订单取消通知管理员和陪诊师orderNo5SMS_508015231开始陪诊前提前一天通知就诊人orderNo6SMS_508180014陪诊师资格审核通过后通知用户name7SMS_509425064订单超时 15 分钟通知陪诊师orderNo8SMS_509740055订单超时通知客户购买超时服务orderNo历史模板SMS_508030056订单指派已废弃改用SMS_508160180。4.2 调用点清单场景status位置小程序登录验证码0service/impl/IJxMpWxServiceImpl.java订单支付成功1wxpay/service/WxPayServiceImpl.java微信支付回调成功后订单指派 / 回退2/3service/impl/TOrderServiceImpl.java订单取消4service/impl/TOrderServiceImpl.java陪诊前一日提醒5service/impl/TOrderServiceImpl.java陪诊师资格审核通过6controller/TMedicalApplicationController.java订单超时通知陪诊师7service/impl/TOrderServiceImpl.java定时任务订单超时通知客户8service/impl/TOrderServiceImpl.java定时任务五、常见错误码返回 Code说明处理建议OK发送成功—isv.SMS_SIGNATURE_ILLEGAL签名不合法 / 未审核通过检查SignName与签名状态isv.SMS_TEMPLATE_ILLEGAL模板不合法 / 未审核通过检查模板 CODE 与状态isv.MOBILE_NUMBER_ILLEGAL手机号格式错误校验手机号isv.AMOUNT_NOT_ENOUGH账户余额不足充值 / 购买套餐包isv.BUSINESS_LIMIT_CONTROL触发流控降低频率或申请提额isv.OUT_OF_SERVICE业务停机欠费检查账户状态isv.PARAM_LENGTH_LIMIT/isv.INVALID_PARAMETERS参数不合法如变量缺失/超长核对模板变量SignatureDoesNotMatchAccessKey 错误检查 AK/SK 配置排查时优先查看日志中的Code与Message并在控制台「发送记录」中核对实际下发结果。