技术文章

外部链接将在新标签页打开。

JSON、表单与图片接口的响应设计规范:内容类型、错误模型与边界条件

一句话回答

响应设计应先确定媒体类型与状态码语义,再确定错误体,最后确定数据字段与缓存头;图片接口必须保证错误路径仍返回可解析的 JSON 错误体,并让调用方先看 Content-Type 再解码;API.PLUS 的具体端点行为需以官方文档核实。

JSON、表单与图片接口的响应设计,关键在顺序:先确定媒体类型(Content-Type)和状态码语义,再确定错误体结构,最后确定成功体字段与缓存头。把这几件事塞进一个“万能响应体”(例如永远返回 200 加大整数 code),就会让调用方无法用通用 HTTP 客户端做正确判断。本文只讨论与具体厂商无关的通用规范;API.PLUS 各端点的实际响应形态、字段名与错误码,应以官方文档为准,本文未做核验。

一、先固定媒体类型#

媒体类型决定解析器:解析器一旦选错,后面的字段设计都无从谈起。JSON 实体使用 application/json(JSON 语法见 RFC 8259);该类型默认按 UTF-8 处理,通常不需要再写 charset。图片等二进制实体直接返回对应类型,如 image/png、image/webp,不要在没有约定的情况下把图片塞进 JSON 的 base64 字段——体积会膨胀约三分之一,且调用方拿到的是“需要二次解码的字符串”,不是可直接落盘的字节流。

表单是请求侧格式,不是响应格式。提交用 application/x-www-form-urlencoded 还是 multipart/form-data(RFC 7578)取决于是否含文件;响应仍应统一为 JSON 或二进制,避免调用方需要同时维护两套响应解析逻辑。

二、状态码先分类,响应体再说明#

常见反模式是“业务码放在 body、HTTP 状态码永远是 200”。这会让网关、重试逻辑、监控和 SDK 都失去判断依据。合理分工是:HTTP 状态码表达结果类别,响应体表达具体原因。

状态码语义响应体形态
200 / 201成功、已创建JSON 数据体(或二进制资源)
400 / 422参数格式错误 / 语义校验失败JSON 错误体,含字段定位
401 / 403未认证 / 无权限JSON 错误体,不泄露内部细节
404资源不存在JSON 错误体,勿回落到 HTML 错误页
429超出频率或配额JSON 错误体,配合 Retry-After
5xx服务端故障JSON 错误体,含可追踪的 request_id

错误体结构可直接采用 RFC 9457(Problem Details for HTTP APIs)的最小字段:type、title、status、detail,再按需补 code 与 request_id。要点是机器可读的 code 与给人看的 message 分离,且不把堆栈、SQL、内网地址写进 detail。

三、图片接口的边界:失败路径最容易破约定#

图片端点的典型故障是:业务校验失败时返回了 HTML 错误页或空 200,调用方按 image/* 解码后拿到损坏文件。因此应明确两条规则:

  • 成功:返回正确 Content-Type、Content-Length,并按资源特性给出 ETag 或 Last-Modified 与 Cache-Control。
  • 失败:返回 JSON 错误体与对应状态码,不要返回空的或占位的图片。调用方应先读 Content-Type,再决定按二进制保存还是按 JSON 解析。

四、演示示例(未执行)#

以下请求与响应均为占位演示,域名为 example.com,密钥为 YOUR_KEY,未对任何真实端点发起调用。

curl -sS -D - https://api.example.com/v1/items/42 \
  -H "Authorization: Bearer YOUR_KEY"
{
  "type": "https://example.com/problems/rate-limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "请求超出当前时间窗口的配额",
  "code": "rate_limited",
  "request_id": "req_demo_0001"
}

五、发布前的检查清单#

  1. 每个端点是否只有一个主媒体类型,且错误路径与成功路径的媒体类型是否明确分离。
  2. 是否所有 4xx/5xx 都返回同构的错误体,且不包含内部实现细节。
  3. 图片端点出错时,是否可能返回成功状态码配空体或损坏数据。
  4. 限流与失败的响应是否给出 Retry-After,是否与幂等键约定一致。
  5. 字段命名、时间格式(建议 ISO 8601 带时区)、数字与字符串类型是否在文档中固定,不随版本漂移。

以上是通用做法,不构成对任何平台行为的陈述。若需确认 API.PLUS 的具体媒体类型、错误码枚举与缓存策略,仍需查阅其官方文档;本文材料不足以支持那部分结论。

作者:沐小悠

本文约 6 分钟读完 · 关键词:API 响应设计、Content-Type、错误模型、Problem Details、multipart/form-data

更多文章 GET 示例接口

「」标签下的其他文章