API Smithy para DynamoDB

O gerador connection conecta uma API Smithy a um projeto TypeScript DynamoDB, configurando o desenvolvimento local para que ambos iniciem juntos automaticamente.

Pré-requisitos

Antes de usar este gerador, certifique-se de ter:

Um projeto Smithy TypeScript API (gerado com ts#api usando --framework=smithy)
Um projeto ts#dynamodb

Uso

Instale o Nx Console VSCode Plugin se ainda não o fez
Abra o console Nx no VSCode
Clique em Generate (UI) na seção "Common Nx Commands"
Procure por @aws/nx-plugin - connection
Preencha os parâmetros obrigatórios
Clique em Generate

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

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

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

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

Selecione seu projeto de backend da API Smithy como origem e seu projeto DynamoDB como destino.

Opções

Parâmetro	Tipo	Padrão	Descrição
sourceProject Obrigatório	string	-	O projeto de origem
targetProject Obrigatório	string	-	O projeto de destino para conectar
sourceComponent	string	-	O componente de origem para conectar (nome do componente, caminho relativo à raiz do projeto de origem, ou id do gerador). Use '.' para selecionar explicitamente o projeto como origem.
targetComponent	string	-	O componente de destino para conectar (nome do componente, caminho relativo à raiz do projeto de destino, ou id do gerador). Use '.' para selecionar explicitamente o projeto como destino.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que os geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

O gerador atualiza o project.json da sua API Smithy para adicionar uma dependência do seu target dev ao target dev do projeto DynamoDB. Nenhum arquivo de código-fonte é modificado.

Usando DynamoDB em Operações

Importe as factories de entidade do pacote DynamoDB e use-as dentro das suas implementações de operação:

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

Infraestrutura

Para permitir que funções Lambda acessem a tabela DynamoDB, conceda as permissões necessárias em sua infraestrutura.

CDK
Terraform

Chame grantReadWriteData no construto da tabela. Isso concede as permissões do DynamoDB e KMS necessárias para a função de execução do Lambda:

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

Conceda à função de execução do Lambda permissão para acessar a tabela DynamoDB e sua chave de criptografia KMS:

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]
      },
    ]
  })
}

Desenvolvimento Local

O gerador connection configura o target dev do seu projeto para depender do target dev do projeto DynamoDB. O DynamoDB Local será iniciado automaticamente junto com o seu projeto ao executar dev.

A variável de ambiente LOCAL_DEV=true é definida automaticamente, então getDynamoDBClient() e resolveTableName() conectam-se à instância local do DynamoDB Local em vez da AWS.