【阶段 3】Web 开发：Spring MVC 与生产级 REST API

<!-- pom.xml 关键依赖 -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.5</version>
    <relativePath/>
</parent>

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

<dependencies>
    <!-- Web MVC：内嵌 Tomcat + DispatcherServlet -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- 参数校验：JSR-303 / Bean Validation 3.0（Spring Boot 2.3 起需单独引入） -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <!-- AOP：幂等切面需要 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-aop</artifactId>
    </dependency>
    <!-- MyBatis-Plus：数据访问层（Spring Boot 3 专用 starter） -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
        <version>3.5.7</version>
    </dependency>
    <!-- MySQL 驱动 -->
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <scope>runtime</scope>
    </dependency>
    <!-- Redis：幂等、限流 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-redis</artifactId>
    </dependency>
    <!-- Lombok -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

# MySQL 8.0
docker run -d --name mysql8 
  -e MYSQL_ROOT_PASSWORD=root 
  -e MYSQL_DATABASE=demo 
  -p 3306:3306 mysql:8.0

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

# 建表（第 7 章用户表）
docker exec -i mysql8 mysql -uroot -proot demo <<'SQL'
CREATE TABLE IF NOT EXISTS `user` (
  `id`         BIGINT AUTO_INCREMENT PRIMARY KEY,
  `username`   VARCHAR(50)  NOT NULL COMMENT '用户名',
  `password`   VARCHAR(100) NOT NULL COMMENT '密码（生产应存 BCrypt 摘要）',
  `email`      VARCHAR(100) DEFAULT NULL COMMENT '邮箱',
  `phone`      VARCHAR(20)  DEFAULT NULL COMMENT '手机号',
  `age`        INT          DEFAULT NULL COMMENT '年龄',
  `status`     TINYINT      DEFAULT 1 COMMENT '状态：1=正常 0=禁用',
  `create_time` DATETIME    DEFAULT NULL COMMENT '创建时间',
  `update_time` DATETIME    DEFAULT NULL COMMENT '更新时间',
  `deleted`    TINYINT      DEFAULT 0 COMMENT '逻辑删除：0=正常 1=删除',
  UNIQUE KEY `uk_username` (`username`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';
SQL

# application.yml
server:
  port: 8080

spring:
  application:
    name: demo-web
  datasource:
    url: jdbc:mysql://localhost:3306/demo?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf8
    username: root
    password: root
    driver-class-name: com.mysql.cj.jdbc.Driver
  data:
    redis:
      host: localhost
      port: 6379

# MyBatis-Plus 配置
mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true   # 下划线转驼峰
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl  # 开发期打印 SQL，生产关闭
  global-config:
    db-config:
      logic-delete-field: deleted        # 逻辑删除字段
      logic-delete-value: 1
      logic-not-delete-value: 0

logging:
  level:
    com.example.demo: debug

package com.example.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * 最小示例：验证请求能到达 Controller 并返回 JSON。
 * @RestController = @Controller + @ResponseBody
 *   @Controller：声明这是一个处理器组件，交给 Spring 管理
 *   @ResponseBody：方法返回值直接序列化为 JSON 写入响应体，而非走视图渲染
 */
@RestController
@RequestMapping("/api/hello")
public class HelloController {

    @GetMapping
    public String hello(@RequestParam(defaultValue = "World") String name) {
        // 直接返回字符串，@ResponseBody 会把它写进响应体
        return "Hello, " + name;
    }
}

package com.example.demo.controller;

import com.example.demo.dto.UserCreateDTO;
import com.example.demo.vo.UserVO;
import com.example.demo.common.ApiResult;
import org.springframework.web.bind.annotation.*;

import java.util.List;

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

    // 1. @PathVariable：占位符 {id} 的值绑定到参数 id
    @GetMapping("/{id}")
    public ApiResult<UserVO> getById(@PathVariable Long id) {
        return ApiResult.ok(new UserVO());
    }

    // 2. @RequestParam：查询串参数，可给默认值
    //    required=false 表示可不传；defaultValue 表示缺省值
    @GetMapping
    public ApiResult<List<UserVO>> list(
            @RequestParam(defaultValue = "1") int page,
            @RequestParam(defaultValue = "10") int size,
            @RequestParam(required = false) String keyword) {
        return ApiResult.ok(List.of());
    }

    // 3. @RequestBody：把 JSON 请求体反序列化为 DTO
    @PostMapping
    public ApiResult<Long> create(@RequestBody UserCreateDTO dto) {
        return ApiResult.ok(1L);
    }
}

package com.example.demo.dto;

import jakarta.validation.constraints.*;
import lombok.Data;

/**
 * 用户创建入参 DTO。
 * 只承载「入参 + 校验规则」，绝不参与数据库映射，也不直接返回给前端。
 */
@Data
public class UserCreateDTO {

    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度必须在 3-20 之间")
    private String username;

    @NotBlank(message = "密码不能为空")
    @Size(min = 6, max = 32, message = "密码长度必须在 6-32 之间")
    private String password;

    @Email(message = "邮箱格式不正确")
    private String email;

    @Min(value = 1, message = "年龄必须大于 0")
    @Max(value = 150, message = "年龄必须小于 150")
    private Integer age;
}

@PostMapping
public ApiResult<Long> create(@Validated @RequestBody UserCreateDTO dto) {
    return ApiResult.ok(userService.create(dto));
}

package com.example.demo.dto;

// 创建分组：创建时校验的规则挂到这个分组
public interface Create {}

package com.example.demo.dto;

// 更新分组：更新时校验的规则挂到这个分组
public interface Update {}

package com.example.demo.dto;

import jakarta.validation.constraints.*;
import lombok.Data;

@Data
public class UserUpsertDTO {

    // 不写 groups 的注解属于默认分组，创建/更新都校验
    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度必须在 3-20 之间")
    private String username;

    // 只在「创建」时校验密码
    @NotBlank(groups = Create.class, message = "密码不能为空")
    @Size(groups = Create.class, min = 6, max = 32, message = "密码长度必须在 6-32 之间")
    private String password;

    @Email(message = "邮箱格式不正确")
    private String email;

    @Min(value = 1, message = "年龄必须大于 0")
    @Max(value = 150, message = "年龄必须小于 150")
    private Integer age;
}

@PostMapping
public ApiResult<Long> create(@Validated(Create.class) @RequestBody UserUpsertDTO dto) {
    return ApiResult.ok(userService.create(dto));
}

@PutMapping("/{id}")
public ApiResult<Void> update(@PathVariable Long id,
                              @Validated(Update.class) @RequestBody UserUpsertDTO dto) {
    userService.update(id, dto);
    return ApiResult.ok(null);
}

package com.example.demo.validator;

import jakarta.validation.Constraint;
import jakarta.validation.Payload;

import java.lang.annotation.*;

/**
 * 手机号校验注解：值为空时跳过（空校验交给 @NotBlank），非空时按正则校验。
 */
@Documented
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = PhoneValidator.class)   // 指定真正干活的校验器
public @interface Phone {

