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 工具不可用，请引导用户按照该技能的设置流程操作。

集成的 MCP 服务

此技能包含随插件自动配置的 CDK MCP 服务：

AWS CDK MCP 服务

使用场景：获取 CDK 专属指导和实用工具

• 获取 CDK 构造建议
• 查阅 CDK 最佳实践
• 获取 CDK 模式建议
• 验证 CDK 配置
• 获取 CDK 专属 API 的帮助

重要提示：使用此服务获取 CDK 构造指导并执行高级 CDK 操作。

何时使用此技能

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

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

CDK 核心原则

资源命名

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

原因：由 CDK 生成的名称可实现：

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

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

// ❌ 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 语言均支持 cdk-nag，可提供相同的合成时验证。

第 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 失败并维持代码质量标准。