技术文章

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

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失败形态
JSONapplication/jsonJSON 错误体,非 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 分支处理。

作者:沐小悠

本文约 5 分钟读完 · 关键词:API 响应设计、JSON 错误体、表单接口、图片接口、内容协商

更多文章 GET 示例接口

「」标签下的其他文章