Java 后端 / 系统课时
处理邮件与通知任务
处理邮件与通知任务
本课实现一条可追踪的邮件通知链路:接口先登记发送任务,事务提交后异步调用 SMTP,失败时有限重试,并把状态、次数和错误原因写入记录表,便于查询、补偿和审计。
学习目标
- 使用 Spring Boot Mail 发送带模板变量的邮件
- 设计发送状态、重试策略与记录表
- 避免业务回滚误发和 SMTP 故障阻塞请求
设计通知链路
核心业务事务中不应直接连接 SMTP。正确顺序是先保存业务数据和邮件任务,事务成功提交后再交给异步 Worker;发送成功写入 SUCCESS,暂时失败进入 RETRYING,达到上限后转为 FAILED。

记录表至少保留任务 ID、收件人、模板编码、状态、尝试次数、最后错误、创建时间和发送时间。模板变量应使用明确的数据结构,而不是任意 Map,以便在入口完成校验。
配置邮件与记录表
在现有 Spring Boot 3 项目中加入邮件、JDBC 和本地验证数据库依赖:
<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>邮件密码通过环境变量注入;生产环境应使用密钥管理服务,而不是把密码写进仓库。
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:
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 包。
// 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);
}
}// 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,启动应用后提交任务:
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}'预期输出:
HTTP/1.1 202
Content-Type: application/json
{"taskId":"<ID>","status":"PENDING"}等待异步发送后查询状态:
curl "http://localhost:<PORT>/api/mail-tasks/<ID>"预期输出:
{"taskId":"<ID>","status":"SUCCESS","attempts":1,"lastError":null}<PORT>、<ID> 和完成时间会随环境变化。SMTP 连续三次失败时,最终状态应为 FAILED,attempts 为 3,并保留最后错误。
可靠性边界
应用内事件无法完全覆盖“事务已提交但进程立即崩溃”的窗口,因此生产系统还应定时扫描长期停留在 PENDING 或 RETRYING 的记录。更严格的场景应采用 Outbox、事务消息或消息队列,并用业务幂等键防止重复发送。