JSON / 表单 / 图片接口的响应设计规范：三类响应的错误通道怎么统一

三类接口的成功响应差别不大，真正容易出事的是失败路径：JSON 接口的调用方习惯解析结构，表单接口的调用方习惯看字段，图片接口的调用方往往只把 URL 塞进 <img> 或图片加载库。响应设计的核心，就是让这三种调用方都能用同一套逻辑判断“成了没有、错在哪、怎么读”。

先定统一的外层约定：状态码、Content-Type、错误体#

建议在任何接口上固定三件事，作为统一的外层约定，而不是每次单独决定：

• 结果用 HTTP 状态码表达：2xx 成功，4xx 调用方问题，5xx 服务端问题。不要用 200 加 {"code": 500} 的方式表达失败，否则代理、重试库和监控都读不到真实结果。
• Content-Type 必须与实际字节一致。JSON 用 application/json，错误体可以用 application/problem+json（Problem Details，见 RFC 9457；具体条款以原文为准）。
• 错误体结构在全局保持一致：至少包含一个稳定的机器可读代码、一段人类可读说明，以及可选的字段级明细。

这是设计建议，不是标准强制要求。是否采用 problem+json，取决于客户端生态能否接受。

JSON 接口：把“字段缺失”和“字段为空”分开#

JSON 层面最容易产生歧义的是空值。同一个字段，null 表示“显式置空”，字段不存在表示“未提供、保持不变”，两者语义不同，必须在文档里写清楚，否则 PATCH 类接口的调用方只能靠猜。

另外几条实践建议：

• 字段命名风格全局统一（全 snake_case 或全 camelCase），不要混用。
• 时间用带时区的 ISO 8601 / RFC 3339 字符串，不要用本地时间戳。
• 超过 JavaScript 安全整数范围的 ID 用字符串返回，避免客户端精度丢失。
• 顶层尽量返回对象而不是裸数组，后续增加分页或元信息时不会破坏已有客户端。

表单接口：请求可以是表单，响应仍应是 JSON#

表单提交本身有两种编码：application/x-www-form-urlencoded 和 multipart/form-data（RFC 7578）。前者适合纯文本字段，后者用于带文件。这是请求侧的差异，不构成把响应也做成表单的理由——响应返回 JSON 后，客户端才能用与其它接口相同的解析逻辑处理结果。

关键在于校验失败的响应：字段级错误的键名应与表单字段同名，并且一次返回全部错误而不是遇到第一个就中断。这样前端可以直接把错误回填到对应输入框；只返回一条错误会让用户反复提交。带文件上传的接口，响应里返回文件标识或临时 URL，不要把文件内容再回传一遍。

图片接口：二进制响应的错误通道要单独设计#

图片接口的特殊之处在于，客户端常常不解析响应体。所以：

• 成功时返回二进制，配准确的 Content-Type、Content-Length，并尽量提供 ETag 或 Last-Modified 以支持条件请求。
• 失败时不要返回图片类型的内容。若 4xx 响应的 Content-Type 仍是 image/png，浏览器和多数图片库会把它当作图片处理失败，调用方拿不到任何错误信息。失败应返回 application/problem+json 或 application/json 加 4xx 状态码。
• 如果业务上需要占位图，应作为独立分支并明确文档化，而不是把错误伪装成一张图。
• 按 Accept 头做内容协商，无法满足时可返回 406。

一个错误体示例#

下面的结构是演示用的占位示例，example.com 为占位域名，未在任何环境中执行或验证：

{
  "type": "https://example.com/problems/validation-error",
  "title": "请求字段校验失败",
  "status": 422,
  "detail": "email 字段格式不合法",
  "errors": [
    { "field": "email", "code": "invalid_format" }
  ]
}

表单接口可以复用同一结构，只需保证 field 的值与表单字段名一致；图片接口在成功分支不使用该结构。

适用边界#

以上是通用设计取向，不涉及具体产品的实现细节。API.PLUS 各接口实际返回的字段命名、错误码表、是否支持 problem+json、图片接口的错误响应形态，本次材料未提供，均需以其官方文档核实后再据此设计客户端。若已有线上客户端，改动错误体结构属于破坏性变更，应通过版本或新增字段过渡，而非直接替换。