1.2.7.1. 高质量的 Terraform 模块 README

在 Terraform 模块开发与维护的过程中，清晰、准确的文档对于模块的可用性和可维护性至关重要。特别是当模块发布到 Terraform Registry 后，用户通过 Registry 页面获取模块信息时，主要依赖于模块的 README.md 文件。因此，编写一份结构清晰、内容详实的 README 是模块开发的重要组成部分。

为什么模块的 README 如此重要？

除了帮助用户理解和使用模块，良好的文档还可以：

帮助模块用户快速了解模块的功能和使用方法。
降低模块使用和维护的学习成本。
就使用中的潜在风险对用户进行提示。
不要手写文档

为了确保文档的准确性和一致性，建议使用 terraform-docs 工具自动生成模块的部分内容，如输入变量、输出变量、资源等。

我们将在后续章节对 terraform-docs 进行详细介绍，本章不再赘述相关内容。

1.2.7.1.1. README 的推荐结构

一个清晰的 README.md 文件通常包括以下几个部分：

模块简介

简要描述模块的功能和用途。例如：

## 模块名称

本模块用于创建和管理 Azure Virtual Network，包括子网、路由表等资源。

注意事项

提醒用户在使用模块时需要注意的事项，例如：

大版本更新中包含的破坏性变更记录。
可能的限制或已知问题。

注意，由于此类信息是无法由自动化工具提取标注在文档中的，所以当我们引入了某种存在风险，需要特别说明的变更时，请务必在文档中进行提示。

1.2.7.1.1.1. 使用示例

提供至少一个基本的使用示例，帮助用户快速上手：

module "vpc" {
  source = "terraform-aws-modules/vpc/aws"
  name   = "my-vpc"
  cidr   = "10.0.0.0/16"
  azs    = ["us-west-1a", "us-west-1b", "us-west-1c"]
...
}

示例相关文档应放置在 examples/ 目录下对应的子目录内，名字也是 README.md，也应该使用自动化工具生成。

输入变量

列出模块支持的所有输入变量，包括名称、类型、默认值和描述。使用 terraform-docs 可以自动生成此部分内容。

输出值

列出模块定义的所有输出变量，包括名称和描述。同样可以使用 terraform-docs 自动生成。

1.2.7.1.2. 在大规模模块治理与维护中的最佳实践

为了在数百个模块中保持文档的一致性和高质量，建议采用以下实践：

1.2.7.1.2.1. 使用预提交钩子自动生成文档

通过配置 pre-commit 钩子，在每次提交代码前自动运行 terraform-docs，确保文档始终与代码保持同步。

1.2.7.1.2.2. 在 CI/CD 流程中集成文档生成

在持续集成流程中添加文档检查步骤，确保每次合并的代码都包含了已正确更新的文档。

README