SpringMVC 执行流程与拦截器

// GET /users?pageNum=1&pageSize=10
@GetMapping("/users")
public Result<Page<User>> list(
    @RequestParam(name = "page", defaultValue = "1") Integer pageNum,
    @RequestParam(name = "size", defaultValue = "10") Integer pageSize,
    @RequestParam(required = false) String keyword) {
    // ...
}

// GET /users/123
@GetMapping("/users/{id}")
public Result<User> getUser(@PathVariable Long id) {
    return Result.success(userService.findById(id));
}

// 多个路径变量
// GET /users/123/orders/456
@GetMapping("/users/{userId}/orders/{orderId}")
public Result<Order> getOrder(
    @PathVariable Long userId,
    @PathVariable Long orderId) {
    return Result.success(orderService.findByUserAndId(userId, orderId));
}

@PostMapping("/users")
public Result<User> create(@RequestBody UserCreateDTO dto) {
    return Result.success(userService.create(dto));
}

// 接收 JSON 数组
@PostMapping("/users/batch")
public Result<Void> batchCreate(@RequestBody List<UserCreateDTO> dtos) {
    userService.batchCreate(dtos);
    return Result.success(null);
}

@GetMapping("/profile")
public Result<User> getProfile(
    @RequestHeader("Authorization") String token,
    @CookieValue("sessionId") String sessionId) {
    // ...
}

// POST /users?username=zhangsan&age=25
@PostMapping("/users")
public Result<User> create(User user) {
    return Result.success(userService.save(user));
}

public class UserBatchVO {
    private List<Long> ids;
    private String reason;
    // getter setter
}

// 前端: ids[0]=1&ids[1]=2&reason=批量删除
@PostMapping("/users/batch-delete")
public Result<Void> batchDelete(UserBatchVO vo) {
    userService.batchDelete(vo.getIds(), vo.getReason());
    return Result.success();
}

// DTO 上添加校验注解
public class UserCreateDTO {
    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度必须在3-20之间")
    private String username;

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

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

// Controller 中使用 @Validated
@PostMapping("/users")
public Result<User> create(@Validated @RequestBody UserCreateDTO dto) {
    return Result.success(userService.create(dto));
}

// 方式一：实现 Converter 接口
@Component
public class StringToDateConverter implements Converter<String, Date> {
    @Override
    public Date convert(String source) {
        try {
            return new SimpleDateFormat("yyyy-MM-dd").parse(source);
        } catch (ParseException e) {
            throw new IllegalArgumentException("日期格式错误，请使用 yyyy-MM-dd");
        }
    }
}

// 方式二：使用 @DateTimeFormat 注解（Spring Boot 自动注册）
public class User {
    @DateTimeFormat(pattern = "yyyy-MM-dd")
    private Date birthday;
}

// 方式一：方法级别
@GetMapping("/users/{id}")
@ResponseBody
public User getUser(@PathVariable Long id) {
    return userService.findById(id);
}

// 方式二：类级别（推荐）
@RestController
@RequestMapping("/api/users")
public class UserRestController {
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return userService.findById(id);
    }
}

@GetMapping("/users/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    User user = userService.findById(id);
    if (user == null) {
        return ResponseEntity.notFound().build();
    }
    return ResponseEntity.ok()
            .header("X-User-Id", String.valueOf(user.getId()))
            .body(user);
}

// 转发（一次请求，地址栏不变）
@GetMapping("/forward-demo")
public String forwardDemo() {
    return "forward:/pages/user-list";
}

// 重定向（两次请求，地址栏改变，避免表单重复提交）
@PostMapping("/save")
public String save(User user) {
    userService.save(user);
    return "redirect:/pages/user-list";
}

@Data
public class Result<T> {
    private Integer code;
    private String message;
    private T data;
    private Long timestamp;

    public static <T> Result<T> success(T data) {
        Result<T> result = new Result<>();
        result.setCode(200);
        result.setMessage("success");
        result.setData(data);
        result.setTimestamp(System.currentTimeMillis());
        return result;
    }

