Ir al contenido
@aws/nx-plugin
Blog

tRPC

Filter this guidePick generator option values to hide sections that don't apply.

tRPC es un framework para construir APIs en TypeScript con seguridad de tipos de extremo a extremo. Usando tRPC, las actualizaciones a 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 AWS CDK o Terraform. El backend generado utiliza AWS Lambda para despliegue 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 de 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 maneras:

Terminal window
pnpm nx g @aws/nx-plugin:ts#api --framework=trpc
También puede realizar una ejecución en seco para ver qué archivos se cambiarían
Terminal window
pnpm nx g @aws/nx-plugin:ts#api --framework=trpc --dry-run

Opciones

Sección titulada «Opciones»
ParámetroTipoPredeterminadoDescripción
name Requeridostring-El nombre de la API (requerido). Se utiliza para generar nombres de clases y rutas de archivos.
framework trpc | smithytrpcEl framework de API a utilizar.
namespace string-El espacio de nombres para la API Smithy (solo aplicable para el framework smithy). Por defecto es el alcance de tu monorepo
integrationPattern isolated | sharedisolatedCómo se generan las integraciones de API Gateway para la API. Elija entre isolated (predeterminado) y shared.
auth iam | cognito | customiamEl método utilizado para autenticar con tu API. Elige entre iam (predeterminado), cognito o custom.
directory stringpackagesEl directorio donde almacenar la aplicación.
subDirectory string-El subdirectorio en el que se coloca el proyecto. Por defecto es el nombre del proyecto.
iac inherit | cdk | terraforminheritEl proveedor de IaC preferido. Por defecto, se hereda de tu selección inicial.
infra rest-lambda | http-lambda | nonerest-lambdaEl tipo de infraestructura a utilizar para desplegar esta API.
preferInstallDependencies booleantrueSi se prefiere instalar las dependencias después de que se ejecute el generador. Establece en false para diferir la instalación cuando se ejecutan múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsecuentes puedan calcular el grafo de proyectos de Nx); instala una vez al final.

Salida del Generador

Sección titulada «Salida del Generador»

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

  • Directoriosrc
    • init.ts Backend tRPC initialisation
    • handler.ts Lambda handler entrypoint
    • router.ts tRPC router definition
    • Directorioschema Schema definitions using Zod
      • echo.ts Example definitions for the input and output of the “echo” procedure
      • z-async-iterable.ts Zod helper for subscriptions (REST API only)
    • Directorioprocedures Procedures (or operations) exposed by your API
      • echo.ts Example procedure
    • Directoriomiddleware
      • error.ts Middleware for error handling
      • logger.ts middleware for configuring AWS Powertools for Lambda logging
      • tracer.ts middleware for configuring AWS Powertools for Lambda tracing
      • metrics.ts middleware for configuring AWS Powertools for Lambda metrics
    • local-server.ts tRPC standalone adapter entrypoint for local development server
    • Directorioclient
      • index.ts Type-safe client for machine-to-machine API calls
  • tsconfig.json TypeScript configuration
  • package.json Project manifest defining the project’s package name and dependencies
  • project.json Project configuration and build targets

Infraestructura

Sección titulada «Infraestructura»

Dado que este generador proporciona infraestructura como código basada en tu iac elegido, creará un proyecto en packages/common que incluye las construcciones CDK o módulos Terraform relevantes.

El proyecto común de infraestructura como código está estructurado de la siguiente manera:

  • Directoriopackages/common/constructs
    • Directoriosrc
      • Directorioapp/ Constructs for infrastructure specific to a project/generator
        • …
      • Directoriocore/ Generic constructs which are reused by constructs in app
        • …
      • index.ts Entry point exporting constructs from app
    • project.json Project build targets and configuration

Para desplegar tu API, se generan los siguientes archivos:

  • Directoriopackages/common/constructs/src
    • Directorioapp
      • Directorioapis
        • <project-name>.ts CDK construct for deploying your API
    • Directoriocore
      • Directorioapi
        • http-api.ts CDK construct for deploying an HTTP API (if you selected to deploy an HTTP API)
        • rest-api.ts CDK construct for deploying a REST API (if you selected to deploy a REST API)
        • utils.ts Utilities for the API constructs

Arquitectura

Sección titulada «Arquitectura»

La aplicación desplegada tiene la siguiente arquitectura:

ClientWAFAPI Gateway(REST API)LambdaCloudWatch(Logs, Metrics)X-Ray(Traces)

Las REST APIs incluyen una Web ACL de AWS WAFv2 frente a la etapa de API Gateway con el conjunto de reglas predeterminado administrado por AWS habilitado.

