【阶段 1】Spring Framework 核心：IoC 与 AOP

curl https://start.spring.io/starter.zip 
  -d type=maven-project 
  -d language=java 
  -d bootVersion=3.2.5 
  -d groupId=com.example 
  -d artifactId=demo 
  -d name=demo 
  -d packageName=com.example.demo 
  -d javaVersion=17 
  -d dependencies=web,aop,validation,jdbc,h2,lombok 
  -o demo.zip
unzip demo.zip && cd demo

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.5</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>demo</name>
    <description>Spring Framework 核心：IoC 与 AOP</description>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <!-- Web：提供 Spring MVC + 内嵌 Tomcat -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- AOP：提供 @Aspect / @EnableAspectJAutoProxy 支持 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-aop</artifactId>
        </dependency>
        <!-- Validation：提供 JSR-303 参数校验（@NotNull 等） -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
        <!-- JDBC：提供 JdbcTemplate + DataSourceTransactionManager（真实事务） -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-jdbc</artifactId>
        </dependency>
        <!-- H2：内存数据库，跑完即丢，适合演示事务 -->
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <scope>runtime</scope>
        </dependency>
        <!-- Lombok：@Data / @Slf4j / @RequiredArgsConstructor -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

-- 用户账户表：余额字段用于演示转账事务
CREATE TABLE IF NOT EXISTS t_account (
    id       BIGINT PRIMARY KEY,
    username VARCHAR(64)  NOT NULL,
    balance  DECIMAL(10,2) NOT NULL DEFAULT 0
);

spring:
  datasource:
    url: jdbc:h2:mem:demo;DB_CLOSE_DELAY=-1   # 内存库，连接断开也不清空
    driver-class-name: org.h2.Driver
    username: sa
    password: ""
  sql:
    init:
      mode: always                 # 每次启动执行 schema.sql
      schema-locations: classpath:schema.sql

// 反例：对象自己 new 依赖，控制权在自己手里
public class UserController {
    // 依赖被硬编码在类内部，UserController 与 UserServiceImpl 强耦合
    private UserService userService = new UserServiceImpl();

    public void register(String username) {
        userService.register(username);
    }
}

// 正例：只声明依赖，不关心它从哪来、怎么创建
@RestController
public class UserController {
    private final UserService userService;   // 只声明「我需要 UserService」

    public UserController(UserService userService) {  // 由容器通过构造器注入
        this.userService = userService;
    }
}

@Service
public class UserServiceImpl implements UserService {
    @Autowired
    private UserMapper userMapper;   // 直接注入到字段
    @Autowired
    private CacheService cacheService;
}

@Service
public class UserServiceImpl implements UserService {
    private UserMapper userMapper;

    @Autowired
    public void setUserMapper(UserMapper userMapper) {  // 通过 Setter 注入
        this.userMapper = userMapper;
    }
}

@Service
public class UserServiceImpl implements UserService {
    private final UserMapper userMapper;      // final：一旦注入，不可再变
    private final CacheService cacheService;

    // 构造器参数就是依赖清单，一目了然
    public UserServiceImpl(UserMapper userMapper, CacheService cacheService) {
        this.userMapper = userMapper;
        this.cacheService = cacheService;
    }
}

// 生产级：构造器注入 + final 字段 + Lombok
// @RequiredArgsConstructor 等价于手写「包含所有 final 字段的构造器」
@Service
@RequiredArgsConstructor
public class UserServiceImpl implements UserService {
    private final UserMapper userMapper;      // final：不可变，必然注入
    private final CacheService cacheService;
    // Lombok 自动生成：public UserServiceImpl(UserMapper userMapper, CacheService cacheService) { ... }
}

@Service
@RequiredArgsConstructor
public class AService {
    private final BService bService;   // A 依赖 B
}

@Service
@RequiredArgsConstructor
public class BService {
    private final AService aService;   // B 依赖 A
}

public interface UserService { void register(String username); }

// 实现一：默认实现
@Service
@Primary                       // 解法 2：标记为主候选，类型匹配时优先选它
public class UserServiceImpl implements UserService { ... }

// 实现二：VIP 用户的特殊实现
@Service
public class VipUserServiceImpl implements UserService { ... }

@Service
@RequiredArgsConstructor
public class VipOrderFacade {
    // 指定注入 Bean 名为 "vipUserServiceImpl" 的那个实现
    private final @Qualifier("vipUserServiceImpl") UserService userService;
}

@Primary
@Service
public class UserServiceImpl implements UserService { ... }

@Service
@RequiredArgsConstructor
public class UserServiceRouter {
    // 容器会把所有 UserService 实现收集成一个 Map，key 是 beanName
    private final Map<String, UserService> userServiceMap;

    public UserService pick(String type) {
        return userServiceMap.getOrDefault(type, userServiceMap.get("userServiceImpl"));
    }
}

