package com.example.mailDemo;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@MapperScan("com.example.mailDemo.**.mapper")  // 告诉 MyBatis-Plus 去哪里找 Mapper 接口
public class MailDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(MailDemoApplication.class, args);
    }
}

package com.example.mailDemo.user;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data                   // Lombok：自动生成 getter、setter、toString、equals、hashCode
@Builder                // Lombok：提供链式构建器，如 User.builder().username("xx").build()
@NoArgsConstructor      // Lombok：生成无参构造器（MyBatis-Plus 反射建实体时需要）
@AllArgsConstructor     // Lombok：生成全参构造器（配合 @Builder 使用）
@TableName("users")     // MyBatis-Plus：指定对应的数据库表名
public class User {

    @TableId(type = IdType.AUTO)  // 主键策略：数据库自增，insert 后自动回填 id 字段
    private Long id;

    private String username;

    private String email;
}

package com.example.mailDemo.user;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;

// 继承 BaseMapper<User> 后，insert、selectById、updateById、deleteById 等方法自动可用
public interface UserMapper extends BaseMapper<User> {}

package com.example.mailDemo.mail;

import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

@Slf4j
@Service
public class MailService {

	/**
	 * 发送欢迎邮件。
	 * 当前为占位实现，第五章接入 Simple Java Mail 后替换此处逻辑。
	 */
	public void sendWelcomeMail(String toEmail, String username) {
		log.info("【邮件发送】收件人：{}，用户名：{}，欢迎邮件已发出", toEmail, username);
	}
}

package com.example.mailDemo.user;

import com.example.mailDemo.mail.MailService;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Slf4j
@Service
@RequiredArgsConstructor  // Lombok：为所有 final 字段自动生成构造器，替代手写的构造器注入
public class UserService {

    private final UserMapper userMapper;
    private final MailService mailService;  // 注册服务直接持有邮件服务的引用

    @Transactional
    public User register(String username, String email) {
        log.info("【注册流程】开始，用户名：{}", username);

        // 用 Builder 构建实体，避免出现参数顺序错误的低级失误
        User newUser = User.builder()
                .username(username)
                .email(email)
                .build();

        userMapper.insert(newUser);  // insert 执行后，newUser.getId() 已被自动回填
        log.info("【注册流程】用户已入库，ID：{}", newUser.getId());

        // 数据库写完后，立刻调用邮件服务
        mailService.sendWelcomeMail(email, username);

        log.info("【注册流程】完成");
        return newUser;
    }
}

@Slf4j
@Service
@RequiredArgsConstructor
public class UserService {

    private final UserMapper userMapper;
    private final MailService mailService;
    private final SmsService smsService;       // 新增
    private final AuditService auditService;   // 新增

    @Transactional
    public User register(String username, String email) {
        User newUser = User.builder().username(username).email(email).build();
        userMapper.insert(newUser);

        mailService.sendWelcomeMail(email, username);
        smsService.sendWelcomeSms(phone, username);         // 新增
        auditService.recordRegistration(newUser.getId());   // 新增

        return newUser;
    }
}

package com.example.mailDemo.user;

/**
 * 事件语义：用户注册已完成（完成时态，描述业务事实）。
 *
 * 使用 record 定义，字段天然 final 且不可变——
 * 监听器在处理过程中无法修改事件内容，避免多个监听器之间互相干扰数据。
 *
 * @param userId   已注册的用户 ID，供需要查询详情的监听器使用
 * @param email    收件人邮箱，邮件监听器直接取用，无需再查库
 * @param username 用户名，用于邮件正文的个性化渲染
 */
public record UserRegisteredEvent(Long userId, String email, String username) {}

package com.example.mailDemo.user;

import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.ApplicationEventPublisher;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Slf4j
@Service
@RequiredArgsConstructor
public class UserService {

    private final UserMapper userMapper;
    private final ApplicationEventPublisher eventPublisher;  // 只注入这一个"广播器"

