JSON 在 API 开发中的设计规范与最佳实践

分类：API 设计 · 阅读约 8 分钟

一、为什么 JSON API 需要设计规范？

无论你是在开发一个内部微服务，还是一个对外的开放 API，JSON 响应的结构设计直接影响着 API 的可用性和可维护性。一个没有规范的 API 会让调用方在每个接口都要猜测响应格式，增加集成成本；而一个设计精良的 JSON API 调用方看一眼就能推理出其他接口的结构。

本指南覆盖了 JSON API 设计的五个核心维度：命名约定、错误处理、分页策略、版本控制和安全性。

二、命名约定：camelCase vs snake_case

这是 JSON API 设计中最基础的共识问题。没有绝对的对错，但有「适合大多数场景」的选择：

风格	示例	适用场景
camelCase	createdAt, userId	JavaScript/TypeScript 生态首选
snake_case	created_at, user_id	Python/Ruby/PostgreSQL 生态
kebab-case	created-at, user-id	❌ JSON 不推荐（键名需引号包裹）

建议：如果你的 API 主要被前端 JavaScript 调用，统一使用 camelCase。如果后端是 Python/Django，使用 snake_case 更自然。无论选哪种，全文一致比选哪种更重要。

三、错误响应：让调用方能自动处理

错误响应的设计是区分「能用的 API」和「好用的 API」的关键。一个好的错误响应应该包含：错误码、可读消息、出错字段（可选）、请求 ID（用于日志追踪）。

标准错误响应格式：

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "字段 'email' 格式不正确",
    "details": [
      {"field": "email", "reason": "不符合邮箱格式"}
    ],
    "requestId": "req_a1b2c3d4"
  }
}

HTTP 状态码的语义使用：

400 — 客户端参数错误（请求格式问题）
401 — 未认证（缺少 token 或 token 过期）
403 — 无权限（token 有效但权限不足）
404 — 资源不存在（不要用于业务逻辑检查）
409 — 资源冲突（如重复创建）
422 — 语义错误（参数格式正确但业务逻辑不通过）
429 — 请求过于频繁（触发限流）
500 — 服务器内部错误（仅用于未预期的异常）

避免：所有错误都返回 200 OK 并在 body 中区分。这会让 HTTP 缓存、监控系统和 API 网关无法正常工作。

四、分页策略：让大列表可管理

分页是 JSON API 设计的高频需求。目前主流有三种模式：

4.1 偏移分页（Offset-based）

GET /api/users?page=1&per_page=20
// 响应
{
  "data": [...],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 256,
    "totalPages": 13
  }
}

优点：实现简单，UI 友好。缺点：数据变动时可能遗漏或重复记录。

4.2 游标分页（Cursor-based）

GET /api/users?cursor=eyJpZCI6MTAwfQ&limit=20
// 响应
{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTIwfQ",
    "hasMore": true
  }
}

优点：性能稳定，数据变动不影响游标。缺点：不支持跳页，UI 通常只能「加载更多」。

选型建议：实时数据流（社交动态、消息列表）用游标分页；后台管理系统用偏移分页。

五、API 版本控制

版本控制的三种方式，按推荐度排序：

URL 路径版本（推荐）：/api/v1/users — 最直观，易于路由和文档生成
请求头版本：Accept: application/vnd.api+json;version=1 — URL 干净但调试不便
查询参数版本：/api/users?version=1 — 简单但容易遗漏（不推荐）

版本升级时，永远要提供弃用通知期。在响应头中加入 Deprecation: true 和 Sunset: Sat, 31 Dec 2024 23:59:59 GMT，给调用方至少 3 个月的迁移时间。

六、安全性：不可忽略的防线

始终使用 HTTPS：没有商量的余地。HTTP 明文传输的 JSON 可以被中间人截获和篡改。
设置 CORS 白名单：只允许可信域名的跨域请求，不要使用 Access-Control-Allow-Origin: *。
限流（Rate Limiting）：每个 IP 或 API Key 应有频率上限。响应头中包含 X-RateLimit-Remaining 供调用方自查。
输入校验：永远不要信任调用方传入的 JSON。对每个字段进行类型检查和长度限制。一个大到异常的字符串就能耗尽服务端内存。
敏感字段脱敏：密码、密钥、身份证号等敏感数据在响应中应用 "***" 遮罩或直接排除。在序列化层做这事，别等到业务代码里再处理。

开发 API 时需要格式化 JSON 响应？

打开 JSON 格式化工具