一个裸 500 错误,让你替客户值夜班
2023 年取代 RFC 7807 的 RFC 9457 定义了机器可读的错误字段,让客户运维团队能自行处理许多故障。
要点速览
- RFC 9457 已取代 RFC 7807,是当前 application/problem+json 错误响应的标准。
- 机器按 type 给错误分类,人读 detail,运维团队用 instance 搜索日志。不要让客户端解析 detail。
- 加上 runbook、retryable 等扩展字段,让客户端自行处理错误;堆栈信息不要出现在响应里。
交付集成后的第一周,半夜,客户运维团队的监控面板一片红。日志里只有一行 500 Internal Server Error,响应体是 {"error": "Something went wrong"}。
客户的值班工程师判断不了问题出在哪一方、要不要重试、该去哪里查日志。他唯一能做的就是开一张工单转给你。第二天一早,你面对的是一个毫无线索的故障。
RFC 9457《Problem Details for HTTP APIs》正是为避免这种场面而设计的标准,于 2023 年 7 月发布,见 rfc-editor.org。
它定义了一种名为“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。某个账户用完了当天的订单配额。糟糕的写法返回:
{ "error": "Bad request", "code": 4021 }
值班工程师不知道 4021 是什么意思,只好再开一张工单。下面是 RFC 9457 的写法:
{
"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 是写给人看的,且与每次发生绑定,下周你可能改措辞或加数字;任何用正则读取这个字符串的代码都会悄无声息地失效。
下面的示意代码展示客户端应如何处理仓储示例中的响应:
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,让双方找到同一次故障。
在多服务系统中,Apidog 建议同时传递 W3C traceparent 请求头和请求 ID,让标识符跟随请求穿过每个服务。把 instance 与这条链路追踪关联起来,就能从客户的工单一路追到具体出错的服务。
何时重试,何时停手?
retryable 标志回答了每个客户端都会问的问题。它不在 RFC 中,而是你自定义的扩展字段,所以必须在 type 指向的页面上写清它的含义。
Hackernoon 上的一篇文章建议只对特定的错误码列表重试,且只有当退避逻辑遵守 Retry-After 响应头时才重试 429。Apidog 说得更直白:返回 429 却不带 Retry-After,等于教客户端拼命轰炸你。Apidog 还指出,几乎所有其他 4xx 都是终态错误,重试也解决不了。
那篇 Hackernoon 文章还建议,重试通常应跳过 POST,以免产生重复记录。在仓储示例中,如果客户代码在超时后重发创建订单的 POST,仓库可能收到两笔相同的订单,因为超时并不能说明第一笔订单是否已记录。
如果客户确实需要重试 POST,可以设计幂等键:客户端为每笔订单生成一个键,每次尝试都发送同一个键;服务端看到已处理过的键时,返回最初的结果。下面的请求头名称是你与客户约定并写进 API 文档的惯例:
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 中,一个配置项就能为内置异常自动配置这个处理器:
spring.mvc.problemdetails.enabled=true
对于自定义的业务错误,在异常处理器中构造 ProblemDetail。扩展字段通过 properties 映射添加,Spring 会把它们渲染为 JSON 顶层属性:
@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 是你真正测得的数字才有分量,所以从项目第一周起就开始统计工单。
下次半夜出现的错误在客户那边就解决了、没有人打电话给你,就说明错误响应设计到位了。
这篇文章对你有帮助吗?
感谢你的反馈!