通过添加注释和元数据来记录代码

4 分钟

好的 Bicep 代码是自文档化的。这意味着它使用明确的命名和良好的结构，当同事阅读你的代码时，他们可以快速了解所发生的情况。如果他们需要进行更改，便可放心地修改正确的地方。

但在某些情况下，可能需要将额外的文档添加到 Bicep 文件来阐明某些代码。此外，在部署模板并在 Azure 中创建资源后，让查看 Azure 环境的任何人了解每项资源及其用途非常重要。

本单元将介绍如何将注释添加到 Bicep 文件，以及如何使用资源标记将元数据添加到 Azure 资源。此附加文档可让你的同事深入了解代码的作用、用于编写代码的逻辑，以及 Azure 资源的用途。

向代码添加注释

Bicep 使你能够向代码添加注释。注释是用于记录代码，但在将文件部署到 Azure 时将被忽略的可读文本。

Bicep 支持两种类型的注释：

单行注释以双斜杠 (//) 字符序列开始，然后持续到行尾，如下所示：

// We need to define a firewall rule to allow Azure services to access the database.

resource firewallRule 'Microsoft.Sql/servers/firewallRules@2023-08-01-preview' = {
  parent: sqlServer
  name: 'AllowAllAzureIPs'
  properties: {
    startIpAddress: '0.0.0.0' // This combination represents 'all Azure IP addresses'.
    endIpAddress: '0.0.0.0'
  }
}

多行注释使用 /* 和 */ 字符序列来环绕注释，可跨越多行，如下所示：

/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/

提示

避免对代码中明显和清晰的部分使用注释。注释过多实际上会降低代码的可读性。此外，当代码在将来发生更改时，很容易忘记更新注释。专注于记录唯一的逻辑和复杂表达式。

还可使用 Bicep 注释在每个文件的开头添加一个结构化的多行块。可将其视为清单。你的团队可能会决定为每个模板和模块提供一个清单来描述模板的用途及其包含的内容，如下例所示：

/*
  SYNOPSIS: Module for provisioning Azure SQL server and database.
  DESCRIPTION: This module provisions an Azure SQL server and a database, and configures the server to accept connections from within Azure.
  VERSION: 1.0.0
  OWNER TEAM: Website
*/

向参数文件添加注释

使用参数文件，可创建 JSON 文件，用于为部署指定一组参数值。参数值需要与 Bicep 模板中声明的参数匹配。

在参数文件中指定的值也可从文档化中受益。当使用的参数值可能无法让读取文件的人立即明白时，向参数文件添加注释是个很好的做法。

例如，网站的 Bicep 模板可能包含用于访问公司产品库存 API 的 URL 参数，以便网站可以显示玩具在仓库中是否还有存货。用于访问每个环境的库存 API 的 URL 不容易理解，因此很适合为其添加注释：

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
      "productStockCheckApiUrl": {
        "value": "https://x73.mytoycompany.com/e4/j7" // This is the URL to the product stock API in the development environment.
      }
    }
  }

提示

使用参数文件和其他包含注释的 JSON 文件时，通常需要使用 .jsonc 文件扩展名而不是 .json。这有助于让 Visual Studio Code 和其他工具了解允许进行注释。

向参数、变量和输出添加说明

创建参数、变量或输出时，可以应用 @description() 修饰器来帮助说明其用途：

@description('The Azure region into which the resources should be deployed.')
param location string = resourceGroup().location

@description('Indicates whether the web application firewall policy should be enabled.')
var enableWafPolicy = (environmentType == 'prod')

@description('The default host name of the App Service app.')
output hostName string = app.properties.defaultHostName

说明比注释的功能更强大，因为如果使用适用于 Bicep 的 Visual Studio Code 扩展，当将鼠标悬停在象征性名称上时，会显示说明。此外，当有人使用你的 Bicep 文件作为模块时，他们将看到你应用于参数的说明。

向资源添加说明

向你定义的资源添加说明也很有帮助。也可以将 @description() 修饰器应用于资源。

此外，某些资源支持将说明或其他可读信息添加到资源本身。例如，许多 Azure Policy 资源以及 Azure 基于角色的访问控制 (RBAC) 角色分配都包含描述属性，如下所示：

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  scope: storageAccount
  name: guid(roleDefinitionId, resourceGroup().id)
  properties: {
    principalType: 'ServicePrincipal'
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    principalId: principalId
    description: 'Contributor access on the storage account is required to enable the application to create blob containers and upload blobs.'
  }
}

建议使用此属性说明创建每个角色分配的原因。使用资源将说明部署到 Azure，使审核 Azure 环境的 RBAC 配置的任何人都可以立即理解角色分配的用途。

应用资源标记

Bicep 文件中的注释不会出现在部署的资源中。它们只是帮助你记录 Bicep 文件。但在许多情况下，都需要跟踪已部署的 Azure 资源的相关信息，包括：

将 Azure 成本分配给特定成本中心。
了解如何对数据库和存储帐户中包含的数据进行分类和保护。
记录负责管理资源的团队名称或人员姓名。
跟踪与资源相关的环境的名称，例如生产或开发。

使用资源标记，可存储有关资源的重要元数据。在 Bicep 代码中定义资源标记，Azure 在部署资源时将相关信息与资源一起存储：

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  name: storageAccountName
  location: location
  tags: {
    CostCenter: 'Marketing'
    DataClassification: 'Public'
    Owner: 'WebsiteTeam'
    Environment: 'Production'
  }
  sku: {
    name: storageAccountSkuName
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
  }
}

使用 Azure PowerShell 和 Azure CLI 等工具可查询资源的标记，在 Azure 门户网站上可查看标记：

存储帐户的 Azure 门户屏幕截图，其中显示了标记的位置。

对所有资源使用一组相同的标记十分常见，所以通常建议将标记定义为参数或变量，然后在每项资源上重用它们：