JSON、表单与图片接口的响应设计:先统一外层,再区分载荷
一句话回答
三类接口的响应应先统一外层:状态码表达协议结果、错误体固定为 JSON、每个响应带请求标识、客户端按 Content-Type 分支处理。表单接口的差异在于字段级错误结构与浏览器提交后的重定向;图片接口的差异在于成功返回二进制、失败必须返回 JSON,且缓存与分段能力需在文档中写明。
核心要点 TL;DR
- 失败一律返回 JSON 错误体,即使接口成功时返回的是图片字节
- 表单提交要区分浏览器直提与脚本调用,前者成功后通常需要重定向
- 批量与重试的边界要在文档里写明,不要让 2xx 里藏着未说明的失败项
三类接口的响应规范,应先定义共用的外层,再分别处理载荷形态。只按单一类型定规则,一旦系统里同时存在 JSON、表单提交和图片流,规则就会互相冲突。以下内容为设计建议与常见做法,未附可核验的规范原文或实测记录;涉及具体协议条款与实现能力处标注待核实。
共用的外层:四件事#
- 状态码只表达请求结果,不要统一返回 200。业务失败放在错误体的
error.code里,两层分工固定下来。状态码语义以 HTTP 规范为准,具体条款需查原文。 - 错误体统一为 JSON,字段固定:
code、message、field(可空)、request_id、retryable。字段名一旦公开,改动即视为破坏性变更。 - 每个响应都带请求标识,响应头与错误体里的值一致,否则排查时对不上日志。
- 客户端按 Content-Type 分支处理。这是图片接口能同时返回字节和错误的前提。
成功体的形状
建议用对象包裹列表,而不是顶层数组:{"items":[],"next_cursor":null}。这样后续加字段不必改结构。客户端忽略未知字段属于设计约定,不是所有语言的默认行为,需在文档中写明。
表单接口:把字段错误放进结构里#
- 提交格式主要是
application/x-www-form-urlencoded与multipart/form-data。服务端要么都识别,要么明确只接受一种,并在 415 响应里说清期望的类型。 - 校验失败建议用 422 或 400,配
errors数组,每项含字段路径与原因。只返回“参数错误”无法定位。 - 浏览器直接提交与脚本调用是两条路径:前者成功后通常应重定向到结果页,避免刷新造成重复提交;后者返回结构化 JSON。两种行为要分开写进文档,不要让同一个端点按 User-Agent 猜。
- 错误回显不要原样带回密码、令牌等敏感字段。
图片接口:二进制与错误体的切换点#
- 成功时返回真实图片类型、正确的
Content-Type与Content-Length,并提供ETag或Last-Modified让缓存可用。 - 失败时返回 JSON 且状态码非 2xx。这条不写清,客户端会把错误页的 HTML 当图片存下来。
- 是否支持
Range与 206 取决于实现,待核实;支持就必须在文档里写明单位与边界,不支持则应忽略该头而非报错。
| 接口类型 | 成功 Content-Type | 失败形态 |
|---|---|---|
| JSON | application/json | JSON 错误体,非 2xx |
| 表单 | JSON 或重定向 | JSON 错误体 + 字段级 errors |
| 图片 | image/* | JSON 错误体,非 2xx |
// 未执行的示例,仅示意字段,非真实响应
{
"error": {
"code": "INVALID_FIELD",
"message": "width must be between 1 and 4096",
"field": "width",
"request_id": "req_demo_0001",
"retryable": false
}
}
需要写进文档的边界#
- 部分成功:批量接口要么整批失败,要么在 2xx 里逐项给结果并给出成功与失败计数。不要在 2xx 中藏失败项却不说明。
- 重试:创建类接口返回 201 并带
Location;重试要靠服务端支持幂等键,头名与语义以服务端文档为准,待核实。 - 版本:新增字段一般兼容,删除字段或改变语义需要版本化。这一条是建议,不同团队的兼容承诺范围不同。
本文没有可引用的规范原文或测试记录,上述状态码、缓存头与幂等键的具体取值和实现细节,落地前需按所用框架与 HTTP 规范原文核对。
常见问题(FAQ)
图片接口出错时该返回 JSON 还是占位图?
建议返回 JSON 错误体并配非 2xx 状态码。返回占位图会让客户端无法区分“成功但图是占位”与“失败”,也会破坏缓存语义。前提是客户端按状态码和 Content-Type 分支处理。