AWS SST 开发

aws-sst-development
分类编程
作者Agentic Awesome Skills 社区
许可MIT
评分4.40/5
使用14.4K

SST v4 for AWS

使用场景

当你需要 SST v4 (Ion) 专家来使用基于 Pulumi 的框架将 AWS 资源作为代码管理时，请使用此技能。具体场景包括：编写或编辑 sst.config.ts、构建 infra/ 模块（如 sst.aws.Function/Bucket/Dynamo/Cron/Service/Router、sst.Secret、sst.Linkable 以及原始的 aws.* Pulumi 资源）、配置资源链接等。

SST v4（"Ion" 引擎）是一个基于 Pulumi 的 IaC 框架：你使用 TypeScript 描述 AWS 资源，由 SST/Pulumi 将其同步到你的账户中。它提供了高级的 sst.aws.* 组件（Function, Bucket, Dynamo, Cron, Service 等），这些组件会扩展为多个底层资源；同时它也提供了一个“逃生口”，允许你使用任何原始的 Pulumi aws.* 资源来处理长尾需求。本技能涵盖了一套经过生产验证的在 AWS 上编写、链接、测试、部署和排查 SST 堆栈的方法——这些方法提炼自真实的跨堆栈项目，且每个经验都由生产事故换来。

SST 和 Pulumi 是第三方工具 —— 当你不确定组件选项时，请通过 Context7 验证当前语法（resolve-library-id $\rightarrow$ query-docs 查询 sst 或 pulumi-aws）。验证 AWS 侧的事实（服务配额、模型 ID、IAM 操作名称、区域可用性）时，请始终使用 AWS 文档 MCP，不要凭记忆操作。这里的模式是“如何做” (*how*)，而文档定义了“是什么” (*what*)。

被调用时的操作

确定你当前所处的模式并跳转到相应的参考文档：

| 场景 | 跳转至 |
|-----------|-------|
| 新项目，或向现有 SST 应用添加资源/模块 | Author $\rightarrow$ references/authoring.md |
| 将一个模块的输出连接到另一个模块（链接、SSM、IAM 范围） | Author $\rightarrow$ references/authoring.md § Sharing |
| 为基础设施编写测试，以防止变更导致静默失效 | Test $\rightarrow$ references/testing.md |
| 执行部署，或部署刚刚失败 | Deploy/Operate $\rightarrow$ references/deploy-and-troubleshoot.md |
| 在 Pulumi 类型之间迁移资源，或重命名物理名称 | Deploy/Operate $\rightarrow$ references/deploy-and-troubleshoot.md § Migrations |

在编辑之前请务必阅读相关参考文档 —— 它们包含了每条规则背后的“原因” (*why*)，而这比规则本身更重要。

快速上手：在操作前阅读仓库

SST 项目虽然有约定俗成的结构，但并非完全相同。在编辑之前，请快速梳理项目地图，确保你的更改符合项目风格而非与其冲突：

1. sst.config.ts —— 包含应用名称、home、提供商/区域、defaultTags、任何全局 $transform（Node 运行时锁定、bundle 修复），以及 run() 导入 infra/ 模块的顺序。导入顺序即为依赖顺序，请务必遵守。
2. infra/ —— 每个领域一个文件（存储、函数、API、可观测性……）。这里是声明资源的地方。检查是否存在 infra/CLAUDE.md —— 这些项目通常将 IaC 特定的规则记录在该文件中，它是最值得优先阅读的文件。
3. infra/tests/
— 源代码级的 Vitest 断言，用于固定资源不变性。如果存在此类断言，你的更改必须确保其通过，且可能需要添加新的断言。
4. package.json / .nvmrc — 包管理器（npm vs pnpm）、Node 版本以及实际安装的 sst/pulumi 版本。

运行 npx sst version 以确认你使用的是 v4/Ion（特征为 $config + .sst/platform/）。v2/v3（"SST Classic"，基于 CDK）是不同的框架 —— 这些模式不适用于该版本。

约定：通用原则 vs 可调参数

本技能所基于的项目遵循一套刻意设计的内部风格。其中一部分是通用的（适用于任何 SST v4 + AWS 项目 —— 请全面应用）；另一部分是项目特定的（这些项目选择的合理默认值 —— 为了保持一致性请采用，但需意识到不同项目可能会有所不同）。

