RESTful API 响应设计规范：一个好用的 JSON 结构长什么样？
2024-06-28
有的接口返回数组，有的包 { code, data, message }，有的 HTTP 200 但 body 里 code:500。客户端每接一个新接口都要写适配层——问题多半出在响应结构没有团队规范。
Envelope 是否必要
纯 REST 资源可直接返回对象或数组；企业 API 常用 { data, meta, errors } 统一扩展位。
关键是一致：同一产品线下所有 v1 接口同一种 envelope。
{
"data": { "id": 1, "name": "Alice" },
"meta": { "requestId": "abc-123" }
}错误响应
HTTP 状态码表达大类；body 里 machine-readable code + human message + details 数组（字段级错误）。
避免仅返回 { error: "something wrong" } 让前端无法分支处理。
分页
cursor：meta.nextCursor；offset：page/limit/total。选一种全站统一。
items 数组命名用 data、items 或资源复数，不要混用。
命名与时间
camelCase 与 snake_case 择一；JSON 里日期推荐 ISO 8601 字符串（UTC 或带 offset）。
布尔字段避免 is_ 前缀混用字符串 "true"。
演进策略
只加字段不删；删字段走 deprecate + 版本号。
breaking change 升 /v2/；OpenAPI 文档与 fixture 同步更新。