API 中的 JSON 设计指南：字段、错误、分页与兼容性

JSON API 的难点不在于能不能返回数据，而在于能否让调用方稳定理解、长期兼容、方便排错。下面是适合多数中小型 Web API 的实用约定。

响应结构保持稳定

列表接口不要直接返回裸数组，建议用对象承载数据和元信息。这样后续添加分页、统计或追踪字段时不会破坏结构。

{
  "data": [
    {"id": "1001", "name": "JSON工具箱"}
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 128
  }
}

字段命名保持一致

同一个 API 内应固定一种命名风格，例如 camelCase 或 snake_case。前端项目常用 camelCase，Python/数据工程场景常见 snake_case。不要在同一响应里混用。

错误对象要可读也可处理

错误响应应同时包含机器可判断的 code 和人类可阅读的 message。字段级校验错误可以放入 details。

{
  "error": {
    "code": "INVALID_JSON",
    "message": "请求体不是合法 JSON",
    "details": [
      {"field": "payload", "reason": "缺少右花括号"}
    ]
  }
}

空值和缺省值要有策略

如果字段存在但暂无值，使用 null；如果字段对该资源不适用，可以省略。关键是文档中说明清楚，避免调用方把“缺失”和“空值”当成同一件事。

时间和大整数

时间建议使用 ISO 8601 字符串，例如 2026-05-08T10:30:00Z。超过 JavaScript 安全整数范围的 ID 建议以字符串返回，避免前端出现精度丢失。

向后兼容原则

• 新增字段通常安全，删除或改名字段通常是破坏性变更。
• 字段类型不要随意变化，例如不要让同一字段有时是字符串、有时是对象。
• 枚举值新增前要确认客户端是否会把未知值当成错误。
• 错误 code 一旦公开，应尽量长期稳定。

相关教程