屬性名準(zhǔn)則

屬性名格式

選擇有意義的屬性名

屬性名必須遵循以下準(zhǔn)則:

• 屬性名應(yīng)該是具有定義語義的有意義的名稱。
• 屬性名必須是駝峰式的，ASCII碼字符串。
• 首字符必須式字母，下劃線(__)或美元符號($_)。
• 隨后的其他字符可以是字母，數(shù)字，下劃線(__)或美元符號($_)。
• 應(yīng)該避免使用Javascript中的保留關(guān)鍵字(下文附有Javascript保留字清單)

這些準(zhǔn)則反映JavaScript標(biāo)識符命名的指導(dǎo)方針。使JavaScript的客戶端可以使用點(diǎn)符號來訪問屬性。(例如,result.thisIsAnInstanceVariable).

下面是一個(gè)對象的一個(gè)屬性的例子：

{
  "thisPropertyIsAnIdentifier": "identifier value"
}

JSON Map中的鍵名

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

當(dāng)JSON對象作為Map(映射)使用時(shí)，屬性的名稱命名規(guī)則并不適用。Map（也稱作關(guān)聯(lián)數(shù)組）是一個(gè)具有任意鍵/值對的數(shù)據(jù)類型，這些鍵/值對通過特定的鍵來訪問相應(yīng)的值。JSON對象和JSON Map在運(yùn)行時(shí)看起來是一樣的；這個(gè)特性與API設(shè)計(jì)相關(guān)。當(dāng)JSON對象被當(dāng)作map使用時(shí)，API文件應(yīng)當(dāng)做出說明。

Map的鍵名不一定要遵循屬性名稱的命名準(zhǔn)則。鍵名可以包含任意的Unicode字符。客戶端可使用maps熟悉的方括號來訪問這些屬性。（例如result.thumbnails["72"]）

{
  // "address" 屬性是一個(gè)子對象
  // 包含地址的各部分.
  "address": {
    "addressLine1": "123 Anystreet",
    "city": "Anytown",
    "state": "XX",
    "zip": "00000"
  },
  // "address" 是一個(gè)映射
  // 含有響應(yīng)規(guī)格所對應(yīng)的URL，用來映射thumbnail url的像素規(guī)格
  "thumbnails": {
    "72": "http://url.to.72px.thumbnail",
    "144": "http://url.to.144px.thumbnail"
  }
}

保留的屬性名稱

某些屬性名稱會被保留以便能在多個(gè)服務(wù)間相容使用

保留屬性名稱的詳細(xì)信息，連同完整的列表，可在本指南后面的內(nèi)容中找到。服務(wù)應(yīng)按照被定義的語義來使用屬性名稱。

單數(shù)屬性名 VS 復(fù)數(shù)屬性名

數(shù)組類型應(yīng)該是復(fù)數(shù)屬性名。其它屬性名都應(yīng)該是單數(shù)。

數(shù)組通常包含多個(gè)條目，復(fù)數(shù)屬性名就反映了這點(diǎn)。在下面這個(gè)保留名稱中可以看到例子。屬性名_items_是復(fù)數(shù)因?yàn)樗枋龅氖且唤M對象。大多數(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" 看起來并不對
  "totalItems": 10,
  // 但 "itemCount" 要好些
  "itemCount": 10,
}

命名沖突

通過選擇新的屬性名或?qū)PI版本化來避免命名沖突

新的屬性可在將來被添加進(jìn)保留列表中。JSON中不存在命名空間。如果存在命名沖突，可通過選擇新的屬性名或者版本化來解決這個(gè)問題。例如，假設(shè)我們由下面的JSON對象開始：

{
  "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"]
  }
}