参数校验与全局异常处理：统一错误码体系设计

参数校验与全局异常处理统一错误码体系设计用户体验最差的接口是什么传错参数返回一个java.lang.NullPointerException堆栈。用户一脸懵前端一脸懵运维一脸懵。这篇把参数校验和异常处理搭成体系让错误信息清清楚楚。一、参数校验的重要性垃圾输入导致垃圾输出Garbage In, Garbage Out。不校验参数用户的手机号传个abc你也存进去年龄传个-999你也信。等数据脏了再清理成本翻十倍。参数校验的原则在数据进入业务逻辑之前把住关卡。二、JSR303校验注解JSR303Bean Validation是一套Java标准校验规范Hibernate Validator是其实现。SpringBoot自带引入spring-boot-starter-validation即可。2.1 常用校验注解注解作用适用类型NotNull不能为null任意类型NotEmpty不能为null且不能为空串字符串、集合NotBlank不能为null且必须含非空白字符字符串Size(min,max)长度范围字符串、集合Min/Max最小值/最大值数字Range(min,max)数值范围数字Pattern(regexp)正则匹配字符串Email邮箱格式字符串Past/Future必须是过去/未来日期日期2.2 DTO校验示例DatapublicclassUserDTO{NotBlank(message用户名不能为空)Size(min3,max20,message用户名长度3-20个字符)privateStringusername;NotBlank(message密码不能为空)Pattern(regexp^(?.*[a-z])(?.*[A-Z])(?.*\\d).{8,}$,message密码至少8位需包含大小写字母和数字)privateStringpassword;NotBlank(message邮箱不能为空)Email(message邮箱格式不正确)privateStringemail;NotNull(message年龄不能为空)Min(value0,message年龄不能小于0)Max(value150,message年龄不能大于150)privateIntegerage;Pattern(regexp^1[3-9]\\d{9}$,message手机号格式不正确)privateStringphone;}Controller中使用RestControllerRequestMapping(/api/user)publicclassUserController{PostMappingpublicResultVoidaddUser(RequestBodyValidatedUserDTOdto){userService.add(dto);returnResult.success(null);}}三、Validated vs Valid这两个注解都能触发校验但有关键区别对比项ValidValidated来源JSR303标准Spring扩展分组校验不支持支持嵌套校验支持加在属性上支持用在方法参数上支持支持用在类级别不支持支持方法级校验3.1 分组校验新增时不传id修改时必须传id。同一个DTO不同场景校验规则不同——这就需要分组校验。定义分组接口publicinterfaceAddGroup{}publicinterfaceUpdateGroup{}DTO标注分组DatapublicclassUserDTO{NotNull(message修改时id不能为空,groupsUpdateGroup.class)privateLongid;// 新增时不校验修改时校验NotBlank(message用户名不能为空,groups{AddGroup.class,UpdateGroup.class})privateStringusername;NotBlank(message密码不能为空,groupsAddGroup.class)privateStringpassword;// 新增时必填修改时选填}Controller指定分组PostMappingpublicResultVoidadd(RequestBodyValidated(AddGroup.class)UserDTOdto){userService.add(dto);returnResult.success(null);}PutMappingpublicResultVoidupdate(RequestBodyValidated(UpdateGroup.class)UserDTOdto){userService.update(dto);returnResult.success(null);}3.2 嵌套校验对象内部还有对象时用Valid触发嵌套校验DatapublicclassOrderDTO{NotBlank(message订单号不能为空)privateStringorderNo;NotNull(message收货地址不能为空)Valid// 触发内部对象的校验privateAddressDTOaddress;}DatapublicclassAddressDTO{NotBlank(message省不能为空)privateStringprovince;NotBlank(message市不能为空)privateStringcity;}四、统一错误码体系设计4.1 错误码设计原则好的错误码体系需要可读、可扩展、能定位问题。推荐用5位数字编码前两位标识模块编码段模块示例00000成功0000010xxx通用错误10001 参数校验失败20xxx用户模块20001 用户不存在30xxx订单模块30001 订单已取消40xxx商品模块40001 库存不足50xxx系统错误50001 数据库异常4.2 错误码枚举实现GetterAllArgsConstructorpublicenumErrorCode{SUCCESS(00000,操作成功,HttpStatus.OK),// 通用错误 10xxxPARAM_ERROR(10001,参数校验失败,HttpStatus.BAD_REQUEST),UNAUTHORIZED(10002,未登录或登录已过期,HttpStatus.UNAUTHORIZED),FORBIDDEN(10003,无权限访问,HttpStatus.FORBIDDEN),NOT_FOUND(10004,资源不存在,HttpStatus.NOT_FOUND),// 用户模块 20xxxUSER_NOT_FOUND(20001,用户不存在,HttpStatus.BAD_REQUEST),USER_PASSWORD_ERROR(20002,密码错误,HttpStatus.BAD_REQUEST),USER_EXISTS(20003,用户名已存在,HttpStatus.BAD_REQUEST),// 系统错误 50xxxSYSTEM_ERROR(50001,系统开小差了请稍后重试,HttpStatus.INTERNAL_SERVER_ERROR);privatefinalintcode;privatefinalStringmessage;privatefinalHttpStatushttpStatus;}五、自定义业务异常GetterpublicclassBusinessExceptionextendsRuntimeException{privatefinalErrorCodeerrorCode;publicBusinessException(ErrorCodeerrorCode){super(errorCode.getMessage());this.errorCodeerrorCode;}publicBusinessException(ErrorCodeerrorCode,Stringmessage){super(message);this.errorCodeerrorCode;}}业务代码中直接抛publicUserlogin(LoginDTOdto){UseruseruserMapper.findByUsername(dto.getUsername());if(usernull){thrownewBusinessException(ErrorCode.USER_NOT_FOUND);}if(!passwordEncoder.matches(dto.getPassword(),user.getPassword())){thrownewBusinessException(ErrorCode.USER_PASSWORD_ERROR);}returnuser;}六、全局异常处理6.1 RestControllerAdvice ExceptionHandler用AOP思想统一拦截异常Controller里不写try-catchSlf4jRestControllerAdvicepublicclassGlobalExceptionHandler{/** 业务异常 */ExceptionHandler(BusinessException.class)publicResultVoidhandleBusinessException(BusinessExceptione){log.warn(业务异常: {},e.getMessage());returnResult.error(e.getErrorCode().getCode(),e.getMessage());}/** 参数校验异常 - RequestBody Validated */ExceptionHandler(MethodArgumentNotValidException.class)publicResultVoidhandleValidException(MethodArgumentNotValidExceptione){Stringmessagee.getBindingResult().getFieldErrors().stream().map(error-error.getField(): error.getDefaultMessage()).collect(Collectors.joining(; ));log.warn(参数校验失败: {},message);returnResult.error(ErrorCode.PARAM_ERROR.getCode(),message);}/** 参数校验异常 - RequestParam/PathVariable */ExceptionHandler(ConstraintViolationException.class)publicResultVoidhandleConstraintViolationException(ConstraintViolationExceptione){Stringmessagee.getConstraintViolations().stream().map(violation-violation.getMessage()).collect(Collectors.joining(; ));log.warn(参数校验失败: {},message);returnResult.error(ErrorCode.PARAM_ERROR.getCode(),message);}/** 其他未捕获异常 */ExceptionHandler(Exception.class)publicResultVoidhandleException(Exceptione){log.error(系统异常,e);returnResult.error(ErrorCode.SYSTEM_ERROR.getCode(),ErrorCode.SYSTEM_ERROR.getMessage());}}6.2 异常处理优先级ExceptionHandler匹配规则精确匹配优先异常继承关系就近原则。比如BusinessException extends RuntimeException如果同时注册了两个ExceptionHandlerExceptionHandler(BusinessException.class)// 精确匹配优先ExceptionHandler(RuntimeException.class)// 兜底抛出BusinessException时走第一个抛出其他RuntimeException走第二个。6.3 常见校验异常类型异常类型触发场景MethodArgumentNotValidExceptionRequestBody Validated 校验失败ConstraintViolationExceptionRequestParam/PathVariable Validated 校验失败BindException表单参数校验失败HttpMessageNotReadableException请求体JSON格式错误要注意类级别Validated 方法参数RequestParam上加NotBlank触发的是ConstraintViolationException不是MethodArgumentNotValidException。这是最常踩的坑之一。RestControllerValidated// 类级别开启方法参数校验publicclassCommonController{GetMapping(/check)publicResultStringcheck(RequestParamNotBlank(messagename不能为空)Stringname){returnResult.success(ok);}}6.4 完整调用链路前端请求 → 参数校验(Validated触发) → 校验失败 → MethodArgumentNotValidException → GlobalExceptionHandler捕获 → 返回错误信息 → 校验通过 → Controller → Service业务逻辑 → 业务异常 → throw BusinessException → GlobalExceptionHandler捕获 → 返回错误码 → 系统异常 → throw Exception → GlobalExceptionHandler兜底 → 返回500整个链路中Controller层零try-catch代码干干净净异常处理逻辑全部收敛到GlobalExceptionHandler一处。后期维护加异常类型只需要改这一个类这就是体系化设计的价值。