Terraform AWS Provider 中的服务命名元数据中心深入解析 names 包与 names_data.hcl【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws本篇指南围绕 terraform-provider-aws 仓库中的names包展开完整覆盖 names/README.md 的核心内容names包如何为整个 Provider 提供 AWS 服务命名信息、names_data.hcl的完整块/属性模式与每个字段的用途、编辑后的再生成流程make gen并结合仓库源码说明数据如何被嵌入、解析与消费帮助你在新增或修改服务时正确维护这份“单一事实来源”。为什么 names 包是 Provider 正确运行的基石names包提供 Terraform AWS Provider 正确运行所必需的关键 AWS 服务命名信息。它对外的承诺非常直接如果你不确定自己正在做的改动是否正确请提问后再动手。需要特别注意的是names/data/names_data.hcl中的信息会影响 Provider、代码生成器、文档、网站导航等的正确工作。官方文档明确警告在理解下文的属性说明表之前不要对该文件做任何改动。names包的核心是 names/data/names_data.hcl它包含关于 AWS Provider、AWS Go SDK v1/v2 以及 AWS CLI 中命名信息的 HCL 数据。该文件在构建时被动态嵌入到 AWS Provider 中通过//go:embed并在代码生成时被生成器引用。其中包含的信息必须是精确的任何改动都应当双重检查。从源码看这一“构建时嵌入”体现在 names/data/read.go 末尾的//go:embed names_data.hcl指令上而 names/names.go 中的init()函数在包初始化阶段就通过data.ReadAllServiceData()解析该文件一旦解析失败会直接log.Fatalf终止进程——这也从侧面印证了数据正确性对 Provider 启动的关键意义。names 包的消费者names包的主要消费者包括provider包internal/providerProvider 主逻辑conns包internal/connsAWS 客户端连接与端点配置AWS Provider 各代码生成器internal/generate下skaff脚手架工具skaff/这一点与 names/names.go 的包注释描述一致注释中同时强调names_data.hcl中的信息必须完全正确因为 Terraform AWS Provider 依赖这些信息才能正确工作。编辑 names_data.hcl 之后运行 make gen每次对names/data/names_data.hcl进行编辑之后都应运行make gen。该命令会重新生成代码并对names_data.hcl执行一系列一致性检查。在 GNUmakefile 中可以看到对应目标约第 402 行gen: prereq-go ## Run Go generators (all provider-wide, or scoped to a service with PKG/Kservice)即生成器既可以整体运行也可以通过PKG/Kservice限定到某个服务。此外还有gen-raw运行全部 Go 生成器和gen-checkCI 中校验生成结果是否漂移。names包自身的生成入口是 names/generate.go其中只保留了//go:generate go run ../internal/generate/namesconsts/main.go指令与包声明——该生成器正是产出下文提到的consts_gen.go常量文件的程序。names_data.hcl 的完整模式Schemanames_data.hcl的属性与块的模式定义如下摘自 README即该文件必须遵循的结构service { // If both of these attributes are the same as the service blocks name, this block will be omitted cli_v2_command { aws_cli_v2_command aws_cli_v2_command_no_dashes } // If both of these attributes are the same as the service blocks name, this block will be omitted go_packages { v1_package v2_package } // If any blocks below here have attirbutes with empty strings or false bools, they will be omitted // Blocks with zero attributes will be omitted sdk { id client_version 2 } names { aliases [] // This can also be excluded if it is empty provider_name_upper human_friendly } client { go_v1_client_typename skip_client_generate bool } env_var { deprecated_env_var tf_aws_env_var } endpoint_info { endpoint_api_call endpoint_api_params endpoint_region_override endpoint_only bool } resource_prefix { actual correct } provider_package_correct split_package file_prefix doc_prefix [] brand exclude bool not_implemented bool allowed_subcategory bool note is_global bool }几个模式层面的要点均可在 names/data/read.go 的 Go 结构体定义中得到印证service块以 label 形式承载包名ProviderPackage string \hcl:,label其余块均为可选。names块中的provider_name_upper与human_friendly使用attr必填标记其余为optional——也就是说每个service块必须声明这两个字段。解析时sdk.client_version缺省为0ReadAllServiceData()会将其回填为默认值2见 names/data/read.go。sub_service块用于表达“多个服务共存于一个服务”的场景例如 VPC 属于 EC2ReadAllServiceData()会将其展平为独立的ServiceRecord见 names/data/read.go。实际数据示例结合仓库中真实的names_data.hcl片段可以直观看到各字段的用法。以下示例取自 names/data/names_data.hclservice accessanalyzer { sdk { id AccessAnalyzer arn_namespace access-analyzer } names { provider_name_upper AccessAnalyzer human_friendly IAM Access Analyzer } endpoint_info { endpoint_api_call ListAnalyzers } resource_prefix { correct aws_accessanalyzer_ } provider_package_correct accessanalyzer doc_prefix [accessanalyzer_] brand AWS }再对比一个启用cli_v2_command覆盖与全局标记的示例service accountaccess { cli_v2_command { aws_cli_v2_command account-access aws_cli_v2_command_no_dashes accountaccess } sdk { id Account Access arn_namespace account-access } names { provider_name_upper AccountAccess human_friendly Account Access } # ... }service acm { names { provider_name_upper ACM human_friendly ACM (Certificate Manager) human_friendly_short ACM } # ... }以及带is_global true的全局服务示例service account { # ... is_global true }这些片段恰好演示了模式说明中的省略规则cli_v2_command与go_packages块仅在与服务块名不同时才出现空字符串/假布尔值的属性会被省略。属性详解每个字段如何被代码使用以下是 README 中完整的属性说明表每个字段标注了用途类别Code 表示参与代码生成/运行逻辑Reference 表示主要供参考核对NameUseDescriptionProviderPackageActualCodeprovider_package_correct未使用时TF AWS Provider 包的实际名称若两者同时定义服务块名以provider_package_correct优先aws_cli_v2_commandReferenceAWS CLI v2 中该服务的命令名aws_cli_v2_command_no_dashesReference与aws_cli_v2_command相同但去掉连字符v1_packageCodeAWS SDK for Go v1 的包名v2_packageCodeAWS SDK for Go v2 的包名idCode代表 AWS 服务的 ServiceID某一具体服务的唯一标识符client_versionCode表示该服务使用哪个版本的 AWS SDK默认2aliasesCode名称变体的 HCL 字符串列表例如 AMP 对应prometheus,prometheusservice。不要包含 ProviderPackageActual若provider_package_correct为空则指它否则会在使用自定义端点时产生重复provider_name_upperCodeProviderPackageActual若存在否则provider_package_correct的规范大写形式human_friendlyCode必填。AWS 侧使用的服务友好名称文档subcategory必须与该值完全一致用于网站导航与错误信息human_friendly_shortCodeAWS 侧服务友好名称但去掉括号注释例如 S3 为S3而不是S3 (Simple Storage)go_v1_client_typenameCodeAWS SDK for Go v1 客户端类型的精确名称拼写与大小写均须一致仅支持 SDK v2 的服务可省略skip_client_generateCode部分服务客户端需要特殊配置而非默认生成的配置使用非空值跳过生成之后必须在internal/conns/config.go中手动配置该客户端deprecated_env_varCode某些服务定义的已弃用AWS_service_ENDPOINT环境变量tf_aws_env_varCode某些服务定义的TF_AWS_service_ENDPOINT环境变量endpoint_api_callCode用于描述当前服务的 AWS CLI 命令/API 调用endpoint_api_paramsCode用于service_endpoints_gen_test.go文件中需要配置值的 API 调用参数endpoint_region_overrideCode为 API 请求指定替代的区域端点endpoint_onlyCode基于not_implemented是否非空决定服务端点是否应包含在 Provider 的endpoints配置中resource_prefix_actualCode用于匹配异常 TF 资源名前缀的正则表达式例如aws_config_config_rule中aws_config_会匹配该服务所有资源仅在resource_prefix_correct不适用时使用例如aws_codepipeline_不行因为只有一个名为aws_codepipeline的资源优先于resource_prefix_correctresource_prefix_correctCode用于匹配资源名前缀应当是什么的正则表达式即aws_provider_package_correct_在resource_prefix_actual为空时使用provider_package_correctCodeaws_cli_v2_command_no_dashes与v2_package中较短者若两者存在则不应为空即“服务标识符”也是 TF AWS Provider 包名应当是什么ProviderPackageActual优先split_package_real_packageCode若多个“服务”位于一个服务内这是该服务 Go 文件所在的包例如 VPC 是 EC2 的一部分file_prefixCode若多个“服务”位于一个服务内文件必须带有的前缀以关联到该子服务例如 EC2 服务中 VPC 文件以vpc_为前缀doc_prefixCodewebsite/docs/r与website/docs/d中服务文档文件前缀的 HCL 字符串列表通常只有一个前缀即provider_package_correct_brandCodeAWS 使用的Amazon、AWS或空罕见用于错误信息excludeCode该服务是否应被包含的布尔值若包含留空则ProviderPackageActual或provider_package_correct必须有值allowed_subcategoryCode若Exclude非空是否仍将human_friendly放入website/allowed-subcategories.txt即某些情况下覆盖exclude。部分被排除的伪服务例如 EC2 中的 VPC仍然是子分类。仅在Exclude非空时生效not_implementedCode该服务是否已被 Provider 实现的布尔值noteReference非常简短的备注通常用于解释为何被排除is_globalCode表示该服务是否为全局服务的布尔值参见 Enhanced Region Support 指南中关于全局服务的说明源码中的优先级规则这些“省略/优先”逻辑如何落地上面表格中的优先级与默认值规则在 names/data/read.go 中有精确实现值得逐一对照理解CLI 命令回退AWSCLIV2Command()/AWSCLIV2CommandNoDashes()在cli_v2_command块缺失时回退到service块的 label即 ProviderPackage见 names/data/read.go。Go 包名回退GoV1Package()/GoV2Package()在go_packages块缺失时同样回退到包名GoPackageName()则根据SDKVersion()选择返回 v1 或 v2 包名names/data/read.go。包名纠正ProviderPackageCorrect()在provider_package_correct非空时优先于块名names/data/read.go。资源前缀优先级ResourcePrefix()明确实现“resource_prefix_actual非空则覆盖resource_prefix_correct”names/data/read.go。友好名称短名回退HumanFriendlyShort()在短名未设置时回退到human_friendlynames/data/read.goFullHumanFriendly()会拼接brand如AWS IAM Access Analyzer。FIPS 支持推断EndpointFIPSSupport()基于endpoint_no_fips_support取反默认支持names/data/read.go。端点环境变量推导AWSServiceEnvVar()直接由SDKID()推导AWS_ENDPOINT_URL_IDAWSConfigParameter()由 SDK ID 转小写下划线形式names/data/read.go——也就是说sdk.id字段间接决定了 SDK v2 的标准端点覆盖变量名。数据如何被消费从 HCL 到 Provider 运行时1. 嵌入与解析names_data.hcl在编译期通过//go:embed嵌入data包见 names/data/read.go。ReadAllServiceData()使用hclparse解析 HCL再用gohcl.DecodeBody解码进Services结构体随后为每条记录含展平的sub_service生成ServiceRecord包装类型。该包装类型聚合了约三十个访问器方法是生成器与运行时代码读取服务元数据的统一入口。2. 运行时服务数据表serviceDatanames/names.go 中的init()构建了一个以 Provider 包名为键的内存表serviceData并执行两条过滤规则Exclude()为真的服务直接跳过NotImplemented()为真且非EndpointOnly()的服务也跳过即尚未实现的服务若仅保留端点定义仍可出现在端点相关逻辑中。在此之上names包对外暴露一组查询函数均位于 names/names.go函数作用ProviderPackageForAlias(alias)通过别名反查 Provider 包名未命中返回错误ProviderPackages()返回全部已加载服务的包名Aliases()返回所有服务的别名集合含包名本身ProviderNameUpper(service)返回规范大写名可用于生成类型名FullHumanFriendly(service)返回brand human_friendly形式的完整名称HumanFriendly(service)返回友好名称支持按别名递归查找conns包正是依赖这套别名→包名映射来解析用户在各服务endpoints配置中书写的服务名而provider包则利用FullHumanFriendly/ProviderNameUpper生成面向用户的错误信息与资源命名。此外 names/data/lookup.go 提供了LookupService(name)供生成器等工具按包名精确获取某条ServiceRecord。3. 端点 ID 常量SDK v1 与 v2 的差异names/names.go 还定义了一组形如ACMPCAEndpointID acm-pca、CloudWatchEndpointID monitoring、SESEndpointID email的常量。这些是 AWS SDK v1 已定义但 SDK v2 未定义的服务端点标识符取值常与 CLI 命令或包名完全不同例如 SES 对应email、CloudWatch 对应monitoring用于在internal/conns中构造endpoints切片的服务键。这也解释了为什么names_data.hcl必须“精确”任何一个 ID 写错都会导致端点配置无法命中对应服务。4. 生成的包名常量文件names/consts_gen.go 由internal/generate/namesconsts/main.go生成文件头注明Code generated ... DO NOT EDIT内容为全大写包名常量到小写包名的映射例如const ( ACM acm ACMPCA acmpca APIGateway apigateway AccessAnalyzer accessanalyzer // ... )整个文件共 557 行覆盖当前全部纳入的服务包名。Provider 代码引用服务包名时统一使用这些常量如names.ACM避免裸字符串拼写错误——这也是“names信息必须正确”的另一层保障。5. 字符串大小写转换工具names包还提供了生成器广泛使用的命名转换函数names/camel.goToCamelCase/ToLowerCamelCase将连字符、下划线、空格、点号分隔的名称转为驼峰式并处理连续大写如ACMPCA中的缩写边界与数字后大写切换names/snake.goToSnakeCase将驼峰式名称转为下划线分隔形式处理大小写与数字交界处插入下划线的规则。这些函数与names_test.go、camel_test.go、snake_test.go中的测试用例共同保证从names_data.hcl的包名派生出 Go 类型名、文件名、资源前缀时行为可预期。实操清单修改 names_data.hcl 的正确姿势结合文档要求与源码行为编辑该文件时建议遵循以下流程先读再改确认理解上文属性表尤其是provider_package_correct、resource_prefix、doc_prefix三者之间的推导关系doc_prefix通常为provider_package_correct_resource_prefix.correct通常为aws_provider_package_correct_。遵守省略约定与服务块名相同的cli_v2_command、go_packages字段省略不写空字符串与假布尔值一律省略保持文件可读性。必填项检查每个service块的names子块必须含provider_name_upper与human_friendlyHCL 解码层面为attr必填human_friendly必须与文档subcategory完全一致。子服务建模若新服务实为已有服务的一部分如 EC2 下的 VPC使用sub_service块并配合file_prefix、split_package、allowed_subcategory表达文件归属与子分类状态。运行make gen编辑后必须执行make gen重新生成代码包括names/consts_gen.go等并让生成器对names_data.hcl做一致性检查CI 中的gen-check目标会验证生成产物没有漂移。人工复核由于exclude、not_implemented、endpoint_only的组合会影响服务是否进入serviceData表以及端点配置改完后建议搜索internal/provider与internal/conns中对相关包名常量的引用确认运行时行为符合预期。小结names包是 Terraform AWS Provider 的服务命名元数据中心names_data.hcl以 HCL 形式声明每个 AWS 服务的包名、SDK 版本、CLI 命令、端点信息、资源前缀与文档前缀等 20 余类字段构建期嵌入、包初始化时解析、生成期被各类生成器读取最终服务于provider、conns、生成器与skaff四大消费者。理解本文介绍的块模式、字段优先级规则如resource_prefix.actual覆盖correct、provider_package_correct覆盖块名与make gen再生成流程是正确扩展 Provider 服务支持的必要前提。【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/17 6:47:44 · 阅读 1.2k Terraform AWS Provider 中的服务命名元数据中心：深入解析 names 包与 names_data.hcl
Terraform AWS Provider 中的服务命名元数据中心深入解析 names 包与 names_data.hcl【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws本篇指南围绕 terraform-provider-aws 仓库中的names包展开完整覆盖 names/README.md 的核心内容names包如何为整个 Provider 提供 AWS 服务命名信息、names_data.hcl的完整块/属性模式与每个字段的用途、编辑后的再生成流程make gen并结合仓库源码说明数据如何被嵌入、解析与消费帮助你在新增或修改服务时正确维护这份“单一事实来源”。为什么 names 包是 Provider 正确运行的基石names包提供 Terraform AWS Provider 正确运行所必需的关键 AWS 服务命名信息。它对外的承诺非常直接如果你不确定自己正在做的改动是否正确请提问后再动手。需要特别注意的是names/data/names_data.hcl中的信息会影响 Provider、代码生成器、文档、网站导航等的正确工作。官方文档明确警告在理解下文的属性说明表之前不要对该文件做任何改动。names包的核心是 names/data/names_data.hcl它包含关于 AWS Provider、AWS Go SDK v1/v2 以及 AWS CLI 中命名信息的 HCL 数据。该文件在构建时被动态嵌入到 AWS Provider 中通过//go:embed并在代码生成时被生成器引用。其中包含的信息必须是精确的任何改动都应当双重检查。从源码看这一“构建时嵌入”体现在 names/data/read.go 末尾的//go:embed names_data.hcl指令上而 names/names.go 中的init()函数在包初始化阶段就通过data.ReadAllServiceData()解析该文件一旦解析失败会直接log.Fatalf终止进程——这也从侧面印证了数据正确性对 Provider 启动的关键意义。names 包的消费者names包的主要消费者包括provider包internal/providerProvider 主逻辑conns包internal/connsAWS 客户端连接与端点配置AWS Provider 各代码生成器internal/generate下skaff脚手架工具skaff/这一点与 names/names.go 的包注释描述一致注释中同时强调names_data.hcl中的信息必须完全正确因为 Terraform AWS Provider 依赖这些信息才能正确工作。编辑 names_data.hcl 之后运行 make gen每次对names/data/names_data.hcl进行编辑之后都应运行make gen。该命令会重新生成代码并对names_data.hcl执行一系列一致性检查。在 GNUmakefile 中可以看到对应目标约第 402 行gen: prereq-go ## Run Go generators (all provider-wide, or scoped to a service with PKG/Kservice)即生成器既可以整体运行也可以通过PKG/Kservice限定到某个服务。此外还有gen-raw运行全部 Go 生成器和gen-checkCI 中校验生成结果是否漂移。names包自身的生成入口是 names/generate.go其中只保留了//go:generate go run ../internal/generate/namesconsts/main.go指令与包声明——该生成器正是产出下文提到的consts_gen.go常量文件的程序。names_data.hcl 的完整模式Schemanames_data.hcl的属性与块的模式定义如下摘自 README即该文件必须遵循的结构service { // If both of these attributes are the same as the service blocks name, this block will be omitted cli_v2_command { aws_cli_v2_command aws_cli_v2_command_no_dashes } // If both of these attributes are the same as the service blocks name, this block will be omitted go_packages { v1_package v2_package } // If any blocks below here have attirbutes with empty strings or false bools, they will be omitted // Blocks with zero attributes will be omitted sdk { id client_version 2 } names { aliases [] // This can also be excluded if it is empty provider_name_upper human_friendly } client { go_v1_client_typename skip_client_generate bool } env_var { deprecated_env_var tf_aws_env_var } endpoint_info { endpoint_api_call endpoint_api_params endpoint_region_override endpoint_only bool } resource_prefix { actual correct } provider_package_correct split_package file_prefix doc_prefix [] brand exclude bool not_implemented bool allowed_subcategory bool note is_global bool }几个模式层面的要点均可在 names/data/read.go 的 Go 结构体定义中得到印证service块以 label 形式承载包名ProviderPackage string \hcl:,label其余块均为可选。names块中的provider_name_upper与human_friendly使用attr必填标记其余为optional——也就是说每个service块必须声明这两个字段。解析时sdk.client_version缺省为0ReadAllServiceData()会将其回填为默认值2见 names/data/read.go。sub_service块用于表达“多个服务共存于一个服务”的场景例如 VPC 属于 EC2ReadAllServiceData()会将其展平为独立的ServiceRecord见 names/data/read.go。实际数据示例结合仓库中真实的names_data.hcl片段可以直观看到各字段的用法。以下示例取自 names/data/names_data.hclservice accessanalyzer { sdk { id AccessAnalyzer arn_namespace access-analyzer } names { provider_name_upper AccessAnalyzer human_friendly IAM Access Analyzer } endpoint_info { endpoint_api_call ListAnalyzers } resource_prefix { correct aws_accessanalyzer_ } provider_package_correct accessanalyzer doc_prefix [accessanalyzer_] brand AWS }再对比一个启用cli_v2_command覆盖与全局标记的示例service accountaccess { cli_v2_command { aws_cli_v2_command account-access aws_cli_v2_command_no_dashes accountaccess } sdk { id Account Access arn_namespace account-access } names { provider_name_upper AccountAccess human_friendly Account Access } # ... }service acm { names { provider_name_upper ACM human_friendly ACM (Certificate Manager) human_friendly_short ACM } # ... }以及带is_global true的全局服务示例service account { # ... is_global true }这些片段恰好演示了模式说明中的省略规则cli_v2_command与go_packages块仅在与服务块名不同时才出现空字符串/假布尔值的属性会被省略。属性详解每个字段如何被代码使用以下是 README 中完整的属性说明表每个字段标注了用途类别Code 表示参与代码生成/运行逻辑Reference 表示主要供参考核对NameUseDescriptionProviderPackageActualCodeprovider_package_correct未使用时TF AWS Provider 包的实际名称若两者同时定义服务块名以provider_package_correct优先aws_cli_v2_commandReferenceAWS CLI v2 中该服务的命令名aws_cli_v2_command_no_dashesReference与aws_cli_v2_command相同但去掉连字符v1_packageCodeAWS SDK for Go v1 的包名v2_packageCodeAWS SDK for Go v2 的包名idCode代表 AWS 服务的 ServiceID某一具体服务的唯一标识符client_versionCode表示该服务使用哪个版本的 AWS SDK默认2aliasesCode名称变体的 HCL 字符串列表例如 AMP 对应prometheus,prometheusservice。不要包含 ProviderPackageActual若provider_package_correct为空则指它否则会在使用自定义端点时产生重复provider_name_upperCodeProviderPackageActual若存在否则provider_package_correct的规范大写形式human_friendlyCode必填。AWS 侧使用的服务友好名称文档subcategory必须与该值完全一致用于网站导航与错误信息human_friendly_shortCodeAWS 侧服务友好名称但去掉括号注释例如 S3 为S3而不是S3 (Simple Storage)go_v1_client_typenameCodeAWS SDK for Go v1 客户端类型的精确名称拼写与大小写均须一致仅支持 SDK v2 的服务可省略skip_client_generateCode部分服务客户端需要特殊配置而非默认生成的配置使用非空值跳过生成之后必须在internal/conns/config.go中手动配置该客户端deprecated_env_varCode某些服务定义的已弃用AWS_service_ENDPOINT环境变量tf_aws_env_varCode某些服务定义的TF_AWS_service_ENDPOINT环境变量endpoint_api_callCode用于描述当前服务的 AWS CLI 命令/API 调用endpoint_api_paramsCode用于service_endpoints_gen_test.go文件中需要配置值的 API 调用参数endpoint_region_overrideCode为 API 请求指定替代的区域端点endpoint_onlyCode基于not_implemented是否非空决定服务端点是否应包含在 Provider 的endpoints配置中resource_prefix_actualCode用于匹配异常 TF 资源名前缀的正则表达式例如aws_config_config_rule中aws_config_会匹配该服务所有资源仅在resource_prefix_correct不适用时使用例如aws_codepipeline_不行因为只有一个名为aws_codepipeline的资源优先于resource_prefix_correctresource_prefix_correctCode用于匹配资源名前缀应当是什么的正则表达式即aws_provider_package_correct_在resource_prefix_actual为空时使用provider_package_correctCodeaws_cli_v2_command_no_dashes与v2_package中较短者若两者存在则不应为空即“服务标识符”也是 TF AWS Provider 包名应当是什么ProviderPackageActual优先split_package_real_packageCode若多个“服务”位于一个服务内这是该服务 Go 文件所在的包例如 VPC 是 EC2 的一部分file_prefixCode若多个“服务”位于一个服务内文件必须带有的前缀以关联到该子服务例如 EC2 服务中 VPC 文件以vpc_为前缀doc_prefixCodewebsite/docs/r与website/docs/d中服务文档文件前缀的 HCL 字符串列表通常只有一个前缀即provider_package_correct_brandCodeAWS 使用的Amazon、AWS或空罕见用于错误信息excludeCode该服务是否应被包含的布尔值若包含留空则ProviderPackageActual或provider_package_correct必须有值allowed_subcategoryCode若Exclude非空是否仍将human_friendly放入website/allowed-subcategories.txt即某些情况下覆盖exclude。部分被排除的伪服务例如 EC2 中的 VPC仍然是子分类。仅在Exclude非空时生效not_implementedCode该服务是否已被 Provider 实现的布尔值noteReference非常简短的备注通常用于解释为何被排除is_globalCode表示该服务是否为全局服务的布尔值参见 Enhanced Region Support 指南中关于全局服务的说明源码中的优先级规则这些“省略/优先”逻辑如何落地上面表格中的优先级与默认值规则在 names/data/read.go 中有精确实现值得逐一对照理解CLI 命令回退AWSCLIV2Command()/AWSCLIV2CommandNoDashes()在cli_v2_command块缺失时回退到service块的 label即 ProviderPackage见 names/data/read.go。Go 包名回退GoV1Package()/GoV2Package()在go_packages块缺失时同样回退到包名GoPackageName()则根据SDKVersion()选择返回 v1 或 v2 包名names/data/read.go。包名纠正ProviderPackageCorrect()在provider_package_correct非空时优先于块名names/data/read.go。资源前缀优先级ResourcePrefix()明确实现“resource_prefix_actual非空则覆盖resource_prefix_correct”names/data/read.go。友好名称短名回退HumanFriendlyShort()在短名未设置时回退到human_friendlynames/data/read.goFullHumanFriendly()会拼接brand如AWS IAM Access Analyzer。FIPS 支持推断EndpointFIPSSupport()基于endpoint_no_fips_support取反默认支持names/data/read.go。端点环境变量推导AWSServiceEnvVar()直接由SDKID()推导AWS_ENDPOINT_URL_IDAWSConfigParameter()由 SDK ID 转小写下划线形式names/data/read.go——也就是说sdk.id字段间接决定了 SDK v2 的标准端点覆盖变量名。数据如何被消费从 HCL 到 Provider 运行时1. 嵌入与解析names_data.hcl在编译期通过//go:embed嵌入data包见 names/data/read.go。ReadAllServiceData()使用hclparse解析 HCL再用gohcl.DecodeBody解码进Services结构体随后为每条记录含展平的sub_service生成ServiceRecord包装类型。该包装类型聚合了约三十个访问器方法是生成器与运行时代码读取服务元数据的统一入口。2. 运行时服务数据表serviceDatanames/names.go 中的init()构建了一个以 Provider 包名为键的内存表serviceData并执行两条过滤规则Exclude()为真的服务直接跳过NotImplemented()为真且非EndpointOnly()的服务也跳过即尚未实现的服务若仅保留端点定义仍可出现在端点相关逻辑中。在此之上names包对外暴露一组查询函数均位于 names/names.go函数作用ProviderPackageForAlias(alias)通过别名反查 Provider 包名未命中返回错误ProviderPackages()返回全部已加载服务的包名Aliases()返回所有服务的别名集合含包名本身ProviderNameUpper(service)返回规范大写名可用于生成类型名FullHumanFriendly(service)返回brand human_friendly形式的完整名称HumanFriendly(service)返回友好名称支持按别名递归查找conns包正是依赖这套别名→包名映射来解析用户在各服务endpoints配置中书写的服务名而provider包则利用FullHumanFriendly/ProviderNameUpper生成面向用户的错误信息与资源命名。此外 names/data/lookup.go 提供了LookupService(name)供生成器等工具按包名精确获取某条ServiceRecord。3. 端点 ID 常量SDK v1 与 v2 的差异names/names.go 还定义了一组形如ACMPCAEndpointID acm-pca、CloudWatchEndpointID monitoring、SESEndpointID email的常量。这些是 AWS SDK v1 已定义但 SDK v2 未定义的服务端点标识符取值常与 CLI 命令或包名完全不同例如 SES 对应email、CloudWatch 对应monitoring用于在internal/conns中构造endpoints切片的服务键。这也解释了为什么names_data.hcl必须“精确”任何一个 ID 写错都会导致端点配置无法命中对应服务。4. 生成的包名常量文件names/consts_gen.go 由internal/generate/namesconsts/main.go生成文件头注明Code generated ... DO NOT EDIT内容为全大写包名常量到小写包名的映射例如const ( ACM acm ACMPCA acmpca APIGateway apigateway AccessAnalyzer accessanalyzer // ... )整个文件共 557 行覆盖当前全部纳入的服务包名。Provider 代码引用服务包名时统一使用这些常量如names.ACM避免裸字符串拼写错误——这也是“names信息必须正确”的另一层保障。5. 字符串大小写转换工具names包还提供了生成器广泛使用的命名转换函数names/camel.goToCamelCase/ToLowerCamelCase将连字符、下划线、空格、点号分隔的名称转为驼峰式并处理连续大写如ACMPCA中的缩写边界与数字后大写切换names/snake.goToSnakeCase将驼峰式名称转为下划线分隔形式处理大小写与数字交界处插入下划线的规则。这些函数与names_test.go、camel_test.go、snake_test.go中的测试用例共同保证从names_data.hcl的包名派生出 Go 类型名、文件名、资源前缀时行为可预期。实操清单修改 names_data.hcl 的正确姿势结合文档要求与源码行为编辑该文件时建议遵循以下流程先读再改确认理解上文属性表尤其是provider_package_correct、resource_prefix、doc_prefix三者之间的推导关系doc_prefix通常为provider_package_correct_resource_prefix.correct通常为aws_provider_package_correct_。遵守省略约定与服务块名相同的cli_v2_command、go_packages字段省略不写空字符串与假布尔值一律省略保持文件可读性。必填项检查每个service块的names子块必须含provider_name_upper与human_friendlyHCL 解码层面为attr必填human_friendly必须与文档subcategory完全一致。子服务建模若新服务实为已有服务的一部分如 EC2 下的 VPC使用sub_service块并配合file_prefix、split_package、allowed_subcategory表达文件归属与子分类状态。运行make gen编辑后必须执行make gen重新生成代码包括names/consts_gen.go等并让生成器对names_data.hcl做一致性检查CI 中的gen-check目标会验证生成产物没有漂移。人工复核由于exclude、not_implemented、endpoint_only的组合会影响服务是否进入serviceData表以及端点配置改完后建议搜索internal/provider与internal/conns中对相关包名常量的引用确认运行时行为符合预期。小结names包是 Terraform AWS Provider 的服务命名元数据中心names_data.hcl以 HCL 形式声明每个 AWS 服务的包名、SDK 版本、CLI 命令、端点信息、资源前缀与文档前缀等 20 余类字段构建期嵌入、包初始化时解析、生成期被各类生成器读取最终服务于provider、conns、生成器与skaff四大消费者。理解本文介绍的块模式、字段优先级规则如resource_prefix.actual覆盖correct、provider_package_correct覆盖块名与make gen再生成流程是正确扩展 Provider 服务支持的必要前提。【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考