// 最小可用：一个接口 + 一个实现 + 一个消费方，三行看穿 DI
public interface GreetingService { String greet(String name); }

@Service
public class GreetingServiceImpl implements GreetingService {
    @Override
    public String greet(String name) { return "Hello, " + name; }
}

@RestController
@RequiredArgsConstructor
public class GreetingController {
    private final GreetingService greetingService;   // 容器注入实现

    @GetMapping("/greet")
    public String greet(@RequestParam String name) {
        return greetingService.greet(name);
    }
}

// 生产级：UserService 接口 + 实现，业务失败抛 BizException，由全局异常处理器统一兜底
public interface UserService {
    Long register(RegisterDTO dto);
}

// DTO：入参对象，带 JSR-303 校验注解，禁止直接用 Entity 接请求
@Data
public class RegisterDTO {
    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度需在 3-20 之间")
    private String username;
}

@Service
@Slf4j
@RequiredArgsConstructor
public class UserServiceImpl implements UserService {
    // 构造器注入：依赖不可变、天然非空、易测试
    private final UserMapper userMapper;
    private final CacheService cacheService;

    @Override
    public Long register(RegisterDTO dto) {
        // 生产习惯：业务校验失败抛 BizException，而不是返回 null 或 -1
        if (userMapper.existsByUsername(dto.getUsername())) {
            throw new BizException(40010, "用户名已存在");
        }
        User user = User.from(dto);
        userMapper.insert(user);
        cacheService.evictUserCache(user.getId());   // 写入后失效缓存，保证一致性
        log.info("用户注册成功: id={}, username={}", user.getId(), dto.getUsername());
        return user.getId();
    }
}

// 字段注入：能跑，但依赖不可变、难测试、易 NPE、隐藏依赖
@Service
public class FieldInjectionService {
    @Autowired
    private UserMapper userMapper;   // 依赖藏在字段里，构造器看不到，final 也加不上
}

// Setter 注入：依赖可变，@Autowired 忘加时字段就是 null，编译不报错、运行才炸
@Service
public class SetterInjectionService {
    private UserMapper userMapper;

    @Autowired
    public void setUserMapper(UserMapper userMapper) {
        this.userMapper = userMapper;
    }
}

// 构造器注入：依赖不可变、非空、显式、易测试
@Service
public class ConstructorInjectionService {
    private final UserMapper userMapper;   // final：只赋值一次

    public ConstructorInjectionService(UserMapper userMapper) {
        this.userMapper = userMapper;
    }
}

// 生产级：用 @Bean 装配第三方对象（RestTemplate 属于 Spring 但需要定制超时，不能用默认值）
@Configuration
public class BeanConfig {

    // @Bean 方法返回的对象会被注册成 Bean，方法名默认就是 beanName
    @Bean
    public RestTemplate restTemplate() {
        return new RestTemplateBuilder()
                .setConnectTimeout(Duration.ofSeconds(3))  // 连接超时 3 秒
                .setReadTimeout(Duration.ofSeconds(5))     // 读取超时 5 秒
                .build();
    }
}

@Scope("prototype")   // 每次注入都拿新实例
@Component
public class PrototypeBean { ... }

@Service
@RequiredArgsConstructor
public class OrderService {
    // 期望每次调用都拿到新 PrototypeBean，实际不是！
    private final PrototypeBean prototypeBean;
}

// 解法 1：ObjectProvider 每次显式获取
@Service
@RequiredArgsConstructor
public class OrderService {
    private final ObjectProvider<PrototypeBean> prototypeProvider;

    public void handle() {
        PrototypeBean bean = prototypeProvider.getObject();   // 每次 get 都是新实例
    }
}

// 解法 2：@Lookup 方法注入（抽象方法由容器生成实现）
@Service
public abstract class OrderService2 {
    @Lookup
    public abstract PrototypeBean createPrototype();   // 每次调用返回新实例

    public void handle() {
        PrototypeBean bean = createPrototype();
    }
}

@Service
@Slf4j
public class CacheWarmService {

    // @PostConstruct：Bean 创建、依赖注入完成后执行，适合初始化缓存/加载配置
    @PostConstruct
    public void init() {
        log.info("Bean 初始化完成，开始预热缓存");
        // loadHotDataToCache();
    }

    // @PreDestroy：容器关闭、Bean 销毁前执行，适合释放连接、关闭线程池
    @PreDestroy
    public void destroy() {
        log.info("Bean 即将销毁，释放资源");
        // threadPool.shutdown();
    }
}

// 1) 实现 Aware 接口，观察容器回调
@Component
@Slf4j
public class LifecycleBean implements BeanNameAware, InitializingBean, DisposableBean {

    public LifecycleBean() {
        log.info("① 实例化：构造器被调用");
    }

    // BeanNameAware：容器把 beanName 告诉你
    @Override
    public void setBeanName(String name) {
        log.info("③ Aware 回调：beanName = {}", name);
    }

