AWS 块

将后端和前端一起写出——完全打入,可运行在笔记本电脑上,可部署到AWS不变.

AWS Blocks 是一个后端框架,由 建筑块:自装模块,每个模块捆绑一个 CCDK 构造,它的 AWS SDK 集成,和一个本地模拟. 您在一个目录中编译块,导出一个 API,然后用端到端的安全调用您的前端. 没有客户端生成,没有胶水代码,不需要启动AWS账户.

此套件 (@aws-blocks/blocks重新出口每个建筑块和核心原始物, 所以你从一个地方进口一切:

import { Scope, ApiNamespace, KVStore, AuthBasic } from '@aws-blocks/blocks';

• 类型安全, 结束到结束 ——前端直接调用后端方法;类型自动流出.
• 当地第一 ——每个区块都作为模拟模型运行,所以你用零云设置来构建和测试.
• 部署情况不变 —— 说 npm run sandbox 将模拟器换成真实的AWS服务(DynamoDB, Aurora, S3, Lambda...). 同样的代码.
• 低仪式,高天花板 ——常见的东西是一行;当你需要基础的CDK构造或者AWS SDK时,它就在那里.

快速启动

npx @aws-blocks/create-blocks-app my-app
cd my-app
npm run dev          # → http://localhost:3000  (mocks, no AWS account needed)

--template <name> 选择启动器( e)react, (中文(简体) ), nextjs, (中文(简体) ), backend见 @aws-blocks/create-blocks-app。 。 。 .

如何运作

你的整个后端 在一个目录中生活, aws-blocks/。您创建块,然后通过 ApiNamespace数字 :

// aws-blocks/index.ts
import { Scope, ApiNamespace, KVStore } from '@aws-blocks/blocks';

const scope = new Scope('my-app');
const store = new KVStore(scope, 'cache');

export const api = new ApiNamespace(scope, 'api', (context) => ({
  async getValue(key: string) {
    return await store.get(key);
  },
  async setValue(key: string, value: string) {
    await store.put(key, value);
  },
}));

前端导入的 API 并称之为本地函数—— 完全输入, 不获取, 没有客户端代码 :

// src/
import { api } from 'aws-blocks';

await api.setValue('greeting', 'hello');
const value = await api.getValue('greeting'); // typed: string | null

这就是整个模型: 定义块 = 导出 API = 在前端导入. 运输(JSON-RPC) /aws-blocks/api)是为你处理的,是故意隐形的.

添加认证和数据

块作曲. 以下为认证后设置的相同API门并辅以可查询表格:

// aws-blocks/index.ts
import { Scope, ApiNamespace, AuthBasic, DistributedTable } from '@aws-blocks/blocks';
import { z } from 'zod';

const scope = new Scope('my-app');

const auth = new AuthBasic(scope, 'auth', { passwordPolicy: { minLength: 8 } });

const notes = new DistributedTable(scope, 'notes', {
  schema: z.object({ userId: z.string(), noteId: z.string(), text: z.string() }),
  key: { partitionKey: 'userId', sortKey: 'noteId' },
});

// Sign-up / sign-in endpoints, ready to wire to the frontend
export const authApi = auth.createApi();

export const api = new ApiNamespace(scope, 'api', (context) => ({
  async addNote(text: string) {
    const user = await auth.requireAuth(context);          // 401s if not signed in
    const noteId = crypto.randomUUID();
    await notes.put({ userId: user.username, noteId, text });
    return { noteId };
  },
  async listNotes() {
    const user = await auth.requireAuth(context);
    return await Array.fromAsync(notes.query({ where: { userId: { equals: user.username } } }));
  },
}));

警卫: 每个 ApiNamespace 方法是一个公共互联网端点 默认无效通过调用打开一个方法 auth.requireAuth(context) (或 auth.requireRole(...)) 在顶上. 本地的嘲弄也无所作为——一种通俗的方法通过每一个本地的检查,仍然可以被任何人叫来的船只.

在前门, @aws-blocks/blocks/ui 给您一个提供者不可知的认证组件或驱动器 authApi 自己说:

import { Authenticator, onAuthChange } from '@aws-blocks/blocks/ui';
import { authApi, api } from 'aws-blocks';

document.body.append(Authenticator(authApi));
onAuthChange(authApi, (user) => {
  if (user) api.listNotes().then(render);
});

建筑块

从需要开始:

• 存储数据
  • 简单密钥 = 值(笼盖、旗帜、用户预览) = KVStore (bb-kv-store) (英语)
  • 有索引和查询的有结构的记录 DistributedTable (bb-分布式表格) - 大多数数据的默认值
  • 关系/SQL(合并、交易) 参见 选择数据块 下级
  • 文件、blobs、上传、静态资产 FileBucket (bb-file-bucket) (英语)
  • 单一配置值 AppSetting (bb-app-设定)
  • 高值证书( API 密钥、 OAuth 密钥、 连接字符串) ~ Secret (bb-secret),由AWS保密管理器支持