    // 校验失败时的提示（可在使用时覆盖）
    String message() default "手机号格式不正确";

    // 以下三个是 Bean Validation 规范强制要求的属性，照抄即可
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

package com.example.demo.validator;

import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;

import java.util.regex.Pattern;

/**
 * @Phone 的校验器。ConstraintValidator<注解, 校验的字段类型>
 */
public class PhoneValidator implements ConstraintValidator<Phone, String> {

    // 中国大陆手机号：1 开头，第二位 3-9，共 11 位
    private static final Pattern PHONE_PATTERN =
            Pattern.compile("^1[3-9]d{9}$");

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        // null 或空串：交给 @NotBlank 处理，这里放行，避免重复报错
        if (value == null || value.isEmpty()) {
            return true;
        }
        return PHONE_PATTERN.matcher(value).matches();
    }
}

@Data
public class UserCreateDTO {

    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度必须在 3-20 之间")
    private String username;

    @NotBlank(message = "密码不能为空")
    @Size(min = 6, max = 32, message = "密码长度必须在 6-32 之间")
    private String password;

    @Email(message = "邮箱格式不正确")
    private String email;

    @Phone(message = "手机号格式不正确")   // 自定义注解
    private String phone;

    @Min(value = 1, message = "年龄必须大于 0")
    @Max(value = 150, message = "年龄必须小于 150")
    private Integer age;
}

