# 一个裸 500 错误，让你替客户值夜班

> 2023 年取代 RFC 7807 的 RFC 9457 定义了机器可读的错误字段，让客户运维团队能自行处理许多故障。

原文: https://fdetimes.net/zh/guides/rfc-9457-api-error-responses/

交付集成后的第一周，半夜，客户运维团队的监控面板一片红。日志里只有一行 `500 Internal Server Error`，响应体是 `{"error": "Something went wrong"}`。

客户的值班工程师判断不了问题出在哪一方、要不要重试、该去哪里查日志。他唯一能做的就是开一张工单转给你。第二天一早，你面对的是一个毫无线索的故障。

RFC 9457《Problem Details for HTTP APIs》正是为避免这种场面而设计的标准，于 2023 年 7 月发布，见 [rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9457.html)。

它定义了一种名为“problem detail”的 JSON 对象，以机器可读的形式承载错误信息，媒体类型为 `application/problem+json`。RFC 9457 取代了 RFC 7807。Apidog 认为，每当讨论错误响应体该长什么样，它就是标准答案。

因此，对前线部署工程师（FDE）来说，错误响应是交付的一部分。设计得好，客户能自行解决很多故障；设计得差，你就成了别人系统的长期值班工程师。

## RFC 9457 能回答哪些状态码回答不了的问题？

422 只说明请求有问题，却没说问题是什么、影响哪个账户、接收方下一步该做什么。RFC 9457 的字段正好补上这块空白。

你可能熟悉 RFC 7807。写文档或与客户架构师沟通时，请引用 RFC 9457，因为新文档已正式取代旧文档。

这个标准的长处在于，每个字段服务不同的读者。`type` 是标识问题类型的 URI，`title` 是简短的人类可读摘要，`detail` 解释这一次具体发生了什么，`instance` 标识这一次发生本身。下表把它们对应到值班工程师常问的问题：

| 字段 | 谁来读 | 回答什么问题 |
|---|---|---|
| `type` | 客户的系统 | 这是哪类错误，能否自动处理？ |
| `title` | 人 | 这类错误简单说是什么？ |
| `detail` | 人 | 这一次具体发生了什么？ |
| `instance` | 运维团队 | 这次发生对应什么 ID，用来搜日志？ |
| 扩展字段 | 两者 | 影响哪个账户，该看哪份处理指南？ |

## 示例：向仓库推送订单的 API

假设你在把一家零售连锁的订货系统对接到公司的仓储 API。某个账户用完了当天的订单配额。糟糕的写法返回：

```json
{ "error": "Bad request", "code": 4021 }
```

值班工程师不知道 `4021` 是什么意思，只好再开一张工单。下面是 RFC 9457 的写法：

```json
{
  "type": "https://docs.example.vn/problems/daily-order-quota-exceeded",
  "title": "超出每日订单配额",
  "detail": "账户 ACC-0192 已用完今日订单配额，配额将于 00:00 重置。",
  "instance": "/incidents/7f3a2c",
  "account_id": "ACC-0192",
  "runbook": "https://docs.example.vn/runbook/order-quota",
  "retryable": false
}
```

看到这个响应，值班工程师立刻知道问题出在自己这边，也知道它何时会自动恢复。他手里有处理指南的链接；如果仍需联系你，还有 ID `7f3a2c`，方便你找到对应的日志行。

`account_id`、`runbook` 和 `retryable` 是扩展字段。RFC 9457 允许每种问题类型的定义添加自己的成员，因此你可以精确附上客户运维团队需要的信息。

`type` 指向的页面也就是你的错误文档。Postman 建议错误文档列出可能的错误码、常见消息和建议的修复方法，这正是值班工程师半夜需要的三样东西。数据库表名或 Java 类名对他们毫无用处。

## 让客户的系统也能处理错误

值班工程师只是一半读者，另一半是调用你 API 的客户端代码，这些代码需要知道该按什么分支。

从 RFC 9457 对字段角色的划分看，答案相当明确：按 `type` 分支，因为它标识错误类型。`detail` 是写给人看的，且与每次发生绑定，下周你可能改措辞或加数字；任何用正则读取这个字符串的代码都会悄无声息地失效。

