计算机网络 / 系统课时

设计统一错误响应

设计统一错误响应

统一错误响应要同时服务两类读者:客户端程序需要稳定字段做分支判断,开发与运维人员需要追踪标识定位一次失败。一个实用方案是采用 application/problem+json,保留标准 Problem Details 字段,再增加稳定的业务错误码和 traceId。

学习目标

  • 能用 HTTP 状态码与应用错误码分别表达协议层类别和业务层原因。
  • 能设计包含 type、title、status、detail、instance、code、traceId 的统一结构。
  • 能通过请求与响应验证状态码、媒体类型和追踪标识是否一致。

状态码与业务错误码分工

HTTP 状态码只承担粗粒度分类,例如 400 表示请求问题、401 表示缺少有效认证、403 表示拒绝访问、404 表示资源不存在、409 表示状态冲突。应用错误码则保持稳定且更具体,例如 ORDER_STATE_CONFLICT 或 RATE_LIMITED,供前端、SDK 和日志系统做精确分支。

不要把 HTTP 状态码复制成业务错误码,例如 "code":"409"。这样无法区分“订单状态冲突”和“用户名占用”等不同原因。也不要让客户端依赖自然语言 message 判断逻辑,因为文案可能改写、翻译或补充上下文。

一个可直接采用的映射是:HTTP 状态码决定客户端的大类处理策略,code 决定产品级分支,detail 面向人类阅读,traceId 用于排查。

使用 Problem Details 作为基础结构

RFC 9457 定义了 HTTP API 的 Problem Details,标准媒体类型是 application/problem+json。常用标准成员包括 type、title、status、detail 和 instance;规范也允许扩展成员,因此可以增加 code 与 traceId。

json
{
  "type": "https://api.example.com/problems/order-state-conflict",
  "title": "Order state conflict",
  "status": 409,
  "detail": "Paid order cannot be cancelled.",
  "instance": "urn:trace:01J9ABCDEF1234567890",
  "code": "ORDER_STATE_CONFLICT",
  "traceId": "01J9ABCDEF1234567890"
}

生效行为与验证方法:服务器应同时返回 HTTP 409,并把 Content-Type 设为 application/problem+json;响应体中的 status 也应为 409。traceId 必须对应服务端日志中的同一次请求,而不是每层组件各生成一个互不关联的值。

字段 责任 建议
type 标识问题类型 使用稳定 URI;同类错误保持不变
title 简短的人类可读标题 同一问题类型尽量固定
status 镜像 HTTP 状态 与真实响应状态一致
detail 本次失败细节 可包含当前对象状态,不放敏感数据
instance 标识这一次问题发生实例 使用可关联到本次失败的 URI 引用
code 应用级稳定错误码 使用可版本管理的枚举值
traceId 关联日志与链路追踪 每次请求唯一或可关联

返回并验证一份统一错误

下面用 Python 标准库启动一个最小 HTTP 服务。它会对取消已支付订单的请求返回 409 和统一错误结构。

python
from http.server import BaseHTTPRequestHandler, HTTPServer
import json
import uuid

class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        if self.path != "/orders/1001/cancel":
            self.send_response(404)
            self.end_headers()
            return

        trace_id = uuid.uuid4().hex
        body = {
            "type": "https://api.example.com/problems/order-state-conflict",
            "title": "Order state conflict",
            "status": 409,
            "detail": "Paid order cannot be cancelled.",
            "instance": f"urn:trace:{trace_id}",
            "code": "ORDER_STATE_CONFLICT",
            "traceId": trace_id
        }
        data = json.dumps(body).encode("utf-8")
        self.send_response(409)
        self.send_header("Content-Type", "application/problem+json")
        self.send_header("Content-Length", str(len(data)))
        self.end_headers()
        self.wfile.write(data)

HTTPServer(("127.0.0.1", 8081), Handler).serve_forever()

预期结果

text
服务启动后保持运行并监听 127.0.0.1:8081;每次错误响应都会生成新的 traceId。

另开终端发起请求。

bash
curl -i -X POST http://127.0.0.1:8081/orders/1001/cancel

预期输出

text
HTTP/1.0 409 Conflict
Content-Type: application/problem+json
Content-Length: 295

{"type": "https://api.example.com/problems/order-state-conflict", "title": "Order state conflict", "status": 409, "detail": "Paid order cannot be cancelled.", "instance": "urn:trace:<ID>", "code": "ORDER_STATE_CONFLICT", "traceId": "<ID>"}

traceId 是动态值,因此示例用 <ID> 表示;由于这里使用固定长度的 32 位十六进制追踪标识,Content-Length 固定为 295。实际输出还会包含动态的 Server 与 Date。验收时至少检查三件事:HTTP 状态与 status 一致,Content-Type 正确,拿响应中的 traceId 能在服务端日志或链路追踪系统中找到同一次请求。

控制错误信息的边界

统一结构不等于把异常堆栈直接返回给调用方。数据库表名、SQL、服务器路径、令牌、内部主机名和完整堆栈都不应进入公开 detail。外部响应写“可操作的信息”,内部日志保留“可诊断的信息”,两者通过同一个 traceId 关联。

例如数据库唯一约束失败时,外部可以返回 409、code: USERNAME_TAKEN 和“用户名已被使用”;内部日志再记录具体约束名与异常堆栈。这样客户端得到稳定契约,排障人员仍能定位根因,同时不会把内部实现细节暴露给外部调用方。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计统一错误响应

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通