技术文章

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

JSON、表单、图片接口的响应设计:先让客户端能判断“成功与否”

一句话回答

三类接口的响应设计应共用同一套判定规则:状态码与响应体一致、错误对象结构固定、内容协商明确。JSON 适合固定信封与字段级错误,表单提交要在 JSON 结果与重定向之间二选一,图片接口的元信息应放头部而不是塞进 JSON 包裹。

核心要点 TL;DR
  • 响应设计的首要目标是让客户端不读文档也能判断成功、失败与可否重试。
  • 避免 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 时,状态码取值、错误码枚举与是否存在统一信封,均需以该平台当前文档为准,本文未做核验。

常见问题(FAQ)

JSON 接口应该用统一信封还是直接返回数据?
两种都可行,关键是同一个 API 内保持一致。统一信封的价值在于客户端只判断一次成功与否,分页等元信息也有固定位置;代价是多一层嵌套。若选择裸对象,需要另用状态码和头部承载错误与分页信息。
表单提交成功后返回 JSON 还是重定向?
取决于调用方。由前端 fetch 调用时返回 JSON 结果;由浏览器原生表单直接提交时,用重定向到结果页更自然。两者混用会让调用方拿到意料之外的 HTML。
图片接口出错时能返回一张占位图吗?
只有当接口本身定位就是占位图服务时才可以,并且要在文档中写明。普通图片接口返回占位图加 200,会让客户端无法区分“图存在”与“图缺失”,破坏缓存与重试判断。

作者:沐小悠

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

更多文章 GET 示例接口

「」标签下的其他文章