技术文章

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

JSON、表单与图片接口的响应设计:先定媒体类型,再定错误边界

一句话回答

三类接口不应共用同一响应外壳:JSON 用稳定的错误结构,表单明确跳转或 JSON 返回,图片返回真实二进制媒体类型。API.PLUS 的具体字段与状态码本次材料未提供,落地需以实际契约为准。

这三类接口不适合共用同一种响应外壳。更稳妥的顺序是:先确定客户端期望收到什么,再确定成功响应的媒体类型,最后定义错误的 HTTP 状态与机器可读错误码。API.PLUS 现有的响应字段、错误码和端点行为,本次材料没有提供;下面只讨论通用设计规范,具体落地前仍需对照实际契约。

先定响应类型,再定 JSON 外壳#

“表单接口”描述的是请求可能采用 application/x-www-form-urlencoded 或 multipart/form-data,并不等于响应必须是 HTML。响应应按调用场景设计:浏览器整页提交可以返回 HTML 或跳转,脚本提交可以返回 JSON;图片下载则应返回图片二进制。建议让 Content-Type 与响应体的真实类型一致,不要让所有端点都返回 application/json。

  • JSON 接口:成功和失败都使用可解析的 JSON,字段结构保持稳定。
  • 表单接口:明确区分浏览器跳转与脚本 JSON 响应,并在文档中写出条件。
  • 图片接口:成功时返回真实图片类型,不要把二进制默认包进 JSON。

JSON:HTTP 状态与业务错误码各司其职#

建议成功使用 2xx,参数错误、未认证、无权限、资源不存在等使用相应的 4xx,服务端异常使用 5xx。不要把所有失败都包成 200 OK,否则客户端需要解析正文才能判断请求是否成功。错误正文应包含稳定的错误码和面向调用方的说明;堆栈、SQL、内部主机名等调试信息留在服务端日志。

下面只是结构示例,字段名不是 API.PLUS 的既有契约,也未实际执行:

{
  "request_id": "req_demo_001",
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "参数校验失败",
    "details": [
      { "field": "email", "reason": "格式不正确" }
    ]
  }
}

若成功响应也使用信封,建议在契约中固定 data、error 等字段的含义和二选一关系。不要让同一字段有时是对象、有时是数组;这会迫使客户端写额外分支。

表单:先说明是跳转还是数据响应#

浏览器表单提交成功后,若希望地址栏进入结果页,可采用 POST-Redirect-GET:返回 303 See Other 和 Location,让浏览器改用 GET 读取结果。是否适合该模式,取决于接口契约和页面流程。供 fetch 调用的表单端点则可以返回 JSON,但应在文档中明确,不要未声明就根据 Accept 或客户端类型悄悄切换格式。

校验失败时,若返回 HTML,应保留用户输入并给出可读错误;若返回 JSON,应复用上面的错误码结构。两种方式都建议避免返回“200 + 一段错误提示 HTML”,因为脚本调用方难以稳定判别。

图片:二进制与错误必须可区分#

图片成功响应建议使用明确的 image/png、image/jpeg 等类型,并在可用时提供长度和缓存相关响应头。确需以 JSON 返回图片时,应单独声明编码方式,例如 Base64 字段,而不要把任意二进制直接拼进普通字符串。

错误响应不要用 200 加一张占位图来掩盖失败,除非契约明确约定“占位图也是成功结果”。更稳妥的做法是返回非 2xx,并使用调用方能够解析的错误媒体类型。若图片涉及权限,缓存策略应与可见范围一致;公开缓存头不应误用于私有图片。

契约检查清单#

  1. 每个端点的成功与失败响应,Content-Type 是否与实际正文一致。
  2. 错误码是否稳定、可枚举,HTTP 状态是否被正确使用。
  3. 表单端点是跳转还是 JSON,是否写清了触发条件和返回结构。
  4. 图片端点失败时,客户端能否不依赖图片解码就识别错误。
  5. 示例是否只作说明,是否有契约测试覆盖状态码、媒体类型和字段结构。

本次材料没有提供 API.PLUS 的具体响应规范,因此无法确认其现有端点是否满足以上条目。上面是设计建议与未执行示例;实际字段、状态码和兼容策略应以官方文档及真实响应为准。

作者:沐小悠

本文约 5 分钟读完 · 关键词:API响应设计、JSON响应、表单接口、图片接口、HTTP状态码

更多文章 GET 示例接口

「」标签下的其他文章