下面的示意代码展示客户端应如何处理仓储示例中的响应：

```python
PROBLEMS = "https://docs.example.vn/problems/"

def handle_error(resp, method, idempotency_key=None):
    if not resp.headers.get("Content-Type", "").startswith("application/problem+json"):
        return open_ticket(None)
    problem = resp.json()
    if problem.get("type") == PROBLEMS + "daily-order-quota-exceeded":
        return wait_until_tomorrow(problem.get("account_id"))
    safe = method != "POST" or idempotency_key is not None
    if problem.get("retryable") is True and safe:
        return retry_later(resp.headers.get("Retry-After"), idempotency_key)
    return open_ticket(problem.get("instance"))
```

函数里没有一行读取 `detail`。无论你怎么改写措辞，函数照样正确运行；需要开工单时，它会附上 `instance`，让双方找到同一次故障。

**要点:** 机器按 type 分支，人读 detail，运维团队按 instance 搜日志。

在多服务系统中，Apidog 建议同时传递 W3C `traceparent` 请求头和请求 ID，让标识符跟随请求穿过每个服务。把 `instance` 与这条链路追踪关联起来，就能从客户的工单一路追到具体出错的服务。

## 何时重试，何时停手？

`retryable` 标志回答了每个客户端都会问的问题。它不在 RFC 中，而是你自定义的扩展字段，所以必须在 `type` 指向的页面上写清它的含义。

Hackernoon 上的一篇文章建议只对特定的错误码列表重试，且只有当退避逻辑遵守 `Retry-After` 响应头时才重试 429。Apidog 说得更直白：返回 429 却不带 `Retry-After`，等于教客户端拼命轰炸你。Apidog 还指出，几乎所有其他 4xx 都是终态错误，重试也解决不了。

那篇 Hackernoon 文章还建议，重试通常应跳过 POST，以免产生重复记录。在仓储示例中，如果客户代码在超时后重发创建订单的 POST，仓库可能收到两笔相同的订单，因为超时并不能说明第一笔订单是否已记录。

如果客户确实需要重试 POST，可以设计幂等键：客户端为每笔订单生成一个键，每次尝试都发送同一个键；服务端看到已处理过的键时，返回最初的结果。下面的请求头名称是你与客户约定并写进 API 文档的惯例：

```python
import uuid
import requests

def create_order(session, order):
    key = str(uuid.uuid4())  # 每笔订单只生成一次，重试时绝不重新生成
    headers = {"Idempotency-Key": key}
    for _ in range(3):
        try:
            return session.post(ORDERS_URL, json=order, headers=headers, timeout=10)
        except requests.Timeout:
            continue  # 重发同一个键；服务端不会创建第二笔订单
    return open_ticket(None)
```

在服务端，把键和首次处理的结果一起存下来，键再次出现时原样返回该结果。在这套机制建成之前，创建订单的 POST 上所有错误的 `retryable` 都应为 `false`。

## 用 Spring 一个下午就能搞定

如果 API 用 Java/Spring 编写，大部分工作已经现成。Spring Framework 通过 `ProblemDetail` 和 `ErrorResponse` 支持 RFC 9457，只需继承 `ResponseEntityExceptionHandler` 并声明为 `@ControllerAdvice` 即可启用。在 Spring Boot 中，一个配置项就能为内置异常自动配置这个处理器：

```properties
spring.mvc.problemdetails.enabled=true
```

对于自定义的业务错误，在异常处理器中构造 `ProblemDetail`。扩展字段通过 properties 映射添加，Spring 会把它们渲染为 JSON 顶层属性：

```java
@ExceptionHandler(QuotaExceededException.class)
ProblemDetail handleQuota(QuotaExceededException ex) {
    ProblemDetail pd = ProblemDetail.forStatusAndDetail(
        HttpStatus.UNPROCESSABLE_ENTITY, ex.getMessage());
    pd.setType(URI.create("https://docs.example.vn/problems/daily-order-quota-exceeded"));
    pd.setTitle("超出每日订单配额");
    pd.setProperty("account_id", ex.getAccountId());
    pd.setProperty("runbook", "https://docs.example.vn/runbook/order-quota");
    pd.setProperty("retryable", false);
    return pd;
}
```

