参数校验与全局异常处理体系

@PostMapping("/users")public Result<UserVO> create(@RequestBody Map<String, Object> body) {    String username = (String) body.get("username");    String email = (String) body.get("email");    Integer age = (Integer) body.get("age");    if (username == null || username.trim().isEmpty()) {        return Result.fail(40000, "用户名不能为空");    }    if (username.length() > 32) {        return Result.fail(40000, "用户名不能超过 32 个字符");    }    if (email == null || !email.matches("^[\\w.-]+@[\\w.-]+$")) {        return Result.fail(40000, "邮箱格式不正确");    }    if (age != null && (age < 18 || age > 120)) {        return Result.fail(40000, "年龄必须在 18 到 120 之间");    }    // ……终于轮到真正的业务逻辑，它已经被淹没在 if 里    return Result.ok(userService.create(username, email, age));}

@PostMapping("/users")public Result<UserVO> create(@Valid @RequestBody UserCreateDTO dto) {    // 业务方法里只剩业务    return Result.ok(userService.create(dto));}public record UserCreateDTO(        @NotBlank(message = "用户名不能为空")        @Size(max = 32, message = "用户名不能超过 32 个字符")        String username,        @NotBlank(message = "邮箱不能为空")        @Email(message = "邮箱格式不正确")        String email,        @Min(value = 18, message = "年龄不能小于 18 岁")        @Max(value = 120, message = "年龄不能大于 120 岁")        Integer age) {}

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

@Validated@RestController@RequestMapping("/api/users")public class UserController {    // @Validated 让类内所有方法参数约束生效    @GetMapping("/{id}")    public UserVO detail(            @PathVariable @Positive(message = "用户 ID 必须为正数") Long id,            @RequestParam @Min(value = 1, message = "页码从 1 开始") int page) {        return userService.detail(id, page);    }}

// 1) 定义两个空接口作为分组标记public interface ValidGroups {    interface Create {}    interface Update {}}

public record UserDTO(        @Null(groups = ValidGroups.Create.class, message = "新增时不能指定 ID")        @NotNull(groups = ValidGroups.Update.class, message = "更新时必须指定 ID")        Long id,        @NotBlank(groups = {ValidGroups.Create.class, ValidGroups.Update.class},                  message = "用户名不能为空")        String username) {}

@Target({ElementType.FIELD, ElementType.PARAMETER})@Retention(RetentionPolicy.RUNTIME)@Constraint(validatedBy = PhoneValidator.class)     // 绑定校验器@Documentedpublic @interface Phone {    String message() default "手机号格式不正确";    Class<?>[] groups() default {};    Class<? extends Payload>[] payload() default {};    /** 是否允许为空；默认 true，配合 @NotBlank 使用 */    boolean required() default false;}

public class PhoneValidator implements ConstraintValidator<Phone, String> {    private static final Pattern CN_MOBILE = Pattern.compile("^1[3-9]\\d{9}$");    private boolean required;    @Override    public void initialize(Phone annotation) {        this.required = annotation.required();    }    @Override    public boolean isValid(String value, ConstraintValidatorContext context) {        if (value == null || value.isBlank()) {            return !required;        // 非必填时空值视为通过        }        return CN_MOBILE.matcher(value).matches();    }}

public record ProfileUpdateDTO(        @NotBlank String nickname,        @Phone(required = true, message = "请填写有效的手机号")        String mobile) {}

# src/main/resources/messages.properties（默认，英文兜底）NotBlank=must not be blankSize=size must be between {min} and {max}Phone=invalid phone number# src/main/resources/messages_zh_CN.propertiesNotBlank=不能为空Size=长度必须在 {min} 到 {max} 之间Phone=手机号格式不正确

spring:  messages:    basename: messages    encoding: UTF-8

package com.example.common.exception;import com.example.common.api.ErrorCode;import com.example.common.api.Result;import jakarta.servlet.http.HttpServletRequest;import jakarta.validation.ConstraintViolationException;import lombok.extern.slf4j.Slf4j;import org.springframework.http.HttpStatus;import org.springframework.validation.BindException;import org.springframework.validation.FieldError;import org.springframework.web.HttpRequestMethodNotSupportedException;import org.springframework.web.bind.MethodArgumentNotValidException;import org.springframework.web.bind.annotation.ExceptionHandler;import org.springframework.web.bind.annotation.ResponseStatus;import org.springframework.web.bind.annotation.RestControllerAdvice;import org.springframework.web.servlet.NoHandlerFoundException;import java.util.List;import java.util.UUID;/** * 全局异常兜底：把各类异常翻译成统一的 Result + 正确的 HTTP 状态码。 */@Slf4j@RestControllerAdvicepublic class GlobalExceptionHandler {    /** 1) @RequestBody 对象校验失败 */    @ResponseStatus(HttpStatus.BAD_REQUEST)    @ExceptionHandler(MethodArgumentNotValidException.class)    public Result<List<FieldErrorVO>> handleInvalidBody(MethodArgumentNotValidException e) {        List<FieldErrorVO> errors = e.getBindingResult().getFieldErrors().stream()                .map(this::toFieldError)                .toList();        return Result.fail(ErrorCode.INVALID_PARAM.getCode(), "参数校验失败", errors);    }    /** 2) 表单 / @ModelAttribute 对象校验失败 */    @ResponseStatus(HttpStatus.BAD_REQUEST)    @ExceptionHandler(BindException.class)    public Result<List<FieldErrorVO>> handleBind(BindException e) {        List<FieldErrorVO> errors = e.getBindingResult().getFieldErrors().stream()                .map(this::toFieldError)                .toList();        return Result.fail(ErrorCode.INVALID_PARAM.getCode(), "参数校验失败", errors);    }    /** 3) @Validated 在类上校验散装参数失败 */    @ResponseStatus(HttpStatus.BAD_REQUEST)    @ExceptionHandler(ConstraintViolationException.class)    public Result<List<FieldErrorVO>> handleConstraint(ConstraintViolationException e) {        List<FieldErrorVO> errors = e.getConstraintViolations().stream()                .map(v -> new FieldErrorVO(lastNode(v.getPropertyPath()), v.getMessage()))                .toList();        return Result.fail(ErrorCode.INVALID_PARAM.getCode(), "参数校验失败", errors);    }    /** 4) 业务异常：错误码与状态码由异常自身携带 */    @ExceptionHandler(BizException.class)    public org.springframework.http.ResponseEntity<Result<Void>> handleBiz(            BizException e, HttpServletRequest request) {        ErrorCode ec = e.getErrorCode();        log.warn("biz exception: {} {} -> {}", request.getMethod(), request.getRequestURI(), e.getMessage());        return org.springframework.http.ResponseEntity                .status(ec.getHttpStatus())                .body(Result.fail(ec.getCode(), e.getMessage()));    }    /** 5) 找不到处理器 → 404 */    @ResponseStatus(HttpStatus.NOT_FOUND)    @ExceptionHandler(NoHandlerFoundException.class)    public Result<Void> handleNotFound(NoHandlerFoundException e) {        return Result.fail(ErrorCode.RESOURCE_NOT_FOUND);    }    /** 6) 请求方法不支持 → 405 */    @ResponseStatus(HttpStatus.METHOD_NOT_ALLOWED)    @ExceptionHandler(HttpRequestMethodNotSupportedException.class)    public Result<Void> handleMethod(HttpRequestMethodNotSupportedException e) {        return Result.fail(ErrorCode.METHOD_NOT_ALLOWED.getCode(), e.getMessage());    }    /** 7) 兜底：未知异常 → 500，带 traceId 便于排查 */    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)    @ExceptionHandler(Exception.class)    public Result<Void> handleUnknown(Exception e, HttpServletRequest request) {        String traceId = UUID.randomUUID().toString().replace("-", "").substring(0, 16);        log.error("unhandled exception, traceId={}, uri={}", traceId, request.getRequestURI(), e);        return Result.fail(ErrorCode.SYSTEM_ERROR.getCode(),                "系统繁忙，请稍后重试（traceId: " + traceId + "）");    }    private FieldErrorVO toFieldError(FieldError fe) {        return new FieldErrorVO(fe.getField(), fe.getDefaultMessage());    }    private String lastNode(jakarta.validation.Path path) {        String s = path.toString();        int i = s.lastIndexOf('.');        return i >= 0 ? s.substring(i + 1) : s;    }    public record FieldErrorVO(String field, String message) {}}

org.springframework.web.bind.MethodArgumentNotValidException: Validation failed for argument [0] in public com.example.api.Result com.example.user.UserController.create(com.example.user.UserCreateDTO): [Field error in object 'userCreateDTO' on field 'username': rejected value []; codes [NotBlank.userCreateDTO.username,NotBlank.username,NotBlank.java.lang.String,NotBlank]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [...]]; default message [用户名不能为空]]

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

package com.example.valid;import jakarta.validation.*;import jakarta.validation.constraints.*;public record SignUpDTO(        @NotBlank(message = "用户名不能为空")        @Size(max = 32, message = "用户名不能超过 32 个字符")        String username,        @NotBlank(message = "邮箱不能为空")        @Email(message = "邮箱格式不正确")        String email,        @Min(value = 18, message = "年龄不能小于 18 岁")        Integer age) {}

package com.example.valid;import jakarta.validation.ConstraintViolationException;import org.springframework.http.HttpStatus;import org.springframework.web.bind.MethodArgumentNotValidException;import org.springframework.web.bind.annotation.*;import java.util.List;@RestControllerAdviceclass ApiErrors {    record FieldErr(String field, String message) {}    @ResponseStatus(HttpStatus.BAD_REQUEST)    @ExceptionHandler(MethodArgumentNotValidException.class)    List<FieldErr> invalidBody(MethodArgumentNotValidException e) {        return e.getBindingResult().getFieldErrors().stream()                .map(fe -> new FieldErr(fe.getField(), fe.getDefaultMessage()))                .toList();    }    @ResponseStatus(HttpStatus.BAD_REQUEST)    @ExceptionHandler(ConstraintViolationException.class)    List<String> invalidParam(ConstraintViolationException e) {        return e.getConstraintViolations().stream()                .map(v -> v.getPropertyPath() + ": " + v.getMessage())                .toList();    }}

curl -i -X POST http://localhost:8080/api/signup \     -H "Content-Type: application/json" \     -d '{"username":"","email":"not-an-email","age":17}'

HTTP/1.1 400Content-Type: application/json[{"field":"username","message":"用户名不能为空"}, {"field":"email","message":"邮箱格式不正确"}, {"field":"age","message":"年龄不能小于 18 岁"}]