3. 参数设计原则：参数化的必要性、单一职责原则、避免硬编码、参数命名规范

在基础设施即代码（IaC）实践中，参数是连接通用模板与具体环境的“粘合剂”。糟糕的参数设计会导致配置爆炸、环境间的不一致以及难以调试的故障。本章将深入剖析参数设计的四大核心原则，帮助你在编写IaC代码时建立正确的抽象层次。

3.1 参数化的必要性：从“写死”到“声明”

参数化的本质是将变化点从代码逻辑中剥离出来，使其成为可被外部注入的变量。没有参数化的IaC代码，本质上只是“可重复执行的脚本”，而非“可复用的配置”。

参数化的必要性体现在以下三个维度：

• 环境隔离： 通过参数注入不同的环境标识（如 environment = "dev" vs "prod"），自动切换VPC CIDR、实例规格、数据库密码等差异配置。
• 安全合规： 敏感信息（数据库密码、）必须通过参数或变量引用，避免将明文凭证提交到版本控制系统中。
• 团队协作： 平台工程师定义参数接口，应用工程师只需填写参数文件（如 terraform.tfvars 或 values.yaml），实现职责分离。

3.2 单一职责原则：一个参数只做一件事

单一职责原则（SRP）在参数设计中的映射是：每个参数应只控制一个维度的配置变化。违反该原则的参数通常表现为“万能参数”或“布尔陷阱”。

遵循单一职责的参数设计应满足以下检查表：

正确的做法是将组合逻辑交给调用方，而非在参数内部做隐式关联：

# 反模式：一个参数控制多个维度
variable "server_profile" {
  type    = string
  default = "web-small"
  # 取值 "web-small" 隐含了：t2.micro + 20GB + 无监控
}

# 正模式：每个维度独立参数
variable "instance_type" {
  type    = string
  default = "t2.micro"
}
variable "disk_size_gb" {
  type    = number
  default = 20
}
variable "enable_detailed_monitoring" {
  type    = bool
  default = false
}

3.3 避免硬编码：将“魔法值”提升为参数

硬编码（Hardcoding）是IaC代码腐化的首要原因。任何直接写在代码中的字面量，如果未来可能因环境或需求变化而需要修改，都应该被提升为参数。常见的硬编码类型包括：

• 基础设施标识符： VPC ID、子网 ID、AMI ID、安全组 ID。
• 容量与配额： 实例规格、磁盘大小、副本数、超时时间。
• 网络地址： CIDR 块、IP 地址、端口号、域名。
• 认证凭证： 数据库密码、API 、SSH 密钥名称。

以下是一个从硬编码到参数化的重构示例：

# 硬编码版本（不可复用）
resource "aws_db_instance" "main" {
  engine         = "postgres"
  engine_version = "15.3"
  instance_class = "db.t3.medium"
  allocated_storage = 100
  db_name        = "app_production"
  username       = "admin"
  password       = "P@ssw0rd2024!"  # 严重安全风险
  skip_final_snapshot = false
}

# 参数化版本（可复用）
variable "db_config" {
  type = object({
    engine         = string
    engine_version = string
    instance_class = string
    storage_gb     = number
    db_name        = string
    admin_user     = string
  })
  description = "数据库实例配置参数"
}

resource "aws_db_instance" "main" {
  engine         = var.db_config.engine
  engine_version = var.db_config.engine_version
  instance_class = var.db_config.instance_class
  allocated_storage = var.db_config.storage_gb
  db_name        = var.db_config.db_name
  username       = var.db_config.admin_user
  password       = data.aws_secretsmanager_secret_version.db_password.secret_string
  skip_final_snapshot = var.environment != "prod"  # 非生产环境跳过最终快照
}

3.4 参数命名规范：可读性即可维护性

参数命名是IaC代码的“公共API”。一个命名良好的参数文件，即使没有注释，也能让运维人员快速理解其用途。以下是经过大量生产环境验证的命名规范：

一个符合规范的参数声明示例：

# 命名规范：snake_case + 前缀分组 + 单位标注
variable "network_vpc_cidr_block" {
  type        = string
  description = "VPC的IPv4 CIDR块，例如 10.0.0.0/16"
  default     = "10.0.0.0/16"
}

variable "compute_instance_type" {
  type        = string
  description = "EC2实例规格，参考 AWS 实例类型命名"
  default     = "t3.medium"
}

variable "storage_disk_size_gb" {
  type        = number
  description = "根卷大小，单位 GB"
  default     = 50
  validation {
    condition     = var.storage_disk_size_gb >= 20 && var.storage_disk_size_gb <= 1000
    error_message = "磁盘大小必须在 20GB 到 1000GB 之间。"
  }
}

variable "security_enable_encryption" {
  type        = bool
  description = "是否启用存储加密"
  default     = true
}

3.5 综合实践：参数设计质量检查表

在每次提交IaC代码前，使用以下检查表对参数设计进行评审：

1. 必要性检查： 每个参数是否都有至少两个不同的预期取值场景？如果所有环境都使用同一个值，考虑移除该参数，使用默认值。
2. 职责检查： 修改一个参数的值，是否只影响一个维度的行为？如果影响多个维度，拆分为多个参数。
3. 硬编码检查： 代码中是否还存在任何环境相关的字面量？使用 grep -rnE '"(subnet-|ami-|sg-|i-)[a-z0-9]+"' 扫描。
4. 命名检查： 参数名是否遵循团队规范？是否包含单位？布尔参数是否以 enable_ 或 is_ 开头？
5. 安全检查： 敏感参数是否标记为 sensitive = true？是否使用了外部密钥管理服务（如 AWS Secrets Manager）而非直接赋值？