技术文章

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

JSON、表单与图片接口的响应设计:让调用方不必写三套解析逻辑

一句话回答

三类接口可以共用一套响应约定:统一状态码语义、统一错误结构、统一字段命名与内容协商规则,载荷格式按场景选择。图片接口应优先返回二进制并配齐缓存与类型头部,而不是默认用 JSON 包 base64。文中给出可迁移的约定与验收清单;API.PLUS 各接口的具体字段、状态码与限制本次材料未提供,需以官方文档核实。

这个问题可以拆成一句:JSON、表单、图片三类接口的响应,能不能用同一套规则描述,让调用方不必按接口类型写三套解析逻辑。答案是能,但共用的是约定而不是载荷格式。状态码语义、错误结构、字段命名和内容协商要统一,具体格式再按场景选择。本文给的是可迁移的设计约定;API.PLUS 各接口的实际字段、状态码与限制以其官方文档为准(本次材料未提供,待核实)。

一、先把响应形态定下来#

成功响应建议统一为 JSON 对象而非顶层裸数组,便于后续增加 meta、分页游标等字段而不破坏兼容。业务失败有两种常见风格:用 HTTP 状态码表达语义,或在 200 响应体里返回业务码。两种都能用,关键是全站只选一种并写进文档,不要让调用方同时猜两处。

错误体建议采用 RFC 9457 定义的 Problem Details(application/problem+json),它的 type、title、status、detail、instance 五个成员足以覆盖多数场景,并可扩展字段级错误(来源:RFC 9457)。响应必须带准确的 Content-Type;客户端通过 Accept 无法接受时返回 406,而不是把 HTML 错误页塞进 JSON 接口(HTTP 语义见 RFC 9110)。

二、JSON 响应的字段约定#

  • 命名统一:全站 snake_case 或 camelCase 择一,不要按模块切换。
  • 空值语义写清楚:null 表示“已知为空”,字段缺省表示“未提供或不适用”,两者不要混用。
  • 时间带时区:用 RFC 3339 格式,例如 2026-11-13T10:00:00+08:00,避免只给本地时间(RFC 3339)。
  • 大整数用字符串:超出 JavaScript 安全整数范围的 ID 建议以字符串返回,这是规避精度丢失的工程惯例,不是标准强制。
  • 错误码稳定可枚举:机器判读用固定 code,人类可读文案放在另一字段,文案可改、码不可改。

三、表单接口:请求用表单,响应仍用 JSON#

表单提交的媒体类型有两种:application/x-www-form-urlencoded 适合纯文本键值;含文件或二进制字段时必须用 multipart/form-data(RFC 7578)。请求是表单,不代表响应也要是表单:成功后返回 JSON,前端就能复用同一套解析与错误处理。

校验失败时,返回 400 加字段级错误映射,键名与表单 name 保持一致,这样前端可以把错误直接挂到对应输入框,不必再做一层名字翻译。

四、图片接口的响应#

图片读取接口默认返回二进制,而不是 JSON 包 base64。base64 会让体积膨胀约三分之一(编码开销的算术结果),并失去浏览器的原生缓存与流式渲染能力。二进制响应至少要配齐:Content-Type、Content-Length、ETag 或 Last-Modified、以及明确的 Cache-Control。

上传接口成功后返回 JSON 元数据(资源 ID、MIME 类型、宽高、校验和),供调用方后续引用。失败要能区分两类:媒体类型不在白名单返回 415,类型正确但内容无法处理返回 422——两者对调用方的处置动作不同,合并成一个错误码会逼着对方去解析错误文案。

场景推荐响应 Content-Type需重点检查的头部典型失败状态
JSON 数据接口application/jsonContent-Type、Cache-Control400 / 422 / 406
错误响应application/problem+jsonContent-Type—
表单提交请求侧 form-urlencoded 或 multipart请求 Content-Type 的 boundary400 / 413 / 415
图片读取具体图片 MIME,如 image/pngETag、Cache-Control、Content-Length404 / 415

错误响应示意(未执行的示例)

下面仅示意结构,example.com 为占位域名,未实际发送请求,也不代表任何真实服务的返回。

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://example.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "部分字段未通过校验",
  "errors": {
    "email": "格式不合法",
    "avatar": "文件超过大小上限"
  }
}

五、上线前的验收清单#

  1. 同一接口在成功、校验失败、鉴权失败三种情况下,响应 Content-Type 是否都正确。
  2. 错误体是否包含稳定的机器可读字段,而不只有自然语言文案。
  3. 字段级错误的键是否与请求字段名一一对应。
  4. 图片与文件响应是否带缓存相关头部,重复请求能否走条件请求。
  5. 约定是否已写入文档或机器可读的接口描述,而不只存在于实现里。

需要说明边界:以上是通用设计约定,不是对 API.PLUS 现有接口的描述。该平台各接口实际采用的响应信封、错误码表和大小限制,本次没有可核验材料,应在接入前对照官方文档逐项确认,并在联调中抽样验证。

作者:沐小悠

本文约 7 分钟读完 · 关键词:JSON 响应设计、表单接口、multipart/form-data、图片接口、错误响应

更多文章 GET 示例接口

「」标签下的其他文章