JSON / 表单 / 图片接口的响应设计规范:先确定失败响应的结构,再确定成功响应的结构
三类接口的响应设计共享同一骨架:状态码定结果类别、Content-Type 声明表示格式、响应体承载细节。差异主要在响应体放什么:JSON 要固定错误结构与数值精度边界,表单接口的响应通常仍是 JSON 并需处理重复提交,图片接口应把字节放响应体、元数据放响应头,并用 4xx/5xx 区分失败与占位图。本文示例均为示意,未执行;涉及具体标准条款的部分标注待核实。
- 失败响应要有固定字段和明确的 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-Type | application/json | application/json 或 HTML | image/* |
| 失败表达 | 4xx/5xx + 统一错误体 | 同左,或 303 重定向回表单页 | 4xx/5xx,体可为空或错误体 |
| 缓存重点 | 通常 no-store | 通常 no-store | ETag / Cache-Control / 304 |
| 易错点 | 大整数精度、null 语义 | 重复提交、部分成功 | 错误占位图配 200 |
边界与待核实项#
状态码的具体选择、错误体规范条款、时间格式标准条目,本次均无可核验来源,待核实。条件请求与范围请求是否在你的框架和网关链路上真正生效,需要自行验证,本文未做测试。