Java 后端 / 系统课时

处理邮件与通知任务

处理邮件与通知任务

本课实现一条可追踪的邮件通知链路:接口先登记发送任务,事务提交后异步调用 SMTP,失败时有限重试,并把状态、次数和错误原因写入记录表,便于查询、补偿和审计。

学习目标

  • 使用 Spring Boot Mail 发送带模板变量的邮件
  • 设计发送状态、重试策略与记录表
  • 避免业务回滚误发和 SMTP 故障阻塞请求

设计通知链路

核心业务事务中不应直接连接 SMTP。正确顺序是先保存业务数据和邮件任务,事务成功提交后再交给异步 Worker;发送成功写入 SUCCESS,暂时失败进入 RETRYING,达到上限后转为 FAILED。

邮件任务提交、异步发送与失败重试流程

记录表至少保留任务 ID、收件人、模板编码、状态、尝试次数、最后错误、创建时间和发送时间。模板变量应使用明确的数据结构,而不是任意 Map,以便在入口完成校验。

配置邮件与记录表

在现有 Spring Boot 3 项目中加入邮件、JDBC 和本地验证数据库依赖:

xml
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-mail</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-jdbc</artifactId>
    </dependency>
    <dependency>
        <groupId>com.h2database</groupId>
        <artifactId>h2</artifactId>
        <scope>runtime</scope>
    </dependency>
</dependencies>

邮件密码通过环境变量注入;生产环境应使用密钥管理服务,而不是把密码写进仓库。

yaml
spring:
  mail:
    host: ${MAIL_HOST}
    port: ${MAIL_PORT:587}
    username: ${MAIL_USERNAME}
    password: ${MAIL_PASSWORD}
    properties:
      mail.smtp.auth: true
      mail.smtp.starttls.enable: true
  datasource:
    url: jdbc:h2:mem:notification;DB_CLOSE_DELAY=-1
  sql:
    init:
      mode: always

创建 src/main/resources/schema.sql:

sql
CREATE TABLE mail_send_record (
    id VARCHAR(36) PRIMARY KEY,
    recipient VARCHAR(320) NOT NULL,
    template_code VARCHAR(64) NOT NULL,
    status VARCHAR(16) NOT NULL,
    attempts INT NOT NULL,
    last_error VARCHAR(1000),
    created_at TIMESTAMP NOT NULL,
    sent_at TIMESTAMP
);

应用启动后应能创建该表。生产库请用 Flyway 或 Liquibase 管理变更版本。

实现提交与异步重试

下面是项目片段,依赖已有的 Spring Boot 启动类、Web 与 Validation 依赖。按文件注释拆分到 com.example.notification 包。

java
// MailTaskService.java
package com.example.notification;

import jakarta.validation.constraints.DecimalMin;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import java.math.BigDecimal;
import java.sql.Timestamp;
import java.time.Duration;
import java.time.Instant;
import java.util.UUID;
import java.util.concurrent.Executor;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.ApplicationEventPublisher;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.mail.MailException;
import org.springframework.mail.SimpleMailMessage;
import org.springframework.mail.javamail.JavaMailSender;
import org.springframework.scheduling.annotation.Async;
import org.springframework.scheduling.annotation.EnableAsync;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
import org.springframework.stereotype.Component;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.transaction.event.TransactionPhase;
import org.springframework.transaction.event.TransactionalEventListener;

record OrderPaidMailCommand(
        @Email @NotBlank String to,
        @NotBlank String customerName,
        @NotBlank String orderNo,
        @DecimalMin("0.01") BigDecimal amount) {}

record MailTaskCreated(UUID taskId, OrderPaidMailCommand command) {}

record MailTaskView(UUID taskId, String status, int attempts, String lastError) {}

@Configuration
@EnableAsync
class MailAsyncConfig {
    @Bean("notificationExecutor")
    Executor notificationExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(2);
        executor.setMaxPoolSize(4);
        executor.setQueueCapacity(100);
        executor.setThreadNamePrefix("notification-");
        executor.initialize();
        return executor;
    }
}

@Service
public class MailTaskService {
    private final JdbcTemplate jdbc;
    private final ApplicationEventPublisher publisher;

    public MailTaskService(JdbcTemplate jdbc, ApplicationEventPublisher publisher) {
        this.jdbc = jdbc;
        this.publisher = publisher;
    }

    @Transactional
    public UUID submit(OrderPaidMailCommand command) {
        // 先持久化任务,再发布事务内事件。
        UUID id = UUID.randomUUID();
        jdbc.update("""
                INSERT INTO mail_send_record(
                    id, recipient, template_code, status, attempts, created_at
                ) VALUES (?, ?, 'order-paid', 'PENDING', 0, ?)
                """, id.toString(), command.to(), Timestamp.from(Instant.now()));
        publisher.publishEvent(new MailTaskCreated(id, command));
        return id;
    }

