SpringBoot集成邮件服务完整实现方案

来源：互联网 2026-07-24 08:21:03

SpringBoot集成邮件服务需引入starter-mail依赖并配置SMTP服务器及授权码。将发送功能封装为工具类，配合条件注解自动装配。结合RabbitMQ实现异步解耦，注册成功后推送消息至队列，消费者异步发送邮件，提高接口响应速度。

在SpringBoot项目中集成邮件服务，基本流程相对固定，但若要将“发送邮件”功能运用得更加顺畅，尤其是与微服务、消息队列等场景结合，仍有不少细节值得深入探讨。以下方案从底层依赖逐步搭建到上层业务，并附带异步解耦的实战案例，帮助开发者快速掌握SpringBoot邮件服务集成。

1. 引入邮箱依赖

要在SpringBoot中发送邮件，首先需要引入starter-mail依赖，操作简单直接。

长期稳定更新的攒劲资源： >>>点此立即查看<<<


    org.springframework.boot
    spring-boot-starter-mail

2. 配置邮箱

依赖引入后，接下来需要配置邮件服务器。以QQ邮箱为例，需要配置SMTP服务器地址、端口以及授权码。注意，这里的password并非邮箱登录密码，而是开启SMTP服务后生成的授权码，这是许多开发者容易忽略的细节。

spring:
  mail:
    host: smtp.qq.com
    username: 你的QQ邮箱@qq.com
    password: 你的授权码  #需要自己去邮箱内开启SMTP服务
    default-encoding: UTF-8
    port: 465
    protocol: smtp
    properties:
      mail:
        smtp:
          auth: true
          ssl:
            enable: true
          socketFactory:
            class: ja vax.net.ssl.SSLSocketFactory

3. 测试发送一封简单的邮件

配置完成后，最直接的方式是编写单元测试，验证邮件发送功能是否正常。以下代码展示了最基础的发件流程：创建消息、设置发件人、收件人、标题和正文，然后发送。注意，setText的第二个参数为true，表示正文为HTML格式。

@Autowired
Ja vaMailSender ja vaMailSender;

@Test
public void test() throws Exception {
    // 创建一个邮件消息
    MimeMessage message = ja vaMailSender.createMimeMessage();
    // 创建 MimeMessageHelper
    MimeMessageHelper helper = new MimeMessageHelper(message, false);
    // 发件人邮箱和名称
    helper.setFrom("747692844@qq.com", "springdoc");
    // 收件人邮箱
    helper.setTo("admin@springboot.io");
    // 邮件标题
    helper.setSubject("Hello");
    // 邮件正文，第二个参数表示是否是HTML正文
    helper.setText("Hello  World! ", true);
    // 发送
    ja vaMailSender.send(message);
}

实际代码-前置条件:

SpringBoot集成邮件服务完整实现方案

然而，在实际项目中，我们不会在每个业务代码中重复编写这套底层逻辑。因此，下一步是封装和抽象，提升代码复用性。

1. 将邮件发送功能封装在公共类中，方便其他地方调用

封装的最佳实践是将邮件发送功能抽成一个公共工具类，放入common模块中。这样做具有以下优势：

依赖管理：工具类位于common模块，所有子服务无需重复引入mail依赖。
yml配置：需要提醒的是，无论工具类放置何处，每个需要发送邮件的微服务都必须自行配置mail配置，因为不同服务的邮箱账号可能不同。
调用便捷：其他服务只需注入MailUtil，直接调用send方法，无需关心底层MimeMessage创建等细节。

package com.bite.common.utils;

import jakarta.mail.internet.MimeMessage;
import org.springframework.boot.autoconfigure.mail.MailProperties;
import org.springframework.mail.ja vamail.Ja vaMailSender;
import org.springframework.mail.ja vamail.MimeMessageHelper;

import ja va.util.Optional;

public class Mail {
    private Ja vaMailSender ja vaMailSender;
    private MailProperties mailProperties;

    public Mail(Ja vaMailSender ja vaMailSender, MailProperties mailProperties) {
        this.ja vaMailSender = ja vaMailSender;
        this.mailProperties = mailProperties;
    }

    public void send(String to, String subject, String content) throws Exception {
        MimeMessage mimeMessage = ja vaMailSender.createMimeMessage();
        MimeMessageHelper helper = new MimeMessageHelper(mimeMessage, false);
        //发件人名称
        String personal = Optional.ofNullable(mailProperties.getProperties().get("personal"))
                .orElse(mailProperties.getUsername());
        helper.setFrom(mailProperties.getUsername(), personal);
        helper.setTo(to);    //收件人
        helper.setSubject(subject);    //邮件主题
        helper.setText(content, true);

        ja vaMailSender.send(mimeMessage);
    }
}

2. 编写Spring邮件配置类，哪个服务需要就写在哪个服务中，也可提取到服务的公共类中

工具类完成后，需要将其注册为Spring Bean。这需要编写一个配置类，使用@ConditionalOnProperty注解。该注解的作用是：只有当配置了spring.mail.username属性时，该Bean才会被创建。这样，不需要发送邮件的服务（如博客展示服务）可以避免因缺少邮箱配置而报错，实现优雅的按需加载。

package com.bite.common.config;

import com.bite.common.utils.Mail;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.autoconfigure.mail.MailProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.mail.ja vamail.Ja vaMailSender;