    // @PostConstruct：比 InitializingBean 更推荐（不耦合 Spring 接口）
    @PostConstruct
    public void postConstruct() {
        log.info("⑤ 初始化：@PostConstruct 执行");
    }

    // InitializingBean 接口回调，在 @PostConstruct 之后
    @Override
    public void afterPropertiesSet() {
        log.info("⑤ 初始化：afterPropertiesSet 执行");
    }

    @PreDestroy
    public void preDestroy() {
        log.info("⑧ 销毁：@PreDestroy 执行");
    }

    @Override
    public void destroy() {
        log.info("⑧ 销毁：DisposableBean#destroy 执行");
    }
}

// 2) 自定义 BeanPostProcessor，观察它在初始化前后的介入点
@Component
@Slf4j
public class LogBeanPostProcessor implements BeanPostProcessor {

    @Override
    public Object postProcessBeforeInitialization(Object bean, String beanName) {
        if ("lifecycleBean".equals(beanName)) {
            log.info("④ BeanPostProcessor#before 执行：beanName = {}", beanName);
        }
        return bean;   // 必须返回 bean（或它的代理），否则容器里就没有这个对象了
    }

    @Override
    public Object postProcessAfterInitialization(Object bean, String beanName) {
        if ("lifecycleBean".equals(beanName)) {
            log.info("⑥ BeanPostProcessor#after 执行：beanName = {}", beanName);
        }
        return bean;
    }
}

@Configuration
public class BeanConfig {

    // 用 @ConfigurationProperties 绑定配置，避免 @Value 满天飞（类型安全 + 可校验）
    @Bean
    @ConfigurationProperties(prefix = "app.thread-pool")
    public ThreadPoolTaskExecutor taskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(4);                          // 核心线程数
        executor.setMaxPoolSize(8);                           // 最大线程数
        executor.setQueueCapacity(200);                       // 队列容量
        executor.setThreadNamePrefix("app-exec-");            // 线程名前缀，排障时一眼认出
        executor.setRejectedExecutionHandler(
                new ThreadPoolExecutor.CallerRunsPolicy());    // 队列满时由调用线程执行，防止丢任务
        return executor;
    }
}

app:
  thread-pool:
    core-pool-size: 8
    max-pool-size: 16

@Configuration
public class BeanConfig {

    @Bean
    public DataSource dataSource() { return new HikariDataSource(); }

    @Bean
    public JdbcTemplate jdbcTemplate() {
        // 这里调用的 dataSource() 不是「再 new 一个」，而是容器里那个单例
        return new JdbcTemplate(dataSource());
    }
}

@PostConstruct
public void init() { ... }   // 签名必须是 void 且无参数，private 也允许

@PreDestroy
public void destroy() { ... }

// 反例：横切逻辑散落在每个方法里，重复且污染业务
public OrderVO createOrder(CreateOrderDTO dto) {
    long start = System.currentTimeMillis();       // 计时开始
    log.info("调用 createOrder, 参数={}", dto);      // 入参日志
    checkPermission();                              // 权限校验
    try {
        Order order = orderMapper.insert(...);      // 真正的业务
        return OrderVO.from(order);
    } catch (Exception e) {
        log.error("createOrder 失败", e);
        throw e;
    } finally {
        log.info("createOrder 耗时 {}ms", System.currentTimeMillis() - start);
    }
}

@Around("execution(* com.example.demo.service..*.*(..))")
//        └修饰符(可省)┘└──返回类型──┘└──包──┘└类┘└方法┘└参数┘
//  语法：execution([修饰符] 返回类型 包.类.方法(参数))

execution(* com.example.demo.service..*.*(..))         // service 包及子包下所有类的所有方法
execution(* com.example.demo.service.UserService.*(..)) // UserService 接口的所有方法
execution(* com.example.demo..*.insert*(..))            // 任意包下 insert 开头的方法

@Aspect      // 声明这是一个切面
@Component   // 切面本身也要注册成 Bean 才能被容器管理
@Slf4j
public class CostAspect {

    // 环绕通知：ProceedingJoinPoint 代表被拦截的方法
    @Around("execution(* com.example.demo.service..*.*(..))")
    public Object around(ProceedingJoinPoint pjp) throws Throwable {
        long start = System.currentTimeMillis();
        Object result = pjp.proceed();   // ★ 放行，执行目标方法；不调用它，目标方法就不执行
        long cost = System.currentTimeMillis() - start;
        log.info("{}.{} 耗时 {}ms",
                pjp.getTarget().getClass().getSimpleName(),   // 目标类名
                pjp.getSignature().getName(),                  // 方法名
                cost);
        return result;   // 把目标方法的结果原样返回给调用方
    }
}

@Aspect
@Component
@Slf4j
public class WebLogAspect {

