属性名准则
最后更新于：2022-04-01 06:07:08
## 属性名格式
**选择有意义的属性名**
属性名必须遵循以下准则:
* 属性名应该是具有定义语义的有意义的名称。
* 属性名必须是驼峰式的，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"]
}
}
~~~