Spring Boot 3.x 错误处理与 ProblemDetail 自动配置：构建符合 RFC 7807 的标准化错误响应体系

敖正炀
5 阅读40分钟

概述

衔接前文： 前文《嵌入式 Web 容器的生命周期整合》已清晰阐明，Servlet 容器（如内嵌 Tomcat）作为请求的入口与响应的出口，是所有请求处理的生命线。容器在启动时初始化 ServletContext，注册 DispatcherServlet，并将请求委托给 Spring MVC 进行处理。然而，再健壮的体系也无法避免异常的发生。当请求处理链路中任何一环抛出异常，或被容器判定为错误（如 404），Spring Boot 如何介入并接管处理？更进一步，它如何将纷繁复杂的技术异常转化为对客户端友好、格式统一且符合国际标准的 HTTP 响应？这正是本文要深入拆解的核心命题。

Spring Boot 3.x 在错误处理领域做出了里程碑式的升级，全面拥抱 RFC 7807 (Problem Details for HTTP APIs) 标准，引入 ProblemDetail 作为核心错误表示。这一变革并非是推翻重来，而是在原有 BasicErrorController、ErrorAttributes 等扩展点的基础上，通过 ErrorMvcAutoConfiguration 的自动配置演进，将新的标准化组件无缝整合进经典的错误处理流程中。本文将带领读者深入源码，从 RFC 7807 标准解读出发，逐步拆解自动配置装配、核心控制器演进、异常体系重构，直至自定义扩展与生产实践，完整呈现 Spring Boot 3.x 如何构建一个灵活、可扩展且符合国际标准的错误响应体系。

核心要点

  • RFC 7807 标准落地：Spring Framework 6.x 提供了 ProblemDetail 类，为 API 错误响应定义了 type、title、status、detail、instance 等标准字段。
  • 自动配置的演进：ErrorMvcAutoConfiguration 在 3.x 中条件化地注册了与 ProblemDetail 相关的 Bean，如 ProblemDetailsErrorAttributes，并与传统 BasicErrorController 协同工作。
  • BasicErrorController 的延续与改变：依然作为默认的 /error 端点处理器，但其 JSON 响应体已从传统的 Map 结构转变为 ProblemDetail 对象。
  • 异常体系重构：引入 ErrorResponseException 体系，允许异常自身携带 ProblemDetail 体，通过 @ControllerAdvice 等机制可直接返回标准化错误。
  • 无缝的后向兼容：ErrorAttributes 接口依然保留，其数据会被填充到 ProblemDetail 的 properties 附加字段中，最大程度保证了旧版自定义属性的平滑过渡。
  • Jakarta EE 迁移：底层 Servlet API 从 javax.servlet 迁移至 jakarta.servlet，ErrorController 及 ErrorAttributes 等接口的包路径随之调整，这是升级到 3.x 必须注意的变更。

文章组织架构图

flowchart TB
    subgraph s1 ["1. 标准与抽象层"]
        direction TB
        n1["1. RFC 7807 与 ProblemDetail<br/>错误响应的标准化"]
    end

    subgraph s2 ["2. 全景与核心链路"]
        direction TB
        n2["2. Spring Boot 3.x<br/>错误处理全景"]
    end

    subgraph s3 ["3. 自动配置层"]
        direction TB
        n3["3. ErrorMvcAutoConfiguration<br/>自动配置拆解"]
    end

    subgraph s4 ["4. 核心控制器演进"]
        direction TB
        n4["4. BasicErrorController 的演进<br/>从 Map 到 ProblemDetail"]
    end

    subgraph s5 ["5. 异常体系重构"]
        direction TB
        n5["5. ErrorResponseException 体系<br/>让异常自带错误体"]
    end

    subgraph s6 ["6. 属性与扩展"]
        direction TB
        n6["6. 自定义 ProblemDetail<br/>与 ErrorAttributes 协作"]
    end

    subgraph s7 ["7. 全局异常处理"]
        direction TB
        n7["7. @ControllerAdvice 与<br/>ProblemDetail 的集成"]
    end

    subgraph s8 ["8. 基础设施迁移"]
        direction TB
        n8["8. Jakarta EE 迁移<br/>对错误处理的影响"]
    end

    subgraph s9 ["9. 工程实践"]
        direction TB
        n9["9. 生产事故排查专题"]
    end

    subgraph s10 ["10. 体系巩固"]
        direction TB
        n10["10. 面试高频专题"]
    end

    s1 --> s2 --> s3 --> s4 --> s5 --> s6 --> s7 --> s8 --> s9 --> s10
    s3 -.->|条件装配 Bean| s4
    s3 -.->|注册 Bean| s6
    s5 -.->|基类提供| s7

    classDef default fill:#f8f9fa,stroke:#333,stroke-width:1px,color:#333;
    classDef subgraphTitle fill:#e9ecef,stroke:#adb5bd,stroke-width:2px,color:#333,rx:5;
    class s1,s2,s3,s4,s5,s6,s7,s8,s9,s10 subgraphTitle;

架构图分层说明：

  1. 总览说明：全文 10 个模块严格遵循从抽象标准到具体实现，再到工程实践的认知路径。起点从 RFC 7807 标准和 ProblemDetail 对象结构入手（模块 1）；随后鸟瞰 Spring Boot 3.x 错误处理的全景链路（模块 2）；紧接着进入核心，深度拆解 ErrorMvcAutoConfiguration 如何利用条件装配自动搭建整个体系（模块 3）；逐层深入到核心控制器 BasicErrorController 的演进（模块 4）和新的 ErrorResponseException 异常体系（模块 5）；之后转向扩展点，讲解如何自定义 ProblemDetail 及与 ErrorAttributes 协作（模块 6），以及如何通过 @ControllerAdvice 集成（模块 7）；然后点出 Jakarta EE 迁移这一基础设施变更带来的影响（模块 8）；最后通过生产事故和面试题将理论与实践闭环（模块 9、10）。

  2. 逐模块说明：

    • 模块 1：奠定全文理论基础，阐述 ProblemDetail 的数据结构，是理解后续所有内容的前提。
    • 模块 2：给出高层抽象的全景图，让读者在进入源码细节前，先对各个组件的职责和协作关系有整体认识。
    • 模块 3：揭示整个体系的“组装车间”——ErrorMvcAutoConfiguration，重点剖析其 @Conditional 注解和 @Bean 方法，这与前文条件装配知识紧密相连。
    • 模块 4：分析核心控制器 BasicErrorController 在 3.x 版本中的具体行为变化，揭示其如何处理请求并根据内容协商返回 HTML 或 JSON 格式的 ProblemDetail。
    • 模块 5：讲解新的 ErrorResponseException 体系，展示 Spring 如何将“错误信息”的概念从响应体扩展到异常对象本身。
    • 模块 6 与 7：聚焦扩展和集成，讲解开发者如何使用既有知识（ErrorAttributes、@ControllerAdvice）来定制和增强基于 ProblemDetail 的错误响应。
    • 模块 8：从工程角度提醒升级到 3.x 必须注意的包名变更，避免常见的迁移陷阱。
    • 模块 9 与 10：作为全文的落脚点，将理论知识转化为解决实际问题和应对面试的能力。

  3. 关键结论：Spring Boot 3.x 的错误处理升级并非推倒重来，而是在原有扩展点上引入 ProblemDetail 标准，通过自动配置和内置异常实现无缝过渡。理解这一过程有助于在定制错误响应时做出精准决策。

1. RFC 7807 与 ProblemDetail：错误响应的标准化

在微服务架构和 RESTful API 盛行的今天，一个 API 可能由众多服务组成，每个服务都可能返回错误。如果没有统一的错误格式，客户端就需要为每种可能的错误格式编写解析代码，这带来了巨大的集成成本和脆弱的调用链。RFC 7807 应运而生，它定义了 application/problem+json 和 application/problem+xml 媒体类型，为 HTTP API 的错误响应提供了一个标准的、机器可读的格式。

1.1 ProblemDetail 对象的源码拆解

Spring Framework 6.x 中的 org.springframework.http.ProblemDetail 类是 RFC 7807 标准的直接实现。其核心结构如下：

// org.springframework.http.ProblemDetail
public class ProblemDetail {

    // 核心标准字段
    private URI type;       // 一个标识问题类型的URI，客户端可以通过它来获取更多信息
    private String title;   // 对人类可读的错误简短摘要
    private int status;     // HTTP状态码
    private String detail;  // 对人类可读的、针对本次错误的具体解释
    private URI instance;   // 一个标识该错误发生实例的URI，通常可以是请求路径

