1. 为什么我们需要分组校验大家好我是老张在Java后端开发这块摸爬滚打十多年了。今天想和大家聊聊SpringBoot3.0里一个非常实用但很多朋友可能还没用起来的功能——分组校验。这玩意儿说白了就是帮你解决“一个实体类多种校验规则”的烦恼。咱们先从一个最常见的场景说起。假设你正在开发一个用户管理模块里面肯定有创建用户、更新用户信息、部分更新比如只改头像这些接口。按照最朴素的思路你是不是会为每个接口都定义一个对应的请求体DTO比如UserCreateDTO、UserUpdateDTO、UserPatchDTO。看起来挺清晰对吧但实际用起来问题就来了。首先这三个DTO里的字段大概率有90%是重叠的比如username、email、phone。你不得不在三个地方重复定义它们以及它们的基础校验注解像NotBlank、Email、Pattern。这就造成了代码冗余。今天产品经理说手机号格式要调整你得同时改三个文件一不小心就漏了一个埋下bug的种子。其次更头疼的是校验规则的冲突。创建用户时id字段肯定是不能传的数据库自增但更新用户时id又是必传的用来定位用户。如果你只有一个UserDTO你怎么写这个NotNull注解给id加上NotNull创建接口就废了不加更新接口又不行。以前我见过不少项目为了绕过这个问题在Controller里写一堆if-else来做手动校验或者干脆把校验逻辑塞进Service层把代码搞得又臭又长维护起来简直是一场噩梦。分组校验就是SpringBoot或者说它底层的Bean Validation规范给我们的一把瑞士军刀。它允许你在同一个实体类上给不同的校验规则打上不同的“标签”。然后在不同的接口里你说“嘿Spring我这次只关心贴着‘创建’标签的那些规则其他的你别管”。这样一来一个实体类就能通吃所有场景既保持了代码的简洁又实现了校验规则的精准控制。我刚开始用的时候也觉得有点绕但一旦用顺手了你就会发现它带来的代码复用性和可维护性的提升是巨大的。下面我就带你一步步把它用起来。2. 从零开始定义你的第一个校验分组理论说再多不如动手试一次。我们就把上面提到的用户管理场景实现出来。首先你需要一个SpringBoot3.0的项目确保你的pom.xml或build.gradle里已经引入了spring-boot-starter-validation依赖。这个依赖是分组校验功能的基础。分组校验的核心是“分组”本身。在Java里我们用“标记接口”来定义分组。啥叫标记接口就是一个空接口里面没有任何方法它的作用纯粹就是作为一个分类的标签。我们来定义三个最常用的分组// 创建用户时使用的校验分组 public interface CreateGroup {} // 更新用户信息时使用的校验分组 public interface UpdateGroup {} // 部分更新用户信息时使用的校验分组 public interface PatchGroup {}没错就是这么简单。这三个接口现在就是三个不同的“标签”。你可以根据业务需要定义更多比如LoginGroup、ChangePasswordGroup等等。定义好了分组下一步就是去我们的实体类上给各个字段的校验规则贴上对应的标签。我们创建一个User类这次它要服务所有接口import jakarta.validation.constraints.*; public class User { // 注意看这里的 groups 参数 NotNull(message 更新用户时ID不能为空, groups UpdateGroup.class) Null(message 创建用户时不应提交ID, groups CreateGroup.class) private Long id; NotBlank(message 用户名不能为空, groups {CreateGroup.class, UpdateGroup.class}) Size(min 2, max 20, message 用户名长度必须在2-20之间, groups {CreateGroup.class, UpdateGroup.class}) private String username; // 创建和更新时需要密码部分更新时不需要 NotBlank(message 密码不能为空, groups {CreateGroup.class}) Pattern(regexp ^(?.*[A-Za-z])(?.*\\d).{8,}$, message 密码必须至少8位且包含字母和数字, groups {CreateGroup.class}) private String password; NotBlank(message 邮箱不能为空, groups {CreateGroup.class, UpdateGroup.class}) Email(message 邮箱格式不正确, groups {CreateGroup.class, UpdateGroup.class}) private String email; // 手机号在创建和更新时做基础校验部分更新时可能只更新其他字段 Pattern(regexp ^1[3-9]\\d{9}$, message 手机号格式不正确, groups {CreateGroup.class, UpdateGroup.class}) private String phone; // 部分更新接口可能只更新这个字段所以给它单独一个分组 NotBlank(message 头像URL不能为空, groups PatchGroup.class) private String avatarUrl; // 省略 getter/setter 和构造方法 }我来解释一下这个配置的妙处id字段这是分组校验解决冲突的经典案例。我们同时使用了NotNull和Null两个看似矛盾的注解但通过groups属性将它们区分开。UpdateGroup分组生效时要求id非空CreateGroup分组生效时要求id为空。完美解决了冲突。password字段在CreateGroup中我们要求密码非空且符合复杂度规则。但在UpdateGroup中我故意没有添加任何校验。为什么因为在实际的“更新用户信息”接口里我们可能允许用户不修改密码即密码字段为null或空字符串表示不更新。如果我们给UpdateGroup也加上NotBlank那用户想只改个昵称就得连原密码再传一遍体验很差。这就是场景化校验的体现。avatarUrl字段它只属于PatchGroup。这意味着只有在部分更新的场景下这个字段的NotBlank规则才会被触发。在创建和全量更新时这个字段可以为空。groups可以接受数组像username字段它在创建和更新时都需要被校验所以它的注解里groups {CreateGroup.class, UpdateGroup.class}。这样配置完一个实体类就承载了所有场景的校验规则而且规则之间互不干扰非常清晰。3. 在Controller中激活分组校验实体类准备好了接下来就是告诉Spring在哪个接口使用哪个分组。这里的关键是使用Validated注解而不是我们更熟悉的Valid。注意Valid是Java标准注解JSR-303它不支持分组功能。Validated是Spring提供的增强版注解它支持分组并且还能用在类、方法、参数上功能更强大。在分组校验场景下我们必须用Validated。看下面的Controller示例import org.springframework.validation.annotation.Validated; import org.springframework.web.bind.annotation.*; RestController RequestMapping(/api/users) public class UserController { PostMapping public ResponseEntityString createUser(Validated(CreateGroup.class) RequestBody User user) { // 业务逻辑创建用户此时user.id应为null // 系统只会校验属于 CreateGroup 分组的规则 // 即id必须为null, username非空password非空且复杂email非空且格式正确phone格式正确 return ResponseEntity.ok(用户创建成功); } PutMapping(/{id}) public ResponseEntityString updateUser(PathVariable Long id, Validated(UpdateGroup.class) RequestBody User user) { // 业务逻辑更新用户 // 此时user对象里的id会被路径变量赋值或者从body中读取如果传了的话 // 系统只会校验属于 UpdateGroup 分组的规则 // 即id不能为null, username非空email非空且格式正确phone格式正确 // password字段没有校验所以可以不传 user.setId(id); // 通常用路径参数覆盖body中的id确保一致性 return ResponseEntity.ok(用户更新成功); } PatchMapping(/{id}/avatar) public ResponseEntityString updateAvatar(PathVariable Long id, Validated(PatchGroup.class) RequestBody User user) { // 业务逻辑只更新用户头像 // 系统只会校验属于 PatchGroup 分组的规则 // 即avatarUrl 不能为空 // 其他字段如username, email即使传了也不会触发校验 return ResponseEntity.ok(用户头像更新成功); } }重点解读一下Validated的用法Validated(CreateGroup.class)括号里直接放分组的Class。这意味着Spring在调用这个createUser方法前会对user参数进行校验但只执行那些groups属性包含了CreateGroup.class的校验注解。同理Validated(UpdateGroup.class)只触发UpdateGroup的规则。你可以传入多个分组比如Validated({CreateGroup.class, Default.class})这表示同时应用这两个分组的规则。这个Default.class是个特殊分组我们稍后会讲。这样配置之后你的接口就具备了智能校验的能力。发个请求试试调用POST /api/users如果body里带了id会立刻收到“创建用户时不应提交ID”的校验错误。调用PUT /api/users/123却不传id字段或传null会收到“更新用户时ID不能为空”的错误。调用PATCH /api/users/123/avatar只传{“avatarUrl”: “”}会收到“头像URL不能为空”的错误。是不是感觉代码一下子干净利落了很多所有校验规则都声明在实体类这一处Controller只负责指明使用场景职责分离得非常清楚。4. 玩转进阶技巧继承、组合与默认分组掌握了基础用法我们来看看几个能让你代码更优雅的进阶技巧。技巧一使用继承组织分组如果你的分组很多并且有些规则是共通的可以用接口继承来管理。比如几乎所有操作都需要校验username和email的格式只有创建时需要额外校验password。// 定义一个基础分组包含最通用的校验规则 public interface BaseUserGroup {} // 创建分组继承基础分组 public interface CreateGroup extends BaseUserGroup {} // 更新分组也继承基础分组 public interface UpdateGroup extends BaseUserGroup {}然后在实体类中public class User { NotBlank(groups BaseUserGroup.class) Email(groups BaseUserGroup.class) private String email; NotBlank(groups CreateGroup.class) // 只有创建时需要 private String password; }在Controller里使用CreateGroup时由于它继承了BaseUserGroup所以email的校验也会生效。这避免了在多个分组的groups数组里重复添加BaseUserGroup.class。技巧二组合使用多个分组Validated注解可以同时指定多个分组规则是取并集。比如你有一个“管理员创建用户”的场景它既要满足普通创建的规则又要满足一些管理员特有的规则比如必须指定部门。public interface AdminCreateGroup {} // Controller中 PostMapping(/admin/users) public ResponseEntity createUserByAdmin(Validated({CreateGroup.class, AdminCreateGroup.class}) RequestBody User user) { // 同时校验 CreateGroup 和 AdminCreateGroup 的规则 }技巧三理解并善用 Default 分组这是一个非常重要的内置分组。如果你在声明校验注解时没有指定groups属性那么该注解就默认属于Default.class分组。public class User { NotBlank // 没有指定groups属于Default分组 private String nickname; NotBlank(groups CreateGroup.class) private String password; }Default分组什么时候生效呢当你使用Valid注解时注意不是Validated只会校验Default分组。当你使用Validated但不传任何参数时即Validated也只会校验Default分组。当你使用Validated(SomeGroup.class)时Default分组的规则不会被校验除非SomeGroup继承了Default。所以一种常见的实践是将那些在任何场景下都必须遵守的、最基础的校验规则放在Default分组里。例如一个User对象的username字段无论创建、更新、登录格式都必须合法。public class User { NotBlank Size(min3, max50) private String username; // 属于Default分组任何使用 Valid 或 无参 Validated 的地方都会校验 NotBlank(groups CreateGroup.class) private String password; // 只属于CreateGroup分组 }如果你想在启用某个自定义分组的同时也启用Default分组可以这样写PostMapping public ResponseEntity create(Validated({Default.class, CreateGroup.class}) RequestBody User user) { // 这会同时校验 Default 分组和 CreateGroup 分组的规则 }5. 处理校验失败打造友好的错误响应校验失败后Spring会抛出MethodArgumentNotValidException异常。如果不对这个异常做处理客户端会收到一个包含一堆堆栈信息的500错误这非常不友好。我们必须进行全局异常处理返回结构化的错误信息。在SpringBoot里我们可以使用RestControllerAdvice轻松实现import org.springframework.web.bind.MethodArgumentNotValidException; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.RestControllerAdvice; import java.util.List; import java.util.stream.Collectors; RestControllerAdvice public class GlobalExceptionHandler { ExceptionHandler(MethodArgumentNotValidException.class) public ResponseEntityApiResponse? handleValidationException(MethodArgumentNotValidException ex) { // 从异常中提取详细的字段错误信息 ListFieldError fieldErrors ex.getBindingResult().getFieldErrors(); ListString errors fieldErrors.stream() .map(error - String.format(字段[%s]: %s, error.getField(), error.getDefaultMessage())) .collect(Collectors.toList()); // 构造一个统一的API响应格式 ApiResponse? response ApiResponse.error( HttpStatus.BAD_REQUEST.value(), 参数校验失败, errors // 把具体的错误列表放到data里 ); return new ResponseEntity(response, HttpStatus.BAD_REQUEST); } // 可以再定义一些其他异常的处理... } // 一个简单的统一响应体 Data class ApiResponseT { private int code; private String message; private T data; public static T ApiResponseT success(T data) { ApiResponseT response new ApiResponse(); response.setCode(200); response.setMessage(成功); response.setData(data); return response; } public static ApiResponse? error(int code, String message, Object data) { ApiResponseObject response new ApiResponse(); response.setCode(code); response.setMessage(message); response.setData(data); return response; } }这样处理之后当校验失败时客户端收到的响应就会是这样的{ code: 400, message: 参数校验失败, data: [ 字段[id]: 创建用户时不应提交ID, 字段[password]: 密码必须至少8位且包含字母和数字 ] }前端同学拿到这个响应可以非常直观地知道哪个字段出了什么问题用户体验瞬间提升好几个档次。这也是我们做后端接口校验的最终目的在第一时间、以最清晰的方式告诉调用方错在哪里。6. 避坑指南与实践建议分组校验虽然强大但在实际项目中用起来还是有一些坑需要注意。这里分享几个我踩过的以及一些最佳实践。第一个坑分组接口的序列化问题。我们定义的CreateGroup.class、UpdateGroup.class这些标记接口只是给校验框架用的。千万不要把它们放到你的API请求体或响应体里也不要在任何需要序列化/反序列化的地方引用它们。它们只是“标签”不是数据模型的一部分。第二个坑过度设计。不是所有场景都需要分组校验。如果一个实体类只被一个接口使用或者不同接口间的校验规则差异极小比如就一两个字段不同那你直接定义两个DTO可能更简单明了。分组校验的优势在于复用度高、规则差异明显的场景。如果为了用而用生硬地拆出很多分组反而会增加代码的理解成本。第三个坑忘记处理“其他字段”。在部分更新PATCH场景下我们只校验了avatarUrl分组。但如果客户端不小心或恶意地传了一个巨大的、不合法的username过来由于这个字段不属于PatchGroup校验不会触发这个数据就会直接进入你的业务逻辑。所以对于PATCH操作更安全的做法是使用一个专门的UserPatchDTO只包含允许更新的字段。或者在接收时仍然用User但在业务层手动检查传入的字段只处理允许更新的那几个忽略其他字段。这通常可以和JsonIgnoreProperties(ignoreUnknown true)配合使用避免反序列化未知字段报错。我的实践建议命名清晰分组接口的名字要能直接反映其业务场景比如UserCreate、UserUpdateBasic、UserChangePassword这比简单的GroupA、GroupB要好理解得多。与文档结合在Swagger或OpenAPI文档中目前没有直接标注分组信息的功能。你需要在接口描述中手动说明本接口适用哪个校验分组或者为不同分组生成不同的API模型这又回到了原点。一个折中的办法是在实体类的字段注释里写明分组信息。保持实体类纯净校验注解只关乎数据格式的“有效性”不要在里面混入业务逻辑校验。比如“用户名是否已存在”这种需要查数据库的校验应该放在Service层或者使用自定义校验注解配合数据库查询来实现。测试要充分为每个接口的分组校验编写单元测试和集成测试。特别是要测试“边界情况”比如在创建接口传了ID会不会被正确拦截在更新接口不传密码会不会通过。分组校验的规则稍微复杂点没测试覆盖很容易出问题。从我自己的经验来看在中等及以上复杂度的后台管理系统、或者存在大量CRUD但规则各异的API服务中引入分组校验是利大于弊的。它初期需要一点学习成本但一旦团队熟悉了这种模式后期在添加新接口、修改校验规则时会感到无比顺畅。你再也不用在多个几乎一样的DTO之间同步字段也不用在Controller里写那些冗长的校验逻辑了。代码变得声明式、集中化维护起来心里有底。