• 认证用户
  • 用户名/密码、原型/MVP AuthBasic (bb-auth-basic) (英语)
  • 认知用户库、外交部、团体 AuthCognito (bb-auth-cognitto) (英语)
  • 外部身份提供商(OIDC) AuthOIDC (bb-auth-oidc) (英语)
• 在请求/答复之外运行工作
  • 火灾和遗忘的背景工作 AsyncJob (bb -sync -job) (bb
  • 计划/经常性任务 CronJob (bb-cron-job) (英语)
• 向浏览器提供实时更新 (聊天、在场、仪表板) Realtime (bb-实时)
• 构建 AI 特性
  • 使用工具的代理 + 对话 + Agent (bb-agent) (英语)
  • 语义文档检索(RAG) KnowledgeBase (bb-知识基础)
• 发送交易邮件 → EmailClient (bb-电子邮件客户端)
• 执行原始 HTTP 端点 (网页接收器、健康检查、重新定向、非JSON反应) —— RawRoute (核心);其他一切经历 ApiNamespace 难民保护委员会
• 观察和操作
  • 结构化日志 + Logger (bb-logger) (英语)
  • 自定义衡量标准 Metrics (bb-meters) (英语)
  • 分布的痕迹 Tracer (bb-tracer) (英语)
  • 自动云表仪表板 Dashboard (bb-dashboard) (英语)

选择数据块

默认为 DistributedTable 用于您的数据模型,除非您的域特别需要 SQL 引擎能力.

当您需要过滤或加入多个相关记录的结果,在多个维度上过滤没有预设分级的模型,存储大对象,需要交易,或者需要NoSQL不提供的SQL的灵活性或熟悉度时,可以到达其中一个SQL块.

如果您需要 SQL , 请选择 DistributedDatabase aurora DSQL,即PostgreSQL线-protocol兼容;参见 Aurora DSQL SQL 兼容文档 用于支持的 SQL 特性。 使用 Database 特别是当你需要一个完整的(更昂贵) 具有行级安全,触发,程序,或PL/pgSQL功能的后置执行;大交易(超过3000行);或与已存在的Postgres数据库相整合. 注意它携带了至少0.5ACU的闲置成本,或者在从零缩放时冷却起步,这与其他两个区块不同.

建筑群文件

每一个建筑区都向内运送文件 @aws-blocks/blocks 软件包下 docs/<block>/: 每个 docs/<block>/ 文件夹包含该块 README.md附加时 API.md, (中文(简体) ), DESIGN.md,以及 CHANGELOG.md 这里 要读取它们, 请找到捆绑的文件夹 :

node -p "require('path').dirname(require.resolve('@aws-blocks/blocks/docs/README.md'))"

如果解析失败, 则返回到 node_modules/@aws-blocks/blocks/docs。该文件夹持有本指南(README.md),框架本身 API.md, (中文(简体) ), TROUBLESHOOTING.md,以及 CHANGELOG.md (版本历史——在排除出故障时读取),每个块外加一个子文件夹;下面的目录列出每个块.

地方发展和部署

部署需要AWS证书. npm run dev 完全本地化(无证书). npm run sandbox 财务报告和审定财务报表 npm run deploy 提供真实的AWS资源,因此首先配置证书——例如. aws login (AWS CLI 2.32.0或以后), aws configure sso + 键 aws sso login,或 aws configure (核查 aws sts get-caller-identity) (中文(简体) ). 如果证书缺失或过期,两个命令在合成之前都停止,并打印他们所使用的配置文件的签名或刷新命令。 使用 最低特权 证书范围为你们组群部署的服务——不广泛 Administrator 访问.

在他们部署之前, npm run sandbox 财务报告和审定财务报表 npm run deploy 打印部署目标:CDK所部署的(AWS配置文件、环境访问密钥或容器或网络身份证书)和所配置的区域。 和 CDK 一样, 环境访问密钥在之前被使用 AWS_PROFILE 除非 cdk.json 设置配置 。 持有有效证书后,还显示账户名称和AWS账户计划(免费或付费),如果这些证书允许的话 account:GetAccountInformation 财务报告和审定财务报表 freetier:GetAccountPlanState。否则它们会显示“无法使用”并继续使用;这些内容不会停止部署。 当您与 AWS 管理的新 AWS 注册体验角色( 路径上的角色) 签约时 /managed/ 那个 account-access.amazonaws.com 可以假设, 检查 iam:GetRole),产出也链接到 https://settings.aws.com/billing 用于限制开支。 在 AWS 设置中,在查看或更改其支出限制之前,验证您打算管理的项目是否与 CLI 部署目标匹配 。 如果你签了 aws login,在您注册前将配置区域设置为您的项目所在区域(aws configure set region <region> --profile <name>),并运行 aws login 以后再换吧. npm run sandbox:destroy 财务报告和审定财务报表 npm run destroy 只打印部署目标.