Implementando tu API tRPC

Sección titulada «Implementando tu API tRPC»

A alto nivel, las APIs tRPC consisten en un router que delega solicitudes a procedimientos específicos. Cada procedimiento tiene una entrada y una salida, definidas como un esquema Zod.

Esquema

Sección titulada «Esquema»

El directorio src/schema contiene los tipos que se comparten entre tu código de cliente y servidor. En este paquete, estos tipos se definen usando Zod, una biblioteca de declaración y validación de esquemas con TypeScript como prioridad.

Un esquema de ejemplo podría verse de la siguiente manera:

import { z } from 'zod';


// Schema definition
export const UserSchema = z.object({
  name: z.string(),
  height: z.number(),
  dateOfBirth: z.string().datetime(),
});


// Corresponding TypeScript type
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 tanto por el código del servidor como del cliente, proporcionando un único lugar para actualizar al hacer cambios en las estructuras utilizadas en tu API.

Los esquemas son validados automáticamente por tu API tRPC en tiempo de ejecución, lo que ahorra tener que crear lógica de validación personalizada en tu 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 web de documentación de Zod.

Router y Procedimientos

Sección titulada «Router y Procedimientos»

Tu router tRPC está definido en src/router.ts, que registra todos los procedimientos. Cada procedimiento define la entrada, salida e implementación esperadas. El punto de entrada del manejador Lambda está en src/handler.ts, que reenvía las solicitudes a tu router.

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 de ejemplo echo se genera para ti en src/procedures/echo.ts:

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

Para desglosar lo anterior:

  • publicProcedure define un método público en la API, incluyendo el middleware configurado en src/middleware. Este middleware incluye integración de 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 enviadas para esta operación se validan automáticamente contra este esquema.
  • output acepta un esquema Zod que define la salida esperada para la operación. Verás errores de tipo en tu implementación si no devuelves una salida que se ajuste al esquema.
  • query acepta una función que define la implementación para 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 se ajuste al esquema output.

El uso de query para definir la implementación indica que la operación no es mutativa. Usa esto para definir métodos para recuperar datos. Para implementar una operación mutativa, usa el método mutation en su lugar.

Si agregas un nuevo procedimiento, asegúrate de registrarlo agregándolo al router en src/router.ts.

infra = rest-lambda

Suscripciones (Streaming)

Sección titulada «Suscripciones (Streaming)»

Las suscripciones tRPC te permiten transmitir datos del servidor al cliente usando Server-Sent Events (SSE). Cuando seleccionas rest-lambda como tu tipo de cómputo, el generador configura automáticamente la infraestructura requerida para streaming, así como un manejador Lambda de streaming y el helper de esquema ZodAsyncIterable.

Para definir un procedimiento de suscripción, usa el método .subscription con una función generadora asíncrona. Usa el helper ZodAsyncIterable de src/schema/z-async-iterable.ts para definir el esquema de salida:

import { publicProcedure } from '../init.js';
import { z } from 'zod';
import { ZodAsyncIterable } from '../schema/z-async-iterable.js';


const InputSchema = z.object({ query: z.string() });
const ChunkSchema = z.object({ text: z.string() });


export const myStream = publicProcedure
  .input(InputSchema)
  .output(
    ZodAsyncIterable({
      yield: ChunkSchema,
    }),
  )
  .subscription(async function* (opts) {
    // Yield data to the client as it becomes available
    for (const chunk of await getResults(opts.input.query)) {
      yield { text: chunk };
    }
  });

Registra la suscripción en tu router como cualquier otro procedimiento:

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

La infraestructura generada usa un manejador Lambda de streaming con ResponseTransferMode.STREAM en API Gateway para todas las operaciones de la API REST, lo que permite que las suscripciones funcionen junto con consultas y mutaciones regulares.

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: 'The requested resource could not be found',
});

Organizando tus Operaciones

Sección titulada «Organizando tus Operaciones»

A medida que tu API crece, es posible que desees 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 reciben esta agrupación de operaciones, por ejemplo, invocar la operación listUsers en este caso podría verse de la siguiente manera:

client.users.list.query();

Logging

Sección titulada «Logging»

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

export const echo = publicProcedure
   .input(...)
   .output(...)
   .query(async (opts) => {
      opts.ctx.logger.info('Operation called with input', opts.input);


      return ...;
   });

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

Registrando Métricas

Sección titulada «Registrando Métricas»

Las métricas de AWS Lambda Powertools están configuradas en src/middleware/metrics.ts, y se puede acceder a ellas en una implementación de API a través de opts.ctx.metrics. Puedes usar esto 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('Invocations', 'Count', 1);


      return ...;
   });

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