    @Transactional
    public User register(String username, String email) {
        log.info("【注册流程】开始，用户名：{}", username);

        User newUser = User.builder()
                .username(username)
                .email(email)
                .build();

        userMapper.insert(newUser);
        log.info("【注册流程】用户已入库，ID：{}", newUser.getId());

        // 宣布事实：用户注册成功了。至于谁来响应、怎么响应，UserService 不关心
        eventPublisher.publishEvent(
                new UserRegisteredEvent(newUser.getId(), email, username)
        );

        log.info("【注册流程】完成");
        return newUser;
    }
}

package com.example.mailDemo.mail;

import com.example.mailDemo.user.UserRegisteredEvent;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Component;

@Slf4j
@Component
@RequiredArgsConstructor
public class WelcomeMailListener {

    private final MailService mailService;

    /**
     * 监听用户注册完成事件，触发欢迎邮件发送。
     *
     * 方法参数的类型 UserRegisteredEvent 就是"订阅声明"：
     * Spring 看到这个方法签名后，会在每次 UserRegisteredEvent 被发布时自动调用它。
     */
    @EventListener
    public void onUserRegistered(UserRegisteredEvent event) {
        log.info("【邮件监听器】收到注册事件，目标邮箱：{}", event.email());
        mailService.sendWelcomeMail(event.email(), event.username());
    }
}

package com.example.mailDemo.user;

/**
 * 用户注册已完成事件。
 *
 * 字段选择依据：
 *   userId   — 业务主键，监听器需要扩展数据时可凭此查询
 *   email    — 渲染参数，邮件/短信发送直接取用，避免监听器再查库
 *   username — 渲染参数，欢迎邮件个性化称呼需要
 *
 * 没有放的字段：
 *   User 实体对象  — 见下方 ⚠️ 说明
 *   HttpServletRequest — 见下方 ⚠️ 说明
 */
public record UserRegisteredEvent(Long userId, String email, String username) {}

// ❌ 错误：一个事件试图描述两件事
public record UserRegisteredAndMailRequestedEvent(
        Long userId,
        String email,
        String username,
        String mailTemplateName,    // 这是"发什么邮件"的决策，属于邮件发送事件的职责
        boolean needSms             // 这是"要不要发短信"的决策，属于短信发送事件的职责
) {}

// ✅ 正确：每个事件只描述一件事
public record UserRegisteredEvent(Long userId, String email, String username) {}

// 事件继承体系示例
public class BaseMailEvent {}
public class WelcomeMailEvent(String email) extends BaseMailEvent {} 
// 以下三个监听器，当发布 WelcomeMailEvent 时，全部都会触发：
@EventListener
public void onWelcomeMail(WelcomeMailEvent event) {}   // 精确匹配，优先推荐

@EventListener
public void onBaseMail(BaseMailEvent event) {}         // 父类匹配，同样触发

@EventListener
public void onAnyObject(Object event) {}               // Object 是所有类的祖先，所有事件都触发

// ❌ 不会触发：方法是 private
@EventListener
private void onUserRegistered(UserRegisteredEvent event) { ... }

// ✅ 正确：方法是 public
@EventListener
public void onUserRegistered(UserRegisteredEvent event) { ... }

package com.example.mailDemo.mail;

import com.example.mailDemo.user.UserRegisteredEvent;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Component;

@Slf4j
@Component
@RequiredArgsConstructor
public class WelcomeMailListener {

    private final MailService mailService;

    /**
     * condition 里的 SpEL 表达式可以读取事件对象的字段。
     * #event 是固定变量名，指向当前发布的事件对象。
     * 这里的含义：只有 email 字段不为空时，才执行邮件发送。
     */
    @EventListener(condition = "#event.email() != null && !#event.email().isBlank()")
    public void onUserRegistered(UserRegisteredEvent event) {
        log.info("【邮件监听器】收到注册事件，目标邮箱：{}", event.email());
        mailService.sendWelcomeMail(event.email(), event.username());
    }
}

package com.example.mailDemo.mail;

import com.example.mailDemo.user.UserRegisteredEvent;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Component;

@Slf4j
@Component
public class AuditMailListener {