    // 拦截 Controller 层所有方法：记录入参、耗时、异常
    @Around("execution(* com.example.demo.controller..*.*(..))")
    public Object log(ProceedingJoinPoint pjp) throws Throwable {
        String method = pjp.getTarget().getClass().getSimpleName() + "." + pjp.getSignature().getName();
        long start = System.currentTimeMillis();
        try {
            Object result = pjp.proceed();
            // 生产注意：入参里可能有敏感字段（密码/token），脱敏后再打日志
            log.info("[OK] {} 耗时 {}ms", method, System.currentTimeMillis() - start);
            return result;
        } catch (Throwable t) {
            // 异常要打全栈，同时原样抛出，交给全局异常处理器统一转 ApiResult
            log.error("[FAIL] {} 耗时 {}ms", method, System.currentTimeMillis() - start, t);
            throw t;
        }
    }
}

// 自定义注解：标在方法上，表示「我要记录这个方法耗时」
@Target(ElementType.METHOD)   // 只能标在方法上
@Retention(RetentionPolicy.RUNTIME)  // 运行时保留，AOP 靠反射读取
public @interface LogExecutionTime {
    String value() default "";   // 可选：给这段耗时起个业务名
}

@Aspect
@Component
@Slf4j
public class LogExecutionTimeAspect {

    // @annotation(logExecutionTime)：拦截所有标注了该注解的方法，
    // 注解对象通过同名参数传入
    @Around("@annotation(logExecutionTime)")
    public Object log(ProceedingJoinPoint pjp, LogExecutionTime logExecutionTime) throws Throwable {
        long start = System.currentTimeMillis();
        Object result = pjp.proceed();
        String label = logExecutionTime.value().isEmpty()
                ? pjp.getSignature().getName()
                : logExecutionTime.value();
        log.info("[耗时统计] {} 耗时 {}ms", label, System.currentTimeMillis() - start);
        return result;
    }
}

@Service
public class OrderServiceImpl implements OrderService {

    @Override
    @LogExecutionTime("创建订单")   // 该方法会被切面自动记录耗时
    public OrderVO createOrder(CreateOrderDTO dto) {
        // 业务代码里完全没有计时/日志，横切逻辑被切面接管
        ...
    }
}

@Service
@Slf4j
public class OrderServiceImpl implements OrderService {

    @Override
    public void placeOrder(Long orderId) {
        // ★ 自调用：this.methodA() 调用本类另一个方法
        // 这里调用的 reduceStock 不经过代理，其上的 @Transactional / 切面全部失效
        this.reduceStock(orderId);
    }

    @LogExecutionTime("扣减库存")
    public void reduceStock(Long orderId) {
        // 期望：这里被切面记录耗时
        // 实际：placeOrder 内部 this.reduceStock 不经过代理，切面静默失效
    }
}

// 解法 1：拆分到另一个 Bean（推荐，从根上消除自调用）
@Service
@RequiredArgsConstructor
public class OrderServiceImpl implements OrderService {
    private final StockService stockService;   // 把被增强的逻辑拆到独立 Bean

    @Override
    public void placeOrder(Long orderId) {
        stockService.reduceStock(orderId);   // 跨 Bean 调用 → 走代理 → 切面/事务生效
    }
}

@Service
public class StockServiceImpl implements StockService {
    @LogExecutionTime("扣减库存")
    @Override
    public void reduceStock(Long orderId) { ... }
}

// 解法 2：注入自身代理（特殊场景兜底，慎用：耦合容器、易循环依赖）
@Service
@RequiredArgsConstructor
public class OrderServiceImpl implements OrderService {
    private final OrderService self;   // 注入自己（容器会把代理对象注入进来）

    @Override
    public void placeOrder(Long orderId) {
        self.reduceStock(orderId);   // 通过代理调用 → 切面/事务生效
    }

    @LogExecutionTime("扣减库存")
    @Override
    public void reduceStock(Long orderId) { ... }
}

@Service
public class OrderServiceImpl implements OrderService {

    @LogExecutionTime("私有方法")
    private void internalMethod() { ... }   // ★ private + 切面：不生效
}

// within：拦截某个类（及其子类）的所有方法
@Before("within(com.example.demo.service.UserServiceImpl)")

// @within：拦截「类上标注了某注解」的类的所有方法（匹配类注解，非方法注解）
@Before("@within(org.springframework.stereotype.Service)")

// 组合：&&（且）、||（或）、!（非）
@Around("execution(* com.example.demo.service..*.*(..)) && !execution(* com.example.demo.service..*.internal*(..))")

@Aspect
@Component
public class WebLogAspect {

    // @Pointcut 定义具名切点，供多个通知复用，避免表达式到处复制
    @Pointcut("execution(* com.example.demo.controller..*.*(..))")
    public void controllerLayer() {}

    @Before("controllerLayer()")
    public void before(JoinPoint jp) { ... }   // 前置通知用 JoinPoint（没有 proceed 方法）

