API Smithy a DynamoDB

El generador connection conecta una API Smithy a un proyecto TypeScript DynamoDB, configurando el desarrollo local para que ambos se inicien juntos automáticamente.

Requisitos previos

Antes de usar este generador, asegúrate de tener:

1. Un proyecto de API TypeScript Smithy (generado con ts#api usando --framework=smithy)
2. Un proyecto ts#dynamodb

Uso

Ejecutar el generador

Ejecute este generador@aws/nx-plugin:connection

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

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - connection
5. Complete los parámetros requeridos
6. Haga clic en Generate

Construya su comando5

sourceProjectRequerido

targetProjectRequerido

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runTambién puede realizar una ejecución en seco para ver qué archivos se cambiarían

Selecciona tu proyecto backend de API Smithy como origen y tu proyecto DynamoDB como destino.

Opciones

Opciones del generador5 opciones

sourceProjectRequeridostring

El proyecto de origen

targetProjectRequeridostring

El proyecto de destino al que conectar

sourceComponentstring

El componente de origen desde el cual conectar (nombre del componente, ruta relativa a la raíz del proyecto de origen, o id del generador). Usa '.' para seleccionar explícitamente el proyecto como origen.

targetComponentstring

El componente de destino al cual conectar (nombre del componente, ruta relativa a la raíz del proyecto de destino, o id del generador). Usa '.' para seleccionar explícitamente el proyecto como destino.

preferInstallDependenciesbooleanPredeterminado: true

Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del generador

El generador actualiza el project.json de tu API Smithy para agregar una dependencia desde su target dev al target dev del proyecto DynamoDB. No se modifican archivos fuente.

Usar DynamoDB en operaciones

Importa las factories de entidades del paquete DynamoDB y úsalas dentro de las implementaciones de tus operaciones:

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

import { createExampleEntity } from '@my-scope/my-table';
import { ServiceContext } from '../context.js';
import { ListExamples as ListExamplesOperation } from '../generated/ssdk/index.js';

export const ListExamples: ListExamplesOperation<ServiceContext> = async () => {
  const entity = await createExampleEntity();
  const result = await entity.scan.go();
  return { items: result.data };
};

Infraestructura

Para permitir que las funciones Lambda accedan a la tabla de DynamoDB, otorga los permisos necesarios en tu infraestructura.

CDK

Llama a grantReadWriteData en el constructo de la tabla. Esto otorga tanto los permisos de DynamoDB como de KMS requeridos por el rol de ejecución de 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

Este ejemplo otorga acceso a cada handler en tu API. Si solo algunos handlers necesitan acceso, configúralos individualmente.

Terraform

Otorga al rol de ejecución de Lambda permiso para acceder a la tabla de DynamoDB y su clave de cifrado 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_execution_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]
      },
    ]
  })
}

Desarrollo local

El generador connection configura el target dev de tu proyecto para que dependa del target dev del proyecto DynamoDB. DynamoDB Local se iniciará automáticamente junto con tu proyecto al ejecutar dev.

La variable de entorno LOCAL_DEV=true se establece automáticamente, por lo que getDynamoDBClient() y resolveTableName() se conectan a la instancia local de DynamoDB Local en lugar de AWS.