API Smithy a DynamoDB

El generador connection conecta una API Smithy a un proyecto de 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 Smithy TypeScript API (generado con ts#api usando --framework=smithy)
2. Un proyecto ts#dynamodb

Uso

Ejecutar el generador

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

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

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

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

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

Opciones

Parámetro	Tipo	Predeterminado	Descripción
sourceProject Requerido	string	-	El proyecto de origen
targetProject Requerido	string	-	El proyecto de destino al que conectar
sourceComponent	string	-	El componente de origen desde el que conectar (nombre del componente, ruta relativa a la raíz del proyecto de origen, o id del generador). Use '.' para seleccionar explícitamente el proyecto como origen.
targetComponent	string	-	El componente de destino al que conectar (nombre del componente, ruta relativa a la raíz del proyecto de destino, o id del generador). Use '.' para seleccionar explícitamente el proyecto como destino.
preferInstallDependencies	boolean	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 de DynamoDB. No se modifican archivos de código fuente.

Usar DynamoDB en operaciones

Importa las factories de entidades desde el paquete de 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 {
  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 };
};

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 todos los handlers de 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_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.