    // 扩展字段，存储非标准的附加信息，如traceId、业务错误码等
    private Map<String, Object> properties;

    // 构造器与静态工厂方法
    public ProblemDetail(int rawStatusCode) {
        this.status = rawStatusCode;
        this.properties = new LinkedHashMap<>();
    }

    // 用于创建常见状态的静态工厂方法
    public static ProblemDetail forStatus(int status) {
        return new ProblemDetail(status);
    }

    public static ProblemDetail forStatusAndDetail(int status, String detail) {
        ProblemDetail problemDetail = new ProblemDetail(status);
        problemDetail.setDetail(detail);
        return problemDetail;
    }

    // ... getter和setter ...
    public void setProperty(String name, Object value) {
        this.properties.put(name, value);
    }
}

源码解读：

  • type 字段 (URI)：这是一个高层次的错误分类。例如，关于“余额不足”的错误可以有一个统一的 type URI，客户端可以据此进行通用处理。如果为空，客户端可以将其视为 about:blank，表示错误是未被分类的。
  • status 字段 (int)与 title 字段 (String)：status 是原始的 HTTP 状态码。title 则是对该状态码的简短人读描述，如“Not Found”或“Bad Request”。两者结合，让开发者无需记忆状态码就能快速理解错误大类。
  • detail 字段 (String)：这是针对本次错误的、具体的、人类可读的解释。例如，同样是“验证失败”，detail 可以说明是“用户名不能为空”还是“邮箱格式错误”。
  • instance 字段 (URI)：这是一个指向具体错误实例的标识，通常可填入请求的路径，便于定位问题。
  • properties 映射 (Map<String, Object>)：这是 RFC 7807 扩展机制的核心实现。任何不属于标准字段的额外信息都应该放在这个 Map 里。这完全替代并增强了传统 ErrorAttributes 返回的 Map 结构，使得标准字段与自定义属性有了明确的界限。

1.2 与传统 ErrorAttributes 的优劣对比

在 Spring Boot 2.x 中，/error 端点返回的 JSON 格式如下（以 DefaultErrorAttributes 为例）：

{
  "timestamp": "2024-05-15T09:30:15.123+00:00",
  "status": 404,
  "error": "Not Found",
  "message": "No message available",
  "path": "/api/users/123"
}

这种格式虽然包含了关键信息，但它是一个非标准的自定义结构。客户端开发者必须查阅 Spring Boot 文档或进行多次试验，才能知道有 timestamp、error 这些字段以及其确切含义。message 字段有时会暴露敏感的异常信息，带来安全风险。

而基于 ProblemDetail 的响应则是标准的：

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "No static resource api/users/123.",
  "instance": "/api/users/123",
  "timestamp": "2024-05-15T09:30:15.123+00:00",
  "path": "/api/users/123"
}

优劣对比分析：

  1. 标准化与自描述性：application/problem+json 媒体类型本身就是一个契约。任何支持 RFC 7807 的客户端都能立刻识别 type、title 等字段的含义，无需额外文档。这是根本性优势。
  2. 错误分类与定位：type 字段提供了错误分类的 URI，可以为不同的错误场景（如验证错误、业务规则错误）定义不同的 type，实现更精细的自动化处理。instance 字段直接指向出问题的端点。
  3. 安全性与可扩展性：标准字段都是安全、概括的。详细的堆栈跟踪等技术信息默认不会出现在标准字段中，避免了信息泄露。而开发者可以通过 properties 在受控的情况下添加如 traceId、spanId 等有助于排查的信息。这比 2.x 中随意往 Map 里放字段要规范得多。
  4. 可发现性：type 字段可以是一个真实的 URL，指向该错误类型的完整文档，指导客户端开发者如何解决问题。

ProblemDetail 对象结构图：

classDiagram
    class ProblemDetail {
        -URI type
        -String title
        -int status
        -String detail
        -URI instance
        -Map properties
        +static forStatus(int status) ProblemDetail
        +static forStatusAndDetail(int status, String detail) ProblemDetail
        +setProperty(String name, Object value) void
        getProperties() Map
    }

    note for ProblemDetail "RFC 7807标准的核心实现"

图表说明：

  • 图表主旨概括：此图展示了 ProblemDetail 类的核心结构，包括其所有字段和方法。它直观地反映了 RFC 7807 标准如何映射为 Java 对象。
  • 逐层/逐元素分解：ProblemDetail 类包含了 RFC 7807 定义的所有成员变量：用于错误分类的 type，简短描述的 title，HTTP 状态码 status，详细解释的 detail，以及指向错误实例的 instance。properties 映射是扩展入口。forStatus 和 forStatusAndDetail 工厂方法提供了便捷的对象创建方式。
  • 设计原理映射：这是一个典型的数据传输对象（DTO）模式，专门用于在不同层（控制器层、异常处理层、消息转换层）之间传输错误信息。其设计兼具不可变性（通过构造器初始化关键属性，只提供 getter 和有限的 setter）和可扩展性（通过 properties Map），符合“封装变化”的原则。
  • 工程联系与关键结论：ProblemDetail 是 Spring Boot 3.x 错误响应体系的基石对象。理解其字段含义是后续深入分析控制器、异常处理器和消息转换器如何协作的基础。 开发者要明确区分哪些信息应放在标准字段，哪些应放入 properties 中，这是构建专业 API 的关键。

2. Spring Boot 3.x 错误处理全景

在深入源码之前，我们需要对 Spring Boot 3.x 错误处理的全貌有一个概览。整个流程是经典 Servlet 错误处理机制与 Spring 自动配置、核心控制器以及消息转换器协作的结果。

2.1 核心组件鸟瞰

Spring Boot 错误处理主要涉及以下几个核心接口和类：

  • jakarta.servlet.ErrorController：替代了旧的 org.springframework.boot.web.servlet.error.ErrorController。该接口定义了处理 /error 路径的控制器，是错误处理的入口。
  • org.springframework.boot.web.servlet.error.ErrorAttributes：负责从请求属性中提取和格式化错误信息。3.x 中新增了 getErrorAttributes(WebRequest, ErrorAttributeOptions) 方法，并且其实现 DefaultErrorAttributes 已演变为同时支持传统 Map 和 ProblemDetail 模式。
  • org.springframework.boot.autoconfigure.web.servlet.error.ErrorMvcAutoConfiguration：核心自动配置类，负责将上述组件像拼图一样组装起来。
  • org.springframework.boot.web.servlet.error.BasicErrorController：ErrorController 的默认实现，同时处理 HTML 和 JSON 类型的错误响应。

2.2 请求到达 /error 的路径

  1. 容器捕获异常/错误：当 Spring MVC 处理请求抛出异常，或者 Filter 链中发生错误，或者请求被容器判定为非法的（如 404），Servlet 容器（Tomcat/Jetty）会拦截这个错误的请求。
  2. 容器转发请求：容器根据部署描述符或编程配置，将请求转发到配置好的错误页（error page）。Spring Boot 默认将错误页配置为 /error。
  3. DispatcherServlet 再次接手：由于 /error 也是一个合法的路径，这个转发后的请求会再次进入 DispatcherServlet，并最终被映射到实现了 ErrorController 接口的控制器上，即 BasicErrorController。
  4. BasicErrorController 处理：BasicErrorController 接到请求后，会调用 ErrorAttributes 来获取当前请求的错误信息，然后根据请求的 Accept 头进行内容协商，决定返回 HTML（ModelAndView）还是返回 JSON（ResponseEntity，在 3.x 中是 ResponseEntity<ProblemDetail>）。

2.3 与传统 Spring Boot 2.x 的差异概述

特性Spring Boot 2.x (基于 Spring Framework 5.x)Spring Boot 3.x (基于 Spring Framework 6.x)
默认 JSON 响应体自定义 Map 结构 (timestamp, status, error, message, path)符合 RFC 7807 的 ProblemDetail 对象 (Content-Type: application/problem+json)
核心响应对象Maporg.springframework.http.ProblemDetail
ErrorAttributes 接口org.springframework.boot.web.servlet.error.ErrorAttributesorg.springframework.boot.web.servlet.error.ErrorAttributes (增加了新方法)
Servlet 包javax.servlet.*jakarta.servlet.*
异常信息载体主要存在被转发的请求属性中既可存在于请求属性中，也可通过 ErrorResponseException 直接由异常携带
内容协商通过 produces 或 Accept 头手动判断同样通过 Accept 头，但结合了 HttpMessageConverter 实现更标准的协商

关键结论：Spring Boot 3.x 的错误处理是在保持核心架构（Servlet 转发、/error 端点）不变的前提下，对响应体的格式和异常信息的传递方式进行了标准化升级。这种演进方式保证了最大程度的向下兼容，同时引入了现代 API 设计的最佳实践。

