如何在AWS CDK中为API Gateway已有端点设置方法级TPS速率限制

要实现API Stage中特定资源路径的方法级限流，核心是在CDK的UsagePlan配置中直接关联目标Method并为其单独设置限流规则，而非仅关联整个Stage。以下是具体实现步骤和代码示例：

关键实现逻辑 #

AWS API Gateway的方法级限流需要绑定到具体的Method对象，而非仅通过Stage关联。在CDK中，你需要在UsagePlan的apiStages参数里，为指定Method配置throttle规则。

代码示例（TypeScript） #

import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { RestApi, UsagePlan, ApiKey, Method } from 'aws-cdk-lib/aws-apigateway';

export class ApiThrottleStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    // 1. 创建RestApi及目标资源、方法
    const restApi = new RestApi(this, 'UserManagementApi');
    const usersResource = restApi.root.addResource('users');
    const singleUserResource = usersResource.addResource('{userId}');
    // 目标方法：GET /users/{userId}
    const getUserMethod: Method = singleUserResource.addMethod('GET');

    // 2. 创建API Key
    const apiKey = new ApiKey(this, 'UserApiKey', {
      enabled: true
    });

    // 3. 创建UsagePlan并配置方法级限流
    const usagePlan = new UsagePlan(this, 'UserApiUsagePlan', {
      name: 'UserApi-Method-Level-Throttle',
      description: '限流规则：GET /users/{userId} 每秒100请求，突发200请求',
      apiStages: [
        {
          api: restApi,
          stage: restApi.deploymentStage,
          // 为指定方法设置限流
          throttle: [
            {
              method: getUserMethod,
              throttle: {
                rateLimit: 100, // 每秒允许的请求数
                burstLimit: 200  // 突发请求上限
              }
            }
            // 可添加更多方法的限流规则，比如POST /users
          ]
        }
      ]
    });

    // 4. 将API Key关联到UsagePlan
    usagePlan.addApiKey(apiKey);
  }
}

注意事项 #

• 必须引用Method对象：不能通过字符串路径指定方法，必须使用CDK中创建或导入的Method实例，否则限流规则无法绑定到具体方法。
• 导入已有资源：如果是配置已存在的API/方法，可使用RestApi.fromRestApiId()和Method.fromMethodArn()导入对象后再配置限流。
• 限流参数约束：burstLimit的值不能小于rateLimit，否则CDK会抛出错误。
• 生效前提：确保API Gateway的Stage已经完成部署，限流规则才会生效。测试时必须使用关联了该UsagePlan的API Key发起请求。

常见误区规避 #

• 不要仅调用usagePlan.addApiStage()而不配置throttle参数，这样只会将整个Stage关联到UsagePlan，无法实现方法级限流。
• 若方法集成了Lambda，需确保Lambda的并发限制与API Gateway的限流规则匹配，避免出现上游资源瓶颈导致的限流失效。

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