1.2.8.1. examples/ 文件夹的设计与实践

在 Terraform 模块开发中，examples/ 文件夹扮演着至关重要的角色。它不仅帮助用户理解模块的实际应用场景，还提供了可运行的示例配置，降低了模块的学习曲线。本章将深入探讨 examples/ 文件夹的作用、结构设计、文档编写以及在团队协作中的最佳实践。

1.2.8.1.1. examples/ 文件夹的作用

examples/ 文件夹主要用于存放模块的使用示例，帮助用户：

• 了解模块的实际应用场景。
• 快速上手并测试模块功能。
• 参考最佳实践配置，避免常见错误。

每个示例应是完备的，必须包含必要的 Terraform 配置文件和说明文档，确保用户可以直接运行 terraform apply 并理解示例的目的（这意味着演示模块功能所需要的所有前置资源都必须在示例代码中创建出来）。

示例应当尽可能体现最佳实践，或者至少，不应该使用已知的反模式，例如使用硬编码的弱密码，或是创建没有备份策略的数据库等等。

1.2.8.1.2. 示例结构设计

为了提高可读性和可维护性，建议按照类似以下结构组织 examples/ 文件夹：

examples/
├── default/
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   └── README.md
├── advanced/
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   └── README.md
└── ...

每个子目录代表一个独立的使用场景（例如：带有 Private Endpoint、使用自有容器镜像仓库并且配置相应凭据，等等），包含完整的 Terraform 配置文件和对应的说明文档。这样不仅方便用户查阅和测试，也有助于模块的持续维护和更新。

1.2.8.1.3. 示例文档编写指南

每个示例子目录中的 README.md 文件应包含以下内容：

• 示例概述：简要描述该示例的目的和应用场景。
• 使用方法：提供运行示例的步骤，包括必要的前置条件和命令。
• 配置说明：解释主要的输入变量和输出结果，帮助用户理解配置的含义。
• 注意事项：提示用户在使用该示例时需要注意的问题，如资源依赖、权限要求等。

同模块文档一样，示例文档也应当通过使用 terraform-docs 来生成。

1.2.8.1.4. 示例的自动化测试

为了确保示例的有效性和可用性，建议在持续集成（CI）流程中加入示例的自动化测试。可以使用工具如 Terratest 或 Kitchen-Terraform 来实现自动化测试，验证示例的正确性和稳定性。

为使用户可以快速体验模块功能，我们强烈建议所有示例都应该设计成不需要用户提供任何输入，在配置了必要的调用凭据（例如 Azure 凭据信息）后，就可以直接通过 terraform apply 命令部署。我们必须配置相应的自动化测试，及时发现和修复示例中的问题，保持示例与模块代码的一致性，提升模块的整体质量。

我们将在后续章节中详细讨论测试相关话题。