[068][公共模块]Spring Boot 全局异常处理与参数校验实战（上）：架构设计与响应封装

[068][公共模块]Spring Boot 全局异常处理与参数校验实战上架构设计与响应封装本文章代码: gitee , gitcode , github在微服务和 RESTful API 盛行的今天一套清晰、统一、可维护的异常处理机制是项目质量的重要保障。本文基于一个真实项目的异常处理模块深入剖析如何利用 Spring Boot 的RestControllerAdvice和 JSR-303 校验框架打造一套兼顾 Servlet 容器和 WebFlux 响应式环境的全局异常处理方案。一、整体架构设计异常处理模块由以下核心组件构成ResultT统一的 API 响应体包含状态码、消息、时间戳、路径、traceId 以及可选的错误详情Error内部类。BaseRuntimeException自定义业务运行时异常聚合了ErrorCode错误码枚举、参数、详情等信息。GlobalExceptionHandler全局异常处理器拦截BaseRuntimeException和通用Exception将异常转化为标准的Result响应。GlobalValidationExceptionHandler专门处理参数校验异常MethodArgumentNotValidException、BindException、ConstraintViolationException将字段校验错误转换为Result.fieldErrors结构。GlobalWebFluxValidationExceptionHandlerWebFlux 环境下的校验异常处理器处理WebExchangeBindException和ServerWebInputException返回MonoResult。这种分层设计将业务异常、系统异常和校验异常区分开既保证了通用性又为特定场景提供了精细化处理。二、统一响应体ResultT的设计亮点Result类采用链式调用的 Builder 风格同时包含一个内部Error类用于承载调试信息publicclassResultT{privatefinalInstanttimestampInstant.now();privateStringmessage;privateStringpath;privateTdata;privateintstatus;privateStringcode;privateStringtraceId;privateErrorerror;// 静态工厂方法publicstaticTResultTsuccess(Tdata){...}publicstaticTResultTfailure(){...}// 链式设置方法publicResultTfieldErrors(MapString,StringfieldErrors){...}publicResultTerrorDetail(Stringdetail){...}// ...}设计要点时间戳自动生成每个响应都带timestamp便于问题追踪。traceId 支持通过 MDC 传递分布式追踪 ID与日志链路打通。错误信息分层message为用户友好的提示Error对象内包含detail技术细节、fieldErrors字段校验错误、stackTrace仅系统异常时返回和params异常参数兼顾了用户体验和开发调试。状态码与 HTTP 状态分离status存储 HTTP 状态码如 400、500code为业务错误码如 “VALIDATION_FAILED”便于前端根据不同错误码做差异化处理。三、自定义异常BaseRuntimeException与错误码枚举BaseRuntimeException继承了RuntimeException内部持有ErrorCode接口和参数 MapGetterpublicclassBaseRuntimeExceptionextendsRuntimeException{privatefinalErrorCodeerrorCode;privatefinalMapString,Objectparams;privatefinalStringdetail;// 构造方法支持链式添加参数publicBaseRuntimeExceptionparam(Stringkey,Objectvalue){...}publicResultVoidgetResult(){...}}ErrorCode接口通常由枚举实现如BaseErrorCode每个枚举项包含一个Feedback对象后者定义了code业务码、httpStatus和message。这种设计使得错误码集中管理且支持国际化扩展。关键方法getResult()将当前异常转换为Result对象若为系统错误且存在 cause则携带堆栈信息生产环境可通过配置关闭。四、全局异常处理器GlobalExceptionHandler该处理器是兜底拦截器处理所有未捕获的异常RestControllerAdvicepublicclassGlobalExceptionHandler{ExceptionHandler(BaseRuntimeException.class)publicResultVoidhandleBaseException(BaseRuntimeExceptionex,HttpServletRequestrequest){returnresolveException(ex,request.getRequestURI());}ExceptionHandler(Exception.class)publicResultVoidhandleOtherException(Exceptionex,HttpServletRequestrequest){returnresolveException(ex,request.getRequestURI());}publicstaticResultVoidresolveException(Exceptionex,Stringpath){ResultVoidresultResult.failure();if(exinstanceofBaseRuntimeExceptionbaseRuntimeException){log.warn(业务异常: {},result);resultbaseRuntimeException.getResult();}else{log.error(系统异常,ex);}result.path(path).errorDetail(ex.getMessage()).errorStackTrace(ex.getStackTrace()).traceId(MDC.get(DefaultConsts.HTTP_HEADER_TRACE_ID));returnresult;}}亮点使用static方法resolveException便于其他处理器复用如后续的校验异常处理器。对BaseRuntimeException仅记录 warn 级别日志对未知异常记录 error 级别并打印堆栈区分了业务预期异常与非预期系统异常。统一补充path、traceId和堆栈信息保证响应完整性。五、参数校验异常处理的挑战Spring Boot 中参数校验可能抛出三种常见异常异常类型触发场景MethodArgumentNotValidExceptionRequestBody标注的 JSON 请求体验证失败BindExceptionModelAttribute或表单参数绑定验证失败ConstraintViolationExceptionRequestParam、PathVariable等单个参数校验失败需配合Validated这三类异常都需要将字段校验错误FieldError或ConstraintViolation转换为前端友好的键值对而不是简单的message。为此项目专门设计了GlobalValidationExceptionHandler。六、小结上篇本文介绍了异常处理模块的整体架构、统一响应体设计、自定义异常体系和基础全局处理器。下一篇我们将深入参数校验异常处理器重点分析 Servlet 环境与 WebFlux 环境下的异同并给出生产环境的优化建议。