AWS CDK 中为 API Gateway 域名添加双栈 IP 地址支持

在 AWS CDK 2.195.0 版本中，开发者发现无法为 API Gateway 的自定义域名配置双栈（IPv4 和 IPv6）IP 地址类型。虽然 HTTP API 本身已经支持设置双栈 IP 地址类型，但 DomainName 构造却缺少这一关键配置项。

问题背景

AWS API Gateway 近期新增了对双栈（IPv4 和 IPv6）端点的支持，这意味着开发者现在可以为 API Gateway 同时启用 IPv4 和 IPv6 访问能力。然而在 CDK 实现中，这一功能并未完全覆盖所有相关组件。

具体表现为：

• HttpApi 构造已支持通过 ipAddressType 参数配置双栈
• 但 DomainName 构造缺少相应配置，导致自定义域名无法完全支持 IPv6

技术实现分析

在底层 CloudFormation 资源 CfnDomainName 中，DomainNameConfigurationProperty 实际上已经包含了 IpAddressType 参数。问题出在 CDK 的高级构造 DomainName 没有将这个参数暴露给开发者使用。

核心差异点在于：

• 底层 CfnDomainName 支持配置 IP 地址类型
• 高级 DomainName 构造缺少相应属性
• 导致即使 API 本身配置了双栈，自定义域名仍无法完全支持 IPv6

解决方案演进

AWS CDK 团队已经通过 PR #34111 解决了这个问题，该变更将在后续版本中发布。新实现主要做了以下改进：

1. 在 EndpointOptions 接口中添加 ipAddressType 属性
2. 更新 DomainName 类的 addEndpoint 方法以支持该属性
3. 允许开发者通过标准方式配置双栈域名

新版本发布后，开发者可以这样使用：

const dn = new apigwv2.DomainName(this, 'DN', {
  domainName: 'api.example.com',
  certificate: cert,
  ipAddressType: apigwv2.IpAddressType.DUAL_STACK
});

临时解决方案

在等待新版本发布期间，开发者可以通过直接操作底层 CloudFormation 资源来实现相同功能：

const cfnDomainName = domainName.node.defaultChild as CfnDomainName;
cfnDomainName.addPropertyOverride(
  "DomainNameConfigurations.0.IpAddressType",
  IpAddressType.DUAL_STACK
);

技术意义

这一改进使得 AWS CDK 对 API Gateway 双栈支持更加完整，帮助开发者：

1. 更容易地构建面向未来的 IPv6 兼容应用
2. 保持 API Gateway 各组件配置的一致性
3. 通过 CDK 的高级抽象简化双栈配置过程

随着 IPv6 的普及，这一功能将变得越来越重要，特别是在需要同时支持新旧网络协议的环境中。