239 lines
6.1 KiB
Markdown
239 lines
6.1 KiB
Markdown
# 短信服务迁移说明 - 从阿里云SMS到腾讯云SMS
|
||
|
||
## 迁移概述
|
||
将短信服务从阿里云SMS迁移到腾讯云SMS，保持原有功能不变。
|
||
|
||
## 1. 代码变更
|
||
|
||
### 1.1 SmsServiceImpl.java
|
||
**位置**：`src/main/java/com/xy/xyaicpzs/service/impl/SmsServiceImpl.java`
|
||
|
||
**主要变更**：
|
||
- 移除阿里云SDK依赖（`com.aliyun.dysmsapi20170525`）
|
||
- 引入腾讯云SDK（`com.tencentcloudapi.sms.v20210111`）
|
||
- 修改客户端创建方式
|
||
- 修改短信发送请求构建方式
|
||
- 手机号格式改为E.164标准（+86前缀）
|
||
|
||
**关键代码**：
|
||
```java
|
||
// 创建腾讯云短信客户端
|
||
private SmsClient createSmsClient() {
|
||
Credential cred = new Credential(secretId, secretKey);
|
||
return new SmsClient(cred, region);
|
||
}
|
||
|
||
// 发送短信
|
||
SendSmsRequest req = new SendSmsRequest();
|
||
req.setSmsSdkAppId(sdkAppId);
|
||
req.setSignName(signName);
|
||
req.setTemplateId(templateId);
|
||
req.setTemplateParamSet(new String[]{verificationCode});
|
||
req.setPhoneNumberSet(new String[]{"+86" + phoneNumber});
|
||
```
|
||
|
||
### 1.2 配置文件更新
|
||
**位置**：`src/main/resources/application.yml`
|
||
|
||
**旧配置（阿里云）**：
|
||
```yaml
|
||
aliyun:
|
||
sms:
|
||
sign-name: 西安精彩数据服务社
|
||
template-code: SMS_489840017
|
||
access-key-id: LTAI5tR18rXPYazi3y8kAuep
|
||
access-key-secret: KZ1aKZOupilVc332SXE1g1DfKsqHPu
|
||
```
|
||
|
||
**新配置（腾讯云）**：
|
||
```yaml
|
||
tencent:
|
||
sms:
|
||
secret-id: ${TENCENT_SMS_SECRET_ID:your-secret-id}
|
||
secret-key: ${TENCENT_SMS_SECRET_KEY:your-secret-key}
|
||
sdk-app-id: 1401068120
|
||
template-id: 2598660
|
||
sign-name: 西安溢彩数智科技有限公司
|
||
region: ap-guangzhou
|
||
```
|
||
|
||
## 2. 配置说明
|
||
|
||
### 2.1 必需配置项
|
||
| 配置项 | 说明 | 示例值 |
|
||
|--------|------|--------|
|
||
| secret-id | 腾讯云SecretId | 从腾讯云控制台获取 |
|
||
| secret-key | 腾讯云SecretKey | 从腾讯云控制台获取 |
|
||
| sdk-app-id | 短信应用ID | 1401068120 |
|
||
| template-id | 短信模板ID | 2598660 |
|
||
| sign-name | 短信签名 | 西安溢彩数智科技有限公司 |
|
||
| region | 地域 | ap-guangzhou（默认） |
|
||
|
||
### 2.2 环境变量配置（推荐）
|
||
为了安全，建议使用环境变量配置敏感信息：
|
||
|
||
**Linux/Mac**：
|
||
```bash
|
||
export TENCENT_SMS_SECRET_ID=your-secret-id
|
||
export TENCENT_SMS_SECRET_KEY=your-secret-key
|
||
```
|
||
|
||
**Windows**：
|
||
```cmd
|
||
set TENCENT_SMS_SECRET_ID=your-secret-id
|
||
set TENCENT_SMS_SECRET_KEY=your-secret-key
|
||
```
|
||
|
||
或者直接在 `application.yml` 中替换默认值。
|
||
|
||
## 3. Maven依赖
|
||
|
||
确保 `pom.xml` 中已添加腾讯云SMS SDK依赖：
|
||
|
||
```xml
|
||
<!-- 腾讯云SMS SDK -->
|
||
<dependency>
|
||
<groupId>com.tencentcloudapi</groupId>
|
||
<artifactId>tencentcloud-sdk-java-sms</artifactId>
|
||
<version>3.1.xxx</version>
|
||
</dependency>
|
||
```
|
||
|
||
**注意**：可以移除阿里云SMS相关依赖：
|
||
```xml
|
||
<!-- 可以删除 -->
|
||
<dependency>
|
||
<groupId>com.aliyun</groupId>
|
||
<artifactId>dysmsapi20170525</artifactId>
|
||
<version>xxx</version>
|
||
</dependency>
|
||
```
|
||
|
||
## 4. 功能保持不变
|
||
|
||
### 4.1 验证码生成
|
||
- 仍然生成6位随机数字验证码
|
||
- 验证码有效期：5分钟
|
||
|
||
### 4.2 发送限制
|
||
- 每个手机号每天最多发送10次
|
||
- 使用Redis存储发送次数和验证码
|
||
|
||
### 4.3 API接口
|
||
- 接口路径不变：`POST /api/sms/sendCode`
|
||
- 请求参数不变：`phoneNumber`
|
||
- 响应格式不变
|
||
|
||
## 5. 腾讯云SMS模板要求
|
||
|
||
### 5.1 模板格式
|
||
根据模板ID `2598660`，模板内容应该类似：
|
||
```
|
||
您的验证码是{1}，请在5分钟内完成验证。
|
||
```
|
||
|
||
### 5.2 模板参数
|
||
代码中传递的参数：
|
||
```java
|
||
String[] templateParamSet = {verificationCode};
|
||
```
|
||
|
||
**注意**：腾讯云模板参数是数组形式，按顺序对应模板中的 `{1}`, `{2}` 等占位符。
|
||
|
||
## 6. 手机号格式
|
||
|
||
### 6.1 阿里云格式
|
||
```
|
||
13868246742 // 直接11位手机号
|
||
```
|
||
|
||
### 6.2 腾讯云格式（E.164标准）
|
||
```
|
||
+8613868246742 // 需要加 +86 前缀
|
||
```
|
||
|
||
代码中已自动处理：
|
||
```java
|
||
String[] phoneNumberSet = {"+86" + phoneNumber};
|
||
```
|
||
|
||
## 7. 错误处理
|
||
|
||
### 7.1 发送成功判断
|
||
腾讯云返回的状态码为 `"Ok"` 表示成功：
|
||
```java
|
||
if ("Ok".equals(code)) {
|
||
// 发送成功
|
||
}
|
||
```
|
||
|
||
### 7.2 常见错误码
|
||
| 错误码 | 说明 | 处理方式 |
|
||
|--------|------|---------|
|
||
| FailedOperation.ContainSensitiveWord | 内容包含敏感词 | 检查模板内容 |
|
||
| FailedOperation.SignatureIncorrectOrUnapproved | 签名未审核或不正确 | 检查签名配置 |
|
||
| LimitExceeded.PhoneNumberDailyLimit | 手机号日发送量超限 | 已在代码中限制 |
|
||
| InvalidParameterValue.TemplateParameterFormatError | 模板参数格式错误 | 检查参数数组 |
|
||
|
||
## 8. 测试建议
|
||
|
||
### 8.1 单元测试
|
||
1. 测试验证码生成
|
||
2. 测试发送次数限制
|
||
3. 测试验证码验证
|
||
|
||
### 8.2 集成测试
|
||
1. 发送验证码到真实手机号
|
||
2. 验证短信内容格式
|
||
3. 验证验证码有效期
|
||
4. 验证每日发送次数限制
|
||
|
||
### 8.3 测试命令
|
||
```bash
|
||
curl -X POST http://localhost:8123/api/sms/sendCode \
|
||
-H "Content-Type: application/x-www-form-urlencoded" \
|
||
-d "phoneNumber=13868246742"
|
||
```
|
||
|
||
## 9. 注意事项
|
||
|
||
1. **配置敏感信息**：
|
||
- 不要将 `secret-id` 和 `secret-key` 提交到代码仓库
|
||
- 使用环境变量或配置中心管理
|
||
|
||
2. **模板审核**：
|
||
- 确保腾讯云控制台中模板ID `2598660` 已审核通过
|
||
- 确保签名"西安溢彩数智科技有限公司"已审核通过
|
||
|
||
3. **地域选择**：
|
||
- 默认使用 `ap-guangzhou`（广州）
|
||
- 可根据实际情况修改为其他地域
|
||
|
||
4. **费用**：
|
||
- 腾讯云SMS按条计费
|
||
- 建议在控制台设置费用告警
|
||
|
||
## 10. 回滚方案
|
||
|
||
如果需要回滚到阿里云SMS：
|
||
|
||
1. 恢复 `SmsServiceImpl.java` 的旧版本
|
||
2. 恢复 `application.yml` 中的阿里云配置
|
||
3. 确保阿里云SDK依赖存在
|
||
4. 重启应用
|
||
|
||
## 11. 完成状态
|
||
|
||
✅ 代码迁移完成
|
||
✅ 配置文件更新
|
||
✅ 编译检查通过
|
||
✅ 功能保持不变
|
||
|
||
**迁移已完成，可以部署使用！**
|
||
|
||
## 12. 相关文档
|
||
|
||
- [腾讯云SMS SDK文档](https://cloud.tencent.com/document/product/382/43199)
|
||
- [腾讯云SMS API文档](https://cloud.tencent.com/document/api/382/52071)
|
||
- [腾讯云SMS控制台](https://console.cloud.tencent.com/smsv2)
|