3. 模块化设计原则：模块封装、单一职责、组合与复用、版本控制、输入输出变量设计规范

模块化是 Terraform 生产级实践的核心。在 CI/CD 服务目录环境中，模块不仅是代码的复用单元，更是治理、安全与变更管理的边界。本章围绕五项核心原则，建立模块设计的规范体系。

3.1 模块封装：隐藏实现，暴露契约

封装要求模块对外隐藏内部资源定义、数据源和 provider 配置，仅通过 输入变量 和 输出值 与调用方交互。调用方不应感知模块使用了哪种计算实例类型、安全组规则细节或存储后端。

3.2 单一职责：一个模块只做一件事

单一职责原则要求每个模块只负责管理 一类基础设施资源 或 一个明确的业务能力。如果一个模块同时管理 VPC、EC2 和 RDS，则职责过重，难以测试、复用和版本化。

3.3 组合与复用：从原子模块到复合模块

组合原则将小粒度、单一职责的 原子模块 通过 module 块嵌套，构建出 复合模块 或 服务目录模板。复用不是复制代码，而是通过 source 引用已发布的模块版本。

3.4 版本控制：模块即制品

模块必须像软件制品一样进行版本管理。Terraform 通过 version 约束和 Git 标签实现模块版本控制。

3.5 输入输出变量设计规范

输入输出变量是模块的契约接口，设计质量直接影响模块的可复用性和可维护性。

3.5.1 输入变量设计规范

# variables.tf 规范示例
variable "vpc_cidr_block" {
  description = "VPC 的 IPv4 CIDR 块，例如 10.0.0.0/16"
  type        = string
  default     = "10.0.0.0/16"

  validation {
    condition     = can(cidrhost(var.vpc_cidr_block, 0))
    error_message = "vpc_cidr_block 必须是有效的 CIDR 表示法。"
  }
}

variable "subnet_configs" {
  description = "子网配置列表，每个元素包含 name、cidr、az"
  type = list(object({
    name = string
    cidr = string
    az   = string
  }))
  default = []
}

variable "db_password" {
  description = "数据库管理员密码"
  type        = string
  sensitive   = true
}

3.5.2 输出变量设计规范

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

output "subnet_ids" {
  description = "所有子网的 ID 列表"
  value       = aws_subnet.this[*].id
}

output "database_endpoint" {
  description = "RDS 实例的连接端点"
  value       = aws_db_instance.this.endpoint
  sensitive   = true
}