3. 服务目录设计原则：模块化、可复用、版本化、安全合规

服务目录是 Terraform 冷启动的核心资产，其设计质量直接决定资源交付的效率与风险。本章围绕四个核心原则展开：模块化（Modularity）、可复用（Reusability）、版本化（Versioning）、安全合规（Security & Compliance）。这四个原则相互支撑，共同构成生产级服务目录的骨架。

3.1 模块化：解耦与职责单一

模块化要求每个 Terraform 模块只负责一个明确的资源边界。例如，一个“VPC 模块”不应同时管理安全组和子网路由表——这些应拆分为独立子模块，通过变量和输出进行组合。

3.2 可复用：输入抽象与输出标准化

可复用性要求模块能够被不同环境（开发、测试、生产）和不同团队调用，而无需修改模块内部代码。关键手段包括：

• 变量抽象： 使用 variable 块定义环境差异点（如实例规格、标签、CIDR 范围），避免硬编码。
• 输出契约： 每个模块输出标准化的属性集，供下游模块或根模块消费。
• 条件逻辑： 通过 count 或 for_each 控制资源是否创建，适应不同场景。

# 可复用模块示例：通用 EC2 模块
variable "instance_config" {
  type = object({
    name          = string
    instance_type = string
    ami_id        = string
    subnet_id     = string
    volume_size   = optional(number, 30)
    tags          = optional(map(string), {})
  })
}

resource "aws_instance" "this" {
  ami           = var.instance_config.ami_id
  instance_type = var.instance_config.instance_type
  subnet_id     = var.instance_config.subnet_id

  root_block_device {
    volume_size = var.instance_config.volume_size
  }

  tags = merge(var.instance_config.tags, {
    Name = var.instance_config.name
  })
}

output "instance_attributes" {
  value = {
    id         = aws_instance.this.id
    private_ip = aws_instance.this.private_ip
    public_ip  = aws_instance.this.public_ip
    arn        = aws_instance.this.arn
  }
}

3.3 版本化：语义化版本与发布流程

版本化是服务目录的变更管理基石。Terraform 模块应遵循 语义化版本（SemVer）：MAJOR.MINOR.PATCH。

在服务目录中，版本化通过 Git Tag 或 Terraform Registry 的版本约束实现：

# 在根模块中引用特定版本
module "vpc" {
  source = "git::https://git.example.com/service-catalog/network/vpc.git?ref=v1.2.0"
  # 或使用 Terraform Registry 语法
  # source  = "terraform-aws-modules/vpc/aws"
  # version = "~> 5.0"
}

3.4 安全合规：内置策略与审计痕迹

安全合规是服务目录的底线。设计阶段应将安全策略内嵌到模块中，而非依赖事后扫描。核心手段包括：

• 默认安全： 模块变量设置安全默认值（如 S3 桶默认私有、安全组默认拒绝所有入站）。
• 策略即代码： 使用 precondition 和 postcondition 在 Plan 阶段校验合规要求。
• 加密与审计： 强制启用加密（KMS）、日志（CloudTrail）、访问分析（IAM Access Analyzer）。

# 安全合规内嵌示例：S3 模块强制加密和版本控制
resource "aws_s3_bucket" "this" {
  bucket = var.bucket_name

  # 使用 precondition 在 Plan 阶段校验标签
  lifecycle {
    precondition {
      condition     = contains(keys(var.tags), "Environment")
      error_message = "所有 S3 桶必须包含 Environment 标签"
    }
  }
}

resource "aws_s3_bucket_versioning" "this" {
  bucket = aws_s3_bucket.this.id
  versioning_configuration {
    status = "Enabled"  # 强制启用版本控制
  }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "this" {
  bucket = aws_s3_bucket.this.id
  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm = "aws:kms"  # 强制使用 KMS 加密
    }
  }
}

3.5 四原则协同矩阵

四个原则并非孤立存在，而是相互增强。下表展示它们在实际服务目录中的协同关系：