通用原则 —— 适用于任何 SST v4 + AWS 项目：

  • 在单一位置刻意控制 Node 运行时。 不要依赖于安装的 SST 默认版本。惯用法是在 run() 中使用单个全局 $transform(sst.aws.Function, (args) => { args.runtime ??= "nodejs24.x" }) —— 这里使用 ??= 是正确的（transform 在组件应用其自身默认值之前运行，因此仅在用户未设置时填充）。最近的 SST 已经默认使用当前的 Node 运行时，因此请先检查安装的默认值（Context7）；该 transform 是版本独立性的保险，可防止未来的 SST 降级静默地更改你的集群。参见 references/authoring.md。
  • 绝不要将 Pulumi 的 Output<T> 插值到普通的 JS 模板字符串中。** 请使用 $interpolate（或 pulumi.interpolate）。直接使用顶层 ` ${bucket.arn}/* 会将 Output 字符串化为 [Output<T>] 占位符，从而产生一个错误的 ARN，且仅在部署时报错（类型检查和 sst dev 运行均正常）。解决方法是使用 $interpolate​ ${bucket.arn}/* 。这曾导致生产环境部署中断。参见 references/authoring.md § Outputs。
  • **在 Pulumi *类型* 之间迁移资源时，默认应分为两个 PR —— Pulumi 采用“先创建后销毁”策略，因此对于具有唯一性约束的 AWS 名称（如 bucket、IAM 角色、网关），旧资源仍持有该名称，导致创建时抛出 ConflictException。两次连续部署（先拆除，再重建）是保守的默认方案；在某些情况下，可以使用 aliases: / pulumi import / 状态手术来衔接身份，但这必须经过方案评审。参见 references/deploy-and-troubleshoot.md § Migrations。
  • 优先使用强类型的 sst.aws.* / aws.* 资源，而非 aws.cloudcontrol.Resource 逃生口。 CloudControl 的输出是字符串类型的，且 oneOf 字段无法干净地打补丁。仅在尚无强类型资源可用时使用，并在强类型资源发布后及时迁移。

项目特定默认值 —— 为保持一致性而采用，但请根据具体仓库确认：

  • 区域 ap-northeast-1，home: "aws"，以及携带 Project / Stage / ManagedBy: "sst" 的 defaultTags。
  • 基于 Stage 的生命周期管理：removal: stage === "prod" ? "retain" : "remove" 和 protect: stage === "prod"，确保生产资源在堆栈拆除时得以保留，而非生产环境的预览资源能被清理。
  • 将 SSM Parameter Store 作为图外契约**，采用 /{app}/{stage}/{domain}/... 前缀 —— 用于不在 Pulumi 图中的消费者（CI 脚本、兄弟应用、运维人员）。对于*同一应用*内的 Lambda，优先使用 SST link:（它会建立真实的依赖边并授予 IAM 权限）；不要将同一应用的共享路由通过...
哎，SSM。参见 references/authoring.md 的 “Sharing” 章节。
  • 在 run() 内部使用延迟 await import("./infra/<module>")，以保持 sst dev 热重载的轻量化。（在测试时，除非被包裹在工厂函数中，否则模块导出仍会运行其顶层的 new sst.aws.* —— 详见 references/testing.md 关于如何测试基础设施的内容。）
  • 针对每个基础设施模块进行源码级 Vitest 测试 —— 这是一种轻量级的、项目风格的回归网，用于断言*源代码文本*（资源名称、索引形状、IAM 范围）。这是一个刻意的选择，而非 SST 的限制：当模块包含实际逻辑时，Pulumi *确实* 支持运行时 Mock (@pulumi/pulumi/runtime) 来进行行为图测试。源码断言不能替代“预览部署 + 冒烟测试”。参见 references/testing.md。
  • 可观测性门禁：每个新增的 Lambda/队列/定时任务在合并前必须配置告警和结构化日志。是否强制执行取决于具体项目，但这是一种低成本的保险。参见 references/deploy-and-troubleshoot.md 的 “Observability” 章节。

在引入约定（Convention）时，请说明其适用范围（例如“这是通用约定”或“符合本仓库的项目风格”），以便用户能有意识地覆盖项目特定约定。

工作节奏

1. 定向（见上文）—— 梳理配置、模块、测试和工具链。
2. 验证语法 —— 若有不明确之处，使用 Context7 / AWS 文档 MCP。不要猜测组件的选项名称。
3. 编写 —— 遵循 references/authoring.md 编写资源/模块。匹配周围文件的注释密度和命名风格 —— 这些项目非常注重注释“为什么”，在大量注释的文件中写一行简短的注释会被视为质量退化。
4. 测试 —— 添加或更新源码级断言 (references/testing.md) 并运行 npx vitest（或仓库的 test 脚本）。运行 npx sst diff 和/或 tsc --noEmit，在部署前拦截类型错误和计划错误。
5. 部署/运维 —— 遵循 references/deploy-and-troubleshoot.md。在执行任何 sst deploy 之前，通过 aws sts get-caller-identity 确认目标账户。
6. 清理 —— 清理所有导出的状态文件 —— 它们包含账户 ID 和 ARN，不得留在 /tmp 或聊天记录中。

优秀标准的定义

  • 变更是在正确的 infra/ 模块中满足需求的最小 diff，并按依赖顺序接入 run()。
  • 每个 Lambda 通过全局转换获得正确的运行时（除非有意偏离，例如 Python 函数，否则不手动设置 runtime）。
  • 跨资源引用使用 link:（图内）和/或 $interpolate 范围的 IAM；供其他工具消费的输出发布到带有 stage 前缀的 SSM 中。
  • 新基础设施配有相应的源码级测试，且现有测试套件保持通过（green）。
  • 通过文档 MCP 确认 AWS 侧事实，通过 Context7 确认 SST/Pulumi 语法，而非依赖记忆。
  • 任何不可逆操作（部署、sst remove`、资源类型迁移）均已向用户标明目标账户，且迁移计划分为两个 PR 而非一个。

局限性

  • 仅在任务明确匹配其上游来源和本地项目上下文时使用此技能。
  • 在应用变更前，验证命令、生成的代码、依赖项、凭据以及外部服务的行为。
  • 不要将示例视为环境特定测试、安全审查或破坏性/高成本操作用户审批的替代方案。