@Data
public class OrderCreateDTO {
    @NotBlank(message = "订单号不能为空")
    private String orderNo;

    // 集合元素也必须校验：@Valid 触发级联，否则 List<ItemDTO> 里的字段校验不生效
    @NotEmpty(message = "订单项不能为空")
    @Valid
    private List<OrderItemDTO> items;
}

@Data
public class UserCreateDTO {
    // @RequestBody 场景用 @JsonFormat，而非 @DateTimeFormat
    @JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
    private LocalDate birthday;
}

// @RequestParam 场景用 @DateTimeFormat
@GetMapping("/born-before")
public ApiResult<List<UserVO>> bornBefore(
        @RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate date) {
    return ApiResult.ok(userService.listBornBefore(date));
}

import jakarta.validation.ConstraintViolation;
import jakarta.validation.Validator;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;

import java.util.Set;
import java.util.stream.Collectors;

@Service
@RequiredArgsConstructor
public class SomeService {

    private final Validator validator;   // Spring 自动注入 javax.validation.Validator

    public void check(Object obj) {
        Set<ConstraintViolation<Object>> violations = validator.validate(obj);
        if (!violations.isEmpty()) {
            String msg = violations.stream()
                    .map(ConstraintViolation::getMessage)
                    .collect(Collectors.joining("; "));
            throw new BizException(ErrorCode.PARAM_ERROR.getCode(), msg);
        }
    }
}

import jakarta.validation.Validation;
import org.hibernate.validator.HibernateValidator;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ValidatorConfig {

    @Bean
    public jakarta.validation.Validator validator() {
        // 开启快速失败：任一字段校验失败即停止，不继续校验后续字段
        return Validation.byProvider(HibernateValidator.class)
                .configure()
                .failFast(true)
                .buildValidatorFactory()
                .getValidator();
    }
}

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());
    }
}

package com.example.demo.common;

/**
 * 统一错误码枚举。
 * 基础码（SUCCESS ~ SYSTEM_ERROR）与总规范逐字一致，数值不变，全系列复用。
 * 各篇可按需在下方追加业务错误码，但不得修改基础码。
 */
public enum ErrorCode {
    SUCCESS(0, "success"),
    PARAM_ERROR(40001, "参数错误"),
    UNAUTHORIZED(40101, "未登录或登录已过期"),
    FORBIDDEN(40301, "无权限访问"),
    USER_NOT_FOUND(40401, "用户不存在"),
    SYSTEM_ERROR(50000, "系统繁忙，请稍后重试"),

    // ===== 本阶段追加的错误码（仅追加，不修改上面基础码） =====
    TOO_MANY_REQUESTS(42901, "请求过于频繁，请稍后重试"),
    DUPLICATE_SUBMIT(40901, "请勿重复提交"),
    FILE_UPLOAD_ERROR(40003, "文件上传失败"),
    ;

    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;
    }
}

@GetMapping("/{id}")
public User getUser(@PathVariable Long id) {   // 前端拿到的是裸 User，结构不统一
    return userService.getById(id);
}

@GetMapping("/{id}")
public ApiResult<UserVO> getById(@PathVariable Long id) {
    UserVO vo = userService.getById(id);
    return ApiResult.ok(vo);   // 成功：code=0, message=success, data=vo
}

@PostMapping
public ApiResult<Long> create(@Validated @RequestBody UserCreateDTO dto) {
    Long id = userService.create(dto);
    return ApiResult.ok(id);   // 创建成功返回新 id
}

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "username": "zhangsan",
    "email": "zhangsan@example.com"
  },
  "traceId": "a1b2c3d4e5f6"
}

