terraform-provider-aws 标识符大小写规范解析names/caps 初短词命名规则与 semgrep 强制机制【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws在 terraform-provider-aws 这样一个横跨数百个 AWS 服务的大型 Go 代码库中标识符里缩写词initialism的大小写直接决定了代码可读性与一致性。本篇基于仓库中 names/caps.md 及其生成器源码完整讲清 Provider 内部的两条大小写原则、125 条错误写法 → 正确写法映射表、Test# 分组编号的原理以及如何通过 semgrep 规则把这些约定固化到 CI 检查中读完后可独立为团队设计类似的命名规范并理解单一数据源驱动文档与 Linter 规则的生成式治理思路。一、两条大小写指导原则names/caps.md 开篇明确了 Provider 代码中函数名、常量名、变量名大小写处理的两条原则原则 1遵循 Go 惯用 MixedCaps并对缩写词initialisms做惯用处理。这一点直接引自 Go 官方 Code Review Comments 中关于缩写词的论述原文档引用名称中作为缩写或缩略词的词例如 URL 或 NATO应保持大小写一致。例如 URL 应写作 URL 或 url如 urlPony 或 URLPony绝不能写作 Url。再如 ServeHTTP 而不是 ServeHttp。对于含多个缩写词的标识符应写作 xmlHTTPRequest 或 XMLHTTPRequest。当 ID 是 identifier 的缩写时也适用这条规则绝大多数情况下都是如此除非是指 ego、superego 中的 id因此应写 appID 而不是 appId。原则 2遵循 AWS 官方偏好的服务名大小写写法。判断标准是查看 AWS 官网上对应服务页面的写法。例如 SageMaker 而非 Sagemaker、GameLift 而非 Gamelift、DynamoDB 而非 Dynamodb。这两条原则的落地方式不是靠人工评审自觉而是靠 semgrep 规则自动检查仓库中维护一张错误写法 → 正确写法清单并据此批量生成 Linter 规则。二、错误 → 正确写法全表Wrong → Right以下为 names/caps.md 收录的全部 125 条初短词大小写映射与数据源 names/caps.csv 同源生成Wrong,Right两列。表格按 Wrong 列字母序排列Test#列是该条对应的 semgrep 规则分组编号其分组逻辑见后文第四节WrongRightTest#AclACLcaps1AcmACMcaps1AcmPcaACMPCAcaps0AcmpcaACMPCAcaps0AmiAMIcaps1ApiAPIcaps1ApiGatewayAPIGatewaycaps0AppconfigAppConfigcaps0AppmeshAppMeshcaps0AppsyncAppSynccaps0ArnARNcaps2AsgASGcaps2AsnASNcaps2AutoscalingAutoScalingcaps0BgpBGPcaps2ByoipBYOIPcaps0CidrCIDRcaps1CloudformationCloudFormationcaps0CloudfrontCloudFrontcaps0CloudwatchCloudWatchcaps0CmkCMKcaps2CnameCNAMEcaps0CoipCoIPcaps1CpuCPUcaps2CssCSScaps2CsvCSVcaps2DaxDAXcaps2DbDBcaps3DhcpDHCPcaps1DkimDKIMcaps1DlmDLMcaps2DmsDMScaps2DnsDNScaps2DnssecDNSSECcaps0DocDbDocDBcaps0DocdbDocDBcaps0DynamoDbDynamoDBcaps0DynamodbDynamoDBcaps0EbsEBScaps2Ec2EC2caps2EcmpECMPcaps1EcrECRcaps2EcsECScaps2EfsEFScaps2EipEIPcaps2EksEKScaps2ElasticacheElastiCachecaps0ElasticSearchElasticsearchcaps0ElbELBcaps2EmrEMRcaps2FifoFIFOcaps1FmsFMScaps2FqdnsFQDNScaps0FSXFSxcaps2FsxFSxcaps2GameliftGameLiftcaps0GcmGCMcaps2Gp2GP2caps2Gp3GP3caps2GraphqlGraphQLcaps0GrpcGRPCcaps1GuarddutyGuardDutycaps0HaproxyHAProxycaps0HsmHSMcaps2HttpHTTPcaps1HttpsHTTPScaps1HvmHVMcaps2IamIAMcaps2IotIoTcaps2IpIPcaps4IpamIPAMcaps1IpsetIPSetcaps1IscsiiSCSIcaps1JdbcJDBCcaps1JsonJSONcaps1KmsKMScaps3MfaMFAcaps3MicrovmsMicroVMscaps0MskMSKcaps3MwaaMWAAcaps1MysqlMySQLcaps1NfsNFScaps3OauthOAuthcaps1OidcOIDCcaps1OpsworksOpsWorkscaps0PhpPHPcaps3PitrPITRcaps1PosixPOSIXcaps1PrecheckPreCheckcaps0QldbQLDBcaps1RabbitmqRabbitMQcaps0RdsRDScaps3RfcRFCcaps3SagemakerSageMakercaps0SaslSASLcaps1SdkSDKcaps3SfnSFNcaps3SmbSMBcaps3SmsSMScaps3SmtpSMTPcaps1SnsSNScaps3SqlSQLcaps3SqsSQScaps3SshSSHcaps3SslSSLcaps3SsmSSMcaps3SsoSSOcaps3StsSTScaps3SwfSWFcaps3TcpTCPcaps3TlsTLScaps3TtlTTLcaps3UriURIcaps3UrlURLcaps3VgwVGWcaps3VoipVoIPcaps1VpcVPCcaps3VpnVPNcaps3WafWAFcaps3Wafv2WAFV2caps1WorklinkWorkLinkcaps0WorkspacesWorkSpacescaps0XrayXRaycaps1XssXSScaps3YamlYAMLcaps1可以观察到三类典型形态全大写缩写占大多数Api → API、Dns → DNS、Ssh → SSH、Vpc → VPC等即 Go 惯用写法中缩写词整体大写驼峰式官方写法Sagemaker → SageMaker、Elasticache → ElastiCache、Workspaces → WorkSpaces这类词 AWS 官方按驼峰书写反向纠正把过度大写改回正确形式ElasticSearch → Elasticsearch、FSX → FSx、Wafv2 → WAFV2说明规范同时约束少写大写和多写大写两个方向。备注上表Microvms一行在源数据 names/caps.csv 中 Right 值带有一个前导空格MicroVMs属于数据源中的小瑕疵此处按规范写法展示为MicroVMs。三、原文档的三个重要 NOTEnames/caps.md 在表格前后给出三条对维护者至关重要的说明不要把 Id 加入清单。正确写法是ID或id永远不是Id但团队发现用 Linter 强制这条缩写词规则误报率过高例如Identifier会被误伤因此刻意放弃对其自动化检查。这是一个典型的原则保留、自动化让位的工程取舍。semgrep 规则 ID 的命名约定。所有大小写规则集中在 semgrep 配置文件semgrep-caps-aws-ec2.yml中生成产物路径为.ci/semgrep-caps-aws-ec2.yml规则 ID 形如Test#-in-func-name、Test#-in-var-name或Test#-in-const-name其中Test#即表格第三列的caps0~caps4编号。Test# 编号顺序不整齐是有意为之。分组必须按更长的名字优先匹配排列。文档给出的例子是HTTPS必须先于HTTP处理否则自动纠正时可能把HTTPS修成HTTPs这类中间态。这正是 Test# 与字母序表头错位的原因。四、生成管线一份 caps.csv两处消费上述表格并非手工维护而是由生成器从唯一数据源 names/caps.csv表头Wrong,Right计算产出。仓库中有两个生成器消费这份 CSV分别产出人读的文档和机器执行的规则。4.1 文档生成器namescapslistinternal/generate/namescapslist/main.go 的main函数把 CSV 读入后写到names/caps.md文件内标注Generated by internal/generate/namescapslist/main.go; DO NOT EDIT。核心逻辑在 readBadCaps 函数分三步按 Wrong 长度降序 字典序排序#L94-L100cmp.Compare(len(b.Wrong), len(a.Wrong))优先比较长度长词在前按每 31 条一个分块指派 Test##L102-L110常量maxBadCaps 31每当i%31 0时块号加一于是 125 条数据被分成caps0~caps4共 5 组按忽略大小写的字母序重排#L112-L117使最终表格对读者友好。这两步排序的先后关系恰好解释了原文档 NOTE 3 的wonky orderTest# 编号是在长度降序状态下分配的长词落在 caps0短词如Ip落在最后一组 caps4而展示表格又是字母序的。也就是说caps0 基本聚集了 6 个字符以上的长条目如AcmPca、Dynamodb、Microvmscaps4 只剩最短的Ip一条。该目录下的 generate.go 提供//go:generate go run main.go指令main.go带//go:build generate构建标签因此重新生成文档的方式是在internal/generate/namescapslist目录下运行go run -tags generate main.go。4.2 semgrep 规则生成器servicesemgrepinternal/generate/servicesemgrep/main.go 读取同一份names/caps.csv用模板 cae.tmpl 渲染出 caps 规则写入.ci/semgrep-caps-aws-ec2.yml生成器中filenameCAE常量指定该目标路径。从 模板的 range 块 可以看到每一条caps 条目都会展开为三条 semgrep 规则- id: caps{{- $i }}-in-func-name # 检查 func $NAME( ... ) 的函数名 - id: caps{{- $i }}-in-const-name # 检查 const $NAME ... 的常量名 - id: caps{{- $i }}-in-var-name # 检查 var $NAME ... 的变量名每条规则的共同点模板内容可确认languages: [go]检查对象为 Go 代码用pattern先锚定函数/常量/变量声明再通过metavariable-pattern对名称元变量做正则匹配pattern-regex: ({{ $s }})其中{{ $s }}即 CSV 中的 Wrong 写法作用域限定paths.include: [/internal]——即覆盖 Provider 全部服务包severity 为WARNING。规则 message 直接指回清单Use correct caps in func name (i.e., HTTPS or https, not Https) (see list at .../names/caps.md)。从同一模板还能看到该配置文件不止管大小写文件开头的aws-in-func-name/aws-in-const-name/aws-in-var-name三条规则禁止在 Provider 内部标识符中使用 AWSProvider 自身就是 AWS 语境避免冗余前缀文件尾部还有针对 ec2 包内禁用 EC2 字样的规则。可以推断semgrep-caps-aws-ec2.yml这个文件名是历史遗留命名其检查范围实际是整个internal/目录。另外注意 servicesemgrep/main.go 中maxBadCaps 21与文档生成器的31不同说明规则侧与文档侧对分块粒度的策略独立演进对使用者而言无需关心差异只需保证两个生成器消费同一 CSV、同步重新生成。五、给维护者的操作指引结合源码可以归纳出新增/修改初短词规范的完整流程唯一入口是 CSV。在 names/caps.csv 中追加一行Wrong,Right如Grpc,GRPC这种既有形态或新发现的误写形式。不要手改names/caps.md——它是生成产物头部明确标注 DO NOT EDIT重新生成文档cd internal/generate/namescapslist go run -tags generate main.go重新生成 semgrep 规则cd internal/generate/servicesemgrep go run -tags generate main.go该生成器同时会刷新.semgrep-service-name.yml与.semgrep-configs.yml见 main.go 中的三个输出常量验证运行 semgrep 检查确认新规则命中预期的错误写法且不误伤Id的教训提醒新条目需先评估误报面宁可放弃自动化也要保住正确原则。由于 Test# 编号是按长度降序分块自动计算的插入任何新条目都可能使后续条目的 Test# 整体漂移——这是生成式设计的一贯代价规则 ID 不稳定但换来文档与 Linter 永远同源、永不漂移。六、小结names/caps.md 表面上是一张 125 行的缩写词对照表其真正价值在于展示了 terraform-provider-aws 的代码治理范式以一份最小化的 CSV 作为单一事实源用确定性生成器同时产出面向人的文档按字母序展示与面向机器的 semgrep 规则按长度降序匹配并在文档中显式记录为什么编号不整齐这类设计意图。对于大型多团队 Go 仓库这套文档即规则、规则即文档的机制比单纯依靠 review 评论更能让命名约定长期稳定。【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考