3. ErrorMvcAutoConfiguration：自动配置拆解

ErrorMvcAutoConfiguration 是整个错误处理体系的组装器。它利用 Spring Boot 强大的条件装配机制，根据类路径、已注册的 Bean 等条件，动态地向容器中注册错误处理所需的各个组件。

3.1 条件装配与 Bean 注册分析

// org.springframework.boot.autoconfigure.web.servlet.error.ErrorMvcAutoConfiguration

@AutoConfiguration
@ConditionalOnWebApplication(type = Type.SERVLET) // 1. 仅在Servlet Web环境下生效
@ConditionalOnClass({ Servlet.class, DispatcherServlet.class }) // 2. 必须有Servlet相关类
@EnableConfigurationProperties({ ServerProperties.class, WebMvcProperties.class })
public class ErrorMvcAutoConfiguration {

    private final ServerProperties serverProperties;

    // 3. ErrorAttributes Bean: 当容器中没有ErrorAttributes时，注册默认实现
    @Bean
    @ConditionalOnMissingBean(ErrorAttributes.class)
    public DefaultErrorAttributes errorAttributes() {
        return new DefaultErrorAttributes();
    }

    // 4. BasicErrorController Bean: 当容器中没有ErrorController时注册
    @Bean
    @ConditionalOnMissingBean(ErrorController.class)
    public BasicErrorController basicErrorController(ErrorAttributes errorAttributes,
            ObjectProvider<ErrorViewResolver> errorViewResolvers) {
        return new BasicErrorController(errorAttributes, this.serverProperties.getError(),
                errorViewResolvers.orderedStream().toList());
    }

    // 5. ... ErrorPageCustomizer, WhateLabelErrorViewResolver 等其他Bean ...

    // 6. 内部类：为ProblemDetail响应提供定制的ErrorAttributes
    @Configuration(proxyBeanMethods = false)
    static class ProblemDetailsErrorHandlingConfiguration {

        @Bean
        @ConditionalOnMissingBean(ErrorAttributes.class)
        ProblemDetailsErrorAttributes errorAttributes() {
            return new ProblemDetailsErrorAttributes();
        }
    }
    // ... 其他内部配置类
}

源码解读与设计剖析：

  1. @AutoConfiguration：声明这是一个自动配置类，会被 Spring Boot 的 spring.factories/org.springframework.boot.autoconfigure.AutoConfiguration.imports 机制加载。
  2. @ConditionalOnWebApplication(type = Type.SERVLET) 和 @ConditionalOnClass：这是条件装配的关键应用。它确保了此配置只在传统的 Servlet 容器 Web 应用中生效，避免了在 WebFlux 等反应式环境中误注册。这与前文讲解的条件装配原理一脉相承，通过限定配置的生效环境，保证了框架的清晰边界和精干。
  3. DefaultErrorAttributes 与 @ConditionalOnMissingBean：@ConditionalOnMissingBean 提供了一种优雅的扩展覆盖机制。如果开发者在自己的配置类中定义了一个 ErrorAttributes Bean，那么 Spring Boot 提供的 DefaultErrorAttributes 就不会被注册。这是 Spring Boot “约定优于配置，但允许覆盖”哲学的体现。
  4. BasicErrorController 的注册：同样用 @ConditionalOnMissingBean 提供了扩展和覆盖的出口。BasicErrorController 的构造器注入了 ErrorAttributes 和 ErrorViewResolver 列表，展示了依赖注入在组装核心组件时的作用。
  5. ProblemDetailsErrorAttributes：这是一个关键的内部类，它存在于 ProblemDetailsErrorHandlingConfiguration 配置类中。这个配置类本身可能受其他更细粒度的条件限制（例如类路径上存在 HttpClientErrorException 等 3.0 新类）。ProblemDetailsErrorAttributes 是 DefaultErrorAttributes 的一个子类，专门用来更好地填充 ProblemDetail 的 properties 字段。

3.2 ErrorMvcAutoConfiguration 自动配置装配流程图

flowchart TD
    Start[Spring Boot 应用启动] --> EvalCondition{评估 ErrorMvcAutoConfiguration<br/>配置类的条件}
    
    subgraph "条件装配检查"
        EvalCondition -->|"@ConditionalOnWebApplication(SERVLET)"| Check1[检查是否为Servlet环境]
        EvalCondition -->|"@ConditionalOnClass(...)"| Check2[检查类路径是否有Servlet API]
        Check1 & Check2 -->|条件全部满足| Assemble[开始装配Bean]
        Check1 & Check2 -->|任一条件不满足| Skip[跳过 ErrorMvcAutoConfiguration]
    end
    
    Assemble --> Bean_ErrorAttributes{容器中存在<br/>ErrorAttributes Bean?}
    Bean_ErrorAttributes -->|否| RegDefaultEA[注册 DefaultErrorAttributes]
    Bean_ErrorAttributes -->|是| SkipDefaultEA[跳过注册]
    
    Assemble --> Bean_ErrorController{容器中存在<br/>ErrorController Bean?}
    Bean_ErrorController -->|否| RegBasicEC[注册 BasicErrorController<br/>注入 ErrorAttributes]
    Bean_ErrorController -->|是| SkipBasicEC[跳过注册]
    
    Assemble --> Bean_ProblemDetailEA{条件成立且<br/>容器中无 ErrorAttributes?}
    Bean_ProblemDetailEA -->|是| RegProblemDetailEA[注册 ProblemDetailsErrorAttributes]
    Bean_ProblemDetailEA -->|否| SkipProblemDetailEA[跳过注册]

    RegDefaultEA & RegBasicEC & RegProblemDetailEA --> End[错误处理体系就绪]

图表说明：

  • 图表主旨概括：本图展示了 ErrorMvcAutoConfiguration 在应用启动时，如何通过一系列条件判断来决定注册哪些错误处理相关的 Bean。
  • 逐层/逐元素分解：流程从应用启动开始，进入 ErrorMvcAutoConfiguration 的评估。首先是两个类级别的 @Conditional 判断，确定是否为 Servlet 环境且有所需的类。通过后，进入方法级别的 Bean 注册。这里以 ErrorAttributes 和 ErrorController 为例，展示了 @ConditionalOnMissingBean 的决策逻辑：如果用户自定义了，就用用户的；否则，使用 Spring Boot 提供的默认实现。ProblemDetailsErrorAttributes 的注册也遵循同样的逻辑，但其生效还需要额外的内部配置类条件。
  • 设计原理映射：这是典型的模板方法和策略模式在配置层的体现。自动配置类定义了一个“组装模板”，具体的“组装策略”（即使用哪个 Bean）由 @Conditional 注解和 @ConditionalOnMissingBean 在运行时动态决定。
  • 工程联系与关键结论：@ConditionalOnMissingBean 是扩展和覆盖 Spring Boot 错误处理行为的最核心入口。 开发者如果想让自己的 ErrorAttributes 或 ErrorController 生效，只需定义一个继承自相应接口的 Bean，Spring Boot 的自动配置就会自动退让。理解这一点，可以避免很多“为什么我的配置没生效”的生产问题。

4. BasicErrorController 的演进：从 Map 到 ProblemDetail

BasicErrorController 实现了 ErrorController 和 RequestMapping 注解，是 /error 端点的默认“服务员”。在 3.x 中，它的核心逻辑依然是内容协商，但产出物发生了根本变化。

4.1 源码核心逻辑解析

// org.springframework.boot.autoconfigure.web.servlet.error.BasicErrorController

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

    private final ErrorProperties errorProperties;

    @RequestMapping(produces = MediaType.TEXT_HTML_VALUE) // 1. 处理HTML请求
    public ModelAndView errorHtml(HttpServletRequest request, HttpServletResponse response) {
        HttpStatus status = getStatus(request);
        Map<String, Object> model = Collections.unmodifiableMap(
                getErrorAttributes(request, getErrorAttributeOptions(request, MediaType.TEXT_HTML)));
        response.setStatus(status.value());
        ModelAndView modelAndView = resolveErrorView(request, response, status, model);
        return (modelAndView != null) ? modelAndView : new ModelAndView("error", model);
    }

    @RequestMapping // 2. 处理其他非HTML请求（主要是JSON）
    public ResponseEntity<?> error(HttpServletRequest request) {
        HttpStatus status = getStatus(request);
        if (status == HttpStatus.NO_CONTENT) {
            return new ResponseEntity<>(status);
        }
        // 3. 这里是关键！getErrorAttributes 返回的 Map 会被用来构建 ProblemDetail
        Map<String, Object> body = getErrorAttributes(request, getErrorAttributeOptions(request, MediaType.ALL));
        // 4. 构建 ProblemDetail 对象，状态码源自原始请求错误
        ProblemDetail problemDetail = ProblemDetail.forStatus(status);
        // 5. 将ErrorAttributes中的属性复制到ProblemDetail的properties中
        body.forEach((key, value) -> problemDetail.setProperty(key, value));
        // 6. 返回 ResponseEntity<ProblemDetail>
        return new ResponseEntity<>(problemDetail, null, status);
    }
    // ...
}

