本文建议在开发 Bicep 文件时要遵循的做法。 这些做法使 Bicep 文件更易于理解和使用。
参数
对参数声明使用良好的命名。 好名称使模板易于阅读和理解。 请确保使用清晰的描述性名称,并在命名中保持一致。
仔细考虑模板所使用的参数。 尝试将参数用于在不同部署之间更改的设置。 变量和硬编码值可用于在部署之间不会发生更改的设置。
请注意使用的默认值。 确保默认值是安全的,可供任何人部署。 例如,请考虑使用低成本的定价层和 SKU,以便部署模板到测试环境时不会产生不必要的大量费用。
请尽量少用
@allowed
修饰器。 如果过于广泛使用此修饰器,可能会导致有效的部署被阻止。 随着 Azure 服务添加 SKU 和大小,允许的列表可能不是最新的。 例如,仅允许高级 v3 SKU 在生产环境中可能有意义,但它会阻止你在非生产环境中使用相同的模板。为参数提供说明是一种很好的做法。 尽量让这些说明有帮助,并提供有关模板所需参数值的重要信息。
还可以使用
//
注释在 Bicep 文件中添加笔记。可以在模板文件中的任意位置放置参数声明,尽管通常最好将它们放在文件顶部,以便 Bicep 代码易于阅读。
最好为控制命名的参数指定最小和最大字符长度。 这些限制有助于避免在部署过程中出现错误。
有关 Bicep 参数的详细信息,请参阅 Bicep 中的参数。
变量
定义变量时,不需要 数据类型 。 变量从解析值推断类型。
可以使用 Bicep 函数创建变量。
在 Bicep 文件中定义变量后,可以使用变量的名称引用该值。
有关 Bicep 变量的详细信息,请参阅 Bicep 中的变量。
名称
对命名(如
myVariableName
或myResource
)使用小驼峰命名法。uniqueString() 函数可用于创建唯一的资源名称。 提供相同的参数时,每次都会返回相同的字符串。 传入资源组 ID 意味着在部署到同一资源组时,字符串一致,但在部署到不同的资源组或订阅时会有所不同。
最好使用模板表达式创建资源名称,如以下示例所示:
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-11-15' = {
用:
resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2023-11-15' = {
避免使用后缀区分变量和参数。
资源定义
使用变量来包含表达式,而不是直接将复杂表达式嵌入资源属性中。 此方法使 Bicep 文件更易于阅读和理解。 它避免资源定义中因逻辑而变得混乱。
尝试使用资源属性作为输出,而不是假设资源的行为方式。 例如,如果需要将 URL 输出到应用服务,请使用该应用的 defaultHostname 属性,而不是自己创建 URL 字符串。 有时,这些假设在不同环境中不正确,或者资源会更改其工作方式。 让资源告诉你自己的属性更安全。
最好为每个资源使用最新的 API 版本。 Azure 服务中的新功能有时仅在较新的 API 版本中可用。
如果可能,请避免在 Bicep 文件中使用 引用 和 resourceId 函数。 可以使用符号名称访问 Bicep 中的任何资源。 例如,如果使用符号名称 toyDesignDocumentsStorageAccount 定义存储帐户,则可以使用表达式
toyDesignDocumentsStorageAccount.id
访问其资源 ID。 通过使用符号名称,可以在资源之间创建隐式依赖项。首选使用隐式依赖项而不是显式依赖项。
dependsOn
尽管资源属性使你能够声明资源之间的显式依赖关系,但通常可以通过使用其符号名称来使用其他资源的属性。 此方法在两个资源之间创建隐式依赖项,并使 Bicep 能够管理关系本身。如果资源未在 Bicep 文件中部署,仍可以使用
existing
关键字获取对该资源的符号引用。
子资源
避免嵌套过多的层级深度。 嵌套过多会使 Bicep 代码难以读取和使用。
避免为子级资源构造资源名称。 当 Bicep 无法了解资源之间的关系时,你将失去所提供的优势。 请改用
parent
属性或嵌套结构。
输出
使用 @secure() 修饰器在输出中标记敏感数据,这会阻止记录或显示敏感输出。 否则,任何有权访问部署历史记录的用户都可以访问输出值。
使用 现有关键字 查找已经存在的资源的属性,而不是通过输出传递属性值。 最佳做法是以这种方式查找其他资源的密钥,而不是通过输出传递密钥。 你将始终获得最新的数据。
有关 Bicep 输出的详细信息,请参阅 Bicep 中的输出。
租户范围
无法在 租户范围内创建策略或角色分配。 但是,如果需要在整个组织中授予访问权限或应用策略,可以将这些资源部署到根管理组。
后续步骤
- 有关 Bicep 简介,请参阅 Bicep 快速入门。
- 有关 Bicep 文件的各个部分的信息,请参阅 了解 Bicep 文件的结构和语法。