短信配置

友情提示：

该功能依赖“消息队列”，需要参考 《消息队列》 文档进行开启消息队列。

本章节，介绍项目的短信功能。该功能提供统一的短信 API 给其它模块，使它们可以快速接入短信功能，无需关心不同短信平台的具体对接。

短信采用异步发送，基于 Redis 消息队列，如下图所示：

整体流程

• yudao-spring-boot-starter-biz-sms (opens new window)业务组件：封装不同短信平台的客户端。
• yudao-module-system 的 sms (opens new window)业务模块，提供短信渠道、模板的配置，短信日志的查看，短信的发送等功能。

#1. 表结构

表结构

#2. 短信配置

本小节，讲解如何配置短信功能，整个过程如下：

• 新建一个短信【渠道】，配置对应短信平台的账号
• 新建一个短信【模版】，配置对应短信平台的模板
• 测试该短信模板，查看对应的短信【日志】，确认是否发送成功

#2.1 新建短信渠道

① 点击 [系统管理 -> 短信管理 -> 短信渠道] 菜单，查看短信渠道的列表。如下图所示：

短信渠道的列表

② 点击 [新增] 按钮，选择渠道编码为【调试（钉钉）】，并填写信息如下图：

短信渠道的新增

短信 API 的账号: 696b5d8ead48071237e4aa5861ff08dbadb2b4ded1c688a7b7c9afc615579859
短信 API 的密钥: SEC5c4e5ff888bc8a9923ae47f59e7ccd30af1f14d93c55b4e2c9cb094e35aeed67

疑问 1：为什么选择渠道编码为【调试（钉钉）】？

该类型使用钉钉机器人来模拟短信发送，用于日常调试。

• 短信 API 的账号，对应机器人的 Webhook 的 access_token 参数
• 短信 API 的密钥，对应机器人的安全设置的加签

上图使用的配置，是艿艿自己的钉钉机器人。正式使用时，必须参考 《钉钉开放平台 —— 自定义机器人接入 》 (opens new window)文档，申请自己的专属机器人。

疑问 2：可以选择其它渠道编码吗？

当然可以，这里主要考虑部分同学暂时没有申请短信平台，所以使用【调试（钉钉）】渠道编码。

不同短信平台的配置，可见 「6. 短信平台附录」 小节。

#2.2 新建短信模板

① 点击 [系统管理 -> 短信管理 -> 短信模板] 菜单，查看短信模板的列表。如下图所示：

短信模板的新增

② 点击 [新增] 按钮，选择刚创建的短信渠道，并填写信息如下图：

短信模板的新增

• 短信渠道编号：发送该短信模板时，使用的短信渠道，即使用哪个短信平台进行发送
• 模板编号：短信模板的唯一标识，使用短信 API 时，通过它标识使用的短信模板
• 模板内容：短信模板的内容，使用 {var} 作为占位符，例如说 {name}、{code} 等
• 短信 API 模板编号：短信平台的短信模板的编号，需要保证该模板在短信平台已经审核通过
• 开启状态：短信模板被禁用时，该短信模板将不发送短信，只记录短信日志

疑问：为什么设计短信模板的功能？

在一些场景下，需要修改短信模板所使用的短信平台。例如说：短信平台出现故障，或者切换短信平台等等。

此时，只需要修改短信模板的两个属性：短信渠道编号、短信 API 模板编号，无需重启应用。

#2.3 查看短信日志

① 使用钉钉，扫码 图片 加入机器人所在的【ruoyi-vue-pro 短信测试群】，查看测试短信的模拟发送。

② 点击 [测试] 按钮，输入任一手机号，进行该短信模板的模拟发送。如下图所示：

测试短信模板

测试短信模板

友情提示：如果使用的短信渠道是阿里云、腾讯云等正式的短信平台，则会发送到填写的手机号中。例如说：

接收示例

③ 点击 [系统管理 -> 短信管理 -> 短信日志] 采单，可以查看到每条短信的发送状态、接收状态。如下图所示：

短信日志

#3. 短信发送

#3.1 SmsSendApi

使用 SmsSendApi (opens new window)进行短信的发送，支持多种用户类型。它的方法如下：

短信发送

#3.2 实战案例

以工作流申请通过时，发送短信为例子，讲解 SmsSendApi 的使用。

① 引入 yudao-module-system-api 依赖，如下图所示：

依赖

② 新建对应的短信模板，如下图所示：

新建短信模板

③ 使用 Spring 注入 SmsSendApi Bean，调用对应的短信发送方法。如下图所示：

调用 SmsSendApi 方法

#4. 验证码发送

#4.1 SmsCodeApi

使用 SmsCodeApi (opens new window)进行【验证码】短信的发送，例如说：用户手机验证码登录、用户忘记密码等等。它的方法如下：

短信发送

验证码使用 system_sms_code (opens new window)表进行存储，默认每天最多发送 10 条，每分钟发送 1 条，有效期为 10 分钟，可通过 yudao.sms-code 配置项进行自定义：

配置项

#4.2 实战案例

以会员用户手机验证码登录为例子，讲解 SmsCodeApi 的使用。

① 引入 yudao-module-system-api 依赖，如下图所示：

依赖

② 新建对应的短信模板，如下图所示：

新建短信模板

③ 在 SmsSceneEnum (opens new window)中，枚举会员用户的手机号登录的场景，如下图所示：

SmsSceneEnum 枚举

④ 使用 Spring 注入 SmsCodeApi Bean，调用对应的短信验证码的发送与使用方法。如下图所示：

调用 SmsCodeApi 方法

#5. 短信客户端

yudao-spring-boot-starter-biz-sms (opens new window)业务组件，对接阿里云、腾讯云等短信平台，提供统一的短信客户端，提供给 yudao-module-system 的 sms (opens new window)业务模块来调用。

#5.1 SmsClient

SmsClient (opens new window)接口，定义短信客户端的方法。代码如下：

SmsClient 接口

每个短信平台，都对应一个 SmsClient 实现类。

SmsClient 实现

#5.2 SmsCodeMapping

SmsCodeMapping (opens new window)接口，定义短信平台错误码转换成 标准错误码 (opens new window)的方法。代码如下：

SmsClient 接口

每个短信平台，都对应一个 SmsCodeMapping 实现类。

SmsClient 实现

#5.3 对接其它短信平台

如果你想要对接其它短信平台，自定义一个 SmsClient + SmsCodeMapping 实现类，并使用 SmsClientFactoryImpl (opens new window)进行创建。代码如下：

SmsClientFactoryImpl 创建客户端

#6. 短信平台附录

一般情况下，建议接入 2-3 个短信平台，避免某个短信平台故障时，影响业务的正常运行。

例如说，手机验证码的短信平台 A 故障时，赶紧将短信验证码切换到短信平台 B 上，否则用户将无法正常登录或是注册。

#6.1 阿里云

• 短信 API 的账号、密钥，可通过 阿里云 —— AccessKey (opens new window)获取。
• 短信发送回调 URL，可通过 阿里云 —— 短信服务 —— 通用设置 (opens new window)配置。

#6.2 腾讯云

• 短信 API 的账号、密钥，可通过 腾讯云 —— API 密钥管理 (opens new window)获取。

  注意！！！

  腾讯云需要额外使用 SDKAppID (opens new window)参数，它的账号需要采用 SDKAppID secretId 格式，具体可见 TencentSmsChannelProperties (opens new window)类。

• 短信发送回调 URL，可通过 腾讯云 —— 短信 —— 基础配置 (opens new window)配置。

上次更新: 2023/07/29, 15:56:49