Ajustando el Trazado X-Ray

Sección titulada «Ajustando el Trazado X-Ray»

El tracer de AWS Lambda Powertools está configurado en src/middleware/tracer.ts, y se puede acceder a él en una implementación de API a través de opts.ctx.tracer. Puedes usar esto para agregar trazas con AWS X-Ray para proporcionar información detallada sobre el rendimiento y el flujo de las solicitudes de API. Por ejemplo:

export const echo = publicProcedure
   .input(...)
   .output(...)
   .query(async (opts) => {
      const subSegment = opts.ctx.tracer.getSegment()!.addNewSubsegment('MyAlgorithm');
      // ... my algorithm logic to capture
      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 algunos detalles sobre el usuario que llama a nuestra API en src/middleware/identity.ts.

auth = iam

Este ejemplo recorre el middleware de identidad para autenticación IAM. Buscamos al llamador en Cognito usando el sub extraído del evento de API Gateway.

Primero, definimos lo que agregaremos al contexto:

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

Ten en cuenta que definimos una propiedad adicional opcional en el contexto. tRPC se encarga de asegurar que esto esté definido en los procedimientos que han configurado correctamente este middleware.

A continuación, implementaremos el middleware en sí. Esto tiene la siguiente estructura:

export const createIdentityPlugin = () => {
   const t = initTRPC.context<...>().create();
   return t.procedure.use(async (opts) => {
      // Add logic here to run before the procedure


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


      // Add logic here to run after the procedure


      return response;
   });
};

En nuestro caso, queremos extraer detalles sobre el usuario de Cognito que llama. Lo haremos extrayendo el ID de sujeto del usuario (o “sub”) del evento de API Gateway, y recuperando los detalles del usuario de Cognito. La implementación varía dependiendo de si el evento fue proporcionado a nuestra función por una API REST o una API 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: `Unable to determine calling user`,
      });
    }


    const { Users } = await cognito.listUsers({
      // Assumes user pool id is configured in lambda environment
      UserPoolId: process.env.USER_POOL_ID!,
      Limit: 1,
      Filter: `sub="${sub}"`,
    });


    if (!Users || Users.length !== 1) {
      throw new TRPCError({
        code: 'FORBIDDEN',
        message: `No user found with subjectId ${sub}`,
      });
    }


    // Provide the identity to other procedures in the context
    return await opts.next({
      ctx: {
        ...opts.ctx,
        identity: {
          sub,
          username: Users[0].Username!,
        },
      },
    });
  });
};
auth = cognito

Cuando despliegas con auth: 'cognito', el autorizador de Cognito de API Gateway verifica el JWT que el llamador proporciona en el encabezado Authorization y coloca las reclamaciones verificadas en el evento Lambda. Nuestro middleware simplemente lee esas reclamaciones: sin llamadas adicionales al AWS SDK, sin verificación manual de JWT.

Primero, definimos lo que agregaremos al contexto:

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

Ten en cuenta que definimos una propiedad adicional opcional en el contexto. tRPC se encarga de asegurar que esto esté definido en los procedimientos que han configurado correctamente este middleware.

A continuación, el middleware en sí:

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


  return t.procedure.use(async (opts) => {
    const claims = opts.ctx.event.requestContext?.authorizer?.claims as
      | Record<string, string>
      | undefined;


    const sub = claims?.sub;
    const username = claims?.username;


    if (!sub || !username) {
      throw new TRPCError({
        code: 'FORBIDDEN',
        message: 'Unable to determine calling user',
      });
    }


    return await opts.next({
      ctx: {
        ...opts.ctx,
        identity: {
          sub,
          username,
        },
      },
    });
  });
};

Luego puedes mezclar el plugin en cualquier procedimiento que necesite la identidad del llamador:

import { publicProcedure } from '../init.js';
import { createIdentityPlugin } from '../middleware/identity.js';
import { z } from 'zod';


export const me = publicProcedure
  .concat(createIdentityPlugin())
  .output(z.object({ sub: z.string(), username: z.string() }))
  .query(({ ctx }) => ({
    sub: ctx.identity!.sub,
    username: ctx.identity!.username,
  }));

Desplegando tu API tRPC

Sección titulada «Desplegando tu API tRPC»

El generador de API tRPC crea infraestructura como código CDK o Terraform basada en tu iac seleccionado. Puedes usar esto para desplegar tu API tRPC.

El constructo CDK para desplegar tu API se encuentra en la carpeta common/constructs. Puedes consumir esto en una aplicación CDK, por ejemplo:

auth = iam | custom
import { MyApi } from '@my-scope/common-constructs';