    /**
     * classes 属性：声明这个方法监听哪些事件类型。
     * 使用 classes 时，方法参数必须改为 Object（因为无法用单一具体类型同时接收多种事件）。
     *
     * 适合场景：多个事件触发完全相同的处理逻辑（如审计日志写入）。
     * 不适合场景：不同事件需要不同的处理分支——那种情况应该拆成两个独立的监听方法。
     */
    @EventListener(classes = {UserRegisteredEvent.class})
    public void onMailableEvent(Object event) {
        log.info("【审计监听器】事件类型：{}，进入审计记录", event.getClass().getSimpleName());
        // 审计写入逻辑...
    }
}

// Order 值越小，优先级越高，越先执行
@Order(1)
@EventListener
public void onUserRegistered_audit(UserRegisteredEvent event) {
    // 先执行：写审计日志
}

@Order(2)
@EventListener
public void onUserRegistered_mail(UserRegisteredEvent event) {
    // 后执行：发邮件
}

@EventListener
public MailSentEvent onUserRegistered(UserRegisteredEvent event) {
    mailService.sendWelcomeMail(event.email(), event.username());
    // 返回非 null 值时，Spring 自动将其发布为新事件
    return new MailSentEvent(event.userId(), event.email());
}

// ❌ 有隐患的写法：泛型事件
public record DomainEvent<T>(T payload) {}

// 发布时：
eventPublisher.publishEvent(new DomainEvent<>(userRegisteredData));
eventPublisher.publishEvent(new DomainEvent<>(orderPlacedData));

// 监听时——问题出现了：
@EventListener
public void onUserDomainEvent(DomainEvent<UserRegisteredData> event) { ... }
// 由于 Java 的类型擦除，运行时 DomainEvent<UserRegisteredData> 和 DomainEvent<OrderPlacedData>
// 都只是 DomainEvent，Spring 无法区分，两个发布都会触发这个方法

// ✅ 正确：具体类型，无歧义
public record UserRegisteredEvent(Long userId, String email, String username) {}
public record OrderPlacedEvent(Long orderId, Long userId, BigDecimal amount) {}

package com.example.mailDemo.mail;

import com.example.mailDemo.user.UserRegisteredEvent;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import org.springframework.transaction.event.TransactionPhase;
import org.springframework.transaction.event.TransactionalEventListener;

@Slf4j
@Component
@RequiredArgsConstructor
public class WelcomeMailListener {

    private final MailService mailService;

    /**
     * 事务提交成功后才执行邮件发送。
     *
     * phase = AFTER_COMMIT（默认值，可省略不写，此处显式保留增加可读性）：
     *   等待发布方的事务成功 commit 之后，再调用此方法。
     *   如果事务回滚，此方法不会被调用——邮件因此不会误发。
     *
     * fallbackExecution = false（默认值）：
     *   如果发布事件时根本没有活跃事务，此方法不会执行。
     *   见下方 ⚠️ 说明。
     */
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void onUserRegistered(UserRegisteredEvent event) {
        log.info("【邮件监听器】事务已提交，开始发送欢迎邮件，目标邮箱：{}", event.email());
        mailService.sendWelcomeMail(event.email(), event.username());
    }
}

// 假设某个工具方法没有 @Transactional：
public void nonTransactionalMethod() {
    eventPublisher.publishEvent(new UserRegisteredEvent(...));
    // 因为没有活跃事务，WelcomeMailListener 不会触发
    // 没有报错，没有日志，事件就这样消失了
}

package com.example.mailDemo.mail;

import com.example.mailDemo.user.UserRegisteredEvent;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.transaction.event.TransactionPhase;
import org.springframework.transaction.event.TransactionalEventListener;

@Slf4j
@Component
@RequiredArgsConstructor
public class MailAuditListener {

    private final MailAuditMapper mailAuditMapper;

    /**
     * 记录邮件发送日志到数据库。
     *
     * @Transactional(propagation = REQUIRES_NEW)：
     *   AFTER_COMMIT 阶段没有活跃事务，如果直接使用默认的 REQUIRED，
     *   会因为没有事务可以加入而导致写库操作在无事务状态下执行（不受回滚保护）。
     *   REQUIRES_NEW 强制开启一个全新的独立事务，确保审计日志的写入是原子的。
     *
     * 注意：@TransactionalEventListener 和 @Transactional 必须同时标注，
     * 两者分别控制"何时触发"和"触发后如何管理自己的事务"，职责不同。
     */
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void onUserRegistered(UserRegisteredEvent event) {
        log.info("【审计监听器】记录邮件发送日志，userId：{}", event.userId());
        // ...写审计日志到数据库...
    }
}

