aws-cdk-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AWS CDK Development

AWS CDK 开发

This skill provides comprehensive guidance for developing AWS infrastructure using the Cloud Development Kit (CDK), with integrated MCP servers for accessing latest AWS knowledge and CDK utilities.

本技能为使用Cloud Development Kit (CDK)开发AWS基础设施提供全面指导，并集成了MCP服务器以获取最新的AWS知识和CDK实用工具。

AWS Documentation Requirement

AWS 文档要求

CRITICAL: This skill requires AWS MCP tools for accurate, up-to-date AWS information.

CRITICAL：本技能需要AWS MCP工具来获取准确、最新的AWS相关信息。

Before Answering AWS Questions

回答AWS问题之前

Always verify using AWS MCP tools (if available):

mcp__aws-mcp__aws___search_documentation

mcp__*awsdocs*__aws___search_documentation

- Search AWS docs

mcp__aws-mcp__aws___read_documentation

mcp__*awsdocs*__aws___read_documentation

- Read specific pages

mcp__aws-mcp__aws___get_regional_availability

- Check service availability

If AWS MCP tools are unavailable:
- Guide user to configure AWS MCP using the
```
aws-mcp-setup
```
  skill (auto-loaded as dependency)
- Help determine which option fits their environment:
  - Has uvx + AWS credentials → Full AWS MCP Server
  - No Python/credentials → AWS Documentation MCP (no auth)
- If cannot determine → Ask user which option to use

务必验证（如果可用）：

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

- 检查服务可用性

如果AWS MCP工具不可用：
- 引导用户使用
```
aws-mcp-setup
```
  技能配置AWS MCP（作为依赖项自动加载）
- 帮助确定适合其环境的选项：
  - 拥有uvx + AWS凭证 → 完整AWS MCP Server
  - 无Python/凭证 → AWS Documentation MCP（无需认证）
- 若无法确定 → 询问用户使用哪个选项

Integrated MCP Servers

集成MCP服务器

This skill includes the CDK MCP server automatically configured with the plugin:

本技能包含自动配置了插件的CDK MCP服务器：

AWS CDK MCP Server

When to use: For CDK-specific guidance and utilities

Get CDK construct recommendations
Retrieve CDK best practices
Access CDK pattern suggestions
Validate CDK configurations
Get help with CDK-specific APIs

Important: Leverage this server for CDK construct guidance and advanced CDK operations.

适用场景：获取CDK特定指导和实用工具

获取CDK构造建议
检索CDK最佳实践
获取CDK模式建议
验证CDK配置
获取CDK特定API相关帮助

重要提示：在获取CDK构造指导和执行高级CDK操作时，请利用此服务器。

When to Use This Skill

何时使用本技能

Use this skill when:

Creating new CDK stacks or constructs
Refactoring existing CDK infrastructure
Implementing Lambda functions within CDK
Following AWS CDK best practices
Validating CDK stack configurations before deployment
Verifying AWS service capabilities and regional availability

在以下场景使用本技能：

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

Core CDK Principles

核心CDK原则

Resource Naming

资源命名

CRITICAL: Do NOT explicitly specify resource names when they are optional in CDK constructs.

Why: CDK-generated names enable:

Reusable patterns: Deploy the same construct/pattern multiple times without conflicts
Parallel deployments: Multiple stacks can deploy simultaneously in the same region
Cleaner shared logic: Patterns and shared code can be initialized multiple times without name collision
Stack isolation: Each stack gets uniquely identified resources automatically

Pattern: Let CDK generate unique names automatically using CloudFormation's naming mechanism.

typescript

// ❌ 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
  // ...
});

Security Note: For different environments (dev, staging, prod), follow AWS Security Pillar best practices by using separate AWS accounts rather than relying on resource naming within a single account. Account-level isolation provides stronger security boundaries.

CRITICAL：当CDK构造中资源名称为可选项时，请勿显式指定资源名称。

原因：CDK生成的名称支持：

可复用模式：无需冲突即可多次部署相同的构造/模式
并行部署：多个堆栈可同时在同一区域部署
更简洁的共享逻辑：模式和共享代码可多次初始化而不会出现名称冲突
堆栈隔离：每个堆栈会自动获得唯一标识的资源

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