@Configuration
public class MailConfig {
    @Bean
    @ConditionalOnProperty(prefix="spring.mail",name="username")
    public Mail mail(Ja vaMailSender ja vaMailSender, MailProperties mailProperties) {
        return new Mail(ja vaMailSender,mailProperties);
    }
}

例子展示：用户注册场景下的异步解耦

下面通过一个实际业务场景展示邮件发送的异步解耦。假设用户注册服务在注册成功后，需要发送欢迎邮件。但发邮件操作可能耗时较长，若同步处理会拖慢响应速度。因此，引入RabbitMQ实现异步解耦。

某服务的注册业务(Service)代码:

@Override
public Integer register(UserInfoRegisterRequest registerRequest) {
    //校验参数:
    checkUserInfo(registerRequest);
    //校验通过,才是用户注册,插入数据库
    UserInfo userInfo = BeanConvert.convertUserInfoByEncrypt(registerRequest);
    try{
        int result = userInfoMapper.insert(userInfo);
        if(result==1){
            //存储数据到redis中
            redis.set(buildKey(userInfo.getUserName()), JsonUtil.toJson(userInfo),EXPIRE_TIME);

            //注册成功主动推送用户数据到 RabbitMQ，交给消费者异步处理发邮件，不阻塞注册接口响应速度
            userInfo.setPassword("");
            rabbitTemplate.convertAndSend(Constants.USER_EXCHANGE_NAME,"",JsonUtil.toJson(userInfo));

            return userInfo.getId();
        }else{
            throw new BlogException("用户注册失败");
        }
    }catch (Exception e){
        log.error("用户注册失败,e:",e);
        throw new BlogException("用户注册失败");
    }
}

关键代码在于rabbitTemplate.convertAndSend(...)。注册成功后，立即将用户信息发送到消息队列，然后返回，确保注册接口响应迅速。发邮件的任务由消费者异步处理。

生产者：注册成功后，主动推送用户数据到RabbitMQ，交给消费者异步处理发邮件，不阻塞注册接口响应速度。

消费者：消费收到的用户数据，并执行下一步操作，如发送邮件。

package com.bite.user.listener;

import com.bite.common.constant.Constants;
import com.bite.common.utils.JsonUtil;
import com.bite.common.utils.Mail;
import com.bite.user.dataobject.UserInfo;
import com.rabbitmq.client.Channel;
import lombok.extern.slf4j.Slf4j;
import org.springframework.amqp.core.ExchangeTypes;
import org.springframework.amqp.core.Message;
import org.springframework.amqp.rabbit.annotation.Exchange;
import org.springframework.amqp.rabbit.annotation.Queue;
import org.springframework.amqp.rabbit.annotation.QueueBinding;
import org.springframework.amqp.rabbit.annotation.RabbitListener;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import ja va.io.IOException;

@Slf4j
@Component
public class UserQueueListener {
    //
    @Autowired
    private Mail mail;
    
    @RabbitListener(bindings=@QueueBinding(
            value=@Queue(value=Constants.USER_QUEUE_NAME,durable="true"),
            exchange=@Exchange(value=Constants.USER_EXCHANGE_NAME,type= ExchangeTypes.FANOUT)
    ))
    public void handler(Message message, Channel channel) throws IOException {
        long deliveryTag=message.getMessageProperties().getDeliveryTag();
        try{
            String body = new String(message.getBody());
            log.info("收到用户信息,body:{}",body);
            //TODO 发送注册成功邮件
            UserInfo userInfo= JsonUtil.parseJson(body, UserInfo.class);
            //发送邮箱
            mail.send(userInfo.getEmail(),"恭喜加入XM博客社区",buildContent(userInfo.getUserName()));

            //确认
            channel.basicAck(deliveryTag,true);
        }catch(Exception e){
            //否定确认
            channel.basicNack(deliveryTag,true,true);
            log.error("邮件发送失败,e:",e);
        }
    }

    //发送的邮箱内容
    private String buildContent(String userName){
        StringBuilder builder=new StringBuilder();
        builder.append("尊敬的").append(userName).append(",您好!").append("
");
        builder.append("感谢您注册成为我们博客社区的一员!我们很高兴您加入我们的大家庭!
");
        builder.append("您的注册信息如下:用户名: ").append(userName).append("
");
        builder.append("为了您的账号安全,请妥善保管您的登录信息.如果使用过程中，遇到任何问题，欢迎联系我们的支持团队. XXXX@bXM.com 
");
        builder.append("再次感谢您的加入，我们期待看到您的精彩内容！
")
                .append("最好的祝愿
")
                .append("XM博客团队");

        return builder.toString();
    }
}

发送邮件前置条件：公共类中的

① 把Mail工具类创建成Spring Bean，放进容器

这一步由前面提到的MailConfig配置类完成。它将Mail工具类注册为Bean，并自动注入Ja vaMailSender和MailProperties。通过@ConditionalOnProperty，只有配置了邮箱的服务才会创建该Bean，灵活且安全。

② 邮箱发送操作实现逻辑

即Mail类本身的功能：封装底层发邮件逻辑，创建邮件、设置发件人/收件人/HTML正文、调用发送API。对外暴露简洁的send(String to, String subject, String content)方法。

三者关系