Terratest v2 Import Map 解读：模块化拆分、导入路径迁移与 v1→v2 升级对照表

测试开发工具DevOps质量保障【免费下载链接】terratestTerratest is a Go library that makes it easier to write automated tests for your infrastructure code.项目地址https://gitcode.com/gh_mirrors/te/terratest点击查看免费下载Terratest 在 v2 中按领域将代码拆分成了 16 个独立 Go 子模块并统一采用.../modules/name/v2的语义化导入版本SIV路径。本文以仓库中的 v2 Import Map 文档 为主体完整给出 v1→v2 的导入路径对照表、core 模块折叠规则、已删除包的去向、beta 期间移动的符号以及行为变更帮助基础设施代码测试的维护者一次性完成迁移与 codemod 改写。v2 模块化的总体规则Terratest v2 把原本modules/下的包重新组织为若干独立发布、独立打 tag 的 Go module。其核心变换规则只有三条且对所有存活的导入路径及其子包都成立前缀替换modules/name/...→modules/name/v2/...。/v2这个语义化导入版本SIV紧跟在模块根之后目录布局保持不变三个改名包除外。例如modules/aws/foo→modules/aws/v2/foomodules/logger/parser→modules/core/v2/logger/parser。六个 tier-0 工具类包合并modules/util/...→modules/core/v2/util/...全部收敛到统一的core/v2模块之下。三个带连字符的包在/v2边界处改名http-helper→httphelper、dns-helper→dnshelper、test-structure→teststructure。包标识符的下划线也一并去掉http_helper→httphelper因此调用点代码本身也要改不只是导入路径。Import Map 是从 v1 的实际布局tagv1.0.1-test共 27 个modules/包、2 个cmd/二进制、1 棵internal/lib树构建的模块基础路径为github.com/gruntwork-io/terratest。当前仓库中每个子模块的go.mod已确认采用github.com/gruntwork-io/terratest/modules/name/v2的模块声明例如 modules/aws/go.mod 与 modules/core/go.mod。SIV 位置是硬性约束/v2必须放在模块根之后、包叶子之前。仓库中的 CI 脚本 scripts/check-siv-placement.sh 专门用于拦截把/v2写到包叶子的写法它注释里明确记录了正确写法github.com/gruntwork-io/terratest/modules/logger/v2/parser与错误写法github.com/gruntwork-io/terratest/modules/logger/parser/v2的区别——后者正是曾导致 PR #1632 卡住的 bug。core 折叠6 个 v1 包 → 一个modules/core/v2v1 中六个被归为 tier-0 的通用工具包全部折叠进单一core/v2模块模块内的子目录名保持原包名v1 导入路径v2 导入路径modules/loggermodules/core/v2/loggermodules/testingmodules/core/v2/testingmodules/retrymodules/core/v2/retrymodules/randommodules/core/v2/randommodules/filesmodules/core/v2/filesmodules/shellmodules/core/v2/shell从源码看这一折叠在 import 语句中已经落地。例如 modules/k8s/node.go 顶部即通过github.com/gruntwork-io/terratest/modules/core/v2/retry与github.com/gruntwork-io/terratest/modules/core/v2/testing引用这两个工具包说明core/v2同时承担retry与testing的职责也印证了 core 模块是其他所有平台模块的基础依赖。独立/v2子模块对照表除 core 折叠外其余存活的领域包各自成为独立子模块。完整对照如下v1 导入路径v2 导入路径modules/awsmodules/aws/v2modules/azuremodules/azure/v2modules/gcpmodules/gcp/v2modules/k8smodules/k8s/v2modules/helmmodules/helm/v2modules/sshmodules/ssh/v2modules/dockermodules/docker/v2modules/packermodules/packer/v2modules/databasemodules/database/v2modules/opamodules/opa/v2modules/terraformmodules/terraform/v2modules/terragruntmodules/terragrunt/v2modules/http-helpermodules/httphelper/v2modules/dns-helpermodules/dnshelper/v2modules/test-structuremodules/teststructure/v2其中httphelper在仓库中实际落地为 modules/httphelper 目录含 httphelper.go 等文件dnshelper对应 modules/dnshelperteststructure对应 modules/teststructurego.mod中声明的模块路径均为.../v2结尾。子模块总数核算27 6 个折叠进 core 15 个独立子模块 6 个被移除最终发布子模块共16 个core 15。v2.0.0 移除的包及其替代方案以下包在 v1 中已被标记废弃于 v2 切版时正式删除Import Map 给出了明确的替代方向v1 导入路径替代方案modules/collections标准库slicesmodules/environment标准库os.Getenvmodules/git标准库os/execmodules/slack无需要时从冻结的 v1 自行 vendormodules/version-checker无直接 shell 调用modules/oci无Oracle Cloud 支持不再延续保留在冻结 v1 中需要时 vendorcmd/pick-instance-type无独立二进制超出范围cmd/terratest_log_parser无独立二进制其logger/parser库以modules/core/v2/logger/parser存活内部扁平化不对外可见v1 的internal/lib/formatting在 v2 中扁平化为internal/formatting。由于internal/目录本身不可被外部导入这一步对消费者无影响仅属仓库内部结构调整。beta 期间移动的符号在 v2 beta 过程中四个原本属于teststructure的保存/加载函数被移动到拥有对应类型的模块以消除teststructure对aws、k8s、packer、ssh的依赖对应 issue #1877。函数签名与磁盘文件名均未改变所有调用点都会以编译错误的形式暴露出来beta.1 位置beta.2 及以后位置teststructure.{Save,Load}Ec2KeyPairaws.{Save,Load}Ec2KeyPairteststructure.{Save,Load}KubectlOptionsk8s.{Save,Load}KubectlOptionsteststructure.{Save,Load}PackerOptionspacker.{Save,Load}PackerOptionsteststructure.{Save,Load}SSHKeyPairssh.{Save,Load}SSHKeyPair从当前仓库源码可以确认这一迁移已经完成SaveEc2KeyPair/LoadEc2KeyPair定义在 modules/aws/save_test_data.goSaveKubectlOptions/LoadKubectlOptions定义在 modules/k8s/save_test_data.goSavePackerOptions/LoadPackerOptions定义在 modules/packer/save_test_data.goSaveSSHKeyPair/LoadSSHKeyPair定义在 modules/ssh/save_test_data.go。四个函数签名保持一致testing.TestingT、testFolder string返回对应类型指针并各自配有 save/load 往返测试如 modules/k8s/save_test_data_test.go 与 modules/ssh/save_test_data_test.go。迁移提示留意那些为 Terratest 的aws起别名的文件——因为裸aws现在是 AWS SDK 的包名别名处理不当会直接撞名。v2 beta 期间的行为变更节点地址优先使用ExternalIP#1878k8s.FindNodeHostnameContextE与GetServiceEndpointNodePort现在在节点存在ExternalIP时直接返回该地址否则才回退到原来的内部 hostname。在 EKS 上这通常是公网 IP因此不再需要发起 EC2 调用、也不再需要ec2:DescribeInstances权限。签名保持不变新增的FindNodeHostnameWithOptionsContext[E]通过NodePublicIPLookup兜底那些没有ExternalIP的集群。源码细节与此一致modules/k8s/kubectl_options.go 定义了NodePublicIPLookup类型func(testing.TestingT, context.Context, []string, string) (map[string]string, error)并注释其仅在节点对象无ExternalIP时才被咨询典型用法可设置为aws.GetPublicIpsOfEc2InstancesContextEmodules/k8s/node_hostname_test.go 中的TestFindNodeHostnamePrefersExternalIPFromNode明确断言节点的ExternalIP必须优先且无需任何 options另有若干用例覆盖无 ExternalIP 时通过NodePublicIPLookup解析的场景。携带RestConfig的KubectlOptions不再可序列化#1879KubectlOptions.MarshalJSON现在遇到非空的RestConfig直接返回k8s.ErrRestConfigNotSerializable而不是静默丢弃该配置。此前该场景会以晦涩的json: unsupported type: transport.WrapperFunc失败。正确做法是用NewKubectlOptions或NewKubectlOptionsWithInClusterAuth构造选项。实现层面modules/k8s/kubectl_options.go 的MarshalJSON通过类型别名避免递归后交给标准json.Marshal并在RestConfig ! nil时返回错误错误定义于 modules/k8s/errors.goErrRestConfigNotSerializable errors.New(kubectl options carrying a RestConfig cannot be serialized)。对应测试 modules/k8s/kubectl_options_test.go 与 modules/k8s/save_test_data_test.go 均覆盖了携带 RestConfig 时保存失败且不写出任何内容的行为。迁移中的常见陷阱包标识符与导入路径要一起改三个改名包的调用点写法如http_helper也要改成新标识符codemod 需要同时覆盖路径与标识符两处/v2位置不能错SIV 必须紧跟模块根modules/logger/parser/v2是错误写法裸aws撞名Terratest 迁移后的aws子包与 AWS SDK 同名需要别名或按模块引用方式处理RestConfig不可序列化不要再依赖旧的静默丢弃行为改用两个NewKubectlOptions*构造函数被删包要换标准库collections、environment、git分别用slices、os.Getenv、os/exec替代其余无替代项按需从冻结的 v1 vendor。总结Import Map 对 v2 的导入路径迁移做了冻结式定稿16 个发布子模块、统一modules/name/v2路径前缀、core 六合一折叠、三个连字符包改名以及oci、slack、version-checker、两个cmd/二进制的移除。beta 期间移动的符号与行为变更也一并固化issue #1877、#1878、#1879。配合 scripts/check-siv-placement.sh 的 SIV 位置检查与 v2 Release Runbook 的发布流程整个 v1→v2 升级路径在导入层已被完全锁定剩余工作就是按上表执行一次彻底的 codemod 改写。赞分享测试开发工具DevOps质量保障【免费下载链接】terratestTerratest is a Go library that makes it easier to write automated tests for your infrastructure code.项目地址https://gitcode.com/gh_mirrors/te/terratest点击查看免费下载相关推荐Terratest v2 导入路径迁移完全指南import map 全量映射表与源码级解读Terratest v2 导入路径迁移完全指南import map 全量映射表与源码级解读 Terratest v2 将原本单一的 github.com/gr测试开发工具DevOps质量保障Terratest v2 迁移指南从单模块到 16 个独立模块的完整升级路径Terratest v2 迁移指南从单模块到 16 个独立模块的完整升级路径 Terratest v2 将原本单一的 github.com/gruntwork测试开发工具DevOps质量保障从 v1 平滑升级 Atomic Agents v2.0破坏性变更迁移指南与导入路径对照表从 v1 平滑升级 Atomic Agents v2.0破坏性变更迁移指南与导入路径对照表 Atomic Agents 是一个轻量级、模块化的 PythonAI AgentAgent 框架MCP 服务后端上一篇VSCode Rainbow Fart 项目常见问题解决方案下一篇BilibiliHistoryFetcher重塑你的B站观看数据叙事创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考