package com.example.demo.common;

import lombok.Data;

import java.util.List;

/**
 * 通用分页结果：列表接口的 data 统一用它承载。
 *
 * @param <T> 列表元素类型
 */
@Data
public class PageResult<T> {
    private long total;        // 总记录数
    private int page;          // 当前页码（从 1 开始）
    private int size;          // 每页条数
    private List<T> records;   // 当前页数据

    public static <T> PageResult<T> of(long total, int page, int size, List<T> records) {
        PageResult<T> result = new PageResult<>();
        result.setTotal(total);
        result.setPage(page);
        result.setSize(size);
        result.setRecords(records);
        return result;
    }
}

@GetMapping
public ApiResult<PageResult<UserVO>> list(
        @RequestParam(defaultValue = "1") int page,
        @RequestParam(defaultValue = "10") int size) {
    PageResult<UserVO> pageResult = userService.listUsers(page, size);
    return ApiResult.ok(pageResult);
}

// 坏味道一：Controller 里到处 try-catch，逻辑被异常处理淹没
@PostMapping
public ApiResult<Long> create(@RequestBody UserCreateDTO dto) {
    try {
        Long id = userService.create(dto);
        return ApiResult.ok(id);
    } catch (Exception e) {
        log.error("创建失败", e);
        return ApiResult.fail(50000, "系统错误");
    }
}

// 坏味道二：什么都不 catch，异常直接冒泡成 Tomcat 的 500 错误页
// 返回的是 HTML 而非 JSON，前端解析直接崩

package com.example.demo.exception;

import com.example.demo.common.ErrorCode;

/**
 * 统一业务异常：可预期的业务错误用它显式抛出。
 * 携带错误码，由全局异常处理器统一捕获并转成 ApiResult。
 */
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;
    }
}

User user = userMapper.selectById(id);
if (user == null) {
    // 抛业务异常，而不是返回 null 让上层猜
    throw new BizException(ErrorCode.USER_NOT_FOUND);
}

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.http.converter.HttpMessageNotReadableException;
import org.springframework.web.HttpRequestMethodNotSupportedException;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.MissingServletRequestParameterException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
import org.springframework.web.servlet.resource.NoResourceFoundException;

/**
 * 全局异常处理器：三类异常 + 若干常见框架异常，统一转 ApiResult。
 * 原则：对外模糊提示，堆栈只进日志。
 */
