- Google JSON 风格指南 - UDN开源文档

属性名准则

属性名格式

选择有意义的属性名

属性名必须遵循以下准则:

属性名应该是具有定义语义的有意义的名称。
属性名必须是驼峰式的，ASCII码字符串。
首字符必须式字母，下划线(_)或美元符号($)。
随后的其他字符可以是字母，数字，下划线(_)或美元符号($)。
应该避免使用Javascript中的保留关键字(下文附有Javascript保留字清单)

这些准则反映JavaScript标识符命名的指导方针。使JavaScript的客户端可以使用点符号来访问属性。(例如, result.thisIsAnInstanceVariable).

下面是一个对象的一个属性的例子：

{
  "thisPropertyIsAnIdentifier": "identifier value"
}

JSON Map中的键名

在JSON Map中键名可以使用任意Unicode字符

当JSON对象作为Map(映射)使用时，属性的名称命名规则并不适用。Map（也称作关联数组）是一个具有任意键/值对的数据类型，这些键/值对通过特定的键来访问相应的值。JSON对象和JSON Map在运行时看起来是一样的；这个特性与API设计相关。当JSON对象被当作map使用时，API文件应当做出说明。

Map的键名不一定要遵循属性名称的命名准则。键名可以包含任意的Unicode字符。客户端可使用maps熟悉的方括号来访问这些属性。（例如result.thumbnails["72"]）

{
  // "address" 属性是一个子对象
  // 包含地址的各部分.
  "address": {
    "addressLine1": "123 Anystreet",
    "city": "Anytown",
    "state": "XX",
    "zip": "00000"
  },
  // "address" 是一个映射
  // 含有响应规格所对应的URL，用来映射thumbnail url的像素规格
  "thumbnails": {
    "72": "http://url.to.72px.thumbnail",
    "144": "http://url.to.144px.thumbnail"
  }
}

保留的属性名称

某些属性名称会被保留以便能在多个服务间相容使用

保留属性名称的详细信息，连同完整的列表，可在本指南后面的内容中找到。服务应按照被定义的语义来使用属性名称。

单数属性名 VS 复数属性名

数组类型应该是复数属性名。其它属性名都应该是单数。

数组通常包含多个条目，复数属性名就反映了这点。在下面这个保留名称中可以看到例子。属性名items是复数因为它描述的是一组对象。大多数的其它字段是单数。

当然也有例外，尤其是涉及到数字的属性值的时候。例如，在保留属性名中，totalItems 比 totalItem更合理。然后，从技术上讲，这并不违反风格指南，因为 totalItems 可以被看作 totalOfItems, 其中 total 是单数（依照风格指南），OfItems 用来限定总数。字段名也可被改为 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"]
  }
}