API设计规范与JSON格式最佳实践，帮助您设计高质量、易用的RESTful API。
保持API响应格式的一致性，便于客户端处理。
{
"code": 200,
"message": "success",
"data": {
"id": 1,
"name": "张三"
},
"timestamp": 1704067200
}// 不同接口格式不一致
// GET /user/1
{"id": 1, "name": "张三"}
// GET /users
[{"id": 1, "name": "张三"}]
// POST /user
{"success": true, "user": {...}}提供清晰的错误信息，帮助开发者快速定位问题。
{
"code": 400,
"message": "参数错误",
"errors": [
{
"field": "email",
"message": "邮箱格式不正确"
},
{
"field": "password",
"message": "密码长度至少8位"
}
],
"request_id": "req_abc123"
}{
"error": "Bad Request"
}列表数据需要分页时，返回完整的分页信息。
{
"code": 200,
"data": {
"items": [...],
"pagination": {
"page": 1,
"page_size": 20,
"total": 100,
"total_pages": 5,
"has_next": true,
"has_prev": false
}
}
}{
"items": [...],
"total": 100
}合理处理关联资源，避免过度嵌套或N+1查询。
// 方案1: 包含简要信息
{
"id": 1,
"title": "文章标题",
"author": {
"id": 101,
"name": "张三",
"avatar": "https://..."
}
}
// 方案2: 引用ID + 可选展开
{
"id": 1,
"title": "文章标题",
"author_id": 101,
"author": null // 需要时通过include参数展开
}// 过度嵌套
{
"id": 1,
"author": {
"id": 101,
"posts": [{
"id": 1,
"comments": [...]
}]
}
}| 状态码 | 描述 | 使用场景 |
|---|---|---|
| 200 | 成功 | GET、PUT、PATCH请求成功 |
| 201 | 创建成功 | POST请求成功创建资源 |
| 204 | 无内容 | DELETE请求成功，无返回内容 |
| 400 | 请求错误 | 参数验证失败、格式错误 |
| 401 | 未认证 | 缺少或无效的身份认证 |
| 403 | 禁止访问 | 无权限访问该资源 |
| 404 | 未找到 | 资源不存在 |
| 409 | 冲突 | 资源冲突（如重复创建） |
| 422 | 无法处理 | 语义错误（如验证失败） |
| 429 | 请求过多 | 触发速率限制 |
| 500 | 服务器错误 | 服务器内部错误 |
| 503 | 服务不可用 | 服务维护或过载 |
JSON文本压缩率高，可减少70%以上传输体积。
// 响应头
Content-Encoding: gzip
// 压缩效果对比
原始大小: 45KB
压缩后: 12KB
压缩率: 73%允许客户端指定需要的字段，减少不必要的数据传输。
// GET /users/1?fields=id,name,email
{
"id": 1,
"name": "张三",
"email": "zhang@example.com"
// 不返回其他字段如bio, avatar等
}提供批量查询和批量操作接口，减少请求次数。
// 批量查询
POST /users/batch
{
"ids": [1, 2, 3, 4, 5]
}
// 批量响应
{
"data": [
{"id": 1, "name": "用户1"},
{"id": 2, "name": "用户2"},
...
]
}合理使用HTTP缓存头，减少重复请求。
// 响应头设置缓存
Cache-Control: public, max-age=3600
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
// 客户端可以使用ETag验证
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
// 服务端返回304 Not Modified不要在响应中返回敏感信息，如密码、token等。
严格验证所有输入数据，防止注入攻击。
实施API速率限制，防止滥用。