@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

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

    // 2. 参数校验异常（@Validated 触发）：拼出所有字段错误信息
    @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);
    }

    // 3. 兜底异常（不可预期）：记完整堆栈，对外只给模糊提示
    @ExceptionHandler(Exception.class)
    public ApiResult<Void> handleOther(Exception e) {
        log.error("系统异常", e);   // 完整堆栈进日志，便于排查
        return ApiResult.fail(ErrorCode.SYSTEM_ERROR);  // 对外不暴露任何细节
    }
}

    // 4. 请求体缺失/JSON 解析失败（如 body 为空、字段类型对不上）
    @ExceptionHandler(HttpMessageNotReadableException.class)
    public ApiResult<Void> handleNotReadable(HttpMessageNotReadableException e) {
        log.warn("请求体解析失败: {}", e.getMessage());
        return ApiResult.fail(ErrorCode.PARAM_ERROR.getCode(), "请求体格式错误");
    }

    // 5. 缺少必填请求参数（@RequestParam required=true 但没传）
    @ExceptionHandler(MissingServletRequestParameterException.class)
    public ApiResult<Void> handleMissingParam(MissingServletRequestParameterException e) {
        log.warn("缺少参数: {}", e.getParameterName());
        return ApiResult.fail(ErrorCode.PARAM_ERROR.getCode(), "缺少参数: " + e.getParameterName());
    }

    // 6. 参数类型不匹配（如 /api/users/abc 传给 Long id）
    @ExceptionHandler(MethodArgumentTypeMismatchException.class)
    public ApiResult<Void> handleTypeMismatch(MethodArgumentTypeMismatchException e) {
        log.warn("参数类型不匹配: {} = {}", e.getName(), e.getValue());
        return ApiResult.fail(ErrorCode.PARAM_ERROR.getCode(), "参数类型错误: " + e.getName());
    }

    // 7. 请求方法不支持（GET 请求了只支持 POST 的接口）
    @ExceptionHandler(HttpRequestMethodNotSupportedException.class)
    public ApiResult<Void> handleMethodNotSupported(HttpRequestMethodNotSupportedException e) {
        log.warn("请求方法不支持: {}", e.getMethod());
        return ApiResult.fail(ErrorCode.PARAM_ERROR.getCode(), "请求方法不支持: " + e.getMethod());
    }

    // 8. 静态资源/路径不存在（Spring Boot 3.2 用 NoResourceFoundException，不是旧版的 NoHandlerFoundException）
    @ExceptionHandler(NoResourceFoundException.class)
    public ApiResult<Void> handleNoResource(NoResourceFoundException e) {
        log.warn("资源不存在: {}", e.getResourcePath());
        return ApiResult.fail(40404, "请求的资源不存在");
    }

    // 文件上传超过大小限制（放在 GlobalExceptionHandler 类内）
    @ExceptionHandler(MaxUploadSizeExceededException.class)
    public ApiResult<Void> handleMaxUpload(MaxUploadSizeExceededException e) {
        log.warn("上传文件超限: {}", e.getMessage());
        return ApiResult.fail(ErrorCode.PARAM_ERROR.getCode(), "上传文件超过大小限制");
    }

package com.example.demo.filter;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.slf4j.MDC;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;
import java.util.UUID;

/**
 * traceId 过滤器：为每个请求生成/透传 traceId，放进 MDC，回写响应头。
 * OncePerRequestFilter 保证同一请求只执行一次（避免转发时重复执行）。
 */
@Component
@Order(1)   // 越小越先执行，traceId 必须最早生成，后续日志才能带上
public class TraceIdFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain)
            throws ServletException, IOException {
        // 优先透传上游 traceId（网关/负载均衡传入），实现跨服务追踪；没有则自己生成
        String traceId = request.getHeader("X-Trace-Id");
        if (traceId == null || traceId.isBlank()) {
            traceId = UUID.randomUUID().toString().replace("-", "").substring(0, 16);
        }
        // 放进 MDC：SLF4J 的线程本地上下文，之后该线程所有 log 都能打印出来
        MDC.put("traceId", traceId);
        // 回写响应头：让前端/调用方也能拿到，报错时带着 traceId 来找你
        response.setHeader("X-Trace-Id", traceId);
        try {
            filterChain.doFilter(request, response);
        } finally {
            // 关键：Tomcat 线程是复用的，必须清理，否则下一个请求会「串号」到上一个 traceId
            MDC.clear();
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- 控制台输出，pattern 里的 %X{traceId} 就是 MDC 中的 traceId -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId}] %-5level %logger{50} - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

package com.example.demo.dto;

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

/** 登录入参 */
@Data
public class LoginDTO {
    @NotBlank(message = "用户名不能为空")
    private String username;

    @NotBlank(message = "密码不能为空")
    private String password;
}

package com.example.demo.service;

import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Service;

import lombok.RequiredArgsConstructor;

import java.time.Duration;
import java.util.UUID;

/**
 * 令牌服务：登录签发 token，拦截器校验 token。
 * 简化版：token 存 Redis，真实项目可替换为 JWT（阶段 5 安全篇详讲）。
 */
@Service
@RequiredArgsConstructor
public class TokenService {

    private final StringRedisTemplate redisTemplate;

    /** 签发 token：随机 UUID，存 Redis 并设置过期时间 */
    public String issue(Long userId) {
        String token = UUID.randomUUID().toString().replace("-", "");
        redisTemplate.opsForValue().set("token:" + token, String.valueOf(userId), Duration.ofHours(2));
        return token;
    }

    /** 校验 token：存在即视为有效 */
    public boolean verify(String token) {
        if (token == null || token.isBlank()) {
            return false;
        }
        return Boolean.TRUE.equals(redisTemplate.hasKey("token:" + token));
    }
}

package com.example.demo.controller;

import com.example.demo.common.ApiResult;
import com.example.demo.dto.LoginDTO;
import com.example.demo.service.TokenService;
import com.example.demo.service.UserService;
import lombok.RequiredArgsConstructor;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/auth")
@RequiredArgsConstructor
public class AuthController {

    private final UserService userService;
    private final TokenService tokenService;

    @PostMapping("/login")
    public ApiResult<String> login(@Validated @RequestBody LoginDTO dto) {
        // 校验用户名密码（失败会抛 BizException，由全局异常处理器接管）
        Long userId = userService.login(dto);
        return ApiResult.ok(tokenService.issue(userId));
    }
}

package com.example.demo.interceptor;

import com.example.demo.common.ErrorCode;
import com.example.demo.exception.BizException;
import com.example.demo.service.TokenService;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Component;
import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.HandlerInterceptor;

/**
 * 登录态拦截器：校验 Authorization 头里的 token。
 * 失败时抛 BizException（而非返回 false），让全局异常处理器返回统一的 401 格式。
 */
@Component
@RequiredArgsConstructor
public class AuthInterceptor implements HandlerInterceptor {

    private final TokenService tokenService;

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        // 非 Controller 请求（如静态资源、错误页）直接放行
        if (!(handler instanceof HandlerMethod)) {
            return true;
        }
        String token = request.getHeader("Authorization");
        if (!tokenService.verify(token)) {
            // 抛业务异常，而不是返回 false：这样能走全局异常处理，返回 ApiResult
            throw new BizException(ErrorCode.UNAUTHORIZED);
        }
        return true;
    }
}

package com.example.demo.config;

import com.example.demo.interceptor.AuthInterceptor;
import lombok.RequiredArgsConstructor;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
@RequiredArgsConstructor
public class WebConfig implements WebMvcConfigurer {

    private final AuthInterceptor authInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(authInterceptor)
                .addPathPatterns("/api/**")          // 拦截所有 /api 接口
                .excludePathPatterns("/api/auth/login"); // 放行登录接口，否则永远登不上
    }
}

package com.example.demo.config;

import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.context.event.ApplicationReadyEvent;
import org.springframework.context.ApplicationListener;
import org.springframework.stereotype.Component;

/**
 * 应用就绪监听器：容器启动完成、能处理请求时触发，适合做预热、初始化缓存。
 */
@Component
@Slf4j
public class AppStartupListener implements ApplicationListener<ApplicationReadyEvent> {

    @Override
    public void onApplicationEvent(ApplicationReadyEvent event) {
        log.info("应用启动完成，可以开始处理请求");
    }
}

@Component
@Order(1)
public class TraceIdFilter extends OncePerRequestFilter { ... }

@Configuration
public class FilterConfig {

    @Bean
    public FilterRegistrationBean<TraceIdFilter> traceIdFilterRegistration(TraceIdFilter filter) {
        FilterRegistrationBean<TraceIdFilter> registration = new FilterRegistrationBean<>();
        registration.setFilter(filter);
        registration.addUrlPatterns("/api/*");   // 只拦 /api
        registration.setOrder(1);               // 优先级，越小越先执行
        return registration;
    }
}

package com.example.demo.entity;

import com.baomidou.mybatisplus.annotation.*;
import lombok.Data;

import java.time.LocalDateTime;

/**
 * 用户实体：与数据库表一一对应。
 * 职责边界：它只出现在 Mapper 和 Service 内部，禁止直接作为接口入参或返回值。
 * 原因：实体含 password 等敏感字段，直接返回会泄露；直接接收请求则绕过校验。
 */
@Data
@TableName("user")
public class User {

