Aller au contenu
@aws/nx-plugin
Blog

tRPC

tRPC est un framework pour construire des APIs en TypeScript avec une sécurité de type de bout en bout. En utilisant tRPC, les mises à jour des entrées et sorties des opérations de l’API sont immédiatement reflétées dans le code client et visibles dans votre IDE sans avoir à reconstruire votre projet.

Le générateur d’API tRPC crée une nouvelle API tRPC avec une infrastructure configurée via AWS CDK ou Terraform. Le backend généré utilise AWS Lambda pour un déploiement serverless, exposé via une API AWS API Gateway, et inclut une validation de schéma avec Zod. Il configure AWS Lambda Powertools pour l’observabilité, incluant le logging, le tracing AWS X-Ray et les métriques Cloudwatch.

Utilisation

Section intitulée « Utilisation »

Générer une API tRPC

Section intitulée « Générer une API tRPC »

Vous pouvez générer une nouvelle API tRPC de deux manières :

  1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
  2. Ouvrez la console Nx dans VSCode
  3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
  4. Recherchez @aws/nx-plugin - ts#trpc-api
  5. Remplissez les paramètres requis
    • Cliquez sur Generate

    Options

    Section intitulée « Options »
    Paramètre Type Par défaut Description
    name Requis string - The name of the API (required). Used to generate class names and file paths.
    computeType string ServerlessApiGatewayRestApi The type of compute to use to deploy this API. Choose between ServerlessApiGatewayRestApi (default) or ServerlessApiGatewayHttpApi.
    auth string IAM The method used to authenticate with your API. Choose between IAM (default), Cognito or None.
    directory string packages The directory to store the application in.
    iacProvider string CDK The preferred IaC provider

    Résultat du générateur

    Section intitulée « Résultat du générateur »

    Le générateur créera la structure de projet suivante dans le répertoire <directory>/<api-name> :

    • Répertoiresrc
      • init.ts Initialisation du backend tRPC
      • router.ts Définition du routeur tRPC (point d’entrée de l’API du gestionnaire Lambda)
      • Répertoireschema Définitions de schémas avec Zod
        • echo.ts Exemple de définitions pour l’entrée et la sortie de la procédure “echo”
      • Répertoireprocedures Procédures (ou opérations) exposées par votre API
        • echo.ts Exemple de procédure
      • Répertoiremiddleware
        • error.ts Middleware pour la gestion des erreurs
        • logger.ts middleware pour configurer AWS Powertools pour le logging Lambda
        • tracer.ts middleware pour configurer AWS Powertools pour le tracing Lambda
        • metrics.ts middleware pour configurer AWS Powertools pour les métriques Lambda
      • local-server.ts Point d’entrée de l’adaptateur autonome tRPC pour le serveur de développement local
      • Répertoireclient
        • index.ts Client typé pour les appels API entre machines
    • tsconfig.json Configuration TypeScript
    • project.json Configuration du projet et cibles de build

    Infrastructure

    Section intitulée « Infrastructure »

    Ce générateur fournit de l’infrastructure as code basée sur votre iacProvider choisi. Il créera un projet dans packages/common qui inclut les constructions CDK ou modules Terraform pertinents.

    Le projet commun d’infrastructure as code est structuré comme suit :

    • Répertoirepackages/common/constructs
      • Répertoiresrc
        • Répertoireapp/ Constructions pour l’infrastructure spécifique à un projet/générateur
          • …
        • Répertoirecore/ Constructions génériques réutilisées par celles dans app
          • …
        • index.ts Point d’entrée exportant les constructions depuis app
      • project.json Cibles de build et configuration du projet

    Pour déployer votre API, les fichiers suivants sont générés :

    • Répertoirepackages/common/constructs/src
      • Répertoireapp
        • Répertoireapis
          • <project-name>.ts Construct CDK pour déployer votre API
      • Répertoirecore
        • Répertoireapi
          • http-api.ts Construct CDK pour déployer une API HTTP (si vous avez choisi de déployer une API HTTP)
          • rest-api.ts Construct CDK pour déployer une API REST (si vous avez choisi de déployer une API REST)
          • utils.ts Utilitaires pour les constructs d’API

    Implémentation de votre API tRPC

    Section intitulée « Implémentation de votre API tRPC »

    À haut niveau, les APIs tRPC consistent en un routeur qui délègue les requêtes à des procédures spécifiques. Chaque procédure a une entrée et une sortie définies comme un schéma Zod.

    Schéma

    Section intitulée « Schéma »

    Le répertoire src/schema contient les types partagés entre votre code client et serveur. Dans ce package, ces types sont définis avec Zod, une bibliothèque de déclaration et validation de schémas orientée TypeScript.

    Un exemple de schéma pourrait ressembler à ceci :

    import { z } from 'zod';
    

    // Définition du schéma
    export const UserSchema = z.object({
      name: z.string(),
      height: z.number(),
      dateOfBirth: z.string().datetime(),
    });
    

    // Type TypeScript correspondant
    export type User = z.TypeOf<typeof UserSchema>;

    Avec le schéma ci-dessus, le type User est équivalent au TypeScript suivant :

    interface User {
      name: string;
      height: number;
      dateOfBirth: string;
    }

    Les schémas sont partagés entre le code serveur et client, fournissant un seul endroit à modifier lors de changements des structures utilisées dans votre API.

    Les schémas sont automatiquement validés par votre API tRPC à l’exécution, évitant d’avoir à écrire manuellement une logique de validation personnalisée dans votre backend.

    Zod fournit des utilitaires puissants pour combiner ou dériver des schémas comme .merge, .pick, .omit et plus encore. Vous trouverez plus d’informations sur le site de documentation de Zod.

    Routeur et procédures

    Section intitulée « Routeur et procédures »

    Vous trouverez le point d’entrée de votre API dans src/router.ts. Ce fichier contient le gestionnaire Lambda qui achemine les requêtes vers des “procédures” basées sur l’opération invoquée. Chaque procédure définit l’entrée attendue, la sortie et l’implémentation.

    Le routeur exemple généré pour vous a une seule opération appelée echo :

    import { echo } from './procedures/echo.js';
    

    export const appRouter = router({
      echo,
    });

    L’exemple de procédure echo est généré pour vous dans src/procedures/echo.ts :

    export const echo = publicProcedure
      .input(EchoInputSchema)
      .output(EchoOutputSchema)
      .query((opts) => ({ result: opts.input.message }));

    Décomposons ce code :

    • publicProcedure définit une méthode publique sur l’API, incluant le middleware configuré dans src/middleware. Ce middleware inclut l’intégration AWS Lambda Powertools pour le logging, tracing et les métriques.
    • input accepte un schéma Zod définissant l’entrée attendue pour l’opération. Les requêtes envoyées pour cette opération sont automatiquement validées contre ce schéma.
    • output accepte un schéma Zod définissant la sortie attendue pour l’opération. Vous verrez des erreurs de type dans votre implémentation si vous ne retournez pas une sortie conforme au schéma.
    • query accepte une fonction définissant l’implémentation de votre API. Cette implémentation reçoit opts, qui contient l’input passé à votre opération, ainsi que d’autres contextes configurés par le middleware, disponibles dans opts.ctx. La fonction passée à query doit retourner une sortie conforme au schéma output.

    L’utilisation de query pour définir l’implémentation indique que l’opération n’est pas mutative. Utilisez cela pour définir des méthodes de récupération de données. Pour implémenter une opération mutative, utilisez plutôt la méthode mutation.

    Si vous ajoutez une nouvelle procédure, assurez-vous de l’enregistrer en l’ajoutant au routeur dans src/router.ts.

    Personnalisation de votre API tRPC

    Section intitulée « Personnalisation de votre API tRPC »

    Erreurs

    Section intitulée « Erreurs »

    Dans votre implémentation, vous pouvez retourner des réponses d’erreur aux clients en lançant un TRPCError. Ceux-ci acceptent un code indiquant le type d’erreur, par exemple :

    throw new TRPCError({
      code: 'NOT_FOUND',
      message: 'La ressource demandée n\'a pas pu être trouvée',
    });

    Organisation des opérations

    Section intitulée « Organisation des opérations »

    Au fur et à mesure que votre API grandit, vous pouvez souhaiter regrouper des opérations liées.

    Vous pouvez regrouper des opérations avec des routeurs imbriqués, par exemple :

    import { getUser } from './procedures/users/get.js';
    import { listUsers } from './procedures/users/list.js';
    

    const appRouter = router({
       users: router({
          get: getUser,
          list: listUsers,
       }),
       ...
    })

    Les clients reçoivent alors ce regroupement d’opérations, par exemple invoquer l’opération listUsers ressemblerait à ceci :

    client.users.list.query();

    Logging

    Section intitulée « Logging »

    Le logger AWS Lambda Powertools est configuré dans src/middleware/logger.ts, et peut être accédé dans une implémentation d’API via opts.ctx.logger. Vous pouvez l’utiliser pour logger dans CloudWatch Logs, et/ou contrôler les valeurs supplémentaires à inclure dans chaque message de log structuré. Par exemple :

    export const echo = publicProcedure
       .input(...)
       .output(...)
       .query(async (opts) => {
          opts.ctx.logger.info('Opération appelée avec l\'entrée', opts.input);
    

          return ...;
       });

    Pour plus d’informations sur le logger, référez-vous à la documentation AWS Lambda Powertools Logger.

    Enregistrement de métriques

    Section intitulée « Enregistrement de métriques »

    Les métriques AWS Lambda Powertools sont configurées dans src/middleware/metrics.ts, et peuvent être accédées dans une implémentation d’API via opts.ctx.metrics. Vous pouvez les utiliser pour enregistrer des métriques dans CloudWatch sans avoir à importer et utiliser l’AWS SDK, par exemple :

    export const echo = publicProcedure
       .input(...)
       .output(...)
       .query(async (opts) => {
          opts.ctx.metrics.addMetric('Invocations', 'Count', 1);
    

          return ...;
       });

    Pour plus d’informations, référez-vous à la documentation AWS Lambda Powertools Metrics.

    Ajustement fin du tracing X-Ray

    Section intitulée « Ajustement fin du tracing X-Ray »

    Le traceur AWS Lambda Powertools est configuré dans src/middleware/tracer.ts, et peut être accédé dans une implémentation d’API via opts.ctx.tracer. Vous pouvez l’utiliser pour ajouter des traces avec AWS X-Ray afin de fournir des insights détaillés sur les performances et le flux des requêtes API. Par exemple :

    export const echo = publicProcedure
       .input(...)
       .output(...)
       .query(async (opts) => {
          const subSegment = opts.ctx.tracer.getSegment()!.addNewSubsegment('MyAlgorithm');
          // ... logique de mon algorithme à capturer
          subSegment.close();
    

          return ...;
       });

    Pour plus d’informations, référez-vous à la documentation AWS Lambda Powertools Tracer.

    Implémentation de middleware personnalisé

    Section intitulée « Implémentation de middleware personnalisé »

    Vous pouvez ajouter des valeurs supplémentaires au contexte fourni aux procédures en implémentant un middleware.

    Par exemple, implémentons un middleware pour extraire des détails sur l’utilisateur appelant notre API dans src/middleware/identity.ts.

    Cet exemple suppose que auth était configuré à IAM. Pour l’authentification Cognito, le middleware d’identité est plus simple, extrayant les claims pertinents depuis l’event.

    D’abord, nous définissons ce que nous ajouterons au contexte :

    export interface IIdentityContext {
      identity?: {
        sub: string;
        username: string;
      };
    }

    Notez que nous définissons une propriété optionnelle supplémentaire au contexte. tRPC s’assure que cette propriété est définie dans les procédures ayant correctement configuré ce middleware.

    Ensuite, nous implémentons le middleware lui-même. Il a la structure suivante :

    export const createIdentityPlugin = () => {
       const t = initTRPC.context<...>().create();
       return t.procedure.use(async (opts) => {
          // Ajoutez ici la logique à exécuter avant la procédure
    

          const response = await opts.next(...);
    

          // Ajoutez ici la logique à exécuter après la procédure
    

          return response;
       });
    };

    Dans notre cas, nous voulons extraire les détails de l’utilisateur Cognito appelant. Nous le ferons en extrayant l’ID de sujet (ou “sub”) de l’utilisateur depuis l’événement API Gateway, et en récupérant les détails de l’utilisateur depuis Cognito. L’implémentation varie légèrement selon que l’événement est fourni par une API REST ou HTTP :

    import { CognitoIdentityProvider } from '@aws-sdk/client-cognito-identity-provider';
    import { initTRPC, TRPCError } from '@trpc/server';
    import { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
    import { APIGatewayProxyEvent } from 'aws-lambda';
    

    export interface IIdentityContext {
      identity?: {
        sub: string;
        username: string;
      };
    }
    

    export const createIdentityPlugin = () => {
      const t = initTRPC.context<IIdentityContext & CreateAWSLambdaContextOptions<APIGatewayProxyEvent>>().create();
    

      const cognito = new CognitoIdentityProvider();
    

      return t.procedure.use(async (opts) => {
        const cognitoAuthenticationProvider = opts.ctx.event.requestContext?.identity?.cognitoAuthenticationProvider;
    

        let sub: string | undefined = undefined;
        if (cognitoAuthenticationProvider) {
          const providerParts = cognitoAuthenticationProvider.split(':');
          sub = providerParts[providerParts.length - 1];
        }
    

        if (!sub) {
          throw new TRPCError({
            code: 'FORBIDDEN',
            message: `Impossible de déterminer l'utilisateur appelant`,
          });
        }
    

        const { Users } = await cognito.listUsers({
          // Suppose que l'ID du pool utilisateur est configuré dans l'environnement Lambda
          UserPoolId: process.env.USER_POOL_ID!,
          Limit: 1,
          Filter: `sub="${sub}"`,
        });
    

        if (!Users || Users.length !== 1) {
          throw new TRPCError({
            code: 'FORBIDDEN',
            message: `Aucun utilisateur trouvé avec l'ID de sujet ${sub}`,
          });
        }
    

        // Fournit l'identité aux autres procédures dans le contexte
        return await opts.next({
          ctx: {
            ...opts.ctx,
            identity: {
              sub,
              username: Users[0].Username!,
            },
          },
        });
      });
    };

    Déploiement de votre API tRPC

    Section intitulée « Déploiement de votre API tRPC »

    Le générateur d’API tRPC crée une infrastructure CDK ou Terraform en fonction du iacProvider sélectionné. Vous pouvez l’utiliser pour déployer votre API tRPC.

    Le construct CDK pour déployer votre API se trouve dans le dossier common/constructs. Vous pouvez l’utiliser dans une application CDK, par exemple :

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

    export class ExampleStack extends Stack {
       constructor(scope: Construct, id: string) {
          // Ajoutez l'API à votre stack
          const api = new MyApi(this, 'MyApi', {
            integrations: MyApi.defaultIntegrations(this).build(),
          });
       }
    }

    Ceci configure l’infrastructure de votre API, incluant une API REST ou HTTP AWS API Gateway, des fonctions AWS Lambda pour la logique métier, et l’authentification selon la méthode auth choisie.

    Si vous avez choisi d’utiliser l’authentification Cognito, vous devrez fournir la propriété identity au construct API :

    import { MyApi, UserIdentity } from ':my-scope/common-constructs';
    

    export class ExampleStack extends Stack {
      constructor(scope: Construct, id: string) {
        const identity = new UserIdentity(this, 'Identity');
    

        const api = new MyApi(this, 'MyApi', {
          integrations: MyApi.defaultIntegrations(this).build(),
          identity,
        });
      }
    }

    Le construct UserIdentity peut être généré en utilisant le générateur ts#react-website-auth

    Intégrations

    Section intitulée « Intégrations »

    Les constructs CDK pour l’API REST/HTTP sont configurés pour fournir une interface typée permettant de définir des intégrations pour chacune de vos opérations.

    Les constructs CDK offrent un support complet d’intégration typée comme décrit ci-dessous.

    Intégrations par défaut

    Section intitulée « Intégrations par défaut »

    Vous pouvez utiliser la méthode statique defaultIntegrations pour utiliser le modèle par défaut, qui définit une fonction AWS Lambda individuelle pour chaque opération :

    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });

    Accès aux intégrations

    Section intitulée « Accès aux intégrations »

    Vous pouvez accéder aux fonctions AWS Lambda sous-jacentes via la propriété integrations du construct API, de manière typée. Par exemple, si votre API définit une opération nommée sayHello et que vous devez ajouter des permissions à cette fonction, vous pouvez le faire comme suit :

    const api = new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
    

    // sayHello est typé selon les opérations définies dans votre API
    api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({
      effect: Effect.ALLOW,
      actions: [...],
      resources: [...],
    }));

    Personnalisation des options par défaut

    Section intitulée « Personnalisation des options par défaut »

    Si vous souhaitez personnaliser les options utilisées lors de la création des fonctions Lambda pour chaque intégration par défaut, vous pouvez utiliser la méthode withDefaultOptions. Par exemple, si vous voulez que toutes vos fonctions Lambda résident dans un VPC :

    const vpc = new Vpc(this, 'Vpc', ...);
    

    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this)
        .withDefaultOptions({
          vpc,
        })
        .build(),
    });

    Surcharge des intégrations

    Section intitulée « Surcharge des intégrations »

    Vous pouvez aussi surcharger les intégrations pour des opérations spécifiques en utilisant la méthode withOverrides. Chaque surcharge doit spécifier une propriété integration typée selon le construct CDK d’intégration approprié pour l’API HTTP ou REST. La méthode withOverrides est également typée. Par exemple, si vous voulez rediriger une API getDocumentation vers une documentation hébergée sur un site externe :

    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this)
        .withOverrides({
          getDocumentation: {
            integration: new HttpIntegration('https://example.com/documentation'),
          },
        })
        .build(),
    });

    Vous remarquerez que l’intégration surchargée n’a plus de propriété handler lorsqu’on y accède via api.integrations.getDocumentation.

    Vous pouvez ajouter des propriétés supplémentaires à une intégration qui seront également typées, permettant d’abstraire d’autres types d’intégration tout en conservant le typage. Par exemple, si vous avez créé une intégration S3 pour une API REST et que vous souhaitez référencer le bucket pour une opération particulière :

    const storageBucket = new Bucket(this, 'Bucket', { ... });
    

    const apiGatewayRole = new Role(this, 'ApiGatewayS3Role', {
      assumedBy: new ServicePrincipal('apigateway.amazonaws.com'),
    });
    

    storageBucket.grantRead(apiGatewayRole);
    

    const api = new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this)
        .withOverrides({
          getFile: {
            bucket: storageBucket,
            integration: new AwsIntegration({
              service: 's3',
              integrationHttpMethod: 'GET',
              path: `${storageBucket.bucketName}/{fileName}`,
              options: {
                credentialsRole: apiGatewayRole,
                requestParameters: {
                  'integration.request.path.fileName': 'method.request.querystring.fileName',
                },
                integrationResponses: [{ statusCode: '200' }],
              },
            }),
            options: {
              requestParameters: {
                'method.request.querystring.fileName': true,
              },
              methodResponses: [{
                statusCode: '200',
              }],
            }
          },
        })
        .build(),
    });
    

    // Plus tard, peut-être dans un autre fichier, vous pouvez accéder à la propriété bucket
    // que nous avons définie de manière typée
    api.integrations.getFile.bucket.grantRead(...);

    Surcharge des autorisations

    Section intitulée « Surcharge des autorisations »

    Vous pouvez aussi fournir des options dans votre intégration pour surcharger des options de méthode spécifiques comme les autorisations. Par exemple, si vous souhaitez utiliser l’authentification Cognito pour votre opération getDocumentation :

    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this)
        .withOverrides({
          getDocumentation: {
            integration: new HttpIntegration('https://example.com/documentation'),
            options: {
              authorizer: new CognitoUserPoolsAuthorizer(...) // pour REST, ou HttpUserPoolAuthorizer pour une API HTTP
            }
          },
        })
        .build(),
    });

    Intégrations explicites

    Section intitulée « Intégrations explicites »

    Si vous préférez, vous pouvez choisir de ne pas utiliser les intégrations par défaut et fournir directement une intégration pour chaque opération. Ceci est utile si, par exemple, chaque opération nécessite un type d’intégration différent ou si vous voulez obtenir une erreur de type lors de l’ajout de nouvelles opérations :

    new MyApi(this, 'MyApi', {
      integrations: {
        sayHello: {
          integration: new LambdaIntegration(...),
        },
        getDocumentation: {
          integration: new HttpIntegration(...),
        },
      },
    });

    Modèle Router

    Section intitulée « Modèle Router »

    Si vous préférez déployer une seule fonction Lambda pour gérer toutes les requêtes API, vous pouvez librement modifier la méthode defaultIntegrations de votre API pour créer une seule fonction au lieu d’une par intégration :

    packages/common/constructs/src/app/apis/my-api.ts
    export class MyApi<...> extends ... {
    

      public static defaultIntegrations = (scope: Construct) => {
        const router = new Function(scope, 'RouterHandler', { ... });
        return IntegrationBuilder.rest({
          ...
          defaultIntegrationOptions: {},
          buildDefaultIntegration: (op) => {
            return {
              # Référencer le même handler router dans chaque intégration
              integration: new LambdaIntegration(router),
            };
          },
        });
      };
    }

    Vous pouvez modifier le code selon vos préférences, par exemple définir la fonction router comme paramètre de defaultIntegrations au lieu de la construire dans la méthode.

    Si vous avez choisi CDK comme iacProvider, lorsque vous ajoutez ou supprimez une procédure dans votre API tRPC, ces changements seront reflétés immédiatement dans le construct CDK sans avoir à reconstruire.

    Octroi d’accès (IAM uniquement)

    Section intitulée « Octroi d’accès (IAM uniquement) »

    Si vous avez choisi d’utiliser l’authentification IAM, vous pouvez octroyer l’accès à votre API :

    api.grantInvokeAccess(myIdentityPool.authenticatedRole);

    Serveur tRPC local

    Section intitulée « Serveur tRPC local »

    Vous pouvez utiliser la cible serve pour exécuter un serveur local pour votre API, par exemple :

    Terminal window
    pnpm nx run @my-scope/my-api:serve

    Le point d’entrée du serveur local est src/local-server.ts.

    Celui-ci se rechargera automatiquement lorsque vous modifierez votre API.

    Appel de votre API tRPC

    Section intitulée « Appel de votre API tRPC »

    Vous pouvez créer un client tRPC pour appeler votre API de manière typée. Si vous appelez votre API tRPC depuis un autre backend, vous pouvez utiliser le client dans src/client/index.ts, par exemple :

    import { createMyApiClient } from ':my-scope/my-api';
    

    const client = createMyApiClient({ url: 'https://my-api-url.example.com/' });
    

    await client.echo.query({ message: 'Hello world!' });

    Si vous appelez votre API depuis un site React, envisagez d’utiliser le générateur Connexion API pour configurer le client.

    Plus d’informations

    Section intitulée « Plus d’informations »

    Pour plus d’informations sur tRPC, référez-vous à la documentation tRPC.