aws-blocks

AWS Blocks 应用开发

软件包命名： 所有软件包均以 @aws-blocks 为作用域发布（例如：@aws-blocks/core、@aws-blocks/blocks、@aws-blocks/bb-kv-store）。

概述

AWS Blocks 是一个「基础设施即代码」框架，其中构建块将 CDK、SDK 和本地模拟整合为一个 API。它提供 18 多个构建块，涵盖存储、身份验证、实时通信、后台任务、文件管理、AI/搜索、电子邮件和可观测性，且均可在本地运行，无需 AWS 凭证。

主要特点：

• 一个 aws-blocks/ 目录即可定义整个后端
• 前端导入具有完整类型，无需生成客户端
• 所有构建块均可在本地运行，无需 AWS（模拟数据持久化到 .bb-data/）
• 使用最小权限凭证，通过 npm run sandbox 部署临时的独立测试环境，并通过 npm run deploy 部署长期运行的环境

搭建新项目

npx @aws-blocks/create-blocks-app my-app
cd my-app

将 AWS Blocks 添加到现有项目：

npx @aws-blocks/create-blocks-app .

此命令会检测现有项目，并在代码旁添加一个 aws-blocks/ 工作区。

将 AWS Blocks 添加到 Amplify Gen 2 项目：

npx @aws-blocks/create-blocks-app .

当 CLI 检测到 amplify/backend.ts 时，会自动将 AWS Blocks 集成到 Amplify 后端。

使用指定模板：

npx @aws-blocks/create-blocks-app my-app --template demo
cd my-app

可用模板

模板	描述
default	基于 Vite + lit-html 的入门应用，包含基本身份验证、数据持久化和实时功能，帮助演示基本的应用架构和模式（未指定 --template 时使用）
bare	基于 Vite + lit-html 的入门项目，仅包含一个「hello world」API 方法和精简的前端
react	基于 React + Vite 的入门项目，包含一个 API 端点和带类型的 React 前端
backend	仅包含后端，不含前端；仅提供带一个端点的 AWS Blocks API
demo	Todo 应用，包含 AuthBasic、KVStore、DistributedTable、Zod 模式、索引以及受身份验证保护的 CRUD 操作
auth-cognito	完整的 AuthCognito 无密码电子邮件 OTP，包含角色、设备管理和 Authenticator UI
nextjs	基于 Next.js + React 的入门项目，集成 AWS Blocks 后端（SSR + Server Components）

开发工作流

搭建完成后，请参阅 node_modules/@aws-blocks/blocks/README.md，了解完整的开发工作流，包括：

• 核心概念（架构、构建块选择）
• 项目结构和 Scope 组织
• 错误处理模式
• 模式验证
• 本地开发
• 最佳实践和常见错误
• 部署 IAM 角色设置和安全指南

实现特定构建块时，请阅读其软件包 README，了解详细的 API 参考（例如：node_modules/@aws-blocks/bb-kv-store/README.md）。这些文档是与你安装的版本对应的权威文档。

安全注意事项

• 对所有不应公开的方法使用 await auth.requireAuth(context)——ApiNamespace 方法默认未经身份验证
• 使用 new AppSetting(scope, id, { secret: true }) 存储 API 密钥和凭据——绝不要将其硬编码或使用 .env 文件
• 为接受用户数据的 KVStore/AppSetting 始终附加架构——RPC 层会验证结构，但不会验证业务逻辑
• 不要添加宽泛的 * IAM 策略——每个 Building Block 都已针对自身资源授予最小权限
• 绝不要更改 FileBucket 上的 blockPublicAccess——应改用 CloudFront 提供公共文件
• 在生产环境中明确配置 CORS_ALLOWED_ORIGINS——避免使用通配符
• 对于跨域部署，在身份验证构造函数中传入 crossDomain: true（启用 SameSite=None; Secure; Partitioned）
• 在 Hosting 上启用 monitoring: { enabled: true, snsTopicArn: '...' }，以接收生产环境告警
• 对于面向公众的应用，通过 CDK 添加 WAF 和 API Gateway 限流——默认不包含这些配置
• Logger 可确保序列化安全（循环引用、类型强制转换），但不会对敏感内容进行脱敏——绝不要将原始凭据、令牌或密钥传递给 Logger 方法；记录日志前应先清理上下文对象