TypeScript DynamoDB

此生成器创建一个新的 TypeScript DynamoDB 项目，由 Amazon DynamoDB 支持，使用 ElectroDB 进行类型安全的实体建模。它生成应用程序代码和基础设施，用于使用 AWS CDK 或 Terraform 配置和管理 DynamoDB 表，支持单表设计，并通过 DynamoDB Local 内置本地开发功能。

用法

生成 TypeScript DynamoDB 项目

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#dynamodb

yarn

yarn nx g @aws/nx-plugin:ts#dynamodb

npm

npx nx g @aws/nx-plugin:ts#dynamodb

bun

bunx nx g @aws/nx-plugin:ts#dynamodb

您还可以执行试运行以查看哪些文件会被更改

pnpm

pnpm nx g @aws/nx-plugin:ts#dynamodb --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#dynamodb --dry-run

npm

npx nx g @aws/nx-plugin:ts#dynamodb --dry-run

bun

bunx nx g @aws/nx-plugin:ts#dynamodb --dry-run

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - ts#dynamodb
5. 填写必需参数
6. 点击 Generate

选项

参数	类型	默认值	描述
name 必需	string	-	要生成的 DynamoDB 项目名称
directory	string	packages	存储项目的目录。
subDirectory	string	-	项目放置的子目录。默认情况下为项目名称。
framework	electrodb	electrodb	用于 DynamoDB 实体的框架。
tableName	string	-	DynamoDB 表名称。如果未指定则自动生成。
infra	dynamodb | none	dynamodb	为 DynamoDB 表配置的基础设施。
iac	inherit | cdk | terraform	inherit	首选的 IaC 提供商。默认情况下，这继承自您的初始选择。
preferInstallDependencies	boolean	true	是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

生成器在 <directory>/<name> 目录中创建以下项目结构：

• 文件夹src

  • index.ts Project entry point and exports
  • client.ts DynamoDB client singleton and table name resolution
  • 文件夹entities

    • example.ts Example ElectroDB entity definition
    • index.ts Entity exports
• config.json Table configuration including GSI definitions and local development settings
• package.json Project manifest defining the project’s package name and dependencies
• project.json Project configuration and build targets

本地开发脚本在所有 DynamoDB 项目（TypeScript 和 Python）之间共享，并生成一次到：

• 文件夹packages/common/scripts/src/dynamodb

  • create-local-table.ts Creates the DynamoDB table in the local DynamoDB Local instance
  • pull-image.ts Pulls the DynamoDB Local image
  • start-container.ts Starts the DynamoDB Local container

基础设施

由于此生成器根据您选择的 iac 提供基础设施即代码，它将在 packages/common 中创建一个项目，其中包含相关的 CDK 构造或 Terraform 模块。

通用基础设施即代码项目的结构如下：

CDK

• 文件夹packages/common/constructs

  • 文件夹src

    • 文件夹app/ Constructs for infrastructure specific to a project/generator

      • …
    • 文件夹core/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Generated Project

此项目使用 ts#project 生成器生成，因此配置了相同的构建目标。

Terraform

• 文件夹packages/common/terraform

  • 文件夹src

    • 文件夹app/ Terraform modules for infrastructure specific to a project/generator

      • …
    • 文件夹core/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Generated Project

此项目使用 terraform#project 生成器生成，因此配置了相同的构建目标。

CDK

• 文件夹packages/common/constructs/src

  • 文件夹app

    • 文件夹dynamodb

      • <name>.ts 特定于您的表的基础设施
  • 文件夹core

    • dynamodb.ts 通用 DynamoDB 表构造

Terraform

• 文件夹packages/common/terraform/src

  • 文件夹app

    • 文件夹dynamodb

      • 文件夹<name>

        • <name>.tf 特定于您的表的模块
  • 文件夹core

    • 文件夹dynamodb

      • dynamodb.tf 通用 DynamoDB 模块

本地开发

启动本地 DynamoDB

生成器配置了一个 dev 目标，用于启动 DynamoDB Local 实例并创建表。使用项目的 dev 目标：

pnpm

pnpm nx dev <project-name>

yarn

yarn nx dev <project-name>

npm

npx nx dev <project-name>

bun

bunx nx dev <project-name>

这会自动：

1. 拉取 DynamoDB Local 镜像（pull-image 目标）
2. 启动容器
3. 使用 config.json 中定义的索引创建本地表

