直接上干货。做后端接口开发的人,大概都经历过那种满屏if判断时期——参数一个个取出来,手动判空、判长度、判格式,校验逻辑散落到每个Controller里。Spring Boot这套接口参数校验体系,核心就是Bean Validation规范加上Hibernate Validator实现,配合全局异常处理,把校验从业务代码里彻底抽离出去。这篇文章我会从最基础的注解使用讲起,再深入到分组校验、自定义注解、嵌套校验,最后把实操里容易踩的坑挨个列一遍,内容偏通用工程实践,适合刚接触Spring Boot校验的初学者,也适合项目里校验逻辑混乱、想重构的老手。1. 先说清楚通用到底解决什么问题1.1 手工校验的代码是怎么失控的我见过不少项目,接口参数校验全靠Controller里的if-else硬扛。比如创建用户接口里要校验用户名非空、手机号格式、年龄范围、邮箱合法性,代码长这样:PostMapping(/users) public ResultVoid createUser(RequestBody UserCreateRequest request) { if (request.getUsername() null || request.getUsername().isEmpty()) { return Result.error(用户名不能为空); } if (request.getUsername().length() 2 || request.getUsername().length() 20) { return Result.error(用户名长度必须在2-20之间); } if (request.getMobile() null || !request.getMobile().matches(^1[3-9]\\d{9}$)) { return Result.error(手机号格式不正确); } if (request.getAge() null || request.getAge() 18) { return Result.error(年龄必须大于等于18); } // 继续校验其他字段... // 然后才进入真正的业务逻辑 }单个接口这么写还能接受,但接口数量一多,问题就暴露了:校验逻辑重复劳动,每个人写的风格还不一样;新增字段时忘了补校验是常态;更重要的是,业务方法和校验逻辑搅在一起,代码的可读性直线下降。参数从十几个涨到三十几个的时候,Controller方法里上半屏全是校验,真正干活的代码只有几行,这种项目维护起来非常痛苦。1.2 注解校验带来的思维转变Spring Boot方案里的通用,核心转变是把校验规则声明在数据模型上,而不是写在业务流程里。你只需要在DTO字段上打注解,框架通过校验器统一执行规则,异常统一被全局处理器拦截。这样做的直接好处有三个:第一,校验规则跟着DTO走,同一个对象在多处使用时规则天然一致;第二,Controller代码去掉校验逻辑后非常干净;第三,自定义校验器做一次,全项目复用。而且这套标准背后是有JSR规范支撑的。Java生态里Bean Validation规范从JSR-303演进到JSR-380(也就是Bean Validation 2.0),Spring Boot 2.x以后默认集成了Hibernate Validator 6.x,基本把规范里的注解全部实现了。Spring Boot 3.x则使用Hibernate Validator 8.x配合Jakarta EE命名空间,注解包名从javax.validation换到了jakarta.validation。理解这个背景很重要,你搜资料的时候会看到很多老文章用javax开头的包名,在Spring Boot 3.x项目里直接复制是编译不过的。2. 基础实战:一套标准校验长什么样2.1 核心注解速查表先过一遍最常用的注解,这些都是Bean Validation规范里定义的,不需要额外引包:注解作用使用场景NotNull值不能为null包装类型字段,比如Integer、LongNotBlank值不能为null且去空格后长度必须大于0String类型必填字段NotEmpty值不能为null且size大于0String、集合、数组、MapSize值长度或size必须在指定范围内字符串长度、集合大小Min / Max数值必须大于等于/小于等于指定值数字类型Positive / PositiveOrZero正数 / 非负数数字类型Pattern必须匹配正则表达式手机号、身份证等格式校验Email必须是合法邮箱格式邮箱字段这里特别强调一下NotNull和NotBlank的区别,这是新手最容易踩的坑。前端传一个空字符串过来,如果字段标注的是NotNull,校验是能通过的,因为空串不是null。如果你的业务要求用户名不能为空,那么请用NotBlank,它同时拒绝了null、空串和纯空格的情况。同理,NotEmpty用于集合字段,比如List参数传了空数组就不能通过。2.2 一个完整的DTO校验示例实际操作中,我会把请求参数封装成独立的DTO。以创建用户接口为例:Data public class UserCreateRequest { NotBlank(message 用户名不能为空) Size(min 2, max 20, message 用户名长度必须在2-20之间) private String username; NotBlank(message 手机号不能为空) Pattern(regexp ^1[3-9]\\d{9}$, message 手机号格式不正确) private String mobile; NotNull(message 年龄不能为空) Min(value 18, message 年龄不能小于18岁) private Integer age; Email(message 邮箱格式不正确) private String email; NotBlank(message 部门不能为空) private String department; }Controller里配合Validated注解触发校验:RestController RequestMapping(/api/users) public class UserController { PostMapping public ResultVoid createUser(Validated RequestBody UserCreateRequest request) { // 这里直接写业务逻辑,参数已经是校验过的了 userService.createUser(request); return Result.success(); } }注意Validated加在方法参数上,Spring会启动MethodValidationPostProcessor,对入参执行校验。RequestBody注解解析完JSON后,校验器马上开始干活,校验不通过会抛出MethodArgumentNotValidException异常。2.3 校验失败后的异常到底去哪了没有异常处理时,Spring Boot默认会把错误信息返回给前端,状态码400,响应体结构是Spring默认的格式,不够友好,也不统一。因此通用参数校验里最关键的一环就是把异常拦截住,包装成项目统一的响应结构。我一般会建一个全局异常处理器,专门处理参数校验相关的三类异常:MethodArgumentNotValidException:处理RequestBody参数校验失败ConstraintViolationException:处理RequestParam、PathVariable参数校验失败BindException:处理表单绑定参数校验失败统一响应体的基础结构我习惯这样定义:Data public class ResultT { private int code; private String message; private T data; public static T ResultT success(T data) { ResultT r new Result(); r.code 0; r.message success; r.data data; return r; } public static T ResultT error(int code, String message) { ResultT r new Result(); r.code code; r.message message; return r; } }全局异常处理的完整写法放在第三章详细拆,这一步你只需要明白:校验框架只负责判断对错,返回什么提示给前端是异常处理器负责的活。3. 异常处理与错误响应,通用性的核心3.1 全局异常处理器的完整实现参数校验的通用性,很大程度上体现在异常处理策略上。我会把校验异常全部收敛到一个类里处理,业务代码里完全不出现try-catch校验逻辑。RestControllerAdvice public class GlobalExceptionHandler { private static final Logger log LoggerFactory.getLogger(GlobalExceptionHandler.class); ExceptionHandler(MethodArgumentNotValidException.class) public ResultVoid handleMethodArgumentNotValid(MethodArgumentNotValidException ex) { String message ex.getBindingResult().getFieldErrors().stream() .map(error - error.getField() : error.getDefaultMessage()) .collect(Collectors.joining(; )); log.warn(参数校验失败: {}, message); return Result.error(400, message); } ExceptionHandler(ConstraintViolationException.class) public ResultVoid handleConstraintViolation(ConstraintViolationException ex) { String message ex.getConstraintViolations().stream() .map(v - v.getPropertyPath() : v.getMessage()) .collect(Collectors.joining(; )); log.warn(参数校验失败: {}, message); return Result.error(400, message); } ExceptionHandler(BindException.class) public ResultVoid handleBind(BindException ex) { String message ex.getBindingResult().getFieldErrors().stream() .map(error - error.getField() : error.getDefaultMessage()) .collect(Collectors.joining(; )); log.warn(参数绑定校验失败: {}, message); return Result.error(400, message); } }这里有个容易忽略的点:MethodArgumentNotValidException和BindException都提供了getBindingResult()方法,可以拿到字段级错误详情。每个FieldError包含field、defaultMessage等属性,按字段拼出提示语,前端能精确知道哪个参数出了问题。3.2 错误提示的国际化思路真实项目里,直接把用户名长度必须在2-20之间这种中文硬编码在注解message里,初期没问题,一旦要做多语言版本就难受了。推荐的思路是message里写错误码,响应之前做国际化映射:NotBlank(message {error.user.username.notblank}) private String username;然后resources目录下放messages.properties:error.user.username.notblank用户名不能为空 error.user.username.size用户名长度必须在2-20之间Spring Boot默认配置了MessageSource,只要在application配置里指定basename,框架会自动根据Locale解析。不过这套配置有个前提:需要在项目里稍微定制一下错误码解析,否则校验器不知道去哪里找资源。Hibernate Validator本身对{xxx}占位符的处理规则是:先尝试从注解属性里找,找不到再从ValidationMessages.properties里找。如果你想让占位符从Spring的MessageSource解析,通常需要注入MessageSourceInterpolator。我建议中小项目先用硬编码中文,等真有多语言需求再引入国际化,步子太大容易给自己挖坑。3.3 别忽略校验异常和其他异常的顺序全局异常处理器往往不止一个方法,除了校验异常,还有业务异常、未知异常等等。这里要留意异常处理方法的匹配优先级:Spring会优先匹配更深层的异常类型。如果业务异常类继承了RuntimeException,同时处理器里又有ExceptionHandler(BusinessException.class)和ExceptionHandler(Exception.class),那么抛出BusinessException时会优先进入更具体的BusinessException方法,不会误入兜底逻辑。还有一个细节:异常处理里不要把所有异常都吞掉返回200。有人会把Exception全部catch住,return Result.success,导致前端收到code0但数据完全是错误结果,这种做法非常坑。校验失败该返回400就返回400,兜底异常返回500,基础的状态码语义要守住。4. 进阶玩法:分组校验与自定义注解4.1 分组校验解决同一个DTO在不同接口规则不同很多场景下,同一个DTO在新增和更新时校验规则不一样。比如创建用户时id必须为空,更新用户时id必须不为空。如果不做分组,只能写两个DTO,代码冗余。Bean Validation用groups属性解决这个问题。先定义两个分组标记接口:public interface CreateGroup {} public interface UpdateGroup {}DTO里给注解指定分组:Data public class UserSaveRequest { Null(groups CreateGroup.class, message 新增时ID必须为空) NotNull(groups UpdateGroup.class, message 更新时ID不能为空) private Long id; NotBlank(groups {CreateGroup.class, UpdateGroup.class}, message 用户名不能为空) Size(min 2, max 20, message 用户名长度必须在2-20之间) private String username; NotBlank(groups CreateGroup.class, message 创建时必须填写手机号) private String mobile; }注意:没有显式声明groups的注解,默认属于Default分组。当校验器执行CreateGroup分组校验时,默认分组里的注解反而不会生效。这个特性坑人,后面我在踩坑章节会重点讲。Controller的用法:PostMapping public ResultVoid create(Validated(CreateGroup.class) RequestBody UserSaveRequest request) { return Result.success(); } PutMapping(/{id}) public ResultVoid update(Validated(UpdateGroup.class) RequestBody UserSaveRequest request) { return Result.success(); }关键点:Validated注解的value属性传入分组Class,Spring就知道当前接口要启用哪组校验规则。这里有个隐含的坑:Valid注解不支持分组,只能靠Validated。所以凡是涉及分组校验的接口,一定不要写Valid,这会静默地忽略groups属性,导致所有分组规则失效。4.2 自定义校验注解,最灵活的一张牌框架自带的注解覆盖了大部分场景,但总有奇怪的需求。比如我要校验一个字符串只能包含大写字母和下划线,用Pattern也行,但业务上如果这个格式在多个地方被使用,重复写正则就违反通用的初衷了。这时候自定义注解更优雅。完整的自定义注解包含两部分:注解定义和校验器实现。Target({ElementType.FIELD, ElementType.PARAMETER}) Retention(RetentionPolicy.RUNTIME) Constraint(validatedBy UpperCaseWithUnderlineValidator.class) public interface UpperCaseWithUnderline { String message() default 只能包含大写字母和下划线; Class?[] groups() default {}; Class? extends Payload[] payload() default {}; }校验器实现ConstraintValidator接口:public class UpperCaseWithUnderlineValidator implements ConstraintValidatorUpperCaseWithUnderline, String { private static final Pattern PATTERN Pattern.compile(^[A-Z_]$); Override public boolean isValid(String value, ConstraintValidatorContext context) { if (value null) { return true; } return PATTERN.matcher(value).matches(); } }有几个细节值得说。第一,Constraint注解的validatedBy属性用来告诉校验器框架这个注解归哪个类管;第二,isValid里对null值直接放行,空值判断交给NotBlank这类注解去管,单一职责;第三,自定义注解定义里必须包含message、groups、payload三个默认属性,这是Bean Validation规范的要求,缺了会编译不过。使用起来和内置注解一样:NotBlank(message 编码不能为空) UpperCaseWithUnderline(message 编码只能包含大写字母和下划线) private String code;如果校验器里需要用到注解上的参数,比如自定义一个范围校验MyRange(min 1, max 10),可以在validator里实现initialize方法拿注解实例:public class MyRangeValidator implements ConstraintValidatorMyRange, Integer { private int min; private int max; Override public void initialize(MyRange constraintAnnotation) { this.min constraintAnnotation.min(); this.max constraintAnnotation.max(); } Override public boolean isValid(Integer value, ConstraintValidatorContext context) { if (value null) { return true; } return value min value max; } }4.3 嵌套对象和集合的校验DTO里嵌套另一个DTO是很常见的。比如创建订单时,订单项是一个List:Data public class OrderCreateRequest { NotNull(message 订单项不能为空) Size(min 1, message 至少要有一个订单项) Valid private ListValid OrderItemRequest items; NotBlank(message 收货地址不能为空) private String address; } Data public class OrderItemRequest { NotBlank(message 商品编码不能为空) private String skuCode; NotNull(message 商品数量不能为空) Min(value 1, message 商品数量至少为1) private Integer count; }这里有两个Valid:一个加在字段上,一个加在泛型参数上。字段上的Valid告诉框架这个List里的每个元素都要递归校验;泛型参数上的Valid是Java类型注解的用法,在Bean Validation 2.0之后支持。两个配合才能保证List中每个OrderItemRequest里的约束都能触发。实际开发中我只写字段上的Valid,List泛型里的Valid也建议加上,兼容性最好。嵌套对象同理:NotNull(message 用户信息不能为空) Valid private UserInfoRequest userInfo;不加Valid的情况下,嵌套对象内部的注解完全不会执行,这是新手最容易踩的深坑,配置文件里看不到任何报错,但嵌套字段的约束一律失效。5. 尽量别踩的坑:这些问题我基本都遇到过5.1 Valid和Validated的混用错觉Valid是JSR规范里的标准注解,Validated是Spring提供的变体。前者只能用在字段、方法参数上,后者还可以用在类上。如果Controller类上标了Validated,方法参数上的校验注解才能对RequestParam和PathVariable生效;而RequestBody的校验,无论用Valid还是Validated都能触发,但分组校验时必须用Validated。我建议统一用Validated,少些纠结。但要注意,类上标了Validated之后,方法参数上必须再标一次Validated,否则类级别的注解不会自动作用于参数。这个细节很容易被忽略,结果就是参数校验完全不生效,而且不报错。5.2 分组校验与默认组的恩怨回到分组校验。如果CreateGroup分组下只有id字段标了Null,而username字段的NotBlank没有指定groups,那么默认属于Default组。此时用Validated(CreateGroup.class)调用,username的NotBlank不会生效,因为Spring只校验了CreateGroup组。解法有两个:要么把新组的接口定义为CreateGroup.class和Default.class的组合,要么在DTO里给不能漏校验的注解显式加上所有分组:NotBlank(groups {CreateGroup.class, UpdateGroup.class, Default.class}, message 用户名不能为空)我的偏好是:把所有涉及分组校验的DTO字段,都显式声明groups,不依赖Default组,规则明确,排查问题也省心。另外有个更顺手的办法:让CreateGroup接口继承Default:public interface CreateGroup extends Default {}这样Validated(CreateGroup.class)时,Default组的约束也会一起生效。这个方法知道的人不多,但实测很好用。5.3 List校验不生效,回溯半天发现忘了Valid嵌套校验失效的问题前面提了一嘴,这里再强调一遍。项目里出现过这种情况:订单提交接口,items传了50条,其中一条的skuCode是空的,结果校验通过了。排查下来发现OrderCreateRequest里List字段没写Valid,只写了NotBlank和Size,框架根本没有往下递归。判断一个校验是否生效,最快的办法是打断点看异常信息。如果根本不进异常处理器,或者调试时发现ConstraintViolation里只有顶层字段,基本就是Valid缺失。另外注意:Spring Boot 2.3版本之后,spring-boot-starter-web不再自动包含hibernate-validator依赖,需要手动引入:dependency groupIdorg.hibernate.validator/groupId artifactIdhibernate-validator/artifactId /dependency很多网上教程用的旧版本demo,新建项目直接复制依赖时会漏掉这个,导致NotBlank等注解完全无效,这是版本升级带来的经典坑。5.4 message占位符和参数拼接的误区在注解里写message时,经常会用到{min}、{max}这种占位符。默认情况下,校验器会把Size(min2, max20)的注解属性值动态替换进占位符。但如果你在自定义注解里希望把某个属性和一段固定文案拼起来,直接写{min}是不行的,因为自定义注解里没有min属性,校验器解析时找不到对应值,最终message就变成原样输出{min}。解决思路是写一个自定义的MessageInterpolator,或者更简单点,干脆在注解里直接用字符串拼接去生成:\Target({ElementType.FIELD}) Retention(RetentionPolicy.RUNTIME) Constraint(validatedBy LengthRangeValidator.class) public interface LengthRange { int min() default 1; int max() default 10; String message() default 非法长度; }想动态提示长度必须在1-10之间,可以在validator的isValid方法里通过context禁用默认消息并重新添加:context.disableDefaultConstraintViolation(); context.buildConstraintViolationWithTemplate( 长度必须在 min - max 之间).addConstraintViolation();这个做法绕开了占位符解析的坑,需要动态参数时直接手拼模板,人和机器都看得懂。5.5 校验注解的叠加顺序一个字段的多个约束注解,校验顺序不保证和注解书写顺序一致。比如username上同时有NotBlank和Size,如果值为null,NotBlank会先失败并返回消息,但Size也可能一起校验,最终异常里可能包含两条错误。前端拿到的错误列表会有多条,这本身不是bug,但如果你的接口期望第一个错误就拦截,需要自己在异常处理器里做去重或只取第一条。我只在异常处理器里做了错误信息拼接,没有做只取第一位的限制。理由很简单:在一次请求中把所有的参数问题一次性反馈给前端,让用户一次性改完,比挤牙膏一样逐条提示体验更好。如果你希望严格短路,不让框架继续校验后续约束,需要自定义校验器,在第一个约束失败后直接抛出异常,但实际收益很小,我基本不推荐。5.6 性能问题:校验器虽然快,但别滥用Bean Validation的校验是反射实现的,性能上比不过手写if判断,但绝大多数Web接口的性能瓶颈根本不在校验这一环,一次校验的耗时通常是微秒到毫秒级别,几乎可以忽略。真正要留意的是避免在循环里重复触发校验框架、避免每个请求都创建新的Validator实例。Spring容器中默认的Validator是单例,正常使用不需要自己new。我曾经在一个批量导入接口里对List的每一项做校验,数据量到几万条时确实能感到明显耗时。后来改成在导入前把所有记录封装成一个大DTO,利用嵌套校验一次性完成,性能提升非常明显。校验框架适合单次请求校验一次的场景,不适合高频循环调用。5.7 校验消息的安全问题还有一个容易忽略的点:异常处理中把错误消息直接拼进返回体时,如果错误消息里包含了字段值,要小心敏感信息泄露。比如Pattern校验失败时,某些自定义模板会把非法输入值也带出来,万一用户传了手机号、邮箱这类敏感数据,就会被回显在响应里。我建议错误提示只描述规则,不回显用户输入,尤其是在审计环境下,这一点很重要。6. 更进一步的通用方案设计6.1 把校验逻辑从Controller中彻底剥离到了这一步,基础校验体系已经能覆盖绝大多数接口。但要谈通用,还可以再往上抽象一层:所有接口的校验入口统一走AOP切面。做法是定义一个自定义注解AutoValidate,切面里解析方法参数上的Validated注解,手动触发Validator校验:Aspect Component public class ValidateAspect { private final Validator validator; public ValidateAspect(Validator validator) { this.validator validator; } Around(annotation(com.example.annotation.AutoValidate)) public Object doValidate(ProceedingJoinPoint pjp) throws Throwable { Object[] args pjp.getArgs(); for (Object arg : args) { if (arg null) { continue; } SetConstraintViolationObject violations validator.validate(arg); if (!violations.isEmpty()) { String msg violations.stream() .map(ConstraintViolation::getMessage) .collect(Collectors.joining(; )); throw new BizException(400, msg); } } return pjp.proceed(); } }这样做的价值在于,校验不再依赖Controller方法上写Validated注解,所有带有AutoValidate的方法入参都会自动被校验。对老项目改造特别友好:在原来那些没有统一校验的Controller方法上加一个注解,校验体系就接入了。6.2 校验器如何复用和扩展自定义校验器默认是单例注册的,Spring容器会管理它们的生命周期。如果一个校验器需要注入业务组件,比如校验用户名是否重复,需要查数据库,可以直接在ConstraintValidator实现类里构造方法注入某个Service或Mapper。这是Bean Validation规范允许的:ValidatorFactory创建validator实例时会使用Spring的依赖注入能力。public class UniqueUsernameValidator implements ConstraintValidatorUniqueUsername, String { private final UserMapper userMapper; public UniqueUsernameValidator(UserMapper userMapper) { this.userMapper userMapper; } Override public boolean isValid(String value, ConstraintValidatorContext context) { if (value null) { return true; } return userMapper.countByUsername(value) 0; } }这种注解判断唯一性的风格我很喜欢,业务语义都在字段上,Service里不需要再写重复代码。不过要注意:远程调用或数据库查询的校验器,性能开销明显高于纯内存正则校验,不要把它用在批量、低频校验之外的地方。6.3 校验规则的外部化配置再往前一步,做配置中心动态规则。把校验规则比如某个字段的正则表达式、长度范围放到配置中心,运行时动态变更。但坦白说,这是个重设计,一般业务系统用不上。Bean Validation的注解是编译期确定的,想动态增删规则,只有手动用Validator的buildConstraintViolationWithTemplate去构建,或者维护一套自己的规则引擎。除非你的系统有大量规则频繁变化且非技术人员在维护,否则我不建议上这套复杂度。中小项目做到注解分组自定义注解统一异常处理,已经非常够用了。这套体系背后的通用思想是:规则声明化、执行框架化、异常集中化。你不需要每一次写接口都重新设计校验逻辑,只需要在DTO上把约束写清楚,剩下的框架替你搞定。最后说一个经验:校验永远只是参数进入业务逻辑前的第一道门,它不是安全边界。注解校验能挡住格式错误,但挡不住业务逻辑错误。比如用户输入的金额不能大于账户余额这种校验,千万不要试图用Bean Validation做,也不该用Bean Validation做——那是业务规则,应该放在Service层里。把技术校验和业务校验的边界划分清楚,你的代码才会越写越顺。
直接上干货。做后端接口开发的人,大概都经历过那种满屏if判断时期——参数一个个取出来,手动判空、判长度、判格式,校验逻辑散落到每个Controller里。Spring Boot这套接口参数校验体系,核心就是Bean Validation规范加上Hibernate Validator实现,配合全局异常处理,把校验从业务代码里彻底抽离出去。这篇文章我会从最基础的注解使用讲起,再深入到分组校验、自定义注解、嵌套校验,最后把实操里容易踩的坑挨个列一遍,内容偏通用工程实践,适合刚接触Spring Boot校验的初学者,也适合项目里校验逻辑混乱、想重构的老手。1. 先说清楚通用到底解决什么问题1.1 手工校验的代码是怎么失控的我见过不少项目,接口参数校验全靠Controller里的if-else硬扛。比如创建用户接口里要校验用户名非空、手机号格式、年龄范围、邮箱合法性,代码长这样:PostMapping(/users) public ResultVoid createUser(RequestBody UserCreateRequest request) { if (request.getUsername() null || request.getUsername().isEmpty()) { return Result.error(用户名不能为空); } if (request.getUsername().length() 2 || request.getUsername().length() 20) { return Result.error(用户名长度必须在2-20之间); } if (request.getMobile() null || !request.getMobile().matches(^1[3-9]\\d{9}$)) { return Result.error(手机号格式不正确); } if (request.getAge() null || request.getAge() 18) { return Result.error(年龄必须大于等于18); } // 继续校验其他字段... // 然后才进入真正的业务逻辑 }单个接口这么写还能接受,但接口数量一多,问题就暴露了:校验逻辑重复劳动,每个人写的风格还不一样;新增字段时忘了补校验是常态;更重要的是,业务方法和校验逻辑搅在一起,代码的可读性直线下降。参数从十几个涨到三十几个的时候,Controller方法里上半屏全是校验,真正干活的代码只有几行,这种项目维护起来非常痛苦。1.2 注解校验带来的思维转变Spring Boot方案里的通用,核心转变是把校验规则声明在数据模型上,而不是写在业务流程里。你只需要在DTO字段上打注解,框架通过校验器统一执行规则,异常统一被全局处理器拦截。这样做的直接好处有三个:第一,校验规则跟着DTO走,同一个对象在多处使用时规则天然一致;第二,Controller代码去掉校验逻辑后非常干净;第三,自定义校验器做一次,全项目复用。而且这套标准背后是有JSR规范支撑的。Java生态里Bean Validation规范从JSR-303演进到JSR-380(也就是Bean Validation 2.0),Spring Boot 2.x以后默认集成了Hibernate Validator 6.x,基本把规范里的注解全部实现了。Spring Boot 3.x则使用Hibernate Validator 8.x配合Jakarta EE命名空间,注解包名从javax.validation换到了jakarta.validation。理解这个背景很重要,你搜资料的时候会看到很多老文章用javax开头的包名,在Spring Boot 3.x项目里直接复制是编译不过的。2. 基础实战:一套标准校验长什么样2.1 核心注解速查表先过一遍最常用的注解,这些都是Bean Validation规范里定义的,不需要额外引包:注解作用使用场景NotNull值不能为null包装类型字段,比如Integer、LongNotBlank值不能为null且去空格后长度必须大于0String类型必填字段NotEmpty值不能为null且size大于0String、集合、数组、MapSize值长度或size必须在指定范围内字符串长度、集合大小Min / Max数值必须大于等于/小于等于指定值数字类型Positive / PositiveOrZero正数 / 非负数数字类型Pattern必须匹配正则表达式手机号、身份证等格式校验Email必须是合法邮箱格式邮箱字段这里特别强调一下NotNull和NotBlank的区别,这是新手最容易踩的坑。前端传一个空字符串过来,如果字段标注的是NotNull,校验是能通过的,因为空串不是null。如果你的业务要求用户名不能为空,那么请用NotBlank,它同时拒绝了null、空串和纯空格的情况。同理,NotEmpty用于集合字段,比如List参数传了空数组就不能通过。2.2 一个完整的DTO校验示例实际操作中,我会把请求参数封装成独立的DTO。以创建用户接口为例:Data public class UserCreateRequest { NotBlank(message 用户名不能为空) Size(min 2, max 20, message 用户名长度必须在2-20之间) private String username; NotBlank(message 手机号不能为空) Pattern(regexp ^1[3-9]\\d{9}$, message 手机号格式不正确) private String mobile; NotNull(message 年龄不能为空) Min(value 18, message 年龄不能小于18岁) private Integer age; Email(message 邮箱格式不正确) private String email; NotBlank(message 部门不能为空) private String department; }Controller里配合Validated注解触发校验:RestController RequestMapping(/api/users) public class UserController { PostMapping public ResultVoid createUser(Validated RequestBody UserCreateRequest request) { // 这里直接写业务逻辑,参数已经是校验过的了 userService.createUser(request); return Result.success(); } }注意Validated加在方法参数上,Spring会启动MethodValidationPostProcessor,对入参执行校验。RequestBody注解解析完JSON后,校验器马上开始干活,校验不通过会抛出MethodArgumentNotValidException异常。2.3 校验失败后的异常到底去哪了没有异常处理时,Spring Boot默认会把错误信息返回给前端,状态码400,响应体结构是Spring默认的格式,不够友好,也不统一。因此通用参数校验里最关键的一环就是把异常拦截住,包装成项目统一的响应结构。我一般会建一个全局异常处理器,专门处理参数校验相关的三类异常:MethodArgumentNotValidException:处理RequestBody参数校验失败ConstraintViolationException:处理RequestParam、PathVariable参数校验失败BindException:处理表单绑定参数校验失败统一响应体的基础结构我习惯这样定义:Data public class ResultT { private int code; private String message; private T data; public static T ResultT success(T data) { ResultT r new Result(); r.code 0; r.message success; r.data data; return r; } public static T ResultT error(int code, String message) { ResultT r new Result(); r.code code; r.message message; return r; } }全局异常处理的完整写法放在第三章详细拆,这一步你只需要明白:校验框架只负责判断对错,返回什么提示给前端是异常处理器负责的活。3. 异常处理与错误响应,通用性的核心3.1 全局异常处理器的完整实现参数校验的通用性,很大程度上体现在异常处理策略上。我会把校验异常全部收敛到一个类里处理,业务代码里完全不出现try-catch校验逻辑。RestControllerAdvice public class GlobalExceptionHandler { private static final Logger log LoggerFactory.getLogger(GlobalExceptionHandler.class); ExceptionHandler(MethodArgumentNotValidException.class) public ResultVoid handleMethodArgumentNotValid(MethodArgumentNotValidException ex) { String message ex.getBindingResult().getFieldErrors().stream() .map(error - error.getField() : error.getDefaultMessage()) .collect(Collectors.joining(; )); log.warn(参数校验失败: {}, message); return Result.error(400, message); } ExceptionHandler(ConstraintViolationException.class) public ResultVoid handleConstraintViolation(ConstraintViolationException ex) { String message ex.getConstraintViolations().stream() .map(v - v.getPropertyPath() : v.getMessage()) .collect(Collectors.joining(; )); log.warn(参数校验失败: {}, message); return Result.error(400, message); } ExceptionHandler(BindException.class) public ResultVoid handleBind(BindException ex) { String message ex.getBindingResult().getFieldErrors().stream() .map(error - error.getField() : error.getDefaultMessage()) .collect(Collectors.joining(; )); log.warn(参数绑定校验失败: {}, message); return Result.error(400, message); } }这里有个容易忽略的点:MethodArgumentNotValidException和BindException都提供了getBindingResult()方法,可以拿到字段级错误详情。每个FieldError包含field、defaultMessage等属性,按字段拼出提示语,前端能精确知道哪个参数出了问题。3.2 错误提示的国际化思路真实项目里,直接把用户名长度必须在2-20之间这种中文硬编码在注解message里,初期没问题,一旦要做多语言版本就难受了。推荐的思路是message里写错误码,响应之前做国际化映射:NotBlank(message {error.user.username.notblank}) private String username;然后resources目录下放messages.properties:error.user.username.notblank用户名不能为空 error.user.username.size用户名长度必须在2-20之间Spring Boot默认配置了MessageSource,只要在application配置里指定basename,框架会自动根据Locale解析。不过这套配置有个前提:需要在项目里稍微定制一下错误码解析,否则校验器不知道去哪里找资源。Hibernate Validator本身对{xxx}占位符的处理规则是:先尝试从注解属性里找,找不到再从ValidationMessages.properties里找。如果你想让占位符从Spring的MessageSource解析,通常需要注入MessageSourceInterpolator。我建议中小项目先用硬编码中文,等真有多语言需求再引入国际化,步子太大容易给自己挖坑。3.3 别忽略校验异常和其他异常的顺序全局异常处理器往往不止一个方法,除了校验异常,还有业务异常、未知异常等等。这里要留意异常处理方法的匹配优先级:Spring会优先匹配更深层的异常类型。如果业务异常类继承了RuntimeException,同时处理器里又有ExceptionHandler(BusinessException.class)和ExceptionHandler(Exception.class),那么抛出BusinessException时会优先进入更具体的BusinessException方法,不会误入兜底逻辑。还有一个细节:异常处理里不要把所有异常都吞掉返回200。有人会把Exception全部catch住,return Result.success,导致前端收到code0但数据完全是错误结果,这种做法非常坑。校验失败该返回400就返回400,兜底异常返回500,基础的状态码语义要守住。4. 进阶玩法:分组校验与自定义注解4.1 分组校验解决同一个DTO在不同接口规则不同很多场景下,同一个DTO在新增和更新时校验规则不一样。比如创建用户时id必须为空,更新用户时id必须不为空。如果不做分组,只能写两个DTO,代码冗余。Bean Validation用groups属性解决这个问题。先定义两个分组标记接口:public interface CreateGroup {} public interface UpdateGroup {}DTO里给注解指定分组:Data public class UserSaveRequest { Null(groups CreateGroup.class, message 新增时ID必须为空) NotNull(groups UpdateGroup.class, message 更新时ID不能为空) private Long id; NotBlank(groups {CreateGroup.class, UpdateGroup.class}, message 用户名不能为空) Size(min 2, max 20, message 用户名长度必须在2-20之间) private String username; NotBlank(groups CreateGroup.class, message 创建时必须填写手机号) private String mobile; }注意:没有显式声明groups的注解,默认属于Default分组。当校验器执行CreateGroup分组校验时,默认分组里的注解反而不会生效。这个特性坑人,后面我在踩坑章节会重点讲。Controller的用法:PostMapping public ResultVoid create(Validated(CreateGroup.class) RequestBody UserSaveRequest request) { return Result.success(); } PutMapping(/{id}) public ResultVoid update(Validated(UpdateGroup.class) RequestBody UserSaveRequest request) { return Result.success(); }关键点:Validated注解的value属性传入分组Class,Spring就知道当前接口要启用哪组校验规则。这里有个隐含的坑:Valid注解不支持分组,只能靠Validated。所以凡是涉及分组校验的接口,一定不要写Valid,这会静默地忽略groups属性,导致所有分组规则失效。4.2 自定义校验注解,最灵活的一张牌框架自带的注解覆盖了大部分场景,但总有奇怪的需求。比如我要校验一个字符串只能包含大写字母和下划线,用Pattern也行,但业务上如果这个格式在多个地方被使用,重复写正则就违反通用的初衷了。这时候自定义注解更优雅。完整的自定义注解包含两部分:注解定义和校验器实现。Target({ElementType.FIELD, ElementType.PARAMETER}) Retention(RetentionPolicy.RUNTIME) Constraint(validatedBy UpperCaseWithUnderlineValidator.class) public interface UpperCaseWithUnderline { String message() default 只能包含大写字母和下划线; Class?[] groups() default {}; Class? extends Payload[] payload() default {}; }校验器实现ConstraintValidator接口:public class UpperCaseWithUnderlineValidator implements ConstraintValidatorUpperCaseWithUnderline, String { private static final Pattern PATTERN Pattern.compile(^[A-Z_]$); Override public boolean isValid(String value, ConstraintValidatorContext context) { if (value null) { return true; } return PATTERN.matcher(value).matches(); } }有几个细节值得说。第一,Constraint注解的validatedBy属性用来告诉校验器框架这个注解归哪个类管;第二,isValid里对null值直接放行,空值判断交给NotBlank这类注解去管,单一职责;第三,自定义注解定义里必须包含message、groups、payload三个默认属性,这是Bean Validation规范的要求,缺了会编译不过。使用起来和内置注解一样:NotBlank(message 编码不能为空) UpperCaseWithUnderline(message 编码只能包含大写字母和下划线) private String code;如果校验器里需要用到注解上的参数,比如自定义一个范围校验MyRange(min 1, max 10),可以在validator里实现initialize方法拿注解实例:public class MyRangeValidator implements ConstraintValidatorMyRange, Integer { private int min; private int max; Override public void initialize(MyRange constraintAnnotation) { this.min constraintAnnotation.min(); this.max constraintAnnotation.max(); } Override public boolean isValid(Integer value, ConstraintValidatorContext context) { if (value null) { return true; } return value min value max; } }4.3 嵌套对象和集合的校验DTO里嵌套另一个DTO是很常见的。比如创建订单时,订单项是一个List:Data public class OrderCreateRequest { NotNull(message 订单项不能为空) Size(min 1, message 至少要有一个订单项) Valid private ListValid OrderItemRequest items; NotBlank(message 收货地址不能为空) private String address; } Data public class OrderItemRequest { NotBlank(message 商品编码不能为空) private String skuCode; NotNull(message 商品数量不能为空) Min(value 1, message 商品数量至少为1) private Integer count; }这里有两个Valid:一个加在字段上,一个加在泛型参数上。字段上的Valid告诉框架这个List里的每个元素都要递归校验;泛型参数上的Valid是Java类型注解的用法,在Bean Validation 2.0之后支持。两个配合才能保证List中每个OrderItemRequest里的约束都能触发。实际开发中我只写字段上的Valid,List泛型里的Valid也建议加上,兼容性最好。嵌套对象同理:NotNull(message 用户信息不能为空) Valid private UserInfoRequest userInfo;不加Valid的情况下,嵌套对象内部的注解完全不会执行,这是新手最容易踩的深坑,配置文件里看不到任何报错,但嵌套字段的约束一律失效。5. 尽量别踩的坑:这些问题我基本都遇到过5.1 Valid和Validated的混用错觉Valid是JSR规范里的标准注解,Validated是Spring提供的变体。前者只能用在字段、方法参数上,后者还可以用在类上。如果Controller类上标了Validated,方法参数上的校验注解才能对RequestParam和PathVariable生效;而RequestBody的校验,无论用Valid还是Validated都能触发,但分组校验时必须用Validated。我建议统一用Validated,少些纠结。但要注意,类上标了Validated之后,方法参数上必须再标一次Validated,否则类级别的注解不会自动作用于参数。这个细节很容易被忽略,结果就是参数校验完全不生效,而且不报错。5.2 分组校验与默认组的恩怨回到分组校验。如果CreateGroup分组下只有id字段标了Null,而username字段的NotBlank没有指定groups,那么默认属于Default组。此时用Validated(CreateGroup.class)调用,username的NotBlank不会生效,因为Spring只校验了CreateGroup组。解法有两个:要么把新组的接口定义为CreateGroup.class和Default.class的组合,要么在DTO里给不能漏校验的注解显式加上所有分组:NotBlank(groups {CreateGroup.class, UpdateGroup.class, Default.class}, message 用户名不能为空)我的偏好是:把所有涉及分组校验的DTO字段,都显式声明groups,不依赖Default组,规则明确,排查问题也省心。另外有个更顺手的办法:让CreateGroup接口继承Default:public interface CreateGroup extends Default {}这样Validated(CreateGroup.class)时,Default组的约束也会一起生效。这个方法知道的人不多,但实测很好用。5.3 List校验不生效,回溯半天发现忘了Valid嵌套校验失效的问题前面提了一嘴,这里再强调一遍。项目里出现过这种情况:订单提交接口,items传了50条,其中一条的skuCode是空的,结果校验通过了。排查下来发现OrderCreateRequest里List字段没写Valid,只写了NotBlank和Size,框架根本没有往下递归。判断一个校验是否生效,最快的办法是打断点看异常信息。如果根本不进异常处理器,或者调试时发现ConstraintViolation里只有顶层字段,基本就是Valid缺失。另外注意:Spring Boot 2.3版本之后,spring-boot-starter-web不再自动包含hibernate-validator依赖,需要手动引入:dependency groupIdorg.hibernate.validator/groupId artifactIdhibernate-validator/artifactId /dependency很多网上教程用的旧版本demo,新建项目直接复制依赖时会漏掉这个,导致NotBlank等注解完全无效,这是版本升级带来的经典坑。5.4 message占位符和参数拼接的误区在注解里写message时,经常会用到{min}、{max}这种占位符。默认情况下,校验器会把Size(min2, max20)的注解属性值动态替换进占位符。但如果你在自定义注解里希望把某个属性和一段固定文案拼起来,直接写{min}是不行的,因为自定义注解里没有min属性,校验器解析时找不到对应值,最终message就变成原样输出{min}。解决思路是写一个自定义的MessageInterpolator,或者更简单点,干脆在注解里直接用字符串拼接去生成:\Target({ElementType.FIELD}) Retention(RetentionPolicy.RUNTIME) Constraint(validatedBy LengthRangeValidator.class) public interface LengthRange { int min() default 1; int max() default 10; String message() default 非法长度; }想动态提示长度必须在1-10之间,可以在validator的isValid方法里通过context禁用默认消息并重新添加:context.disableDefaultConstraintViolation(); context.buildConstraintViolationWithTemplate( 长度必须在 min - max 之间).addConstraintViolation();这个做法绕开了占位符解析的坑,需要动态参数时直接手拼模板,人和机器都看得懂。5.5 校验注解的叠加顺序一个字段的多个约束注解,校验顺序不保证和注解书写顺序一致。比如username上同时有NotBlank和Size,如果值为null,NotBlank会先失败并返回消息,但Size也可能一起校验,最终异常里可能包含两条错误。前端拿到的错误列表会有多条,这本身不是bug,但如果你的接口期望第一个错误就拦截,需要自己在异常处理器里做去重或只取第一条。我只在异常处理器里做了错误信息拼接,没有做只取第一位的限制。理由很简单:在一次请求中把所有的参数问题一次性反馈给前端,让用户一次性改完,比挤牙膏一样逐条提示体验更好。如果你希望严格短路,不让框架继续校验后续约束,需要自定义校验器,在第一个约束失败后直接抛出异常,但实际收益很小,我基本不推荐。5.6 性能问题:校验器虽然快,但别滥用Bean Validation的校验是反射实现的,性能上比不过手写if判断,但绝大多数Web接口的性能瓶颈根本不在校验这一环,一次校验的耗时通常是微秒到毫秒级别,几乎可以忽略。真正要留意的是避免在循环里重复触发校验框架、避免每个请求都创建新的Validator实例。Spring容器中默认的Validator是单例,正常使用不需要自己new。我曾经在一个批量导入接口里对List的每一项做校验,数据量到几万条时确实能感到明显耗时。后来改成在导入前把所有记录封装成一个大DTO,利用嵌套校验一次性完成,性能提升非常明显。校验框架适合单次请求校验一次的场景,不适合高频循环调用。5.7 校验消息的安全问题还有一个容易忽略的点:异常处理中把错误消息直接拼进返回体时,如果错误消息里包含了字段值,要小心敏感信息泄露。比如Pattern校验失败时,某些自定义模板会把非法输入值也带出来,万一用户传了手机号、邮箱这类敏感数据,就会被回显在响应里。我建议错误提示只描述规则,不回显用户输入,尤其是在审计环境下,这一点很重要。6. 更进一步的通用方案设计6.1 把校验逻辑从Controller中彻底剥离到了这一步,基础校验体系已经能覆盖绝大多数接口。但要谈通用,还可以再往上抽象一层:所有接口的校验入口统一走AOP切面。做法是定义一个自定义注解AutoValidate,切面里解析方法参数上的Validated注解,手动触发Validator校验:Aspect Component public class ValidateAspect { private final Validator validator; public ValidateAspect(Validator validator) { this.validator validator; } Around(annotation(com.example.annotation.AutoValidate)) public Object doValidate(ProceedingJoinPoint pjp) throws Throwable { Object[] args pjp.getArgs(); for (Object arg : args) { if (arg null) { continue; } SetConstraintViolationObject violations validator.validate(arg); if (!violations.isEmpty()) { String msg violations.stream() .map(ConstraintViolation::getMessage) .collect(Collectors.joining(; )); throw new BizException(400, msg); } } return pjp.proceed(); } }这样做的价值在于,校验不再依赖Controller方法上写Validated注解,所有带有AutoValidate的方法入参都会自动被校验。对老项目改造特别友好:在原来那些没有统一校验的Controller方法上加一个注解,校验体系就接入了。6.2 校验器如何复用和扩展自定义校验器默认是单例注册的,Spring容器会管理它们的生命周期。如果一个校验器需要注入业务组件,比如校验用户名是否重复,需要查数据库,可以直接在ConstraintValidator实现类里构造方法注入某个Service或Mapper。这是Bean Validation规范允许的:ValidatorFactory创建validator实例时会使用Spring的依赖注入能力。public class UniqueUsernameValidator implements ConstraintValidatorUniqueUsername, String { private final UserMapper userMapper; public UniqueUsernameValidator(UserMapper userMapper) { this.userMapper userMapper; } Override public boolean isValid(String value, ConstraintValidatorContext context) { if (value null) { return true; } return userMapper.countByUsername(value) 0; } }这种注解判断唯一性的风格我很喜欢,业务语义都在字段上,Service里不需要再写重复代码。不过要注意:远程调用或数据库查询的校验器,性能开销明显高于纯内存正则校验,不要把它用在批量、低频校验之外的地方。6.3 校验规则的外部化配置再往前一步,做配置中心动态规则。把校验规则比如某个字段的正则表达式、长度范围放到配置中心,运行时动态变更。但坦白说,这是个重设计,一般业务系统用不上。Bean Validation的注解是编译期确定的,想动态增删规则,只有手动用Validator的buildConstraintViolationWithTemplate去构建,或者维护一套自己的规则引擎。除非你的系统有大量规则频繁变化且非技术人员在维护,否则我不建议上这套复杂度。中小项目做到注解分组自定义注解统一异常处理,已经非常够用了。这套体系背后的通用思想是:规则声明化、执行框架化、异常集中化。你不需要每一次写接口都重新设计校验逻辑,只需要在DTO上把约束写清楚,剩下的框架替你搞定。最后说一个经验:校验永远只是参数进入业务逻辑前的第一道门,它不是安全边界。注解校验能挡住格式错误,但挡不住业务逻辑错误。比如用户输入的金额不能大于账户余额这种校验,千万不要试图用Bean Validation做,也不该用Bean Validation做——那是业务规则,应该放在Service层里。把技术校验和业务校验的边界划分清楚,你的代码才会越写越顺。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