    public static <T> Result<T> fail(Integer code, String message) {
        Result<T> result = new Result<>();
        result.setCode(code);
        result.setMessage(message);
        result.setTimestamp(System.currentTimeMillis());
        return result;
    }
}

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

    @GetMapping
    public Result<List<User>> list() {
        return Result.success(userService.findAll());
    }

    @GetMapping("/{id}")
    public Result<User> getById(@PathVariable Long id) {
        User user = userService.findById(id);
        if (user == null) {
            return Result.fail(404, "用户不存在");
        }
        return Result.success(user);
    }

    @PostMapping
    public Result<User> create(@Validated @RequestBody UserCreateDTO dto) {
        return Result.success(userService.create(dto));
    }

    @PutMapping("/{id}")
    public Result<User> update(@PathVariable Long id,
                              @Validated @RequestBody UserUpdateDTO dto) {
        dto.setId(id);
        return Result.success(userService.update(dto));
    }

    @DeleteMapping("/{id}")
    public Result<Void> delete(@PathVariable Long id) {
        userService.delete(id);
        return Result.success(null);
    }
}

<!-- web.xml -->
<servlet>
    <servlet-name>dispatcherServlet</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>classpath:springmvc.xml</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
    <servlet-name>dispatcherServlet</servlet-name>
    <url-pattern>/</url-pattern>
</servlet-mapping>

// Spring Boot 自动注册 DispatcherServlet
// 无需手动配置，通过 application.yml 调整参数

// application.yml
spring:
  mvc:
    servlet:
      path: /                    # DispatcherServlet 映射路径
      load-on-startup: 1         # 启动时加载
    async:
      request-timeout: 30000     # 异步请求超时时间

public interface HandlerMapping {
    // 根据请求找到 HandlerExecutionChain
    @Nullable
    HandlerExecutionChain getHandler(HttpServletRequest request) throws Exception;
}

// 启动时扫描所有 @RequestMapping 方法并注册映射
@Controller
@RequestMapping("/users")
public class UserController {

    @GetMapping("/{id}")
    public Result<User> getUser(@PathVariable Long id) {
        return Result.success(userService.findById(id));
    }

    @PostMapping
    public Result<User> createUser(@Validated @RequestBody UserCreateDTO dto) {
        return Result.success(userService.create(dto));
    }

    @PutMapping("/{id}")
    public Result<User> updateUser(@PathVariable Long id, @RequestBody UserUpdateDTO dto) {
        return Result.success(userService.update(id, dto));
    }
}

// HandlerMapping 会注册以下映射:
// GET    /users/{id}   -> UserController.getUser()
// POST   /users        -> UserController.createUser()
// PUT    /users/{id}   -> UserController.updateUser()

public class HandlerExecutionChain {
    private final Object handler;                              // Handler 方法
    private final List<HandlerInterceptor> interceptorList;    // 拦截器链
    private int interceptorIndex = -1;                         // 当前执行的拦截器索引

    // 执行 preHandle
    boolean applyPreHandle(HttpServletRequest request, HttpServletResponse response) throws Exception {
        for (int i = 0; i < this.interceptorList.size(); i++) {
            HandlerInterceptor interceptor = this.interceptorList.get(i);
            if (!interceptor.preHandle(request, response, this.handler)) {
                triggerAfterCompletion(request, response, null);
                return false;
            }
            this.interceptorIndex = i;
        }
        return true;
    }

    // 执行 postHandle
    void applyPostHandle(HttpServletRequest request, HttpServletResponse response, @Nullable ModelAndView mv) {
        for (int i = this.interceptorList.size() - 1; i >= 0; i--) {
            HandlerInterceptor interceptor = this.interceptorList.get(i);
            interceptor.postHandle(request, response, this.handler, mv);
        }
    }
}

public interface HandlerAdapter {
    // 判断是否支持该 Handler
    boolean supports(Object handler);

    // 执行 Handler 方法
    @Nullable
    ModelAndView handle(HttpServletRequest request,
                       HttpServletResponse response,
                       Object handler) throws Exception;

    // 获取 Last-Modified 时间戳
    long getLastModified(HttpServletRequest request, Object handler);
}

