【阶段 4】数据访问：MyBatis-Plus、事务与缓存

# 确认版本
java -version          # 期望 openjdk 17.x
mysql --version        # 期望 8.0.x
redis-cli --version    # 期望 7.x

# 启动 MySQL 与 Redis（Docker 方式，二选一即可）
docker run -d --name mysql8 
  -e MYSQL_ROOT_PASSWORD=root123456 
  -e MYSQL_DATABASE=shop 
  -p 3306:3306 mysql:8.0

docker run -d --name redis7 -p 6379:6379 redis:7

# 创建示例库（进入 mysql 容器执行）
mysql -uroot -proot123456 -e "CREATE DATABASE IF NOT EXISTS shop DEFAULT CHARACTER SET utf8mb4;"

<properties>
    <java.version>17</java.version>
    <spring-boot.version>3.2.5</spring-boot.version>
    <mybatis-plus.version>3.5.7</mybatis-plus.version>
    <dynamic-datasource.version>4.3.0</dynamic-datasource.version>
</properties>

<dependencies>
    <!-- Web：提供 Controller / MVC 能力 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- 校验：DTO 上的 JSR-303 注解 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>

    <!-- JDBC：JdbcTemplate 与 DataSource 自动装配 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-jdbc</artifactId>
    </dependency>

    <!-- MyBatis-Plus：注意是 boot3 专用 starter，boot2 用的是另一个 artifact -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
        <version>${mybatis-plus.version}</version>
    </dependency>

    <!-- Spring Data JPA：本篇第 3 章与 MP 对比使用 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>

    <!-- Redis + Cache 抽象：本篇第 5 章缓存使用 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-redis</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-cache</artifactId>
    </dependency>

    <!-- 多数据源：本篇第 6 章读写分离使用 -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>dynamic-datasource-spring-boot3-starter</artifactId>
        <version>${dynamic-datasource.version}</version>
    </dependency>

    <!-- Flyway：本篇第 7 章数据库迁移使用 -->
    <dependency>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-core</artifactId>
    </dependency>
    <dependency>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-mysql</artifactId>
    </dependency>

    <!-- Lombok：@Data / @Slf4j / @RequiredArgsConstructor -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

spring:
  datasource:
    # ${DB_HOST:localhost} 表示：读环境变量 DB_HOST，未设置则用默认值 localhost
    url: jdbc:mysql://${DB_HOST:localhost}:3306/shop?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf8&rewriteBatchedStatements=true
    username: ${DB_USER:root}
    password: ${DB_PASSWORD:root123456}
    driver-class-name: com.mysql.cj.jdbc.Driver
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 30000
      max-lifetime: 1800000
      idle-timeout: 600000
      pool-name: ShopHikariPool

  data:
    redis:
      host: ${REDIS_HOST:localhost}
      port: ${REDIS_PORT:6379}
      # 生产环境必须设密码，本地开发可省略
      password: ${REDIS_PASSWORD:}
      timeout: 3000ms

  jpa:
    hibernate:
      ddl-auto: none   # 生产禁用自动建表，表结构交给 Flyway 管理
    open-in-view: false  # 关闭 OSIV，避免连接被长事务长期占用
    show-sql: false

mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true   # 下划线列名自动映射到驼峰字段
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl  # 开发期打印 SQL，生产换 logback
  global-config:
    db-config:
      id-type: auto            # 主键自增
      logic-delete-field: deleted   # 逻辑删除字段（配合 @TableLogic）
      logic-delete-value: 1         # 删除后置为 1
      logic-not-delete-value: 0     # 未删除为 0

// 最小可用：直接用 JdbcTemplate 查一行数据
@RestController
@RequiredArgsConstructor
public class HealthController {

    // 构造器注入 JdbcTemplate，它底层通过 HikariCP 获取连接
    private final JdbcTemplate jdbcTemplate;

    @GetMapping("/db/health")
    public ApiResult<String> health() {
        // queryForObject 内部流程：从池借连接 -> 执行 SQL -> 归还连接
        Integer one = jdbcTemplate.queryForObject("SELECT 1", Integer.class);
        return ApiResult.ok("db is alive, result=" + one);
    }
}

spring:
  datasource:
    url: jdbc:mysql://${DB_HOST:localhost}:3306/shop?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf8&rewriteBatchedStatements=true
    username: ${DB_USER:root}
    password: ${DB_PASSWORD:root123456}
    hikari:
      # 池中最大连接数。核心调优项，不是越大越好，见下文解释
      maximum-pool-size: 20
      # 池中最小空闲连接数，用于预热，避免突发流量时临时创建连接的延迟
      minimum-idle: 5
      # 获取连接的超时时间。超过这个时间还没拿到连接就抛 SQLTransientConnectionException
      connection-timeout: 30000
      # 连接最大存活时间，必须小于 MySQL 的 wait_timeout（默认 8 小时），
      # 否则连接被 MySQL 主动断开后，池子还拿着一条死连接
      max-lifetime: 1800000
      # 空闲连接超过这个时间会被回收（但不会低于 minimum-idle）
      idle-timeout: 600000
      # 连接池名称，日志里能区分是哪个池，排障时非常有用
      pool-name: ShopHikariPool
      # 借出连接前先测试其有效性，防止拿到死连接
      connection-test-query: SELECT 1

// 打开 Hikari 连接池统计日志（生产可开启，性能影响极小）
@Configuration
public class HikariConfig {
    // 通过日志观察 active / idle / waiting 三个值的变化趋势
}

logging:
  level:
    com.zaxxer.hikari: DEBUG

-- 找出跑得最久的连接，Time 列单位是秒
SELECT id, user, host, db, command, time, state, info
FROM information_schema.processlist
WHERE command != 'Sleep'
ORDER BY time DESC
LIMIT 20;

// 反例：手动从连接池取连接，却忘记关闭，造成连接泄漏
@Service
@RequiredArgsConstructor
@Slf4j
public class LeakDemoService {

