JSON、表单与图片接口的响应设计:先定媒体类型,再定错误边界
三类接口不应共用同一响应外壳:JSON 用稳定的错误结构,表单明确跳转或 JSON 返回,图片返回真实二进制媒体类型。API.PLUS 的具体字段与状态码本次材料未提供,落地需以实际契约为准。
这三类接口不适合共用同一种响应外壳。更稳妥的顺序是:先确定客户端期望收到什么,再确定成功响应的媒体类型,最后定义错误的 HTTP 状态与机器可读错误码。API.PLUS 现有的响应字段、错误码和端点行为,本次材料没有提供;下面只讨论通用设计规范,具体落地前仍需对照实际契约。
先定响应类型,再定 JSON 外壳#
“表单接口”描述的是请求可能采用 application/x-www-form-urlencoded 或 multipart/form-data,并不等于响应必须是 HTML。响应应按调用场景设计:浏览器整页提交可以返回 HTML 或跳转,脚本提交可以返回 JSON;图片下载则应返回图片二进制。建议让 Content-Type 与响应体的真实类型一致,不要让所有端点都返回 application/json。
- JSON 接口:成功和失败都使用可解析的 JSON,字段结构保持稳定。
- 表单接口:明确区分浏览器跳转与脚本 JSON 响应,并在文档中写出条件。
- 图片接口:成功时返回真实图片类型,不要把二进制默认包进 JSON。
JSON:HTTP 状态与业务错误码各司其职#
建议成功使用 2xx,参数错误、未认证、无权限、资源不存在等使用相应的 4xx,服务端异常使用 5xx。不要把所有失败都包成 200 OK,否则客户端需要解析正文才能判断请求是否成功。错误正文应包含稳定的错误码和面向调用方的说明;堆栈、SQL、内部主机名等调试信息留在服务端日志。
下面只是结构示例,字段名不是 API.PLUS 的既有契约,也未实际执行:
{
"request_id": "req_demo_001",
"error": {
"code": "INVALID_ARGUMENT",
"message": "参数校验失败",
"details": [
{ "field": "email", "reason": "格式不正确" }
]
}
}
若成功响应也使用信封,建议在契约中固定 data、error 等字段的含义和二选一关系。不要让同一字段有时是对象、有时是数组;这会迫使客户端写额外分支。
表单:先说明是跳转还是数据响应#
浏览器表单提交成功后,若希望地址栏进入结果页,可采用 POST-Redirect-GET:返回 303 See Other 和 Location,让浏览器改用 GET 读取结果。是否适合该模式,取决于接口契约和页面流程。供 fetch 调用的表单端点则可以返回 JSON,但应在文档中明确,不要未声明就根据 Accept 或客户端类型悄悄切换格式。
校验失败时,若返回 HTML,应保留用户输入并给出可读错误;若返回 JSON,应复用上面的错误码结构。两种方式都建议避免返回“200 + 一段错误提示 HTML”,因为脚本调用方难以稳定判别。
图片:二进制与错误必须可区分#
图片成功响应建议使用明确的 image/png、image/jpeg 等类型,并在可用时提供长度和缓存相关响应头。确需以 JSON 返回图片时,应单独声明编码方式,例如 Base64 字段,而不要把任意二进制直接拼进普通字符串。
错误响应不要用 200 加一张占位图来掩盖失败,除非契约明确约定“占位图也是成功结果”。更稳妥的做法是返回非 2xx,并使用调用方能够解析的错误媒体类型。若图片涉及权限,缓存策略应与可见范围一致;公开缓存头不应误用于私有图片。
契约检查清单#
- 每个端点的成功与失败响应,
Content-Type是否与实际正文一致。 - 错误码是否稳定、可枚举,HTTP 状态是否被正确使用。
- 表单端点是跳转还是 JSON,是否写清了触发条件和返回结构。
- 图片端点失败时,客户端能否不依赖图片解码就识别错误。
- 示例是否只作说明,是否有契约测试覆盖状态码、媒体类型和字段结构。
本次材料没有提供 API.PLUS 的具体响应规范,因此无法确认其现有端点是否满足以上条目。上面是设计建议与未执行示例;实际字段、状态码和兼容策略应以官方文档及真实响应为准。