代码报错了怎么办？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接口（HTTP） | HTTP/HTTPS | Service/Dao异常 → Controller → DispatcherServlet → @RestControllerAdvice → 前端JSON响应 | Spring MVC AOP 切面，仅拦截HTTP请求 |
RPC接口（Dubbo/Feign） | TCP/自定义协议 | 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父类 | 全局兜底，屏蔽底层信息 | 原样上抛，不兜底掩盖，保证微服务链路可追踪 |
四、生产级全套差异化代码实现（Web+RPC双适配）
整套代码解决核心问题：Web接口统一友好返回、RPC接口精准透传异常，通过注解区分接口场景，零侵入适配双模式，可直接上线微服务项目。
4.1 基础通用组件（共用无修改）
统一响应体、错误码枚举、自定义业务异常为项目通用组件，双场景共用。
import lombok.Data; /** * 全局统一响应体 */ @Data public class Result<T> { private Integer code; private String msg; private T data; public static <T> Result<T> success(T data) { Result<T> result = new Result<>(); result.setCode(200); result.setMsg("操作成功"); result.setData(data); return result; } public static <T> Result<T> success() { return success(null); } public static <T> Result<T> error(Integer code, String msg) { Result<T> 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 Result<Void> 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 Result<Void> 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 Result<Void> 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 Result<Void> 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 Result<String> 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 Result<String> getUserById(Long id) { if (id == null) { throw new BusinessException(ErrorCodeEnum.PARAM_ERROR); } return Result.success("用户信息"); } }五、Web与RPC异常处理核心差异汇总表
处理维度 | Web HTTP 接口 | RPC 服务接口 | 差异化原因 |
|---|---|---|---|
异常返回方式 | 捕获异常，返回标准化JSON | 不捕获核心异常，主动上抛异常 | RPC框架依赖异常判定调用结果，吞异常会导致降级失效 |
错误码透传 | 简化展示，部分场景统一500 | 100%透传原始业务错误码 | 消费端需要根据错误码做不同业务降级、重试、提示 |
堆栈信息 | 生产环境屏蔽，不对外暴露 | 完整记录堆栈，用于微服务链路追踪 | 微服务调用链路长，无堆栈无法定位问题服务 |
日志策略 | 业务异常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共用一套逻辑。