Saltearse al contenido
@aws/nx-plugin
Blog

tRPC

tRPC es un framework para construir APIs en TypeScript con seguridad de tipos de extremo a extremo. Con tRPC, las actualizaciones en las entradas y salidas de las operaciones de la API se reflejan inmediatamente en el código del cliente y son visibles en tu IDE sin necesidad de reconstruir tu proyecto.

El generador de API tRPC crea una nueva API tRPC con configuración de infraestructura en AWS CDK o Terraform. El backend generado utiliza AWS Lambda para despliegues serverless, expuesto a través de una API de AWS API Gateway, e incluye validación de esquemas usando Zod. Configura AWS Lambda Powertools para observabilidad, incluyendo logging, trazado con AWS X-Ray y métricas de CloudWatch.

Uso

Sección titulada «Uso»

Generar una API tRPC

Sección titulada «Generar una API tRPC»

Puedes generar una nueva API tRPC de dos formas:

  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 - ts#trpc-api
  5. Complete los parámetros requeridos
    • Haga clic en Generate

    Opciones

    Sección titulada «Opciones»
    Parámetro Tipo Predeterminado Descripción
    name Requerido 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

    Salida del Generador

    Sección titulada «Salida del Generador»

    El generador creará la siguiente estructura de proyecto en el directorio <directory>/<api-name>:

    • Directorysrc
      • init.ts Inicialización del backend tRPC
      • router.ts Definición del router tRPC (punto de entrada del handler Lambda)
      • Directoryschema Definiciones de esquemas usando Zod
        • echo.ts Ejemplo de definiciones para entrada y salida del procedimiento “echo”
      • Directoryprocedures Procedimientos (u operaciones) expuestos por tu API
        • echo.ts Procedimiento de ejemplo
      • Directorymiddleware
        • error.ts Middleware para manejo de errores
        • logger.ts Middleware para configurar AWS Powertools para logging en Lambda
        • tracer.ts Middleware para configurar AWS Powertools para trazado en Lambda
        • metrics.ts Middleware para configurar AWS Powertools para métricas en Lambda
      • local-server.ts Punto de entrada del adaptador standalone de tRPC para servidor de desarrollo local
      • Directoryclient
        • index.ts Cliente tipado para llamadas máquina-a-máquina a la API
    • tsconfig.json Configuración de TypeScript
    • project.json Configuración de proyecto y targets de build

    Infraestructura

    Sección titulada «Infraestructura»

    Dado que este generador proporciona infraestructura como código basada en tu proveedor de iacProvider seleccionado, creará un proyecto en packages/common que incluye los constructos CDK o módulos de Terraform correspondientes.

    El proyecto común de infraestructura como código tiene la siguiente estructura:

    • Directorypackages/common/constructs
      • Directorysrc
        • Directoryapp/ Constructos para infraestructura específica de un proyecto/generador
          • …
        • Directorycore/ Constructos genéricos reutilizados por los constructos en app
          • …
        • index.ts Punto de entrada que exporta los constructos de app
      • project.json Objetivos de compilación y configuración del proyecto

    Para implementar tu API, se generan los siguientes archivos:

    • Directorypackages/common/constructs/src
      • Directoryapp
        • Directoryapis
          • <project-name>.ts Constructo de CDK para implementar tu API
      • Directorycore
        • Directoryapi
          • http-api.ts Constructo de CDK para implementar una API HTTP (si seleccionaste implementar una API HTTP)
          • rest-api.ts Constructo de CDK para implementar una API REST (si seleccionaste implementar una API REST)
          • utils.ts Utilidades para los constructos de API

    Implementando tu API tRPC

    Sección titulada «Implementando tu API tRPC»

    En términos generales, las API tRPC constan de un router que delega solicitudes a procedimientos específicos. Cada procedimiento tiene una entrada y salida definidas como esquemas Zod.

    Esquema

    Sección titulada «Esquema»

    El directorio src/schema contiene los tipos compartidos entre tu código cliente y servidor. En este paquete, estos tipos se definen usando Zod, una biblioteca TypeScript-first para declaración y validación de esquemas.

    Un esquema de ejemplo podría verse así:

    import { z } from 'zod';
    

    // Definición del esquema
    export const UserSchema = z.object({
      name: z.string(),
      height: z.number(),
      dateOfBirth: z.string().datetime(),
    });
    

    // Tipo TypeScript correspondiente
    export type User = z.TypeOf<typeof UserSchema>;

    Dado el esquema anterior, el tipo User es equivalente al siguiente TypeScript:

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

    Los esquemas son compartidos por el código del cliente y servidor, proporcionando un único lugar para actualizar cuando se realizan cambios en las estructuras usadas en tu API.

    Los esquemas son validados automáticamente por tu API tRPC en tiempo de ejecución, lo que evita tener que crear lógica de validación manual en el backend.

    Zod proporciona utilidades poderosas para combinar o derivar esquemas como .merge, .pick, .omit y más. Puedes encontrar más información en el sitio de documentación de Zod.

    Router y Procedimientos

    Sección titulada «Router y Procedimientos»

    El punto de entrada de tu API se encuentra en src/router.ts. Este archivo contiene el handler Lambda que enruta las solicitudes a “procedimientos” basados en la operación invocada. Cada procedimiento define la entrada esperada, la salida y la implementación.

    El router de ejemplo generado para ti tiene una sola operación llamada echo:

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

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

    El procedimiento echo de ejemplo se genera en src/procedures/echo.ts:

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

    Desglosando lo anterior:

    • publicProcedure define un método público en la API, incluyendo el middleware configurado en src/middleware. Este middleware incluye integración con AWS Lambda Powertools para logging, trazado y métricas.
    • input acepta un esquema Zod que define la entrada esperada para la operación. Las solicitudes para esta operación se validan automáticamente contra este esquema.
    • output acepta un esquema Zod que define la salida esperada. Verás errores de tipo en tu implementación si no devuelves una salida que cumpla con el esquema.
    • query acepta una función que define la implementación de tu API. Esta implementación recibe opts, que contiene el input pasado a tu operación, así como otro contexto configurado por el middleware, disponible en opts.ctx. La función pasada a query debe devolver una salida que cumpla con el esquema de output.

    El uso de query para definir la implementación indica que la operación no es mutativa. Úsalo para definir métodos de recuperación de datos. Para operaciones mutativas, usa el método mutation en su lugar.

    Si agregas un nuevo procedimiento, asegúrate de registrarlo añadiéndolo al router en src/router.ts.

    Personalizando tu API tRPC

    Sección titulada «Personalizando tu API tRPC»

    Errores

    Sección titulada «Errores»

    En tu implementación, puedes devolver respuestas de error a los clientes lanzando un TRPCError. Estos aceptan un code que indica el tipo de error, por ejemplo:

    throw new TRPCError({
      code: 'NOT_FOUND',
      message: 'El recurso solicitado no pudo ser encontrado',
    });

    Organizando tus Operaciones

    Sección titulada «Organizando tus Operaciones»

    A medida que tu API crece, puedes querer agrupar operaciones relacionadas.

    Puedes agrupar operaciones usando routers anidados, por ejemplo:

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

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

    Los clientes entonces reciben esta agrupación de operaciones, por ejemplo, invocar la operación listUsers se vería así:

    client.users.list.query();

    Logging

    Sección titulada «Logging»

    El logger de AWS Lambda Powertools se configura en src/middleware/logger.ts, y se puede acceder a él en una implementación de API via opts.ctx.logger. Puedes usarlo para registrar en CloudWatch Logs, y/o controlar valores adicionales a incluir en cada mensaje de log estructurado. Por ejemplo:

    export const echo = publicProcedure
       .input(...)
       .output(...)
       .query(async (opts) => {
          opts.ctx.logger.info('Operación llamada con input', opts.input);
    

          return ...;
       });

    Para más información sobre el logger, consulta la documentación de AWS Lambda Powertools Logger.

    Registro de Métricas

    Sección titulada «Registro de Métricas»

    Las métricas de AWS Lambda Powertools se configuran en src/middleware/metrics.ts, y se puede acceder a ellas en una implementación de API via opts.ctx.metrics. Puedes usarlas para registrar métricas en CloudWatch sin necesidad de importar y usar el AWS SDK, por ejemplo:

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

          return ...;
       });

    Para más información, consulta la documentación de AWS Lambda Powertools Metrics.

    Ajuste Fino de Trazado con X-Ray

    Sección titulada «Ajuste Fino de Trazado con X-Ray»

    El tracer de AWS Lambda Powertools se configura en src/middleware/tracer.ts, y se puede acceder a él en una implementación de API via opts.ctx.tracer. Puedes usarlo para agregar trazas con AWS X-Ray y obtener insights detallados sobre el rendimiento y flujo de las solicitudes de la API. Por ejemplo:

    export const echo = publicProcedure
       .input(...)
       .output(...)
       .query(async (opts) => {
          const subSegment = opts.ctx.tracer.getSegment()!.addNewSubsegment('MiAlgoritmo');
          // ... lógica de mi algoritmo para capturar
          subSegment.close();
    

          return ...;
       });

    Para más información, consulta la documentación de AWS Lambda Powertools Tracer.

    Implementando Middleware Personalizado

    Sección titulada «Implementando Middleware Personalizado»

    Puedes agregar valores adicionales al contexto proporcionado a los procedimientos implementando middleware.

    Como ejemplo, implementemos un middleware para extraer detalles del usuario que llama a nuestra API en src/middleware/identity.ts.

    Este ejemplo asume que auth se configuró como IAM. Para autenticación con Cognito, el middleware de identidad es más directo, extrayendo los claims relevantes del event.

    Primero, definimos lo que agregaremos al contexto:

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

    Nota que definimos una propiedad adicional opcional al contexto. tRPC se encarga de asegurar que esto esté definido en procedimientos que hayan configurado correctamente este middleware.

    Luego, implementamos el middleware mismo. Tiene la siguiente estructura:

    export const createIdentityPlugin = () => {
       const t = initTRPC.context<...>().create();
       return t.procedure.use(async (opts) => {
          // Agrega lógica aquí para ejecutar antes del procedimiento
    

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

          // Agrega lógica aquí para ejecutar después del procedimiento
    

          return response;
       });
    };

    En nuestro caso, queremos extraer detalles del usuario de Cognito que llama. Hacemos esto extrayendo el ID de sujeto (o “sub”) del usuario del evento de API Gateway, y recuperando detalles del usuario desde Cognito. La implementación varía ligeramente dependiendo de si el evento fue proporcionado por una REST API o una HTTP API:

    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: `No se pudo determinar el usuario llamante`,
          });
        }
    

        const { Users } = await cognito.listUsers({
          // Asume que el ID del user pool está configurado en el entorno de Lambda
          UserPoolId: process.env.USER_POOL_ID!,
          Limit: 1,
          Filter: `sub="${sub}"`,
        });
    

        if (!Users || Users.length !== 1) {
          throw new TRPCError({
            code: 'FORBIDDEN',
            message: `No se encontró usuario con subjectId ${sub}`,
          });
        }
    

        // Proporciona la identidad a otros procedimientos en el contexto
        return await opts.next({
          ctx: {
            ...opts.ctx,
            identity: {
              sub,
              username: Users[0].Username!,
            },
          },
        });
      });
    };

    Desplegando tu API tRPC

    Sección titulada «Desplegando tu API tRPC»

    El generador de API tRPC crea código de infraestructura con CDK o Terraform basado en tu iacProvider seleccionado. Puedes usar esto para desplegar tu API tRPC.

    El constructo CDK para desplegar tu API está en la carpeta common/constructs. Puedes consumirlo en una aplicación CDK, por ejemplo:

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

    export class ExampleStack extends Stack {
       constructor(scope: Construct, id: string) {
          // Agrega la API a tu stack
          const api = new MyApi(this, 'MyApi', {
            integrations: MyApi.defaultIntegrations(this).build(),
          });
       }
    }

    Esto configura la infraestructura de tu API, incluyendo una REST API o HTTP API de AWS API Gateway, funciones AWS Lambda para la lógica de negocio, y autenticación basada en tu método auth elegido.

    Integraciones

    Sección titulada «Integraciones»

    Los constructos CDK de la API REST/HTTP están configurados para proporcionar una interfaz type-safe que define integraciones para cada una de tus operaciones.

    Los constructos CDK proporcionan soporte completo de integración con seguridad de tipos como se describe a continuación.

    Integraciones por defecto

    Sección titulada «Integraciones por defecto»

    Puedes usar el método estático defaultIntegrations para utilizar el patrón por defecto, que define una función AWS Lambda individual para cada operación:

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

    Accediendo a las integraciones

    Sección titulada «Accediendo a las integraciones»

    Puedes acceder a las funciones AWS Lambda subyacentes a través de la propiedad integrations del constructo de la API, de manera type-safe. Por ejemplo, si tu API define una operación llamada sayHello y necesitas agregar permisos a esta función, puedes hacerlo así:

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

    // sayHello está tipado según las operaciones definidas en tu API
    api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({
      effect: Effect.ALLOW,
      actions: [...],
      resources: [...],
    }));

    Personalizando opciones por defecto

    Sección titulada «Personalizando opciones por defecto»

    Si deseas personalizar las opciones usadas al crear la función Lambda para cada integración por defecto, puedes usar el método withDefaultOptions. Por ejemplo, si quieres que todas tus funciones Lambda residan en una VPC:

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

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

    Sobrescribiendo integraciones

    Sección titulada «Sobrescribiendo integraciones»

    También puedes sobrescribir integraciones para operaciones específicas usando el método withOverrides. Cada override debe especificar una propiedad integration que está tipada al constructo de integración CDK apropiado para la API HTTP o REST. El método withOverrides también es type-safe. Por ejemplo, si quieres sobrescribir una API getDocumentation para apuntar a documentación alojada en un sitio externo:

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

    Notarás que la integración sobrescrita ya no tiene una propiedad handler cuando se accede a través de api.integrations.getDocumentation.

    Puedes agregar propiedades adicionales a una integración que también estarán tipadas, permitiendo abstraer otros tipos de integración manteniendo el type-safe. Por ejemplo, si creaste una integración S3 para una API REST y luego quieres referenciar el bucket para una operación particular:

    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(),
    });
    

    // Más tarde, quizás en otro archivo, puedes acceder a la propiedad bucket que definimos
    // de manera type-safe
    api.integrations.getFile.bucket.grantRead(...);

    Sobrescribiendo autorizadores

    Sección titulada «Sobrescribiendo autorizadores»

    También puedes proveer options en tu integración para sobrescribir opciones de método específicas como autorizadores. Por ejemplo, si deseas usar autenticación con Cognito para tu operación getDocumentation:

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

    Integraciones explícitas

    Sección titulada «Integraciones explícitas»

    Si prefieres, puedes no usar las integraciones por defecto y proveer directamente una para cada operación. Esto es útil si, por ejemplo, cada operación necesita usar un tipo diferente de integración o quieres recibir un error de tipo al agregar nuevas operaciones:

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

    Patrón Router

    Sección titulada «Patrón Router»

    Si prefieres desplegar una única función Lambda para manejar todas las solicitudes de la API, puedes modificar libremente el método defaultIntegrations de tu API para crear una sola función en lugar de una por integración:

    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 {
              // Referenciar el mismo router lambda handler en cada integración
              integration: new LambdaIntegration(router),
            };
          },
        });
      };
    }

    Puedes modificar el código de otras formas si prefieres, por ejemplo definiendo la función router como parámetro de defaultIntegrations en lugar de construirla dentro del método.

    Otorgando Acceso (Solo IAM)

    Sección titulada «Otorgando Acceso (Solo IAM)»

    Si seleccionaste usar autenticación IAM, puedes otorgar acceso a tu API:

    api.grantInvokeAccess(myIdentityPool.authenticatedRole);

    Servidor tRPC Local

    Sección titulada «Servidor tRPC Local»

    Puedes usar el target serve para ejecutar un servidor local para tu API, por ejemplo:

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

    El punto de entrada para el servidor local es src/local-server.ts.

    Esto se recargará automáticamente cuando hagas cambios en tu API.

    Invocando tu API tRPC

    Sección titulada «Invocando tu API tRPC»

    Puedes crear un cliente tRPC para invocar tu API de manera tipada. Si estás llamando a tu API tRPC desde otro backend, puedes usar el cliente en src/client/index.ts, por ejemplo:

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

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

    await client.echo.query({ message: '¡Hola mundo!' });

    Si estás llamando a tu API desde un sitio React, considera usar el generador Conexión de API para configurar el cliente.

    Más Información

    Sección titulada «Más Información»

    Para más información sobre tRPC, consulta la documentación de tRPC.