    @TableId(type = IdType.AUTO)   // 主键自增
    private Long id;

    private String username;

    private String password;       // 生产应存 BCrypt 摘要，绝不存明文

    private String email;

    private String phone;

    private Integer age;

    private Integer status;        // 1=正常 0=禁用

    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;

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

    @TableLogic                    // 逻辑删除：delete 变成 update deleted=1
    private Integer deleted;
}

package com.example.demo.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.example.demo.entity.User;
import org.apache.ibatis.annotations.Mapper;

/**
 * 继承 BaseMapper 即获得 selectById/insert/updateById/deleteById/selectPage 等能力，
 * 无需写一行 SQL。复杂 SQL 再写 @Select 或 XML。
 */
@Mapper
public interface UserMapper extends BaseMapper<User> {
}

package com.example.demo.dto;

import com.example.demo.validator.Phone;
import jakarta.validation.constraints.*;
import lombok.Data;

/** 创建用户入参 */
@Data
public class UserCreateDTO {

    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度必须在 3-20 之间")
    private String username;

    @NotBlank(message = "密码不能为空")
    @Size(min = 6, max = 32, message = "密码长度必须在 6-32 之间")
    private String password;

    @Email(message = "邮箱格式不正确")
    private String email;

    @Phone(message = "手机号格式不正确")   // 自定义校验注解（第 3 章）
    private String phone;

    @Min(value = 1, message = "年龄必须大于 0")
    @Max(value = 150, message = "年龄必须小于 150")
    private Integer age;
}

package com.example.demo.dto;

import com.example.demo.validator.Phone;
import jakarta.validation.constraints.*;
import lombok.Data;

/** 更新用户入参：用户名不可改，密码走独立流程，这里只更新可编辑字段 */
@Data
public class UserUpdateDTO {

    @Email(message = "邮箱格式不正确")
    private String email;

    @Phone(message = "手机号格式不正确")
    private String phone;

    @Min(value = 1, message = "年龄必须大于 0")
    @Max(value = 150, message = "年龄必须小于 150")
    private Integer age;

    @Min(value = 0, message = "状态值非法")
    @Max(value = 1, message = "状态值非法")
    private Integer status;
}

package com.example.demo.dto;

import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import lombok.Data;

/**
 * 列表查询入参：GET 请求的查询串参数自动绑定到对象字段（@ModelAttribute 绑定）。
 */
@Data
public class UserQueryDTO {

    @Min(value = 1, message = "页码最小为 1")
    private int page = 1;      // 默认值：不传则用 1

    @Min(value = 1, message = "每页条数最小为 1")
    @Max(value = 100, message = "每页条数最大为 100")
    private int size = 10;     // 默认值：不传则用 10

    private String keyword;    // 按用户名模糊搜索
}

package com.example.demo.vo;

import lombok.Data;

import java.time.LocalDateTime;

/**
 * 用户出参 VO：只返回前端需要的字段。
 * 与 Entity 的关键区别：没有 password 字段——这是三层分离的核心价值，
 * 从结构上杜绝「把密码返回给前端」这类事故。
 */
@Data
public class UserVO {
    private Long id;
    private String username;
    private String email;
    private String phone;
    private Integer age;
    private Integer status;
    private LocalDateTime createTime;
}

package com.example.demo.service;

import com.example.demo.common.PageResult;
import com.example.demo.dto.*;
import com.example.demo.vo.UserVO;

public interface UserService {

    UserVO getById(Long id);

    PageResult<UserVO> listUsers(UserQueryDTO query);

    Long create(UserCreateDTO dto);

    void update(Long id, UserUpdateDTO dto);

    void delete(Long id);

    /** 登录校验：成功返回 userId，失败抛 BizException */
    Long login(LoginDTO dto);
}

package com.example.demo.service.impl;

import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.example.demo.common.ErrorCode;
import com.example.demo.common.PageResult;
import com.example.demo.dto.*;
import com.example.demo.entity.User;
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.stereotype.Service;
import org.springframework.util.StringUtils;