    @Around("controllerLayer()")
    public Object around(ProceedingJoinPoint pjp) throws Throwable { ... }  // 环绕用 ProceedingJoinPoint
}

spring:
  aop:
    proxy-target-class: true   # 默认 true：CGLIB；false 则优先 JDK 动态代理（要求接口）

// 代码方式（与上面配置等价）
@EnableAspectJAutoProxy(proxyTargetClass = true)

@Order(1)   // 先执行，包在最外层
@Aspect
@Component
public class LogAspect { ... }

@Order(2)   // 后执行，包在内层
@Aspect
@Component
public class PermissionAspect { ... }

// 反例：支付方法里串行耦合了 4 件事，加一个新动作就得改这里
@Transactional
public void pay(Long orderId) {
    orderMapper.markPaid(orderId);      // 核心动作：改订单状态
    notifyService.sendSms(userId);       // 动作 2
    pointService.addPoints(userId, 100); // 动作 3
    syncService.syncToDataWarehouse(orderId); // 动作 4
}

// 1) 定义事件：携带业务数据
public class OrderPaidEvent extends ApplicationEvent {
    private final Long orderId;
    private final Long userId;

    public OrderPaidEvent(Object source, Long orderId, Long userId) {
        super(source);              // source 是发布者对象，框架要求
        this.orderId = orderId;
        this.userId = userId;
    }

    public Long getOrderId() { return orderId; }
    public Long getUserId() { return userId; }
}

// 2) 发布事件：注入 ApplicationEventPublisher
@Service
@RequiredArgsConstructor
public class OrderServiceImpl implements OrderService {
    private final ApplicationEventPublisher publisher;

    public void pay(Long orderId, Long userId) {
        // ... 改订单状态 ...
        publisher.publishEvent(new OrderPaidEvent(this, orderId, userId));  // 发布
    }
}

// 3) 监听事件
@Component
@Slf4j
public class OrderPaidListener {

    // @EventListener：容器会自动把匹配类型的事件传给该方法（默认同步执行）
    @EventListener
    public void onPaid(OrderPaidEvent event) {
        log.info("收到订单支付事件，发短信通知: orderId={}", event.getOrderId());
    }
}

// 反例：事务未提交就同步消费，可能读到脏数据，且监听器异常会连累主事务
@EventListener
public void onPaid(OrderPaidEvent event) { ... }

@Component
@Slf4j
public class OrderPaidListener {

    // 默认 phase = TransactionPhase.AFTER_COMMIT：主事务提交成功后才执行
    // 好处：① 此时数据一定已落库；② 监听器异常不会让主事务回滚
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void onPaidAfterCommit(OrderPaidEvent event) {
        log.info("事务已提交，开始发通知/加积分: orderId={}", event.getOrderId());
        notifyService.sendSms(event.getUserId());
        pointService.addPoints(event.getUserId(), 100);
    }

    // fallbackExecution = true：发布方没有事务时也能触发（否则会被忽略）
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT, fallbackExecution = true)
    public void onPaidNoTx(OrderPaidEvent event) { ... }
}

// 1) 启动类上加 @EnableAsync
@SpringBootApplication
@EnableAsync
public class DemoApplication { ... }

// 2) 监听器方法加 @Async，交给线程池异步执行
@Component
@Slf4j
public class OrderPaidListener {

    // @Async：用第 4.2.5 节配置的 taskExecutor 线程池执行，不阻塞主线程
    @Async
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void onPaidAsync(OrderPaidEvent event) {
        log.info("异步发短信: orderId={}", event.getOrderId());
    }
}

// 接口式监听器：实现 ApplicationListener<事件类型>
@Component
public class LegacyListener implements ApplicationListener<OrderPaidEvent> {
    @Override
    public void onApplicationEvent(OrderPaidEvent event) {
        log.info("接口式监听: orderId={}", event.getOrderId());
    }
}

@Component
public class OrderPaidListeners {

    @Order(1)   // 先发通知
    @EventListener
    public void sendNotify(OrderPaidEvent e) { ... }

    @Order(2)   // 再加积分
    @EventListener
    public void addPoints(OrderPaidEvent e) { ... }
}

// 只处理 orderId 非空的事件（表达式里的 #event 指方法参数）
@EventListener(condition = "#event.orderId != null")
public void onPaid(OrderPaidEvent event) { ... }

// REQUIRED（默认）：transfer 与它内部调用的方法共用同一个事务
@Transactional   // 等价于 @Transactional(propagation = Propagation.REQUIRED)
public void transfer(Long fromId, Long toId, BigDecimal amount) {
    accountMapper.deduct(fromId, amount);   // 若这里抛出异常，add 也不会生效
    accountMapper.add(toId, amount);
}

// REQUIRES_NEW：独立事务，不受外层回滚影响（典型：审计日志）
@Transactional(propagation = Propagation.REQUIRES_NEW)
public void saveAuditLog(String content) { ... }

