现代 Web 应用的 JSON API 设计最佳实践

设计良好的 JSON API 对于构建可扩展且可维护的 Web 应用至关重要。本指南涵盖每位开发者应遵循的关键最佳实践。

使用一致的命名约定

在 JavaScript 项目中始终使用 camelCase 命名 JSON 属性，在 Python 项目中使用 snake_case。一致性比选择哪种约定更重要。

{
  "userId": 123,
  "firstName": "John",
  "lastName": "Doe",
  "emailAddress": "john@example.com"
}

使用一致的响应封装。以可预测的结构包含数据、元数据和错误信息：

{
  "status": "success",
  "data": { "id": 1, "name": "示例" },
  "meta": { "page": 1, "totalPages": 10 }
}

对于列表端点，始终实现带有清晰元数据的分页：

{
  "data": [...],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 150,
    "totalPages": 8
  }
}

200 — 成功的 GET、PUT 或 PATCH

201 — 资源创建（POST）

204 — 成功的 DELETE

400 — 验证错误

404 — 资源未找到

500 — 服务器错误

返回包含有用信息的结构化错误对象：

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "邮箱字段为必填项",
    "field": "email"
  }
}

在 URL 路径中包含版本号（/api/v1/users），以便在更改时保持向后兼容。

使用我们的 JSON 格式化器在开发过程中格式化和验证 API 响应。