package com.example.mailDemo;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.scheduling.annotation.EnableAsync;

@SpringBootApplication
@EnableAsync          // 开启 @Async 注解的处理能力，缺少此注解时 @Async 标注的方法仍会同步执行
@MapperScan("com.example.mailDemo.**.mapper")
public class MailDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(MailDemoApplication.class, args);
    }
}

package com.example.mailDemo.config;

import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;

import java.util.concurrent.ThreadPoolExecutor;

@Slf4j
@Configuration
public class AsyncConfig {

    /**
     * 邮件发送专属线程池。
     *
     * Bean 名称 "mailTaskExecutor" 与监听器上 @Async("mailTaskExecutor") 对应，
     * 指定异步任务投递到这个线程池，而不是公共线程池。
     */
    @Bean("mailTaskExecutor")
    public ThreadPoolTaskExecutor mailTaskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();

        // 核心线程数：常驻线程，即使空闲也不会销毁
        // 生产建议值：根据邮件发送的并发量评估，通常 2-4 即可
        executor.setCorePoolSize(2);

        // 最大线程数：核心线程不够用时，最多扩展到此数量
        // 生产建议值：不超过核心数的 2 倍，避免线程调度开销过大
        executor.setMaxPoolSize(4);

        // 队列容量：任务等待队列的最大长度
        // 生产建议值：根据邮件发送的峰值 QPS × 预估最大延迟时间来设定
        // 设为 100 意味着最多允许 100 封邮件在队列里等待
        executor.setQueueCapacity(100);

        // 线程名前缀：出现在日志和线程 dump 里，方便定位问题
        executor.setThreadNamePrefix("mail-async-");

        // 拒绝策略：队列满且线程数达到最大时，由调用者线程直接执行（降级，而非直接丢弃）
        // CallerRunsPolicy 是最保守的策略：不丢任务，但会让调用者线程阻塞，起到背压效果
        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());

        // 等待所有任务执行完毕再关闭线程池（优雅停机）
        // 生产必须设为 true，否则应用关闭时正在发送的邮件会被中断
        executor.setWaitForTasksToCompleteOnShutdown(true);

        // 等待的最大秒数，超时后强制关闭（防止关机卡住）
        executor.setAwaitTerminationSeconds(30);

        executor.initialize();
        return executor;
    }
}

package com.example.mailDemo.mail;

import com.example.mailDemo.user.UserRegisteredEvent;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Component;
import org.springframework.transaction.event.TransactionPhase;
import org.springframework.transaction.event.TransactionalEventListener;

@Slf4j
@Component
@RequiredArgsConstructor
public class WelcomeMailListener {

    private final MailService mailService;

    /**
     * @TransactionalEventListener：等事务提交后再触发（第四章已解释）
     * @Async("mailTaskExecutor")：触发后把任务投递到邮件专属线程池异步执行
     *
     * 两个注解的职责完全不同：
     *   前者控制"什么时候触发"（事务边界）
     *   后者控制"在哪个线程执行"（线程模型）
     * 两者可以同时使用，互不干扰。
     */
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    @Async("mailTaskExecutor")
    public void onUserRegistered(UserRegisteredEvent event) {
        log.info("【邮件监听器】线程：{}，开始发送欢迎邮件，目标邮箱：{}",
                Thread.currentThread().getName(), event.email());
        mailService.sendWelcomeMail(event.email(), event.username());
    }
}

package com.example.mailDemo.config;

import lombok.extern.slf4j.Slf4j;
import org.springframework.aop.interceptor.AsyncUncaughtExceptionHandler;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.annotation.AsyncConfigurer;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;

import java.lang.reflect.Method;
import java.util.concurrent.ThreadPoolExecutor;

@Slf4j
@Configuration
public class AsyncConfig implements AsyncConfigurer {

