API Smithy vers Base de Données Relationnelle

Le générateur connection relie une API Smithy à un projet de Base de Données Relationnelle, en injectant un client Prisma dans le contexte du service afin que toutes les implémentations d’opérations puissent accéder à la base de données.

Prérequis

Avant d’utiliser ce générateur, assurez-vous d’avoir :

Un projet ts#smithy-api (backend TypeScript)
Un projet ts#rdb

Utilisation

Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
Ouvrez la console Nx dans VSCode
Cliquez sur Generate (UI) dans la section "Common Nx Commands"
Recherchez @aws/nx-plugin - connection
Remplissez les paramètres requis
Cliquez sur 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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

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

Sélectionnez votre projet backend d’API Smithy comme source et votre projet de base de données relationnelle comme cible.

Options

Paramètre	Type	Par défaut	Description
sourceProject Requis	string	-	Le projet source
targetProject Requis	string	-	Le projet cible auquel se connecter
sourceComponent	string	-	Le composant source depuis lequel se connecter (nom du composant, chemin relatif à la racine du projet source, ou identifiant du générateur). Utilisez '.' pour sélectionner explicitement le projet comme source.
targetComponent	string	-	Le composant cible auquel se connecter (nom du composant, chemin relatif à la racine du projet cible, ou identifiant du générateur). Utilisez '.' pour sélectionner explicitement le projet comme cible.

Sortie du Générateur

Le générateur modifie trois fichiers existants dans votre backend d’API Smithy :

Répertoirepackages/api/src
- context.ts propriété db ajoutée à ServiceContext
- handler.ts Client Prisma créé dans lambdaHandler, passé à serviceHandler.handle
- local-server.ts Client Prisma créé dans le gestionnaire de requêtes, passé à serviceHandler.handle

De plus, il met à jour la cible serve-local de l’API pour démarrer automatiquement la base de données.

Comment ça Fonctionne

ServiceContext

Le générateur ajoute une propriété db typée à ServiceContext dans context.ts :

import { getPrisma as getMyDb } from ':my-scope/my-db';

export interface ServiceContext {
  tracer: Tracer;
  logger: Logger;
  metrics: Metrics;
  myDb: Awaited<ReturnType<typeof getMyDb>>;
}

Lambda Handler

Le client Prisma est instancié dans lambdaHandler et passé via le contexte du service :

import { getPrisma as getMyDb } from ':my-scope/my-db';

export const lambdaHandler = async (event: APIGatewayProxyEvent) => {
  const httpRequest = convertEvent(event);
  const myDb = await getMyDb();
  const httpResponse = await serviceHandler.handle(httpRequest, {
    tracer,
    logger,
    metrics,
    myDb,
  });
  return convertVersion1Response(httpResponse);
};

Utiliser la Base de Données dans les Opérations

Accédez à db depuis le contexte dans vos implémentations d’opérations :

import { ListUsersOperationInput, ListUsersOperationOutput } from '../generated/ssdk/index.js';
import { ServiceContext } from '../context.js';

export const listUsers = async (
  input: ListUsersOperationInput,
  ctx: ServiceContext,
): Promise<ListUsersOperationOutput> => {
  const users = await ctx.myDb.user.findMany();
  return { users };
};

Bases de Données Multiples

Exécuter à nouveau le générateur avec une cible différente ajoute la deuxième base de données à côté de la première. Les deux clients sont ajoutés à ServiceContext et instanciés dans handler.ts :

export interface ServiceContext {
  tracer: Tracer;
  logger: Logger;
  metrics: Metrics;
  myDb: Awaited<ReturnType<typeof getMyDb>>;
  otherDb: Awaited<ReturnType<typeof getOtherDb>>;
}

const myDb = await getMyDb();
const otherDb = await getOtherDb();
const httpResponse = await serviceHandler.handle(httpRequest, {
  tracer,
  logger,
  metrics,
  myDb,
  otherDb,
});

Infrastructure

Pour permettre à votre API de se connecter à la base de données lors de l’exécution, les fonctions Lambda de l’API doivent être déployées dans le même VPC que la base de données et bénéficier d’un accès réseau et IAM.

CDK
Terraform

Dans votre stack d’application, déployez l’API dans le même VPC que la base de données, puis appelez allowDefaultPortFrom et grantConnect pour ouvrir le chemin réseau et accorder la permission IAM rds-db:connect à chaque gestionnaire Lambda :

import { MyDatabase } from ':my-scope/common-constructs';

const db = new MyDatabase(this, 'Db', { vpc, ... });

const api = new MyApi(this, 'Api', {
  integrations: MyApi.defaultIntegrations(this)
    .withDefaultOptions({
      vpc,
      vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
    })
    .build(),
});

Object.entries(api.integrations).forEach(([operation, integration]) => {
  db.allowDefaultPortFrom(integration.handler, `Allow ${operation} to connect to the database`);
  db.grantConnect(integration.handler);
});

Déployez les fonctions Lambda de l’API dans un sous-réseau privé avec sortie, et non dans un sous-réseau privé isolé. Lors de l’exécution, getPrisma() récupère les détails de connexion à la base de données depuis AWS AppConfig, qui est un point de terminaison de service AWS public nécessitant un accès Internet sortant.

Transmettez les sorties du module de base de données à votre module API afin qu’il puisse atteindre la base de données et lire sa configuration d’exécution :

module "my_database" {
  source              = "../../common/terraform/src/app/dbs/my-database"
  vpc_id              = module.vpc.vpc_id
  database_subnet_ids = module.vpc.private_isolated_subnet_ids
  lambda_subnet_ids   = module.vpc.private_subnet_ids
}

module "api" {
  source             = "..."
  vpc_id             = module.vpc.vpc_id
  private_subnet_ids = module.vpc.private_subnet_ids

  appconfig_application_id     = module.my_database.appconfig_application_id
  database_cluster_resource_id = module.my_database.cluster_resource_id
  database_runtime_user        = module.my_database.database_runtime_user
  database_security_group_id   = module.my_database.security_group_id
  database_port                = module.my_database.cluster_port

  environment_variables = {
    RUNTIME_CONFIG_APP_ID = module.my_database.appconfig_application_id
  }
}

Déployez les fonctions Lambda de l’API dans des sous-réseaux privés avec sortie, et non dans des sous-réseaux privés isolés. Assurez-vous que le rôle Lambda de l’API dispose de la permission rds-db:connect et que son groupe de sécurité peut atteindre le groupe de sécurité de la base de données sur le port de la base de données.

Développement Local

Le générateur applique la même injection de client Prisma dans le gestionnaire de requêtes dans local-server.ts :

import { getPrisma as getMyDb } from ':my-scope/my-db';

const server = createServer(async function (req, res) {
  const httpRequest = convertRequest(req);
  const myDb = await getMyDb();
  const httpResponse = await serviceHandler.handle(httpRequest, {
    tracer,
    logger,
    metrics,
    myDb,
  });
  return writeResponse(httpResponse, res);
});

pnpm nx serve-local <api-project-name>

yarn nx serve-local <api-project-name>

npx nx serve-local <api-project-name>

bunx nx serve-local <api-project-name>

Cela démarre à la fois l’API et la base de données locale. La variable d’environnement SERVE_LOCAL=true est définie automatiquement, de sorte que le client Prisma se connecte à la base de données Docker locale au lieu d’Aurora.