problem-details-rfc9457

问题详情 - RFC 9457

选择错误契约

先检查现有的 advice、安全入口和 API 测试。每个 API 保持一种错误策略。 成功 DTO 或成功响应封装可以与 Problem Details 错误共存： RFC 9457 规定的是错误，而不是成功表示。

对于使用 Problem Details 的 API，启用 Spring 内置的 MVC 异常处理：

spring:
  mvc:
    problemdetails:
      enabled: true

对于 WebFlux，使用 spring.webflux.problemdetails.enabled 和响应式异常处理； 以下 Servlet 模板不是 WebFlux 处理器。

领域错误

将编译后的 DomainException 与 ProblemDetailExceptionHandler 配合使用。 处理器会根据各子类声明的状态码和稳定错误代码映射所有子类：

• OrderNotFoundException：404。
• InsufficientInventoryException：422。
• BusinessRuleViolationException：422。

每个公共类都使用独立的文件。这些是带有 HTTP 状态元数据、面向 API 的异常； 对于不依赖框架的领域，应保持领域异常独立，并在 Web 适配器中进行映射。 不要暴露任意持久化或基础设施异常消息。

该 advice 扩展 ResponseEntityExceptionHandler，以保留 Spring 对框架异常的处理。 验证失败时返回带字段违规信息的 400；意外失败时返回通用的 500，同时仅在服务器日志中保留完整异常信息。确保能安全处理可空的验证消息。 过滤器级身份验证失败需要 AuthenticationEntryPoint；授权失败需要 AccessDeniedHandler。Controller advice 不会覆盖安全过滤器链。 方法安全（@PreAuthorize）拒绝访问则属于相反情况：AccessDeniedException 在分发器内部抛出，因此 advice 必须将其映射为 403，否则会由 Exception 兜底处理器返回 500。

响应字段

{
  "type": "https://api.example.com/errors/order_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Order not found",
  "instance": "/api/orders/123",
  "errorCode": "ORDER_NOT_FOUND"
}

为自定义问题类型使用项目自有且稳定的 URI。type 可以省略； 省略时默认值为 about:blank。此时其标题应与 HTTP 状态短语一致。 HTTP 状态码必须与正文中的状态码一致。JSON 问题使用 application/problem+json。 使用 errorCode 或 violations 等扩展字段提供机器可读的详情，而不是要求客户端解析人类可读的消息。

验证

测试实际 HTTP 响应，覆盖领域错误 404/422、验证失败 400、意外错误 500，以及格式错误的 JSON 和不支持的方法等框架错误。断言内容类型、状态码、稳定错误代码，以及不存在堆栈跟踪或内部消息。另行测试过滤器级 401/403。 仓库验证夹具会为两个 Boot 版本导入这些确切的模板。

官方来源

• RFC 9457
• Spring MVC 错误响应

注意事项

• Agent 处理的异常类与领域实际抛出的不同——测试具体异常。
• Agent 强行将 Problem Details 用于现有旧版 API——除非要求迁移，否则应保留其契约。
• Agent 要求每个错误都显式指定类型——默认值为 about:blank。
• Agent 认为成功响应封装与 Problem Details 不兼容——只需统一错误策略。
• Agent 依赖 advice 处理过滤器异常——应单独配置安全处理器。
• Agent 在 500 响应中返回内部异常消息——仅在内部日志记录，并返回通用详情。