技术文章

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

JSON、表单与图片接口的响应设计:先定内容类型,再定错误模型

一句话回答

建议把 Content-Type 与 HTTP 状态码作为第一层契约:JSON 使用稳定错误对象,表单明确重定向、HTML 或 JSON 分支,图片成功返回二进制且失败不要伪装成 200 图片。具体 API.PLUS 端点行为待核实。

JSON、表单和图片接口的响应设计,关键不是“都返回 JSON”,而是让调用方从状态码和 Content-Type 就能判断该用哪种解析器、成功还是失败。本文给出的是通用设计建议,不是 API.PLUS 官方规范;本次没有可核验的接口正文,涉及具体端点、字段和状态码的现状待核实。

第一层契约:内容类型与状态码#

建议先固定两件事:成功响应是什么媒体类型,失败响应又是什么媒体类型。JSON 接口统一使用 application/json; charset=utf-8(JavaScript Object Notation,JSON);图片成功响应使用对应的 image/png、image/jpeg 等类型;表单提交后的响应则要明确是重定向、HTML 还是 JSON。

不要让客户端靠猜字段判断结果。更稳妥的做法是:请求侧错误用 4xx,服务侧错误用 5xx,具体状态码在文档中固定;不要用 200 OK 包一个 {"success": false} 来代替错误状态。这样日志、网关和客户端都能按同一层语义处理。

JSON:稳定字段与错误对象#

  • 成功体只放资源或操作结果,避免重复封装 HTTP 状态码。
  • 错误体至少包含稳定的机器码、可读消息和请求标识,例如 code、message、request_id;字段级错误可放在 details。
  • 文档要写明字段缺失与 null 的区别;ID 建议用字符串,避免前端精度损失。
  • 新增字段通常可兼容,删除或改变字段含义应走版本化。

下面只是协议示意,未在真实服务执行:

{
  "code": "invalid_parameter",
  "message": "email 格式不正确",
  "request_id": "req_demo_001",
  "details": [{"field": "email", "reason": "format"}]
}

表单:请求编码不等于响应格式#

application/x-www-form-urlencoded 和 multipart/form-data 描述的是浏览器如何提交表单,不是响应应该长什么样。面向浏览器的表单,成功后可建议使用 303 重定向到结果页,降低刷新导致重复提交的风险;面向 API 客户端时,可通过 Accept 协商返回 JSON。失败时也应保持分支清楚:HTML 表单返回带错误提示的 HTML 和 4xx,JSON 客户端返回 JSON 错误。

错误页不要回显密码、令牌等敏感字段。若表单包含文件上传,还要在文档中写明大小上限、允许类型和超时,而不是只在失败时返回一句“上传失败”。

图片:成功返回二进制,失败不要伪装#

图片接口成功时应直接返回图片二进制,并配合 Content-Length、ETag、Cache-Control;需要下载时再用 Content-Disposition。失败时若返回 JSON,状态码应在 4xx 或 5xx,且 Content-Type 明确为 application/json。不建议用 200 OK 加一张占位图掩盖后端错误;如果产品确实要求占位图,至少要用非 2xx 状态码并在文档中写明,这是例外而非常规。

也不建议默认把图片转成 Base64 塞进 JSON:Base64 会增大约三分之一体积,并增加解析成本。只有调用方无法处理二进制时,才提供显式的格式参数。

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 12345
ETag: "demo-etag"
Cache-Control: public, max-age=3600

<binary>

以上为响应头示意,未实际执行。

发布前检查#

  1. 分别用带 Accept 和不带 Accept 的请求测试成功与失败响应,确认解析路径一致。
  2. 错误响应也要检查 Content-Type,并考虑加 X-Content-Type-Options: nosniff,避免浏览器错误嗅探。
  3. 限制错误体大小,日志脱敏,request_id 贯穿请求与响应。
  4. 文档写明分页、字段可空、重试语义和上传限制;涉及重复提交的写操作可评估幂等键。

一句话总结:统一的是“可判断”,不是“全部 JSON”。让状态码、Content-Type 和错误对象三者一致,调用方才能稳定处理。API.PLUS 的具体响应契约仍需以实际接口文档和联调结果为准。

作者:沐小悠

本文约 5 分钟读完 · 关键词:API 响应设计、JSON 响应、表单提交、图片接口、Content-Type

更多文章 GET 示例接口

「」标签下的其他文章