typescript

// ❌ 错误示例 - 显式命名会影响可复用性和并行部署
new lambda.Function(this, 'MyFunction', {
  functionName: 'my-lambda',  // 避免这种写法
  // ...
});

// ✅ 正确示例 - 让CDK自动生成唯一名称
new lambda.Function(this, 'MyFunction', {
  // 未指定functionName - CDK会生成：StackName-MyFunctionXXXXXX
  // ...
});

安全提示：针对不同环境（开发、预发布、生产），请遵循AWS安全支柱最佳实践，使用独立的AWS账户，而非依赖单账户内的资源命名。账户级隔离能提供更强的安全边界。

Lambda Function Development

Lambda函数开发

Use the appropriate Lambda construct based on runtime:

TypeScript/JavaScript: Use

@aws-cdk/aws-lambda-nodejs

typescript

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: Use

@aws-cdk/aws-lambda-python

typescript

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
});

Benefits:

Automatic bundling and dependency management
Transpilation handled automatically
No manual packaging required
Consistent deployment patterns

根据运行时选择合适的Lambda构造：

TypeScript/JavaScript：使用

@aws-cdk/aws-lambda-nodejs

typescript

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

new NodejsFunction(this, 'MyFunction', {
  entry: 'lambda/handler.ts',
  handler: 'handler',
  // 自动处理打包、依赖项和转译
});

Python：使用

@aws-cdk/aws-lambda-python

typescript

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

new PythonFunction(this, 'MyFunction', {
  entry: 'lambda',
  index: 'handler.py',
  handler: 'handler',
  // 自动处理依赖项和打包
});

优势：

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

Pre-Deployment Validation

部署前验证

Use a multi-layer validation strategy for comprehensive CDK quality checks:

使用多层验证策略进行全面的CDK质量检查：

Layer 1: Real-Time IDE Feedback (Recommended)

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

For TypeScript/JavaScript projects:

Install cdk-nag for synthesis-time validation:

bash

npm install --save-dev cdk-nag

Add to your CDK app:

typescript

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

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

Optional - VS Code users: Install CDK NAG Validator extension for faster feedback on file save.

For Python/Java/C#/Go projects: cdk-nag is available in all CDK languages and provides the same synthesis-time validation.

针对TypeScript/JavaScript项目：

安装cdk-nag进行合成时验证：

bash

npm install --save-dev cdk-nag

将其添加到CDK应用中：

typescript

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语言，并提供相同的合成时验证。

Layer 2: Synthesis-Time Validation (Required)

第二层：合成时验证（必填）

Synthesis with cdk-nag: Validate stack with comprehensive rules
bash
```
cdk synth  # cdk-nag runs automatically via Aspects
```

Suppress legitimate exceptions with documented reasons:

typescript

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'
  }
]);

使用cdk-nag进行合成：通过全面规则验证堆栈
bash
```
cdk synth  # cdk-nag会通过Aspects自动运行
```

记录原因后抑制合理异常：

typescript

import { NagSuppressions } from 'cdk-nag';

// 记录为何需要该异常
NagSuppressions.addResourceSuppressions(resource, [
  {
    id: 'AwsSolutions-L1',
    reason: 'Lambda@Edge需要特定运行时以兼容CloudFront'
  }
]);

Layer 3: Pre-Commit Safety Net

第三层：提交前安全保障

Build: Ensure compilation succeeds

bash

npm run build  # or language-specific build command

Tests: Run unit and integration tests
bash
```
npm test  # or pytest, mvn test, etc.
```
Validation Script: Meta-level checks
bash
```
./scripts/validate-stack.sh
```

The validation script now focuses on:

Language detection
Template size and resource count analysis
Synthesis success verification
(Note: Detailed anti-pattern checks are handled by cdk-nag)

构建：确保编译成功

bash

npm run build  # 或对应语言的构建命令

测试：运行单元测试和集成测试
bash
```
npm test  # 或pytest、mvn test等
```
验证脚本：元级检查
bash
```
./scripts/validate-stack.sh
```

验证脚本现在重点关注：

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

Workflow Guidelines

工作流指南

Development Workflow

开发工作流

