为何AWS CDK文档与本地waf2.generated.d.ts的CfnWebACLProps定义不一致？

问题场景 #

在使用AWS CDK创建WAFv2 Web ACL时，执行以下代码：

import * as wafv2 from "aws-cdk-lib/aws-wafv2";
const wafAclCloudFront = new wafv2.CfnWebACL(scope, id, props)

其构造函数签名为：

CfnWebACL.constructor(scope: constructs.Construct, id: string, props: CfnWebACLProps)

根据AWS CDK官方文档给出的CfnWebACLProps示例定义如下：

const cfnWebACLProps: waf.CfnWebACLProps = {
  defaultAction: {
    type: 'type',
  },
  metricName: 'metricName',
  name: 'name',

  // the properties below are optional
  rules: [{
    priority: 123,
    ruleId: 'ruleId',

    // the properties below are optional
    action: {
      type: 'type',
    },
  }],
};

但本地项目的全局waf2.generated.d.ts文件中，CfnWebACLProps接口的完整定义为：

export interface CfnWebACLProps {
    /**
     * The action to perform if none of the `Rules` contained in the `WebACL` match.
     *
     * @link http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-wafv2-webacl.html#cfn-wafv2-webacl-defaultaction
     */
    readonly defaultAction: CfnWebACL.DefaultActionProperty | cdk.IResolvable;
    /**
     * Specifies whether this is for an Amazon CloudFront distribution or for a regional application. A regional application can be an Application Load Balancer (ALB), an Amazon API Gateway REST API, or an AWS AppSync GraphQL API. Valid Values are `CLOUDFRONT` and `REGIONAL` .
     *
     * > For `CLOUDFRONT` , you must create your WAFv2 resources in the US East (N. Virginia) Region, `us-east-1` .
     *
     * For information about how to define the association of the web ACL with your resource, see `WebACLAssociation` .
     *
     * @link http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-wafv2-webacl.html#cfn-wafv2-webacl-scope
     */
    readonly scope: string;
    /**
     * Defines and enables Amazon CloudWatch metrics and web request sample collection.
     *
     * @link http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-wafv2-webacl.html#cfn-wafv2-webacl-visibilityconfig
     */
    readonly visibilityConfig: CfnWebACL.VisibilityConfigProperty | cdk.IResolvable;
    /**
     * Specifies how AWS WAF should handle `CAPTCHA` evaluations for rules that don't have their own `CaptchaConfig` settings. If you don't specify this, AWS WAF uses its default settings for `CaptchaConfig` .
     *
     * @link http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-wafv2-webacl.html#cfn-wafv2-webacl-captchaconfig
     */
    readonly captchaConfig?: CfnWebACL.CaptchaConfigProperty | cdk.IResolvable;
    /**
     * A map of custom response keys and content bodies. When you create a rule with a block action, you can send a custom response to the web request. You define these for the web ACL, and then use them in the rules and default actions that you define in the web ACL.
     *
     * For information about customizing web requests and responses, see [Customizing web requests and responses in AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html) in the [AWS WAF Developer Guide](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) .
     *
     * For information about the limits on count and size for custom request and response settings, see [AWS WAF quotas](https://docs.aws.amazon.com/waf/latest/developerguide/limits.html) in the [AWS WAF Developer Guide](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) .
     *
     * @link http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-wafv2-webacl.html#cfn-wafv2-webacl-customresponsebodies
     */
    readonly customResponseBodies?: {
        [key: string]: (CfnWebACL.CustomResponseBodyProperty | cdk.IResolvable);
    } | cdk.IResolvable;
    /**
     * A description of the web ACL that helps with identification.
     *
     * @link http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-wafv2-webacl.html#cfn-wafv2-webacl-description
     */
    readonly description?: string;
    /**
     * The name of the web ACL. You cannot change the name of a web ACL after you create it.
     *
     * @link http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-wafv2-webacl.html#cfn-wafv2-webacl-name
     */
    readonly name?: string;
    /**
     * The rule statements used to identify the web requests that you want to allow, block, or count. Each rule includes one top-level statement that AWS WAF uses to identify matching web requests, and parameters that govern how AWS WAF handles them.
     *
     * @link http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-wafv2-webacl.html#cfn-wafv2-webacl-rules
     */
    readonly rules?: Array<CfnWebACL.RuleProperty | cdk.IResolvable> | cdk.IResolvable;
    /**
     * Key:value pairs associated with an AWS resource. The key:value pair can be anything you define. Typically, the tag key represents a category (such as "environment") and the tag value represents a specific value within that category (such as "test," "development," or "production"). You can add up to 50 tags to each AWS resource.
     *
     * > To modify tags on existing resources, use the AWS WAF APIs or command line interface. With AWS CloudFormation , you can only add tags to AWS WAF resources during resource creation.
     *
     * @link http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-wafv2-webacl.html#cfn-wafv2-webacl-tags
     */
    readonly tags?: cdk.CfnTag[];
}

差异原因分析 #

1. 文档示例的简化性 #

官方文档给出的示例仅用于展示核心用法，刻意省略了部分必填属性（如scope、visibilityConfig）和大部分可选属性，目的是降低入门学习的复杂度，并非完整的属性参考。实际生产中必须遵循本地生成文件的完整定义来配置。

2. CDK版本不一致 #

本地的.generated.d.ts文件是根据你当前安装的AWS CDK版本自动生成的，严格对应该版本中WAFv2 CloudFormation资源的实际属性规范。如果文档版本与本地CDK版本不匹配，就会出现属性差异——比如AWS WAFv2的属性在不同CDK版本中可能有更新：

• 早期版本的metricName被整合到visibilityConfig中，成为其下属配置项
• scope属性后来被设为必填项，用于区分CloudFront和区域型资源

3. 模块路径的历史变更 #

注意到文档链接指向的是aws-cdk-lib.aws_waf.CfnWebACLProps，但你实际使用的是aws-cdk-lib/aws-wafv2模块。早期CDK版本中WAFv2资源可能归类在aws_waf模块下，后来拆分到独立的aws_wafv2模块，文档可能存在滞后或链接指向错误，导致示例与实际模块的属性定义不匹配。

内容的提问来源于stack exchange，提问作者MasterOfTheHouse