API响应数据返回是否有规范？三种返回格式如何抉择？

行业里没有强制统一的全球规范，但有通用的设计原则——核心看一致性、扩展性和可读性，下面直接拆解三种格式的优劣：

1. 带data键的对象（Version 1） #

{
  "data": [
    {"id":1,"name":"Mexico City"}
  ]
}

• 优势：通用性拉满，能统一所有API的响应结构。后续要加分页信息、状态码、提示文本这类元数据时，直接在顶层对象里加字段就行，完全不用改原有数据结构，比如：

  {
    "code": 200,
    "message": "请求成功",
    "data": [{"id":1,"name":"Mexico City"}],
    "page": 1,
    "total": 100
  }
  

• 劣势：简单场景下有点冗余，多了一层嵌套。

2. 直接返回数组（Version 2） #

[
  {"id":1,"name":"Mexico City"}
]

• 优势：最简洁，纯列表场景下前端解析直接用数组操作，省事儿。
• 劣势：扩展性基本为0。哪天要加分页、状态信息，要么彻底改结构，要么在数组里塞奇怪的额外数据（完全不规范）；另外部分HTTP客户端或框架处理数组响应时，存在JSON劫持的安全风险。

3. 带业务专属键的对象（Version 3） #

{
  "cities": [
    {"id":1,"name":"Mexico City"}
  ]
}

• 优势：语义清晰到离谱，一眼就知道返回的是城市列表。如果接口需要同时返回多个业务数据集（比如同时给cities和regions），这种结构天然支持，不用动顶层框架。
• 劣势：通用性弱，每个业务接口的顶层键都不一样，前端要适配不同的键名；后期加元数据虽然比数组灵活，但还是不如data键的统一结构省心。

最终选择参考 #

• 要是你做的是统一风格的后端服务（比如整套RESTful接口），优先选Version 1，保证所有接口结构一致，后期维护和扩展成本最低。
• 要是只是临时的简单列表接口，且确定永远不需要加额外元数据，可以用Version 2，但不推荐长期用。
• 要是接口业务针对性极强，或者需要同时返回多个业务数据集，选Version 3，语义明确不歧义。

内容的提问来源于stack exchange，提问作者Max Pattern