技术文章

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

JSON / 表单 / 图片接口的响应设计规范:先确定失败响应的结构,再确定成功响应的结构

一句话回答

三类接口的响应设计共享同一骨架:状态码定结果类别、Content-Type 声明表示格式、响应体承载细节。差异主要在响应体放什么:JSON 要固定错误结构与数值精度边界,表单接口的响应通常仍是 JSON 并需处理重复提交,图片接口应把字节放响应体、元数据放响应头,并用 4xx/5xx 区分失败与占位图。本文示例均为示意,未执行;涉及具体标准条款的部分标注待核实。

核心要点 TL;DR
  • 失败响应要有固定字段和明确的 Content-Type,不要用 200 加业务失败标志承载错误。
  • 超过 2^53 的整数 ID 建议用字符串,避免在 JS 侧丢精度。
  • 图片失败不要返回 200 加占位图,客户端无法据此区分成功与失败。

JSON、表单、图片三类接口看起来是三种格式问题,实际上是同一套响应契约的三次变形:用 HTTP 状态码表达结果类别,用 Content-Type 声明表示格式,用响应体承载细节。三者共享这个骨架,差异集中在“响应体里放什么”。本文不含实测,代码与报文均为示意、未执行;涉及具体标准条款的部分本次没有可核验来源,标注为待核实。

通用骨架:状态码表达结果类别,响应体表达细节#

建议把 2xx 严格限定为“请求被正常处理”。用 200 加 {"success": false} 承载业务失败,会让缓存、重试、监控和网关的默认策略全部失效——它们只看状态码。

  • 失败响应固定少量字段:机器可读的 code、人类可读的 message、可选的 details(字段级原因)、可选的 requestId(用于对日志)。
  • 失败响应同样要有 Content-Type。返回空体加 500 是最难排查的一类实现。
  • 客户端 Accept 与服务端实际返回的类型应一致;服务端做了内容协商,就要带 Vary。

JSON 接口:顶层结构与可演进字段#

建议顶层始终是对象,而不是裸数组。裸数组没有位置放分页游标、总量或后续的扩展字段,一旦要加就只能破坏性改版。

  • 命名风格、时间格式、空值语义要在文档里一次定清。尤其是 null 与字段缺失的区别:“值为空”和“未提供”是两件事,客户端的分支逻辑依赖这个区分。
  • 大整数 ID 用字符串。多数 JavaScript 运行时把 JSON 数字解析为双精度浮点,超过 253 的整数会丢精度,这是语言侧事实,不是接口设计偏好。
  • 金额用最小货币单位的整数或字符串,避免浮点累加误差。

错误体形状示意(占位值,未执行):

{
  "code": "INVALID_FIELD",
  "message": "字段校验失败",
  "details": [{"field": "email", "reason": "格式不正确"}],
  "requestId": "YOUR_REQUEST_ID"
}

业界有一个专门描述 HTTP 错误体的规范(Problem Details for HTTP APIs),其字段名与适用范围以原文为准,本文未核验条款,待核实。是否采用它,比采用哪个更重要:一旦定了就全站统一。

表单接口:请求侧是表单,响应侧通常仍是 JSON#

表单接口的分歧点常被误放在响应上,其实关键在请求的内容类型:application/x-www-form-urlencoded 与 multipart/form-data 的边界不同(后者用于文件与二进制部分)。响应侧建议显式返回 application/json; charset=utf-8,让前端用同一套解析逻辑处理所有端点。

  • 浏览器直出的表单,POST 成功后返回 303 加 Location,可避免刷新导致重复提交;这是实践建议,具体取舍取决于调用方形态。
  • 校验失败用 400 还是 422,两者都有人用。重点不是选哪个,而是全站只选一个并写进文档,不要按端点随机分布。
  • 批量提交的“部分成功”必须显式建模:要么整体失败,要么返回逐条结果数组,不要用 200 让调用方自己猜哪几条失败了。

图片接口:字节放体,元数据放头#

成功的图片响应应明确 Content-Type(如 image/png)、给出 Content-Length,并配合 ETag 与 Cache-Control 支持条件请求;命中缓存时返回 304 且无响应体。宽度、高度、色彩空间这类元数据放在响应头或单独的 JSON 端点,不要混进图片字节里让客户端二次解析。

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 20480
Cache-Control: public, max-age=300
ETag: "YOUR_ETAG"
Vary: Accept

以上为示意报文,非真实响应。失败时不要返回 200 加一张“错误占位图”——客户端无法区分成功与失败,缓存还会把占位图存下来。若业务确实需要占位图,就用 4xx/5xx,并让错误响应的 Content-Type 与成功时不同。

另外,把图片 base64 塞进 JSON 作为默认通道会让体积增大约三分之一,只适合小图标等窄场景。

三类接口对照#

维度JSON表单图片
成功 Content-Typeapplication/jsonapplication/json 或 HTMLimage/*
失败表达4xx/5xx + 统一错误体同左,或 303 重定向回表单页4xx/5xx,体可为空或错误体
缓存重点通常 no-store通常 no-storeETag / Cache-Control / 304
易错点大整数精度、null 语义重复提交、部分成功错误占位图配 200

边界与待核实项#

状态码的具体选择、错误体规范条款、时间格式标准条目,本次均无可核验来源,待核实。条件请求与范围请求是否在你的框架和网关链路上真正生效,需要自行验证,本文未做测试。

常见问题(FAQ)

表单提交成功后该返回 HTML 还是 JSON?
取决于调用方。浏览器表单常需要 303 重定向避免刷新重提交;前端用 fetch 提交时通常返回 JSON。同一端点不要按 Accept 随机切换语义,应拆成两个端点或明确文档。
图片接口需要返回 JSON 错误体吗?
不必强求。关键是失败状态码可被客户端识别,且错误响应自身的 Content-Type 与成功时不同,避免客户端把错误体当图片渲染。

作者:沐小悠

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

更多文章 GET 示例接口

「」标签下的其他文章