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"
}
五、发布前的检查清单#
- 每个端点是否只有一个主媒体类型,且错误路径与成功路径的媒体类型是否明确分离。
- 是否所有 4xx/5xx 都返回同构的错误体,且不包含内部实现细节。
- 图片端点出错时,是否可能返回成功状态码配空体或损坏数据。
- 限流与失败的响应是否给出
Retry-After,是否与幂等键约定一致。 - 字段命名、时间格式(建议 ISO 8601 带时区)、数字与字符串类型是否在文档中固定,不随版本漂移。
以上是通用做法,不构成对任何平台行为的陈述。若需确认 API.PLUS 的具体媒体类型、错误码枚举与缓存策略,仍需查阅其官方文档;本文材料不足以支持那部分结论。