混合响应怎么解析:先状态码,后 Content-Type
当一个接口同时返回 JSON、表单和图片时,稳定的做法是先用 HTTP 状态码判断成败,再用 Content-Type 决定解析通道;错误体统一为 JSON,图片接口失败时不要用 200 加占位图表示。文中给出客户端的最小判定顺序,并说明这些是通用约定,API.PLUS 的具体响应格式本次材料未提供,需以官方文档核实。
当一个服务同时输出 JSON、表单编码和图片,最容易出错的地方是同一个失败在三种通道里表现得不一样,而不是各格式本身。一种可行的做法是:先用 HTTP 状态码判断成败,再用 Content-Type 决定解析方式,错误体一律 JSON。图片接口失败时,不要把错误留在图片通道里。以下属于通用设计约定,不是对某个具体服务现状的描述。
先定“怎么判断失败”,再定“怎么解析”#
- 状态码负责判断成败。只有 2xx 才尝试解析成功响应体;非 2xx 一律按错误体处理,不因为响应体能被解析成图片或 JSON 就当作成功。
- Content-Type 负责决定解析方式。客户端应以响应头中完整的媒体类型为准(例如
application/json; charset=utf-8),不要靠 URL 后缀、请求参数里的format或文件名去推断。这两类信息由调用方控制,不能当作服务端的声明。 - 错误体固定为 JSON。即使调用方请求的是图片或表单,失败时也应把 Content-Type 切回
application/json,返回与其它接口结构相同的错误对象。这样客户端只需要一个错误解析器。
图片接口:失败要离开二进制通道#
用 200 返回一张占位图或零字节流表示失败,是最难排查的一种设计:图片解码环节会“成功”,调用方只能靠图像内容猜测结果,而图像内容不是可枚举的约定。建议失败时返回非 2xx,并把 Content-Type 切回 application/json。
成功路径上,尺寸、缓存策略这类元数据放在响应头里,比把二进制包成 base64 塞进 JSON 更省事;后者会让体积膨胀,也让客户端多一步解码。二进制响应不要附加 charset 参数,它只对文本类型有意义。
表单响应:输入可以是表单,输出尽量不是#
请求使用 application/x-www-form-urlencoded 或 multipart/form-data 是合理的,文件上传和浏览器原生提交都依赖它。但响应体再回到表单编码通常没有收益:嵌套结构和类型(布尔、数字、null)在表单编码里没有通用表达,客户端要二次转换。除非调用方就是浏览器原生表单提交并直接渲染结果,否则响应统一用 JSON。
客户端的最小判断顺序#
- 读取状态码。
- 非 2xx:按 JSON 解析错误体;解析失败则退回文本摘要,但保留原始状态码与 Content-Type,便于上报。
- 2xx:读取 Content-Type,去掉参数后按类型分流(JSON、纯文本、二进制)。
- 类型不在预期集合内:视为不符合约定,不要临时猜测格式做兜底,否则会把服务端的回归问题藏到客户端。
以下为示意代码,未在真实环境执行,仅用于说明判定顺序:
async function readResponse(res) {
const status = res.status;
const type = (res.headers.get('content-type') || '').split(';')[0].trim();
if (status < 200 || status >= 300) {
if (type === 'application/json') {
return { ok: false, status, error: await res.json() };
}
return { ok: false, status, error: { message: await res.text() } };
}
if (type === 'application/json') return { ok: true, status, data: await res.json() };
if (type === 'text/plain') return { ok: true, status, data: await res.text() };
if (type.startsWith('image/')) return { ok: true, status, data: await res.blob() };
return { ok: false, status, error: { message: 'unexpected content-type: ' + type } };
}
边界与待核实#
以上是约定层面的建议,落地效果取决于链路是否忠实传递头部。若中间存在 CDN 或 API 网关,需要确认它们是否改写 Content-Type、是否保留自定义头、是否会在错误页替换响应体——这些都会让“按头部判断”的前提失效。
本文没有提供 API.PLUS 的具体响应格式。该服务实际使用的状态码集合、错误字段命名、图片接口是否支持内容协商,以及是否存在上述中间层改写,均待核实。接入前应以官方文档和实际响应为准,不宜把本文示例直接当作该服务的契约。