core_wing_web/邮件发送测试说明.md

邮件发送测试说明

📧 功能概述

项目已集成邮件发送功能，支持：

• 简单文本邮件
• HTML格式邮件
• 验证码邮件（带精美HTML模板）

🔧 配置步骤

1. 邮箱配置

在 src/main/resources/application.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邮箱

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邮箱

spring.mail.host=smtp.163.com
spring.mail.port=465
spring.mail.username=your_email@163.com
spring.mail.password=your_authorization_code

Gmail

spring.mail.host=smtp.gmail.com
spring.mail.port=587
spring.mail.username=your_email@gmail.com
spring.mail.password=your_app_password

企业邮箱（腾讯企业邮箱为例）

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. 修改测试邮箱地址：

   String to = "test@example.com";  // 改为你的邮箱
   

3. 运行测试方法：

   • testSendSimpleMail() - 测试简单文本邮件
   • testSendHtmlMail() - 测试HTML邮件
   • testSendVerifyCode() - 测试验证码邮件
   • testSendMultipleVerifyCode() - 测试批量发送

方法二：使用Gradle命令行

# 运行所有邮件测试
./gradlew test --tests EmailUtilTest

# 运行单个测试方法
./gradlew test --tests EmailUtilTest.testSendVerifyCode

📝 测试示例

1. 简单文本邮件测试

@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. 验证码邮件测试

@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. 生产环境配置

   # 使用环境变量
   spring.mail.username=${MAIL_USERNAME}
   spring.mail.password=${MAIL_PASSWORD}
   

3. 限流保护

   • 建议添加发送频率限制
   • 防止被恶意利用大量发送邮件

📊 测试检查清单

• 配置文件中邮箱信息填写正确
• 邮箱SMTP服务已开启
• 授权码获取成功
• 网络连接正常
• 测试邮箱地址修改为实际邮箱
• 运行测试方法
• 检查收件箱（包括垃圾邮件）
• 验证邮件内容和格式

🎯 实际应用

在验证码功能中的使用：

// 发送邮箱验证码
POST /user/sendCode
{
  "account": "user@example.com",
  "type": "register"
}

系统将自动：

1. 生成6位随机验证码
2. 存储到Redis（有效期5分钟）
3. 发送精美的HTML邮件到用户邮箱
4. 用户输入验证码完成验证

📚 相关文档

• Spring Boot Mail 官方文档
• API接口说明.md - 查看完整的API文档
• CLAUDE.md - 项目开发指南

💡 提示

• 首次测试建议使用 testSendVerifyCode() 方法
• 确保收件人邮箱地址正确
• 检查垃圾邮件箱
• 测试成功后可以通过API接口测试完整流程