FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

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

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

分享微博

要点速览

  • RFC 9457 已取代 RFC 7807,是当前 application/problem+json 错误响应的标准。
  • 机器按 type 给错误分类,人读 detail,运维团队用 instance 搜索日志。不要让客户端解析 detail。
  • 加上 runbook、retryable 等扩展字段,让客户端自行处理错误;堆栈信息不要出现在响应里。
RFC 9457 下 application/problem+json 错误响应的结构示意图。左侧是 type、title、detail、instance 字段及扩展字段(account_id、runbook、retryable),每个字段连到对应读者:type 连到客户系统用于分支(高亮显示),title 和 detail 连到值班工程师,instance 连到追查日志的运维团队,扩展字段同时连到人和机器。
机器按 type 分支,人读 detail,运维团队按 instance 追查日志。措辞可以改,客户端代码不会因此失效。

交付集成后的第一周,半夜,客户运维团队的监控面板一片红。日志里只有一行 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 是你真正测得的数字才有分量,所以从项目第一周起就开始统计工单。

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

这篇文章对你有帮助吗?

5 个信源
路线图上的下一篇 · 阶段 5: 部署上线云端跑得好的模型,为何到了传送带旁就失灵先定设备、供电和几十个站点的铺开方案,再选 TensorRT、LiteRT 或 ExecuTorch。