JSON、表单与图片接口的响应设计规范：统一契约后，错误与二进制怎么分

结论先说：JSON、表单提交和图片接口不该各写一套响应约定。更稳妥的做法是共用一层“结果契约”——用 HTTP 状态码区分成功与失败类别，用固定错误体携带机器可读的 code、人类可读的 message 和可追踪的 request_id；成功载荷再按媒体类型分别设计。API.PLUS 各接口的实际字段、状态码与限制，本次材料未提供，接入时应以其官方文档为准。

外层契约：三类接口共用的部分#

• 状态码表达类别：2xx 表示成功，4xx 表示请求方问题，5xx 表示服务端或上游问题。字段校验失败可用 422，但要在文档中固定下来，不要同一接口时而 400、时而 422。
• 错误体结构固定：至少包含 code、message、request_id；字段错误再加 fields 数组。调用方先看状态码，再看 code，不要依赖解析 message 文案。
• 请求 ID 贯穿日志：响应头或响应体提供同一个 ID，便于把客户端报错与服务端日志对上。
• 不要用 200 掩盖失败：若业务上确实需要“HTTP 200 + 业务错误码”，必须在文档里写清楚，并保证所有接口一致。

JSON 响应：顶层对象、分页与精度#

建议成功响应返回顶层对象而不是裸数组，便于以后加 next_cursor、total 等字段而不破坏兼容。分页要写明游标还是页码、排序是否稳定。时间统一用带时区的 ISO 8601 字符串；金额和大整数用字符串传输，避免 JavaScript 的 Number 精度损失。空结果返回 [] 或 null 需二选一并在文档中固定，不要让不同接口各用一套。

表单响应：错误要定位到字段#

application/x-www-form-urlencoded 与 multipart/form-data 是请求格式；响应通常仍应是 JSON，而不是 HTML 页面。校验失败时返回字段级错误，调用方才能把提示挂到对应输入框。文件上传要区分“文件过大”“类型不支持”“字段缺失”，不要统一成“参数错误”。

图片响应：成功是二进制，失败是结构化错误#

图片成功响应应带准确的 Content-Type（如 image/webp）、Content-Length，并按可缓存性设置 ETag（实体标签，用于条件请求）和 Cache-Control。随机图或一次性生成图应使用短缓存或 no-store；固定资源可用较长 max-age。失败时返回 JSON 错误体，不要返回 HTML 错误页、空白图或 200 状态码的占位图，否则客户端很难区分“图错了”和“请求失败了”。

下面两个响应仅用于说明格式，未实际发送，头部数值为占位：

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
X-Request-Id: req_demo_0001

{
  "error": {
    "code": "invalid_field",
    "message": "字段校验失败",
    "fields": [
      { "name": "email", "reason": "format" }
    ],
    "request_id": "req_demo_0001"
  }
}

HTTP/1.1 200 OK
Content-Type: image/webp
Content-Length: 48213
ETag: "demo-etag-1"
Cache-Control: public, max-age=300

图片生成或转码失败时，状态码可用 502 或 504，并返回同样的 JSON 错误结构：

{
  "error": {
    "code": "upstream_timeout",
    "message": "图片处理超时",
    "request_id": "req_demo_0002"
  }
}

落地前的检查清单#

1. 三类接口是否共用同一套错误体字段与状态码约定？
2. JSON 是否避免裸数组，并写明分页、排序和时间格式？
3. 表单校验失败是否返回字段级错误，而不是整页 HTML？
4. 图片成功响应是否带正确的 Content-Type、长度和缓存头？
5. 图片失败是否返回结构化 JSON，而不是占位图或 HTML？
6. 文档是否明确说明哪些字段可能为 null、哪些属于实验性？

以上是设计与验收建议，不构成对 API.PLUS 具体接口行为的描述；实际字段、错误码和缓存策略仍待以其官方文档核实。