SpringBoot全局异常处理全景深度解析：Web与RPC接口差异化兜底方案（微服务全覆盖）

代码报错了怎么办Web报错和RPC报错为什么不能用同一套处理逻辑这是单体架构转微服务架构后90%开发者都会踩的核心大坑。在传统单体项目中我们只需适配浏览器Web接口异常统一返回JSON即可但在微服务架构下项目同时存在HTTP Web接口对外给前端和RPC接口对内服务调用两套通信模式。两套接口的异常传播机制、返回规范、兜底逻辑、日志要求完全不同Web接口需要友好前端提示、屏蔽堆栈RPC接口需要透传错误码、保留异常信息、支持服务降级重试。如果全局异常不做Web/RPC差异化处理会出现服务调用雪崩、错误码丢失、微服务调用异常无法溯源、前端/客户端报错错乱等致命线上问题。本文基于SpringBoot2.x/3.x全版本从底层机制差异、双场景异常分类、全景对比、差异化代码实现、踩坑避坑、企业规范全方位解析搭配多维度标准表格打造适配单体微服务的完整全局异常处理体系彻底解决不同场景代码报错兜底问题。一、微服务架构下的核心痛点为什么要区分Web与RPC异常很多项目全局异常失效、微服务调用报错、服务间异常透传失败根源均为用Web接口的异常逻辑处理了RPC接口报错。下表直观展示统一处理带来的线上致命问题。适配场景统一Web异常逻辑错误做法造成的线上问题HTTP Web接口统一返回友好提示、屏蔽堆栈、统一200状态码正常适配前端无问题用户体验良好RPC服务接口统一屏蔽异常堆栈、覆盖原始错误码、吞掉业务异常1. 下游服务只收到“系统异常”无法精准处理降级2. 原始业务错误码丢失服务间校验失效3. 无堆栈信息微服务报错无法溯源4. RPC框架判定无异常重试机制失效核心结论Web异常重在屏蔽、友好兜底RPC异常重在透传、精准溯源二者必须差异化处理不可共用一套逻辑。二、底层原理Web vs RPC 异常机制全景对比Web接口和RPC接口的异常拦截链路、执行时机、框架机制完全不同这是差异化处理的底层根本原因。2.1 两套接口异常传播链路差异接口类型核心通信协议异常传播链路拦截依赖Web接口HTTPHTTP/HTTPSService/Dao异常 → Controller → DispatcherServlet → RestControllerAdvice → 前端JSON响应Spring MVC AOP 切面仅拦截HTTP请求RPC接口Dubbo/FeignTCP/自定义协议Service业务异常 → RPC服务骨架 → 框架异常过滤器 → 抛出远程异常 → 消费端捕获Spring AOP RPC框架自适应切面不被MVC拦截器捕获2.2 核心特性全方位对比企业核心依据对比维度Web HTTP 接口异常RPC 服务接口异常服务对象面向前端浏览器、APP客户端面向后端微服务、内部服务调用设计目标用户体验优先、屏蔽底层细节、保障安全数据精准优先、异常透传、保障调用一致性堆栈处理策略生产环境屏蔽堆栈仅展示友好文案生产环境保留关键堆栈用于服务溯源错误码策略统一HTTP状态码业务码简化前端处理必须透传原始业务错误码保证消费端可识别日志级别业务异常WARN、系统异常ERROR所有RPC业务异常均为ERROR强制记录链路日志重试机制前端自主重试服务端不处理依赖RPC框架重试、降级、熔断异常不可吞兜底原则宁可错兜底不可暴露信息宁可抛异常不可丢失异常信息三、双场景异常分类与标准化处理策略结合Web和RPC双场景重新定义项目四类异常的差异化处理规则覆盖微服务99%报错场景。异常类型典型异常类Web接口处理策略RPC接口处理策略自定义业务异常BusinessException返回友好业务提示WARN日志无堆栈完整透传错误码提示信息ERROR日志保留简要堆栈供消费端判断降级参数校验异常MethodArgumentNotValidException返回字段精准错误提示简化文案抛出标准化参数异常透传字段错误详情禁止笼统提示系统运行时异常空指针、类型转换、数组越界屏蔽详情提示“系统繁忙”ERROR日志存堆栈直接抛出原始异常完整堆栈日志触发RPC熔断降级未知全局异常Exception父类全局兜底屏蔽底层信息原样上抛不兜底掩盖保证微服务链路可追踪四、生产级全套差异化代码实现WebRPC双适配整套代码解决核心问题Web接口统一友好返回、RPC接口精准透传异常通过注解区分接口场景零侵入适配双模式可直接上线微服务项目。4.1 基础通用组件共用无修改统一响应体、错误码枚举、自定义业务异常为项目通用组件双场景共用。import lombok.Data; /** * 全局统一响应体 */ Data public class ResultT { private Integer code; private String msg; private T data; public static T ResultT success(T data) { ResultT result new Result(); result.setCode(200); result.setMsg(操作成功); result.setData(data); return result; } public static T ResultT success() { return success(null); } public static T ResultT error(Integer code, String msg) { ResultT result new Result(); result.setCode(code); result.setMsg(msg); return result; } }import lombok.AllArgsConstructor; import lombok.Getter; /** * 全局统一错误码 */ Getter AllArgsConstructor public enum ErrorCodeEnum { SYSTEM_ERROR(500, 系统内部异常请稍后重试), PARAM_ERROR(400, 请求参数非法), AUTH_ERROR(401, 登录认证失败), PERMISSION_ERROR(403, 权限不足), USER_NOT_EXIST(1001, 用户不存在), PASSWORD_ERROR(1002, 密码错误), BALANCE_NOT_ENOUGH(1003, 账户余额不足); private final Integer code; private final String msg; }import lombok.Data; /** * 自定义业务异常Web/RPC通用 */ Data public class BusinessException extends RuntimeException { private Integer code; private String msg; public BusinessException(ErrorCodeEnum errorCode) { super(errorCode.getMsg()); this.code errorCode.getCode(); this.msg errorCode.getMsg(); } public BusinessException(Integer code, String msg) { super(msg); this.code code; this.msg msg; } }4.2 场景标记注解核心区分Web/RPC接口自定义注解标记RPC接口实现异常处理器动态适配不同场景。import java.lang.annotation.*; /** * 标记RPC服务接口 * 被该注解标记的接口执行RPC异常透传逻辑 */ Target({ElementType.TYPE, ElementType.METHOD}) Retention(RetentionPolicy.RUNTIME) Documented public interface RpcApi { }4.3 核心双场景差异化全局异常处理器自动识别Web接口和RPC接口执行不同的异常兜底逻辑完美适配微服务架构。import lombok.extern.slf4j.Slf4j; import org.springframework.validation.BindException; import org.springframework.validation.FieldError; import org.springframework.web.bind.MethodArgumentNotValidException; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.RestControllerAdvice; import org.springframework.web.method.HandlerMethod; import javax.servlet.http.HttpServletRequest; /** * 微服务全局异常处理器 * 差异化处理Web接口友好兜底、RPC接口异常透传 */ Slf4j RestControllerAdvice public class GlobalExceptionHandler { /** * 判断当前是否为RPC接口请求 */ private boolean isRpcApi(HandlerMethod handlerMethod) { if (handlerMethod null) { return false; } // 方法或类标记RpcApi注解则判定为RPC接口 return handlerMethod.hasMethodAnnotation(RpcApi.class) || handlerMethod.getBeanType().isAnnotationPresent(RpcApi.class); } // 1、自定义业务异常差异化处理 ExceptionHandler(BusinessException.class) public ResultVoid businessExceptionHandler(HttpServletRequest request, HandlerMethod handlerMethod, BusinessException e) { // RPC接口ERROR日志、透传详情不屏蔽信息 if (isRpcApi(handlerMethod)) { log.error(【RPC业务异常】code:{}, msg:{}, e.getCode(), e.getMsg()); throw e; } // Web接口WARN日志、友好提示 log.warn(【Web业务异常】code:{}, msg:{}, e.getCode(), e.getMsg()); return Result.error(e.getCode(), e.getMsg()); } // 2、参数校验异常差异化处理 ExceptionHandler(MethodArgumentNotValidException.class) public ResultVoid validExceptionHandler(HttpServletRequest request, HandlerMethod handlerMethod, MethodArgumentNotValidException e) { FieldError fieldError e.getBindingResult().getFieldError(); String msg fieldError ! null ? fieldError.getDefaultMessage() : 参数非法; if (isRpcApi(handlerMethod)) { log.error(【RPC参数异常】{}, msg); throw new BusinessException(ErrorCodeEnum.PARAM_ERROR.getCode(), msg); } log.warn(【Web参数异常】{}, msg); return Result.error(ErrorCodeEnum.PARAM_ERROR.getCode(), msg); } // 3、空指针系统异常差异化处理 ExceptionHandler(NullPointerException.class) public ResultVoid nullExceptionHandler(HttpServletRequest request, HandlerMethod handlerMethod, NullPointerException e) { if (isRpcApi(handlerMethod)) { log.error(【RPC系统异常-空指针】, e); throw e; } log.error(【Web系统异常-空指针】, e); return Result.error(ErrorCodeEnum.SYSTEM_ERROR.getCode(), 数据加载异常操作失败); } // 4、全局未知异常兜底 ExceptionHandler(Exception.class) public ResultVoid exceptionHandler(HttpServletRequest request, HandlerMethod handlerMethod, Exception e) { // RPC接口不兜底原样抛出保证链路透传 if (isRpcApi(handlerMethod)) { log.error(【RPC未知异常】, e); throw new BusinessException(ErrorCodeEnum.SYSTEM_ERROR); } // Web接口统一友好兜底 log.error(【Web未知系统异常】, e); return Result.error(ErrorCodeEnum.SYSTEM_ERROR.getCode(), 系统繁忙请稍后重试); } }4.4 接口使用示范/** * Web接口对外前端友好兜底 */ RestController RequestMapping(/web/user) public class UserWebController { GetMapping(/login) public ResultString login(String username) { if (username null) { throw new BusinessException(ErrorCodeEnum.PARAM_ERROR); } return Result.success(登录成功); } } /** * RPC接口对内服务调用异常透传 */ RestController RequestMapping(/rpc/user) RpcApi public class UserRpcController { GetMapping(/getById) public ResultString getUserById(Long id) { if (id null) { throw new BusinessException(ErrorCodeEnum.PARAM_ERROR); } return Result.success(用户信息); } }五、Web与RPC异常处理核心差异汇总表处理维度Web HTTP 接口RPC 服务接口差异化原因异常返回方式捕获异常返回标准化JSON不捕获核心异常主动上抛异常RPC框架依赖异常判定调用结果吞异常会导致降级失效错误码透传简化展示部分场景统一500100%透传原始业务错误码消费端需要根据错误码做不同业务降级、重试、提示堆栈信息生产环境屏蔽不对外暴露完整记录堆栈用于微服务链路追踪微服务调用链路长无堆栈无法定位问题服务日志策略业务异常WARN系统异常ERROR所有业务系统异常均为ERROR级别RPC调用失败均属于服务异常需要重点监控告警兜底策略强兜底杜绝原生报错弱兜底不掩盖真实异常RPC优先保证数据真实Web优先保证体验与安全六、微服务高频踩坑与解决方案线上踩坑问题问题根源解决方案RPC调用永远返回成功无法触发降级全局异常统一捕获并返回JSON吞掉了RPC异常RPC接口禁止捕获业务异常主动上抛微服务报错无堆栈无法定位问题照搬Web异常逻辑屏蔽了所有异常堆栈差异化开启RPC堆栈日志记录前端偶尔展示英文异常堆栈Web接口异常未完全兜底部分系统异常透传Web接口全量捕获统一友好提示消费端无法获取服务端自定义错误码RPC异常被包装原始错误码丢失RPC场景原样透传自定义BusinessException异步Async RPC异常拦截失效异步线程脱离MVC切面异步RPC方法内部手动捕获并上抛框架异常七、全文总结与企业落地规范在微服务架构中全局异常处理的核心不再是统一返回而是场景化差异化适配。Web接口面向用户优先安全和体验RPC接口面向服务优先精准和溯源。核心落地规范场景隔离通过自定义注解区分Web/RPC接口两套异常逻辑解耦互不干扰Web规范全量兜底、屏蔽堆栈、友好提示、保障前端体验与项目安全RPC规范异常透传、保留堆栈、不吞报错、保障微服务降级重试机制生效日志规范分级打印日志RPC异常强制告警Web异常区分用户操作与系统Bug架构规范所有微服务必须采用双场景差异化异常方案禁止Web/RPC共用一套逻辑。