技术文章

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

JSON、表单、图片接口的响应设计规范:成功定一种类型,失败定一个包络

一句话回答

三类响应共用的最小规范是:每个端点只承诺一种成功媒体类型,所有失败统一返回同一结构的 JSON 错误包络;媒体类型由路径或显式参数确定而不是靠 Accept 猜测,二进制响应的元数据放在头部,不要用占位图代替错误。

先给出结论:为每个端点固定一种成功媒体类型,并让所有失败共用同一结构的 JSON 错误包络,JSON、表单、图片三类接口便能共用一套客户端判别逻辑。以下属于设计层面的规范建议;API.PLUS 各端点的实际字段、状态码与媒体类型,本次材料未提供,需对照官方文档核对(待核实)。

成功响应:一个端点只承诺一种媒体类型#

如果同一个路径会根据参数在 JSON 和图片之间切换,客户端在发请求前就无法确定该按哪种方式解析,只能靠嗅探响应头来补判断。更稳妥的做法是用路径区分(例如 /data 与 /image),或在文档中把参数与媒体类型的对应关系写成固定规则,而不是让 Accept 去猜。

文本类响应应显式带 charset;JSON 使用 application/json,不要在响应体里再包一层与 HTTP 语义重复的“成功/失败”字段后仍然返回 200。

错误包络:失败不跟随成功类型#

图片接口失败时返回一张“错误图”,是常见但代价高的做法:客户端拿到的仍是 200,只有解码后才发现内容不对,缓存层也会把这张图当成正常结果存下来。除非文档明确承诺占位图语义,否则失败应返回错误状态码加 JSON 体。

下面是一个结构示例(占位字段,未执行,仅示意形状):

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "too many requests",
    "request_id": "YOUR_REQUEST_ID"
  }
}

约定:code 是稳定、可枚举的机器可读值,新增只能追加不能改义;message 面向人,允许调整措辞;request_id 用于和日志对账。三者缺一,排障时就只能靠时间戳猜。

内容协商的边界要写死#

Accept 表达的是偏好,不是命令。当请求的类型确实无法满足时,是返回 406 还是降级为默认类型,两种都可以,但必须在一个版本内保持一致并写进文档。同一端点这次降级、下次报错,比选错方案更难排查。

图片与二进制:元数据放头,不放另一个接口#

尺寸、格式、过期时间应通过 Content-Type、Content-Length、ETag、Cache-Control 表达,不要让客户端先请求 JSON 拿元信息、再请求字节流——那会把一次失败拆成两次失败。若确实需要元数据,可用独立的 HEAD 或元信息端点,并保证它与 GET 的一致性有明确定义。

表单既是请求格式,也可能是响应格式#

application/x-www-form-urlencoded 与 multipart/form-data 的主要差别在于是否承载文件;请求侧按此选型即可。响应侧返回表单编码的情况较少见,若确有需要,Content-Type 必须显式声明,且不能与 JSON 错误包络共用同一状态码语义——错误体永远走 JSON,与成功体是什么格式无关。

上线前的最小核对清单#

  1. 每个端点的成功媒体类型是否唯一且写进文档。
  2. 错误体是否为固定结构,code 是否可枚举。
  3. 是否存在用 200 携带错误的路径。
  4. 二进制响应是否带缓存与校验头。
  5. 内容无法满足时,是报错还是降级,是否只有一种行为。
  6. request_id 是否同时出现在响应头或响应体与日志中。

以上规范与具体实现无关,因此在任何语言栈里都能先落地;代价是需要一次性梳理已有端点的历史行为。若有端点已在不合规状态下被调用,迁移顺序与兼容窗口属于另一个需要单独评估的问题,本次材料不足以给出结论。

作者:沐小悠

本文约 4 分钟读完 · 关键词:响应设计、Content-Type、错误包络、内容协商、图片接口

更多文章 GET 示例接口

「」标签下的其他文章