@GetMapping("/users/{id}/orders")
public Result<Page<Order>> getUserOrders(
    @PathVariable Long id,                    // 路径变量：从 URL 路径提取
    @RequestParam(defaultValue = "1") Integer page,  // 请求参数：从查询参数提取
    @RequestParam(defaultValue = "10") Integer size,
    @RequestHeader("X-Token") String token,   // 请求头：从请求头提取
    @CookieValue("sessionId") String sessionId, // Cookie：从 Cookie 提取
    HttpServletRequest request,               // Servlet API：直接注入
    Principal principal,                      // 认证信息：从 SecurityContext 注入
    @CurrentUser User user                    // 自定义参数：通过自定义解析器注入
) {
    // HandlerAdapter 会自动完成以下工作:
    // 1. 从 URL 路径 /users/123/orders 提取 id = 123
    // 2. 从查询参数 ?page=2&size=20 提取 page=2, size=20
    // 3. 从请求头 X-Token 提取 token 值
    // 4. 从 Cookie 提取 sessionId 值
    // 5. 注入 HttpServletRequest 对象
    // 6. 注入当前认证用户 Principal
    // 7. 通过自定义参数解析器注入当前用户
}

// 1. 返回 JSON（@ResponseBody）
@GetMapping("/users/{id}")
@ResponseBody
public User getUser(@PathVariable Long id) {
    return userService.findById(id);
}
// 等价于（类级别 @RestController）
@RestController
public class UserController {
    @GetMapping("/users/{id}")
    public User getUser(@PathVariable Long id) {
        return userService.findById(id);
    }
}

// 2. 返回视图名（String）
@GetMapping("/users/{id}/profile")
public String userProfile(@PathVariable Long id, Model model) {
    model.addAttribute("user", userService.findById(id));
    return "user/profile";  // 解析为 /WEB-INF/views/user/profile.jsp
}

// 3. 返回 ModelAndView
@GetMapping("/users/{id}/detail")
public ModelAndView userDetail(@PathVariable Long id) {
    ModelAndView mv = new ModelAndView("user/detail");
    mv.addObject("user", userService.findById(id));
    return mv;
}

// 4. 返回 ResponseEntity（带响应头和状态码）
@GetMapping("/users/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    User user = userService.findById(id);
    if (user == null) {
        return ResponseEntity.notFound().build();
    }
    return ResponseEntity.ok()
            .header("X-User-Id", String.valueOf(user.getId()))
            .body(user);
}

// 5. 异步返回（CompletableFuture）
@GetMapping("/users/{id}/async")
public CompletableFuture<User> getUserAsync(@PathVariable Long id) {
    return CompletableFuture.supplyAsync(() -> userService.findById(id));
}

public interface ViewResolver {
    @Nullable
    View resolveViewName(String viewName, Locale locale) throws Exception;
}

// Spring Boot 3.x 配置 Thymeleaf
// application.yml
spring:
  thymeleaf:
    prefix: classpath:/templates/
    suffix: .html
    cache: false  # 开发环境关闭缓存

// Spring Boot 3.x 配置 JSP（不推荐，仅作参考）
spring:
  mvc:
    view:
      prefix: /WEB-INF/views/
      suffix: .jsp

// 传统 Java Config 配置
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Bean
    public ViewResolver viewResolver() {
        InternalResourceViewResolver resolver = new InternalResourceViewResolver();
        resolver.setPrefix("/WEB-INF/views/");
        resolver.setSuffix(".jsp");
        resolver.setOrder(1);
        return resolver;
    }
}

// Controller 返回 "user/list"
// 解析为: /WEB-INF/views/user/list.jsp（JSP）
// 或: classpath:/templates/user/list.html（Thymeleaf）

@Controller
public class UserController {

    @GetMapping("/users")
    public String listUsers(Model model) {
        model.addAttribute("users", userService.findAll());
        return "user/list";
    }
}

public interface HandlerInterceptor {

    /**
     * 前置处理：在 Handler 执行前调用
     * @return true 继续执行，false 中断请求
     */
    default boolean preHandle(HttpServletRequest request,
                             HttpServletResponse response,
                             Object handler) throws Exception {
        return true;
    }

    /**
     * 后置处理：在 Handler 执行后、视图渲染前调用
     * 可以修改 ModelAndView
     */
    default void postHandle(HttpServletRequest request,
                           HttpServletResponse response,
                           Object handler,
                           @Nullable ModelAndView modelAndView) throws Exception {
    }

