我们如何将 AWS Amplify GraphQL 后端迁移到 CDK（无需重写）

Source: Dev.to

我们如何在不重写业务逻辑的情况下从 Amplify 迁移到 CDK，为什么这么做，以及我们学到了什么。

注意： 这并不是一篇反 Amplify 的文章。它旨在了解 Amplify 的优势所在——以及它何时不再具备可扩展性。

当 Amplify 表现良好时

Amplify 是一个很好的选择，当：

• 项目还处于早期阶段。
• 需要快速、基于 schema 的开发。
• 对 Amplify 管理的 CloudFormation 感到满意。
• 不需要细粒度的 IAM 或自定义流水线。

我们在项目起始阶段正是这样使用 Amplify 的。通过 @model、@auth 和连接等指令，Amplify 生成了：

• 一个 AppSync GraphQL API
• DynamoDB 表
• VTL 解析器
• IAM 角色
• Lambda 数据源（在需要时）

在很长一段时间里，这一切都运行得非常完美。

Source: …

我们最终遇到的问题

随着后端的增长，出现了一些越来越难以忽视的问题。

1. 控制和可视性受限

Amplify 抽象了大量基础设施：

• IAM 权限自动生成。
• CloudFormation 堆栈被隐藏。
• 资源命名不透明。

这导致：

• 代码审查更困难
• 安全审查变得痛苦
• 调试部署变得困难

2. 多环境与平台集成困难

我们的需求是：

• 明确的 dev / staging / prod 环境
• 与已有的基于 CDK 的平台集成
• 可预测的差异（diff）和回滚

Amplify 的 CLI 驱动工作流难以满足这些要求。

3. 严格的 CloudFormation 扩展限制

AWS CloudFormation 对每个堆栈强制限制为 500 个资源。
Amplify 将大多数 GraphQL 后端部署到一个（或极少数）堆栈中。随着 schema 的增长，生成的资源数量会迅速逼近该限制：

• 解析器（Resolvers）
• 函数（Functions）
• IAM 角色和策略
• DynamoDB 表及全局二级索引（GSIs）

当接近 500 资源的限制时：

• 部署变得脆弱
• 添加新模型或解析器可能失败
• Amplify 没有提供受支持的方式来拆分或重构生成的堆栈

此时，后端的演进基本停滞。

为什么我们没有重写所有内容

当我们遇到这些限制时，我们已经拥有：

• 大型 GraphQL 架构
• 自定义 VTL 解析器
• 基于 Lambda 的业务逻辑
• DynamoDB 中的生产数据

完整重写将会是：

• 有风险
• 耗时
• 没必要

相反，我们提出了另一个问题：

如果 Amplify 只用于生成初始产物，而不是永远拥有后端，会怎样？

Source: …

迁移步骤

第 1 步 – 将 Amplify 仅用作脚手架工具

把 Amplify 当作 编译器，而 CDK 成为 部署引擎。
Amplify 生成了：

• schema.graphql
• .vtl 解析器模板
• 构建产物：
  • build/cloudformation-template.json
  • build/stacks/*.json
  • build/resolvers/*.vtl
• 嵌入解析器中的认证逻辑

在此阶段 Amplify 完成了它的工作。

第 2 步 – 提取持久化资产

从 Amplify 后端输出中我们仅保留了持久且有价值的部分：

• GraphQL 架构
• 解析器模板
• 表定义
• 认证规则与逻辑

我们 没有 保留：

• Amplify CLI 文件
• Amplify Console 配置
• 自动生成的 CloudFormation 堆栈

这些属于实现细节，而非架构本身。

第 3 步 – 在 AWS CDK 中显式重建

每个 Amplify 生成的资源都在 CDK 中显式重新实现。CDK 现在负责：

• AppSync API + 数据源
• 函数配置
• 流水线解析器
• IAM 角色 / 策略
• DynamoDB 表（可选）
• Lambda 数据源（可选）

我们不再直接部署 Amplify 堆栈，而是把意图抽取到 CDK 代码中并从那里重新部署。这消除了 Amplify 的“魔法”，使行为可预测。

第 4 步 – 将后端拆分为多个 CDK 堆栈

不同于 Amplify 的单体堆栈，CDK 让我们能够：

• 将 AppSync、DynamoDB、Lambda 和 IAM 拆分到独立堆栈
• 控制资源边界
• 完全规避 CloudFormation 的 500‑资源限制

这一次性改动消除了一个长期的可扩展性风险。

第 5 步 – 基于配置、感知环境的设计

我们用以下方式取代了 CLI 驱动的配置：

• 基于 YAML 的配置文件
• 环境特定的定义（dev、staging、prod）
• 确定性的命名

现在可以通过 cdk diff 获得可审查的差异：

cdk diff -c env=staging
cdk deploy -c env=staging

CDK 成为唯一的 事实真相来源。

第 6 步 – 完全移除 Amplify

在确认功能等价后：

• 删除 Amplify 项目
• 断开 Amplify Console 连接
• 不再使用 amplify push

此后：

• 基础设施变更通过代码审查
• 部署可预测
• 扩展不再受堆栈限制的约束

我们学到的

• Amplify 在 scaffolding 方面表现出色。
• 它并非为 large, long‑lived backends 设计。
• CloudFormation 的 500‑resource 限制是一个真实的约束。
• 迁移比完全重写更安全。
• 明确的 CDK 所有权在大规模时能快速收获回报。

想要完整的设置？

我们已将此方案打包成可复用的 bundle，包含：

• 生产级 CDK AppSync 后端
• 基于配置的 resolver 和 Lambda 实现
• 示例 CI/CD 流水线

👉 在 GitHub 上获取仓库

如果遇到任何问题，欢迎提交 issue 或 PR！

bda wiring

• 迁移清单和深得的经验教训
• 真实案例（非玩具演示）

👉 Gumroad:

最后思考

这次迁移并不是在否定 Amplify，而是要在合适的阶段使用合适的工具。

• Amplify 在早期帮助我们快速前进。
• CDK 在规模化时帮助我们安全前进。

如果你也正面临相同的限制，有一个干净的退出方式——无需重写。