JSON、表单与图片接口的响应边界：错误体统一，成功体分流

JSON、表单和图片接口不需要共用一个成功响应体；更稳妥的做法是共用错误信封，成功载荷按媒体类型分流。客户端先看 HTTP 状态码和 Content-Type，再决定解析 JSON、渲染 HTML 还是读取二进制。这是设计建议，不是对 API.PLUS 现有接口的描述。

错误信封先统一#

错误信封建议固定顶层字段：机器可读的 code、给人看的 message、字段级 details 和用于串联日志的 request_id。HTTP 状态码负责大类，信封负责细节；不要用 200 表示失败，也不要在错误体里返回成功数据结构。

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "请求参数不合法",
    "details": [
      { "field": "email", "reason": "格式错误" }
    ],
    "request_id": "req_demo_123"
  }
}

上例是未执行的示例，仅示意字段，不是实际响应。错误信息不要暴露堆栈、SQL 或内部路径；details 适合放校验失败字段，不适合放整段异常文本。

成功体按接口类型分开#

JSON 接口

成功时直接返回业务对象或数组，Content-Type: application/json; charset=utf-8。是否再包一层 data 由团队约定，但同一组接口应保持一致；不要一半返回裸数组、一半返回 {"data": ...}。错误信封与成功体不要共享同一个“万能壳”。

表单接口

浏览器表单成功后可重定向到结果页，例如采用 POST/重定向/GET 模式；失败时返回表单回显或错误页。AJAX 表单则更适合统一 JSON 错误信封。关键是按请求来源和 Accept 明确分支，不要让同一个端点对 AJAX 返回 200 的 HTML 失败页。

图片接口

成功响应应是图片二进制，正确设置 Content-Type、Content-Length 和缓存头。失败时不要返回一张“看起来成功”的图片；若客户端能解析 JSON，返回 4xx/5xx 错误信封，并加 Cache-Control: no-store，避免错误被 CDN 或浏览器缓存。若只能服务 img 标签，需在客户端用 onerror 兜底，这是可读性边界。

一组可操作的检查表#

落地顺序#

1. 先固定错误信封和状态码分层：4xx 表示请求方问题，5xx 表示服务方问题。
2. 为每个端点声明成功媒体类型，不让客户端猜返回的是 JSON、HTML 还是图片。
3. 表单端点区分浏览器提交与 AJAX 调用，避免混用失败语义。
4. 图片错误响应禁止缓存，并在客户端准备失败兜底。
5. 用 request_id 关联访问日志和错误日志，便于定位，不要把它当成用户身份。

在 API.PLUS 上发布接口时，平台是否已有响应规范需查其当前文档；本次材料未提供，待核实。没有平台约束时，上述边界可以作为评审清单，而不是“官方标准”。