選擇有意義的屬性名
屬性名必須遵循以下準(zhǔn)則:
這些準(zhǔn)則反映JavaScript標(biāo)識(shí)符命名的指導(dǎo)方針。使JavaScript的客戶端可以使用點(diǎn)符號(hào)來訪問屬性。(例如,result.thisIsAnInstanceVariable
).
下面是一個(gè)對(duì)象的一個(gè)屬性的例子:
{
"thisPropertyIsAnIdentifier": "identifier value"
}
在JSON Map中鍵名可以使用任意Unicode字符
當(dāng)JSON對(duì)象作為Map(映射)使用時(shí),屬性的名稱命名規(guī)則并不適用。Map(也稱作關(guān)聯(lián)數(shù)組)是一個(gè)具有任意鍵/值對(duì)的數(shù)據(jù)類型,這些鍵/值對(duì)通過特定的鍵來訪問相應(yīng)的值。JSON對(duì)象和JSON Map在運(yùn)行時(shí)看起來是一樣的;這個(gè)特性與API設(shè)計(jì)相關(guān)。當(dāng)JSON對(duì)象被當(dāng)作map使用時(shí),API文件應(yīng)當(dāng)做出說明。
Map的鍵名不一定要遵循屬性名稱的命名準(zhǔn)則。鍵名可以包含任意的Unicode字符??蛻舳丝墒褂胢aps熟悉的方括號(hào)來訪問這些屬性。(例如result.thumbnails["72"]
)
{
// "address" 屬性是一個(gè)子對(duì)象
// 包含地址的各部分.
"address": {
"addressLine1": "123 Anystreet",
"city": "Anytown",
"state": "XX",
"zip": "00000"
},
// "address" 是一個(gè)映射
// 含有響應(yīng)規(guī)格所對(duì)應(yīng)的URL,用來映射thumbnail url的像素規(guī)格
"thumbnails": {
"72": "http://url.to.72px.thumbnail",
"144": "http://url.to.144px.thumbnail"
}
}
某些屬性名稱會(huì)被保留以便能在多個(gè)服務(wù)間相容使用
保留屬性名稱的詳細(xì)信息,連同完整的列表,可在本指南后面的內(nèi)容中找到。服務(wù)應(yīng)按照被定義的語義來使用屬性名稱。
數(shù)組類型應(yīng)該是復(fù)數(shù)屬性名。其它屬性名都應(yīng)該是單數(shù)。
數(shù)組通常包含多個(gè)條目,復(fù)數(shù)屬性名就反映了這點(diǎn)。在下面這個(gè)保留名稱中可以看到例子。屬性名_items_是復(fù)數(shù)因?yàn)樗枋龅氖且唤M對(duì)象。大多數(shù)的其它字段是單數(shù)。
當(dāng)然也有例外,尤其是涉及到數(shù)字的屬性值的時(shí)候。例如,在保留屬性名中,totalItems?比?_totalItem_更合理。然后,從技術(shù)上講,這并不違反風(fēng)格指南,因?yàn)?totalItems?可以被看作?totalOfItems, 其中?total?是單數(shù)(依照風(fēng)格指南),OfItems?用來限定總數(shù)。字段名也可被改為?itemCount,這樣看起來更象單數(shù).
{
// 單數(shù)
"author": "lisa",
// 一組同胞, 復(fù)數(shù)
"siblings": [ "bart", "maggie"],
// "totalItem" 看起來并不對(duì)
"totalItems": 10,
// 但 "itemCount" 要好些
"itemCount": 10,
}
通過選擇新的屬性名或?qū)PI版本化來避免命名沖突
新的屬性可在將來被添加進(jìn)保留列表中。JSON中不存在命名空間。如果存在命名沖突,可通過選擇新的屬性名或者版本化來解決這個(gè)問題。例如,假設(shè)我們由下面的JSON對(duì)象開始:
{
"apiVersion": "1.0",
"data": {
"recipeName": "pizza",
"ingredients": ["tomatoes", "cheese", "sausage"]
}
}
如果我們希望將來把_ingredients_列為保留字,我們可以通過下面兩件事情來達(dá)成。 1.選一個(gè)不同的名字
{
"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"]
}
}
更多建議: