Skip to Content
JSON属性名指南

属性名指南

属性名格式

选择有意义的属性名。

属性名必须符合以下规则：

  • 属性名应该是具有明确语义的有意义名称。
  • 属性名必须是驼峰命名法（camelCase）的 ASCII 字符串。
  • 第一个字符必须是字母、下划线（_）或美元符号（$）。
  • 后续字符可以是字母、数字、下划线或美元符号。
  • 应避免使用 JavaScript 保留字（JavaScript 保留字列表见下文）。

这些规则与 JavaScript 标识符的命名规则一致。这允许 JavaScript 客户端使用点号表示法访问属性（例如 result.thisIsAnInstanceVariable）。以下是包含一个属性的对象示例：

{
  "thisPropertyIsAnIdentifier": "identifier value"
}

JSON 映射中的键名

JSON 映射（map）的键名可以使用任何 Unicode 字符。

当 JSON 对象用作映射（map）时，属性名命名规则不适用。映射（也称为关联数组）是一种数据类型，具有任意的键/值对，使用键来访问对应的值。JSON 对象和 JSON 映射在运行时看起来相同；这一区别与 API 设计相关。API 文档应指明何时将 JSON 对象用作映射。 映射的键不必遵循属性名的命名规则。映射的键可以包含任何 Unicode 字符。客户端可以使用映射常用的方括号表示法访问这些属性（例如 result.thumbnails["72"]）。

{
  // "address" 属性是一个子对象，
  // 包含地址的各个部分。
  "address": {
    "addressLine1": "123 Anystreet",
    "city": "Anytown",
    "state": "XX",
    "zip": "00000"
  },
  // "thumbnails" 属性是一个映射，
  // 将像素大小映射到该大小的缩略图 URL。
  "thumbnails": {
    "72": "https://url.to.72px.thumbnail",
    "144": "https://url.to.144px.thumbnail"
  }
}

保留属性名

某些属性名被保留用于跨服务的一致使用。

有关保留属性名的详细信息及完整列表，可以在本指南后面的部分找到。服务应避免将这些属性名用于其定义语义之外的用途。

单数 vs 复数属性名

数组类型应使用复数属性名。所有其他属性名应使用单数。

数组通常包含多个项目，复数属性名反映了这一点。下面的保留名称中可以看到示例。items 属性名是复数形式，因为它代表一个项目对象的数组。大多数其他字段是单数形式。 可能有一些例外，特别是在涉及数值属性值时。例如，在保留名称中，totalItems 比 totalItem 更合理。然而，从技术上讲，这并不违反风格指南，因为 totalItems 可以视为 totalOfItems，其中 total 是单数（符合风格指南），OfItems 用于限定 total。字段名也可以改为 itemCount 以呈现单数形式。

{
  // 单数
  "author": "lisa",
  // 兄弟姐妹数组，复数
  "siblings": [ "bart", "maggie"],
  // "totalItem" 听起来不对
  "totalItems": 10,
  // 但 "itemCount" 可能更好
  "itemCount": 10,
}

命名冲突

通过选择新的属性名或对 API 进行版本控制来避免命名冲突。

未来可能会有新的属性添加到保留列表中。JSON 没有命名空间的概念。如果出现命名冲突，通常可以通过选择新的属性名或进行版本控制来解决。例如，假设我们从以下 JSON 对象开始：

{
  "apiVersion": "1.0",
  "data": {
    "recipeName": "pizza",
    "ingredients": ["tomatoes", "cheese", "sausage"]
  }
}

如果将来我们希望将 ingredients 设为保留字，我们可以采取以下两种方式之一： 1）选择不同的名称：

{
  "apiVersion": "1.0",
  "data": {
    "recipeName": "pizza",
    "ingredientsData": "Some new property",
    "ingredients": ["tomatoes", "cheese", "sausage"]
  }
}

2）在主版本边界上重命名属性：

{
  "apiVersion": "2.0",
  "data": {
    "recipeName": "pizza",
    "ingredients": "Some new property",
    "recipeIngredients": ["tomatos", "cheese", "sausage"]
  }
}
Last updated on
通用指南属性值指南