    public MailTaskView find(UUID id) {
        return jdbc.queryForObject("""
                SELECT id, status, attempts, last_error
                FROM mail_send_record WHERE id=?
                """, (rs, rowNum) -> new MailTaskView(
                        UUID.fromString(rs.getString("id")),
                        rs.getString("status"),
                        rs.getInt("attempts"),
                        rs.getString("last_error")), id.toString());
    }
}

@Component
class MailTaskWorker {
    private final JdbcTemplate jdbc;
    private final JavaMailSender sender;
    private final String fromAddress;

    MailTaskWorker(
            JdbcTemplate jdbc,
            JavaMailSender sender,
            @Value("${spring.mail.username}") String fromAddress) {
        this.jdbc = jdbc;
        this.sender = sender;
        this.fromAddress = fromAddress;
    }

    @Async("notificationExecutor")
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void handle(MailTaskCreated event) {
        // 只有业务事务提交成功后,异步发送才会开始。
        for (int attempt = 1; attempt <= 3; attempt++) {
            jdbc.update(
                    "UPDATE mail_send_record SET status='SENDING', attempts=? WHERE id=?",
                    attempt, event.taskId().toString());
            try {
                sender.send(render(event.command()));
                jdbc.update("""
                        UPDATE mail_send_record
                        SET status='SUCCESS', last_error=NULL, sent_at=?
                        WHERE id=?
                        """, Timestamp.from(Instant.now()), event.taskId().toString());
                return;
            } catch (MailException ex) {
                // 每次失败都落库,便于查询当前进度和最终原因。
                boolean exhausted = attempt == 3;
                jdbc.update("""
                        UPDATE mail_send_record SET status=?, last_error=? WHERE id=?
                        """, exhausted ? "FAILED" : "RETRYING",
                        abbreviate(ex.getMessage()), event.taskId().toString());
                if (!exhausted) {
                    pause(attempt);
                }
            }
        }
    }

    private SimpleMailMessage render(OrderPaidMailCommand command) {
        String body = "%s,您好:订单 %s 已支付,金额 %s 元。"
                .formatted(command.customerName(), command.orderNo(), command.amount());
        SimpleMailMessage message = new SimpleMailMessage();
        message.setFrom(fromAddress);
        message.setTo(command.to());
        message.setSubject("订单支付成功:" + command.orderNo());
        message.setText(body);
        return message;
    }

    private void pause(int attempt) {
        // 2 秒、4 秒退避;生产环境应改为可配置策略。
        try {
            Thread.sleep(Duration.ofSeconds(attempt * 2L).toMillis());
        } catch (InterruptedException ex) {
            Thread.currentThread().interrupt();
            throw new IllegalStateException("邮件重试被中断", ex);
        }
    }

    private String abbreviate(String message) {
        if (message == null) {
            return "unknown mail error";
        }
        return message.length() <= 1000 ? message : message.substring(0, 1000);
    }
}
java
// MailTaskController.java
package com.example.notification;

import jakarta.validation.Valid;
import java.util.Map;
import java.util.UUID;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/mail-tasks")
public class MailTaskController {
    private final MailTaskService service;

    public MailTaskController(MailTaskService service) {
        this.service = service;
    }

    @PostMapping
    ResponseEntity<Map<String, Object>> submit(
            @Valid @RequestBody OrderPaidMailCommand command) {
        UUID id = service.submit(command);
        return ResponseEntity.accepted()
                .body(Map.of("taskId", id, "status", "PENDING"));
    }

    @GetMapping("/{id}")
    MailTaskView find(@PathVariable UUID id) {
        return service.find(id);
    }
}

强类型命令就是模板变量契约;事务提交事件避免业务回滚后误发;异步方法必须由另一个 Spring Bean 调用,不能在同一对象里自调用。

调用并验证

配置可用 SMTP,启动应用后提交任务:

bash
curl -i -X POST "http://localhost:<PORT>/api/mail-tasks" \
  -H "Content-Type: application/json" \
  -d '{"to":"user@example.com","customerName":"张三","orderNo":"SO-2026-001","amount":199.00}'

预期输出:

text
HTTP/1.1 202
Content-Type: application/json

{"taskId":"<ID>","status":"PENDING"}

等待异步发送后查询状态:

bash
curl "http://localhost:<PORT>/api/mail-tasks/<ID>"

预期输出:

json
{"taskId":"<ID>","status":"SUCCESS","attempts":1,"lastError":null}

<PORT>、<ID> 和完成时间会随环境变化。SMTP 连续三次失败时,最终状态应为 FAILED,attempts 为 3,并保留最后错误。

可靠性边界

应用内事件无法完全覆盖“事务已提交但进程立即崩溃”的窗口,因此生产系统还应定时扫描长期停留在 PENDING 或 RETRYING 的记录。更严格的场景应采用 Outbox、事务消息或消息队列,并用业务幂等键防止重复发送。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

处理邮件与通知任务

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通