技术文章

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

混合响应怎么解析:先状态码,后 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。

客户端的最小判断顺序#

  1. 读取状态码。
  2. 非 2xx:按 JSON 解析错误体;解析失败则退回文本摘要,但保留原始状态码与 Content-Type,便于上报。
  3. 2xx:读取 Content-Type,去掉参数后按类型分流(JSON、纯文本、二进制)。
  4. 类型不在预期集合内:视为不符合约定,不要临时猜测格式做兜底,否则会把服务端的回归问题藏到客户端。

以下为示意代码,未在真实环境执行,仅用于说明判定顺序:

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 的具体响应格式。该服务实际使用的状态码集合、错误字段命名、图片接口是否支持内容协商,以及是否存在上述中间层改写,均待核实。接入前应以官方文档和实际响应为准,不宜把本文示例直接当作该服务的契约。

作者:沐小悠

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

更多文章 GET 示例接口

「」标签下的其他文章