// 生产一般显式指定，避免依赖不同数据库的默认值差异
@Transactional(isolation = Isolation.REPEATABLE_READ)
public void transfer(Long fromId, Long toId, BigDecimal amount) { ... }

@Service
@Slf4j
@RequiredArgsConstructor
public class AccountServiceImpl implements AccountService {

    private final JdbcTemplate jdbcTemplate;

    // 转账：扣 A + 加 B，任一步失败都整体回滚
    @Override
    @Transactional   // 默认 REQUIRED：整个方法一个事务
    public void transfer(Long fromId, Long toId, BigDecimal amount) {
        // 1) 扣款：余额不足时抛异常，触发回滚
        int updated = jdbcTemplate.update(
                "UPDATE t_account SET balance = balance - ? WHERE id = ? AND balance >= ?",
                amount, fromId, amount);
        if (updated == 0) {
            // 抛业务异常，事务回滚（扣款不会生效）
            throw new BizException(ErrorCode.INSUFFICIENT_BALANCE);
        }
        // 2) 入账
        jdbcTemplate.update(
                "UPDATE t_account SET balance = balance + ? WHERE id = ?",
                amount, toId);
        log.info("转账成功: {} -> {}, 金额={}", fromId, toId, amount);
    }
}

@Service
@RequiredArgsConstructor
public class AccountServiceImpl implements AccountService {

    // 外部调用 createAndTransfer()，它内部调用了带 @Transactional 的 doTransfer()
    public void createAndTransfer(Long fromId, Long toId, BigDecimal amount) {
        this.doTransfer(fromId, toId, amount);   // ★ 自调用：事务不生效！
    }

    @Transactional
    public void doTransfer(Long fromId, Long toId, BigDecimal amount) {
        // 期望有事务，实际 this 调用绕过代理，事务静默失效
    }
}

@Service
public class AccountServiceImpl {
    @Transactional
    private void doTransfer(...) { ... }   // ★ private：事务不生效
}

@Transactional
public void transfer(Long fromId, Long toId, BigDecimal amount) {
    try {
        jdbcTemplate.update("UPDATE t_account SET balance = balance - ? WHERE id = ?", amount, fromId);
        int i = 1 / 0;   // 抛 ArithmeticException（RuntimeException）
    } catch (Exception e) {
        // ★ 吞掉异常：Spring 感知不到异常，事务照常提交，数据不一致
        log.error("转账异常", e);
    }
}

@Transactional
public void transfer(Long fromId, Long toId, BigDecimal amount) {
    try {
        ... 
    } catch (Exception e) {
        log.error("转账异常，标记回滚", e);
        // 显式标记当前事务只回滚，然后（可选）把异常转成业务异常上抛
        TransactionAspectSupport.currentTransactionStatus().setRollbackOnly();
        throw new BizException(ErrorCode.SYSTEM_ERROR);
    }
}

// 反例：抛出受检异常，事务不会回滚
@Transactional
public void transfer(...) throws IOException {
    // 业务代码抛出 IOException（受检异常）→ 事务提交，数据不一致
}

// 正例：显式声明回滚范围，覆盖所有异常
@Transactional(rollbackFor = Exception.class)
public void transfer(...) { ... }

@Transactional(readOnly = true)
public UserVO getUser(Long id) { ... }

@Transactional(timeout = 5)   // 超过 5 秒强制回滚，单位秒
public void transfer(...) { ... }

@Service
@RequiredArgsConstructor
public class OrderServiceImpl implements OrderService {

    private final AuditService auditService;

    @Transactional
    public void cancelOrder(Long orderId) {
        orderMapper.cancel(orderId);               // 主事务：取消订单
        auditService.record("订单取消");             // 独立事务：主事务回滚，日志也落库
        throw new BizException(ErrorCode.SYSTEM_ERROR);  // 故意让主事务回滚
        // 结果：订单取消被回滚，但审计日志因 REQUIRES_NEW 已提交
    }
}

@Service
public class AuditServiceImpl implements AuditService {
    @Override
    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void record(String content) {
        // 挂起外层事务，新建独立事务写审计日志
    }
}

// common/ApiResult.java —— 统一响应体：所有 Controller 返回该结构
package com.example.demo.common;

import lombok.Data;
import org.slf4j.MDC;

@Data
public class ApiResult<T> {
    private int code;        // 0=成功，非 0=错误码
    private String message;  // 提示信息
    private T data;          // 业务数据
    private String traceId;  // 链路追踪 id

    public static <T> ApiResult<T> ok(T data) {
        ApiResult<T> r = new ApiResult<>();
        r.setCode(ErrorCode.SUCCESS.getCode());
        r.setMessage(ErrorCode.SUCCESS.getMessage());
        r.setData(data);
        r.setTraceId(MDC.get("traceId"));
        return r;
    }
    public static <T> ApiResult<T> ok() {
        return ok(null);
    }
    public static <T> ApiResult<T> fail(int code, String message) {
        ApiResult<T> r = new ApiResult<>();
        r.setCode(code);
        r.setMessage(message);
        r.setTraceId(MDC.get("traceId"));
        return r;
    }
    public static <T> ApiResult<T> fail(ErrorCode ec) {
        return fail(ec.getCode(), ec.getMessage());
    }
}