数据建模

生成的项目使用 ElectroDB 在单个 DynamoDB 表上进行类型安全的实体建模，遵循 DynamoDB 的单表设计。在 src/entities/ 下添加或更新实体文件，使用生成的示例实体作为起点。

示例实体定义：

packages/my-table/src/entities/example.ts

import { Entity } from 'electrodb';
import { getDynamoDBClient, resolveTableName } from '../client.js';

export const createExampleEntity = async () =>
  new Entity(
    {
      model: {
        entity: 'example',
        version: '1',
        service: 'MyTable',
      },
      attributes: {
        id: {
          type: 'string',
          required: true,
        },
        createdAt: {
          type: 'string',
          required: true,
          default: () => new Date().toISOString(),
          readOnly: true,
        },
        updatedAt: {
          type: 'string',
          required: true,
          default: () => new Date().toISOString(),
          watch: '*',
          set: () => new Date().toISOString(),
        },
      },
      indexes: {
        primary: {
          pk: {
            field: 'pk',
            composite: ['id'],
          },
          sk: {
            field: 'sk',
            composite: [],
          },
        },
      },
    },
    { client: getDynamoDBClient(), table: await resolveTableName() },
  );

有关更多详细信息，请参阅 ElectroDB 实体文档。

使用 DynamoDB 客户端

生成的 src/client.ts 导出两个关键实用程序：

• getDynamoDBClient() — 返回一个缓存的单例 DynamoDBClient。当 LOCAL_DEV=true 时，连接到本地 DynamoDB Local 实例；否则使用默认凭证链创建 AWS 客户端。
• resolveTableName() — 返回 DynamoDB 表名称。当 LOCAL_DEV=true 时，返回本地表名称常量；否则使用 RUNTIME_CONFIG_APP_ID 环境变量从 AWS AppConfig 获取名称，并将其缓存以供后续调用。

停止本地 DynamoDB

停止 dev（例如使用 Ctrl+C）会自动删除 DynamoDB Local 容器，但会保留命名卷，因此您的数据在重启后仍然存在。

Windows

由于 Windows 上信号处理的限制，当 dev 停止时容器不会自动删除。您需要手动删除它：

<engine> rm -f <scope>-dynamodb

将 <engine> 替换为您的容器引擎（docker 或 finch），将 <scope> 替换为您的 Nx 工作区作用域（例如 proj）。

添加/删除全局二级索引

GSI 在项目根目录的 config.json 中的 tableConfig.globalSecondaryIndexes 键下定义。为每个 GSI 添加一个条目，遵循 单表设计 的 GSI 键命名约定：

config.json

{
  ...
  "tableConfig": {
    "globalSecondaryIndexes": [
      {
        "indexName": "gsi1pk-gsi1sk-index",
        "partitionKey": "gsi1pk",
        "sortKey": "gsi1sk"
      },
      {
        "indexName": "gsi2pk-gsi2sk-index",
        "partitionKey": "gsi2pk",
        "sortKey": "gsi2sk"
      }
    ]
  }
}

对于仅使用哈希键的 GSI，sortKey 字段是可选的。

此配置文件是所有使用者读取的单一事实来源：

• 本地开发 — dev 读取 config.json 并创建或更新本地表以匹配 GSI 列表
• CDK — 构造在合成时读取 config.json，因此 GSI 更改会在下次 cdk deploy 时反映出来
• Terraform — 模块在计划/应用时读取 config.json

每次部署一个 GSI

警告

DynamoDB 不允许在单次表更新中创建或删除多个 GSI。

每次部署最多只能添加或删除一个 GSI。如果需要添加或删除多个 GSI，请逐个进行 — 更新 config.json 和相关实体类，部署堆栈，然后对下一个更改重复此操作。

连接到表

在任何 TypeScript 项目中，从您的 DynamoDB 包导入实体工厂并直接使用它们：

import { createExampleEntity } from '@my-scope/my-table';

const entity = await createExampleEntity();
const result = await entity.query.primary({ id: '123' }).go();

在幕后，createExampleEntity() 调用 resolveTableName() 在运行时从 AWS AppConfig 获取表名称。

运行时配置

这依赖于 RUNTIME_CONFIG_APP_ID 环境变量在运行时从 AWS AppConfig 获取配置。使用此插件构建的项目（API、Agent、MCP 服务器）已自动配置此变量。对于其他项目，请确保在运行时环境中设置 RUNTIME_CONFIG_APP_ID，其值为基础设施配置的 AppConfig 应用程序 ID。有关更多信息，请参阅 运行时配置指南。

