JSON、表单与图片接口的响应设计:让调用方不必写三套解析逻辑
三类接口可以共用一套响应约定:统一状态码语义、统一错误结构、统一字段命名与内容协商规则,载荷格式按场景选择。图片接口应优先返回二进制并配齐缓存与类型头部,而不是默认用 JSON 包 base64。文中给出可迁移的约定与验收清单;API.PLUS 各接口的具体字段、状态码与限制本次材料未提供,需以官方文档核实。
这个问题可以拆成一句:JSON、表单、图片三类接口的响应,能不能用同一套规则描述,让调用方不必按接口类型写三套解析逻辑。答案是能,但共用的是约定而不是载荷格式。状态码语义、错误结构、字段命名和内容协商要统一,具体格式再按场景选择。本文给的是可迁移的设计约定;API.PLUS 各接口的实际字段、状态码与限制以其官方文档为准(本次材料未提供,待核实)。
一、先把响应形态定下来#
成功响应建议统一为 JSON 对象而非顶层裸数组,便于后续增加 meta、分页游标等字段而不破坏兼容。业务失败有两种常见风格:用 HTTP 状态码表达语义,或在 200 响应体里返回业务码。两种都能用,关键是全站只选一种并写进文档,不要让调用方同时猜两处。
错误体建议采用 RFC 9457 定义的 Problem Details(application/problem+json),它的 type、title、status、detail、instance 五个成员足以覆盖多数场景,并可扩展字段级错误(来源:RFC 9457)。响应必须带准确的 Content-Type;客户端通过 Accept 无法接受时返回 406,而不是把 HTML 错误页塞进 JSON 接口(HTTP 语义见 RFC 9110)。
二、JSON 响应的字段约定#
- 命名统一:全站
snake_case或camelCase择一,不要按模块切换。 - 空值语义写清楚:
null表示“已知为空”,字段缺省表示“未提供或不适用”,两者不要混用。 - 时间带时区:用 RFC 3339 格式,例如
2026-11-13T10:00:00+08:00,避免只给本地时间(RFC 3339)。 - 大整数用字符串:超出 JavaScript 安全整数范围的 ID 建议以字符串返回,这是规避精度丢失的工程惯例,不是标准强制。
- 错误码稳定可枚举:机器判读用固定
code,人类可读文案放在另一字段,文案可改、码不可改。
三、表单接口:请求用表单,响应仍用 JSON#
表单提交的媒体类型有两种:application/x-www-form-urlencoded 适合纯文本键值;含文件或二进制字段时必须用 multipart/form-data(RFC 7578)。请求是表单,不代表响应也要是表单:成功后返回 JSON,前端就能复用同一套解析与错误处理。
校验失败时,返回 400 加字段级错误映射,键名与表单 name 保持一致,这样前端可以把错误直接挂到对应输入框,不必再做一层名字翻译。
四、图片接口的响应#
图片读取接口默认返回二进制,而不是 JSON 包 base64。base64 会让体积膨胀约三分之一(编码开销的算术结果),并失去浏览器的原生缓存与流式渲染能力。二进制响应至少要配齐:Content-Type、Content-Length、ETag 或 Last-Modified、以及明确的 Cache-Control。
上传接口成功后返回 JSON 元数据(资源 ID、MIME 类型、宽高、校验和),供调用方后续引用。失败要能区分两类:媒体类型不在白名单返回 415,类型正确但内容无法处理返回 422——两者对调用方的处置动作不同,合并成一个错误码会逼着对方去解析错误文案。
| 场景 | 推荐响应 Content-Type | 需重点检查的头部 | 典型失败状态 |
|---|---|---|---|
| JSON 数据接口 | application/json | Content-Type、Cache-Control | 400 / 422 / 406 |
| 错误响应 | application/problem+json | Content-Type | — |
| 表单提交 | 请求侧 form-urlencoded 或 multipart | 请求 Content-Type 的 boundary | 400 / 413 / 415 |
| 图片读取 | 具体图片 MIME,如 image/png | ETag、Cache-Control、Content-Length | 404 / 415 |
错误响应示意(未执行的示例)
下面仅示意结构,example.com 为占位域名,未实际发送请求,也不代表任何真实服务的返回。
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
{
"type": "https://example.com/problems/validation-error",
"title": "Validation failed",
"status": 422,
"detail": "部分字段未通过校验",
"errors": {
"email": "格式不合法",
"avatar": "文件超过大小上限"
}
}
五、上线前的验收清单#
- 同一接口在成功、校验失败、鉴权失败三种情况下,响应 Content-Type 是否都正确。
- 错误体是否包含稳定的机器可读字段,而不只有自然语言文案。
- 字段级错误的键是否与请求字段名一一对应。
- 图片与文件响应是否带缓存相关头部,重复请求能否走条件请求。
- 约定是否已写入文档或机器可读的接口描述,而不只存在于实现里。
需要说明边界:以上是通用设计约定,不是对 API.PLUS 现有接口的描述。该平台各接口实际采用的响应信封、错误码表和大小限制,本次没有可核验材料,应在接入前对照官方文档逐项确认,并在联调中抽样验证。