技术文章

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

JSON、表单与图片接口的响应设计:同一份契约,三种编码

一句话回答

三类接口的响应差异主要在编码方式和调用方,不在契约本身。建议先统一错误语义、状态码类别与缓存语义,再分别确定 JSON 的稳定外层结构、表单的提交后跳转与字段级错误、图片的 Content-Type 与条件请求。错误一律不能伪装成 200;图片接口尤其要防止错误占位图被 CDN 缓存。

JSON、表单和图片接口看起来是三种设计,实际是同一份响应契约的三种编码。先定与编码无关的部分——错误怎么表达、状态码表示到哪一层、缓存由谁决定——再分别处理 JSON 的字段结构、表单的提交后跳转、图片的二进制响应头。本文不含联网核验:涉及具体框架默认行为、CDN 默认缓存策略与规范原文的内容,均按“待核实”处理,需要以你实际使用的文档为准。

先定三件与编码无关的事#

  • 错误语义:HTTP 状态码表达“类别”(成功、客户端错误、服务端错误、限流),业务码表达“细分原因”。用 200 包裹一切错误会让网关、重试库、监控全部失效——这是通例性判断,不是某份文档的结论。
  • 可追踪标识:响应里回传 request id 或 trace id,图片接口也一样(可放在响应头)。没有它,前端报“接口错了”时你无法定位。
  • 内容协商:声明服务端支持哪些 Accept,不支持的返回 406 或明确的兜底结构。HTTP 对 406 的定义请以规范原文为准(本次未核验)。

JSON 响应:外层结构要稳定,内层字段才可演进#

建议成功与失败使用两套固定外层,让调用方可以只判断一次:

// 未执行的示例,仅演示结构,非真实接口输出
// 成功
{ "data": { "id": "u_123" }, "meta": { "request_id": "req_xxx" } }
// 失败
{ "error": { "code": "INVALID_FIELD", "message": "参数校验失败",
             "details": [{ "field": "email", "reason": "格式错误" }] },
  "meta": { "request_id": "req_xxx" } }

几个容易踩的点:

  • null 与缺字段要区分并写进文档。“字段不存在”和“字段存在但为空”对客户端是两种分支,含混会让前端写出 if (!obj.x) 这类既判空又判存在的代码。
  • 时间统一为 UTC 的 ISO 8601 字符串,不要混用秒级时间戳与本地时区字符串;如果必须用时间戳,明确单位。
  • 分页优先用游标。offset 分页在数据变动时会漏项或重复,这是推断而非实测结论;是否可接受取决于你的数据变更频率。
  • 错误详情按字段给出,而不是只给一句“参数错误”,否则表单侧无法把错误定位到具体输入框。

表单提交:先确认调用方是谁#

表单接口的响应设计分歧,本质是消费方不同:浏览器整页导航提交,和 fetch / XHR 提交,需要的响应完全不一样。

  • 整页提交:成功后用 303 重定向到结果页(Post/Redirect/Get),避免刷新重复提交;失败时不要重定向,直接返回带字段错误的 HTML,或用会话暂存后重定向回填。
  • 脚本提交:返回 JSON,字段级错误结构与上文一致。校验失败常用 422,请求体无法解析用 400,媒体类型不对用 415,体积超限用 413——这些是 HTTP 状态码的通用语义,具体边界建议在自己文档里写死。
  • multipart 上传:在响应里明确区分“格式被拒”和“超过上限”,两者前端处理方式不同;同时给出允许的类型与大小上限,不要只返回一句失败。
  • 校验失败不能用重定向表达,因为重定向会丢掉错误上下文,用户回来看到的是空白表单。

图片与二进制:状态码和响应头就是契约#

  • 必须返回真实的 Content-Type,不要用 application/octet-stream 兜底一切,否则浏览器不会内联渲染。
  • 设置 ETag 或 Last-Modified,支持 If-None-Match / If-Modified-Since 返回 304,减少重复传输。
  • 错误绝不能返回 200 加一张占位图。图片接口通常挂在 CDN 后面,200 的错误图会被缓存并在长时间内持续命中,问题会被放大。占位图属于成功响应的一种,应由业务显式请求或由前端兜底,而不是服务端在失败时伪装。
  • 需要下载而非预览时用 Content-Disposition: attachment,并在文档里写明。
  • 图片接口出错时返回 JSON,会让只接受图片的调用方无法解析。建议二选一并写进文档:错误统一走状态码加响应头(如错误码头),或按 Accept 返回对应结构。这一条是设计建议,不是标准要求。

三类响应的对照#

维度JSON 接口表单接口图片接口
主要消费方脚本、移动端浏览器导航或脚本浏览器、img 标签、CDN
成功响应固定外层加 data303 跳转或 JSON二进制加响应头
校验失败422 加字段级 details直接渲染错误,不跳转错误码,不返回假图片
缓存重点通常不缓存业务响应不缓存含用户数据的页面ETag、Cache-Control 是核心
错误可读性结构化,机器优先可读文本,人优先状态码加日志关联 id

检查清单#

  1. 错误是否只有一套语义?HTTP 状态码与业务码是否分工明确、不互相覆盖?
  2. 每个响应(含图片)是否都带可追踪 id?
  3. JSON 的 null 与缺字段是否有文档约定?时间格式是否唯一?
  4. 表单的成功路径是否避免重复提交?失败路径是否保留字段错误?
  5. 图片是否设置了正确的 Content-Type、ETag 与缓存策略?失败时是否绝不返回 200?
  6. 内容协商与不支持的 Accept 如何处理,是否写进了文档?
边界说明:本文不含实测。具体框架的默认状态码、CDN 对错误响应的缓存规则、以及 HTTP 规范对 303/406/422 的精确定义,均需以对应官方文档为准,本文未做核验,不据此下结论。

作者:沐小悠

本文约 7 分钟读完 · 关键词:JSON 响应设计、表单接口响应、图片接口缓存、HTTP 状态码、错误契约

更多文章 GET 示例接口

「」标签下的其他文章