// common/ErrorCode.java —— 统一错误码：基础码必须保留且数值不变
package com.example.demo.common;

public enum ErrorCode {
    SUCCESS(0, "success"),
    PARAM_ERROR(40001, "参数错误"),
    UNAUTHORIZED(40101, "未登录或登录已过期"),
    FORBIDDEN(40301, "无权限访问"),
    USER_NOT_FOUND(40401, "用户不存在"),
    SYSTEM_ERROR(50000, "系统繁忙，请稍后重试"),
    // 本篇业务扩展
    INSUFFICIENT_BALANCE(50001, "账户余额不足"),
    ;

    private final int code;
    private final String message;

    ErrorCode(int code, String message) {
        this.code = code;
        this.message = message;
    }

    public int getCode() { return code; }

    public String getMessage() { return message; }
}

// exception/BizException.java —— 业务异常：业务代码抛出，由全局处理器统一转 ApiResult
package com.example.demo.exception;

import com.example.demo.common.ErrorCode;

public class BizException extends RuntimeException {
    private final int code;

    public BizException(ErrorCode ec) {
        super(ec.getMessage());
        this.code = ec.getCode();
    }

    public BizException(int code, String message) {
        super(message);
        this.code = code;
    }

    public int getCode() { return code; }
}

// exception/GlobalExceptionHandler.java —— 全局异常处理：兜底异常对外只给模糊提示
package com.example.demo.exception;

import com.example.demo.common.ApiResult;
import com.example.demo.common.ErrorCode;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {

    // 业务异常：code/message 直接透传给前端
    @ExceptionHandler(BizException.class)
    public ApiResult<Void> handleBiz(BizException e) {
        log.warn("业务异常: code={}, message={}", e.getCode(), e.getMessage());
        return ApiResult.fail(e.getCode(), e.getMessage());
    }

    // 参数校验异常（@Valid 触发）：取第一条失败信息返回
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ApiResult<Void> handleValid(MethodArgumentNotValidException e) {
        String msg = e.getBindingResult().getFieldErrors().stream()
                .findFirst()
                .map(f -> f.getField() + " " + f.getDefaultMessage())
                .orElse(ErrorCode.PARAM_ERROR.getMessage());
        log.warn("参数校验失败: {}", msg);
        return ApiResult.fail(ErrorCode.PARAM_ERROR.getCode(), msg);
    }

    // 兜底异常：对外返回模糊提示，详细堆栈只进日志，避免泄露内部结构
    @ExceptionHandler(Exception.class)
    public ApiResult<Void> handleOther(Exception e) {
        log.error("系统异常", e);
        return ApiResult.fail(ErrorCode.SYSTEM_ERROR);
    }
}

// entity/User.java —— 数据库实体（映射 t_user 表）
package com.example.demo.entity;

import lombok.Data;

@Data
public class User {
    private Long id;
    private String username;
}

// dto/RegisterDTO.java —— 入参：带 JSR-303 校验注解，禁止直接接 Entity
package com.example.demo.dto;

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import lombok.Data;

@Data
public class RegisterDTO {
    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度需在 3-20 之间")
    private String username;
}

// vo/UserVO.java —— 出参：按需裁剪字段，不暴露内部实体细节
package com.example.demo.vo;

import lombok.Data;

@Data
public class UserVO {
    private Long id;
    private String username;

    public static UserVO from(Long id, String username) {
        UserVO vo = new UserVO();
        vo.setId(id);
        vo.setUsername(username);
        return vo;
    }
}

// mapper/UserMapper.java —— 数据访问：本篇用 JdbcTemplate 演示（后续阶段再换 MyBatis-Plus）
package com.example.demo.mapper;

import lombok.RequiredArgsConstructor;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.jdbc.support.GeneratedKeyHolder;
import org.springframework.jdbc.support.KeyHolder;
import org.springframework.stereotype.Repository;

import java.sql.PreparedStatement;
import java.sql.Statement;

@Repository   // @Repository：数据访问层，提供持久层异常翻译
@RequiredArgsConstructor
public class UserMapper {

    private final JdbcTemplate jdbcTemplate;

    public Long insert(String username) {
        KeyHolder keyHolder = new GeneratedKeyHolder();
        jdbcTemplate.update(con -> {
            PreparedStatement ps = con.prepareStatement(
                    "INSERT INTO t_user(username) VALUES (?)", Statement.RETURN_GENERATED_KEYS);
            ps.setString(1, username);
            return ps;
        }, keyHolder);
        // 拿到自增主键
        Number key = keyHolder.getKey();
        return key == null ? null : key.longValue();
    }

