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 作为最后兜底吗?
可以在请求边界捕获未知异常,脱敏后返回 500,并记录根因。兜底 Advice 应设置较低优先级,让具体处理器先处理已知错误。响应已提交时,则保留已发出的响应并记录失败。对于请求取消,应结束后续工作,并单独记录取消结果。
11. 面试题卡片
12. 参考资料
- Spring Framework:Controller Exceptions
- Spring Framework:Error Responses
- RFC 9457:Problem Details for HTTP APIs
- Spring Framework:Asynchronous Requests
- RFC 9110:Status Codes
- RFC 6585:429 Too Many Requests
- Spring Framework:Controller Advice
来源:Coding 101 原文 · 免费阅读,引用请保留出处。内容使用说明