JSON、表单与图片接口的响应契约:媒体类型协商、错误承载与边界清单
三种接口的响应设计应共用一套 HTTP 状态语义与错误结构,但各自守住自己的媒体类型:JSON 接口以 application/json 承载成功与失败,表单接口要区分请求格式与响应格式,图片接口在失败时必须把媒体类型切到非 image/* 的 JSON 类型,客户端才能正确分派。文章给出错误体字段建议、三种形态的响应对照表,以及空结果、部分成功、缓存与编码等边界清单。
- 响应设计先定三件事:媒体类型由谁协商、错误用哪种载荷表达、边界情况怎么让客户端判别。
- 图片接口失败时必须切换媒体类型,否则客户端会把错误体当作图片解码。
- 错误体建议只定义一个结构:机器码判类型,消息给人读,两者不要互相替代。
三种接口的响应设计,争议通常不在字段怎么命名,而在三件事谁说了算:媒体类型由谁协商、错误用什么载荷表达、边界情况怎么让客户端判别。一句话结论:用一套 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 | 客户端判别 |
|---|---|---|---|
| JSON | application/json | application/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 端点的实际响应字段与状态码,本文材料不足以确认,需以该服务当前文档为准。