aws-cdk-development

AWS CDK 开发

本技能提供使用 Cloud Development Kit（CDK）开发 AWS 基础设施的全面指导，并集成 MCP 服务，以便访问最新的 AWS 知识和 CDK 工具。

AWS 文档要求

回答前，务必使用 MCP 工具（mcp__aws-mcp__* 或 mcp__*awsdocs*__*）核实 AWS 相关信息。依赖项 aws-mcp-setup 会自动加载——如果 MCP 工具不可用，请引导用户完成该技能的设置流程。

CDK 专用 MCP 指南

AWS Labs 已用更全面的 awslabs.aws-iac-mcp-server 取代专用的 CDK MCP 服务（awslabs.cdk-mcp-server），该服务涵盖 CDK、CloudFormation 及其他 AWS 基础设施即代码工作流。

如需查询 CDK 构造、获取最佳实践建议和模式指导，请安装 awslabs.aws-iac-mcp-server。它包含在 awslabs/agent-plugins 中的 deploy-on-aws 插件内，也可以通过 claude mcp add aws-iac uvx awslabs.aws-iac-mcp-server@latest 直接注册。

适用场景：

• CDK 构造建议和 API 查询
• CDK 和 CloudFormation 最佳实践模式
• 合成模板验证
• 跨资源配置指导

何时使用本技能

在以下情况下使用本技能：

• 创建新的 CDK 堆栈或构造
• 重构现有 CDK 基础设施
• 在 CDK 中实现 Lambda 函数
• 遵循 AWS CDK 最佳实践
• 部署前验证 CDK 堆栈配置
• 核实 AWS 服务功能和区域可用性

CDK 核心原则

资源命名

重要：如果 CDK 构造中的资源名称为可选项，请勿显式指定资源名称。

原因：由 CDK 生成的名称可以：

• 复用模式：多次部署同一构造／模式而不发生冲突
• 并行部署：同一区域中的多个堆栈可以同时部署
• 简化共享逻辑：模式和共享代码可以多次初始化，而不会发生名称冲突
• 隔离堆栈：每个堆栈都会自动获得唯一标识的资源

模式：使用 CloudFormation 的命名机制，让 CDK 自动生成唯一名称。

// ❌ BAD - Explicit naming prevents reusability and parallel deployments
new lambda.Function(this, 'MyFunction', {
  functionName: 'my-lambda',  // Avoid this
  // ...
});

// ✅ GOOD - Let CDK generate unique names
new lambda.Function(this, 'MyFunction', {
  // No functionName specified - CDK generates: StackName-MyFunctionXXXXXX
  // ...
});

安全说明：对于不同环境（dev、staging、prod），请遵循 AWS 安全支柱最佳实践，使用独立的 AWS 账户，而不是依赖在单个账户内命名资源。账户级隔离可以提供更强的安全边界。

Lambda 函数开发

根据运行时使用适当的 Lambda 构造：

TypeScript/JavaScript：使用 @aws-cdk/aws-lambda-nodejs

import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';

new NodejsFunction(this, 'MyFunction', {
  entry: 'lambda/handler.ts',
  handler: 'handler',
  // Automatically handles bundling, dependencies, and transpilation
});

Python：使用 @aws-cdk/aws-lambda-python

import { PythonFunction } from '@aws-cdk/aws-lambda-python-alpha';

new PythonFunction(this, 'MyFunction', {
  entry: 'lambda',
  index: 'handler.py',
  handler: 'handler',
  // Automatically handles dependencies and packaging
});

优点：

• 自动打包并管理依赖项
• 自动处理转译
• 无需手动打包
• 部署模式一致

部署前验证

采用多层验证策略，全面检查 CDK 质量：

第 1 层：IDE 实时反馈（推荐）

对于 TypeScript/JavaScript 项目：

安装 cdk-nag，以便在合成时进行验证：

npm install --save-dev cdk-nag

将以下内容添加到 CDK 应用中：

import { Aspects } from 'aws-cdk-lib';
import { AwsSolutionsChecks } from 'cdk-nag';

const app = new App();
Aspects.of(app).add(new AwsSolutionsChecks());

可选——VS Code 用户：安装 CDK NAG Validator 扩展，以便在保存文件时更快获得反馈。

对于 Python/Java/C#/Go 项目：cdk-nag 支持所有 CDK 语言，并提供相同的合成时验证。

