技术文章

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

JSON、表单与图片接口的响应设计:API.PLUS 场景下的边界与错误包络

一句话回答

在缺少 API.PLUS 官方规范正文的情况下,本文给出一般性设计建议:先按 JSON、表单、图片区分成功响应的 Content-Type,再用 HTTP 状态码和稳定错误包络表达失败;具体端点字段、缓存头与重定向行为需以官方文档或可复现响应核对。

如果问题是为 API.PLUS 定义 JSON、表单和图片接口的响应规范,先要回答的不是字段长什么样,而是:同一类请求在成功与失败时,分别返回什么媒体类型、什么状态码、什么错误结构。由于本次材料没有 API.PLUS 官方规范正文,也没有可核验的响应样本,下面只能给出一般性设计建议,不能称为平台现行规则;具体端点的字段、缓存头和重定向行为仍需以官方文档或实际响应核对。

先按响应类型划边界#

三类接口不宜共用一种“成功体”。建议把成功响应的媒体类型固定下来,并让失败响应也能被客户端稳定识别。

接口类型成功响应建议失败响应建议
JSON 接口2xx,Content-Type 标明 JSON,返回可解析的对象4xx/5xx,仍返回 JSON 错误包络
表单接口浏览器提交可重定向到结果页;脚本客户端可要求 JSON明确返回 HTML 错误页还是 JSON 错误,不能含糊
图片接口2xx,Content-Type 为实际图片类型,响应体为二进制用错误状态码加明确媒体类型,不用 200 返回占位图掩盖失败

统一错误包络,但不要吞掉状态码#

建议让 HTTP 状态码表达错误类别,让响应体表达细节。错误包络至少包含稳定的机器可读 code、可读 message,以及便于排查的 request_id。message 不应泄露堆栈、内部路径或密钥。

适用环境:HTTP 客户端阅读;未执行示例,字段仅演示,不是 API.PLUS 实际输出。

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "参数格式不正确",
    "request_id": "req_demo_0001"
  }
}

这里的 request_id 是占位演示值。建议文档说明 code 的稳定性:客户端可以按 code 分支,但不要依赖 message 文案做逻辑判断。

内容协商与表单返回#

内容协商指客户端用 Accept 请求头表达可接受的媒体类型。若同一表单端点既服务浏览器又服务脚本,建议在文档中写清 Accept 与响应 Content-Type 的对应关系。浏览器场景可考虑重定向到结果页;脚本场景应能明确拿到 JSON 错误,而不是解析一张 HTML 错误页。成功返回 HTML、失败返回 JSON 时,更要让状态码和 Content-Type 如实反映实际内容。

图片响应:二进制与错误分开#

图片成功响应应是实际图片二进制,并用 Content-Type 标明格式。客户端应先看状态码和 Content-Type,再决定解码图片还是解析错误体,不能只按 URL 扩展名判断。错误响应建议明确为 JSON 或文档规定的其他类型;限流、鉴权失败与图片解码失败应能区分。缓存头(如 ETag、Cache-Control)是否设置、如何设置,需结合资源是否可变和平台文档确认,待核实。

验收清单#

  1. 每个端点是否列出成功与失败的状态码、Content-Type 和示例。
  2. 错误 code 是否稳定,message 是否避免泄露内部信息。
  3. 表单端点的 Accept、重定向和错误页行为是否写明。
  4. 图片接口失败时返回什么媒体类型,客户端如何分支是否清楚。
  5. 缓存、限流和 request_id 是否可观测;以官方文档或可复现响应为准。

结论可以收窄为:先把 JSON、表单、图片三类响应的 Content-Type 和失败形态分开,再统一错误语义。API.PLUS 的具体实现不在本次可核验材料内,本文未调用端点,相关字段与缓存行为待核实。

作者:沐小悠

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

更多文章 GET 示例接口

「」标签下的其他文章