    /**
     * 完成回调：在视图渲染后调用（无论成功或异常）
     * 用于资源清理
     */
    default void afterCompletion(HttpServletRequest request,
                                HttpServletResponse response,
                                Object handler,
                                @Nullable Exception ex) throws Exception {
    }
}

@Component
public class LoginInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request,
                             HttpServletResponse response,
                             Object handler) throws Exception {
        // 1. 从 Session 获取用户信息
        HttpSession session = request.getSession(false);
        if (session == null || session.getAttribute("user") == null) {
            // 2. 未登录，返回 401
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.setContentType("application/json;charset=UTF-8");
            response.getWriter().write("{\"code\":401,\"message\":\"未登录，请先登录\"}");
            return false;  // 中断请求
        }

        // 3. 已登录，将用户信息放入请求上下文
        User user = (User) session.getAttribute("user");
        request.setAttribute("currentUser", user);
        return true;
    }
}

@Component
@Slf4j
public class AuditLogInterceptor implements HandlerInterceptor {

    private static final String START_TIME = "startTime";
    private static final String TRACE_ID = "traceId";

    @Override
    public boolean preHandle(HttpServletRequest request,
                             HttpServletResponse response,
                             Object handler) throws Exception {
        // 1. 生成 TraceId
        String traceId = UUID.randomUUID().toString().replace("-", "");
        request.setAttribute(TRACE_ID, traceId);
        MDC.put("traceId", traceId);  // 放入日志上下文，便于日志追踪

        // 2. 记录请求开始
        request.setAttribute(START_TIME, System.currentTimeMillis());

        // 3. 获取 Handler 信息
        if (handler instanceof HandlerMethod handlerMethod) {
            String className = handlerMethod.getBeanType().getSimpleName();
            String methodName = handlerMethod.getMethod().getName();
            log.info("[{}] 请求开始: {} {} -> {}.{}",
                    traceId, request.getMethod(), request.getRequestURI(),
                    className, methodName);
        } else {
            log.info("[{}] 请求开始: {} {}",
                    traceId, request.getMethod(), request.getRequestURI());
        }

        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request,
                                HttpServletResponse response,
                                Object handler,
                                Exception ex) throws Exception {
        // 1. 计算耗时
        Long startTime = (Long) request.getAttribute(START_TIME);
        long duration = System.currentTimeMillis() - (startTime != null ? startTime : 0L);

        // 2. 记录请求结束
        String traceId = (String) request.getAttribute(TRACE_ID);
        if (ex != null) {
            log.error("[{}] 请求异常: 状态={}, 耗时={}ms, 异常={}",
                    traceId, response.getStatus(), duration, ex.getMessage());
        } else {
            log.info("[{}] 请求结束: 状态={}, 耗时={}ms",
                    traceId, response.getStatus(), duration);
        }

        // 3. 清理 MDC 上下文，防止内存泄漏
        MDC.remove("traceId");
    }
}

@Component
@Slf4j
public class PerformanceInterceptor implements HandlerInterceptor {

    @Autowired
    private MeterRegistry meterRegistry;  // Micrometer 指标注册

    private static final String START_TIME = "startTime";

    @Override
    public boolean preHandle(HttpServletRequest request,
                             HttpServletResponse response,
                             Object handler) throws Exception {
        request.setAttribute(START_TIME, System.currentTimeMillis());
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request,
                                HttpServletResponse response,
                                Object handler,
                                Exception ex) throws Exception {
        Long startTime = (Long) request.getAttribute(START_TIME);
        if (startTime == null) return;

        long duration = System.currentTimeMillis() - startTime;
        String uri = request.getRequestURI();
        String method = request.getMethod();
        int status = response.getStatus();

        // 1. 记录 Prometheus 指标
        Timer.builder("http.server.requests")
                .tag("method", method)
                .tag("uri", uri)
                .tag("status", String.valueOf(status))
                .register(meterRegistry)
                .record(Duration.ofMillis(duration));

        // 2. 慢请求告警（超过 3 秒）
        if (duration > 3000) {
            log.warn("慢请求告警: {} {} 耗时 {}ms, 状态={}",
                    method, uri, duration, status);
        }
    }
}

@Component
public class PermissionInterceptor implements HandlerInterceptor {

    @Autowired
    private PermissionService permissionService;

