4. 模块基础结构：模块目录标准布局与核心文件

一个可复用、可共享的 Terraform 模块，其文件结构必须遵循社区约定和官方推荐标准。标准化的目录布局不仅让模块使用者一目了然，还能被 Terraform Registry、服务目录工具（如 Terraform Cloud 的模块库）自动识别和解析。本章将详细拆解模块的四个核心文件：main.tf、variables.tf、outputs.tf 和 versions.tf，并说明它们各自的作用与最佳实践。

4.1 模块目录标准布局

一个典型的 Terraform 模块仓库根目录结构如下：

terraform-aws-vpc/
├── main.tf          # 核心资源定义
├── variables.tf     # 输入变量声明
├── outputs.tf       # 输出值声明
├── versions.tf      # Terraform 与 Provider 版本约束
├── README.md        # 模块说明文档
├── examples/        # 使用示例目录
│   └── basic/
│       ├── main.tf
│       ├── variables.tf
│       └── outputs.tf
├── tests/           # 测试目录（可选）
└── modules/         # 嵌套子模块目录（可选）
    └── sub-module/
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

其中，main.tf、variables.tf、outputs.tf 和 versions.tf 是模块的四个基础文件，缺一不可。下表总结了每个文件的核心职责：

4.2 核心文件详解

4.2.1 main.tf —— 资源定义中心

main.tf 是模块的主体文件，包含所有需要创建、管理或引用的云资源。它通常包含 resource 块和 data 块。模块使用者通过调用模块，间接创建这些资源。

# main.tf 示例：创建一个 AWS VPC 模块的核心资源
resource "aws_vpc" "this" {
  cidr_block           = var.vpc_cidr
  enable_dns_support   = var.enable_dns_support
  enable_dns_hostnames = var.enable_dns_hostnames

  tags = merge(
    var.tags,
    {
      Name = var.vpc_name
    }
  )
}

resource "aws_subnet" "public" {
  count = var.create_public_subnets ? length(var.public_subnet_cidrs) : 0

  vpc_id            = aws_vpc.this.id
  cidr_block        = var.public_subnet_cidrs[count.index]
  availability_zone = var.availability_zones[count.index]

  map_public_ip_on_launch = true

  tags = merge(
    var.tags,
    {
      Name = "${var.vpc_name}-public-${count.index + 1}"
      Tier = "public"
    }
  )
}

4.2.2 variables.tf —— 输入接口定义

variables.tf 定义了模块的输入参数，是模块与外部世界交互的接口。每个变量都应包含 type、description，并尽可能提供 default 值或 validation 规则。

# variables.tf 示例
variable "vpc_name" {
  description = "VPC 的名称标签"
  type        = string
}

variable "vpc_cidr" {
  description = "VPC 的 CIDR 地址块"
  type        = string
  default     = "10.0.0.0/16"

  validation {
    condition     = can(cidrhost(var.vpc_cidr, 0))
    error_message = "VPC CIDR 必须是一个有效的 IPv4 CIDR 地址块。"
  }
}

variable "availability_zones" {
  description = "可用区列表"
  type        = list(string)
}

variable "tags" {
  description = "应用于所有资源的标签映射"
  type        = map(string)
  default     = {}
}

variable "create_public_subnets" {
  description = "是否创建公有子网"
  type        = bool
  default     = true
}

variable "public_subnet_cidrs" {
  description = "公有子网的 CIDR 列表"
  type        = list(string)
  default     = []
}

4.2.3 outputs.tf —— 输出接口定义

outputs.tf 定义了模块对外暴露的信息，如资源 ID、ARN、DNS 名称等。这些输出可以被模块调用方引用，或作为其他模块的输入。

# outputs.tf 示例
output "vpc_id" {
  description = "创建的 VPC 的 ID"
  value       = aws_vpc.this.id
}

output "vpc_arn" {
  description = "创建的 VPC 的 ARN"
  value       = aws_vpc.this.arn
}

output "public_subnet_ids" {
  description = "公有子网 ID 列表"
  value       = aws_subnet.public[*].id
}

output "public_subnet_cidrs" {
  description = "公有子网 CIDR 列表"
  value       = aws_subnet.public[*].cidr_block
}

4.2.4 versions.tf —— 版本约束声明

versions.tf 用于声明模块所依赖的 Terraform 版本和 Provider 版本。这是确保模块在不同环境中行为一致的关键文件。

# versions.tf 示例
terraform {
  required_version = ">= 1.3.0, < 2.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.0.0, < 6.0.0"
    }
    random = {
      source  = "hashicorp/random"
      version = ">= 3.5.0"
    }
  }
}

4.3 模块文件关系与数据流

下图展示了四个核心文件之间的数据流向与依赖关系：

4.4 模块目录布局的进阶模式

除了基础的四文件结构，生产级模块仓库通常还会包含以下目录和文件：

• examples/：提供至少一个完整的使用示例，展示如何调用该模块。示例本身也是一个完整的 Terraform 配置，可以直接 terraform apply 测试。
• tests/：包含自动化测试代码（如 Terratest 或 Terraform 测试框架），验证模块在不同输入下的行为。
• modules/：当模块变得复杂时，可以拆分为多个嵌套子模块。每个子模块拥有自己的 main.tf、variables.tf、outputs.tf。
• README.md：模块的文档入口，包含模块用途、前置条件、输入输出说明、使用示例等。

4.5 常见错误与避坑指南

4.6 模块结构可视化总览

下图展示了标准模块仓库的完整目录结构与文件职责：