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

代码报错了怎么办？Web报错和RPC报错为什么不能用同一套处理逻辑？

这是单体架构转微服务架构后，90%开发者都会踩的核心大坑。在传统单体项目中，我们只需适配浏览器Web接口异常，统一返回JSON即可；但在微服务架构下，项目同时存在 HTTP Web接口（对外给前端） 和 RPC接口（对内服务调用）两套通信模式。

两套接口的异常传播机制、返回规范、兜底逻辑、日志要求完全不同：Web接口需要友好前端提示、屏蔽堆栈；RPC接口需要透传错误码、保留异常信息、支持服务降级重试。如果全局异常不做Web/RPC差异化处理，会出现服务调用雪崩、错误码丢失、微服务调用异常无法溯源、前端/客户端报错错乱等致命线上问题。

本文基于SpringBoot2.x/3.x全版本，从底层机制差异、双场景异常分类、全景对比、差异化代码实现、踩坑避坑、企业规范全方位解析，搭配多维度标准表格，打造适配单体+微服务的完整全局异常处理体系，彻底解决不同场景代码报错兜底问题。

一、微服务架构下的核心痛点：为什么要区分Web与RPC异常？

很多项目全局异常失效、微服务调用报错、服务间异常透传失败，根源均为：用Web接口的异常逻辑处理了RPC接口报错。下表直观展示统一处理带来的线上致命问题。

适配场景

统一Web异常逻辑（错误做法）

造成的线上问题

核心结论：Web异常重在屏蔽、友好兜底，RPC异常重在透传、精准溯源，二者必须差异化处理，不可共用一套逻辑。

二、底层原理：Web vs RPC 异常机制全景对比

Web接口和RPC接口的异常拦截链路、执行时机、框架机制完全不同，这是差异化处理的底层根本原因。

2.1 两套接口异常传播链路差异

接口类型

核心通信协议

异常传播链路

拦截依赖

2.2 核心特性全方位对比（企业核心依据）

对比维度

Web HTTP 接口异常

RPC 服务接口异常

三、双场景异常分类与标准化处理策略

结合Web和RPC双场景，重新定义项目四类异常的差异化处理规则，覆盖微服务99%报错场景。

异常类型

典型异常类

Web接口处理策略

RPC接口处理策略

四、生产级全套差异化代码实现（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 服务接口

差异化原因

六、微服务高频踩坑与解决方案

线上踩坑问题

问题根源

解决方案

七、全文总结与企业落地规范

在微服务架构中，全局异常处理的核心不再是统一返回，而是场景化差异化适配。Web接口面向用户，优先安全和体验；RPC接口面向服务，优先精准和溯源。

核心落地规范：