难点不在代码，而在于和客户运维团队坐下来，列出他们真正遇到的错误，为每种错误命名一个 `type`，并逐一写好运维手册（runbook）。这项工作更像客户需求调研，而不是编程。

## 常见陷阱

最危险的陷阱是泄露实现细节。RFC 9457 警告不要让堆栈信息之类的内容通过 HTTP 泄露出去；Apidog 也指出，冗长的错误响应体是攻击者最爱的侦察渠道。把堆栈跟踪写进内部日志并以 `instance` 为键，返回给客户的响应只带这个 ID。

第二个陷阱是每个端点错误格式各不相同：这里用 `error`，那里用 `message`，别处又返回 HTML。Postman 建议所有请求采用一致的错误结构，因为哪怕只有一个例外，客户端代码也得为它加一个特殊分支。

第三个陷阱是 `type` 指向一个空 URI。半夜的值班工程师一定会点这个链接，如果打开是 404，你就错失了让他自己解决问题的机会。

## 采用 RFC 9457 时的三个常见问题

**响应体里的 `status` 字段能代替 HTTP 状态码吗？** 不能。按照 RFC 9457，`status` 即使存在也只是参考，真正的状态码仍在响应的状态行里。两者应保持一致，但客户端应以状态行为准。

**一个请求有多处错误时，返回哪一个？** RFC 建议返回最相关或最紧迫的那个问题。对运维团队来说，就是阻碍他们继续推进的那个错误，而不是校验器碰巧最先遇到的那个。

**已经在用 RFC 7807，需要改什么吗？** RFC 9457 已取代 RFC 7807，所以至少要更新文档和技术讨论，改为引用新文档。

## 如何在 FDE 面试中讲好这个故事

“交付后你做了什么来减少工单？”这类问题，是展示这项能力的好切入点。“认真处理错误”这样的泛泛回答说服不了任何人，要讲清具体的工作步骤和对应的数字。

以前面的仓储 API 为基础，设想一个案例。标准化之前，团队每周收到客户约 25 张工单，大多是配额错误和订单数据错误。

当所有错误都返回 `application/problem+json`、每个 `type` 都有运维手册、客户代码按 `type` 分支之后，转到你手上的工单降到约 6 张，因为配额和数据错误客户自己就处理掉了。

这样，面试回答就有三个层次：问题（工单里没有日志 ID）、你做了什么（RFC 9457、每个 `type` 配一份运维手册、POST 使用幂等键）、量化的结果。

写进简历时，“基于 RFC 9457 统一错误响应，交付后每周工单从 X 降到 Y”这样的句子，只有当 X 和 Y 是你真正测得的数字才有分量，所以从项目第一周起就开始统计工单。

下次半夜出现的错误在客户那边就解决了、没有人打电话给你，就说明错误响应设计到位了。

**本周动手试试:**

- 从你正在开发的 API 日志中挑出最常见的 5 个错误，逐一改写为 RFC 9457 JSON，包含 type、title、detail、instance 和 runbook 字段。
- 为写好的每个 type，在对应的 URI 上放一页简短文档，分三部分：原因、如何自行修复、何时联系你的团队。
- 扮演客户：写一个小型客户端函数，针对这 5 个错误按 type 分支，不读取 detail 字符串；然后修改 detail 的措辞，检查函数是否仍然正常工作。

## 信源

- [RFC 9457 - Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457.html)

- [Spring Framework Reference: Error Responses](https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html)

- [Best Practices for API Error Handling](https://blog.postman.com/best-practices-for-api-error-handling/)

- [How To Improve Your Backend By Adding Retries to Your API Calls](https://hackernoon.com/how-to-improve-your-backend-by-adding-retries-to-your-api-calls-83r3udx)

- [REST API Error Handling Best Practices: Status Codes, RFC 9457, and Retryable Errors](https://apidog.com/blog/rest-api-error-handling-best-practices/)
