跳到主要内容
约 8 分钟2 张卡

API 错误契约

API 错误契约是服务端与客户端对失败响应的约定,包括 HTTP 状态、错误码和响应字段。客户端依靠这些稳定信息判断下一步该修改输入、重新登录,还是稍后重试。

例如,订单已支付和服务暂时不可用,需要客户端采取不同动作,不能只返回一句“操作失败”。设计错误处理时,既要给出明确的失败分类,也要确认 Filter、MVC 和后台任务的异常分别由谁处理。文中的 ProblemDetail 示例适用于 Spring 6,也就是 Boot 3.x 使用的框架版本。

1. 面试核心​

先记住这几条,再读正文
  • Spring 6 的 ProblemDetail 提供标准问题字段,客户端应按 HTTP 状态、问题类型或稳定错误码判断失败,避免解析提示文案。
  • @RestControllerAdvice 配合 @ExceptionHandler,通过 MVC 异常解析链把异常集中映射为错误响应。卡 · 错误字段
  • MVC 异步派发返回的异常仍能交给 @ExceptionHandler 处理,独立后台任务则需要自己的失败处理机制。
  • 响应已经提交后,错误处理器无法重新设置完整响应,只能记录失败并结束当前处理。
  • 同一 Controller 或 Advice 内,Spring MVC 先匹配顶层异常,再查找内部原因;多个类型都匹配时,选择继承关系更近的类型。卡 · 异常处理器选择

2. 错误字段​

错误响应要把程序判断和用户展示分开:错误码供程序选择处理分支,文字说明帮助用户理解原因。Spring 6 的 ProblemDetail 是表示 HTTP API 错误的类型,按 RFC 9457 提供以下标准字段:

  • type 用 URI 标识问题类型。
  • title 提供该问题类型的简短描述。
  • status 记录本次响应的 HTTP 状态码。
  • detail 解释本次失败的具体情况。
  • instance 用 URI 标识这一次问题出现的位置或实例。

下面的响应表示订单状态冲突,并扩展业务错误码和请求关联标识:

{
"type": "https://coding101.dev/problems/order-state",
"title": "Order state conflict",
"status": 409,
"detail": "The order has already been paid",
"instance": "/orders/101",
"code": "ORDER_ALREADY_PAID",
"traceId": "..."
}

示例中的 code 和 traceId 是业务扩展字段。traceId 用于关联同一次请求的服务端日志,便于根据报错追踪原因。客户端按 HTTP 状态、type 或稳定错误码选择处理分支,字段校验错误也要采用稳定结构。detail 用于展示,内容可随语言变化,因此应与程序判断分开。

响应使用 application/problem+json。正文的 status 应与实际 HTTP 状态一致。Spring MVC 的消息转换器支持该格式。

3. 异常处理器​

异常处理器是把 Java 异常转换成客户端响应的方法。@RestControllerAdvice 把处理方法集中在一个类中,@ExceptionHandler 指定每个方法接收哪些异常:

@RestControllerAdvice
class ApiExceptionHandler {
@ExceptionHandler(OrderStateException.class)
ResponseEntity<ProblemDetail> handle(OrderStateException exception) {
ProblemDetail problem = ProblemDetail.forStatus(409);
problem.setTitle("Order state conflict");
problem.setProperty("code", "ORDER_STATE_CONFLICT");
return ResponseEntity.status(409).body(problem);
}
}

MVC 处理请求时遇到 OrderStateException,会调用 handle。这个方法把错误映射为 HTTP 409,并返回 ORDER_STATE_CONFLICT 错误码。这样,客户端既能按状态码识别冲突,也能按业务错误码决定具体提示。

不同失败需要客户端采取不同动作,因此要分别映射:

  • 输入错误说明请求结构或参数需要修改。
  • 认证授权错误说明身份凭证或访问权限有问题。
  • 业务冲突说明当前资源状态无法接受该操作。
  • 依赖失败说明外部服务调用未能完成。
  • 未知异常返回 500,并在服务端日志中保留根因。

ResponseEntityExceptionHandler 是 Spring 提供的 MVC 标准异常处理基类。继承它,可以统一参数绑定、媒体类型等框架异常的响应,不必只处理业务代码自己抛出的异常。

4. 状态码​

选择状态码时,要表达当前请求为何失败。下表区分了客户端输入、业务状态和服务端处理中的常见问题。

状态语义
400请求语法、参数或校验错误
401缺少有效认证凭证;需返回 WWW-Authenticate
403服务端理解请求,但拒绝执行
404资源不存在,或服务端拒绝披露其存在
409操作与资源当前状态冲突
429请求频率超过限制
500服务端未预期错误
502网关收到无效的上游响应
503服务暂时无法处理请求
504网关等待上游响应超时

客户端决定重试前,还要检查幂等性,也就是重复请求是否会产生额外副作用。响应中的 Retry-After 可指示等待多久后再尝试,因此仅凭 5xx 无法决定是否安全重试。

依赖失败要结合当前服务的角色映射。例如 502 和 504 表达网关与上游之间的问题,普通业务服务应按实际失败原因选择状态。

