infrastructure-code-synthesis

AWS CDK 开发

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

AWS 文档要求

重要：本技能需要使用 AWS MCP 工具来获取准确且最新的 AWS 信息。

回答 AWS 问题之前

1. 始终使用 AWS MCP 工具进行验证（如果可用）：

   • mcp__aws-mcp__aws___search_documentation 或 mcp__*awsdocs*__aws___search_documentation - 搜索 AWS 文档
   • mcp__aws-mcp__aws___read_documentation 或 mcp__*awsdocs*__aws___read_documentation - 阅读特定页面
   • mcp__aws-mcp__aws___get_regional_availability - 检查服务可用性

2. 如果 AWS MCP 工具不可用：

   • 指引用户配置 AWS MCP：请参阅 AWS MCP 设置指南
   • 帮助判断哪种选项适合其环境：
     • 有 uvx 和 AWS 凭证 → 完整版 AWS MCP 服务
     • 没有 Python/凭证 → AWS Documentation 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 生成的名称可以：

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

模式：使用 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 失败，并维持代码质量标准。