    // 注入 DataSource 本身（HikariCP 的实现）
    private final DataSource dataSource;

    public void leakConnection() {
        try {
            // 直接从池里"借"一条连接，绕过了框架的自动归还机制
            Connection conn = dataSource.getConnection();
            // 模拟业务：执行 SQL
            Statement stmt = conn.createStatement();
            stmt.execute("SELECT 1");
            // 致命问题：这里没有 conn.close()！
            // 这条连接被借走后永远不归还，池子里的连接只会越来越少
        } catch (SQLException e) {
            // 注意：即使进了 catch，连接也依然没有关闭，泄漏依旧发生
            log.error("执行 SQL 失败", e);
        }
    }
}

# 第 1~3 次：正常执行（把 3 条连接全部借走且不还）
# 第 4 次：池子空了，等待 connection-timeout 后抛异常
# java.sql.SQLTransientConnectionException: ShopHikariPool - Connection is not available...

// 修复：try-with-resources 自动关闭连接，无论正常返回还是抛异常都会归还
public void noLeak() {
    // Connection 和 Statement 都实现 AutoCloseable，try 块结束自动 close
    try (Connection conn = dataSource.getConnection();
         Statement stmt = conn.createStatement()) {
        stmt.execute("SELECT 1");
    } catch (SQLException e) {
        log.error("执行 SQL 失败", e);
        // 连接已在 try-with-resources 里自动归还，无需手动处理
    }
}

# 引入 Actuator 以暴露连接池指标
management:
  endpoints:
    web:
      exposure:
        include: health,metrics,info
  metrics:
    enable:
      hikaricp: true

-- 查看数据库连接数上限，约束所有实例的池子总大小
SHOW VARIABLES LIKE 'max_connections';
-- 查看当前连接数
SHOW STATUS LIKE 'Threads_connected';

