API Smithy a DynamoDB

Il generatore connection collega un’API Smithy a un progetto TypeScript DynamoDB, configurando lo sviluppo locale in modo che entrambi si avviino automaticamente insieme.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

1. Un progetto Smithy TypeScript API (generato con ts#api usando --framework=smithy)
2. Un progetto ts#dynamodb

Utilizzo

Eseguire il Generatore

VSCode

1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - connection
5. Compila i parametri richiesti
6. Clicca su Generate

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Seleziona il tuo progetto backend API Smithy come sorgente e il tuo progetto DynamoDB come destinazione.

Opzioni

Parametro	Tipo	Predefinito	Descrizione
sourceProject Obbligatorio	string	-	Il progetto sorgente
targetProject Obbligatorio	string	-	Il progetto di destinazione a cui connettersi
sourceComponent	string	-	Il componente sorgente da cui connettersi (nome del componente, percorso relativo alla radice del progetto sorgente, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come sorgente.
targetComponent	string	-	Il componente di destinazione a cui connettersi (nome del componente, percorso relativo alla radice del progetto di destinazione, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come destinazione.
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Il generatore aggiorna il file project.json della tua API Smithy per aggiungere una dipendenza dal suo target dev al target dev del progetto DynamoDB. Nessun file sorgente viene modificato.

Utilizzare DynamoDB nelle Operazioni

Importa le factory di entità dal pacchetto DynamoDB e utilizzale all’interno delle implementazioni delle tue operazioni:

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

Infrastruttura

Per consentire alle funzioni Lambda di accedere alla tabella DynamoDB, concedi le autorizzazioni necessarie nella tua infrastruttura.

CDK

Chiama grantReadWriteData sul costrutto della tabella. Questo concede sia le autorizzazioni DynamoDB che KMS richieste dal ruolo di esecuzione 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);
});

Nota

Questo esempio concede l’accesso a ogni handler nella tua API. Se solo alcuni handler necessitano di accesso, configurali individualmente.

Terraform

Concedi al ruolo di esecuzione Lambda l’autorizzazione per accedere alla tabella DynamoDB e alla sua chiave di crittografia KMS:

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

Sviluppo Locale

Il generatore connection configura il target dev del tuo progetto in modo che dipenda dal target dev del progetto DynamoDB. DynamoDB Local si avvierà automaticamente insieme al tuo progetto quando esegui dev.

La variabile d’ambiente LOCAL_DEV=true viene impostata automaticamente, quindi getDynamoDBClient() e resolveTableName() si connettono all’istanza locale di DynamoDB Local invece che ad AWS.