短信配置

本章节，介绍项目的短信功能。该功能提供统一的短信 API 给其它模块，使它们可以快速接入短信功能，无需关心不同短信平台的具体对接。
短信采用异步发送，基于 Redis 消息队列，如下图所示：

• ykkj-spring-boot-starter-biz-sms业务组件：封装不同短信平台的客户端。

• ykkj-module-system 的 module/system/service/sms/业务模块，提供短信渠道、模板的配置，短信日志的查看，短信的发送等功能。

  1. 短信配置

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

• 新建一个短信【渠道】，配置对应短信平台的账号

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

1.1 新建短信渠道

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

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

短信 API 的账号: 696b5d8ead48071237e4aa5861ff08dbadb2b4ded1c688a7b7c9afc615579859 短信 API 的密钥: SEC5c4e5ff888bc8a9923ae47f59e7ccd30af1f14d93c55b4e2c9cb094e35aeed67
疑问 1：为什么选择渠道编码为【调试（钉钉）】？
该类型使用钉钉机器人来模拟短信发送，用于日常调试。

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

上图使用的配置，是艿艿自己的钉钉机器人。正式使用时，必须参考 《钉钉开放平台 —— 自定义机器人接入 》文档，申请自己的专属机器人。
疑问 2：可以选择其它渠道编码吗？
当然可以，这里主要考虑部分同学暂时没有申请短信平台，所以使用【调试（钉钉）】渠道编码。

1.2 新建短信模板

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

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

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

疑问：为什么设计短信模板的功能？
在一些场景下，需要修改短信模板所使用的短信平台。例如说：短信平台出现故障，或者切换短信平台等等。
此时，只需要修改短信模板的两个属性：短信渠道编号、短信 API 模板编号，无需重启应用。

1.3 查看短信日志

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


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

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

2. 短信发送

2.1 SmsSendApi

使用 module/system/api/sms/SmsSendApi.java进行短信的发送，支持多种用户类型。它的方法如下：

2.2 实战案例

以工作流申请通过时，发送短信为例子，讲解 SmsSendApi 的使用。
① 引入 ykkj-module-system-api 依赖，如下图所示：

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

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

3. 验证码发送

3.1 SmsCodeApi

使用 module/system/api/sms/SmsCodeApi.java进行【验证码】短信的发送，例如说：用户手机验证码登录、用户忘记密码等等。它的方法如下：

验证码使用 module/system/dal/dataobject/sms/SmsCodeDO.java表进行存储，默认每天最多发送 10 条，每分钟发送 1 条，有效期为 10 分钟，可通过 ykkj.sms-code 配置项进行自定义：

3.2 实战案例

以会员用户手机验证码登录为例子，讲解 SmsCodeApi 的使用。
① 引入 ykkj-module-system-api 依赖，如下图所示：

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

③ 在 /module/system/enums/sms/SmsSceneEnum.java中，枚举会员用户的手机号登录的场景，如下图所示：

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

4. 短信客户端

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

4.1 SmsClient

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

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

4.2 SmsCodeMapping

framework/sms/core/client/SmsCodeMapping.java接口，定义短信平台错误码转换成 标准错误码-framework/sms/core/enums/SmsFrameworkErrorCodeConstants.java的方法。代码如下：

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

4.3 对接其它短信平台

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

5. 短信平台附录

一般情况下，建议接入 2-3 个短信平台，避免某个短信平台故障时，影响业务的正常运行。
例如说，手机验证码的短信平台 A 故障时，赶紧将短信验证码切换到短信平台 B 上，否则用户将无法正常登录或是注册。

5.1 云片

• 短信 API 的账号，可通过 云片 —— 子账号管理获取。【无需密钥】
• 短信发送回调 URL，可通过 云片 —— 数据推送与获取配置。

友情提示：
之前的公司，主要采用【云片】短信渠道，体验非常不错。

5.2 阿里云

• 短信 API 的账号、密钥，可通过 阿里云 —— AccessKey获取。

• 短信发送回调 URL，可通过 阿里云 —— 短信服务 —— 通用设置配置。

  5.3 腾讯云

• 短信 API 的账号、密钥，可通过 腾讯云 —— API 密钥管理获取。注意！！！腾讯云需要额外使用 SDKAppID参数，它的账号需要采用 SDKAppID secretId 格式，具体可见 TencentSmsChannelProperties类。

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