JSON、表单、图片接口的响应设计：先分形态，再统一错误体
三类接口的响应设计要先按载荷形态分开（JSON 结构化数据、表单提交后的结构化回执、图片二进制流），再用同一套错误结构收口。关键约束是 Content-Type 准确、错误不伪装成 200、图片接口把元信息放头部而非塞进 JSON、表单接口提供字段级错误定位。文中示例均为未执行的演示，具体标准编号与实现细节待核实。
一句话回答标题问题：JSON、表单、图片三类接口不该共用一套响应模板。应先把“成功时返回什么形态”按载荷分开定，再用同一套错误结构收口；否则轻则客户端要写三套解析逻辑，重则把失败伪装成成功。
第一步：按载荷定成功响应的形态#
JSON 接口
成功响应返回 JSON 对象或数组，Content-Type 与之一致。建议把顶层固定为对象而不是裸数组，这样以后加 meta、request_id 等字段不会破坏客户端解析。字段命名、时间格式、空值用 null 还是省略，都应在文档里写死一处，而不是每个接口各写一套。
表单接口
表单提交的请求体是 application/x-www-form-urlencoded 或 multipart/form-data，但响应体不必是表单格式。建议统一返回 JSON：提交类接口的调用方通常需要拿到新资源 id、校验结果或跳转地址，结构化回执比 302 更利于前端判断。是否使用重定向，取决于这个接口是给浏览器用还是给程序用，这一点要在文档里明确。
图片接口
图片接口的响应体是二进制流，Content-Type 必须与实际编码一致（如 image/jpeg、image/png），尺寸、来源、缓存键等元信息放响应头，而不是把 base64 塞进 JSON——后者会让体积膨胀、让浏览器失去流式解码和缓存能力。只有当调用方确实需要把图片内嵌进结构化文档时，才考虑 base64，并把这条路径单独标注。
第二步：用一套错误结构收口#
三类接口的错误应共享同一组字段，客户端才能只写一份错误处理。建议至少包含：机器可读的 code、人可读的 message、可用于对账的 request_id，以及表单场景下的字段级 details。
{
"error": {
"code": "INVALID_FIELD",
"message": "参数校验未通过",
"request_id": "示例占位-id",
"details": [
{ "field": "email", "reason": "格式不合法" }
]
}
}以上为结构演示，未执行，非真实响应。
- 不要用 200 包错误。HTTP 状态码与业务错误码分工：前者表达传输与请求层面的结果，后者表达业务语义。混用会让网关、监控和重试策略全部失效。
- 图片接口失败时不能回占位图。返回一张“默认图”并给 200，调用方无法区分“取到了图”和“取图失败”，缓存还会把失败固化下来。失败就返回错误体加对应状态码，
Content-Type改成 JSON。 - 表单接口要能给到字段。只说“参数错误”会让前端无法定位，
details里的field应与表单字段名一致。
第三步：缓存与协商头，三类接口各有重点#
| 接口类型 | 成功响应要点 | 常见失误 |
|---|---|---|
| JSON | 顶层对象、稳定字段名、错误体同构 | 裸数组、错误字段与成功字段混在一起 |
| 表单 | JSON 回执、字段级错误、明确是否重定向 | 成功返回 HTML 片段，程序调用方无法解析 |
| 图片 | 准确 Content-Type、ETag、Cache-Control | base64 内嵌、失败回占位图 |
图片接口尤其值得给 ETag：同一 URL 的图片内容变化时，校验值随之变化，调用方才敢长期缓存。JSON 与表单接口是否可缓存，取决于其中是否含用户私有数据，这一点必须逐接口判断，不能整站套一个策略。关于错误体的字段命名，业内常见的 Problem Details（RFC 9457）给出了一套约定；其编号、当前状态与字段定义请以 IETF 发布页为准，本文未核验。
落地顺序#
- 先列出所有接口，标注载荷形态：结构化、表单回执、二进制。
- 为三类各写一个成功样例，确认
Content-Type与结构。 - 再写一份共享的错误体样例，覆盖校验失败、未授权、资源不存在、内部错误四类。
- 最后统一缓存与
request_id的生成规则，写进文档并给出可复制的请求骨架。
需要说明的边界：本文只讨论响应形态与结构的约定，不涉及具体框架实现、性能表现或某平台的实际返回。文中代码块均为结构演示，未在任何环境中执行；具体标准的版本与细节，请以官方文档为准。