源码解读：

  1. 内容协商分支：produces = MediaType.TEXT_HTML_VALUE 使得 errorHtml 方法专用于处理浏览器等请求 HTML 的客户端。非 HTML 请求（Accept 头包含 application/json, */* 等）会落入 error 方法。
  2. 错误状态获取：getStatus(request) 方法从其父类 AbstractErrorController 继承而来，它从 jakarta.servlet 定义的请求属性（如 jakarta.servlet.error.status_code）中提取出 HTTP 状态码。
  3. error 方法的核心变化：这里是与 2.x 最大的不同点。在 2.x 中，这一行是 return new ResponseEntity<>(body, status)，直接将 Map<String, Object> 作为响应体返回。而在 3.x 中，虽然依然调用了 getErrorAttributes 获取 Map，但其目的不是直接返回此 Map，而是将其作为源数据，构建出一个全新的 ProblemDetail 对象。
  4. 精心构建 ProblemDetail：ProblemDetail.forStatus(status) 创建了一个状态码正确的实例。之后的 body.forEach(...) 循环，将 getErrorAttributes 返回的 Map 中的所有键值对，都作为扩展属性，通过 setProperty 方法添加到了 ProblemDetail 的 properties 映射中。
  5. 响应返回：最终返回的是一个 ResponseEntity<ProblemDetail>。当 Spring MVC 的 HttpMessageConverter 处理这个返回值时，会发现 ProblemDetail 类型，并将其序列化为 application/problem+json 格式。

4.2 BasicErrorController 处理错误请求序列图

sequenceDiagram
    participant Client as 客户端
    participant Container as Servlet容器(Tomcat)
    participant DS as DispatcherServlet
    participant BEC as BasicErrorController
    participant EA as ErrorAttributes
    participant HMC as HttpMessageConverter

    Client->>+Container: GET /api/nonexistent
    Container->>+DS: 转发请求
    DS-->>DS: 无匹配Handler，抛异常/返回404
    DS-->>-Container: 通知处理失败(status=404)
    Container->>Container: 捕获错误，获取错误页路径 "/error"
    Container->>+DS: FORWARD /error，附带错误属性（status_code, message, etc.）
    
    DS->>+BEC: 请求映射到 BasicErrorController
    alt 请求头 Accept: text/html
        BEC->>+EA: getErrorAttributes(request, HTML options)
        EA-->>-BEC: Map of error details
        BEC->>BEC: 构造 ModelAndView，解析错误视图
        BEC-->>DS: ModelAndView (HTML页面)
    else 请求头 Accept: application/json 或 */*
        BEC->>+EA: getErrorAttributes(request, ALL options)
        EA-->>-BEC: Map of error details
        BEC->>BEC: 组装 ProblemDetail(status=404)，将Map属性填入properties
        BEC-->>DS: ResponseEntity<ProblemDetail>
        DS->>+HMC: 选择合适的HttpMessageConverter
        HMC-->>-DS: 将ProblemDetail序列化为JSON (application/problem+json)
    end
    DS-->>-Client: HTTP/1.1 404，响应体为HTML或JSON

图表解读：

  • 图表主旨概括：本序列图详细描绘了一个 404 请求从客户端发出，经过容器、DispatcherServlet，最终由 BasicErrorController 处理，并根据内容协商返回 HTML 或 Problem Detail JSON 的完整时序。
  • 逐层/逐元素分解：图中共有 6 个生命线。流程清晰地分为两个阶段：1）原始请求失败并被容器捕获，容器将错误信息设置为请求属性后转发到 /error；2）BasicErrorController 处理 /error 请求，调用 ErrorAttributes 聚合错误信息，并根据 Accept 请求头进入不同分支。JSON 分支明确展示了如何将 ErrorAttributes 的 Map 填充到 ProblemDetail 的 properties 中，并最终由 HttpMessageConverter 序列化。
  • 设计原理映射：BasicErrorController 的方法选择体现了策略模式，根据内容协商结果选择不同的处理策略（errorHtml 或 error）。而 error 方法内部则展示了适配器模式的思想，它将旧的 ErrorAttributes（Map 接口）适配到了新的 ProblemDetail（标准对象）上。
  • 工程联系与关键结论：BasicErrorController 的 error 方法是理解传统机制与 3.0 新标准如何桥接的关键。 它明确告诉我们，旧的 ErrorAttributes 并没有被废弃，它的产出成为了新标准的“扩展属性”来源。这意味着你之前所有的 ErrorAttributes 自定义，默认情况下都会通过 properties 在 ProblemDetail 响应中继续生效。

5. ErrorResponseException 体系：让异常自带错误体

除了通过 Servlet 容器转发到 /error，Spring MVC 的 @ExceptionHandler 是另一大错误处理支柱。在 3.x 中，Spring 引入了一个全新的异常体系，其核心是 ErrorResponseException，它允许异常实例直接携带一个 ProblemDetail 对象作为响应体。

5.1 ErrorResponseException 基类与体系

// org.springframework.web.ErrorResponseException
public class ErrorResponseException extends RuntimeException implements ErrorResponse {

    private final HttpStatusCode status;
    private final ProblemDetail body;
    private final String message;
    // ...

    // 构造时即可传入 ProblemDetail
    public ErrorResponseException(HttpStatusCode status, ProblemDetail body) {
        this(status, body, null);
    }

    // 从ErrorResponse接口实现，直接返回ProblemDetail
    @Override
    public ProblemDetail getBody() {
        return this.body;
    }

    @Override
    public HttpStatusCode getStatusCode() {
        return this.status;
    }
    // ...
}

ErrorResponseException 的引入，将“异常”和“错误响应体”这两个概念紧密地绑定在了一起。之前，开发者需要在 @ExceptionHandler 方法中手动构建 ResponseEntity 和响应体；而现在，一个继承了 ErrorResponseException 的异常，其自身就包含了生成最终 HTTP 响应所需的全部信息（状态码、响应头、响应体）。

Spring Framework 6.x 为此提供了大量内置子类，例如：

  • HttpRequestMethodNotSupportedException (Servlet 层，实现 ErrorResponse)
  • MethodArgumentNotValidException 不再直接实现 ErrorResponse，但其处理方式在 ResponseEntityExceptionHandler 中被导向 ProblemDetail。

5.2 体系优势与应用

这个体系极大地简化了全局异常处理。设想一个场景，我们在服务层抛出一个业务异常。

传统 2.x 方式：

// 自定义异常
public class OrderNotFoundException extends RuntimeException { ... }

// 在@ControllerAdvice中
@ExceptionHandler(OrderNotFoundException.class)
public ResponseEntity<?> handleOrderNotFound(OrderNotFoundException ex) {
    Map<String, Object> body = new LinkedHashMap<>();
    body.put("timestamp", ...);
    body.put("status", 404);
    body.put("error", "Not Found");
    body.put("message", ex.getMessage());
    // ... 反复的手动构建
    return new ResponseEntity<>(body, HttpStatus.NOT_FOUND);
}

3.x 方式：

// 1. 自定义异常，继承ErrorResponseException
public class OrderNotFoundException extends ErrorResponseException {
    public OrderNotFoundException(Long orderId) {
        super(HttpStatus.NOT_FOUND, ProblemDetail.forStatusAndDetail(
                HttpStatus.NOT_FOUND, "Order with id " + orderId + " not found"));
        // 可以继续添加扩展信息
        this.getBody().setProperty("orderId", orderId);
        this.getBody().setType(URI.create("https://api.example.com/errors/order-not-found"));
    }
}

// 2. 全局异常处理器变得极其简洁
@ControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(OrderNotFoundException.class)
    ResponseEntity<ProblemDetail> handleOrderNotFound(OrderNotFoundException ex) {
        // 直接返回异常中的ProblemDetail，状态码、消息均已完备
        return new ResponseEntity<>(ex.getBody(), ex.getHeaders(), ex.getStatusCode());
    }
}