CREATE TABLE `user` (
  `id`          BIGINT       NOT NULL AUTO_INCREMENT COMMENT '主键',
  `username`    VARCHAR(64)  NOT NULL COMMENT '用户名',
  `age`         INT          DEFAULT NULL COMMENT '年龄',
  `email`       VARCHAR(128) DEFAULT NULL COMMENT '邮箱',
  `create_time` DATETIME     DEFAULT NULL COMMENT '创建时间',
  `update_time` DATETIME     DEFAULT NULL COMMENT '更新时间',
  `deleted`     TINYINT      NOT NULL DEFAULT 0 COMMENT '逻辑删除 0正常 1删除',
  `version`     INT          NOT NULL DEFAULT 0 COMMENT '乐观锁版本号',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_username` (`username`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';

// 最小可用：Entity 用注解建立「字段 <-> 列」的映射
@Data
public class User {
    // 主键自增。生产也可用 ASSIGN_ID 走雪花算法，本篇用自增便于演示
    @TableId(type = IdType.AUTO)
    private Long id;

    private String username;
    private Integer age;
    private String email;

    // fill = FieldFill.INSERT 表示插入时由框架自动填充，见 2.5 节
    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;

    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updateTime;

    // 逻辑删除标记：MP 会把 deleteById 自动改写为 update deleted=1
    @TableLogic
    private Integer deleted;

    // 乐观锁版本号：更新时带上 version 条件，见 2.7 节
    @Version
    private Integer version;
}

// 继承 BaseMapper 即拥有 selectById/insert/updateById/deleteById/selectList 等方法
@Mapper
public interface UserMapper extends BaseMapper<User> {
    // 复杂 SQL 仍可在这里手写（@Select 注解或 XML），MP 不剥夺控制权
}

@RestController
@RequiredArgsConstructor
public class UserController {
    private final UserMapper userMapper;

    @GetMapping("/user/{id}")
    public ApiResult<User> getById(@PathVariable Long id) {
        // selectById：等价 SELECT * FROM user WHERE id=?
        // 注意：生产不推荐 selectById 直接返回 Entity，这里仅演示最小链路
        return ApiResult.ok(userMapper.selectById(id));
    }
}

// 反例：列名写死在字符串里，字段一改名就静默失效
QueryWrapper<User> w = new QueryWrapper<>();
w.eq("username", name).ge("age", 18);

// 生产级：用方法引用写条件，字段名改动会被编译期发现
List<User> list = userMapper.selectList(
        new LambdaQueryWrapper<User>()
                .eq(User::getUsername, name)      // 精确匹配
                .ge(User::getAge, 18)             // age >= 18
                .orderByDesc(User::getCreateTime) // 按创建时间倒序
);

// 生产级：注册分页插件（同时可挂乐观锁拦截器）
@Configuration
public class MybatisPlusConfig {

    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        // 分页拦截器：注意 DbType 要写对，不同数据库分页方言不同
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        // 乐观锁拦截器：配合 @Version 使用，见 2.7 节
        interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor());
        return interceptor;
    }
}

// 生产级：分页查询，返回 Page 对象，禁止一次性查全表
public Page<User> pageUsers(int pageNum, int pageSize, String keyword) {
    // 防御性校验：pageSize 上限，防止恶意传 pageSize=100000 拖垮数据库
    if (pageNum < 1) pageNum = 1;
    if (pageSize < 1 || pageSize > 100) pageSize = 20;

    Page<User> page = new Page<>(pageNum, pageSize);
    LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<User>()
            .like(StringUtils.hasText(keyword), User::getUsername, keyword)
            .orderByDesc(User::getCreateTime);
    return userMapper.selectPage(page, wrapper);
}

// 生产级：全局自动填充处理器
@Component
public class MyMetaObjectHandler implements MetaObjectHandler {

    // insert 时触发：填充创建时间和更新时间
    @Override
    public void insertFill(MetaObject metaObject) {
        // strictInsertFill：只有当目标字段为 null 时才填充，避免覆盖业务显式传入的值
        this.strictInsertFill(metaObject, "createTime", LocalDateTime.class, LocalDateTime.now());
        this.strictInsertFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());
    }

    // update 时触发：只刷新更新时间
    @Override
    public void updateFill(MetaObject metaObject) {
        this.strictUpdateFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());
    }
}

// 业务代码：看起来是"删除"，MP 实际执行的是 UPDATE
public void removeUser(Long id) {
    // 实际 SQL：UPDATE user SET deleted=1 WHERE id=? AND deleted=0
    userMapper.deleteById(id);
}

// 生产级：乐观锁更新。演示并发下"谁后写谁失败"的语义
public boolean updateAgeWithOptimisticLock(Long id, Integer newAge) {
    // 1. 先查出当前记录，拿到 version
    User user = userMapper.selectById(id);
    if (user == null) {
        throw new BizException(ErrorCode.USER_NOT_FOUND);
    }
    user.setAge(newAge);
    // 2. updateById 生成的 SQL 会带上 version 条件：
    //    UPDATE user SET age=?, version=version+1 WHERE id=? AND version=?
    // 3. 返回 false 说明 version 不匹配，有并发修改，本次更新失败
    return userMapper.updateById(user) > 0;
}

// 生产级：查全量 + 裁剪成 VO，只返回前端需要的字段
public UserVO getUserVO(Long id) {
    User user = userMapper.selectById(id);
    if (user == null) {
        throw new BizException(ErrorCode.USER_NOT_FOUND);
    }
    // VO 只暴露 username/age/email，不暴露 deleted/version
    UserVO vo = new UserVO();
    vo.setId(user.getId());
    vo.setUsername(user.getUsername());
    vo.setAge(user.getAge());
    vo.setEmail(user.getEmail());
    return vo;
}

// 生产级：只查需要的列，减少网络与内存开销
List<User> list = userMapper.selectList(
        new LambdaQueryWrapper<User>()
                .select(User::getId, User::getUsername)   // 只查两列
                .ge(User::getAge, 18));

// 反例：循环单条 insert，慢且消耗连接
for (User u : users) {
    userMapper.insert(u);
}

// 生产级：批量插入。需在 JDBC URL 加 rewriteBatchedStatements=true 才真正合并
public void importUsers(List<User> users) {
    // saveBatch 默认每 1000 条一批（可指定 batchSize），内部走 JDBC 批处理
    userService.saveBatch(users, 1000);
}

// 最小可用：能跑，但缺校验、缺异常、缺日志、Entity 直接外泄
@RestController
@RequiredArgsConstructor
public class UserController {
    private final UserMapper userMapper;

    @GetMapping("/users")
    public List<User> list() {
        return userMapper.selectList(null);   // 无分页，select *，Entity 直接返回
    }
}

// 生产级：Controller 只做参数接收与响应组装
@RestController
@RequiredArgsConstructor
@Slf4j
public class UserController {

    private final UserService userService;

    @GetMapping("/users")
    public ApiResult<Page<UserVO>> page(@RequestParam(defaultValue = "1") int pageNum,
                                        @RequestParam(defaultValue = "20") int pageSize,
                                        @RequestParam(required = false) String keyword) {
        log.info("分页查询用户, pageNum={}, pageSize={}, keyword={}", pageNum, pageSize, keyword);
        return ApiResult.ok(userService.pageUsers(pageNum, pageSize, keyword));
    }

    @GetMapping("/users/{id}")
    public ApiResult<UserVO> get(@PathVariable Long id) {
        return ApiResult.ok(userService.getUserVO(id));
    }

    @PostMapping("/users")
    public ApiResult<Long> create(@Valid @RequestBody UserSaveDTO dto) {
        return ApiResult.ok(userService.createUser(dto));
    }

    @PutMapping("/users/{id}")
    public ApiResult<Void> update(@PathVariable Long id, @Valid @RequestBody UserSaveDTO dto) {
        userService.updateUser(id, dto);
        return ApiResult.ok(null);
    }

    @DeleteMapping("/users/{id}")
    public ApiResult<Void> remove(@PathVariable Long id) {
        userService.removeUser(id);
        return ApiResult.ok(null);
    }
}

// 生产级：Service 实现，含校验、异常、日志、VO 裁剪
@Service
@RequiredArgsConstructor
@Slf4j
public class UserServiceImpl implements UserService {

    private final UserMapper userMapper;

    @Override
    public Page<UserVO> pageUsers(int pageNum, int pageSize, String keyword) {
        // 分页参数防御：上限 100，防止大 pageSize 拖垮 DB
        if (pageNum < 1) pageNum = 1;
        if (pageSize < 1 || pageSize > 100) pageSize = 20;

        Page<User> page = new Page<>(pageNum, pageSize);
        LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<User>()
                .like(StringUtils.hasText(keyword), User::getUsername, keyword)
                .orderByDesc(User::getCreateTime);
        Page<User> userPage = userMapper.selectPage(page, wrapper);

        // Entity -> VO 转换，脱敏并裁剪字段
        Page<UserVO> voPage = new Page<>(pageNum, pageSize, userPage.getTotal());
        voPage.setRecords(userPage.getRecords().stream().map(this::toVO).toList());
        return voPage;
    }

    @Override
    public UserVO getUserVO(Long id) {
        User user = userMapper.selectById(id);
        if (user == null) {
            throw new BizException(ErrorCode.USER_NOT_FOUND);
        }
        return toVO(user);
    }

    @Override
    public Long createUser(UserSaveDTO dto) {
        // 用户名唯一性校验，避免插库时才撞唯一索引
        Long count = userMapper.selectCount(
                new LambdaQueryWrapper<User>().eq(User::getUsername, dto.getUsername()));
        if (count > 0) {
            throw new BizException(40010, "用户名已存在");
        }
        User user = new User();
        user.setUsername(dto.getUsername());
        user.setAge(dto.getAge());
        user.setEmail(dto.getEmail());
        // createTime/updateTime 由自动填充处理器负责，这里不 set
        userMapper.insert(user);
        log.info("创建用户成功, id={}, username={}", user.getId(), dto.getUsername());
        return user.getId();
    }

    @Override
    public void updateUser(Long id, UserSaveDTO dto) {
        User user = userMapper.selectById(id);
        if (user == null) {
            throw new BizException(ErrorCode.USER_NOT_FOUND);
        }
        user.setAge(dto.getAge());
        user.setEmail(dto.getEmail());
        // updateById 带上乐观锁 version 条件，并发下安全
        userMapper.updateById(user);
    }

    @Override
    public void removeUser(Long id) {
        // 逻辑删除：实际执行 UPDATE deleted=1
        userMapper.deleteById(id);
    }

    // 统一的 Entity -> VO 转换，集中管理字段裁剪
    private UserVO toVO(User user) {
        UserVO vo = new UserVO();
        vo.setId(user.getId());
        vo.setUsername(user.getUsername());
        vo.setAge(user.getAge());
        vo.setEmail(user.getEmail());
        vo.setCreateTime(user.getCreateTime());
        return vo;
    }
}

// 悲观锁示例：扣库存前先锁行，保证读到的是最新库存
@Mapper
public interface StockMapper extends BaseMapper<Stock> {

    // FOR UPDATE 会锁住这一行，其他事务的 FOR UPDATE 会阻塞等待
    @Select("SELECT * FROM stock WHERE product_id = #{productId} FOR UPDATE")
    Stock selectForUpdate(@Param("productId") Long productId);
}

// 悲观锁用法：读（锁）-> 判断 -> 改，全程持有行锁
@Transactional(rollbackFor = Exception.class)
public void deductWithPessimisticLock(Long productId, Integer qty) {
    // 1. 锁住这一行，读到最新库存
    Stock stock = stockMapper.selectForUpdate(productId);
    if (stock == null || stock.getQuantity() < qty) {
        throw new BizException(ErrorCode.STOCK_NOT_ENOUGH);
    }
    // 2. 更新库存（此时别的并发事务都被阻塞在步骤 1）
    stock.setQuantity(stock.getQuantity() - qty);
    stockMapper.updateById(stock);
}

// 最小可用：JPA Entity，用 javax.persistence 注解（Jakarta）
@Data
@Entity
@Table(name = "jpa_user")   // 与 MP 的 user 表分开，避免两套 ORM 抢同一张表
public class JpaUser {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)  // 主键自增
    private Long id;

    @Column(nullable = false, length = 64)
    private String username;

    private Integer age;
    private String email;

    // JPA 审计：创建/更新时间由 @EnableJpaAuditing + @EntityListeners 自动填充
    @CreatedDate
    private LocalDateTime createTime;

    @LastModifiedDate
    private LocalDateTime updateTime;
}

// 继承 JpaRepository<实体, 主键类型>，即拥有 save/findById/findAll/deleteById 等
public interface JpaUserRepository extends JpaRepository<JpaUser, Long> {
}

@RestController
@RequiredArgsConstructor
public class JpaUserController {
    private final JpaUserRepository repository;

    @GetMapping("/jpa/users/{id}")
    public JpaUser get(@PathVariable Long id) {
        // findById 返回 Optional，orElseThrow 在不存在时抛异常
        return repository.findById(id)
                .orElseThrow(() -> new BizException(ErrorCode.USER_NOT_FOUND));
    }

    @PostMapping("/jpa/users")
    public JpaUser create(@RequestBody JpaUser user) {
        return repository.save(user);   // save 同时承担 insert 和 update
    }
}

public interface JpaUserRepository extends JpaRepository<JpaUser, Long> {

    // 方法名解析规则：find + By + 字段 + 条件 + 连接符
    // 框架自动生成：SELECT * FROM jpa_user WHERE username = ?
    Optional<JpaUser> findByUsername(String username);

    // 生成：SELECT * FROM jpa_user WHERE age >= ?
    List<JpaUser> findByAgeGreaterThanEqual(Integer age);

    // 生成：SELECT * FROM jpa_user WHERE username LIKE ? ORDER BY create_time DESC
    List<JpaUser> findByUsernameContainingOrderByCreateTimeDesc(String keyword);

    // 生成：分页 + 排序，配合 Pageable 使用
    Page<JpaUser> findByAgeBetween(Integer min, Integer max, Pageable pageable);

    // 删除类查询也要用方法命名，框架会先查再删
    void deleteByUsername(String username);
}

public interface JpaUserRepository extends JpaRepository<JpaUser, Long> {

    // JPQL：注意 from 后面是实体名 JpaUser，不是表名；:name 是命名参数
    @Query("SELECT u FROM JpaUser u WHERE u.username = :name")
    Optional<JpaUser> findByNameWithJpql(@Param("name") String name);

    // 原生 SQL 也能写，但要加 nativeQuery=true，此时面对的是真实表和列
    @Query(value = "SELECT * FROM jpa_user WHERE age > :age", nativeQuery = true)
    List<JpaUser> findOlderThan(@Param("age") Integer age);

    // 更新/删除必须加 @Modifying，且必须在事务内执行
    @Modifying
    @Query("UPDATE JpaUser u SET u.age = u.age + 1 WHERE u.id = :id")
    int increaseAge(@Param("id") Long id);
}

@SpringBootApplication
@EnableJpaAuditing   // 开启 JPA 审计，让 @CreatedDate/@LastModifiedDate 生效
public class ShopApplication {
    public static void main(String[] args) {
        SpringApplication.run(ShopApplication.class, args);
    }
}

@Data
@Entity
@Table(name = "jpa_user")
@EntityListeners(AuditingEntityListener.class)   // 注册审计监听器，关键一步
public class JpaUser {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @CreatedDate
    private LocalDateTime createTime;

    @LastModifiedDate
    private LocalDateTime updateTime;
}

// 生产级：JPA 用户 Service
@Service
@RequiredArgsConstructor
@Slf4j
public class JpaUserService {

    private final JpaUserRepository repository;

    // 简单查询：一行方法命名查询搞定，无需写 SQL
    public Page<JpaUser> page(int pageNum, int pageSize) {
        // 防御性校验
        if (pageNum < 1) pageNum = 1;
        if (pageSize < 1 || pageSize > 100) pageSize = 20;
        // Sort.by(Direction.DESC, "createTime") 按创建时间倒序
        return repository.findAll(
                PageRequest.of(pageNum - 1, pageSize, Sort.by(Sort.Direction.DESC, "createTime")));
    }

    public Long create(JpaUser user) {
        // 唯一性校验：优先走方法命名查询
        repository.findByUsername(user.getUsername()).ifPresent(u -> {
            throw new BizException(40010, "用户名已存在");
        });
        JpaUser saved = repository.save(user);
        log.info("创建 JPA 用户成功, id={}", saved.getId());
        return saved.getId();
    }

    public void updateAge(Long id, Integer age) {
        JpaUser user = repository.findById(id)
                .orElseThrow(() -> new BizException(ErrorCode.USER_NOT_FOUND));
        user.setAge(age);
        // save 对"有主键"的实体执行 update，对"无主键"的执行 insert
        repository.save(user);
    }
}

// 反例：N+1 查询的温床——懒加载关联
@Data
@Entity
@Table(name = "jpa_order")
public class JpaOrder {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String orderNo;

    // 多对一：默认 FetchType.EAGER 会 join 查询，LAZY 则懒加载
    // JPA 的坑在于：@ManyToOne 默认是 EAGER（会 join），@OneToMany 默认是 LAZY（会 N+1）
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "user_id")
    private JpaUser user;
}

// 触发 N+1：查 100 条订单，再为每条订单单独查 1 次用户 = 101 条 SQL
List<JpaOrder> orders = orderRepository.findAll();   // 1 条 SQL 查订单
for (JpaOrder order : orders) {
    // 每次访问 order.getUser() 都触发 1 条 SQL 查用户（懒加载）
    System.out.println(order.getUser().getUsername());  // 演示用：反例教学，仅展示 N+1 现象，生产请用日志
}

public interface JpaOrderRepository extends JpaRepository<JpaOrder, Long> {

    // @EntityGraph 指定加载 user 关联，框架用一条 join SQL 一次性查出，避免 N+1
    @EntityGraph(attributePaths = "user")
    @Query("SELECT o FROM JpaOrder o")
    List<JpaOrder> findAllWithUser();
}

// join fetch 让关联数据随主查询一起加载，也是一条 SQL 搞定
@Query("SELECT o FROM JpaOrder o JOIN FETCH o.user")
List<JpaOrder> findAllWithUserByJoinFetch();

// 生产级：用 Specification 动态拼接条件，替代方法名爆炸
@Service
@RequiredArgsConstructor
public class JpaUserQueryService {

    private final JpaUserRepository repository;

    public Page<JpaUser> search(String username, Integer minAge, Integer maxAge, int pageNum, int pageSize) {
        // Specification 是函数式接口，动态拼接条件
        Specification<JpaUser> spec = (root, query, cb) -> {
            List<Predicate> predicates = new ArrayList<>();
            // 条件非空才拼接，实现"可选筛选"
            if (StringUtils.hasText(username)) {
                predicates.add(cb.like(root.get("username"), "%" + username + "%"));
            }
            if (minAge != null) {
                predicates.add(cb.greaterThanOrEqualTo(root.get("age"), minAge));
            }
            if (maxAge != null) {
                predicates.add(cb.lessThanOrEqualTo(root.get("age"), maxAge));
            }
            return cb.and(predicates.toArray(new Predicate[0]));
        };
        // 配合分页
        Page<JpaUser> page = repository.findAll(spec,
                PageRequest.of(pageNum - 1, pageSize, Sort.by(Sort.Direction.DESC, "createTime")));
        return page;
    }
}

// 脏检查演示：托管实体改字段，事务提交时自动 UPDATE
@Transactional(rollbackFor = Exception.class)
public void updateAgeByDirtyChecking(Long id, Integer age) {
    // findById 返回的是"托管"实体，被 EntityManager 追踪
    JpaUser user = repository.findById(id)
            .orElseThrow(() -> new BizException(ErrorCode.USER_NOT_FOUND));
    // 直接改字段，不用调 save
    user.setAge(age);
    // 事务提交时，脏检查发现 age 变了，自动生成 UPDATE 语句
}

// 反例：无事务，一步成功一步失败，数据就脏了
public void createOrderNoTx(OrderCreateDTO dto) {
    orderMapper.insert(order);                              // 第 1 步：订单写库成功
    int rows = stockMapper.deduct(dto.getProductId(), dto.getQty()); // 第 2 步：扣库存
    if (rows <= 0) {
        throw new BizException(ErrorCode.STOCK_NOT_ENOUGH); // 库存不足，抛异常
    }
}

// 最小可用：加 @Transactional，异常自动回滚
@Service
@RequiredArgsConstructor
public class OrderServiceImpl implements OrderService {
    private final OrderMapper orderMapper;
    private final StockMapper stockMapper;

    @Transactional
    @Override
    public void createOrder(OrderCreateDTO dto) {
        orderMapper.insert(Order.from(dto));
        if (stockMapper.deduct(dto.getProductId(), dto.getQty()) <= 0) {
            // 抛 RuntimeException，事务回滚，上面的 insert 一并撤销
            throw new BizException(ErrorCode.STOCK_NOT_ENOUGH);
        }
    }
}

// 场景：下单主流程（REQUIRED）+ 记录操作日志（REQUIRES_NEW）
@Service
@RequiredArgsConstructor
@Slf4j
public class OrderServiceImpl implements OrderService {

    private final OrderMapper orderMapper;
    private final StockMapper stockMapper;
    private final OperationLogService operationLogService;

    @Transactional   // 外层事务 REQUIRED
    @Override
    public void createOrder(OrderCreateDTO dto) {
        orderMapper.insert(Order.from(dto));
        stockMapper.deduct(dto.getProductId(), dto.getQty());

        try {
            // 日志用 REQUIRES_NEW：即使主事务最终回滚，日志也要保留
            operationLogService.log("创建订单", dto.getRequestNo());
        } catch (Exception e) {
            // 日志失败不能影响下单主流程，所以这里吞掉异常
            log.error("记录操作日志失败, requestNo={}", dto.getRequestNo(), e);
        }

        // 这里故意抛异常，让主事务回滚
        if ("FORCE_FAIL".equals(dto.getRequestNo())) {
            throw new BizException(ErrorCode.SYSTEM_ERROR);
        }
    }
}

// 日志服务：REQUIRES_NEW 保证独立事务，主事务回滚不影响它
@Service
@RequiredArgsConstructor
public class OperationLogServiceImpl implements OperationLogService {

    private final OperationLogMapper logMapper;

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    @Override
    public void log(String action, String bizNo) {
        OperationLog log = new OperationLog();
        log.setAction(action);
        log.setBizNo(bizNo);
        logMapper.insert(log);   // 在独立事务里提交，不随主事务回滚
    }
}

// 生产级：显式指定隔离级别（一般用默认即可，这里演示写法）
@Transactional(isolation = Isolation.REPEATABLE_READ)
public void transfer(Long fromId, Long toId, Integer amount) {
    // 转账：先减后加，两行数据必须在同一隔离级别下保证一致
    accountMapper.deduct(fromId, amount);
    accountMapper.add(toId, amount);
}

// 失效代码：同类自调用，事务不生效
@Service
@RequiredArgsConstructor
public class OrderServiceImpl implements OrderService {

    private final OrderMapper orderMapper;
    private final StockMapper stockMapper;

    // 这个方法被外部调用，有事务
    @Transactional
    @Override
    public void createOrder(OrderCreateDTO dto) {
        // 自调用：走 this，绕过代理，下面这个方法的事务失效
        this.doCreate(dto);
    }

    // 标了 @Transactional，但因为是被 this 调用的，事务不生效
    @Transactional
    public void doCreate(OrderCreateDTO dto) {
        orderMapper.insert(Order.from(dto));
        if (stockMapper.deduct(dto.getProductId(), dto.getQty()) <= 0) {
            throw new BizException(ErrorCode.STOCK_NOT_ENOUGH);
        }
    }
}

// 修复一：把事务方法拆到另一个 Bean，让调用重新走代理
@Service
@RequiredArgsConstructor
public class OrderServiceImpl implements OrderService {

    private final OrderCreateHelper orderCreateHelper;  // 拆出去的 Bean

    @Transactional
    @Override
    public void createOrder(OrderCreateDTO dto) {
        // 跨 Bean 调用，orderCreateHelper 是代理对象，事务生效
        orderCreateHelper.doCreate(dto);
    }
}

@Service
public class OrderCreateHelper {
    private final OrderMapper orderMapper;
    private final StockMapper stockMapper;
    // 构造器注入（省略 @RequiredArgsConstructor 展开）
    public OrderCreateHelper(OrderMapper orderMapper, StockMapper stockMapper) {
        this.orderMapper = orderMapper;
        this.stockMapper = stockMapper;
    }

    @Transactional
    public void doCreate(OrderCreateDTO dto) {
        orderMapper.insert(Order.from(dto));
        if (stockMapper.deduct(dto.getProductId(), dto.getQty()) <= 0) {
            throw new BizException(ErrorCode.STOCK_NOT_ENOUGH);
        }
    }
}

// 修复二：注入自身代理，通过代理调用（需开启 exposeProxy）
// 注意：这是备选方案，代码可读性不如拆 Bean
@Service
@RequiredArgsConstructor
public class OrderServiceImpl implements OrderService {
    private final OrderMapper orderMapper;
    private final StockMapper stockMapper;

    @Transactional
    @Override
    public void createOrder(OrderCreateDTO dto) {
        // 拿到当前类的代理对象，走代理调用，事务生效
        ((OrderService) AopContext.currentProxy()).doCreate(dto);
    }

    @Transactional
    @Override
    public void doCreate(OrderCreateDTO dto) { /* 同上 */ }
}

// 失效代码：protected 方法，事务不生效
@Transactional
protected void doCreate(OrderCreateDTO dto) {   // 不是 public，代理拦不到
    orderMapper.insert(Order.from(dto));
    stockMapper.deduct(dto.getProductId(), dto.getQty());
}

// 失效代码：异常被 try-catch 吞掉，事务不回滚
@Transactional
@Override
public void createOrder(OrderCreateDTO dto) {
    try {
        orderMapper.insert(Order.from(dto));
        if (stockMapper.deduct(dto.getProductId(), dto.getQty()) <= 0) {
            throw new BizException(ErrorCode.STOCK_NOT_ENOUGH);
        }
    } catch (Exception e) {
        // 吞掉异常，只打日志，不往上抛——事务感知不到，不回滚
        log.error("下单失败", e);
    }
}

// 修复一：catch 之后重新抛，让代理感知
@Transactional
@Override
public void createOrder(OrderCreateDTO dto) {
    try {
        // ...业务逻辑
        throw new BizException(ErrorCode.STOCK_NOT_ENOUGH);
    } catch (BizException e) {
        log.error("下单失败", e);
        throw e;   // 重新抛出，触发回滚
    }
}

// 修复二：手动标记回滚（适用于"异常要吞掉但事务要回滚"的特殊场景）
@Transactional
@Override
public void createOrder(OrderCreateDTO dto) {
    try {
        // ...业务逻辑
        throw new BizException(ErrorCode.STOCK_NOT_ENOUGH);
    } catch (BizException e) {
        log.error("下单失败", e);
        // 手动标记当前事务回滚，即使异常不继续抛也会回滚
        TransactionAspectSupport.currentTransactionStatus().setRollbackOnly();
    }
}

// 失效代码：抛受检异常，默认不回滚
@Transactional
@Override
public void createOrder(OrderCreateDTO dto) throws OrderBizException {
    orderMapper.insert(Order.from(dto));
    // 抛出自定义受检异常（继承 Exception，不是 RuntimeException）
    throw new OrderBizException("库存不足");
}

// 修复：rollbackFor 指定受检异常也回滚（生产标配写法）
@Transactional(rollbackFor = Exception.class)
@Override
public void createOrder(OrderCreateDTO dto) throws OrderBizException {
    orderMapper.insert(Order.from(dto));
    throw new OrderBizException("库存不足");   // 现在会回滚
}

// 失效代码：自己 new 出来的对象，不在 Spring 容器里，事务失效
@Service
@RequiredArgsConstructor
public class OrderServiceImpl implements OrderService {
    private final OrderMapper orderMapper;
    private final StockMapper stockMapper;

    @Override
    public void createOrder(OrderCreateDTO dto) {
        // 反例：new 一个"看起来有事务"的对象
        OrderTxHelper helper = new OrderTxHelper(orderMapper, stockMapper);
        helper.doCreate(dto);   // helper 没被 Spring 管理，@Transactional 失效
    }
}

// 这个类没加 @Service/@Component，不在容器里
public class OrderTxHelper {
    private final OrderMapper orderMapper;
    private final StockMapper stockMapper;
    public OrderTxHelper(OrderMapper orderMapper, StockMapper stockMapper) {
        this.orderMapper = orderMapper;
        this.stockMapper = stockMapper;
    }

    @Transactional
    public void doCreate(OrderCreateDTO dto) { /* ... */ }
}

// 生产级：订单 + 扣库存，事务保护 + 显式 rollbackFor + 幂等
@Service
@RequiredArgsConstructor
@Slf4j
public class OrderServiceImpl implements OrderService {

    private final OrderMapper orderMapper;
    private final StockMapper stockMapper;
    private final RedisTemplate<String, Object> redisTemplate;

    // 显式 rollbackFor=Exception.class，杜绝"受检异常不回滚"的隐患
    @Transactional(rollbackFor = Exception.class)
    @Override
    public Long createOrder(OrderCreateDTO dto) {
        // 1. 幂等校验：同一 requestNo 只处理一次，防重复提交
        String idempotentKey = "order:submit:" + dto.getRequestNo();
        if (Boolean.TRUE.equals(redisTemplate.hasKey(idempotentKey))) {
            throw new BizException(40020, "请勿重复提交订单");
        }

        // 2. 扣库存（悲观锁：SELECT ... FOR UPDATE 保证并发下不超卖）
        int deducted = stockMapper.deductWithLock(dto.getProductId(), dto.getQty());
        if (deducted <= 0) {
            throw new BizException(ErrorCode.STOCK_NOT_ENOUGH);
        }

        // 3. 落订单
        Order order = Order.from(dto);
        orderMapper.insert(order);

        // 4. 标记幂等 key（设置过期时间，避免内存泄漏）
        redisTemplate.opsForValue().set(idempotentKey, "1", 10, TimeUnit.MINUTES);

        log.info("订单创建成功, orderId={}, requestNo={}", order.getId(), dto.getRequestNo());
        return order.getId();
    }
}

@Mapper
public interface StockMapper extends BaseMapper<Stock> {

    // 悲观锁：SELECT ... FOR UPDATE 锁住行，防止并发下同时读到同一库存导致超卖
    @Update("UPDATE stock SET quantity = quantity - #{qty} " +
            "WHERE product_id = #{productId} AND quantity >= #{qty}")
    int deductWithLock(@Param("productId") Long productId, @Param("qty") Integer qty);
}

// 集成测试：验证事务回滚语义（需 @SpringBootTest + 真实 DB 或 H2）
@SpringBootTest
@Slf4j
@RequiredArgsConstructor
class OrderTxTest {

    private final OrderService orderService;
    private final OrderMapper orderMapper;

    @Test
    @Transactional   // 测试方法自带事务，结束后自动回滚，不污染数据库
    void shouldRollbackWhenExceptionThrown() {
        OrderCreateDTO dto = new OrderCreateDTO();
        dto.setRequestNo("TEST-ROLLBACK-001");
        dto.setProductId(999999L);   // 不存在的商品，扣库存必然失败
        dto.setQuantity(1);

        // 期望：扣库存失败抛异常，整个事务回滚
        assertThrows(BizException.class, () -> orderService.createOrder(dto));

        // 断言：订单表里没有这条订单（证明 insert 被回滚了）
        Long count = orderMapper.selectCount(
                new LambdaQueryWrapper<Order>().eq(Order::getOrderNo, "TEST-ROLLBACK-001"));
        assertEquals(0L, count, "异常后订单应该被回滚，但订单仍然存在");
    }
}

// 最小可用：手写 Cache Aside，读时回源、写时删缓存
@Service
@RequiredArgsConstructor
@Slf4j
public class UserServiceImpl implements UserService {

    private final UserMapper userMapper;
    private final RedisTemplate<String, Object> redisTemplate;

    @Override
    public User getUser(Long id) {
        String key = "user:" + id;
        // 1. 先查缓存
        User user = (User) redisTemplate.opsForValue().get(key);
        if (user != null) {
            return user;   // 命中，直接返回，不打 DB
        }
        // 2. 未命中，查 DB
        user = userMapper.selectById(id);
        // 3. 写回缓存（只有查到数据才写，查不到不写，否则会缓存穿透，见 5.5）
        if (user != null) {
            redisTemplate.opsForValue().set(key, user, 30, TimeUnit.MINUTES);
        }
        return user;
    }

    @Override
    public void updateUser(Long id, UserSaveDTO dto) {
        // 先更新 DB，再删缓存（不是更新缓存，见 5.7）
        User user = userMapper.selectById(id);
        user.setAge(dto.getAge());
        userMapper.updateById(user);
        redisTemplate.delete("user:" + id);
    }
}

// 生产级：配置 Redis 缓存管理器 + 序列化 + 全局 TTL
@Configuration
@EnableCaching   // 开启 @Cacheable 等注解
public class CacheConfig {

    @Bean
    public RedisCacheManager cacheManager(RedisConnectionFactory factory) {
        // 用 JSON 序列化，避免默认 JDK 序列化带来的可读性差、跨语言难、必须实现 Serializable 的问题
        RedisSerializer<Object> serializer = new GenericJackson2JsonRedisSerializer();

        RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()
                // 默认过期时间 30 分钟，防止 key 永久占用内存
                .entryTtl(Duration.ofMinutes(30))
                // key 加前缀，区分不同业务
                .prefixCacheNameWith("shop:")
                .serializeValuesWith(RedisSerializationContext.SerializationPair.fromSerializer(serializer))
                // 缓存 null 值需显式开启，且要给很短的 TTL（防穿透，见 5.5）
                .computePrefixWith(cacheName -> cacheName + ":");

        return RedisCacheManager.builder(factory)
                .cacheDefaults(config)
                .build();
    }
}

// 生产级：@Cacheable 读缓存，@CacheEvict 删缓存
@Service
@RequiredArgsConstructor
@Slf4j
public class UserServiceImpl implements UserService {

    private final UserMapper userMapper;

    // 查：缓存 key 为 user::123，命中直接返回，未命中执行方法体并缓存结果
    @Cacheable(value = "user", key = "#id")
    @Override
    public UserVO getUserVO(Long id) {
        log.info("缓存未命中，回源数据库查询用户 id={}", id);
        User user = userMapper.selectById(id);
        if (user == null) {
            throw new BizException(ErrorCode.USER_NOT_FOUND);
        }
        return toVO(user);
    }

    // 更新：执行完方法体后，删除缓存 key 为 user::123 的条目
    @CacheEvict(value = "user", key = "#id")
    @Override
    public void updateUser(Long id, UserSaveDTO dto) {
        User user = userMapper.selectById(id);
        user.setAge(dto.getAge());
        userMapper.updateById(user);
    }

    // 批量删除：allEntries=true 清空整个 user 缓存区
    @CacheEvict(value = "user", allEntries = true)
    @Override
    public void clearAllUserCache() {
        // 一般用于数据全量刷新的场景
    }
}

// 生产级：空值缓存防穿透（核心：查不到也缓存，但 TTL 要短）
@Cacheable(value = "user", key = "#id", unless = "#result == null")
@Override
public UserVO getUserVO(Long id) {
    // 参数兜底校验：id 必须大于 0，从源头挡住大部分穿透
    if (id == null || id <= 0) {
        throw new BizException(ErrorCode.PARAM_ERROR);
    }
    User user = userMapper.selectById(id);
    if (user == null) {
        // 查不到，手动缓存一个"空值标记"，TTL 设短（如 60 秒），避免长期占用且能快速自愈
        redisTemplate.opsForValue().set("user:" + id + ":null", "NULL", 60, TimeUnit.SECONDS);
        throw new BizException(ErrorCode.USER_NOT_FOUND);
    }
    return toVO(user);
}

// 概念示意：布隆过滤器（生产用 Redisson 的 RBloomFilter）
@Service
@RequiredArgsConstructor
public class UserQueryWithBloom {

    private final RedissonClient redissonClient;
    private final UserMapper userMapper;

    public UserVO getUserWithBloom(Long id) {
        RBloomFilter<Long> filter = redissonClient.getBloomFilter("user:bloom");
        // 布隆过滤器说"不存在"，直接返回，绝不打 DB
        if (!filter.contains(id)) {
            throw new BizException(ErrorCode.USER_NOT_FOUND);
        }
        // 说"存在"（可能有误判），走正常查缓存 + 查 DB
        return getUserVO(id);
    }
}

// 生产级：互斥锁防击穿（核心：只让一个线程回源 DB，其余重试读缓存）
@Service
@RequiredArgsConstructor
@Slf4j
public class ProductServiceImpl implements ProductService {

    private final ProductMapper productMapper;
    private final StringRedisTemplate redisTemplate;

    @Override
    public ProductVO getProduct(Long id) {
        String cacheKey = "product:" + id;
        String lockKey = "product:lock:" + id;

        // 1. 先查缓存，命中直接返回
        String json = redisTemplate.opsForValue().get(cacheKey);
        if (json != null) {
            return JsonUtil.fromJson(json, ProductVO.class);
        }

        // 2. 未命中，尝试抢互斥锁（setIfAbsent = SET NX，原子操作，只有一个线程成功）
        Boolean locked = redisTemplate.opsForValue()
                .setIfAbsent(lockKey, "1", 3, TimeUnit.SECONDS);
        if (Boolean.TRUE.equals(locked)) {
            try {
                // 3. 抢到锁：双重检查，可能前面的线程已经回源写好了缓存
                json = redisTemplate.opsForValue().get(cacheKey);
                if (json != null) {
                    return JsonUtil.fromJson(json, ProductVO.class);
                }
                // 4. 回源 DB
                Product product = productMapper.selectById(id);
                if (product == null) {
                    throw new BizException(ErrorCode.PRODUCT_NOT_FOUND);
                }
                // 5. 写缓存，TTL 加随机值（同时缓解雪崩）
                long ttl = 30 + ThreadLocalRandom.current().nextInt(10);
                redisTemplate.opsForValue().set(cacheKey, JsonUtil.toJson(product), ttl, TimeUnit.MINUTES);
                return toVO(product);
            } finally {
                // 6. 释放锁（用 Lua 保证"判断是自己的锁再删"，简化版直接 delete）
                redisTemplate.delete(lockKey);
            }
        } else {
            // 7. 没抢到锁：短暂休眠后重试（自旋），读到缓存后返回
            try {
                Thread.sleep(50);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
            return getProduct(id);   // 递归重试
        }
    }
}