    @Bean("mailTaskExecutor")
    public ThreadPoolTaskExecutor mailTaskExecutor() {
        // ...（同上，省略重复配置）...
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(2);
        executor.setMaxPoolSize(4);
        executor.setQueueCapacity(100);
        executor.setThreadNamePrefix("mail-async-");
        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
        executor.setWaitForTasksToCompleteOnShutdown(true);
        executor.setAwaitTerminationSeconds(30);
        executor.initialize();
        return executor;
    }

    /**
     * 全局异步异常处理器。
     *
     * 当 @Async 标注的方法抛出未捕获异常时，Spring 会调用此处理器。
     * 注意：此处理器只对返回 void 的异步方法生效。
     * 返回 Future/CompletableFuture 的方法，异常由调用方在 get() 时获取。
     */
    @Override
    public AsyncUncaughtExceptionHandler getAsyncUncaughtExceptionHandler() {
        return new MailAsyncExceptionHandler();
    }

    /**
     * 邮件发送异步异常处理器。
     * 实际项目中可在此接入告警系统（钉钉、PagerDuty 等）或写入失败补偿队列。
     */
    static class MailAsyncExceptionHandler implements AsyncUncaughtExceptionHandler {
        @Override
        public void handleUncaughtException(Throwable ex, Method method, Object... params) {
            log.error("【异步邮件】发送失败，方法：{}，参数：{}，原因：{}",
                    method.getName(), params, ex.getMessage(), ex);
            // 生产环境建议：将失败记录写入数据库或消息队列，供定时任务重试
        }
    }
}

package com.example.mailDemo.mail;

/**
 * 邮件发送失败事件。
 *
 * @param userId    目标用户 ID，用于补偿任务查询用户信息
 * @param email     目标邮箱，重试时直接使用
 * @param reason    失败原因描述，写入补偿记录，方便人工排查
 */
public record MailSendFailedEvent(Long userId, String email, String reason) {}

package com.example.mailDemo.mail;

import com.example.mailDemo.user.UserRegisteredEvent;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.ApplicationEventPublisher;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Component;
import org.springframework.transaction.event.TransactionPhase;
import org.springframework.transaction.event.TransactionalEventListener;

@Slf4j
@Component
@RequiredArgsConstructor
public class WelcomeMailListener {

    private final MailService mailService;
    private final ApplicationEventPublisher eventPublisher;

    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    @Async("mailTaskExecutor")
    public void onUserRegistered(UserRegisteredEvent event) {
        try {
            log.info("【邮件监听器】开始发送欢迎邮件，目标邮箱：{}", event.email());
            mailService.sendWelcomeMail(event.email(), event.username());
            log.info("【邮件监听器】发送成功，目标邮箱：{}", event.email());
        } catch (Exception ex) {
            log.error("【邮件监听器】发送失败，目标邮箱：{}，原因：{}", event.email(), ex.getMessage(), ex);
            // 发布失败事件，由专门的补偿监听器处理重试或告警
            eventPublisher.publishEvent(
                    new MailSendFailedEvent(event.userId(), event.email(), ex.getMessage())
            );
        }
    }
}

package com.example.mailDemo.user;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.event.ApplicationEvents;
import org.springframework.test.context.event.RecordApplicationEvents;
import org.springframework.transaction.annotation.Transactional;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest
@RecordApplicationEvents  // 启用事件录制，测试执行期间所有发布的事件都会被记录
@Transactional            // 每个测试方法结束后自动回滚，保持数据库清洁
class UserServiceTest {

    @Autowired
    private UserService userService;

    /**
     * ApplicationEvents 是 Spring 注入的特殊对象，持有当前测试方法内录制的所有事件。
     * 必须用 @Autowired 注入，不能手动 new。
     */
    @Autowired
    private ApplicationEvents applicationEvents;

    @Test
    void 注册成功后应发布UserRegisteredEvent() {
        // 执行注册
        userService.register("testUser", "test@example.com");

        // 断言事件类型与数量：注册一次，应该发布恰好一个 UserRegisteredEvent
        assertThat(
                applicationEvents.stream(UserRegisteredEvent.class)
        ).hasSize(1);
    }