设计优势：

  • 职责内聚：错误表示（ProblemDetail）与错误本身（异常）放在一起，符合高内聚原则。
  • 减少样板代码：@ExceptionHandler 不再需要重复地、手动地构建 ResponseEntity 和响应体 Map，代码更简洁、更不易出错。
  • 类型安全：ProblemDetail 是一个强类型对象，相比松散的 Map，在组件间传递时更安全，编译器可以检查出更多错误。

6. 自定义 ProblemDetail 与 ErrorAttributes 协作

虽然 ProblemDetail 是标准的，但业务系统总需要添加自定义信息。理解 ErrorAttributes 与 ProblemDetail 是如何协作的，对于安全、有效地扩展错误响应至关重要。

6.1 DefaultErrorAttributes 的演进与适配

在 3.x 中，DefaultErrorAttributes 依然负责从请求中提取错误信息，但它现在同时服务于 HTML 视图和 ProblemDetail 构建。

// org.springframework.boot.web.servlet.error.DefaultErrorAttributes

@Override
public Map<String, Object> getErrorAttributes(WebRequest webRequest, ErrorAttributeOptions options) {
    Map<String, Object> errorAttributes = this.getErrorAttributes(webRequest, options.isIncluded(Include.STACK_TRACE));
    // 对于 ProblemDetail，这些属性最终会成为其 properties 的一部分
    if (!options.isIncluded(Include.EXCEPTION_CLASS)) {
        errorAttributes.remove("exception");
    }
    // ...
    return errorAttributes;
}

当 BasicErrorController.error() 方法调用 getErrorAttributes 时，拿到的 Map 中包含了传统的 timestamp, status, error, message, path 等字段。在 3.x 中，这些字段会被无差别地通过 forEach 循环设置到 ProblemDetail 的 properties 中。

6.2 ErrorAttributes 与 ProblemDetail 属性合并的流程

flowchart TD
    Start[BasicErrorController.error 方法开始] --> GetStatus[从请求属性获取 HttpStatus]
    GetStatus --> InitPD[新建 ProblemDetail.forStatus]
    InitPD --> SetStd[设置 ProblemDetail 标准字段<br/>如 instance=请求路径]
    
    SetStd --> CallEA[调用 ErrorAttributes.getErrorAttributes]
    CallEA --> GetMap[获得包含传统属性的 Map<br/>如 timestamp, message, path 等]
    
    GetMap --> LoopStart[遍历 Map 中的每个 Entry]
    LoopStart --> SetProp{调用 problemDetail.setProperty}
    SetProp -->|Entry 进入 properties| Merge[合并/覆盖字段]
    
    Merge --> LoopEnd{Map遍历结束?}
    LoopEnd -->|否| LoopStart
    LoopEnd -->|是| BuildResponse[构建 ResponseEntity<ProblemDetail>]
    
    BuildResponse --> End[由 HttpMessageConverter 序列化并返回]

图表解读：

  • 图表主旨概括：此流程图清晰展示了 BasicErrorController 如何将旧的 ErrorAttributes 风格的错误信息，映射并合并到新的 ProblemDetail 对象中。
  • 逐层/逐元素分解：流程开始于创建一个空的 ProblemDetail 对象（仅设置了状态码）。然后调用 ErrorAttributes 获取传统的错误信息 Map。接着进入一个关键的循环，将 Map 中的每一个键值对都通过 setProperty 方法“注入”到 ProblemDetail 的 properties 中。例如，Map 中的 "path" -> "/api/test" 就会变成 ProblemDetail 的一个扩展属性。
  • 设计原理映射：这是一种典型的数据迁移/适配模式。它确保了新旧两种错误表示机制可以并行工作。ErrorAttributes 关心的是“从哪获取原始错误数据”（请求属性、异常），而 ProblemDetail 关心的是“以何种标准格式呈现数据”。两者的职责通过这个映射过程被清晰地分离。
  • 工程联系与关键结论：这种协作方式意味着，如果你有一个完全自定义的 ErrorAttributes 实现，它的输出会被自动吸收为 ProblemDetail 的 properties。但同时也要警惕，如果自定义的 Map 中的键与标准字段重名（如 detail），它可能会意外地通过 setProperty 覆盖掉某些内部的表示（尽管 ProblemDetail 的 setter 对标准字段和 properties 是分开存储的，这里说的是语义上的混淆）。 因此，在设计自定义 ErrorAttributes 时，应避免使用 RFC 7807 的标准字段名作为键。

6.3 实现自定义扩展性

示例：添加 traceId 和业务错误码

@Component
public class CustomErrorAttributes extends DefaultErrorAttributes {

    private static final String TRACE_ID_KEY = "traceId";
    private static final String BIZ_CODE_KEY = "bizCode";

    @Override
    public Map<String, Object> getErrorAttributes(WebRequest webRequest, ErrorAttributeOptions options) {
        Map<String, Object> errorAttributes = super.getErrorAttributes(webRequest, options);

        // 从请求头或MDC中获取traceId
        String traceId = (String) webRequest.getAttribute(TRACE_ID_KEY, RequestAttributes.SCOPE_REQUEST);
        if (traceId == null) {
            traceId = UUID.randomUUID().toString();
        }
        errorAttributes.put(TRACE_ID_KEY, traceId);

        // 添加模拟的业务错误码
        Throwable error = getError(webRequest);
        if (error instanceof BusinessException bizEx) {
            errorAttributes.put(BIZ_CODE_KEY, bizEx.getBizCode());
        }

        return errorAttributes;
    }
}

// 最终在ProblemDetail的JSON响应中，会出现：
// {
//   "type": "about:blank",
//   "title": "Bad Request",
//   "status": 400,
//   ...
//   "traceId": "a1b2c3d4...",
//   "bizCode": "ORDER_VALIDATION_ERR"
// }

7. @ControllerAdvice 与 ProblemDetail 的集成

@ControllerAdvice 结合 @ExceptionHandler 是实现全局异常处理的强大工具。在 3.x 中，ResponseEntityExceptionHandler 已经全面升级，其内部方法直接构建并返回 ProblemDetail，为我们提供了一个标准的使用范本。

7.1 ResponseEntityExceptionHandler 的升级

// org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler

@ExceptionHandler({
    HttpRequestMethodNotSupportedException.class, // 实现了ErrorResponse
    MethodArgumentNotValidException.class,       // 非ErrorResponse类
    ...
})
public final ResponseEntity<Object> handleException(Exception ex, WebRequest request) throws Exception {
    // 委派给各个具体的处理方法
    if (ex instanceof HttpRequestMethodNotSupportedException subEx) {
        return handleHttpRequestMethodNotSupported(subEx, null, null, request);
    }
    // ...
    else if (ex instanceof MethodArgumentNotValidException subEx) {
        return handleMethodArgumentNotValid(subEx, null, null, request);
    }
    // ...
}

// 处理方法直接构建并返回包含ProblemDetail的ResponseEntity
protected ResponseEntity<Object> handleHttpRequestMethodNotSupported(
        HttpRequestMethodNotSupportedException ex, HttpHeaders headers, HttpStatusCode status, WebRequest request) {

    ProblemDetail body = createProblemDetail(ex, status, "Method '" + ex.getMethod() + "' is not supported.",
            null, null, request);
    // 自定义detail信息，比2.x更清晰
    return handleExceptionInternal(ex, body, headers, status, request);
}

protected ProblemDetail createProblemDetail(Exception ex, HttpStatusCode status,
        String defaultDetail, String detailMessageCode, Object[] detailMessageArguments, WebRequest request) {

    ProblemDetail problemDetail = ProblemDetail.forStatusAndDetail(status, defaultDetail);
    // 可以设置type、title等
    return problemDetail;
}

源码解读：ResponseEntityExceptionHandler 不再输出松散的 Map，转而输出严格的 ProblemDetail。在 handleHttpRequestMethodNotSupported 方法中，它清晰地将“不支持的 HTTP 方法”这一消息设置到了 ProblemDetail 的 detail 字段。这种内置的处理方式，确保了所有继承自 ResponseEntityExceptionHandler 的全局异常处理器，都能自动获得返回标准化错误的能力。

7.2 全局异常处理器与 ProblemDetail 集成序列图

sequenceDiagram
    participant Client
    participant DS as DispatcherServlet
    participant Controller
    participant GHE as GlobalExceptionHandler<br/>(@ControllerAdvice)
    participant HMC as HttpMessageConverter

    Client->>+DS: POST /api/orders (Invalid Data)
    DS->>+Controller: 调用控制器方法
    Controller->>Controller: 参数校验失败，抛出 MethodArgumentNotValidException
    Controller-->>-DS: 异常抛出
    DS->>+GHE: 查找能处理该异常的 @ExceptionHandler
    GHE->>+GHE: handleMethodArgumentNotValid(ex)
    GHE->>GHE: createProblemDetail(status, detail)
    Note over GHE: 构建 ProblemDetail<br/>type, title, status, detail
    GHE-->>-DS: 返回 ResponseEntity<ProblemDetail>
    DS->>+HMC: 选择 HttpMessageConverter
    HMC-->>-DS: 将 ProblemDetail 序列化为 JSON
    DS-->>-Client: HTTP/1.1 400 Bad Request<br/>Content-Type: application/problem+json

