别把 Terraform 模块写成黑盒：IaC 分层设计决策与 6 个生产级反模式拆解
概述 去年给一家做电商的客户搭 IaC 体系，接手时他们的 Terraform 代码库大概长这样：三个环境（dev/staging/prod）各自一套配置，加起来 3000 多行，90% 是复制粘贴。改一个 VPC CIDR 要同步改三个文件，漏改一个就是环境漂移。最离谱的是有个安全组规则在 prod 里少了一条，三个月没人发现。 这种痛每个用过 Terraform 的团队都经历过。模块化是公认的解法——但很多人做完模块化后发现：代码确实短了，可维护性反而更差了。一个模块塞了 40 个变量、3 层嵌套，改一个参数要翻三个文件才能理解影响面。这就是"把模块写成黑盒"的典型症状。 这篇文章拆解我在多个企业客户项目中验证过的一套 Terraform 模块分层架构，以及 6 个在生产环境中真实踩过的反模式。不是泛泛的"最佳实践"罗列，而是每个决策点都附上"为什么这么做"和"什么场景下不推荐这么做"。 为什么需要模块化 先说清楚模块化解决什么问题。不是"代码复用"这么笼统的话，而是三个具体痛点： 痛点一：环境漂移。 三个环境的配置本应一致，但人工复制必然出错。在某出行项目中，我们统计过：复制粘贴的配置平均每个环境有 3-5 处细微差异（CIDR 偏移、可用区数量不一致、安全组规则遗漏），这些差异在平时不爆发，一出故障就是定位地狱。 痛点二：变更同步成本。 改一个 AMI ID 要在 3 套环境里各改一次。如果团队有 5 个人同时改不同模块，合并冲突频繁到让人怀疑人生。 痛点三：知识传递断裂。 新人来了看一个 800 行的 main.tf，完全不知道哪些资源是有关联的、改哪个会影响哪个。没有模块边界，就没有认知锚点。 模块化的本质不是"把代码拆短"，而是建立明确的抽象边界——让每个模块成为一个可以独立理解、独立测试、独立变更的单元。 模块分层架构设计 三层模型 我推荐的三层架构如下： 层级 职责 示例 变量数量 资源数量 基础模块 封装单一云资源 modules/vpc、modules/rds 5-15 3-8 组合模块 组合多个基础模块 modules/eks-platform 15-30 调用 3-5 个基础模块 环境层 定义环境差异化配置 envs/prod/ 不限 调用 2-4 个组合模块 这三层不是什么新概念，但很多人在实际落地时会把层级搞混——最常见的是基础模块里塞了组合逻辑，或者环境层直接调用基础模块跳过了组合层。下面逐层拆解。...