有经过核实的证书, npm run sandbox (包括 npm run sandbox:deploy和 npm run deploy 并检查CDK是否已在该账户和地区被拖入: 他们读取了 SSM 参数 /cdk-bootstrap/<qualifier>/version,在限定词是 @aws-cdk/core:bootstrapQualifier 从 cdk.json 上下文,或 CDK 默认值。 当参数不存在时,它们在合成并打印拖动这个账户和区域的指令前就停止了, npx cdk bootstrap aws://<account-id>/<region> --app=从项目目录中运行; --app= 使CDK不首先合成应用程序. 每一个账户和地区都需进行布道,这就创造了 CDKToolkit CloudFormation 堆栈, 包括 CDK 配置的 IAM 角色, 因此命令永远不会为您拖入陷阱 。 读取的任何其他结果,如拒绝读取或超时,并不停止部署.

npm run deploy 全面部署生产; npm run sandbox:deploy 一次部署沙盒并退出(没有表,用于脚本和CI); npm run sandbox:destroy 泪下沙盒。 同一后端代码在所有三个中运行——块切换执行自动.

导入 @aws-blocks/blocks 通过其默认(节点)条目宣布默认计算(LambdaCompute因此,CLI报告它在遥测。 只有在远程测量读取注册簿时,在构建的应用程序的块后,才将其折叠起来 LambdaCompute 以优先为准。 这个 cdk 财务报告和审定财务报表 browser 条目不声明.

npm run deploy 流出云阵事件到 静态 他们发生的时候,所以 npm run deploy | tee deploy.log 显示实事求是的进步 而不是沉默几分钟, 部署失败保持其理由 标准 (因为部署失败了) 在POSIX上,部署也能活过一个迷失的收获: SIGTERM,或任何 SIGHUP - 一个封闭的终端,一个背景 npm run deploy & ——记录一行并保持流线,而不是放弃堆栈更新 Cloud Formation 仍在应用. 按 Ctrl- C 键,或发送 SIGTERM 两次,停止它。 该信号恢复能力仅为 POSIX : Windows 没有进程组和 OS 交付 SIGTERM编号 :SIGHUP,所以在进程树上有一个杀 仍然结束部署.

测试

最快的循环是通过其输入的 API 调用 test/e2e.test.ts ——没有浏览器,没有嘲笑:

import { test } from 'node:test';
import assert from 'node:assert';
import type { api as ApiType } from 'aws-blocks';

let api: typeof ApiType;
test.before(async () => { api = (await import('aws-blocks')).api; });

test('stores and reads back a value', async () => {
  await api.setValue('k', 'v');
  assert.equal(await api.getValue('k'), 'v');
});

运行 npm run test:e2e先写测试,然后对着嘲笑,直到它通过.

最佳做法

• 导出每个 API - 前端只能导入你的东西 export 从 aws-blocks/index.ts。 。 。 .
• 以计划验证 将 Zod/Valibot 计划传递到数据块进行编译时间 财务报告和审定财务报表 运行时类型安全 .
• 别挡住请求 ——使用 AsyncJob 为慢事; submit() 返回 a jobId 马上.
• 警惕种族 - 使用有条件的写作(ifNotExists, (中文(简体) ), ifValueEquals, (中文(简体) ), ifFieldEquals)而不是读取-修改-写作.
• 本地先测试 ——嘲弄行为像真正的服务;一旦绿色就部署.

常见错误

• 未指定的终点 - 方法是公开的,除非你打电话 requireAuth编号 :requireRole本地的模拟器不会给你这个.
• 忘记导出 - 一个 ApiNamespace 您不会被前端所忽略.
• Database 何时 DistributedTable 一定会 ——"奥罗拉"成本较高,且起步冷;"SQL"只有在需要时才能到达.
• 校正 REST 风格路径 没有 GET /api/getData所有电话都是JSON -RPC POST下级 /aws-blocks/api; 替换为输入.

安全考虑

• 使用 await auth.requireAuth(context) 在不应该公开的每一种方法中——ApiNamespace方法都是 默认未校正
• 使用 new Secret(scope, id) aPI 密钥和证书 Secret 被推荐为生产秘密之家. new AppSetting(scope, id, { secret: true }) 是一个自由的,加密的倒置,只用于一个低值的秘密。 在源代码中不要硬化秘密值, 不要通过纯文本环境变量将真实的秘密传送给部署的应用程序—— 将它们传送到 Secret编号 :AppSetting
• 总是在 KVStore/ AppSetting 中附加一个接受用户数据的计划—— RPC 层验证结构而非业务逻辑
• 不添加宽度 * IAM政策——每个建筑区已经给予自身资源最少的优惠
• 永远不变 blockPublicAccess 在FileBucket上——通过 CloudFront 提供公共文件
• 配置 defaults.allowedOrigins 明确用于生产——避免通配符
• defaults.allowedOrigins 仅覆盖 API —— 从浏览器获取其预先签名的 URL 或文件控件的 FileBucket corsRules 列出您的前端来源( 包括 http://localhost:3000 用于对沙盒的本地前端),或上传/下载失败,一旦部署 CORS 错误
• 跨域部署,通过 crossDomain: true 用于验证构造器(可转让设备) SameSite=None; Secure; Partitioned(中文(简体) )
• 启用 frontDoor: { features: { monitoring: { enabled: true, subscriptions: [new subs.EmailSubscription('[email protected]')] } } } 用于生产警报的东道主subs =: aws-cdk-lib/aws-sns-subscriptions; 仅电子邮件/URL; 顶级 monitoring 道具是被贬损的别名)
• 通过 CDK 添加 WPAF 和 API Gateway 节奏, 用于 公用软件 — 默认不包括
• Logger提供串行安全(circular refs,类型强制),但不编辑敏感内容——从不向 Logger 方法传递原始证书,令牌或秘密;在记录前将上下文对象进行消毒

IAM 硬化

每个区块计算为一个共享的IAM(身份和访问管理)执行角色运行,每个建筑区块都给予它权限. 设定 defaults.permissionsBoundary 将附件a 权限边界对每个IAM角色 AWS Blocks 设定一个有效权限的上限。 传递政策名称,其完整的ARN(当政策有路径时需要),或 iam.IManagedPolicy。它在两个预设中都没有设置,而未设置的叶片模板没有改变.

// aws-blocks/index.cdk.ts
export const blocksStack = await BlocksStack.create(app, stackName, {
  backendHandlerPath: join(__dirname, 'index.handler.ts'),
  backendCDKPath: join(__dirname, 'index.ts'),
  defaults: { ...BlocksPresets.production, permissionsBoundary: 'my-app-boundary' },
});

• 报曰. 无论有没有边界,每个合成人都会写出共同角色的构成政策 cdk.out/<stack>.blocks-iam.json (单位:千美元)<stack>.<backendId>.blocks-iam.json 用于嵌入式 BlocksBackend),它没有部署,所以CI可以通过它来捕捉许可增长.
• 范围. 在一个 BlocksStack 边框覆盖堆栈中的每个角色; 在嵌入式上 BlocksBackend 它覆盖了后端的子树外加堆栈级的CDK(Cloud Development Kit)单通角色 它的块加.
• CDK语境. 如果是CDK的话 @aws-cdk/core:permissionsBoundary 设置上下文, defaults.permissionsBoundary blocks创造的角色获胜 合成警告.

细节,包括在许多应用程序中共享一个 AWS 账户,都在捆绑中 @aws-blocks/core 读取docs/core/README.md)),"IAM:允许边界和组成政策报告"和"在一个AWS账户(共享平台)中运行许多应用"等章节.

