同一 API 返回三种内容:JSON、表单与图片响应的判别顺序
响应设计应先把成功响应的媒体类型与失败响应的统一包络定清楚,再处理内容协商、缓存和浏览器行为。JSON 适合结构化数据;表单端点的响应不应默认为 JSON;图片成功响应应返回真实图片,失败则用明确状态码和可解析错误体。API.PLUS 的具体端点行为缺少本次材料支持,需按实际文档核对。
同一服务里同时提供 JSON、表单和图片接口时,最容易出问题的地方是客户端不知道当前拿到的是哪一种响应,格式本身反倒不是关键。较稳妥的判别顺序是:先看 HTTP 状态码,再看 Content-Type,最后才解析正文;不要用 JSON.parse 去试探响应。API.PLUS 的具体端点行为缺少本次材料支持,下面把通用设计建议与需要按实际文档核对的项分开说明。
先判别响应类型,再解析内容#
- 状态码优先。4xx 或 5xx 响应即使正文看起来像正常数据,也不应当作成功结果处理。
- 以响应头为准。结构化数据应使用
application/json;图片应使用具体的image/*类型;表单提交后的响应则可能是重定向、HTML 或 JSON,必须在接口文档中写明。 Accept是偏好,不是命令。客户端可以声明希望接收 JSON,但服务器是否支持内容协商、协商失败时返回什么,仍要看接口约定。- 不要靠 URL 后缀猜类型。以
.json结尾的路径也可能返回错误页,图片地址也可能返回 JSON 错误体。
三类成功响应的最小约定#
| 场景 | 成功响应应明确什么 | 常见误区 |
|---|---|---|
| JSON 接口 | Content-Type: application/json、字符集、稳定的顶层结构,以及字段缺失与 null 的区别。 |
把登录页或网关 HTML 以 200 返回,客户端解析失败后误判为数据格式问题。 |
| 表单提交 | 写清成功后的响应形态:是 303 重定向到结果页,还是直接返回 JSON;同时说明失败时返回什么。 |
把请求体的 application/x-www-form-urlencoded 当成响应类型,进而默认响应一定是表单。 |
| 图片接口 | 成功时返回真实图片字节和正确的 image/* 类型;必要时说明尺寸、格式、缓存与条件请求策略。 |
失败时仍返回 200 和一张“默认图”,让调用方无法区分占位图与真实资源。 |
表单端点尤其需要区分“表单请求”和“表单响应”。浏览器提交表单后看到结果页,不代表供程序调用的接口也应返回 HTML;反过来,接口返回 JSON 也不代表表单提交失败。关键是同一端点是否有稳定、可记录的响应契约。
错误包络不要随成功类型分裂#
建议 JSON、表单和图片接口共享一套错误语义:用明确的 4xx/5xx 状态码表示失败,用稳定的机器可读错误码区分原因,再附上人类可读的说明。图片端点返回错误时,Content-Type 应如实标为 application/json 等实际类型,不要伪装成 image/png。浏览器通过 <img> 直接加载图片时通常不会展示错误正文,因此前端仍需根据状态码和加载失败事件提供兜底界面。
下面只是错误体示意,未实际执行,也不代表 API.PLUS 的现有字段:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json; charset=utf-8
{
"error": {
"code": "INVALID_ARGUMENT",
"message": "参数校验失败",
"details": [
{"field": "width", "reason": "must be a positive integer"}
]
}
}
错误体不宜包含堆栈、内部路径或数据库语句。是否返回请求追踪标识,应以服务端实际能力为准,不能由客户端假定一定存在。
内容协商与缓存的边界#
如果同一 URL 会根据 Accept 返回不同表示,应设置 Vary: Accept,避免缓存把图片响应交给期待 JSON 的调用方。图片可使用 ETag 或 Last-Modified 支持条件请求;涉及用户身份的 JSON 不应被标记为公共可缓存。具体缓存策略取决于资源敏感性和部署方式,不能只凭响应类型决定。
接入 API.PLUS 前应核对什么#
在缺少可核验接口文档的情况下,不应推断 API.PLUS 已采用上述任一约定。实际对接前至少核对:
- 每个端点的成功状态码与
Content-Type; - 表单端点的成功响应是重定向还是数据体,失败时是否仍返回 HTML;
- 图片端点失败时的状态码、错误体类型,以及是否可能返回 200 占位图;
- 是否支持内容协商、条件请求和缓存头,以及这些行为是否因端点而异。
这些是核对项,不是对 API.PLUS 现状的描述。把“成功形状”和“失败形状”分别固定下来,比在客户端堆叠格式试探更可靠。