SpringBoot中默认异常处理机制的实现

 更新时间:2025年08月20日 09:32:26   作者:南姜先生  
本文主要介绍了Spring Boot 中的默认异常处理机制,如 /error 接口,用于统一返回错误信息,具有一定的参考价值,感兴趣的可以了解一下

Spring Boot 中,为了简化 Web 应用的异常处理流程,它提供了一套默认的全局异常处理机制,其中最核心的就是 /error 接口。这个接口是 Spring Boot 提供的一个内置错误页面控制器(BasicErrorController),用于统一返回错误信息。

🧠 一句话总结:

✅ Spring Boot 默认使用 BasicErrorController 来处理所有未被捕获的异常,并通过 /error 接口返回结构化的错误响应或跳转到错误页面(如 HTML 页面)。

🔍 一、默认行为概览

请求类型返回内容
浏览器请求(HTML)跳转到 /error 页面(如 error.html
API 请求(JSON/REST)返回 JSON 格式的错误信息

例如:

  • 访问一个不存在的路径:GET /not-found
  • 控制器抛出未处理的异常 都会被 Spring Boot 的 /error 端点捕获并处理。

🛠️ 二、核心组件解析

1.BasicErrorController

这是 Spring Boot 默认提供的错误处理器,负责处理 /error 请求。

@Controller
@RequestMapping("${server.error.path:${spring.mvc.async.request-timeout}}")
public class BasicErrorController extends AbstractErrorController {
    ...
}
  • 默认路径为 /error(可通过 server.error.path 配置修改)
  • 支持两种响应格式:
    • text/html:返回 HTML 错误页面(如 error.html
    • 其他格式(如 JSON):返回结构化错误信息

2.ErrorAttributes接口

该接口定义了错误信息的内容来源,包括:

  • 异常对象
  • HTTP 状态码
  • 请求 URL
  • 时间戳等

默认实现是 DefaultErrorAttributes,你也可以自定义。

3.ErrorViewResolver接口

用于解析 HTML 错误页面。例如:

  • /templates/error/404.html
  • /templates/error/5xx.html
  • /templates/error.html

Spring Boot 会根据状态码优先匹配具体页面。

📦 三、默认返回的 JSON 错误结构

当你访问一个 REST 接口时,如果发生异常且没有被 @ExceptionHandler@ControllerAdvice 捕获,Spring Boot 会返回如下格式的 JSON 响应:

{
  "timestamp": "2025-07-12T10:45:00.000+00:00",
  "status": 404,
  "error": "Not Found",
  "path": "/not-found"
}

字段说明:

字段名含义
timestamp错误发生时间
statusHTTP 状态码
error错误描述
exception异常类名(仅当 spring.boot.debug=true 时显示)
message异常消息(可选)
path出错的请求路径

🌐 四、如何自定义错误处理?

虽然 Spring Boot 提供了默认的错误处理机制,但在实际项目中我们通常需要进行定制:

1.方式一:自定义ErrorAttributes

你可以实现 ErrorAttributes 接口来自定义错误信息内容:

@Component
public class CustomErrorAttributes extends DefaultErrorAttributes {
    @Override
    public Map<String, Object> getErrorAttributes(WebRequest webRequest, ErrorAttributeOptions options) {
        Map<String, Object> errorMap = super.getErrorAttributes(webRequest, options);
        errorMap.put("customInfo", "This is a custom error info.");
        return errorMap;
    }
}

2.方式二:继承BasicErrorController自定义控制器

@RestController
@RequestMapping("${server.error.path:/error}")
public class CustomErrorController extends BasicErrorController {

    public CustomErrorController(ErrorAttributes errorAttributes) {
        super(errorAttributes, new ErrorProperties());
    }

    @Override
    public ResponseEntity<Map<String, Object>> error(HttpServletRequest request) {
        Map<String, Object> body = getErrorAttributes(new ServletWebRequest(request), true);
        return new ResponseEntity<>(body, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

3.方式三:创建自定义错误页面(HTML)

将 HTML 页面放在以下位置之一即可:

  • src/main/resources/templates/error/404.html
  • src/main/resources/static/error/500.html
  • src/main/resources/public/error.html

Spring Boot 会根据 HTTP 状态码自动选择对应的页面。

4.方式四:使用@ControllerAdvice全局处理异常

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(Exception.class)
    public ResponseEntity<Map<String, Object>> handleException(Exception ex, HttpServletRequest request) {
        Map<String, Object> errorBody = new HashMap<>();
        errorBody.put("error", ex.getMessage());
        errorBody.put("path", request.getRequestURI());
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(errorBody);
    }
}

这种方式比默认机制更灵活,适用于大型项目。

⚙️ 五、配置相关属性(application.yml)

你可以在 application.ymlapplication.properties 中配置一些与错误相关的参数:

spring:
  mvc:
    async:
      request-timeout: 0 # 禁用超时控制
server:
  error:
    path: /my-error     # 自定义错误路径
    whitelabel:
      enabled: false    # 关闭默认白标错误页

✅ 六、总结

项目内容
默认错误端点/error
默认控制器BasicErrorController
默认错误信息DefaultErrorAttributes
默认视图支持支持 HTML 错误页面(按状态码命名)
JSON 输出格式包含 timestamp, status, error, path 等字段
可扩展性支持自定义 ErrorAttributes、ErrorController、HTML 页面、@ControllerAdvice

到此这篇关于SpringBoot中默认异常处理机制的实现的文章就介绍到这了,更多相关SpringBoot 默认异常处理机制内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家! 

相关文章

  • Spring中BeanFactoryPostProcessors是如何执行的

    Spring中BeanFactoryPostProcessors是如何执行的

    BeanFactoryPostProcessor是Spring容器提供的一个扩展机制,它允许开发者在Bean的实例化和初始化之前对BeanDefinition进行修改和处理,这篇文章主要介绍了你知道Spring中BeanFactoryPostProcessors是如何执行的吗,需要的朋友可以参考下
    2023-11-11
  • maven继承父工程统一版本号的实现

    maven继承父工程统一版本号的实现

    这篇文章主要介绍了maven继承父工程统一版本号的实现,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2020-08-08
  • 基于springboot+vue实现垃圾分类管理系统

    基于springboot+vue实现垃圾分类管理系统

    这篇文章主要为大家详细介绍了基于springboot+vue实现垃圾分类管理系统,文中示例代码介绍的非常详细,具有一定的参考价值,感兴趣的小伙伴们可以参考一下
    2021-07-07
  • 在java中获取List集合中最大的日期时间操作

    在java中获取List集合中最大的日期时间操作

    这篇文章主要介绍了在java中获取List集合中最大的日期时间操作,具有很好的参考价值,希望对大家有所帮助。一起跟随小编过来看看吧
    2020-08-08
  • Java实现发送HTML内容并带附件的电子邮件

    Java实现发送HTML内容并带附件的电子邮件

    这篇文章主要为大家详细介绍了如何使用Java实现发送HTML内容并带附件的电子邮件,文中的示例代码讲解详细,有需要的小伙伴可以参考一下
    2025-01-01
  • Spring Boot项目中定制拦截器的方法详解

    Spring Boot项目中定制拦截器的方法详解

    这篇文章主要介绍了Spring Boot项目中定制拦截器的方法详解,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
    2019-10-10
  • MybatisPlus特殊查询的实现介绍

    MybatisPlus特殊查询的实现介绍

    这篇文章主要介绍了MybatisPlus查询投影、聚合查询、分组查询、等值查询、范围查询、模糊查询、排序查询,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习吧
    2022-10-10
  • 详解java构建者模式Builder

    详解java构建者模式Builder

    这篇文章主要介绍了java构建者模式Builder,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2019-04-04
  • 使用Backoff策略提高HttpClient连接管理的效率

    使用Backoff策略提高HttpClient连接管理的效率

    这篇文章主要为大家介绍了Backoff策略提高HttpClient连接管理的效率使用解析,有需要的朋友可以借鉴参考下,希望能够有所帮助,祝大家多多进步,早日升职加薪
    2023-10-10
  • springboot序列化和反序列化器配置方法

    springboot序列化和反序列化器配置方法

    这篇文章主要介绍了springboot序列化和反序列化器配置方法,本文通过实例代码给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下
    2023-08-08

最新评论