技术文章

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

JSON、表单与图片接口的响应规范:先定外层,再定错误

一句话回答

同一套接口里,JSON、表单与图片三类响应应共用一层状态与错误约定,再分别确定载荷形态;图片接口尤其要保证失败时不会返回看似成功的二进制体。文章给出外层结构、字段约定与三类响应的对照表,示例为未执行的演示代码。

核心要点 TL;DR
  • 先定一层与载荷无关的外层(结果标识、错误码、请求标识),再按接口类型定载荷。
  • 图片接口的失败分支必须与成功分支在状态码和 Content-Type 上可区分。
  • 表单接口要区分浏览器原生提交与脚本提交,两者返回形态通常不同。

如果一个服务的 JSON 接口、表单接口和图片接口各自定义错误格式,调用方就得为每条路径写一套解析逻辑。更省事的做法是:先约定一层与载荷无关的外层结构,再让三类接口各自决定成功时返回什么。下面是可落地的设计顺序,示例为演示代码,未实际执行;API.PLUS 现有接口的实际字段与错误码表需以官方文档为准,本文不代为确认。

先定外层:与载荷无关的那部分#

外层只回答三个问题:这次调用是否被服务端接受、失败原因是什么、如何与日志对齐。它不应随接口类型变化。

  • 结果标识:用字符串错误码,不用裸数字。数字码一旦扩张就要靠文档记,字符串码自身可读。
  • 请求标识:服务端生成,回写在响应体与响应头里,便于用户报障时对齐日志。
  • 字段级明细:参数校验失败时给出字段名与原因,避免调用方靠猜。
{
  "code": "INVALID_PARAM",
  "message": "参数校验失败",
  "request_id": "req_demo_0001",
  "details": [
    {"field": "size", "reason": "must be <= 4096"}
  ]
}

注意成功响应是否也带这层外层,需要一次性定死:如果成功时直接返回业务对象、失败时返回错误对象,调用方就必须先判断结构再取字段。两种都能用,混用不行。

JSON 响应的字段约定#

  • 类型稳定:同一字段不要这次是字符串、下次是数字。数值型 ID 若可能超出调用方语言的整数精度,直接以字符串返回。
  • 空值策略:明确“字段缺失”和“字段为 null”是否等价。建议不等价:缺失表示未提供,null 表示明确为空。
  • 时间与单位:时间统一用带时区的 ISO 8601 字符串,或在字段名里写明时区;数值字段在文档中标单位。
  • 列表分页:游标或页码只选一种,并把“是否还有下一页”作为显式字段,而不是靠返回条数推断。

表单接口:先分清谁来提交#

表单接口的响应形态取决于提交方。浏览器原生提交需要一个可导航的结果,脚本提交需要可解析的数据。建议按 Accept 或显式的提交模式区分:

  • 原生提交成功:返回 303 See Other 重定向到结果页,避免刷新重复提交。
  • 原生提交失败:返回 4xx 并重新渲染表单,错误信息就近显示。
  • 脚本提交:成功与失败都返回 JSON,响应头 Content-Type: application/json。

不要用 200 状态码包裹失败结果再让前端自己判断——这会让重试、监控和缓存都失去判断依据。

图片接口:成功是二进制,失败不能像成功#

图片接口最容易出的事故,是失败时仍返回 200 和一段错误文本或占位图,调用方按图片处理后才在渲染层报错。可用的约定是:

  • 成功:2xx,Content-Type 为具体图片类型(如 image/png),响应体为字节流,不要塞进 JSON 的 base64 字段。
  • 失败:4xx/5xx,Content-Type 为 application/json,响应体使用与 JSON 接口相同的外层错误结构。
  • 元信息:尺寸、来源、缓存时长放在响应头,避免为了读元信息再发一次请求。
  • 内容协商:若支持格式转换,用 Accept 表达偏好,并在无法满足时明确返回 406 或降级到默认格式——选哪种要写进文档。

三类响应的对照

维度JSON 接口表单接口图片接口
成功载荷JSON 对象重定向或 HTML图片字节流
失败载荷JSON 错误外层4xx + 表单/JSONJSON 错误外层
关键响应头Content-TypeLocationContent-Type、缓存头
重试判断按状态码按状态码按状态码,不看字节长度

需要向平台方确认的部分#

以上是设计建议,不是对某个具体服务的描述。若要在 API.PLUS 上对接现有接口,以下信息本文无法提供,需查官方文档或实测确认:现有接口是否已统一外层、错误码清单、图片接口失败时的实际 Content-Type、以及是否支持 Accept 协商。在这些信息确认之前,客户端侧较稳妥的做法是先判断状态码与 Content-Type,再决定按 JSON 还是字节流解析。

作者:沐小悠

本文约 5 分钟读完 · 关键词:API 响应设计、JSON 响应结构、表单接口、图片接口、错误响应

更多文章 GET 示例接口

「」标签下的其他文章