SpringBoot实战：接口参数校验与优雅处理

接口参数校验是后端开发的第一道防线。与其在业务代码中写满if (name null)不如使用 Spring Boot 提供的参数校验机制让代码更简洁、逻辑更清晰。一、 为什么需要参数校验在早期的开发中我们经常在 Service 层写大量的防御性代码publicvoidcreateUser(UserDTOdto){if(StringUtils.isEmpty(dto.getName())){thrownewIllegalArgumentException(用户名不能为空);}if(dto.getAge()null||dto.getAge()0){thrownewIllegalArgumentException(年龄必须为正数);}if(!dto.getEmail().matches(^[\\w-\\.]([\\w-]\\.)[\\w-]{2,4}$)){thrownewIllegalArgumentException(邮箱格式不正确);}// ... 业务逻辑}这种方式的缺点显而易见代码臃肿校验逻辑与业务逻辑混杂难以阅读。维护困难一旦校验规则变更需要修改多处代码。复用性差同样的 DTO 在不同接口中可能需要不同的校验规则。Spring Boot 整合了 Hibernate Validator实现了 Bean Validation 规范为我们提供了声明式的参数校验方案。二、 快速上手1. 引入依赖在 Spring Boot 2.3.x 之前spring-boot-starter-web已经包含了 validation 依赖。但在Spring Boot 2.3.x 及之后需要显式引入dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-validation/artifactId/dependency2. 定义 DTO 并添加注解我们在 DTOData Transfer Object的字段上直接添加校验注解DatapublicclassUserDTO{NotBlank(message用户名不能为空)Size(min2,max20,message用户名长度必须在 2-20 之间)privateStringusername;NotNull(message年龄不能为空)Min(value0,message年龄必须大于等于 0)Max(value150,message年龄必须小于等于 150)privateIntegerage;Email(message邮箱格式不正确)privateStringemail;}3. Controller 层开启校验在 Controller 的方法参数前添加Valid或Validated注解RestControllerRequestMapping(/user)publicclassUserController{PostMappingpublicResultVoidcreateUser(ValidRequestBodyUserDTOuserDTO){// 如果参数校验失败程序不会进入这里而是抛出 MethodArgumentNotValidExceptionuserService.createUser(userDTO);returnResult.success();}}三、 进阶用法1.ValidvsValidatedValid: 属于 JSR-303 标准支持嵌套校验即如果一个对象内部包含另一个对象内部对象的注解也会被校验。Validated: 是 Spring 提供的注解功能更强大支持分组校验但默认不支持嵌套校验需要配合Valid使用。通常在 Controller 参数上使用Validated在 DTO 内部嵌套对象上使用Valid。2. 自定义校验注解当内置注解无法满足需求时例如校验手机号我们可以自定义注解。Step 1: 定义注解Target({ElementType.FIELD,ElementType.PARAMETER})Retention(RetentionPolicy.RUNTIME)DocumentedConstraint(validatedByPhoneValidator.class)// 指定校验器publicinterfacePhone{Stringmessage()default手机号格式不正确;Class?[]groups()default{};Class?extendsPayload[]payload()default{};}Step 2: 实现校验器publicclassPhoneValidatorimplementsConstraintValidatorPhone,String{privatestaticfinalStringPHONE_REGEX^1[3-9]\\d{9}$;OverridepublicbooleanisValid(Stringvalue,ConstraintValidatorContextcontext){if(StringUtils.isEmpty(value)){returntrue;// 是否为空由 NotBlank/NotNull 控制这里只校验格式}returnvalue.matches(PHONE_REGEX);}}Step 3: 使用DatapublicclassUserDTO{// ... 其他字段Phone(message请输入有效的手机号码)privateStringphone;}3. 分组校验 (Validation Groups)同一个 DTO 在“创建”和“更新”场景下校验规则可能不同。例如创建时id应该为空更新时id必须有值。定义分组接口publicinterfaceCreateGroup{}publicinterfaceUpdateGroup{}配置 DTO 分组DatapublicclassUserDTO{Null(message创建用户时 ID 必须为空,groupsCreateGroup.class)NotNull(message更新用户时 ID 不能为空,groupsUpdateGroup.class)privateLongid;NotBlank(message用户名不能为空,groups{CreateGroup.class,UpdateGroup.class})privateStringusername;}Controller 中指定分组PostMappingpublicResultVoidcreateUser(Validated(CreateGroup.class)RequestBodyUserDTOuserDTO){// ...}PutMappingpublicResultVoidupdateUser(Validated(UpdateGroup.class)RequestBodyUserDTOuserDTO){// ...}注意使用分组校验时如果字段没有指定groups默认属于Default组。如果指定了groups则不再属于 Default 组。这意味着如果 Controller 使用Validated不加参数即 Default 组那些指定了自定义 Group 的注解将不会生效。四、 异常处理集成参数校验失败时会抛出异常。对于RequestBody参数抛出的是MethodArgumentNotValidException对于RequestParam或路径参数抛出的是ConstraintViolationException。我们需要在全局异常处理器中统一捕获它们RestControllerAdvicepublicclassGlobalExceptionHandler{ExceptionHandler(MethodArgumentNotValidException.class)publicResult?handleValidationException(MethodArgumentNotValidExceptione){Stringmessagee.getBindingResult().getFieldErrors().stream().map(DefaultMessageSourceResolvable::getDefaultMessage).collect(Collectors.joining(, ));returnResult.fail(400,message);}ExceptionHandler(ConstraintViolationException.class)publicResult?handleConstraintViolation(ConstraintViolationExceptione){Stringmessagee.getConstraintViolations().stream().map(ConstraintViolation::getMessage).collect(Collectors.joining(, ));returnResult.fail(400,message);}}五、 最佳实践总结DTO 与 Entity 分离校验注解通常加在 DTO 上不要直接加在数据库实体 Entity 上。快速失败 (Fail-Fast)默认情况下Validator 会校验所有字段并收集错误。如果希望发现第一个错误就停止可以在类上添加GroupSequence或者自定义 Validator 实现逻辑。明确错误提示每个校验注解都应该指定清晰的message方便前端直接展示给用户。嵌套对象校验如果 DTO 中包含对象如AddressDTO address需要在字段上同时添加Valid才能触发内部对象的校验。复杂逻辑校验对于跨字段校验如“密码”与“确认密码”必须一致建议使用自定义 Class 级别的校验注解。六、 总结参数校验是系统安全的第一道关卡。通过 Spring Validation 框架我们将散落在各处的if-else转化为声明式的注解配合全局异常处理实现了一套既优雅又强大的参数校验方案。掌握这些技巧让你的接口开发事半功倍 福利时间如果你正在备战面试或者想要学习其他知识给大家推荐一个宝藏知识库作者整理了一些列 Java 程序员需要掌握的核心知识有需要的自取不谢。知识库地址https://farerboy.com/