在 java 中实现 rfc 7807 problem detail,核心是定义一个符合规范的 json 结构并配置 spring boot 的全局异常处理器。具体做法是创建一个包含 type、title、status、detail 等字段的 dto 类,然后使用 @controlleradvice 捕获业务异常,将其转换为该 dto 并通过 responseentity 返回。这样当发生错误时,客户端会收到标准的 http 4xx/5xx 响应及对应的 json 描述。

如何定义符合 RFC 7807 的 JSON 数据结构
要实现标准格式,需要创建一个 Java 类来映射 JSON 字段。该类必须包含 type(问题类型 URI)、title(简短标题)和 status(HTTP 状态码),而 detail(详细解释)和 instance(实例 URI)则是可选的。推荐使用 Jackson 注解来控制序列化行为,确保字段名与 RFC 规范一致。
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
@JsonInclude(JsonInclude.Include.NON_NULL)
public class ProblemDetail {
private String type;
private String title;
private int status;
private String detail;
private String instance;
public ProblemDetail(String type, String title, int status, String detail) {
this.type = type;
this.title = title;
this.status = status;
this.detail = detail;
}
// Getters and Setters omitted for brevity
}上述代码定义了基础结构。通过 @JsonInclude(JsonInclude.Include.NON_NULL),如果某个字段为空(如 detail),它将被排除在 JSON 输出之外,这符合 RFC 7807 中关于可选字段的规定。在实际使用中,你可以根据不同的错误场景填充这些字段。
如何在全局异常处理器中统一返回 Problem Detail
为了让所有控制器自动应用这一格式,需要编写一个全局异常处理类。利用 @RestControllerAdvice 拦截抛出的自定义异常,并将其转换为 ProblemDetail 对象。关键在于设置正确的 HTTP 状态码,并确保响应头正确无误。这样,无论哪个 Controller 抛出异常,客户端都能获得一致的响应格式。
使用Atmosphere构建通过WebSocket、SSE、gRPC、WebTransport、MCP、A2A和AG-UI流传输的JVM代理网关,并带有治理钩子。
立即学习“Java免费学习笔记(深入)”;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<ProblemDetail> handleNotFound(ResourceNotFoundException ex) {
ProblemDetail problem = new ProblemDetail(
"https://example.com/errors/not-found",
"Resource Not Found",
HttpStatus.NOT_FOUND.value(),
ex.getMessage()
);
return new ResponseEntity<>(problem, HttpStatus.NOT_FOUND);
}
@ExceptionHandler(IllegalArgumentException.class)
public ResponseEntity<ProblemDetail> handleBadRequest(IllegalArgumentException ex) {
ProblemDetail problem = new ProblemDetail(
"https://example.com/errors/bad-request",
"Bad Request",
HttpStatus.BAD_REQUEST.value(),
ex.getMessage()
);
return new ResponseEntity<>(problem, HttpStatus.BAD_REQUEST);
}
}这段代码展示了如何处理两种常见异常。对于 ResourceNotFoundException,返回 404 状态码;对于 IllegalArgumentException,返回 400 状态码。每个处理器都构建了一个 ProblemDetail 实例,其中 type 指向具体的错误文档,detail 提供用户友好的消息。这种集中处理方式避免了在每个 Controller 中重复编写错误响应逻辑。
当自定义异常未指定 message 时,detail 字段会显示什么
如果在抛出异常时没有提供具体的错误信息,即调用无参构造函数或 super(),那么 ex.getMessage() 将返回 null。由于我们在 ProblemDetail 类中使用了 @JsonInclude(JsonInclude.Include.NON_NULL),这个 null 值会导致 detail 字段被完全省略,而不是显示为 null 字符串。这确保了 JSON 响应的简洁性,符合 RFC 7807 对可选字段的行为定义。

