第 2 层：合成时验证（必需）

1. 使用 cdk-nag 进行合成：使用全面的规则验证堆栈

   cdk synth  # cdk-nag runs automatically via Aspects
   

2. 通过记录原因的方式抑制合理的例外：

   import { NagSuppressions } from 'cdk-nag';
   
   // Document WHY the exception is needed
   NagSuppressions.addResourceSuppressions(resource, [
     {
       id: 'AwsSolutions-L1',
       reason: 'Lambda@Edge requires specific runtime for CloudFront compatibility'
     }
   ]);
   

第 3 层：提交前安全网

1. 构建：确保编译成功

   npm run build  # or language-specific build command
   

2. 测试：运行单元测试和集成测试

   npm test  # or pytest, mvn test, etc.
   

3. 验证脚本：元级检查

   ./scripts/validate-stack.sh
   

验证脚本现在重点检查：

• 语言检测
• 模板大小和资源数量分析
• 合成成功验证
• （注意：详细的反模式检查由 cdk-nag 处理）

工作流指南

开发工作流

1. 设计：规划基础设施资源及其关系
2. 验证 AWS 服务：使用 AWS Documentation MCP 确认服务可用性和功能
   • 检查所有必需服务在各区域的可用性
   • 验证服务限制和配额
   • 确认最新的 API 规范
3. 实现：遵循最佳实践编写 CDK 构造
   • 使用 CDK MCP 服务获取构造建议
   • 通过 MCP 工具参考 CDK 最佳实践
4. 验证：运行部署前检查（见上文）
5. 合成：生成 CloudFormation 模板
6. 审查：检查合成的模板是否正确
7. 部署：部署到目标环境
8. 确认：确认资源已正确创建

堆栈组织

• 对于复杂应用，使用嵌套堆栈
• 将关注点划分到逻辑构造边界中
• 导出其他堆栈可能需要的值
• 使用 CDK 上下文进行特定环境的配置

测试策略

• 对单个构造进行单元测试
• 对堆栈合成进行集成测试
• 对 CloudFormation 模板进行快照测试
• 验证资源属性及其关系

有效使用 MCP 服务

何时使用 AWS Documentation MCP

实现前务必验证：

• AWS 服务的新功能或配置
• 服务在目标区域的可用性
• API 参数规范
• 服务限制和配额
• AWS 服务的安全最佳实践

示例场景：

• “检查 Lambda 是否支持 Python 3.13 运行时”
• “验证 DynamoDB 是否在 eu-south-2 区域可用”
• “当前 Lambda 超时限制是多少？”
• “获取最新的 S3 加密选项”

何时使用 CDK MCP 服务

利用它获取 CDK 专属指导：

• CDK 构造的选择和使用
• CDK API 参数选项
• CDK 最佳实践模式
• 构造属性配置
• CDK 专属优化

示例场景：

• “API Gateway REST API 推荐使用哪个 CDK 构造？”
• “如何配置 NodejsFunction 打包选项？”
• “CDK 堆栈组织的最佳实践”
• “用于自动扩缩 DynamoDB 的 CDK 构造”

MCP 使用最佳实践

1. 先验证：实现新功能前，务必先检查 AWS Documentation MCP
2. 区域验证：检查服务在目标部署区域的可用性
3. CDK 指导：使用 CDK MCP 获取构造专属建议
4. 保持最新：MCP 服务提供超出知识截止时间的最新信息
5. 结合来源：结合使用技能模式和 MCP 服务，获取全面指导

CDK 模式参考

有关详细的 CDK 模式、反模式和架构指导，请参阅完整参考文档：

文件：references/cdk-patterns.md

此参考文档包括：

• 常见 CDK 模式及其使用场景
• 应避免的反模式
• 安全最佳实践
• 成本优化策略
• 性能注意事项

其他资源

• 验证脚本：scripts/validate-stack.sh - 部署前验证
• CDK 模式：references/cdk-patterns.md - 详细模式库
• AWS Documentation MCP：已集成，可获取最新 AWS 信息
• CDK MCP 服务：已集成，可获取 CDK 专属指导

GitHub Actions 集成

当仓库中存在 GitHub Actions 工作流文件时，请确保提交前 .github/workflows/ 中定义的所有检查均通过。这有助于避免 CI/CD 失败并维持代码质量标准。