计算机网络 / 系统课时
设计统一错误响应
设计统一错误响应
统一错误响应要同时服务两类读者:客户端程序需要稳定字段做分支判断,开发与运维人员需要追踪标识定位一次失败。一个实用方案是采用 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。
{
"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 和统一错误结构。
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()预期结果
服务启动后保持运行并监听 127.0.0.1:8081;每次错误响应都会生成新的 traceId。另开终端发起请求。
curl -i -X POST http://127.0.0.1:8081/orders/1001/cancel预期输出
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 和“用户名已被使用”;内部日志再记录具体约束名与异常堆栈。这样客户端得到稳定契约,排障人员仍能定位根因,同时不会把内部实现细节暴露给外部调用方。