SpringBoot全局异常处理方式是什么

发布时间：2021-11-19 16:27:25 作者：iii
来源：亿速云阅读：159

# SpringBoot全局异常处理方式是什么

## 目录
- [引言](#引言)
- [为什么需要全局异常处理](#为什么需要全局异常处理)
- [SpringBoot异常处理核心机制](#springboot异常处理核心机制)
  - [默认错误处理](#默认错误处理)
  - [BasicErrorController](#basicerrorcontroller)
- [5种全局异常处理实现方式](#5种全局异常处理实现方式)
  - [1. @ControllerAdvice + @ExceptionHandler](#1-controlleradvice--exceptionhandler)
  - [2. 实现HandlerExceptionResolver接口](#2-实现handlerexceptionresolver接口)
  - [3. 自定义ErrorController](#3-自定义errorcontroller)
  - [4. @ResponseStatus定义异常](#4-responsestatus定义异常)
  - [5. Filter级别的异常处理](#5-filter级别的异常处理)
- [最佳实践与对比分析](#最佳实践与对比分析)
- [高级应用场景](#高级应用场景)
  - [异常处理与事务管理](#异常处理与事务管理)
  - [国际化异常消息](#国际化异常消息)
  - [自定义异常体系设计](#自定义异常体系设计)
- [性能优化建议](#性能优化建议)
- [常见问题排查](#常见问题排查)
- [总结](#总结)

## 引言

在Web应用开发中，异常处理是保证系统健壮性和用户体验的关键环节。SpringBoot作为当下最流行的Java Web框架，提供了多种灵活的全局异常处理机制。本文将深入剖析SpringBoot全局异常处理的实现原理、具体方案和最佳实践，帮助开发者构建更加健壮的后端服务。

## 为什么需要全局异常处理

传统开发模式中，异常处理通常分散在各个Controller方法中：

```java
@GetMapping("/user/{id}")
public User getUser(@PathVariable Long id) {
    try {
        return userService.findById(id);
    } catch (UserNotFoundException e) {
        // 处理特定异常
    } catch (DatabaseException e) {
        // 处理数据库异常
    } catch (Exception e) {
        // 处理其他异常
    }
}

这种模式存在三个主要问题： 1. 代码重复：每个方法都需要重复异常处理逻辑 2. 维护困难：异常处理逻辑变更需要修改多处 3. 响应不统一：不同方法可能返回不同格式的错误响应

全局异常处理通过集中管理异常处理逻辑，可以： - 统一错误响应格式 - 减少样板代码 - 提高代码可维护性 - 实现异常与业务逻辑解耦

SpringBoot异常处理核心机制

默认错误处理

SpringBoot默认提供了/error映射，当应用抛出异常时： 1. 对于浏览器请求：返回Whitelabel错误页面 2. 对于机器客户端请求：返回JSON响应

{
    "timestamp": "2023-08-20T10:30:15.123+00:00",
    "status": 500,
    "error": "Internal Server Error",
    "path": "/api/users"
}

BasicErrorController

SpringBoot自动配置的BasicErrorController是默认错误处理的核心：

@Controller
@RequestMapping("${server.error.path:${error.path:/error}}")
public class BasicErrorController extends AbstractErrorController {
    
    @RequestMapping(produces = MediaType.TEXT_HTML_VALUE)
    public ModelAndView errorHtml(HttpServletRequest request, 
                                HttpServletResponse response) {
        // 返回HTML错误页面
    }
    
    @RequestMapping
    public ResponseEntity<Map<String, Object>> error(HttpServletRequest request) {
        // 返回JSON错误响应
    }
}

5种全局异常处理实现方式

1. @ControllerAdvice + @ExceptionHandler

最推荐的方式，结合AOP思想实现异常集中处理：

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);

    /**
     * 处理业务异常
     */
    @ExceptionHandler(BusinessException.class)
    public Result<Void> handleBusinessException(BusinessException e) {
        log.error("业务异常: {}", e.getMessage(), e);
        return Result.fail(e.getCode(), e.getMessage());
    }

    /**
     * 处理系统异常
     */
    @ExceptionHandler(Exception.class)
    public Result<Void> handleException(Exception e) {
        log.error("系统异常: ", e);
        return Result.fail(500, "系统繁忙，请稍后再试");
    }

    /**
     * 处理参数校验异常
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<Void> handleMethodArgumentNotValidException(
            MethodArgumentNotValidException e) {
        String message = e.getBindingResult().getAllErrors().stream()
                .map(DefaultMessageSourceResolvable::getDefaultMessage)
                .collect(Collectors.joining("; "));
        return Result.fail(400, message);
    }
}

优点： - 代码简洁直观 - 支持细粒度的异常分类处理 - 与Controller逻辑完全解耦

2. 实现HandlerExceptionResolver接口

更底层的处理方式，适合需要完全控制异常处理流程的场景：

@Component
public class CustomHandlerExceptionResolver implements HandlerExceptionResolver {

    @Override
    public ModelAndView resolveException(
            HttpServletRequest request,
            HttpServletResponse response,
            Object handler,
            Exception ex) {
        
        if (ex instanceof BusinessException) {
            // 处理业务异常
        } else if (ex instanceof MethodArgumentNotValidException) {
            // 处理参数校验异常
        }
        
        // 返回自定义ModelAndView
        return new ModelAndView();
    }
}

执行顺序： 1. ExceptionHandlerExceptionResolver（处理@ExceptionHandler） 2. ResponseStatusExceptionResolver（处理@ResponseStatus） 3. DefaultHandlerExceptionResolver（Spring默认处理） 4. 自定义HandlerExceptionResolver

3. 自定义ErrorController

完全接管SpringBoot默认错误处理：

@RestController
@RequestMapping("/error")
public class MyErrorController implements ErrorController {

    @Autowired
    private ErrorAttributes errorAttributes;

    @RequestMapping
    public Result<?> error(HttpServletRequest request) {
        Map<String, Object> body = getErrorAttributes(request);
        return Result.fail(
            (Integer) body.get("status"),
            (String) body.get("error"));
    }

    private Map<String, Object> getErrorAttributes(HttpServletRequest request) {
        return errorAttributes.getErrorAttributes(
            new ServletWebRequest(request),
            ErrorAttributeOptions.defaults());
    }
}

配置项：

server.error.path=/api/error
server.error.include-message=always

4. @ResponseStatus定义异常

适用于简单的HTTP状态码映射：

@ResponseStatus(code = HttpStatus.NOT_FOUND, reason = "用户不存在")
public class UserNotFoundException extends RuntimeException {
    // ...
}

// 使用示例
@GetMapping("/user/{id}")
public User getUser(@PathVariable Long id) {
    return userRepository.findById(id)
            .orElseThrow(UserNotFoundException::new);
}

5. Filter级别的异常处理

处理过滤器链中抛出的异常：

@Component
public class ExceptionHandlerFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                  HttpServletResponse response,
                                  FilterChain filterChain) {
        try {
            filterChain.doFilter(request, response);
        } catch (Exception e) {
            // 处理异常并写入response
            response.setContentType("application/json");
            response.getWriter().write(
                objectMapper.writeValueAsString(
                    Result.fail(500, e.getMessage())));
        }
    }
}

最佳实践与对比分析

方案	适用场景	优点	缺点
@ControllerAdvice	常规业务异常	使用简单，功能强大	无法处理过滤器异常
HandlerExceptionResolver	需要完全控制流程	处理优先级高	实现较复杂
ErrorController	替换默认错误处理	完全自定义错误响应	需要处理原始错误属性
@ResponseStatus	简单状态码映射	声明式配置	灵活性差
Filter处理	过滤器异常	处理早期异常	破坏FilterChain

推荐组合方案： 1. 使用@ControllerAdvice处理大多数业务异常 2. 自定义ErrorController提供备用错误处理 3. 使用Filter处理安全框架等前置异常

高级应用场景

异常处理与事务管理

@Service
public class UserService {
    
    @Transactional
    public void createUser(User user) {
        try {
            userRepository.save(user);
            sendWelcomeEmail(user); // 可能抛出异常
        } catch (EmailException e) {
            // 标记事务为回滚
            TransactionAspectSupport.currentTransactionStatus()
                .setRollbackOnly();
            throw new BusinessException("邮件发送失败", e);
        }
    }
}

国际化异常消息

定义消息资源文件：

# messages.properties
user.notfound=用户不存在
error.unknown=系统错误

# messages_zh_CN.properties
user.notfound=用户不存在
error.unknown=系统错误

在异常处理器中使用：

@ExceptionHandler(UserNotFoundException.class)
public Result<Void> handleUserNotFound(
        UserNotFoundException e,
        Locale locale) {
    String message = messageSource.getMessage(
        "user.notfound", null, locale);
    return Result.fail(404, message);
}

自定义异常体系设计

// 基础异常类
public abstract class BaseException extends RuntimeException {
    private final int code;
    private final String errorKey;
    
    public BaseException(int code, String errorKey, String message) {
        super(message);
        this.code = code;
        this.errorKey = errorKey;
    }
    
    // getters...
}

// 业务异常
public class BusinessException extends BaseException {
    public BusinessException(String errorKey, String message) {
        super(400, errorKey, message);
    }
}

// 系统异常
public class SystemException extends BaseException {
    public SystemException(String errorKey, String message) {
        super(500, errorKey, message);
    }
}

性能优化建议

异常构造开销：
- 避免在异常构造函数中执行复杂逻辑
- 对于高频异常可考虑使用静态异常实例
日志记录优化： “`java // 避免不必要的字符串拼接 log.error(“查询用户失败，ID: {}, 原因: {}”, userId, e.getMessage(), e);

// 使用条件日志 if (log.isDebugEnabled()) { log.debug(“详细调试信息: {}”, expensiveOperation()); }


3. **响应序列化**：
   - 使用Jackson的`@JsonInclude`减少不必要字段
   - 对敏感信息进行脱敏处理

## 常见问题排查

1. **异常处理不生效**：
   - 检查`@ControllerAdvice`是否在组件扫描路径
   - 确认没有更具体的`@ExceptionHandler`处理了该异常
   - 检查过滤器是否捕获了异常未继续抛出

2. **响应格式不一致**：
   - 确保所有异常处理器返回相同结构的Result对象
   - 检查是否有多个异常处理器匹配同一异常

3. **事务不回滚**：
   - 确认异常是否被捕获未传播到Spring事务管理器
   - 检查`@Transactional`的rollbackFor配置

## 总结

SpringBoot提供了从简单到复杂的多层次异常处理方案，开发者可以根据项目需求选择合适的组合方式。良好的异常处理应该：
- 提供清晰的错误信息
- 保持响应格式统一
- 区分客户端和服务端错误
- 记录足够的排查信息
- 保证系统安全性

通过本文介绍的各种技术方案和最佳实践，开发者可以构建出健壮、易维护的异常处理体系，显著提升系统的可靠性和开发效率。

注：实际输出约3000字，要达到9750字需要扩展以下内容： 1. 每个方案的更多实现细节和示例 2. 增加性能测试数据对比 3. 添加更多实际案例场景 4. 深入源码分析机制 5. 增加异常处理流程图 6. 补充SpringBoot版本差异说明 7. 添加与微服务异常处理的联动方案 8. 增加安全相关异常处理专题需要继续扩展哪些部分可以告诉我。