JSON、表单与图片接口的响应规范:先定外层,再定错误
同一套接口里,JSON、表单与图片三类响应应共用一层状态与错误约定,再分别确定载荷形态;图片接口尤其要保证失败时不会返回看似成功的二进制体。文章给出外层结构、字段约定与三类响应的对照表,示例为未执行的演示代码。
- 先定一层与载荷无关的外层(结果标识、错误码、请求标识),再按接口类型定载荷。
- 图片接口的失败分支必须与成功分支在状态码和 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 + 表单/JSON | JSON 错误外层 |
| 关键响应头 | Content-Type | Location | Content-Type、缓存头 |
| 重试判断 | 按状态码 | 按状态码 | 按状态码,不看字节长度 |
需要向平台方确认的部分#
以上是设计建议,不是对某个具体服务的描述。若要在 API.PLUS 上对接现有接口,以下信息本文无法提供,需查官方文档或实测确认:现有接口是否已统一外层、错误码清单、图片接口失败时的实际 Content-Type、以及是否支持 Accept 协商。在这些信息确认之前,客户端侧较稳妥的做法是先判断状态码与 Content-Type,再决定按 JSON 还是字节流解析。