    @Override
    public boolean preHandle(HttpServletRequest request,
                             HttpServletResponse response,
                             Object handler) throws Exception {
        // 1. 获取当前用户
        User user = (User) request.getAttribute("currentUser");
        if (user == null) {
            response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "未登录");
            return false;
        }

        // 2. 检查 Handler 方法上的权限注解
        if (handler instanceof HandlerMethod handlerMethod) {
            RequirePermission annotation = handlerMethod.getMethodAnnotation(RequirePermission.class);
            if (annotation != null) {
                String requiredPermission = annotation.value();

                // 3. 检查权限
                if (!permissionService.hasPermission(user.getId(), requiredPermission)) {
                    response.sendError(HttpServletResponse.SC_FORBIDDEN,
                            "无权限: " + requiredPermission);
                    return false;
                }
            }
        }

        return true;
    }
}

// 自定义权限注解
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface RequirePermission {
    String value();
}

// 使用示例
@RestController
@RequestMapping("/admin")
public class AdminController {

    @GetMapping("/users")
    @RequirePermission("user:list")
    public Result<List<User>> listUsers() {
        return Result.success(userService.findAll());
    }

    @DeleteMapping("/users/{id}")
    @RequirePermission("user:delete")
    public Result<Void> deleteUser(@PathVariable Long id) {
        userService.delete(id);
        return Result.success();
    }
}

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Autowired
    private LoginInterceptor loginInterceptor;

    @Autowired
    private AuditLogInterceptor auditLogInterceptor;

    @Autowired
    private PermissionInterceptor permissionInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 1. 审计日志拦截器（最先执行，记录所有请求）
        registry.addInterceptor(auditLogInterceptor)
                .addPathPatterns("/**")
                .order(1);

        // 2. 登录校验拦截器
        registry.addInterceptor(loginInterceptor)
                .addPathPatterns("/**")
                .excludePathPatterns(
                        "/login",
                        "/register",
                        "/error",
                        "/static/**",
                        "/swagger-ui/**",
                        "/v3/api-docs/**"
                )
                .order(2);

        // 3. 权限校验拦截器（依赖登录拦截器）
        registry.addInterceptor(permissionInterceptor)
                .addPathPatterns("/**")
                .excludePathPatterns(
                        "/login",
                        "/register",
                        "/error",
                        "/static/**"
                )
                .order(3);
    }
}

// Spring Boot 3.x 可以直接注入所有 HandlerInterceptor Bean
// 无需手动注册，但需要配置路径

@Component
public class LoginInterceptor implements HandlerInterceptor, WebMvcConfigurer {

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(this)
                .addPathPatterns("/**")
                .excludePathPatterns("/login", "/register");
    }
}

public interface AsyncHandlerInterceptor extends HandlerInterceptor {

    /**
     * 异步请求开始时调用（在主线程分发给异步线程后）
     */
    default void afterConcurrentHandlingStarted(HttpServletRequest request,
                                                HttpServletResponse response,
                                                Object handler) throws Exception {
    }
}

// 示例：异步请求的 TraceId 传递
@Component
public class AsyncTraceInterceptor implements AsyncHandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request,
                             HttpServletResponse response,
                             Object handler) {
        // 主线程设置 TraceId
        String traceId = UUID.randomUUID().toString();
        request.setAttribute("traceId", traceId);
        MDC.put("traceId", traceId);
        return true;
    }

    @Override
    public void afterConcurrentHandlingStarted(HttpServletRequest request,
                                               HttpServletResponse response,
                                               Object handler) {
        // 异步线程开始前，需要将 TraceId 传递到异步线程
        String traceId = (String) request.getAttribute("traceId");
        // 使用 TaskDecorator 将 MDC 传递到异步线程
    }

    @Override
    public void afterCompletion(HttpServletRequest request,
                                HttpServletResponse response,
                                Object handler,
                                Exception ex) {
        MDC.remove("traceId");
    }
}

// 过滤器：处理编码和 XSS
@Component
@Order(1)
public class CharacterEncodingFilter implements Filter {

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        request.setCharacterEncoding("UTF-8");
        response.setCharacterEncoding("UTF-8");
        response.setContentType("application/json;charset=UTF-8");
        chain.doFilter(request, response);
    }
}