5. 日志与响应​

错误响应提供客户端处理失败所需的信息,服务端日志则保留排查依据。响应只包含公开字段,堆栈、SQL、文件路径和内部类名留在受控诊断范围,密钥等敏感值应脱敏。

日志应记录 cause,也就是原始异常,以及 trace ID 和必要业务标识。路由可记录为 /orders/{id} 这类规范化模板,便于聚合同类请求。日志中的用户数据和敏感参数同样要脱敏。

预期业务冲突可记录简要信息,未知异常则在处理边界记录一次完整堆栈。若 Controller 和 Advice 都记录同一异常,会产生重复日志,增加定位成本。

6. ControllerAdvice 的处理范围​

ControllerAdvice 只能处理进入 MVC 异常解析流程的异常。DispatcherServlet 会把异常交给 HandlerExceptionResolver 解析链,由其中的解析器寻找处理方式,@ExceptionHandler 就在这个流程中被调用。判断异常能否统一处理,先看它有没有进入这条链。

下面三条路径的处理方式不同:

  • Filter 在进入 MVC 前抛出的异常,由过滤链或 Servlet 容器处理。安全过滤链可使用自己的错误处理器,容器也可发起 error dispatch,即错误派发。
  • MVC 的 Callable 抛错后,会触发异步派发,重新进入 MVC 处理流程。DeferredResult.setErrorResult(exception) 也会把异常交给 MVC resolver。
  • 独立后台任务没有对应的 MVC 请求派发,其失败由任务结果或任务异常处理器承接。

响应提交后,状态和已写出的正文已经交给客户端,错误处理器无法重新设置完整响应。这时应记录序列化或写出失败,再按连接状态结束处理。客户端断开造成的 I/O 错误应单独统计,避免全部计为应用 500。

7. 字段校验错误​

客户端要把校验错误显示在对应输入框旁,就需要稳定的字段路径和错误码。下面的响应表示 quantity 未通过正数校验:

{
"code": "VALIDATION_FAILED",
"errors": [
{"field": "quantity", "code": "Positive"}
]
}

示例用 field 定位字段,用 code 表达校验规则。数组和嵌套对象也要约定路径表示方式,客户端才能找到对应输入项。响应省略密码等敏感拒绝值,展示文本则可由客户端或服务端按语言生成。这样,调整提示文案就不会改变稳定错误码。

8. 契约测试​

契约测试是检查接口实际行为是否符合约定的测试。对错误响应,要逐类检查 HTTP 状态、Content-Type、业务 code 和字段结构。还可以用敏感值作为输入,确认失败响应没有把它原样带回来。

同一服务的错误可能来自不同入口,测试需要分别触发:

  • 路由不存在、请求方法错误和不可接受的媒体类型。
  • 参数校验失败和 Filter 拒绝请求。
  • MVC 异步异常与下游调用超时。
  • 序列化或响应写出失败,以及响应已经提交的情况。

这些用例能发现不同入口是否产生了互不兼容的格式。响应已提交的用例则检查记录和结束处理的行为。

9. 异常处理器选择​

多个方法都能处理同一个异常时,先确定查找哪个类,再确定类里的哪个方法匹配。Controller 内的局部 @ExceptionHandler 优先于全局 Advice;多个 Advice 按 Ordered 或 @Order 排序,数值越小越早查找。

顶层异常是当前向外抛出的异常。在同一个 Controller 或 Advice 内,Spring 先尝试匹配它。如果多个类型都能匹配,就选继承关系更近的类型。例如,抛出 IllegalArgumentException 时,接收它的处理器比接收 Exception 的处理器更具体。

顶层异常没有匹配方法时,才沿 cause 链查找,也就是逐层检查被包装在内部的异常。Spring 5.3 起支持任意深度的 cause,Boot 2.7 和 3.x 都支持这条规则。

跨 Advice 时,要先遵守 Advice 的优先级。Spring 在高优先级 Advice 中找到 cause 的匹配后,就不会为了寻找顶层匹配而继续检查低优先级 Advice。

因此,接收 Exception 的兜底处理器应放在低优先级 Advice 中,否则它可能提前接住所有异常,让后面的具体处理器没有机会执行。调整方法在源码中的书写顺序不会改变匹配结果。

10. 常见问题​

10.1 所有响应都要使用统一包装吗?​

不必。成功响应可以直接返回资源,错误响应保持稳定结构即可。团队使用统一包装时,也要保留正确的 HTTP 状态。如果所有结果都返回 200,按状态码工作的代理、监控和客户端就会把失败当作成功,影响告警与重试判断。

10.2 可以捕获 Exception 作为最后兜底吗?​

11. 面试题卡片​

先想答案,再翻面先在心里答一遍,再点开卡片对照参考回答。卡片之间可以左右切换,看完会回到这里。
逐张翻看 2 张 →
未标记的卡读完后明天进入复习;已标记的按状态安排

12. 参考资料​

来源:Coding 101 原文 · 免费阅读,引用请保留出处。内容使用说明