export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Add the api to your stack
    const api = new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}
auth = cognito
import { MyApi, UserIdentity } from '@my-scope/common-constructs';


export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Add the api to your stack
    const identity = new UserIdentity(this, 'Identity');


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

El constructo UserIdentity puede ser generado usando el generador ts#website#auth.

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

infra = rest-lambda

WAF

Sección titulada «WAF»

Para las API REST, el constructo generado asocia una Web ACL de AWS WAFv2 con la etapa de API Gateway de forma predeterminada. La Web ACL utiliza el conjunto de reglas predeterminado administrado por AWS (AWSManagedRulesCommonRuleSet y AWSManagedRulesKnownBadInputsRuleSet), proporcionando protección contra exploits web comunes, incluidos los OWASP Top 10. Los registros de solicitudes de WAF se escriben en un grupo de CloudWatch Logs.

Puedes editar el constructo rest-api generado para agregar, eliminar o ajustar reglas (por ejemplo, para agregar reglas basadas en tasa o grupos de reglas administradas adicionales).

Para optar por no participar (por ejemplo, para adjuntar tu propia Web ACL), establece enableWaf en false:

const api = new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this).build(),
  enableWaf: false,
});
infra = rest-lambda

Registro de acceso

Sección titulada «Registro de acceso»

Para las REST APIs, la infraestructura generada habilita el registro de acceso de forma predeterminada, escribiendo una línea JSON estructurada por solicitud en un grupo de CloudWatch Logs dedicado. El grupo de logs está cifrado con una clave KMS administrada por el cliente y se retiene durante un año.

API Gateway escribe los logs de acceso utilizando un rol de CloudWatch Logs a nivel de cuenta. Este rol se configura en la configuración AWS::ApiGateway::Account, que es un singleton por región por cuenta: solo hay un rol para cada REST API en la región. Para gestionar esto de forma segura en múltiples stacks implementados de forma independiente, la infraestructura generada:

  • Crea un rol compartido de CloudWatch Logs y lo configura en la cuenta solo cuando no hay un rol funcional ya establecido, por lo que las implementaciones nunca sobrescriben un rol que pertenece a otro stack.
  • Deja la configuración de la cuenta intacta durante el desmontaje, por lo que destruir un stack nunca deshabilita el registro para otras REST APIs en la región.

El rol de cuenta es gestionado por el constructo ApiGatewayAccount, un singleton con ámbito de stack resuelto mediante ApiGatewayAccount.ensure(scope). La etapa de cada REST API depende de él, y el rol se configura mediante un recurso personalizado respaldado por Lambda.

El formato del log de acceso es establecido por el constructo RestApi que tu API extiende. Para personalizarlo, pasa deployOptions a super en el archivo generado packages/common/constructs/src/app/apis/my-api.ts, manteniendo el tracingEnabled que el constructo ya establece:

packages/common/constructs/src/app/apis/my-api.ts
super(scope, id, {
  apiName: 'MyApi',
  // ...
  deployOptions: {
    tracingEnabled: true,
    accessLogFormat: AccessLogFormat.clf(),
  },
  ...props,
});

AccessLogFormat se importa desde aws-cdk-lib/aws-apigateway. Cualquier cosa que dejes sin configurar mantiene el valor predeterminado del constructo: un formato JSON con los campos estándar.

Integraciones

Sección titulada «Integraciones»

Los constructos CDK de API REST/HTTP están configurados para proporcionar una interfaz con seguridad de tipos para definir integraciones para cada una de sus operaciones.

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

Integraciones Predeterminadas

Sección titulada «Integraciones Predeterminadas»

Puede usar el método estático defaultIntegrations para hacer uso del patrón predeterminado, que define una función AWS Lambda individual para cada operación:

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

Acceso a Integraciones

Sección titulada «Acceso a Integraciones»

Puede acceder a las funciones AWS Lambda subyacentes a través de la propiedad integrations del constructo de API, de manera segura en cuanto a tipos. Por ejemplo, si su API define una operación llamada sayHello y necesita agregar algunos permisos a esta función, puede hacerlo de la siguiente manera:

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


// sayHello is typed to the operations defined in your API
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({
  effect: Effect.ALLOW,
  actions: [...],
  resources: [...],
}));

Si su API utiliza el patrón shared, el enrutador Lambda compartido se expone como api.integrations.$router:

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


api.integrations.$router.handler.addEnvironment('LOG_LEVEL', 'DEBUG');

Personalización de Opciones Predeterminadas

Sección titulada «Personalización de Opciones Predeterminadas»

