241 lines
6.1 KiB
Markdown
241 lines
6.1 KiB
Markdown
# 邮件发送测试说明
|
||
|
||
## 📧 功能概述
|
||
|
||
项目已集成邮件发送功能，支持：
|
||
- 简单文本邮件
|
||
- HTML格式邮件
|
||
- 验证码邮件（带精美HTML模板）
|
||
|
||
## 🔧 配置步骤
|
||
|
||
### 1. 邮箱配置
|
||
|
||
在 `src/main/resources/application.properties` 中配置邮件服务器信息：
|
||
|
||
```properties
|
||
# 邮件配置
|
||
spring.mail.host=smtp.chengmail.cn # SMTP服务器地址
|
||
spring.mail.port=465 # SMTP端口
|
||
spring.mail.username=dev@corewing.com # 发件人邮箱
|
||
spring.mail.password=HRTmmNrBRjSxfwAk # 邮箱授权码
|
||
spring.mail.default-encoding=UTF-8
|
||
spring.mail.properties.mail.smtp.auth=true
|
||
spring.mail.properties.mail.smtp.starttls.enable=true
|
||
spring.mail.properties.mail.smtp.starttls.required=true
|
||
spring.mail.properties.mail.smtp.ssl.enable=false
|
||
```
|
||
|
||
### 2. 常用邮箱SMTP配置
|
||
|
||
#### QQ邮箱
|
||
```properties
|
||
spring.mail.host=smtp.qq.com
|
||
spring.mail.port=587 # 或 465 (SSL)
|
||
spring.mail.username=your_email@qq.com
|
||
spring.mail.password=your_authorization_code
|
||
```
|
||
|
||
**获取QQ邮箱授权码：**
|
||
1. 登录QQ邮箱网页版
|
||
2. 设置 -> 账户
|
||
3. 开启 "POP3/SMTP服务" 或 "IMAP/SMTP服务"
|
||
4. 生成授权码（16位字符）
|
||
|
||
#### 163邮箱
|
||
```properties
|
||
spring.mail.host=smtp.163.com
|
||
spring.mail.port=465
|
||
spring.mail.username=your_email@163.com
|
||
spring.mail.password=your_authorization_code
|
||
```
|
||
|
||
#### Gmail
|
||
```properties
|
||
spring.mail.host=smtp.gmail.com
|
||
spring.mail.port=587
|
||
spring.mail.username=your_email@gmail.com
|
||
spring.mail.password=your_app_password
|
||
```
|
||
|
||
#### 企业邮箱（腾讯企业邮箱为例）
|
||
```properties
|
||
spring.mail.host=smtp.exmail.qq.com
|
||
spring.mail.port=465
|
||
spring.mail.username=your_email@your_domain.com
|
||
spring.mail.password=your_password
|
||
```
|
||
|
||
## 🧪 运行测试
|
||
|
||
### 方法一：使用IDE运行
|
||
|
||
1. 打开测试文件：`src/test/java/com/corewing/app/util/EmailUtilTest.java`
|
||
|
||
2. 修改测试邮箱地址：
|
||
```java
|
||
String to = "test@example.com"; // 改为你的邮箱
|
||
```
|
||
|
||
3. 运行测试方法：
|
||
- `testSendSimpleMail()` - 测试简单文本邮件
|
||
- `testSendHtmlMail()` - 测试HTML邮件
|
||
- `testSendVerifyCode()` - 测试验证码邮件
|
||
- `testSendMultipleVerifyCode()` - 测试批量发送
|
||
|
||
### 方法二：使用Gradle命令行
|
||
|
||
```bash
|
||
# 运行所有邮件测试
|
||
./gradlew test --tests EmailUtilTest
|
||
|
||
# 运行单个测试方法
|
||
./gradlew test --tests EmailUtilTest.testSendVerifyCode
|
||
```
|
||
|
||
## 📝 测试示例
|
||
|
||
### 1. 简单文本邮件测试
|
||
|
||
```java
|
||
@Test
|
||
public void testSendSimpleMail() {
|
||
String to = "your_email@example.com";
|
||
String subject = "【CoreWing】简单文本邮件测试";
|
||
String content = "这是一封测试邮件";
|
||
|
||
boolean success = emailUtil.sendSimpleMail(to, subject, content);
|
||
System.out.println(success ? "发送成功" : "发送失败");
|
||
}
|
||
```
|
||
|
||
### 2. 验证码邮件测试
|
||
|
||
```java
|
||
@Test
|
||
public void testSendVerifyCode() {
|
||
String to = "your_email@example.com";
|
||
String code = "123456";
|
||
|
||
boolean success = emailUtil.sendVerifyCode(to, code);
|
||
System.out.println(success ? "发送成功" : "发送失败");
|
||
}
|
||
```
|
||
|
||
## ✅ 预期结果
|
||
|
||
### 成功标志
|
||
```
|
||
✅ 验证码邮件发送成功！
|
||
收件人: test@example.com
|
||
验证码: 123456
|
||
请检查收件箱（可能在垃圾邮件中）
|
||
```
|
||
|
||
### 验证码邮件样式
|
||
邮件将以精美的HTML格式展示：
|
||
- 紫色渐变标题
|
||
- 大字号验证码显示
|
||
- 友好的提示信息
|
||
- 有效期说明（5分钟）
|
||
|
||
## ❌ 常见问题
|
||
|
||
### 1. 发送失败：认证失败
|
||
**错误信息：** `Authentication failed`
|
||
|
||
**解决方法：**
|
||
- 确认邮箱授权码是否正确（不是邮箱密码！）
|
||
- QQ邮箱需要开启SMTP服务并生成授权码
|
||
- 检查用户名格式是否正确（完整邮箱地址）
|
||
|
||
### 2. 发送失败：连接超时
|
||
**错误信息：** `Connection timed out`
|
||
|
||
**解决方法：**
|
||
- 检查网络连接
|
||
- 确认SMTP服务器地址和端口是否正确
|
||
- 检查防火墙设置
|
||
- 尝试切换端口（587/465/25）
|
||
|
||
### 3. 发送失败：SSL错误
|
||
**错误信息：** `SSL handshake failed`
|
||
|
||
**解决方法：**
|
||
- 端口465使用SSL，需要设置 `spring.mail.properties.mail.smtp.ssl.enable=true`
|
||
- 端口587使用TLS，需要设置 `spring.mail.properties.mail.smtp.starttls.enable=true`
|
||
|
||
### 4. 邮件进入垃圾箱
|
||
**解决方法：**
|
||
- 这是正常现象，测试邮件可能被识别为垃圾邮件
|
||
- 在垃圾箱中将发件人标记为"非垃圾邮件"
|
||
- 添加发件人到通讯录
|
||
|
||
### 5. QQ邮箱授权码获取失败
|
||
**解决方法：**
|
||
1. 进入QQ邮箱网页版
|
||
2. 设置 -> 账户 -> POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务
|
||
3. 开启"POP3/SMTP服务"
|
||
4. 通过密保验证后生成授权码
|
||
5. 授权码仅显示一次，请妥善保存
|
||
|
||
## 🔒 安全建议
|
||
|
||
1. **不要将授权码提交到代码仓库**
|
||
- 使用环境变量或配置中心管理敏感信息
|
||
- 在 `.gitignore` 中添加 `application.properties`
|
||
|
||
2. **生产环境配置**
|
||
```properties
|
||
# 使用环境变量
|
||
spring.mail.username=${MAIL_USERNAME}
|
||
spring.mail.password=${MAIL_PASSWORD}
|
||
```
|
||
|
||
3. **限流保护**
|
||
- 建议添加发送频率限制
|
||
- 防止被恶意利用大量发送邮件
|
||
|
||
## 📊 测试检查清单
|
||
|
||
- [ ] 配置文件中邮箱信息填写正确
|
||
- [ ] 邮箱SMTP服务已开启
|
||
- [ ] 授权码获取成功
|
||
- [ ] 网络连接正常
|
||
- [ ] 测试邮箱地址修改为实际邮箱
|
||
- [ ] 运行测试方法
|
||
- [ ] 检查收件箱（包括垃圾邮件）
|
||
- [ ] 验证邮件内容和格式
|
||
|
||
## 🎯 实际应用
|
||
|
||
在验证码功能中的使用：
|
||
|
||
```java
|
||
// 发送邮箱验证码
|
||
POST /user/sendCode
|
||
{
|
||
"account": "user@example.com",
|
||
"type": "register"
|
||
}
|
||
```
|
||
|
||
系统将自动：
|
||
1. 生成6位随机验证码
|
||
2. 存储到Redis（有效期5分钟）
|
||
3. 发送精美的HTML邮件到用户邮箱
|
||
4. 用户输入验证码完成验证
|
||
|
||
## 📚 相关文档
|
||
|
||
- [Spring Boot Mail 官方文档](https://docs.spring.io/spring-boot/docs/current/reference/html/io.html#io.email)
|
||
- [API接口说明.md](./API接口说明.md) - 查看完整的API文档
|
||
- [CLAUDE.md](./CLAUDE.md) - 项目开发指南
|
||
|
||
## 💡 提示
|
||
|
||
- 首次测试建议使用 `testSendVerifyCode()` 方法
|
||
- 确保收件人邮箱地址正确
|
||
- 检查垃圾邮件箱
|
||
- 测试成功后可以通过API接口测试完整流程
|