参数校验与异常处理

这一课你将能做到

1. 用 Bean Validation 注解声明式校验入参，拦截非法数据并返回清晰的错误提示
2. 写一个全局异常处理器，把校验失败、业务异常、未知异常统一转换成规范 JSON
3. 建立业务错误码体系，让前端拿到结构一致的失败响应

为什么要学

上一课的创建接口，传 "title":"" 也能创建成功——脏数据进了库，前端展示乱成一团；而 Controller 里到处 if (title == null || title.isBlank()) 又会淹没业务逻辑。另外，一旦某个 Service 抛了未处理异常，接口直接甩出 500 白页堆栈，前端完全没法处理。

两件事各需要一个机制：校验负责「把不合法的请求挡在业务门口」，声明式注解一行顶十个 if；全局异常处理负责「所有失败出口收敛成统一格式」，业务代码里只管 throw，收尾交给处理器。这两个机制是接口「能用」到「能用得体面」的分水岭，也是本站后端接口规范的地基。

先建立图像

请求进入 Controller
   ↓ @Valid 触发校验（Hibernate Validator 执行）
   ├─ 校验失败 ──→ 抛 MethodArgumentNotValidException ─┐
   ↓ 校验通过                                          │
业务方法执行                                            │
   ├─ 业务不满足 ──→ throw BusinessException ──────────┤→ @RestControllerAdvice 统一捕获
   ↓ 业务成功                                          │
正常返回                                              │
   ├─ 未知异常 ──→ Exception ─────────────────────────┘
                                              ↓
                              统一 JSON：{code, message, errors?}

一句话：正常路径走业务，所有异常路径汇入 Advice 汇成一个出口。

名词	人话
Bean Validation	Java 校验规范（jakarta.validation），定义 @NotBlank 等注解
Hibernate Validator	该规范的参考实现，Boot 引 starter-validation 即用
@Valid	触发校验的开关，标在要校验的参数上
@RestControllerAdvice	全局「异常翻译器」，所有 Controller 共享

跟着做

步骤 1：引入校验 starter

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

注意：Boot 2.3 起它不再是 starter-web 的一部分，必须单独引入，否则 @Valid 静默不生效。

步骤 2：给 DTO 加校验注解 + @Valid 触发

新建 DTO（改造上一课的 CreateRequest 为独立类并加校验）：

package com.example.taskflow.dto;

import jakarta.validation.constraints.*;

public record TaskCreateRequest(
        @NotBlank(message = "任务标题不能为空")
        @Size(max = 50, message = "任务标题不能超过 50 字")
        String title,

        @NotNull(message = "优先级不能为空")
        @Min(value = 1, message = "优先级最小为 1")
        @Max(value = 5, message = "优先级最大为 5")
        Integer priority,

        @Pattern(regexp = "^(19|20)\\d{2}-\\d{2}-\\d{2}$", message = "截止日期格式应为 yyyy-MM-dd")
        String deadline,

        @Email(message = "通知邮箱格式不正确")
        String notifyEmail
) {}