Si desea personalizar las opciones utilizadas al crear la función Lambda para cada integración predeterminada, puede usar el método withDefaultOptions. Por ejemplo, si desea que todas sus funciones Lambda residan en una Vpc:

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


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

Personalización de Opciones por Operación

Sección titulada «Personalización de Opciones por Operación»

Para personalizar las opciones utilizadas para crear la integración predeterminada para operaciones específicas (sin afectar a las demás), puede usar el método withOperationOptions. Por ejemplo, si desea aumentar el tiempo de espera de la función Lambda para solo una operación:

const api = new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withOperationOptions({
      sayHello: {
        timeout: Duration.seconds(60),
      },
    })
    .build(),
});


// The selected operations remain default integrations, so they're still typed accordingly:
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({ ... }));

Las opciones que especifique se fusionan con las opciones de integración predeterminadas (y cualquier opción establecida a través de withDefaultOptions). Tenga en cuenta que no puede especificar opciones para operaciones que haya reemplazado a través de withOverrides, ya que estas ya no usan la integración predeterminada.

Encontrará un error de tipo si la misma operación es objetivo tanto de withOperationOptions como de withOverrides, independientemente del orden en que los llame.

Anulación de Integraciones

Sección titulada «Anulación de Integraciones»

También puede anular integraciones para operaciones específicas usando el método withOverrides. Cada anulación 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 seguro en cuanto a tipos. Por ejemplo, si desea anular una API getDocumentation para que apunte a documentación alojada por algún sitio web externo, podría lograrlo de la siguiente manera:

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

También notará que la integración anulada ya no tiene una propiedad handler al acceder a ella a través de api.integrations.getDocumentation.

Puede agregar propiedades adicionales a una integración que también se tipará en consecuencia, permitiendo que otros tipos de integración se abstraigan pero permanezcan seguros en cuanto a tipos, por ejemplo, si ha creado una integración S3 para una API REST y luego desea hacer referencia al bucket para una operación en particular, puede hacerlo de la siguiente manera:

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


// Later, perhaps in another file, you can access the bucket property we defined
// in a type-safe manner
api.integrations.getFile.bucket.grantRead(...);

Anulación de Autorizadores

Sección titulada «Anulación de Autorizadores»

También puede proporcionar options en su integración para anular opciones de método particulares como autorizadores, por ejemplo, si desea usar autenticación Cognito para su operación getDocumentation:

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

Integraciones Explícitas

Sección titulada «Integraciones Explícitas»

Si lo prefiere, puede optar por no usar las integraciones predeterminadas y en su lugar proporcionar directamente una para cada operación. Esto es útil si, por ejemplo, cada operación necesita usar un tipo diferente de integración o si desea recibir un error de tipo al agregar nuevas operaciones:

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

Patrón de Integración

Sección titulada «Patrón de Integración»

Los constructos de API CDK generados admiten dos patrones de integración:

  • isolated crea una función Lambda por operación. Este es el valor predeterminado para las API generadas.
  • shared crea un único enrutador Lambda predeterminado y lo reutiliza para cada operación a menos que anule integraciones específicas.

isolated le brinda permisos y configuración más detallados por operación. shared reduce la proliferación de Lambda y la integración de API Gateway mientras permite anulaciones selectivas.

Por ejemplo, establecer pattern en 'shared' crea una única 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) => {
    ...
    return IntegrationBuilder.rest({
      pattern: 'shared',
      ...
    });
  };
}
auth = iam

Otorgando Acceso (Solo IAM)

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

Puedes otorgar acceso a tu API de la siguiente manera:

api.grantInvokeAccess(myIdentityPool.authenticatedRole);

Bundle Target

Sección titulada «Bundle Target»

El generador configura automáticamente un target bundle que utiliza Rolldown para crear un paquete de despliegue:

Terminal window
pnpm nx bundle <project-name>

La configuración de Rolldown se encuentra en rolldown.config.ts, con una entrada por cada bundle a generar. Rolldown gestiona la creación de múltiples bundles en paralelo si están definidos.

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 serve my-api

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 type-safe. 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: 'Hello world!' });

Si estás llamando a tu API desde un sitio web React, considera usar el generador de Connection 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.

Conexiones

Sección titulada «Conexiones»

Usa el generador connection para integrar este proyecto con otros en tu espacio de trabajo. Las siguientes conexiones involucran este proyecto:

tRPC
React to tRPCCall a tRPC API from a React website
tRPCAmazon Aurora
tRPC API to Relational DatabaseConnect a tRPC API to an Aurora relational database
tRPCAmazon DynamoDB
tRPC API to TypeScript DynamoDBConnect a tRPC API to a DynamoDB table