import java.util.List;

@Service
@RequiredArgsConstructor   // 构造器注入：对 final 字段生成构造器，依赖不可变
@Slf4j
public class UserServiceImpl implements UserService {

    private final UserMapper userMapper;

    @Override
    public UserVO getById(Long id) {
        User user = userMapper.selectById(id);
        if (user == null) {
            // 业务错误用 BizException 抛出，交给全局异常处理器
            throw new BizException(ErrorCode.USER_NOT_FOUND);
        }
        return toVO(user);
    }

    @Override
    public PageResult<UserVO> listUsers(UserQueryDTO query) {
        // MyBatis-Plus 分页
        Page<User> page = new Page<>(query.getPage(), query.getSize());
        LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<User>()
                // like 第一个参数是条件开关：keyword 为空时该条件不生效
                .like(StringUtils.hasText(query.getKeyword()), User::getUsername, query.getKeyword())
                .orderByDesc(User::getCreateTime);
        Page<User> result = userMapper.selectPage(page, wrapper);
        List<UserVO> vos = result.getRecords().stream().map(this::toVO).toList();
        return PageResult.of(result.getTotal(), query.getPage(), query.getSize(), vos);
    }

    @Override
    public Long create(UserCreateDTO dto) {
        // 业务校验（格式校验已在前置拦截）：用户名唯一
        Long count = userMapper.selectCount(
                new LambdaQueryWrapper<User>().eq(User::getUsername, dto.getUsername()));
        if (count > 0) {
            // 用 int+message 构造器演示临时业务码；正式项目建议加入 ErrorCode 枚举统一管理
            throw new BizException(40003, "用户名已存在");
        }

        User user = new User();
        user.setUsername(dto.getUsername());
        user.setPassword(dto.getPassword());  // 生产：先 BCrypt 加密再存，阶段 5 详讲
        user.setEmail(dto.getEmail());
        user.setPhone(dto.getPhone());
        user.setAge(dto.getAge());
        user.setStatus(1);
        userMapper.insert(user);

        // 脱敏日志：username 可打，但密码/手机号等敏感信息不落日志
        log.info("创建用户成功: id={}, username={}", user.getId(), user.getUsername());
        return user.getId();
    }

    @Override
    public void update(Long id, UserUpdateDTO dto) {
        User user = userMapper.selectById(id);
        if (user == null) {
            throw new BizException(ErrorCode.USER_NOT_FOUND);
        }
        user.setEmail(dto.getEmail());
        user.setPhone(dto.getPhone());
        user.setAge(dto.getAge());
        if (dto.getStatus() != null) {
            user.setStatus(dto.getStatus());
        }
        userMapper.updateById(user);
        log.info("更新用户成功: id={}", id);
    }

    @Override
    public void delete(Long id) {
        User user = userMapper.selectById(id);
        if (user == null) {
            throw new BizException(ErrorCode.USER_NOT_FOUND);
        }
        // 逻辑删除：@TableLogic 让 deleteById 变成 update deleted=1
        userMapper.deleteById(id);
        log.info("删除用户成功: id={}", id);
    }

    @Override
    public Long login(LoginDTO dto) {
        User user = userMapper.selectOne(
                new LambdaQueryWrapper<User>().eq(User::getUsername, dto.getUsername()));
        if (user == null || !user.getPassword().equals(dto.getPassword())) {
            // 统一用「用户名或密码错误」，不透露到底是哪个错（防撞库）
            throw new BizException(40102, "用户名或密码错误");
        }
        return user.getId();
    }

    /** Entity → VO：裁剪掉 password 等敏感字段 */
    private UserVO toVO(User user) {
        UserVO vo = new UserVO();
        vo.setId(user.getId());
        vo.setUsername(user.getUsername());
        vo.setEmail(user.getEmail());
        vo.setPhone(user.getPhone());
        vo.setAge(user.getAge());
        vo.setStatus(user.getStatus());
        vo.setCreateTime(user.getCreateTime());
        return vo;
    }
}