JSON、表单与图片接口的响应设计：先统一契约，再分开处理载荷

面向 API.PLUS 设计 JSON、表单和图片三类接口的响应时，可以采用这样一条较窄但可执行的结论：先固定三类接口共用的状态码与错误语义，再分别约束各自的 Content-Type、正文形态，以及失败时的回退行为。API.PLUS 现有端点的字段名、错误码表、图片格式与尺寸限制，本次材料未提供，需以其官方文档为准（待核实）。下文给出的是设计建议与结构示意，不是对某个端点的实测结论。

共同层：先确定三件事#

• 结果类别交给 HTTP 状态码，响应体只承载细节。客户端可以先按状态码分流，再解析正文，不必为每个端点单独判断“是否成功”。
• 错误体结构固定：错误码、面向人的消息、请求标识、字段级明细各占一个固定键。成功体里不出现 error 字段，错误体里不出现业务数据。
• 显式声明 Content-Type，客户端按它解析，而不是按 URL 后缀或请求参数猜测。

JSON 响应：形状只选一种#

顶层是“固定信封”还是“直接返回资源”，两者都可以，但同一个 API 内应二选一。混用的代价是客户端要为每个端点写分支。另外两点容易被忽略：缺失字段与值为 null 应区分语义，前者表示“未提供”，后者表示“明确为空”；大整数 ID 和金额建议用字符串传输，避免超出 JavaScript 安全整数范围后精度丢失。时间字段建议统一为带时区的格式，并在文档里写明是 UTC 还是本地偏移。

下面是错误体的结构示意，未执行任何请求，也不代表 API.PLUS 的真实返回：

{
  "code": "INVALID_ARGUMENT",
  "message": "参数校验失败",
  "request_id": "req_demo_0001",
  "details": [
    { "field": "size", "reason": "out_of_range" }
  ]
}

表单接口：提交是表单，响应不一定是#

表单类端点常被默认“返回 HTML”，但更稳妥的做法是把两件事分开：请求体用 application/x-www-form-urlencoded 或 multipart/form-data 提交；响应则按调用方决定。面向浏览器的服务端渲染表单，校验失败可回填 HTML；面向脚本调用时，返回 JSON 更易处理。

• 处理成功后若需跳转，用 303 让浏览器以 GET 重新请求目标页，避免用户刷新时重复提交。
• 校验失败返回 4xx 并附字段级明细，明细里的字段名与表单 name 保持一致，前端才能直接定位到输入框。
• 不要用 200 加 {"ok": false} 表达失败，也不要在不同端点对同一类错误给出不同状态码。

图片接口：成功是字节流，失败必须不是#

图片端点的成功响应直接返回二进制，配明确的 Content-Type（如 image/png）、长度、以及 ETag 或 Last-Modified。关键约束在失败路径：出错时不能返回图片字节、空图或 200 占位图，否则客户端会把错误当成正常图片渲染。失败应返回错误体，并让 Content-Type 表明这是 JSON 而非图片。

对应的客户端写法是“先看 Content-Type 再决定解析方式”，而不是默认 response.blob()。缓存方面，URL 稳定的图片适合长缓存；随机图或短期签名链接的缓存边界需要在文档中单独写清，因为同一套缓存头用在不同语义的 URL 上会出错。

三类载荷对照#

边界与待核实#

API.PLUS 侧的字段命名、错误码枚举、图片格式与体积上限、限流相关响应头，本次材料均未提供，无法给出确定结论，请以官方文档为准。文中示例里的 req_demo_0001 等取值均为占位，示例域名与密钥应替换为 example.com 与 YOUR_KEY 后再验证。