技术文章

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

JSON、表单与图片接口的响应契约:媒体类型协商、错误承载与边界清单

一句话回答

三种接口的响应设计应共用一套 HTTP 状态语义与错误结构,但各自守住自己的媒体类型:JSON 接口以 application/json 承载成功与失败,表单接口要区分请求格式与响应格式,图片接口在失败时必须把媒体类型切到非 image/* 的 JSON 类型,客户端才能正确分派。文章给出错误体字段建议、三种形态的响应对照表,以及空结果、部分成功、缓存与编码等边界清单。

核心要点 TL;DR
  • 响应设计先定三件事:媒体类型由谁协商、错误用哪种载荷表达、边界情况怎么让客户端判别。
  • 图片接口失败时必须切换媒体类型,否则客户端会把错误体当作图片解码。
  • 错误体建议只定义一个结构:机器码判类型,消息给人读,两者不要互相替代。

三种接口的响应设计,争议通常不在字段怎么命名,而在三件事谁说了算:媒体类型由谁协商、错误用什么载荷表达、边界情况怎么让客户端判别。一句话结论:用一套 HTTP 状态语义,三种表示各自守住自己的媒体类型,错误统一走一个机器可读结构。本文是通用设计建议,不针对某个具体服务的实测结论;涉及框架默认行为的部分,请以所用框架文档为准。

一、先让媒体类型成为第一判据#

响应头 Content-Type 是客户端分派处理逻辑的第一依据,不是装饰。它决定客户端是把响应体交给 JSON 解析器、表单渲染器,还是图片解码器。

  • JSON 接口:成功与失败都用 JSON 类媒体类型,不要用 text/html 返回一段 JSON 字符串再让客户端去解析。
  • 表单接口:application/x-www-form-urlencoded 与 multipart/form-data 描述的是请求侧载荷格式。响应侧不必“回表单”,返回 JSON 或重定向更常见。文档里要把请求格式与响应格式分开写。
  • 图片接口:成功时给出具体类型,如 image/png、image/jpeg,而不是 image/*;失败时不能仍标 image/png 却塞一段 JSON。

协商失败要有明确状态:请求体类型不被接受时用 415,Accept 无法满足时用 406。这是 HTTP 语义中的通用约定,具体实现以团队规范与框架文档为准,本文未联网核验任何框架的实际行为。

二、错误模型:一套结构,三种承载#

错误体建议只定义一个结构,字段至少包含:稳定的机器码、可读消息、字段级明细、可追踪 ID。机器码用于判断类型,消息用于人读,二者不要互相替代。

{
  "code": "INVALID_FIELD",
  "message": "参数校验失败",
  "details": [{"field": "email", "reason": "格式不正确"}],
  "trace_id": "YOUR_TRACE_ID"
}

以上为结构示意,未对任何真实服务执行,YOUR_TRACE_ID 为占位值。把错误体标准化为 application/problem+json 是一种常见做法,其规范编号与措辞请以 IETF 原文为准,本文未联网核验。

图片接口最容易踩的坑是:客户端拿到一段错误 JSON,却仍按 image/png 去解码。所以失败响应的关键动作是换媒体类型,客户端则以“Content-Type 不是 image/*”作为进入错误分支的判据。

接口形态成功 Content-Type失败 Content-Type客户端判别
JSONapplication/jsonapplication/problem+json 或 application/json状态码 + code 字段
表单application/json 或 HTML同上状态码 + code,或页面错误区
图片image/png 等具体类型非 image/* 的 JSON 类类型状态码 + Content-Type

是否用 200 再包一层业务错误,取决于调用方生态。对通用 HTTP 客户端与浏览器,用 4xx/5xx 更省事;若已有大量客户端依赖 200 判定,就要在文档里写死并保持兼容。这是取舍,不是规范强制。

三、边界条件清单#

  • 空结果与不存在:空列表返回 200 + 空数组;资源不存在返回 404。不要用 200 + null 把两者混同。
  • 部分成功:批量操作要么全成功,要么返回逐项结果,不要只给一个布尔值。
  • 大响应:图片与文件给出 Content-Length 和缓存头(ETag、Cache-Control);列表接口给出分页游标。
  • 可重试性:哪些 5xx 与超时可以重试,要在文档里写清,图片接口尤其如此。
  • 编码:JSON 默认 UTF-8;表单的字符集应显式声明,减少中文参数出现乱码的可能。

四、一份可评审的响应示例#

下面是失败响应的示意,仅用于说明头部与错误体的配合关系,未对真实端点执行。

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
Cache-Control: no-store

{
  "code": "INVALID_FIELD",
  "message": "参数校验失败",
  "details": [{"field": "email", "reason": "格式不正确"}],
  "trace_id": "YOUR_TRACE_ID"
}

把这三件事写进接口文档并配上示例,评审时就有可对照的条目:媒体类型是否唯一、错误体是否同构、边界是否都有明确状态码。具体到某个 API.PLUS 端点的实际响应字段与状态码,本文材料不足以确认,需以该服务当前文档为准。

常见问题(FAQ)

图片接口返回错误时可以用 200 加一段 JSON 吗?
不建议。更稳妥的做法是保留 4xx/5xx 状态码,并把 Content-Type 从 image/* 换成 JSON 类类型,客户端据此判断该走错误分支而不是图片解码分支。
表单接口的响应必须还是表单吗?
不必。表单描述的是请求侧的载荷格式(urlencoded 或 multipart),响应侧返回 JSON 或重定向更常见,关键是在文档里把请求格式与响应格式分开写清。

作者:沐小悠

本文约 6 分钟读完 · 关键词:JSON接口、表单接口、图片接口、响应设计、Content-Type

更多文章 GET 示例接口

「」标签下的其他文章