图表解读：

  • 图表主旨概括：该序列图展示了一个控制器抛出 MethodArgumentNotValidException 后，由扩展自 ResponseEntityExceptionHandler 的全局异常处理器拦截并处理，最终返回 ProblemDetail 响应的全过程。
  • 逐层/逐元素分解：请求进入 DispatcherServlet 并到达控制器。控制器在参数校验阶段失败，抛出异常。DispatcherServlet 捕获异常后，遍历所有 @ControllerAdvice 类，找到能处理该异常的 @ExceptionHandler 方法。我们自定义的 GlobalExceptionHandler 继承自 ResponseEntityExceptionHandler，它的 handleMethodArgumentNotValid 方法被调用。该方法内部调用基类的辅助方法，快速创建了一个 ProblemDetail 对象，并返回 ResponseEntity<ProblemDetail>。最后，HttpMessageConverter 介入，将这个对象序列化为 application/problem+json。
  • 设计原理映射：这里体现了模板方法模式的威力。ResponseEntityExceptionHandler 类定义了处理异常的骨架，我们的自定义处理器只需继承它，重写我们关心的方法（比如 handleMethodArgumentNotValid 来自定义 detail 信息），而底层的 ProblemDetail 创建和 ResponseEntity 包装逻辑则由基类完成。这是一种非常经典的框架设计，将变与不变分离。
  • 工程联系与关键结论：在 Spring Boot 3.x 中，构建全局异常处理的最佳实践是继承 ResponseEntityExceptionHandler，并利用其提供的 createProblemDetail 等方法构建标准化错误响应。这不仅省去了手动构建对象的麻烦，还保证了所有由 MVC 内部抛出的常见异常（如参数校验失败、方法不支持）都能被自动转换为符合标准的 Problem Detail 响应。

8. Jakarta EE 迁移对错误处理的影响

从 Spring Boot 2.x 到 3.x，底层 Java EE 规范的迁移从 javax 到 jakarta 是一个影响深远的变更。错误处理体系直接依赖 Servlet API，因此也受到了直接影响。

8.1 包名变更与核心接口调整

最核心的变化是 ErrorController 和 ErrorAttributes 接口所在包的迁移：

  • org.springframework.boot.web.servlet.error.ErrorController 被标记为 @Deprecated，新的核心接口是 jakarta.servlet.ErrorController。
  • org.springframework.boot.web.servlet.error.ErrorAttributes 接口本身还在 boot 包里，但其方法签名中用到的类（如 WebRequest）可能未变，但其从请求属性中提取错误的常量名称发生了变化。

旧的 javax.servlet.error.status_code 现在变为了 jakarta.servlet.error.status_code，其他如 exception, message 等请求属性名称也做了相应的包名变更。Spring Boot 的 AbstractErrorController 和 DefaultErrorAttributes 内部已经适配了这些新的常量。

8.2 对开发者自定义扩展的影响

如果一个项目从 Spring Boot 2.x 升级到 3.x，并且有自定义的组件：

// 2.x 中的自定义实现
import org.springframework.boot.web.servlet.error.ErrorController;
import javax.servlet.http.HttpServletRequest;

@Component
public class CustomErrorController implements ErrorController {
    @Override
    public String getErrorPath() {
        return "/custom-error";
    }
    // ...
}

在 3.x 中，上述代码会编译失败，必须进行如下修改：

  1. 实现新接口：改为实现 jakarta.servlet.ErrorController。
  2. 移除 getErrorPath() ：新接口中不再有此方法，该路径配置转移到了 ServerProperties 中。
  3. 更新 @RequestMapping ：需要在一个 @Controller 或 @RestController 中自行处理 /custom-error 路径的逻辑。

关键结论：Jakarta EE 迁移对错误处理的定制开发是一个“硬阻断”。任何直接依赖了旧 javax.servlet 的错误处理相关代码，在升级到 3.x 时都必须修改。Spring Boot 通过提供新的 jakarta.servlet.ErrorController 接口，并与新的 ErrorMvcAutoConfiguration 配合，完成了这次底层基础设施的平滑过渡。

9. 生产事故排查专题

理论最终要服务于实践。以下是两个因对 Spring Boot 3.x 错误处理新机制理解不足而可能导致的生产事故。

9.1 事故一：自定义 ErrorAttributes 未生效，错误响应缺少关键字段

  • 现象：为满足可观测性要求，开发者自定义了 ErrorAttributes，意图为所有 API 错误响应添加 traceId 和 spanId 字段。代码部署后，发现在 HTML 错误页面（通过 ModelAndView）中这些字段有值，但在返回给客户端的 application/problem+json 响应中一直缺失。
  • 排查思路：
    1. 确认自定义的 ErrorAttributes Bean 是否被正确注册。通过 Spring Boot Actuator 的 /actuator/beans 端点检查，发现容器中确实有自定义的 Bean，且类型是 CustomErrorAttributes。
    2. 在自定义 ErrorAttributes 的 getErrorAttributes 方法上打断点，调用 API 产生错误，发现方法被成功调用，并且返回的 Map 中有 traceId 和 spanId。
    3. 既然如此，为何最终的 JSON 响应中没有？问题转移到序列化阶段。怀疑是返回的 ProblemDetail 对象不包含这些属性或其 getProperties 方法没有输出它们。
    4. 在 BasicErrorController.error 方法上打断点，发现 body.forEach(...) 正常执行，problemDetail.getProperties() 中也确实有对应的键值对。
    5. 关键点：检查 JSON 序列化配置。项目中为了“序列化优化”，自定义了 ObjectMapper，并配置了 SerializationInclusion(NON_NULL)。同时不经意间还设置了 @JsonIgnoreProperties 或在 ProblemDetail 的相关 getter 上加了某些注解。但经过逐步排查，发现问题出在 ProblemDetail 序列化使用的是 ProblemDetailJacksonXmlSerializer 注册的特定序列化器，可能与全局的 ObjectMapper 配置有冲突，或者 properties Map 中的值存在 null 导致 NON_NULL 策略将其过滤掉。
  • 根因：经过深入排查，是项目组一个通用的 JSON 配置类对 ObjectMapper 做了全局设置 mapper.setSerializationInclusion(JsonInclude.Include.NON_DEFAULT)。ProblemDetail 的 properties 默认是一个空 LinkedHashMap，其“默认值”就是一个空 Map。当 properties 中填充了 traceId 等字段后，Map 不再是空的，但 NON_DEFAULT 策略可能在某些序列化库版本中对 Map 类型处理有特殊行为，导致某些情况下（如只有少量属性）输出被意外抑制。
  • 解决：将全局的 mapper.setSerializationInclusion(JsonInclude.Include.NON_DEFAULT) 改为仅对特定业务 DTO 生效的局部配置，或注册一个 ProblemDetail 专用的序列化器，确保其 properties 字段总能被正确序列化。更好的实践是：不要对全局 ObjectMapper 做过于宽泛的设定，除非你完全理解它会影响哪些框架类的序列化。
  • 最佳实践：
    1. 区分标准字段与扩展属性：明确 traceId 这类信息应放入 properties。
    2. 谨慎定制 ObjectMapper：全局的 ObjectMapper 定制可能影响 Spring 框架内部的序列化和反序列化行为。优先使用 @JsonComponent 或 Jackson2ObjectMapperBuilderCustomizer 进行精准定制。
    3. 完备测试：编写集成测试，不仅调用 API，还要断言返回的 ProblemDetail JSON 中确实包含了自定义的 properties 字段。

9.2 事故二：部分 API 的错误响应变成了 200 OK

  • 现象：在迁移某批旧接口到 Spring Boot 3.x 后，监控系统发现，当接口本应返回 4xx 或 5xx 错误时，部分接口的 HTTP 状态码错误地变成了 200 OK，尽管响应体内容是符合 ProblemDetail 格式的。
  • 排查思路：
    1. 分析现象：ProblemDetail 响应体存在，说明错误被正确处理且生成了响应。问题在状态码上。
    2. 检查控制器代码：这些出问题的接口都返回 ResponseEntity，并且在业务逻辑中使用 @ExceptionHandler 进行了处理。
    3. 焦点在 @ExceptionHandler：提取出其中一个发生问题的异常处理方法： 
      @ExceptionHandler(BusinessException.class)
