SpringBoot+QQ邮箱实战：从零搭建邮件服务到高级模板应用全解析
1. 环境准备与QQ邮箱配置
在开始SpringBoot整合QQ邮箱之前，我们需要先做好基础准备工作。就像盖房子需要打地基一样，邮件服务开发也需要先搭建好开发环境。我建议使用JDK 17+版本，这是目前SpringBoot官方推荐的最新稳定版本。开发工具可以选择IntelliJ IDEA或者Eclipse，我个人更推荐IDEA，它的智能提示和代码补全功能对新手特别友好。
QQ邮箱的配置是整个流程中最关键也最容易出错的一环。很多新手在这里栽跟头，主要问题都出在SMTP服务开启和授权码获取上。登录QQ邮箱网页版后，点击顶部"设置"，然后选择左侧的"账户"选项卡。往下滚动找到"POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务"这一项，点击"开启"SMTP服务。这里有个坑需要注意：系统会要求你发送短信验证，验证通过后生成的16位授权码一定要立即复制保存！这个授权码只显示一次，刷新页面就会消失，如果忘记就只能重新生成了。
QQ邮箱的SMTP服务器地址是固定的smtp.qq.com，端口建议使用465（SSL加密端口）。这里有个小技巧：虽然25端口也能用，但很多云服务器厂商会屏蔽25端口，所以直接用465端口最稳妥。发件人邮箱必须和你开启SMTP服务的QQ邮箱一致，密码则是刚才获取的16位授权码，注意不是QQ密码！
2. SpringBoot项目初始化
创建SpringBoot项目有两种常用方式：一种是通过IDEA自带的Spring Initializr创建，另一种是在Spring官网生成项目后导入。我建议新手直接用IDEA创建，因为更直观简单。在New Project界面选择Spring Initializr，然后按步骤操作即可。
项目创建时，必须选择的依赖是Spring Mail Starter，这是邮件功能的核心。此外，我建议同时勾选Web和Thymeleaf依赖，Web用于创建测试接口，Thymeleaf则是后面实现模板邮件的关键。如果创建项目时漏选了这些依赖，也不用担心，可以手动在pom.xml中添加：
<dependencies> <!-- 邮件核心依赖 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-mail</artifactId> </dependency> <!-- Web依赖（用于写接口测试） --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- Thymeleaf依赖（用于邮件模板） --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-thymeleaf</artifactId> </dependency> </dependencies>配置文件我推荐使用application.yml，它比properties文件更简洁清晰。邮件相关的关键配置包括：
- host: smtp.qq.com
- username: 你的QQ邮箱
- password: 16位授权码
- port: 465
- 必须开启SSL加密
完整的配置示例如下：
spring: mail: host: smtp.qq.com username: 123456@qq.com password: abcdefghijklmnop port: 465 default-encoding: UTF-8 properties: mail: smtp: ssl: enable: true auth: true timeout: 30000 connectiontimeout: 30000 writetimeout: 300003. 基础邮件功能实现
3.1 纯文本邮件发送
我们先从最简单的纯文本邮件开始。创建一个MailService类，注入JavaMailSender，这是Spring提供的邮件发送工具类。发送纯文本邮件只需要三个步骤：
- 创建SimpleMailMessage对象
- 设置发件人、收件人、主题和内容
- 调用javaMailSender.send方法发送
@Service public class MailService { @Resource private JavaMailSender javaMailSender; private static final String SENDER = "123456@qq.com"; public void sendSimpleTextMail(String to, String subject, String content) { SimpleMailMessage message = new SimpleMailMessage(); message.setFrom(SENDER); message.setTo(to); message.setSubject(subject); message.setText(content); javaMailSender.send(message); } }为了方便测试，我们可以创建一个简单的Controller：
@RestController public class MailController { @Resource private MailService mailService; @PostMapping("/mail/simple") public String sendSimpleMail(@RequestParam String to, @RequestParam String subject, @RequestParam String content) { mailService.sendSimpleTextMail(to, subject, content); return "纯文本邮件发送成功！"; } }启动项目后，用Postman发送POST请求到http://localhost:8080/mail/simple，传入to、subject和content参数，就能测试邮件发送功能了。
3.2 HTML格式邮件发送
实际项目中，我们更常用的是HTML格式的邮件，比如注册验证邮件、订单通知邮件等。HTML邮件的实现和纯文本邮件类似，但需要使用MimeMessage和MimeMessageHelper：
public void sendHtmlMail(String to, String subject, String htmlContent) throws MessagingException { MimeMessage mimeMessage = javaMailSender.createMimeMessage(); MimeMessageHelper helper = new MimeMessageHelper(mimeMessage, true, "UTF-8"); helper.setFrom(SENDER); helper.setTo(to); helper.setSubject(subject); helper.setText(htmlContent, true); // 关键：第二个参数true表示是HTML javaMailSender.send(mimeMessage); }对应的Controller方法可以这样写：
@PostMapping("/mail/html") public String sendHtmlMail(@RequestParam String to, @RequestParam String subject) { String htmlContent = "<!DOCTYPE html><html><body>" + "<h1 style='color:red'>欢迎注册</h1>" + "<p>请点击<a href='https://example.com/verify'>链接</a>完成验证</p>" + "</body></html>"; mailService.sendHtmlMail(to, subject, htmlContent); return "HTML邮件发送成功！"; }3.3 带附件邮件发送
发送带附件的邮件也很常见，比如发送报表、合同等。实现方式是在MimeMessageHelper中添加附件：
public void sendMailWithAttachment(String to, String subject, String content, String filePath) throws MessagingException { MimeMessage mimeMessage = javaMailSender.createMimeMessage(); MimeMessageHelper helper = new MimeMessageHelper(mimeMessage, true, "UTF-8"); helper.setFrom(SENDER); helper.setTo(to); helper.setSubject(subject); helper.setText(content); File file = new File(filePath); if (file.exists()) { FileSystemResource resource = new FileSystemResource(file); helper.addAttachment(resource.getFilename(), resource); } javaMailSender.send(mimeMessage); }注意文件路径的写法，在Windows系统中应该使用"D:/test.pdf"而不是"D:\test.pdf"，因为反斜杠在Java字符串中需要转义。
4. 高级功能实现
4.1 Thymeleaf模板邮件
对于需要动态内容的邮件，比如订单通知，使用Thymeleaf模板是最佳选择。首先在resources/templates目录下创建模板文件order-notice.html：
<!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <meta charset="UTF-8"> <title>订单通知</title> <style> .container { width: 600px; margin: 0 auto; } .title { color: #E64A19; } </style> </head> <body> <div class="container"> <h2 class="title">订单创建成功</h2> <p>订单号：<span th:text="${orderId}"></span></p> <p>金额：<span th:text="${amount}"></span>元</p> <p>时间：<span th:text="${createTime}"></span></p> </div> </body> </html>然后在MailService中添加模板邮件发送方法：
@Resource private TemplateEngine templateEngine; public void sendTemplateMail(String to, String subject, String orderId, String amount, String createTime) throws MessagingException { Context context = new Context(); context.setVariable("orderId", orderId); context.setVariable("amount", amount); context.setVariable("createTime", createTime); String htmlContent = templateEngine.process("mail/order-notice", context); sendHtmlMail(to, subject, htmlContent); }4.2 异步邮件发送
邮件发送是相对耗时的操作，为了不影响主业务流程，应该使用异步方式发送。首先在启动类上添加@EnableAsync注解：
@SpringBootApplication @EnableAsync public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }然后在邮件发送方法上添加@Async注解：
@Async public void sendTemplateMail(String to, String subject, String orderId, String amount, String createTime) throws MessagingException { // 方法实现不变 }这样调用该方法时会立即返回，邮件发送操作会在后台线程中执行。
5. 异常处理与优化
5.1 全局异常处理
为了避免在每个Controller方法中都写try-catch，我们可以使用Spring的全局异常处理机制：
@RestControllerAdvice public class GlobalExceptionHandler { @ExceptionHandler(MessagingException.class) public String handleMailException(MessagingException e) { return "邮件发送失败：" + e.getMessage(); } @ExceptionHandler(Exception.class) public String handleOtherException(Exception e) { return "系统异常：" + e.getMessage(); } }5.2 安全优化
敏感信息如授权码不应该硬编码在代码中，应该放在配置文件中。可以在application.yml中添加自定义配置：
custom: mail: sender: 123456@qq.com然后在Service中通过@Value注入：
@Value("${custom.mail.sender}") private String sender;生产环境中，更安全的做法是使用环境变量或配置中心来管理这些敏感信息。
6. 常见问题排查
在实际开发中，你可能会遇到各种问题。最常见的是授权码错误，表现为"535 Login Fail"。这时候需要确认你使用的是16位授权码而不是QQ密码。另一个常见问题是端口配置错误，如果使用25端口被拒绝，可以尝试改用465端口并确保SSL已启用。
附件发送失败通常是因为文件路径问题，Windows系统下注意使用正斜杠"/"而不是反斜杠""。Thymeleaf模板找不到的错误通常是因为模板文件没有放在正确的目录下，或者缺少了Thymeleaf命名空间声明。