JSON、表单与图片接口怎么设计响应：三份消费契约与统一错误边界
响应设计应先按客户端消费路径区分 JSON、表单和图片三类契约，再共享状态码、可机器读取的错误体与可追踪标识；图片失败时不要伪装成成功图片。API.PLUS 的具体端点与错误码需以官方文档为准。
给 API.PLUS 接入者设计响应时，先回答一个更具体的问题：客户端拿到响应后，准备用哪条解析路径消费它？工程上可把响应分成 JSON、表单和图片三类契约，再共享状态码、错误体和可追踪标识。本文是设计与验收建议，不是对 API.PLUS 现有接口行为的描述；具体端点、字段、限流与错误码本次材料未提供，需以官方文档为准（待核实）。
一、按消费路径分三份契约#
同一套服务可以返回不同形态，但不要让客户端靠猜。先约定每类接口的成功响应和失败响应分别长什么样。
| 接口形态 | 成功响应应让客户端确认什么 | 失败响应应让客户端做什么 |
|---|---|---|
| JSON 结构化数据 | Content-Type 为 application/json；字段稳定；分页或游标语义明确 | 读状态码与错误体中的 code、message |
| 表单提交 | 提交是否成功；下一步是跳转还是返回 JSON 结果 | 区分字段校验失败与服务失败 |
| 图片 | 2xx 状态、Content-Type 为图片类型、长度与缓存规则明确 | 按状态码和 Content-Type 读取错误体，不把错误体当图片解析 |
二、JSON：字段稳定，错误可机器读#
建议成功响应保持顶层字段稳定，错误响应使用独立结构。下面只是演示结构，不是 API.PLUS 实际返回，也未实际执行：
{
"error": {
"code": "INVALID_ARGUMENT",
"message": "参数格式不正确",
"request_id": "req_demo_123"
}
}HTTP 状态码负责表达成功或失败的大类，错误体负责可编程处理细节；不要让 200 同时表示成功和业务失败。request_id 可用于日志关联，但不应在响应中泄露密钥、账号或内部堆栈。
三、表单：不要用 200 HTML 页面替代结果#
表单接口常见的问题是提交成功后返回登录页或错误页，而客户端只看状态码 200 就误判成功。建议成功时返回 303 跳转或 JSON 结果；字段校验失败返回 4xx，并在错误体中定位字段；Content-Type 必须与实际 body 一致。若确实返回 HTML，客户端应按 text/html 解析，而不是当作 JSON。
四、图片：成功是二进制，失败不要伪装成图片#
图片成功响应建议明确 Content-Type（如 image/png）、Content-Length 和缓存策略。失败时应返回错误状态码与可解析错误体，Content-Type 设为 application/json；不要把 JSON 错误包装成 200 图片。客户端验收先看状态码和 Content-Type，必要时检查文件签名（magic bytes），不要只信 URL 后缀。若产品要求返回占位图，应把占位图定义为独立的产品语义，并单独约定缓存规则。
五、可核对的验收清单#
- 同一服务使用一张错误码表，错误体 schema 固定；
- 状态码、Content-Type 与 body 三者一致；
- 错误响应带可追踪的 request_id，且不泄露敏感信息；
- 图片接口分别验证成功图、空响应、超时和非图片错误体；只有保留真实环境、请求与断言的记录，才能称为实测；
- 表单接口验证成功、字段校验失败和重定向，确认客户端不会把 HTML 当 JSON。
在 API.PLUS 接入前，把上述项目写成可复现请求与断言。没有实际调用记录时，只能称验收方案，不能称实测。