public ProblemDetail handleBusinessError(BusinessException ex) {
     ProblemDetail pd = ProblemDetail.forStatus(ex.getHttpStatus());
     pd.setDetail(ex.getMessage());
     return pd; // 注意：这里直接返回了 ProblemDetail，而不是 ResponseEntity<ProblemDetail>
}
    4. 根因确认：问题就在 return pd; 这一行。在 Spring MVC 中，如果一个 @ExceptionHandler 方法返回的是一个 ProblemDetail 对象，而不是 ResponseEntity<ProblemDetail>，框架会将这个返回值当作普通的模型数据（Model）或视图名来处理，而不会将其视为已经包含了状态码的响应体。这时，框架会使用一个默认的成功状态码（通常是 200 OK），同时尝试寻找一个视图或使用消息转换器来渲染这个 ProblemDetail 对象。虽然最终也可能输出 JSON，但状态码不再是 ProblemDetail 中设定的状态码。
  • 解决：将所有 @ExceptionHandler 方法的返回值统一包装成 ResponseEntity<ProblemDetail>。 
    @ExceptionHandler(BusinessException.class)
public ResponseEntity<ProblemDetail> handleBusinessError(BusinessException ex) {
     ProblemDetail pd = ProblemDetail.forStatus(ex.getHttpStatus());
     pd.setDetail(ex.getMessage());
     return new ResponseEntity<>(pd, ex.getHttpStatus()); // 明确设置状态码
}
  • 最佳实践：在 @ExceptionHandler 中，永远返回 ResponseEntity 或其子类。 直接返回 ProblemDetail 或 Map 会导致状态码信息丢失，这是从老版本 Spring 迁移时一个非常隐蔽的陷阱。Spring Tool Suite 或 IDEA 应配置相关静态检查规则，拦截这类错误写法。

10. 面试高频专题

