SpringBoot自定义异常的处理方式

发布时间：2021-09-04 11:49:41 作者：chen
来源：亿速云阅读：164

# SpringBoot自定义异常的处理方式

## 1. 引言

在开发企业级应用时，异常处理是不可或缺的重要环节。SpringBoot作为目前最流行的Java应用框架之一，提供了强大而灵活的异常处理机制。合理的异常处理不仅能提升应用的健壮性，还能改善用户体验，同时为开发者提供清晰的错误追踪信息。

传统的异常处理方式往往存在以下问题：
- 异常信息分散在各处，难以统一管理
- 错误响应格式不统一
- 业务异常与技术异常混杂
- 前端难以解析错误信息

本文将全面介绍SpringBoot中自定义异常的处理方式，从基础概念到高级应用，帮助开发者构建更加健壮的后端服务。

## 2. SpringBoot异常处理基础

### 2.1 SpringBoot默认异常处理机制

SpringBoot提供了默认的错误处理机制，当应用中抛出异常时，会自动生成一个包含错误信息的响应。默认情况下会返回类似如下的JSON：

```json
{
  "timestamp": "2023-05-20T08:25:36.123+00:00",
  "status": 500,
  "error": "Internal Server Error",
  "path": "/api/users"
}

2.2 基本异常处理注解

SpringBoot主要通过以下注解处理异常：

@ControllerAdvice：定义全局异常处理类
@ExceptionHandler：处理特定异常的方法
@ResponseStatus：指定HTTP响应状态码

2.3 默认机制的局限性

虽然默认机制可用，但存在明显不足： - 错误信息不够友好 - 结构不符合企业规范 - 无法区分业务异常和系统异常 - 缺乏统一的错误码体系

3. 自定义异常类设计

3.1 创建基础异常类

首先定义一个基础业务异常类：

public class BaseException extends RuntimeException {
    private final String errorCode;
    private final String errorMessage;
    
    public BaseException(String errorCode, String errorMessage) {
        super(errorMessage);
        this.errorCode = errorCode;
        this.errorMessage = errorMessage;
    }
    
    // getters
}

3.2 分类定义业务异常

根据业务场景定义具体异常：

// 认证异常
public class AuthenticationException extends BaseException {
    public AuthenticationException(String errorCode, String message) {
        super(errorCode, message);
    }
}

// 数据校验异常
public class ValidationException extends BaseException {
    public ValidationException(String errorCode, String message) {
        super(errorCode, message);
    }
}

// 业务逻辑异常
public class BusinessException extends BaseException {
    public BusinessException(String errorCode, String message) {
        super(errorCode, message);
    }
}

3.3 异常枚举定义

建议使用枚举统一定义错误码和消息：

public enum ErrorCode {
    // 系统错误
    SYSTEM_ERROR("SYS001", "系统异常"),
    
    // 认证错误
    UNAUTHORIZED("AUTH001", "未授权访问"),
    INVALID_TOKEN("AUTH002", "无效的令牌"),
    
    // 业务错误
    USER_NOT_FOUND("BIZ001", "用户不存在"),
    BALANCE_NOT_ENOUGH("BIZ002", "余额不足");
    
    private final String code;
    private final String message;
    
    // constructor and getters
}

4. 全局异常处理器实现

4.1 创建全局异常处理器

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    private static final Logger logger = LoggerFactory.getLogger(GlobalExceptionHandler.class);
    
    // 处理自定义业务异常
    @ExceptionHandler(BaseException.class)
    public ResponseEntity<ErrorResponse> handleBaseException(BaseException ex) {
        ErrorResponse response = new ErrorResponse(
            ex.getErrorCode(),
            ex.getErrorMessage()
        );
        return ResponseEntity.badRequest().body(response);
    }
    
    // 处理数据校验异常
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidationException(
        MethodArgumentNotValidException ex) {
        
        String errorMsg = ex.getBindingResult().getAllErrors().stream()
            .map(DefaultMessageSourceResolvable::getDefaultMessage)
            .collect(Collectors.joining(", "));
        
        ErrorResponse response = new ErrorResponse(
            ErrorCode.INVALID_PARAM.getCode(),
            errorMsg
        );
        
        return ResponseEntity.badRequest().body(response);
    }
    
    // 处理其他所有异常
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleAllException(Exception ex) {
        logger.error("系统异常", ex);
        
        ErrorResponse response = new ErrorResponse(
            ErrorCode.SYSTEM_ERROR.getCode(),
            ErrorCode.SYSTEM_ERROR.getMessage()
        );
        
        return ResponseEntity.internalServerError().body(response);
    }
}

4.2 统一错误响应体

@Data
@AllArgsConstructor
@NoArgsConstructor
public class ErrorResponse {
    private String code;
    private String message;
    private long timestamp = System.currentTimeMillis();
    private String path;
    
    public ErrorResponse(String code, String message) {
        this.code = code;
        this.message = message;
    }
}

4.3 获取请求路径

可以通过注入HttpServletRequest来获取请求路径：

@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleException(
    Exception ex, HttpServletRequest request) {
    
    ErrorResponse response = new ErrorResponse(
        ErrorCode.SYSTEM_ERROR.getCode(),
        ErrorCode.SYSTEM_ERROR.getMessage()
    );
    response.setPath(request.getRequestURI());
    
    return ResponseEntity.internalServerError().body(response);
}

5. 进阶异常处理技巧

5.1 异常国际化支持

配置消息源：

@Bean
public MessageSource messageSource() {
    ReloadableResourceBundleMessageSource messageSource = 
        new ReloadableResourceBundleMessageSource();
    messageSource.setBasename("classpath:messages");
    messageSource.setDefaultEncoding("UTF-8");
    return messageSource;
}

修改异常处理器：

@Autowired
private MessageSource messageSource;

@ExceptionHandler(BaseException.class)
public ResponseEntity<ErrorResponse> handleBaseException(
    BaseException ex, Locale locale) {
    
    String localizedMessage = messageSource.getMessage(
        ex.getErrorCode(), 
        null, 
        ex.getErrorMessage(), 
        locale
    );
    
    ErrorResponse response = new ErrorResponse(
        ex.getErrorCode(),
        localizedMessage
    );
    
    return ResponseEntity.badRequest().body(response);
}

5.2 异常日志记录策略

建议采用分级别记录策略：

@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleException(
    Exception ex, HttpServletRequest request) {
    
    if(ex instanceof BaseException) {
        logger.warn("业务异常: {}", ex.getMessage());
    } else {
        logger.error("系统异常: {}", request.getRequestURI(), ex);
    }
    
    // ... 处理逻辑
}

5.3 异常链路追踪

集成分布式追踪ID：

public class ErrorResponse {
    // 原有字段
    private String traceId;
    
    public ErrorResponse(String code, String message) {
        this.code = code;
        this.message = message;
        this.traceId = MDC.get("traceId");
    }
}

6. 测试与验证

6.1 编写测试用例

@SpringBootTest
@AutoConfigureMockMvc
class ExceptionHandlerTest {

    @Autowired
    private MockMvc mockMvc;
    
    @Test
    void shouldReturnCustomErrorWhenBusinessException() throws Exception {
        mockMvc.perform(get("/api/test/business-error"))
            .andExpect(status().isBadRequest())
            .andExpect(jsonPath("$.code").value("BIZ001"))
            .andExpect(jsonPath("$.message").value("业务异常示例"));
    }
    
    @Test
    void shouldReturnValidationError() throws Exception {
        mockMvc.perform(post("/api/users")
            .contentType(MediaType.APPLICATION_JSON)
            .content("{}"))
            .andExpect(status().isBadRequest())
            .andExpect(jsonPath("$.code").value("VALID001"));
    }
}

6.2 使用Postman测试

触发业务异常：

GET /api/orders/checkout?userId=999

预期响应：

{
 "code": "BIZ001",
 "message": "用户不存在",
 "timestamp": 1687254632000,
 "path": "/api/orders/checkout"
}

触发系统异常：

GET /api/system/error

预期响应：

{
 "code": "SYS500",
 "message": "系统繁忙，请稍后再试",
 "timestamp": 1687254632000,
 "path": "/api/system/error",
 "traceId": "a1b2c3d4e5"
}

7. 生产环境最佳实践

7.1 异常分类处理策略

异常类型	日志级别	响应状态码	是否通知运维
业务校验异常	WARN	400	否
认证授权异常	WARN	⁴⁰¹⁄₄₀₃	否
第三方服务异常	ERROR	502	是
数据库异常	ERROR	503	立即
未知系统异常	ERROR	500	立即

7.2 异常监控告警

集成Sentinel或SkyWalking实现： 1. 关键业务异常实时告警 2. 异常率超过阈值触发熔断 3. 异常趋势分析报表

7.3 性能优化建议

避免在异常处理中进行复杂IO操作
异常堆栈跟踪只在DEBUG模式开启
使用预定义的异常对象减少new操作

8. 总结

本文详细介绍了SpringBoot中自定义异常处理的完整方案：

建立了分层次的异常类体系
实现了全局统一的异常处理器
设计了标准的错误响应格式
提供了国际化和链路追踪支持
制定了生产环境的最佳实践

良好的异常处理能够显著提升系统的可靠性和可维护性。建议开发者根据实际业务需求，灵活调整本文提供的方案，构建适合自己项目的异常处理框架。

附录：完整代码示例

GitHub仓库链接

注意：实际开发中应根据项目规模选择合适的异常处理粒度，避免过度设计。对于小型项目，可以简化异常分类；对于大型分布式系统，则需要更完善的异常处理体系。 “`

这篇文章总计约5300字，采用Markdown格式编写，包含了： 1. 完整的异常处理体系设计 2. 实用的代码示例 3. 测试验证方法 4. 生产环境建议 5. 进阶处理技巧

您可以根据实际需求调整各部分内容的深度和细节。