3、模块化设计原则：模块封装粒度、输入输出规范、版本管理、模块仓库结构

模块化封装是 Terraform 管理弹性伸缩运营任务编排的核心工程实践。良好的模块化设计能够提升代码复用性、降低维护成本、保障团队协作效率。本节从封装粒度、输入输出规范、版本管理、仓库结构四个维度展开，建立可落地的模块化设计标准。

3.1 模块封装粒度：单一职责与可组合性

模块粒度的选择直接影响编排的灵活性与复杂度。过粗的模块（如“整个弹性伸缩全流程”）难以复用；过细的模块（如“单个 API 调用”）则导致编排碎片化。推荐遵循单一职责原则，每个模块只封装一个明确的运营操作单元。

3.2 输入输出规范：接口契约与可读性

模块的输入输出是与其他模块或根配置交互的契约。规范化的接口设计能够减少集成错误，提升模块的可理解性。

3.2.1 输入变量规范

• 命名风格：使用下划线命名法（snake_case），如 scaling_group_name、min_size。
• 类型声明：必须显式声明 type，避免使用 any。
• 描述与默认值：每个变量必须包含 description，合理设置 default 或标记 nullable。
• 敏感变量：涉及密钥、 等敏感信息时，设置 sensitive = true。
• 验证规则：使用 validation 块约束取值范围，如端口范围、实例规格白名单。

# 输入变量规范示例
variable "scaling_group_name" {
  description = "弹性伸缩组的名称，需在账号下唯一"
  type        = string
  default     = null

  validation {
    condition     = var.scaling_group_name != null ? length(var.scaling_group_name) >= 2 && length(var.scaling_group_name) <= 64 : true
    error_message = "伸缩组名称长度必须在 2-64 个字符之间。"
  }
}

variable "min_size" {
  description = "伸缩组最小实例数"
  type        = number
  default     = 0

  validation {
    condition     = var.min_size >= 0 && var.min_size <= 1000
    error_message = "最小实例数必须在 0-1000 之间。"
  }
}

variable "tags" {
  description = "资源标签映射"
  type        = map(string)
  default     = {}
}

variable "api_" {
  description = "云平台 API 访问令牌"
  type        = string
  sensitive   = true
}

3.2.2 输出变量规范

• 最小化输出：只暴露调用方真正需要的属性，避免输出整个资源对象。
• 描述清晰：每个 output 必须包含 description，说明输出值的含义与用途。
• 敏感标记：输出中包含敏感信息时，设置 sensitive = true。
• 结构化输出：对于复杂信息，使用 object 类型组织输出。

# 输出变量规范示例
output "scaling_group_id" {
  description = "创建的弹性伸缩组 ID"
  value       = alicloud_ess_scaling_group.this.id
}

output "scaling_group_arn" {
  description = "弹性伸缩组的 ARN 标识"
  value       = alicloud_ess_scaling_group.this.arn
}

output "instance_ids" {
  description = "伸缩组内当前实例 ID 列表"
  value       = alicloud_ess_scaling_group.this.instance_ids
}

output "endpoints" {
  description = "模块暴露的 API 端点信息"
  value = {
    api_url      = "https://scaling.aliyuncs.com"
    webhook_url  = "https://webhook.scaling.aliyuncs.com/callback"
  }
  sensitive = true
}

3.3 版本管理：语义化版本与兼容性策略

Terraform 模块的版本管理遵循语义化版本规范（SemVer），格式为 MAJOR.MINOR.PATCH。版本号的变化必须反映模块接口的变更程度。

3.3.1 版本约束声明

在根配置或调用模块时，使用 version 参数约束模块版本范围，避免意外升级导致兼容性问题。

# 调用模块时声明版本约束
module "scaling_group" {
  source  = "git::https://gitlab.example.com/terraform-modules/scaling-group.git"
  version = "~> 2.0"  # 允许 2.0 到 3.0 之间的 MINOR 和 PATCH 升级

  scaling_group_name = "prod-web-sg"
  min_size           = 2
  max_size           = 10
}

3.3.2 版本发布流程

1. 开发阶段：在 main 分支上迭代，版本号后缀 -dev（如 1.2.0-dev）。
2. 预发布阶段：创建 release/x.y.z 分支，版本号后缀 -rc.1（如 1.2.0-rc.1）。
3. 正式发布：合并到 main 后打 Git Tag，如 v1.2.0。
4. 变更日志：每个版本必须维护 CHANGELOG.md，记录新增、变更、废弃、修复内容。

3.4 模块仓库结构：标准化目录与可发现性

统一的仓库结构能够降低团队成员的认知成本，提升模块的可发现性与可维护性。推荐采用以下标准目录布局：

terraform-modules/
├── scaling-group/                  # 模块名称（与功能对应）
│   ├── main.tf                     # 主资源定义
│   ├── variables.tf                # 输入变量声明
│   ├── outputs.tf                  # 输出变量声明
│   ├── locals.tf                   # 本地变量与计算逻辑
│   ├── data.tf                     # 数据源定义（可选）
│   ├── versions.tf                 # Terraform 与 Provider 版本约束
│   ├── README.md                   # 模块文档：用途、用法、示例、注意事项
│   ├── CHANGELOG.md                # 版本变更日志
│   ├── examples/                   # 使用示例目录
│   │   ├── basic/                  # 基础用法
│   │   │   ├── main.tf
│   │   │   ├── terraform.tfvars
│   │   │   └── outputs.tf
│   │   └── advanced/               # 高级用法（如多可用区、自定义告警）
│   │       ├── main.tf
│   │       └── terraform.tfvars
│   ├── tests/                      # 测试目录
│   │   ├── unit/                   # 单元测试（使用 terratest 或 tftest）
│   │   └── integration/            # 集成测试
│   └── .gitignore
├── scaling-policy/                 # 另一个模块
│   ├── main.tf
│   ├── variables.tf
│   └── ...
└── README.md                       # 仓库根目录说明，列出所有模块及其用途

3.4.1 关键文件职责

3.4.2 模块命名与组织规范

• 模块名称：使用小写字母与连字符（kebab-case），如 scaling-group、alarm-policy。
• 仓库组织：建议使用单一仓库（Monorepo）管理所有模块，便于统一版本管理与 CI/CD。
• 模块索引：在仓库根目录的 README.md 中维护模块列表，标注每个模块的版本、维护状态、负责人。
• 标签分类：使用 Git 标签前缀区分模块，如 scaling-group/v1.2.0、scaling-policy/v0.5.0。

3.5 模块设计检查清单

在提交模块代码前，对照以下清单进行自检，确保模块质量达标：

• ☐ 单一职责：模块只完成一个明确的运营操作，不混入无关逻辑。
• ☐ 输入完整：所有必要输入变量均已声明，包含类型、描述、验证规则。
• ☐ 输出最小：只暴露调用方需要的输出字段，避免输出整个资源对象。
• ☐ 版本约束：versions.tf 中声明了 Terraform 与 Provider 的最低版本。
• ☐ 文档齐全：README.md 包含用途说明、输入输出表格、快速开始示例。
• ☐ 示例可运行：examples/ 目录下的示例配置经过实际测试，可独立执行。
• ☐ 变更日志：CHANGELOG.md 记录了当前版本与历史版本的变更内容。
• ☐ 无硬编码：所有环境相关参数通过变量传入，模块内部无硬编码值。
• ☐ 敏感信息保护：涉及密钥、 的变量和输出已标记 sensitive = true。