// 过滤器：XSS 防护
@Component
@Order(2)
public class XssFilter implements Filter {

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        // 包装请求，过滤 XSS 字符
        XssHttpServletRequestWrapper wrappedRequest = new XssHttpServletRequestWrapper((HttpServletRequest) request);
        chain.doFilter(wrappedRequest, response);
    }
}

// 拦截器：处理登录和审计
@Component
public class LoginInterceptor implements HandlerInterceptor {

    @Autowired
    private UserService userService;  // 可以自动注入

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        String token = request.getHeader("Authorization");
        User user = userService.findByToken(token);
        if (user == null) {
            response.setStatus(401);
            return false;
        }
        request.setAttribute("currentUser", user);
        return true;
    }
}

@PostMapping("/users")
public Result<User> createUser(@RequestBody User user) {
    return Result.success(userService.create(user));
}

// 前端发送:
// {"name": "张三", "age": "abc"}  // age 应该是数字，但传了字符串

org.springframework.http.converter.HttpMessageNotReadableException:
JSON parse error: Cannot deserialize value of type `java.lang.Integer` from String "abc"

// 方案 1：使用 @Validated 校验
@PostMapping("/users")
public Result<User> createUser(@Validated @RequestBody User user) {
    return Result.success(userService.create(user));
}

public class User {
    @NotBlank(message = "姓名不能为空")
    private String name;

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

    // getters and setters
}

// 方案 2：全局异常处理
@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(HttpMessageNotReadableException.class)
    public Result<?> handleHttpMessageNotReadableException(HttpMessageNotReadableException e) {
        return Result.fail(400, "请求参数格式错误: " + e.getCause().getMessage());
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<?> handleValidationException(MethodArgumentNotValidException e) {
        String message = e.getBindingResult().getFieldErrors().stream()
                .map(FieldError::getDefaultMessage)
                .collect(Collectors.joining(", "));
        return Result.fail(400, message);
    }
}

// 方案 3：开启 DEBUG 日志
// application.yml
logging:
  level:
    org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter: DEBUG
    org.springframework.http.converter.json.MappingJackson2HttpMessageConverter: DEBUG

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 顺序错误：日志拦截器需要用户信息，但登录拦截器还未执行
        registry.addInterceptor(logInterceptor).addPathPatterns("/**");
        registry.addInterceptor(loginInterceptor).addPathPatterns("/**");
    }
}

// 日志拦截器中:
public class LogInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        User user = (User) request.getAttribute("currentUser");  // null!
        log.info("用户 {} 执行了操作", user.getName());  // NullPointerException!
        return true;
    }
}

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 正确顺序：登录拦截器先执行
        registry.addInterceptor(loginInterceptor)
                .addPathPatterns("/**")
                .excludePathPatterns("/login", "/register")
                .order(1);

        // 日志拦截器后执行
        registry.addInterceptor(logInterceptor)
                .addPathPatterns("/**")
                .order(2);
    }
}

@Component
public class LoginInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        String token = request.getHeader("Authorization");
        if (token == null) {
            throw new BusinessException("未登录");  // 错误：拦截器中的异常不会被全局异常处理器捕获！
        }
        return true;
    }
}

@Component
public class LoginInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)
            throws IOException {
        String token = request.getHeader("Authorization");
        if (token == null) {
            // 手动写入响应
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.setContentType("application/json;charset=UTF-8");
            response.getWriter().write("{\"code\":401,\"message\":\"未登录，请先登录\"}");
            return false;  // 中断请求
        }
        return true;
    }
}

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(loginInterceptor)
                .addPathPatterns("/*");  // 错误：只匹配一级路径
    }
}

// 问题:
// /users        会匹配
// /users/123    不会匹配！
// /api/users    不会匹配！

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(loginInterceptor)
            .addPathPatterns("/**")  // 正确：匹配所有路径
            .excludePathPatterns(
                    "/login",
                    "/register",
                    "/static/**",
                    "/error"
            );
}

Access to XMLHttpRequest at 'http://api.example.com/users' from origin
'http://localhost:3000' has been blocked by CORS policy:
No 'Access-Control-Allow-Origin' header is present on the requested resource.

