Bicep 的最佳做法

本文建議開發 Bicep 檔案時要遵循的做法。 這些做法可讓您的 Bicep 檔案更容易被理解和使用。

訓練資源

如果您比較想要透過逐步指導來了解 Bicep 的最佳做法，請參閱架構您的 Bicep 程式碼以進行共同作業。

參數

• 請為參數宣告妥善命名。 好的名稱可讓您的範本更易於閱讀及理解。 請務必使用清楚的描述性名稱，而且命名方式一致。

• 請仔細思考您範本所使用的參數。 請盡量為會隨不同部署而改變的設定使用參數。 不會隨不同部署而改變的設定，可以使用變數與硬式編碼值。

• 請留意您使用的預設值。 請確定預設值對要任何人都是安全的，可以進行部屬。 例如，請考慮使用低成本的定價層和 SKU，避免將範本部署至測試環境的使用者衍生不必要的大量成本。

• 盡量不使用 @allowed 裝飾項目。 如果您太廣泛地使用此裝飾項目，您可能會阻擋有效的部署。 隨著 Azure 服務新增 SKU 以及增加尺寸大小，您的允許清單可能不會是最新的版本。 例如，只允許進階版 v3 SKU 在生產環境中可能是合理的，但這麼做會使您無法在非生產環境中使用相同的範本。

• 建議您為參數提供描述。 請提供有所助益的描述，並提供範本所需參數值的相關重要資訊。

  您也可以使用 // 註解，於 Bicep 檔案內新增附注。

• 您可以將參數宣告放在範本檔案中的任何位置，但通常最好是將其放在檔案的最上方，使得您的 Bicep 程式碼易於讀取。

• 為控制命名的參數指定字元長度上限和下限是良好做法。 這些限制有助於避免以後在部署過程中發生錯誤。

如需 Bicep 參數的詳細資訊，請參閱Bicep 中的參數。

變數

• 定義變數時，不需要資料類型。 變數會從解析值推斷類型。

• 您可以使用 Bicep 函數來建立變數。

• 在 Bicep 檔案中定義變數之後，您可以使用該變數的名稱來參考值。

如需 Bicep 變數的詳細資訊，請參閱Bicep 中的變數。

名稱

• 針對名稱使用小駝峰式命名法，例如 myVariableName 或 myResource。

• uniqueString() 函數適用於建立唯一的資源名稱。 提供相同參數時，每次都會傳回相同的字串。 傳入資源群組識別碼表示每次對相同資源群組進行部署時，該字串都會是相同的，但在部署至不同資源群組或訂用帳戶時，則會不同。

• 使用範本運算式來建立資源名稱是很好的作法，如下列範例所示：

  param shortAppName string = 'toy'
  param shortEnvironmentName string = 'prod'
  param appServiceAppName string = '${shortAppName}-${shortEnvironmentName}-${uniqueString(resourceGroup().id)}'
  

  使用範本運算式來建立資源名稱，可為您帶來多個優點：

  • 由 uniqueString() 所產生的字串不具意義。 使用範本運算式來建立包含有意義資訊的名稱會有所幫助，例如專案或環境名稱的簡短描述項，以及讓名稱更容易是唯一的隨機元件。

  • uniqueString() 函式不保證全域唯一的名稱。 藉由將其他文字簡訊新增至您的資源名稱中，您可以降低重複使用現有資源名稱的可能性。

  • uniqueString() 函數有時候會建立以數字開頭的字串。 某些 Azure 資源 (例如儲存體帳戶) 不允許名稱開頭為數字。 此需求表示使用字串內插補點來建立資源名稱是很好的做法。 您可以新增首碼至唯一字串。

  • 許多 Azure 資源類型都有關於允許的字元和其名稱長度的規則。 在範本中內嵌資源名稱建立，表示使用該範本的任何人都不必自己記得遵循這些規則。

• 避免在符號名稱中使用 name。 符號名稱代表資源，而不是資源的名稱。 例如，避免使用下列語法：

  resource cosmosDBAccountName 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {
  

  使用：

  resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {
  

• 避免使用尾碼來區分變數與參數。

資源定義

• 不要直接將複雜的運算式內嵌至資源屬性，而是使用變數來包含運算式。 此方法可讓您的 Bicep 檔案更容易被讀取和了解。 其可避免因邏輯使得資源定義雜亂無章。

• 請嘗試使用資源屬性作為輸出，而不是假設資源的行為模式。 例如，如果您需要將 URL 輸出至 App Service 應用程式，請使用應用程式的 defaultHostname 屬性，而不要自行為 URL 建立字串。 有時候這些假設在不同的環境中並不正確，或資源會變更其運作方式。 讓資源告訴您自身的屬性會更安全。

• 最好是針對每個資源使用最新的 API 版本。 Azure 服務中的新功能有時只適用於較新的 API 版本。

• 可能的話，請避免在您的 Bicep 檔案中使用reference和resourceId函式。 您可以使用符號名稱來存取 Bicep 中的任何資源。 例如，如果您使用符號名稱 toyDesignDocumentsStorageAccount 定義儲存體帳戶，您可以使用運算式 toyDesignDocumentsStorageAccount.id 來存取其資源識別碼。 透過使用符號名稱，您可以建立資源之間的隱含相依性。

• 傾向使用隱含相依性優先於明確相依性。 雖然 dependsOn 資源屬性可讓您宣告資源之間的明確相依性，但通常可以使用其他資源的符號名稱來使用該資源的屬性。 此方法會在這兩個資源之間建立隱含相依性，並讓 Bicep 能夠管理這種關聯性。

• 如果未在 Bicep 檔案中部署資源，您仍然可以使用 existing 關鍵字來取得資源的符號參考。

子資源

• 避免建立太多層級的巢套。 過多的巢套會讓您的 Bicep 程式碼更難被讀取及使用。

• 避免為子資源建構資源名稱。 當其了解資源之間的關聯性時，您將會喪失 Bicep 提供的權益。 請改用 parent 屬性或巢套。

輸出

• 請確定您未建立敏感性資料的輸出。 任何人只要有權存取部署歷程記錄，都能存取輸出值。 這些人並不適合處理祕密。

• 避免透過輸出傳遞屬性值，而是使用現有關鍵字來查閱已存在資源的屬性。 最佳做法是以這種方式查閱其他資源中的索引鍵，而不是透過輸出來傳遞索引鍵。 如此永遠會取得最新的資料。

如需 Bicep 輸出的詳細資訊，請參閱Bicep 中的輸出。

租用戶範圍

您無法在租用戶範圍建立原則或角色指派。 不過，如果您需要授與存取權或將原則套用於整個組織，您可以將這些資源部署到根管理群組。

下一步

• 如需 Bicep 的簡介，請參閱Bicep 快速入門。
• 如需 Bicep 檔案組件的資訊，請參閱了解 Bicep 檔案的結構和語法。