列表与对象的文档模式

API 与配置文件常采用不同的 顶层形态。识别模式有助于快速读文档并设计一致的接口。

根级数组

合法 JSON 可以以数组开头：

[
  {"id": 1, "name": "Alpha"},
  {"id": 2, "name": "Beta"}
]

适合小型静态列表或批量导出。许多 REST API 更倾向用对象包装，以便放置元数据。

包装对象

把列表与元数据放在一起：

{
  "data": [
    {"id": 1, "name": "Alpha"}
  ],
  "meta": { "total": 42, "page": 1 }
}

字段名各异（data、items、results 等），思路一致：载荷 + 上下文。

分页字段

常见模式：

{
  "items": [],
  "nextCursor": "abc123",
  "hasMore": true
}

或 offset 风格的 page、pageSize、totalCount。客户端不应假设字段名——以各 API 规范为准。

纯对象文档

配置通常是单个对象：

{
  "theme": "dark",
  "features": { "beta": false }
}

根级无数组；嵌套对象分组设置项。

如何选择形态

倾向对象根	根数组可接受
需要分页、错误信息与数据并列	固定小目录
有版本号或 links 等元信息	内部工具、测试夹具
同一端点多种资源类型	简单公开数据流

自家 API 内部一致 比照搬他人字段名更重要。