JavaBaseExceptionHandler 处理 Java 标准库中的常见运行时异常与受检异常

Java 基础异常

JavaBaseExceptionHandler 是异常处理链的最底层，负责捕获 Java 标准库中的常见异常。该处理器标注 @RestControllerAdvice，所有异常均转换为标准化的 BaseResponse<T> 响应。

MVC 与 WebFlux

本文档描述的异常映射表在 MVC 和 WebFlux 中完全一致。主要差异是返回类型：

MVC: ResponseEntity<BaseResponse<T>>
WebFlux: Mono<ResponseEntity<BaseResponse<T>>>

处理的异常类型

客户端错误（4xx）

字段

类型

服务端错误（5xx）

字段

类型

日志级别

不同类型的异常使用不同的日志级别：

日志级别	异常类型	说明
`ERROR`	NullPointerException, IOException, ClassCastException 等	服务端错误，需要关注
`WARN`	IllegalArgumentException, TimeoutException, FileNotFoundException 等	客户端错误或预期内异常

响应示例

NullPointerException

response.json

{
  "context": "550e8400-e29b-41d4-a716-446655440000",
  "output": "ServerInternalError",
  "code": 50001,
  "message": "服务器内部错误",
  "errorMessage": "空指针异常",
  "duration": 3,
  "data": {
    "message": "Cannot invoke method on null reference"
  }
}

HTTP 状态码为 500（50001 / 100）。

TimeoutException

response.json

{
  "context": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "output": "Timeout",
  "code": 40801,
  "message": "请求超时",
  "errorMessage": "操作超时: Connection timed out",
  "duration": 30000,
  "data": null
}

HTTP 状态码为 408（40801 / 100）。

FileNotFoundException

response.json

{
  "context": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "output": "NotExist",
  "code": 40000,
  "message": "内容不存在",
  "errorMessage": "文件未找到: /data/config.json",
  "duration": 2,
  "data": null
}

HTTP 状态码为 400（40000 / 100）。

设计说明

IllegalArgumentException、FileNotFoundException、TimeoutException 等映射为对应的客户端错误码
NullPointerException、IOException、ClassCastException 等映射为服务端错误码
Exception 兜底处理器确保任何未预期的异常都不会泄露堆栈信息至客户端
所有处理方法均通过 ResultUtil.error() 构建响应，自动注入上下文标识与请求耗时

Java 基础异常

Java 基础异常

处理的异常类型

客户端错误（4xx）

服务端错误（5xx）

日志级别

响应示例

NullPointerException

TimeoutException

FileNotFoundException

设计说明

下一步

公共业务异常

MySQL 异常

异常处理架构

On this page