JSON、表单、图片接口的响应设计:先让客户端能判断“成功与否”
三类接口的响应设计应共用同一套判定规则:状态码与响应体一致、错误对象结构固定、内容协商明确。JSON 适合固定信封与字段级错误,表单提交要在 JSON 结果与重定向之间二选一,图片接口的元信息应放头部而不是塞进 JSON 包裹。
- 响应设计的首要目标是让客户端不读文档也能判断成功、失败与可否重试。
- 避免 200 状态码包裹业务错误,否则重试、缓存、监控三层都会失真。
- 图片接口失败时不要返回占位图加 200,除非该接口本身定位为占位图服务。
三类接口的响应设计,核心问题不是“格式好不好看”,而是让客户端在不读文档的情况下判定三件事:这次调用成功还是失败、失败能不能重试、数据在哪一层。下面按内容类型分别说明。文中不涉及 API.PLUS 具体端点的字段名与状态码,这些需要以平台文档为准,本文未做核验。
一、先定三条公共契约#
- 状态码与响应体一致:不要在 200 里塞
{"code":500}。状态码是网关、缓存、监控和客户端库共同读取的第一手信号,一旦被架空,重试策略与告警都会失真。 - 错误对象结构固定:至少包含机器可读的错误码、面向人的说明、可用于排障的请求标识。字段名一次定好,不要按接口各写一套。
- 内容协商明确:同一个地址可能返回 JSON 或二进制,应通过
Accept表达偏好,并把“无法满足时怎么办”写进文档,而不是靠调用方试错。
二、JSON:信封与裸对象的取舍#
两种做法都成立,关键是同一 API 内保持一致。统一信封的价值是客户端只判断一次成功与否,分页游标、总数等元信息也有固定位置;代价是多一层嵌套。若选择直接返回数据对象,就要接受错误信息和分页信息改由状态码与响应头承载。
以下是错误响应的结构示意,未执行的示例,仅表达字段布局,不代表任何真实接口的实际输出:
{
"error": {
"code": "INVALID_PARAM",
"message": "page_size 必须在 1 到 100 之间",
"field": "page_size",
"request_id": "req_demo_0001"
}
}
字段级错误建议用数组承载,一次返回全部校验失败项,而不是让调用方逐条重试修正。
三、表单提交:结果与重定向二选一#
表单类接口的响应形态要先看调用方。由前端脚本提交时,返回 JSON 结果最直接;由浏览器原生表单直接提交时,成功后重定向到结果页更自然。两者混用,最典型的故障是前端 fetch 拿到一段 HTML 却按 JSON 解析。
校验失败建议返回可区分的客户端错误状态码,并在响应体中给出字段名与原因的对应关系;服务端内部异常则不应回显堆栈。
四、图片接口:元信息放头部#
成功时响应体就是二进制本身,版本、尺寸、校验等元信息只能放在头部:Content-Type 要准确,Content-Length 便于调用方显示进度,ETag 与 Cache-Control 决定能否复用已下载内容。把图片转成 base64 再包进 JSON,只在调试或极小尺寸时考虑,常规传输会放大体积并失去流式处理能力。
失败时不要返回占位图配 200,除非该接口本身就是占位图服务。否则客户端无法区分“图存在”与“图缺失”,缓存层也会把一次失败当作可缓存的成功结果。
五、三类响应的对照#
| 类型 | 成功体 | 失败体 | 主要缓存依据 |
|---|---|---|---|
| JSON | 信封或数据对象,结构固定 | 固定错误对象 + 对应状态码 | 按业务语义设定,默认谨慎 |
| 表单 | JSON 结果或重定向 | 字段级错误数组 | 一般不缓存 |
| 图片 | 二进制 + 准确的内容头 | 错误对象或空体 + 错误码 | ETag / Cache-Control |
六、需要提前定的边界条件#
- 空结果与不存在要分开:查询返回空列表是成功,单个资源不存在是失败,两者不能都写成 200 加空体。
- 批量操作的部分失败:要么整批失败并说明原因,要么逐项给出状态,不要只返回一句“部分成功”。
- 可重试性要显式:写操作配合幂等键,让客户端在超时后知道重发是否安全。
以上是设计层面的建议,不构成对任何具体平台行为的描述。落地到 API.PLUS 时,状态码取值、错误码枚举与是否存在统一信封,均需以该平台当前文档为准,本文未做核验。