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 |
| 成功响应 | 固定外层加 data | 303 跳转或 JSON | 二进制加响应头 |
| 校验失败 | 422 加字段级 details | 直接渲染错误,不跳转 | 错误码,不返回假图片 |
| 缓存重点 | 通常不缓存业务响应 | 不缓存含用户数据的页面 | ETag、Cache-Control 是核心 |
| 错误可读性 | 结构化,机器优先 | 可读文本,人优先 | 状态码加日志关联 id |
检查清单#
- 错误是否只有一套语义?HTTP 状态码与业务码是否分工明确、不互相覆盖?
- 每个响应(含图片)是否都带可追踪 id?
- JSON 的 null 与缺字段是否有文档约定?时间格式是否唯一?
- 表单的成功路径是否避免重复提交?失败路径是否保留字段错误?
- 图片是否设置了正确的 Content-Type、ETag 与缓存策略?失败时是否绝不返回 200?
- 内容协商与不支持的
Accept如何处理,是否写进了文档?
边界说明:本文不含实测。具体框架的默认状态码、CDN 对错误响应的缓存规则、以及 HTTP 规范对 303/406/422 的精确定义,均需以对应官方文档为准,本文未做核验,不据此下结论。