VPC 支持

AWS Blocks 支持在 VPC 中运行您的后端,用于网络级别隔离或连接到 VPC 约束的资源. 您可以让 Blocks 自动管理端点提供和安全小组, 或者带来一个完全配置的 VPC 并处理自己的网络.

见 瓦努阿图 用于使用、配置选项、成本细节和关于何时适合VPC的指导.

参考文献

• 每个街区的文件: docs/<block>/README.md (概览),加 docs/<block>/API.md (完整的API参考)和 docs/<block>/DESIGN.md (architecture & programmation) 凡有——例如. docs/bb-distributed-table/README.md。目录 + 决策树 docs/README.md。 。 。 .
• UI 组件 (单位:千美元)@aws-blocks/blocks/ui: Authenticator, (中文(简体) ), AuthenticatedContent, (中文(简体) ), AccountMenuBar, (中文(简体) ), onAuthChange, (中文(简体) ), broadcastAuthChange ——框架不可知,回DOM节点. 见 @aws-blocks/auth-common 读取.
• 安全部门改革 (单位:千美元)@aws-blocks/blocks/server: withAuth 在服务器渲染时将浏览器 cookie 转发到 API 调用 。 见 @aws-blocks/core 读取.
• 电线协议调试( D) : 客户端是JSON-RPC 2.0 /aws-blocks/api 你不应该直接打电话 对于 curl- 一级故障,看 难题. md。 。 。 .