// 方案 1：@CrossOrigin 注解（细粒度控制）
@RestController
@RequestMapping("/api")
@CrossOrigin(
        origins = "http://localhost:3000",
        methods = {RequestMethod.GET, RequestMethod.POST, RequestMethod.PUT, RequestMethod.DELETE},
        allowedHeaders = "*",
        allowCredentials = "true",
        maxAge = 3600
)
public class ApiController {
    // ...
}

// 方案 2：全局 CORS 配置（推荐）
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOriginPatterns("http://localhost:*")
                .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
                .allowedHeaders("*")
                .allowCredentials(true)
                .maxAge(3600);
    }
}

// 方案 3：CORS 过滤器（最灵活）
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)  // 最高优先级，确保在所有过滤器之前执行
public class CorsFilter implements Filter {

    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
            throws IOException, ServletException {
        HttpServletResponse response = (HttpServletResponse) res;
        HttpServletRequest request = (HttpServletRequest) req;

        String origin = request.getHeader("Origin");
        if (origin != null && origin.startsWith("http://localhost:")) {
            response.setHeader("Access-Control-Allow-Origin", origin);
        }

        response.setHeader("Access-Control-Allow-Methods", "GET,POST,PUT,DELETE,OPTIONS");
        response.setHeader("Access-Control-Allow-Headers", "*");
        response.setHeader("Access-Control-Allow-Credentials", "true");
        response.setHeader("Access-Control-Max-Age", "3600");

        // 预检请求直接返回
        if ("OPTIONS".equalsIgnoreCase(request.getMethod())) {
            response.setStatus(HttpServletResponse.SC_OK);
            return;
        }

        chain.doFilter(req, res);
    }
}

// 1. 统一响应格式
@Data
@AllArgsConstructor
@NoArgsConstructor
public class Result<T> {
    private Integer code;
    private String message;
    private T data;
    private Long timestamp;

    public static <T> Result<T> success(T data) {
        return new Result<>(200, "success", data, System.currentTimeMillis());
    }

    public static <T> Result<T> fail(String message) {
        return new Result<>(500, message, null, System.currentTimeMillis());
    }

    public static <T> Result<T> fail(Integer code, String message) {
        return new Result<>(code, message, null, System.currentTimeMillis());
    }
}

// 2. 使用 ResponseBodyAdvice 统一包装
@RestControllerAdvice
public class ResponseWrapperAdvice implements ResponseBodyAdvice<Object> {

    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        // 排除已经包装过的 Result 类型
        return !returnType.getParameterType().equals(Result.class);
    }

    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType,
                                  Class<? extends HttpMessageConverter<?>> selectedConverterType,
                                  ServerHttpRequest request, ServerHttpResponse response) {
        // 统一包装为 Result
        return Result.success(body);
    }
}

// 3. 全局异常处理
@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

    // 业务异常
    @ExceptionHandler(BusinessException.class)
    public Result<?> handleBusinessException(BusinessException e) {
        log.warn("业务异常: {}", e.getMessage());
        return Result.fail(e.getCode(), e.getMessage());
    }

    // 参数校验异常（@RequestBody + @Validated）
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<?> handleValidationException(MethodArgumentNotValidException e) {
        String message = e.getBindingResult().getFieldErrors().stream()
                .map(FieldError::getDefaultMessage)
                .collect(Collectors.joining(", "));
        log.warn("参数校验失败: {}", message);
        return Result.fail(400, message);
    }

    // 参数绑定异常（表单提交）
    @ExceptionHandler(BindException.class)
    public Result<?> handleBindException(BindException e) {
        String message = e.getBindingResult().getFieldErrors().stream()
                .map(FieldError::getDefaultMessage)
                .collect(Collectors.joining(", "));
        return Result.fail(400, message);
    }

    // 缺少请求参数
    @ExceptionHandler(MissingServletRequestParameterException.class)
    public Result<?> handleMissingParam(MissingServletRequestParameterException e) {
        return Result.fail(400, "缺少参数: " + e.getParameterName());
    }

    // 请求方法不支持
    @ExceptionHandler(HttpRequestMethodNotSupportedException.class)
    public Result<?> handleMethodNotSupported(HttpRequestMethodNotSupportedException e) {
        return Result.fail(405, "不支持 " + e.getMethod() + " 请求方法");
    }

    // 其他异常
    @ExceptionHandler(Exception.class)
    public Result<?> handleException(Exception e) {
        log.error("系统异常", e);
        return Result.fail("系统繁忙，请稍后重试");
    }
}

