Smithy API đến DynamoDB

Generator connection kết nối một Smithy API với dự án TypeScript DynamoDB, cấu hình phát triển cục bộ để cả hai khởi động cùng nhau một cách tự động.

Điều kiện tiên quyết

Trước khi sử dụng generator này, hãy đảm bảo bạn có:

1. Một dự án Smithy TypeScript API (được tạo bằng ts#api sử dụng --framework=smithy)
2. Một dự án ts#dynamodb

Cách sử dụng

Chạy Generator

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --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 - connection
5. Điền các tham số bắt buộc
6. Nhấp Generate

Chọn dự án backend Smithy API của bạn làm nguồn và dự án DynamoDB của bạn làm đích.

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
sourceProject Bắt buộc	string	-	Dự án nguồn
targetProject Bắt buộc	string	-	Dự án đích để kết nối tới
sourceComponent	string	-	Component nguồn để kết nối từ đó (tên component, đường dẫn tương đối so với thư mục gốc của dự án nguồn, hoặc generator id). Sử dụng '.' để chọn rõ ràng dự án làm nguồn.
targetComponent	string	-	Component đích để kết nối tới (tên component, đường dẫn tương đối so với thư mục gốc của dự án đích, hoặc generator id). Sử dụng '.' để chọn rõ ràng dự án làm đích.
preferInstallDependencies	boolean	true	Có nên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để trì 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.

Kết quả của Generator

Generator cập nhật project.json của Smithy API để thêm một dependency từ target dev của nó đến target dev của dự án DynamoDB. Không có file nguồn nào bị sửa đổi.

Sử dụng DynamoDB trong Operations

Import các entity factory từ package DynamoDB và sử dụng chúng bên trong các triển khai operation của bạn:

packages/api/src/operations/list-examples.ts

import { createExampleEntity } from '@my-scope/my-table';
import {
  ListExamplesOperationInput,
  ListExamplesOperationOutput,
} from '../generated/ssdk/index.js';
import { ServiceContext } from '../context.js';

export const listExamples = async (
  _input: ListExamplesOperationInput,
  _ctx: ServiceContext,
): Promise<ListExamplesOperationOutput> => {
  const entity = await createExampleEntity();
  const result = await entity.scan.go();
  return { items: result.data };
};

Hạ tầng

Để cho phép các hàm Lambda truy cập bảng DynamoDB, hãy cấp các quyền cần thiết trong cơ sở hạ tầng của bạn.

CDK

Gọi grantReadWriteData trên construct của bảng. Điều này cấp cả quyền DynamoDB và KMS cần thiết cho vai trò thực thi Lambda:

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

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

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

const api = new Api(this, 'Api', {
  integrations: Api.defaultIntegrations(this).build(),
});

Object.entries(api.integrations).forEach(([, integration]) => {
  table.grantReadWriteData(integration.handler);
});

Ghi chú

Ví dụ này cấp quyền truy cập cho mọi handler trong API của bạn. Nếu chỉ một số handler cần quyền truy cập, hãy cấu hình chúng riêng lẻ.

Terraform

Cấp quyền cho vai trò thực thi Lambda để truy cập bảng DynamoDB và khóa mã hóa KMS của nó:

packages/infra/src/main.tf

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

resource "aws_iam_role_policy" "dynamodb_access" {
  role = module.my_api.lambda_role_name

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = [
          "dynamodb:GetItem",
          "dynamodb:PutItem",
          "dynamodb:UpdateItem",
          "dynamodb:DeleteItem",
          "dynamodb:Query",
          "dynamodb:Scan",
          "dynamodb:BatchGetItem",
          "dynamodb:BatchWriteItem",
        ]
        Resource = [
          module.my_table.table_arn,
          "${module.my_table.table_arn}/index/*",
        ]
      },
      {
        Effect = "Allow"
        Action = [
          "kms:Encrypt",
          "kms:Decrypt",
          "kms:ReEncrypt*",
          "kms:GenerateDataKey*",
          "kms:DescribeKey"
        ]
        Resource = [module.my_table.kms_key_arn]
      },
    ]
  })
}

Phát triển cục bộ

Trình tạo connection cấu hình target dev của dự án để phụ thuộc vào target dev của dự án DynamoDB. DynamoDB Local sẽ tự động khởi động cùng với dự án của bạn khi chạy dev.

Biến môi trường LOCAL_DEV=true được đặt tự động, do đó getDynamoDBClient() và resolveTableName() kết nối với phiên bản DynamoDB Local cục bộ thay vì AWS.