Design: Plan infrastructure resources and relationships
Verify AWS Services: Use AWS Documentation MCP to confirm service availability and features
- Check regional availability for all required services
- Verify service limits and quotas
- Confirm latest API specifications
Implement: Write CDK constructs following best practices
- Use CDK MCP server for construct recommendations
- Reference CDK best practices via MCP tools
Validate: Run pre-deployment checks (see above)
Synthesize: Generate CloudFormation templates
Review: Examine synthesized templates for correctness
Deploy: Deploy to target environment
Verify: Confirm resources are created correctly

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

Stack Organization

堆栈组织

Use nested stacks for complex applications
Separate concerns into logical construct boundaries
Export values that other stacks may need
Use CDK context for environment-specific configuration

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

Testing Strategy

测试策略

Unit test individual constructs
Integration test stack synthesis
Snapshot test CloudFormation templates
Validate resource properties and relationships

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

Using MCP Servers Effectively

有效使用MCP服务器

When to Use AWS Documentation MCP

何时使用AWS Documentation MCP

Always verify before implementing:

New AWS service features or configurations
Service availability in target regions
API parameter specifications
Service limits and quotas
Security best practices for AWS services

Example scenarios:

"Check if Lambda supports Python 3.13 runtime"
"Verify DynamoDB is available in eu-south-2"
"What are the current Lambda timeout limits?"
"Get latest S3 encryption options"

实现前务必验证：

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

示例场景：

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

When to Use CDK MCP Server

何时使用CDK MCP Server

Leverage for CDK-specific guidance:

CDK construct selection and usage
CDK API parameter options
CDK best practice patterns
Construct property configurations
CDK-specific optimizations

Example scenarios:

"What's the recommended CDK construct for API Gateway REST API?"
"How to configure NodejsFunction bundling options?"
"Best practices for CDK stack organization"
"CDK construct for DynamoDB with auto-scaling"

用于获取CDK特定指导：

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

示例场景：

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

MCP Usage Best Practices

MCP使用最佳实践

Verify First: Always check AWS Documentation MCP before implementing new features
Regional Validation: Check service availability in target deployment regions
CDK Guidance: Use CDK MCP for construct-specific recommendations
Stay Current: MCP servers provide latest information beyond knowledge cutoff
Combine Sources: Use both skill patterns and MCP servers for comprehensive guidance

先验证：在实现新功能前，务必先检查AWS Documentation MCP
区域验证：检查目标部署区域的服务可用性
CDK指导：使用CDK MCP获取构造特定建议
保持更新：MCP服务器提供知识截止日期之后的最新信息
结合来源：同时使用技能模式和MCP服务器获取全面指导

CDK Patterns Reference

CDK模式参考

For detailed CDK patterns, anti-patterns, and architectural guidance, refer to the comprehensive reference:

File:

references/cdk-patterns.md

This reference includes:

Common CDK patterns and their use cases
Anti-patterns to avoid
Security best practices
Cost optimization strategies
Performance considerations

如需详细的CDK模式、反模式和架构指导，请参考综合参考文档：

文件：

references/cdk-patterns.md

该参考文档包含：

常见CDK模式及其用例
需要避免的反模式
安全最佳实践
成本优化策略
性能考量

Additional Resources

其他资源

Validation Script:
```
scripts/validate-stack.sh
```
- Pre-deployment validation
CDK Patterns:
```
references/cdk-patterns.md
```
- Detailed pattern library
AWS Documentation MCP: Integrated for latest AWS information
CDK MCP Server: Integrated for CDK-specific guidance

验证脚本：
```
scripts/validate-stack.sh
```
- 部署前验证
CDK模式：
```
references/cdk-patterns.md
```
- 详细模式库
AWS Documentation MCP：集成以获取最新AWS信息
CDK MCP Server：集成以获取CDK特定指导

GitHub Actions Integration

GitHub Actions集成

When GitHub Actions workflow files exist in the repository, ensure all checks defined in

.github/workflows/

pass before committing. This prevents CI/CD failures and maintains code quality standards.

当仓库中存在GitHub Actions工作流文件时，提交前需确保

.github/workflows/

中定义的所有检查都已通过。这可以避免CI/CD失败并维持代码质量标准。