📚 课程目录第3章模板化设计原则

3. 模板化设计原则

模板化设计是自助门户环境快速创建方法的核心工程实践。一套健壮的模板体系必须遵循五项基本原则，才能从“一次性脚本”进化为“可复用、可维护、可治理”的工程资产。以下逐一展开。

3.1 五项原则概览

原则	核心含义	反例	工程收益
单一职责	一个模板只负责一个环境维度（网络/计算/存储/中间件）	一个模板同时创建 VPC、ECS、RDS 和 DNS	降低耦合，便于独立升级与排错
可组合性	模板之间通过输出/输入接口串联，像积木一样拼装	硬编码依赖其他模板的资源 ID	支持多环境差异化组装
参数化	所有环境差异点暴露为参数，模板内无硬编码	在模板里写死 region、实例规格、密码	一份模板适配开发/测试/生产
版本控制	模板与代码同源，使用 Git 标签管理发布版本	模板散落在共享目录，靠文件名区分版本	可追溯、可回滚、可审计
可测试性	模板支持 dry-run、语法校验、单元测试与集成验证	直接在生产环境执行未验证的模板	提前发现错误，保障交付质量

  工程经验： 五项原则的优先级排序为 参数化 > 单一职责 > 可组合性 > 版本控制 > 可测试性。参数化是基础，没有参数化，其他原则无从谈起。

3.2 单一职责：模板的原子化拆分

每个模板只封装一个基础设施维度。例如：

vpc-template.yaml — 仅定义 VPC、子网、路由表、网关。
ecs-template.yaml — 仅定义 ECS 实例、安全组、弹性 IP。
rds-template.yaml — 仅定义数据库实例、参数组、备份策略。

拆分后，团队可以独立维护每个维度的版本，避免“改一个参数影响整个环境”。

# 反例：一个模板包含所有资源
Resources:
  MyVPC:
    Type: AWS::EC2::VPC
  MyECS:
    Type: AWS::EC2::Instance
  MyRDS:
    Type: AWS::RDS::DBInstance

# 正例：每个模板只负责一个维度
# vpc-template.yaml
Resources:
  MyVPC:
    Type: AWS::EC2::VPC

3.3 可组合性：模板间的契约式组装

可组合性依赖模板的输出（Outputs）与输入（Parameters）建立契约。上层编排模板通过引用下层模板的输出值，实现资源间依赖传递。

# vpc-template.yaml 输出
Outputs:
  VpcId:
    Value: !Ref MyVPC
    Export:
      Name: !Sub "${AWS::StackName}-VpcId"

# ecs-template.yaml 输入
Parameters:
  VpcId:
    Type: String
    Description: VPC ID from VPC stack

推荐模式： 使用 嵌套栈（Nested Stacks） 或 模块（Modules） 实现组合。Terraform Module、CloudFormation Nested Stack、Pulumi Component 都是成熟方案。

3.4 参数化：消除硬编码

参数化是模板化的第一道门槛。所有环境差异点必须暴露为参数，包括但不限于：

参数类别	典型参数	默认值策略
基础设施	region, vpcCidr, subnetCidrs	开发环境默认值
计算资源	instanceType, amiId, diskSize	最小规格
网络配置	allowedIps, dnsServers, enableNat	安全默认值
应用配置	appVersion, dbPassword, logLevel	从密钥服务读取

# 参数化示例（Terraform）
variable "instance_type" {
  description = "ECS instance type"
  type        = string
  default     = "t3.medium"
}

variable "vpc_cidr" {
  description = "VPC CIDR block"
  type        = string
  default     = "10.0.0.0/16"
}

3.5 版本控制：模板即代码

模板必须与源代码一起纳入 Git 仓库，并使用语义化版本标签管理发布。推荐结构：

infra-templates/
├── modules/
│   ├── vpc/
│   │   ├── v1.0.0/
│   │   ├── v1.1.0/
│   │   └── v2.0.0/
│   ├── ecs/
│   └── rds/
├── environments/
│   ├── dev/
│   ├── test/
│   └── prod/
└── releases/
    ├── release-2024-01-v1.0.0.md
    └── release-2024-02-v1.1.0.md

常见陷阱： 不要只保存最新版模板。生产环境可能运行 v1.0.0，而开发环境已升级到 v2.0.0。必须通过 Git 标签锁定每个环境使用的模板版本。

3.6 可测试性：模板的验证流水线

模板必须经过四级验证才能进入生产：

语法校验 — 使用工具检查 YAML/JSON 格式与 Schema 合规性。
Dry-Run 执行 — 在沙箱环境执行预览，验证参数组合与资源依赖。
单元测试 — 使用 TaskCat、Terratest 等框架验证模板逻辑。
集成测试 — 在隔离环境创建真实资源，验证端到端功能。

# 语法校验示例（AWS CloudFormation）
aws cloudformation validate-template \
  --template-body file://vpc-template.yaml

# Dry-Run 示例（Terraform）
terraform plan -var-file=dev.tfvars -out=plan.out

3.7 模板化设计原则关系图

3.8 原则落地检查清单

团队在引入模板化设计时，可使用以下清单进行自检：

检查项	通过标准	验证方式
单一职责	每个模板只包含一个资源类型或一个维度	代码审查
可组合性	模板间通过 Outputs/Inputs 传递依赖，无硬编码引用	自动化测试
参数化	所有环境差异点均定义为参数，无硬编码值	静态扫描
版本控制	模板使用 Git 标签管理，每个环境锁定版本	Git 日志审计
可测试性	CI 流水线包含语法校验、dry-run、单元测试	流水线状态检查

推荐工具： Terraform 的 terraform validate + terraform plan + Terratest 组合；CloudFormation 的 cfn-lint + aws cloudformation validate-template + TaskCat。