// 4. 自定义业务异常
public class BusinessException extends RuntimeException {
    private final Integer code;

    public BusinessException(String message) {
        super(message);
        this.code = 500;
    }

    public BusinessException(Integer code, String message) {
        super(message);
        this.code = code;
    }

    public Integer getCode() {
        return code;
    }
}

# application.yml
spring:
  servlet:
    multipart:
      max-file-size: 5MB       # 单个文件最大 5MB
      max-request-size: 10MB   # 整个请求最大 10MB

@RestController
@RequestMapping("/api/files")
public class FileController {

    @Value("${file.upload-path:/tmp/upload/}")
    private String uploadPath;

    @PostMapping("/upload")
    public Result<String> upload(@RequestParam("file") MultipartFile file) throws IOException {
        // 1. 校验
        if (file.isEmpty()) {
            return Result.fail(400, "文件不能为空");
        }
        String contentType = file.getContentType();
        if (!List.of("image/jpeg", "image/png", "image/gif").contains(contentType)) {
            return Result.fail(400, "只支持 JPG、PNG、GIF 格式");
        }

        // 2. UUID 重命名 + 按日期分目录存储
        String extension = file.getOriginalFilename()
            .substring(file.getOriginalFilename().lastIndexOf("."));
        String newFilename = UUID.randomUUID() + extension;
        String datePath = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd"));
        Path dirPath = Paths.get(uploadPath, datePath);
        Files.createDirectories(dirPath);

        // 3. 保存文件
        file.transferTo(dirPath.resolve(newFilename));

        // 4. 返回访问路径
        String fileUrl = "/upload/" + datePath + "/" + newFilename;
        return Result.success(fileUrl);
    }
}

@PostMapping("/batch-upload")
public Result<List<String>> batchUpload(@RequestParam("files") MultipartFile[] files) throws IOException {
    List<String> fileUrls = new ArrayList<>();
    for (MultipartFile file : files) {
        if (!file.isEmpty()) {
            String url = saveFile(file);
            fileUrls.add(url);
        }
    }
    return Result.success(fileUrls);
}

@GetMapping("/download/{filename}")
public void download(@PathVariable String filename,
                    HttpServletResponse response) throws IOException {
    Path filePath = Paths.get(uploadPath, filename);
    if (!Files.exists(filePath)) {
        response.sendError(HttpServletResponse.SC_NOT_FOUND);
        return;
    }
    response.setContentType("application/octet-stream");
    response.setHeader("Content-Disposition",
        "attachment; filename=" + URLEncoder.encode(filename, StandardCharsets.UTF_8));
    response.setHeader("Content-Length", String.valueOf(Files.size(filePath)));
    Files.copy(filePath, response.getOutputStream());
}

@Override
public void afterCompletion(HttpServletRequest request,
                            HttpServletResponse response,
                            Object handler,
                            Exception ex) {
    // 异步记录审计日志
    CompletableFuture.runAsync(() -> {
        auditLogService.record(request, response);
    });
}

@Component
public class PermissionInterceptor implements HandlerInterceptor {

    @Autowired
    private CacheManager cacheManager;

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        User user = (User) request.getAttribute("currentUser");
        // 缓存用户权限，避免重复查询
        Cache cache = cacheManager.getCache("userPermissions");
        String cacheKey = "user:" + user.getId() + ":permissions";
        Set<String> permissions = cache.get(cacheKey, () ->
                permissionService.findPermissionsByUserId(user.getId())
        );
        request.setAttribute("userPermissions", permissions);
        return true;
    }
}

@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)
        throws IOException {
    if (!checkLogin(request)) {
        response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
        response.setContentType("application/json;charset=UTF-8");
        response.getWriter().write("{\"code\":401,\"message\":\"未登录\"}");
        return false;
    }
    return true;
}

@Component
public class CurrentUserArgumentResolver implements HandlerMethodArgumentResolver {
    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.hasParameterAnnotation(CurrentUser.class)
            && parameter.getParameterType().equals(User.class);
    }

    @Override
    public Object resolveArgument(MethodParameter parameter, ...) {
        String token = webRequest.getHeader("Authorization");
        return userService.findByToken(token);
    }
}