    public boolean existsByUsername(String username) {
        Integer count = jdbcTemplate.queryForObject(
                "SELECT COUNT(*) FROM t_user WHERE username = ?", Integer.class, username);
        return count != null && count > 0;
    }
}

// service/UserService.java —— 接口
package com.example.demo.service;

import com.example.demo.dto.RegisterDTO;
import com.example.demo.vo.UserVO;

public interface UserService {
    UserVO register(RegisterDTO dto);
}

// service/impl/UserServiceImpl.java —— 实现：构造器注入 + @Transactional + 发布事件
package com.example.demo.service.impl;

import com.example.demo.dto.RegisterDTO;
import com.example.demo.event.UserRegisteredEvent;
import com.example.demo.exception.BizException;
import com.example.demo.mapper.UserMapper;
import com.example.demo.service.UserService;
import com.example.demo.vo.UserVO;
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 UserServiceImpl implements UserService {

    private final UserMapper userMapper;
    private final ApplicationEventPublisher publisher;   // 事件发布器

    @Override
    @Transactional   // 注册整体在一个事务内：落库 + 发布事件要么都成功，要么都回滚
    public UserVO register(RegisterDTO dto) {
        // 业务校验：用户名重复抛业务异常（由全局处理器转 ApiResult）
        if (userMapper.existsByUsername(dto.getUsername())) {
            throw new BizException(40010, "用户名已存在");
        }
        Long id = userMapper.insert(dto.getUsername());
        // 发布事件：监听器在「事务提交后」才异步消费，不拖慢、不连累本事务
        publisher.publishEvent(new UserRegisteredEvent(this, id, dto.getUsername()));
        log.info("用户注册成功: id={}, username={}", id, dto.getUsername());
        return UserVO.from(id, dto.getUsername());
    }
}

// event/UserRegisteredEvent.java
package com.example.demo.event;

import org.springframework.context.ApplicationEvent;

public class UserRegisteredEvent extends ApplicationEvent {
    private final Long userId;
    private final String username;

    public UserRegisteredEvent(Object source, Long userId, String username) {
        super(source);
        this.userId = userId;
        this.username = username;
    }

    public Long getUserId() { return userId; }
    public String getUsername() { return username; }
}

// event/UserRegisteredListener.java —— 事务提交后 + 异步发通知
package com.example.demo.event;

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
public class UserRegisteredListener {

    // ① @TransactionalEventListener(AFTER_COMMIT)：数据落库后才消费，异常不连累主事务
    // ② @Async：走第 4.2.5 节配置的线程池，不阻塞注册接口
    @Async
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void sendWelcomeNotice(UserRegisteredEvent event) {
        // 生产里这里会对接短信/邮件/推送服务
        log.info("异步发送欢迎通知: userId={}, username={}", event.getUserId(), event.getUsername());
    }
}

// aspect/WebLogAspect.java —— 接口耗时 + 异常日志
package com.example.demo.aspect;

import lombok.extern.slf4j.Slf4j;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.springframework.stereotype.Component;

@Slf4j
@Aspect
@Component
public class WebLogAspect {

    @Around("execution(* com.example.demo.controller..*.*(..))")
    public Object log(ProceedingJoinPoint pjp) throws Throwable {
        String method = pjp.getTarget().getClass().getSimpleName() + "." + pjp.getSignature().getName();
        long start = System.currentTimeMillis();
        try {
            Object result = pjp.proceed();
            log.info("[OK] {} 耗时 {}ms", method, System.currentTimeMillis() - start);
            return result;
        } catch (Throwable t) {
            log.error("[FAIL] {} 耗时 {}ms", method, System.currentTimeMillis() - start, t);
            throw t;   // 原样抛出，交给 GlobalExceptionHandler
        }
    }
}

// config/BeanConfig.java —— 线程池 @Bean（给 @Async 用）
package com.example.demo.config;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;

import java.util.concurrent.ThreadPoolExecutor;

@Configuration
public class BeanConfig {

    @Bean
    @ConfigurationProperties(prefix = "app.thread-pool")
    public ThreadPoolTaskExecutor taskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(4);
        executor.setMaxPoolSize(8);
        executor.setQueueCapacity(200);
        executor.setThreadNamePrefix("app-exec-");
        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
        return executor;
    }
}

// controller/UserController.java
package com.example.demo.controller;

import com.example.demo.common.ApiResult;
import com.example.demo.dto.RegisterDTO;
import com.example.demo.service.UserService;
import com.example.demo.vo.UserVO;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/users")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;   // 构造器注入

    // @Valid 触发 DTO 校验，失败抛 MethodArgumentNotValidException，由全局处理器兜底
    @PostMapping("/register")
    public ApiResult<UserVO> register(@Valid @RequestBody RegisterDTO dto) {
        return ApiResult.ok(userService.register(dto));
    }
}