    @Test
    void 注册成功后事件应携带正确的用户信息() {
        userService.register("alice", "alice@example.com");

        // 取出第一个（也是唯一一个）UserRegisteredEvent，断言其字段内容
        UserRegisteredEvent event = applicationEvents
                .stream(UserRegisteredEvent.class)
                .findFirst()
                .orElseThrow();

        assertThat(event.email()).isEqualTo("alice@example.com");
        assertThat(event.username()).isEqualTo("alice");
        assertThat(event.userId()).isNotNull();  // id 由数据库自增回填，只验证非空
    }
}

package com.example.mailDemo.config;

import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Primary;
import org.springframework.core.task.SyncTaskExecutor;
import org.springframework.core.task.TaskExecutor;

/**
 * 测试专用异步配置。
 *
 * @Primary 确保此 Bean 优先级高于生产配置中的 mailTaskExecutor，
 * 测试期间 @Async("mailTaskExecutor") 的调用会被路由到这个同步执行器。
 *
 * SyncTaskExecutor 不开启新线程，直接在当前线程里同步执行任务，
 * 使得异步监听器的执行结果在断言时已经确定可见。
 */
@TestConfiguration
public class TestAsyncConfig {

    @Bean("mailTaskExecutor")
    @Primary
    public TaskExecutor mailTaskExecutor() {
        return new SyncTaskExecutor();
    }
}

package com.example.mailDemo.mail;

import com.example.mailDemo.config.TestAsyncConfig;
import com.example.mailDemo.user.UserRegisteredEvent;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.context.ApplicationEventPublisher;
import org.springframework.context.annotation.Import;
import org.springframework.test.context.event.ApplicationEvents;
import org.springframework.test.context.event.RecordApplicationEvents;

import static org.mockito.Mockito.*;

@SpringBootTest
@RecordApplicationEvents
@Import(TestAsyncConfig.class)  // 引入同步执行器，覆盖生产线程池
class WelcomeMailListenerTest {

    @Autowired
    private ApplicationEventPublisher eventPublisher;

    /**
     * MockBean：用 Mockito 的 Mock 对象替换 Spring 容器中的 MailService Bean，
     * 避免测试时真的去连 SMTP 服务器发邮件。
     */
    @MockBean
    private MailService mailService;

    @Autowired
    private ApplicationEvents applicationEvents;

    @Test
    void 收到注册事件后应调用邮件服务发送欢迎邮件() {
        // 直接发布事件（绕过 UserService 和事务，单独测试监听器行为）
        // 注意：@TransactionalEventListener 在无事务时默认不触发，
        // 此处测试会无法触发，需要结合 fallbackExecution 或改用 @EventListener 测试
        // 推荐的替代方案见下方说明
        eventPublisher.publishEvent(
                new UserRegisteredEvent(1L, "test@example.com", "testUser")
        );

        // 断言 MailService.sendWelcomeMail 被调用了一次
        verify(mailService, times(1))
                .sendWelcomeMail("test@example.com", "testUser");
    }
}

// 第一层：只测发布者，不测副作用
@Test
void 注册方法应发布正确的事件() {
    userService.register("alice", "alice@example.com");
    assertThat(applicationEvents.stream(UserRegisteredEvent.class))
            .hasSize(1)
            .first()
            .satisfies(e -> {
                assertThat(e.email()).isEqualTo("alice@example.com");
                assertThat(e.username()).isEqualTo("alice");
            });
}

// 第二层：只测监听器，Mock 掉真实依赖
@Test
void 监听器收到事件后应调用邮件服务() {
    // 直接发布事件，绕过 UserService，隔离测试监听器
    eventPublisher.publishEvent(new UserRegisteredEvent(1L, "b@b.com", "bob"));
    verify(mailService, times(1)).sendWelcomeMail("b@b.com", "bob");
}

@Test
void 邮件发送失败时应发布MailSendFailedEvent() {
    // 让 MailService 抛出异常，模拟 SMTP 连接失败
    doThrow(new RuntimeException("SMTP 连接超时"))
            .when(mailService).sendWelcomeMail(anyString(), anyString());

    eventPublisher.publishEvent(new UserRegisteredEvent(1L, "c@c.com", "carol"));

    // 断言失败事件被发布
    assertThat(applicationEvents.stream(MailSendFailedEvent.class))
            .hasSize(1)
            .first()
            .satisfies(e -> assertThat(e.reason()).contains("SMTP 连接超时"));
}