本部分严格与正文分离，旨在通过模拟高强度的面试问答，帮助读者巩固核心知识。

  1. 什么是 RFC 7807？Spring Boot 3.x 是如何实现它的？

    • 标准回答：RFC 7807 是一个为 HTTP API 定义标准错误响应格式的规范。它定义了一个 ProblemDetail JSON/XML 对象，包含 type、title、status、detail、instance 等标准字段。
    • 追问与加分回答：
      • 追问1：type 字段的作用是什么，和 instance 有何区别？ （答：type 是错误“类”的标识，用于归类，比如“/errors/validation”；instance 是“具体发生实例”的标识，常为请求URI。）
      • 追问2：Spring 如何保证响应符合标准？ （答：通过 HttpMessageConverter 将 ProblemDetail 对象序列化为 application/problem+json 媒体类型。）
      • 追问3：和不返回这个标准格式相比，优势在哪？ （答：客户端可以实现通用的、基于 type 的错误处理逻辑，降低耦合；响应自描述，人读和机读都更友好。）

  2. Spring Boot 3.x 和 2.x 的错误处理最重要的区别是什么？

    • 标准回答：核心区别在于默认 JSON 错误响应体的格式。2.x 返回一个非标准的 Map，而 3.x 返回一个符合 RFC 7807 标准的 ProblemDetail 对象。
    • 追问与加分回答：
      • 追问1：那我的自定义 ErrorAttributes 在 3.x 中还工作吗？ （答：工作，但其产出的 Map 中的数据会被填充到 ProblemDetail 的 properties 扩展字段中，不再直接作为顶层字段。）
      • 追问2：Controller 抛出相同的异常，响应头 Content-Type 会有变化吗？ （答：会，3.x 中对于 API 请求，Content-Type 会变为 application/problem+json。）
      • 追问3：这项改变是否要求我修改所有的客户端代码？ （答：取决于客户端，如果客户端是强类型校验，需要更新模型；如果是弱解析，可能只需适配新的内容类型。）

  3. BasicErrorController 在 3.x 中是如何选择返回 HTML 或 JSON 的？

    • 标准回答：通过请求头内容协商。errorHtml 方法指定了 produces = MediaType.TEXT_HTML_VALUE，处理接受 HTML 的请求；另一个 error 方法处理其他请求，主要输出 JSON 格式的 ProblemDetail。
    • 追问与加分回答：
      • 追问1：如果请求 Accept 头是 */*，会走哪个分支？ （答：会走非HTML的 error 方法，返回JSON。）
      • 追问2：error 方法是如何从 ErrorAttributes Map 构建 ProblemDetail 的？ （答：先创建 ProblemDetail.forStatus()，然后遍历 Map，通过 problemDetail.setProperty() 将每个键值对加入扩展属性。）
      • 追问3：我能自定义这个内容协商逻辑吗？ （答：可以，通过实现自己的 ErrorController 并覆盖 BasicErrorController，或者定制 HttpMessageConverter。）

  4. ErrorResponseException 的作用是什么？如何自定义？

    • 标准回答：它是一个实现了 ErrorResponse 接口的异常基类，允许异常对象自身携带 ProblemDetail 响应体。自定义时只需继承它，在构造器里通过 super 传递状态码和 ProblemDetail 即可。
    • 追问与加分回答：
      • 追问1：使用它有什么好处？ （答：将错误表示和异常内聚，避免在 @ExceptionHandler 里每次都手动构建响应体，简化代码。）
      • 追问2：我的OrderNotFoundException继承了它，Spring会如何处理？ （答：在 @ExceptionHandler 里，你可以直接从该异常实例的 getBody() 方法获取 ProblemDetail 并返回。）
      • 追问3：Spring MVC 内部哪些异常已经实现了这个接口？ （答：例如 HttpRequestMethodNotSupportedException 等。）

  5. 如何在 ProblemDetail 中添加自定义的业务错误代码？

    • 标准回答：使用 problemDetail.setProperty("bizCode", "ERR_1001") 方法，将自定义信息添加到 properties 扩展映射中。
    • 追问与加分回答：
      • 追问1：为什么不直接放在 detail 字段里？ （答：detail 是人读的详细解释，应保持自然语言。bizCode 是机器可用的错误码，放入 properties 更合适，利于客户端自动化处理。）
      • 追问2：添加的属性在 JSON 中会出现在哪个层级？ （答：会直接作为顶层键值对出现，与 title、status 等平级。）
      • 追问3：如果我想为所有错误都添加一个通用的 apiVersion 属性，该怎么做？ （答：自定义 ErrorAttributes，在其方法返回的 Map 中加入 apiVersion，或使用 @ControllerAdvice 结合 ResponseBodyAdvice 处理。）

  6. ErrorMvcAutoConfiguration 是如何利用条件装配的？

    • 标准回答：它使用 @ConditionalOnWebApplication 和 @ConditionalOnClass 限制生效环境；并使用大量的 @ConditionalOnMissingBean 提供“默认但可被覆盖”的扩展点。
    • 追问与加分回答：
      • 追问1：如果我定义了自己的 ErrorController，Spring Boot 的默认实现会怎样？ （答：@ConditionalOnMissingBean 条件不满足，BasicErrorController Bean 不会被注册。）
      • 追问2：ProblemDetailsErrorAttributes 和 DefaultErrorAttributes 如何共存？ （答：它们不共存。ProblemDetailsErrorAttributes 是 DefaultErrorAttributes 的子类，其注册条件互斥，根据应用是否启用了 ProblemDetail 功能动态选择一个。）
      • 追问3：这种设计模式的好处是什么？ （答：开闭原则——对扩展开放（开发者可轻易覆盖），对修改关闭（框架核心代码不需变动）。）

  7. 如何完全禁用 Spring Boot 的默认错误处理？

    • 标准回答：可以实现 jakarta.servlet.ErrorController 接口并注册为 Spring Bean，或者将 server.error.whitelabel.enabled=false 与自定义错误页结合。最彻底的是排除 ErrorMvcAutoConfiguration 的自动配置。
    • 追问与加分回答：
      • 追问1：排除自动配置有哪几种方式？ （答：@SpringBootApplication(exclude = ErrorMvcAutoConfiguration.class) 或在 application.properties 中使用 spring.autoconfigure.exclude。）
      • 追问2：如果只是不想看到白页，但保留 JSON 错误响应，怎么做？ （答：设置 server.error.whitelabel.enabled=false 并提供一个自定义的 error 视图或静态页面即可。）
      • 追问3：完全禁用后，我还需要做什么才能处理错误？ （答：你需要负责所有错误处理，最好实现一个全局的 @ExceptionHandler 或一个自定义的 Filter。）

  8. 在 @ControllerAdvice 中返回 ProblemDetail 还是 ResponseEntity？为什么？

    • 标准回答：必须返回 ResponseEntity<ProblemDetail>。如果仅返回 ProblemDetail，Spring MVC 会丢失其携带的 HTTP 状态码信息，并使用默认的 200 作为响应状态码。
    • 追问与加分回答：
      • 追问1：返回 ResponseEntity 时，状态码从哪里取？ （答：可以由 ProblemDetail 创建时设置的状态码决定，或直接在 ResponseEntity 构造器中传入。）
      • 追问2：还有什么其他的返回方式吗？ （答：也可以返回 ErrorResponseException，由系统进行解析，但其本质上也是一种包装。）
      • 追问3：这背后的原理涉及到哪个核心组件？ （答：HandlerMethodReturnValueHandler，特别是 HttpEntityMethodProcessor，负责处理 ResponseEntity 的返回值，它会设置响应状态码和头。）

  9. Jakarta EE 迁移对错误处理的影响体现在哪些地方？

    • 标准回答：主要体现在包名的变更，javax.servlet 变为 jakarta.servlet，导致 ErrorController 接口被弃用并由新包名下的接口替代，以及与错误相关的请求属性常量名发生变化。
    • 追问与加分回答：
      • 追问1：如果从 2.x 升级，一个实现旧 ErrorController 的类会怎么样？ （答：编译失败。需要改为实现 jakarta.servlet.ErrorController，并移除 getErrorPath 方法。）
      • 追问2：这对 DefaultErrorAttributes 的实现有影响吗？ （答：有，其内部读取的请求属性常量从 javax.servlet.error.status_code 换成了 jakarta.servlet.error.status_code。）
      • 追问3：这个迁移是 Spring Boot 独有的吗？ （答：不是，是整个 Java EE 生态向 Jakarta EE 迁移的一部分，Spring Framework 6 和 Spring Boot 3 只是跟进者。）

  10. 如果同时存在 BasicErrorController 和自定义的 ErrorController，哪个生效？

    • 标准回答：自定义的 ErrorController 生效。因为 ErrorMvcAutoConfiguration 在注册 BasicErrorController 时使用了 @ConditionalOnMissingBean(ErrorController.class)，一旦自定义 Bean 存在，条件不满足，BasicErrorController 就不会被注册。
    • 追问与加分回答：
      • 追问1：如果自定义 Bean 是一个 @Component，而 BasicErrorController 是 @Bean 方法注册的，Spring 如何保证 Bean 覆盖？ （答：@ConditionalOnMissingBean 在 Bean 定义加载阶段起作用，它会检查所有已定义（包括 component-scan 扫到的和 @Bean 方法定义的）的 Bean，如果有匹配，当前 @Bean 方法就被忽略。）
      • 追问2：如果我想让我的自定义控制器在某些路径下工作，而默认的在 /error 工作呢？ （答：不应该同时在容器中存在两个。你需要自定义一个继承自 BasicErrorController 的类，并在其上使用 @Controller 和不同的 @RequestMapping，但这会导致混乱，不推荐。）
      • 追问3：这个机制的核心注解是什么？ （答：@ConditionalOnMissingBean。）

  11. ProblemDetail 的 properties 字段和传统 ErrorAttributes 返回的 Map 区别何在？

    • 标准回答：ErrorAttributes 返回的 Map 是一个混合体，同时包含状态码、消息等标准信息和自定义信息。而 ProblemDetail 的 properties 是明确用于存放非标准扩展信息的字段，标准信息有独立的 type、status 等字段，职责更清晰。
    • 追问与加分回答：
      • 追问1：在 3.x 中，ErrorAttributes 返回的 Map 中的 status 字段会怎样？ （答：它会被调用 problemDetail.setProperty("status", ...)，添加到 properties 中。这可能导致冗余，因为顶层的 status 字段已经有这个值了。）
      • 追问2：如何避免这种冗余？ （答：在自定义的 ErrorAttributes.getErrorAttributes 方法中，通过 ErrorAttributeOptions 进行过滤，或者重写 BasicErrorController 的 error 方法，实现更精细的映射。）
      • 追问3：这个设计体现了什么设计原则？ （答：关注点分离。ErrorAttributes 仍然负责聚合错误信息，而 ProblemDetail 负责按照标准格式化。）

  12. (系统设计题) 设计一个全局错误处理框架，要求支持多语言错误消息、错误码枚举、开发环境打印堆栈、生产环境只显示错误码，同时完全基于 RFC 7807。请结合 Spring Boot 3.x 的 ProblemDetail 和 @ControllerAdvice 给出核心设计。

    • 标准回答：
      • 核心实体：定义一个 AppErrorCode 枚举，包含 code（如 "ORD_NOT_FOUND"）、messageKey（国际化键）、httpStatus。
      • 异常基类：AppException extends ErrorResponseException，构造时接收 AppErrorCode 和动态参数，内部构建 ProblemDetail，设置 type 为统一前缀+错误码。
      • 多语言：通过 Spring MessageSource 根据 messageKey 和区域解析人读的 detail 信息。
      • 环境区分：在 @ControllerAdvice 的 @ExceptionHandler 中，注入 Environment，如果当前是开发环境，调用 problemDetail.setProperty("stackTrace", ...) 将堆栈加入 properties；生产环境则绝不添加。
      • 全局处理：一个 @RestControllerAdvice 类，处理所有 AppException，返回 ResponseEntity<ProblemDetail>。
    • 追问与加分回答：
      • 追问1：type 字段你会如何设计？ （答：设计成可解析的 URL，如 https://api.mycompany.com/errors/nfr/ord-not-found，nfr 表示功能域，ord-not-found 是错误码。这个 URL 甚至可以指向内部文档。）
      • 追问2：如何保证开发环境绝不会把堆栈泄露到生产？ （答：在配置中心或 application-prod.yml 中设置一个特性开关，@ConditionalOnProperty 控制添加堆栈的 @ControllerAdvice 或 ErrorAttributes 是否生效，双重保障。）
      • 追问3：如果需要区分“给前端看的消息”和“给开发者看的消息”，如何用 ProblemDetail 表达？ （答：detail 字段始终是给前端用户看的、安全的、本地化的消息。给开发者看的技术细节（如堆栈、内部状态）只在开发环境通过扩展 properties 如 debugInfo 暴露。）
      • 追问4：如果 @ExceptionHandler 也要处理 MethodArgumentNotValidException，如何与你的框架融合，并实现多语言？ （答：继续继承 ResponseEntityExceptionHandler，重写其方法，在方法里解析校验失败的字段，转化为你的 AppErrorCode（如 VALIDATION_ERR），并用 MessageSource 通过字段名查找本地化消息，最后将错误放入 ProblemDetail 的 properties 中，比如 "errors": [{"field": "email", "message": "邮箱不能为空"}]。）

错误处理核心组件速查表

组件/接口/类 (3.x)角色与职责与前文知识关联
ProblemDetailRFC 7807 标准的核心对象，作为标准化的错误响应体。HTTP 消息转换：由其序列化为 application/problem+json。
ErrorMvcAutoConfiguration错误处理体系的自动配置“组装器”。条件装配：大量使用 @ConditionalOnMissingBean 等注解实现组件插拔。
BasicErrorController默认的 /error 请求处理器，分 HTML 和 JSON 两路处理。依赖注入：注入 ErrorAttributes、ErrorViewResolver；内容协商：依赖 RequestMapping 的 produces。
ErrorResponseException新的异常基类，让异常实例能直接携带 ProblemDetail 作为响应体。@ControllerAdvice：被全局异常处理器捕获，简化处理逻辑。
ErrorAttributes传统的错误信息聚合接口，其 Map 产出成为 ProblemDetail 的 properties 来源。模板方法：其实现类 DefaultErrorAttributes 定义了聚合骨架。
ResponseEntityExceptionHandlerSpring MVC 内置的全局异常处理器基类，3.x 中全面返回 ProblemDetail。@ControllerAdvice：实现全局异常拦截，是 @ExceptionHandler 的载体。
jakarta.servlet.ErrorControllerJakarta EE 规范定义的错误控制器接口，替代旧的 Spring 接口。Jakarta EE 迁移：体现了整个底层基础设施的版本演进。

至此，我们完成了对 Spring Boot 3.x 错误处理体系的深度剖析。从 RFC 7807 标准，到核心组件的自动装配，再到控制器的演进和异常体系的重构，整个脉络清晰地展现了 Spring 技术栈在拥抱标准、简化开发方面的一贯追求。掌握这些原理，将使你在构建专业级、高可观测性的微服务时游刃有余。

avatar
文章
阅读
粉丝