TypeScript DynamoDB

Generator này tạo một dự án TypeScript DynamoDB mới được hỗ trợ bởi Amazon DynamoDB, sử dụng ElectroDB để mô hình hóa thực thể an toàn kiểu. Nó tạo ra mã ứng dụng và cơ sở hạ tầng cần thiết để cung cấp và quản lý bảng DynamoDB bằng AWS CDK hoặc Terraform, với hỗ trợ thiết kế bảng đơn và phát triển cục bộ tích hợp sẵn thông qua DynamoDB Local.

Cách sử dụng

Tạo một Dự án 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

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

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. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - ts#dynamodb
5. Điền các tham số bắt buộc
6. Nhấp Generate

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
name Bắt buộc	string	-	Tên của dự án DynamoDB cần tạo
directory	string	packages	Thư mục để lưu trữ dự án.
subDirectory	string	-	Thư mục con mà dự án được đặt trong đó. Mặc định là tên dự án.
framework	electrodb	electrodb	Framework sử dụng cho các entity DynamoDB.
tableName	string	-	Tên bảng DynamoDB. Tự động tạo nếu không chỉ định.
infra	dynamodb | none	dynamodb	Cơ sở hạ tầng để cung cấp cho bảng DynamoDB.
iac	inherit | cdk | terraform	inherit	Nhà cung cấp IaC ưa thích. Mặc định giá trị này được kế thừa từ lựa chọn ban đầu của bạn.
preferInstallDependencies	boolean	true	Có nên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để hoãn việc cài đặt khi chạy nhiều generator liên tiếp (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

Đầu ra của Generator

Generator tạo cấu trúc dự án sau trong thư mục <directory>/<name>:

• Thư mụcsrc

  • index.ts Project entry point and exports
  • client.ts DynamoDB client singleton and table name resolution
  • Thư mụcentities

    • 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

Các script phát triển cục bộ được chia sẻ trên tất cả các dự án DynamoDB (cả TypeScript và Python) và được tạo một lần vào:

• Thư mụcpackages/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

Cơ sở hạ tầng

Vì generator này cung cấp infrastructure as code dựa trên iac bạn đã chọn, nó sẽ tạo một dự án trong packages/common bao gồm các CDK constructs hoặc Terraform modules liên quan.

Dự án infrastructure as code chung được cấu trúc như sau:

CDK

• Thư mụcpackages/common/constructs

  • Thư mụcsrc

    • Thư mụcapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Thư mụccore/ 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

Dự án này được tạo bằng generator ts#project và do đó cấu hình các build targets giống nhau.

Terraform

• Thư mụcpackages/common/terraform

  • Thư mụcsrc

    • Thư mụcapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Thư mụccore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Generated Project

Dự án này được tạo bằng generator terraform#project và do đó cấu hình các build targets giống nhau.

CDK

• Thư mụcpackages/common/constructs/src

  • Thư mụcapp

    • Thư mụcdynamodb

      • <name>.ts Cơ sở hạ tầng cụ thể cho bảng của bạn
  • Thư mụccore

    • dynamodb.ts Construct bảng DynamoDB chung

Terraform

• Thư mụcpackages/common/terraform/src

  • Thư mụcapp

    • Thư mụcdynamodb

      • Thư mục<name>

        • <name>.tf Module cụ thể cho bảng của bạn
  • Thư mụccore

    • Thư mụcdynamodb

      • dynamodb.tf Module DynamoDB chung

Phát triển Cục bộ

Khởi động DynamoDB Cục bộ

Generator cấu hình một target dev để khởi động một instance DynamoDB Local và tạo bảng. Sử dụng target dev của dự án:

pnpm

pnpm nx dev <project-name>

yarn

yarn nx dev <project-name>

npm

npx nx dev <project-name>

bun

bunx nx dev <project-name>

Điều này tự động:

1. Kéo image DynamoDB Local (target pull-image)
2. Khởi động một container
3. Tạo một bảng local với các index được định nghĩa trong config.json

Mô hình hóa Dữ liệu

Dự án được tạo sử dụng ElectroDB để mô hình hóa thực thể an toàn kiểu trên một bảng DynamoDB đơn, tuân theo thiết kế bảng đơn của DynamoDB. Thêm hoặc cập nhật các tệp thực thể trong src/entities/, sử dụng thực thể ví dụ được tạo làm điểm khởi đầu.

Định nghĩa thực thể ví dụ:

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() },
  );

Để biết thêm chi tiết, xem tài liệu thực thể ElectroDB.

Sử dụng DynamoDB Client

src/client.ts được tạo xuất hai tiện ích chính:

• getDynamoDBClient() — trả về một DynamoDBClient singleton được lưu trong bộ nhớ cache. Khi LOCAL_DEV=true, kết nối đến phiên bản DynamoDB Local cục bộ; nếu không tạo một AWS client sử dụng chuỗi thông tin xác thực mặc định.
• resolveTableName() — trả về tên bảng DynamoDB. Khi LOCAL_DEV=true, trả về hằng số tên bảng cục bộ; nếu không lấy tên từ AWS AppConfig sử dụng biến môi trường RUNTIME_CONFIG_APP_ID và lưu vào bộ nhớ cache cho các lần gọi tiếp theo.

Dừng DynamoDB Cục bộ

Việc dừng dev (ví dụ: bằng Ctrl+C) sẽ tự động xóa container DynamoDB Local, nhưng vẫn giữ lại named volume để dữ liệu của bạn được bảo toàn qua các lần khởi động lại.

Windows

Do hạn chế trong việc xử lý tín hiệu trên Windows, container sẽ không được tự động xóa khi dev bị dừng. Bạn sẽ cần phải xóa nó thủ công:

<engine> rm -f <scope>-dynamodb

Thay thế <engine> bằng container engine của bạn (docker hoặc finch) và <scope> bằng scope của Nx workspace (ví dụ: proj).

Thêm/Xóa Global Secondary Indexes

GSI được định nghĩa trong config.json ở thư mục gốc dự án dưới khóa tableConfig.globalSecondaryIndexes. Thêm một mục cho mỗi GSI, tuân theo quy ước đặt tên khóa GSI thiết kế bảng đơn:

config.json

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

Trường sortKey là tùy chọn cho các GSI chỉ có hash-key.

File cấu hình này là nguồn sự thật duy nhất được đọc bởi tất cả các consumer:

• Phát triển cục bộ — dev đọc config.json và tạo hoặc cập nhật bảng cục bộ để khớp với danh sách GSI
• CDK — construct đọc config.json tại thời điểm synth, do đó các thay đổi GSI được phản ánh trong lần cdk deploy tiếp theo
• Terraform — module đọc config.json tại thời điểm plan/apply

Một GSI mỗi Triển khai

Chú ý

DynamoDB không cho phép tạo hoặc xóa nhiều hơn một GSI trong một lần cập nhật bảng.

Mỗi lần triển khai có thể thêm hoặc xóa tối đa một GSI. Nếu bạn cần thêm hoặc xóa nhiều GSI, hãy thực hiện từng cái một — cập nhật config.json và các lớp entity liên quan, triển khai stack, sau đó lặp lại cho thay đổi tiếp theo.

Kết nối đến Bảng

Trong bất kỳ dự án TypeScript nào, import các factory thực thể từ gói DynamoDB của bạn và sử dụng chúng trực tiếp:

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

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

Ở hậu trường, createExampleEntity() gọi resolveTableName() để lấy tên bảng từ AWS AppConfig tại thời điểm chạy.

Runtime config

Điều này dựa vào biến môi trường RUNTIME_CONFIG_APP_ID để lấy cấu hình từ AWS AppConfig tại runtime. Các dự án được xây dựng với plugin này (API, Agent, MCP server) đã có biến này được cấu hình tự động. Đối với các dự án khác, hãy đảm bảo RUNTIME_CONFIG_APP_ID được thiết lập trong môi trường runtime với AppConfig application ID được cung cấp bởi cơ sở hạ tầng của bạn. Để biết thêm thông tin, xem hướng dẫn Runtime Configuration.

Triển khai Bảng của bạn

Trình tạo DynamoDB tạo ra cơ sở hạ tầng CDK hoặc Terraform dựa trên iac bạn đã chọn.

CDK

Construct CDK được tạo trong common/constructs. Ví dụ sử dụng:

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');
  }
}

Điều này cung cấp một bảng DynamoDB với:

• pk (partition key) và sk (sort key), cả hai đều là kiểu String
• Global Secondary Indexes như được định nghĩa trong config.json
• Thanh toán theo yêu cầu (PAY_PER_REQUEST)
• Mã hóa KMS do khách hàng quản lý với tự động xoay khóa
• Khôi phục theo thời điểm được bật
• Bảo vệ xóa được bật
• Tên bảng được đăng ký trong Runtime Config dưới namespace dynamodb trong AWS AppConfig

Terraform

Module Terraform được tạo trong common/terraform. Ví dụ sử dụng:

packages/infra/src/main.tf

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

Điều này cung cấp một bảng DynamoDB với:

• pk (partition key) và sk (sort key), cả hai đều là kiểu String
• Global Secondary Indexes như được định nghĩa trong config.json
• Thanh toán theo yêu cầu (PAY_PER_REQUEST)
• Mã hóa KMS do khách hàng quản lý với tự động xoay khóa
• Khôi phục theo thời điểm được bật
• Bảo vệ xóa được bật
• Tên bảng được đăng ký trong Runtime Config

Bảo vệ Xóa

Bảo vệ xóa được bật mặc định để ngăn chặn việc xóa bảng một cách vô tình.

Tắt Bảo vệ Xóa

Tắt nó cho các môi trường mà việc xóa bảng được mong đợi, chẳng hạn như các stack phát triển hoặc xem trước có thời gian tồn tại ngắn.

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
}

Chế độ Thanh toán

Bảng mặc định sử dụng thanh toán theo yêu cầu (PAY_PER_REQUEST). Chuyển sang dung lượng được cung cấp cho các khối lượng công việc có thông lượng cao và có thể dự đoán.

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"
}

Khôi phục Theo Thời điểm

Khôi phục theo thời điểm được bật mặc định, cho phép bạn khôi phục bảng về bất kỳ thời điểm nào trong 35 ngày qua.

Tắt Khôi phục Theo Thời điểm

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
}

Xoay Khóa Mã hóa

Khóa KMS được sử dụng để mã hóa bảng có tính năng tự động xoay khóa được bật mặc định. Tắt nó nếu chính sách bảo mật của bạn quản lý việc xoay khóa từ bên ngoài.

Tắt Xoay Khóa Mã hóa

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
}

Kết nối

Sử dụng generator connection để tích hợp dự án này với các dự án khác trong workspace của bạn. Các kết nối sau liên quan đến dự án này:

tRPC API to TypeScript DynamoDBConnect a tRPC API to a DynamoDB table

Smithy API to TypeScript DynamoDBConnect a Smithy API to a DynamoDB table

TypeScript Agent to TypeScript DynamoDBConnect a TypeScript Agent to a DynamoDB table

MCP Server to TypeScript DynamoDBConnect a TypeScript MCP Server to a DynamoDB table