部署您的表

DynamoDB 生成器根据您选择的 iac 创建 CDK 或 Terraform 基础设施。

CDK

CDK 构造在 common/constructs 中创建。使用示例：

packages/infra/src/stacks/application-stack.ts

import { MyTable } from '@my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const table = new MyTable(this, 'Table');
  }
}

这将配置一个具有以下特性的 DynamoDB 表：

• pk（分区键）和 sk（排序键），均为 String 类型
• 在 config.json 中定义的全局二级索引
• 按需（PAY_PER_REQUEST）计费
• 具有自动密钥轮换的客户托管 KMS 加密
• 启用时间点恢复
• 启用删除保护
• 表名在 AWS AppConfig 的 dynamodb 命名空间下注册到 Runtime Config

Terraform

Terraform 模块在 common/terraform 中创建。使用示例：

packages/infra/src/main.tf

module "my_table" {
  source = "../../common/terraform/src/app/dynamodb/my-table"
}

这将配置一个具有以下特性的 DynamoDB 表：

• pk（分区键）和 sk（排序键），均为 String 类型
• 在 config.json 中定义的全局二级索引
• 按需（PAY_PER_REQUEST）计费
• 具有自动密钥轮换的客户托管 KMS 加密
• 启用时间点恢复
• 启用删除保护
• 表名注册到 Runtime Config

删除保护

默认启用删除保护以防止意外删除表。

禁用删除保护

对于预期会删除表的环境（例如短期开发或预览堆栈），可以禁用它。

CDK

packages/infra/src/stacks/application-stack.ts

import { MyTable } from '@my-scope/common-constructs';

const table = new MyTable(this, 'Table', {
  deletionProtection: false,
});

Terraform

packages/infra/src/main.tf

module "my_table" {
  source                      = "../../common/terraform/src/app/dynamodb/my-table"
  deletion_protection_enabled = false
}

计费模式

表默认使用按需（PAY_PER_REQUEST）计费。对于可预测的高吞吐量工作负载，可以切换到预配置容量。

CDK

packages/infra/src/stacks/application-stack.ts

import { BillingMode } from 'aws-cdk-lib/aws-dynamodb';
import { MyTable } from '@my-scope/common-constructs';

const table = new MyTable(this, 'Table', {
  billingMode: BillingMode.PROVISIONED,
  readCapacity: 5,
  writeCapacity: 5,
});

Terraform

packages/infra/src/main.tf

module "my_table" {
  source       = "../../common/terraform/src/app/dynamodb/my-table"
  billing_mode = "PROVISIONED"
}

时间点恢复

默认启用时间点恢复，允许您将表恢复到过去 35 天内的任意时间点。

禁用时间点恢复

CDK

packages/infra/src/stacks/application-stack.ts

import { MyTable } from '@my-scope/common-constructs';

const table = new MyTable(this, 'Table', {
  pointInTimeRecoverySpecification: { pointInTimeRecoveryEnabled: false },
});

Terraform

packages/infra/src/main.tf

module "my_table" {
  source                         = "../../common/terraform/src/app/dynamodb/my-table"
  point_in_time_recovery_enabled = false
}

加密密钥轮换

用于加密表的 KMS 密钥默认启用自动密钥轮换。如果您的安全策略在外部管理轮换，可以禁用它。

禁用加密密钥轮换

CDK

packages/infra/src/stacks/application-stack.ts

import { MyTable } from '@my-scope/common-constructs';

const table = new MyTable(this, 'Table', {
  enableKeyRotation: false,
});

Terraform

packages/infra/src/main.tf

module "my_table" {
  source              = "../../common/terraform/src/app/dynamodb/my-table"
  enable_key_rotation = false
}

连接

使用 connection 生成器将此项目与工作区中的其他项目集成。以下连接涉及此项目：

tRPC API to TypeScript DynamoDB将 tRPC API 连接到 DynamoDB 表

Smithy API to TypeScript DynamoDB将 Smithy API 连接到 DynamoDB 表

TypeScript Agent to TypeScript DynamoDB将 TypeScript Agent 连接到 DynamoDB 表

MCP Server to TypeScript DynamoDB将 TypeScript MCP Server 连接到 DynamoDB 表