Pular para o conteúdo
@aws/nx-plugin
Blog

tRPC

tRPC é um framework para construir APIs em TypeScript com segurança de tipos de ponta a ponta. Usando tRPC, atualizações nas entradas e saídas das operações da API são imediatamente refletidas no código do cliente e visíveis em sua IDE sem necessidade de reconstruir o projeto.

O gerador de API tRPC cria uma nova API tRPC com configuração de infraestrutura AWS CDK ou Terraform. O backend gerado usa AWS Lambda para implantação serverless, exposto via API Gateway da AWS, e inclui validação de esquema usando Zod. Configura AWS Lambda Powertools para observabilidade, incluindo logging, rastreamento com AWS X-Ray e métricas no CloudWatch.

Uso

Seção intitulada “Uso”

Gerar uma API tRPC

Seção intitulada “Gerar uma API tRPC”

Você pode gerar uma nova API tRPC de duas formas:

  1. Instale o Nx Console VSCode Plugin se ainda não o fez
  2. Abra o console Nx no VSCode
  3. Clique em Generate (UI) na seção "Common Nx Commands"
  4. Procure por @aws/nx-plugin - ts#trpc-api
  5. Preencha os parâmetros obrigatórios
    • Clique em Generate

    Opções

    Seção intitulada “Opções”
    Parâmetro Tipo Padrão Descrição
    name Obrigatório 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

    Saída do Gerador

    Seção intitulada “Saída do Gerador”

    O gerador criará a seguinte estrutura de projeto no diretório <directory>/<api-name>:

    • Directorysrc
      • init.ts Inicialização do backend tRPC
      • router.ts Definição do roteador tRPC (ponto de entrada da API no handler Lambda)
      • Directoryschema Definições de esquema usando Zod
        • echo.ts Exemplo de definições para entrada e saída do procedimento “echo”
      • Directoryprocedures Procedimentos (ou operações) expostos pela sua API
        • echo.ts Procedimento de exemplo
      • Directorymiddleware
        • error.ts Middleware para tratamento de erros
        • logger.ts middleware para configurar AWS Powertools para logging em Lambda
        • tracer.ts middleware para configurar AWS Powertools para rastreamento em Lambda
        • metrics.ts middleware para configurar AWS Powertools para métricas em Lambda
      • local-server.ts Ponto de entrada do adaptador standalone tRPC para servidor de desenvolvimento local
      • Directoryclient
        • index.ts Cliente type-safe para chamadas máquina-a-máquina na API
    • tsconfig.json Configuração TypeScript
    • project.json Configuração do projeto e targets de build

    Infraestrutura

    Seção intitulada “Infraestrutura”

    Como este gerador fornece infraestrutura como código com base no iacProvider escolhido, ele criará um projeto em packages/common que inclui os constructs CDK ou módulos Terraform relevantes.

    O projeto comum de infraestrutura como código está estruturado da seguinte forma:

    • Directorypackages/common/constructs
      • Directorysrc
        • Directoryapp/ Constructs para infraestrutura específica de um projeto/gerador
          • …
        • Directorycore/ Constructs genéricos reutilizados pelos constructs em app
          • …
        • index.ts Ponto de entrada exportando os constructs de app
      • project.json Metas de build e configuração do projeto

    Para implantar sua API, os seguintes arquivos são gerados:

    • Directorypackages/common/constructs/src
      • Directoryapp
        • Directoryapis
          • <project-name>.ts Construto CDK para implantar sua API
      • Directorycore
        • Directoryapi
          • http-api.ts Construto CDK para implantar uma API HTTP (se você escolheu implantar uma API HTTP)
          • rest-api.ts Construto CDK para implantar uma API REST (se você escolheu implantar uma API REST)
          • utils.ts Utilitários para os construtos da API

    Implementando sua API tRPC

    Seção intitulada “Implementando sua API tRPC”

    Em alto nível, APIs tRPC consistem em um roteador que delega requisições para procedimentos específicos. Cada procedimento tem uma entrada e saída definidas como um esquema Zod.

    Esquema

    Seção intitulada “Esquema”

    O diretório src/schema contém os tipos compartilhados entre seu código cliente e servidor. Neste pacote, esses tipos são definidos usando Zod, uma biblioteca de declaração e validação de esquemas TypeScript-first.

    Um exemplo de esquema pode ser:

    import { z } from 'zod';
    

    // Definição do esquema
    export const UserSchema = z.object({
      name: z.string(),
      height: z.number(),
      dateOfBirth: z.string().datetime(),
    });
    

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

    Dado o esquema acima, o tipo User é equivalente ao seguinte TypeScript:

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

    Esquemas são compartilhados por código cliente e servidor, proporcionando um único local para atualizar quando houver mudanças nas estruturas usadas em sua API.

    Esquemas são validados automaticamente por sua API tRPC em runtime, economizando a criação manual de lógica de validação no backend.

    Zod fornece utilitários poderosos para combinar ou derivar esquemas como .merge, .pick, .omit e mais. Você pode encontrar mais informações no site de documentação do Zod.

    Roteador e Procedimentos

    Seção intitulada “Roteador e Procedimentos”

    O ponto de entrada da sua API está em src/router.ts. Este arquivo contém o handler Lambda que roteia requisições para “procedimentos” baseado na operação sendo invocada. Cada procedimento define a entrada esperada, saída e implementação.

    O roteador de exemplo gerado possui uma única operação chamada echo:

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

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

    O procedimento echo de exemplo é gerado em src/procedures/echo.ts:

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

    Quebrando o código acima:

    • publicProcedure define um método público na API, incluindo o middleware configurado em src/middleware. Este middleware inclui integração com AWS Lambda Powertools para logging, rastreamento e métricas.
    • input aceita um esquema Zod que define a entrada esperada para a operação. Requisições para esta operação são validadas automaticamente contra este esquema.
    • output aceita um esquema Zod que define a saída esperada para a operação. Você verá erros de tipo em sua implementação se não retornar uma saída que conforme com o esquema.
    • query aceita uma função que define a implementação para sua API. Esta implementação recebe opts, que contém o input passado para sua operação, bem como outros contextos configurados por middleware, disponíveis em opts.ctx. A função passada para query deve retornar uma saída que conforme com o esquema output.

    O uso de query para definir a implementação indica que a operação não é mutativa. Use isto para definir métodos de recuperação de dados. Para implementar uma operação mutativa, use o método mutation ao invés.

    Se você adicionar um novo procedimento, certifique-se de registrá-lo adicionando-o ao roteador em src/router.ts.

    Personalizando sua API tRPC

    Seção intitulada “Personalizando sua API tRPC”

    Erros

    Seção intitulada “Erros”

    Em sua implementação, você pode retornar respostas de erro para clientes lançando um TRPCError. Estes aceitam um code que indica o tipo de erro, por exemplo:

    throw new TRPCError({
      code: 'NOT_FOUND',
      message: 'O recurso solicitado não pôde ser encontrado',
    });

    Organizando Suas Operações

    Seção intitulada “Organizando Suas Operações”

    Conforme sua API cresce, você pode querer agrupar operações relacionadas.

    Você pode agrupar operações usando roteadores aninhados, por exemplo:

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

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

    Clientes então recebem este agrupamento de operações, por exemplo invocar a operação listUsers neste caso seria:

    client.users.list.query();

    Logging

    Seção intitulada “Logging”

    O logger AWS Lambda Powertools é configurado em src/middleware/logger.ts, e pode ser acessado em uma implementação de API via opts.ctx.logger. Você pode usar isto para logar no CloudWatch Logs, e/ou controlar valores adicionais a incluir em cada mensagem de log estruturada. Por exemplo:

    export const echo = publicProcedure
       .input(...)
       .output(...)
       .query(async (opts) => {
          opts.ctx.logger.info('Operação chamada com input', opts.input);
    

          return ...;
       });

    Para mais informações sobre o logger, consulte a documentação do AWS Lambda Powertools Logger.

    Registrando Métricas

    Seção intitulada “Registrando Métricas”

    As métricas AWS Lambda Powertools são configuradas em src/middleware/metrics.ts, e podem ser acessadas em uma implementação de API via opts.ctx.metrics. Você pode usar isto para registrar métricas no CloudWatch sem necessidade de usar o AWS SDK, por exemplo:

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

          return ...;
       });

    Para mais informações, consulte a documentação do AWS Lambda Powertools Metrics.

    Ajustando Rastreamento X-Ray

    Seção intitulada “Ajustando Rastreamento X-Ray”

    O tracer AWS Lambda Powertools é configurado em src/middleware/tracer.ts, e pode ser acessado em uma implementação de API via opts.ctx.tracer. Você pode usar isto para adicionar traces com AWS X-Ray para fornecer insights detalhados sobre performance e fluxo de requisições da API. Por exemplo:

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

          return ...;
       });

    Para mais informações, consulte a documentação do AWS Lambda Powertools Tracer.

    Implementando Middleware Customizado

    Seção intitulada “Implementando Middleware Customizado”

    Você pode adicionar valores adicionais ao contexto fornecido aos procedimentos implementando middleware.

    Como exemplo, vamos implementar um middleware para extrair detalhes sobre o usuário chamador de nossa API em src/middleware/identity.ts.

    Este exemplo assume que auth foi definido como IAM. Para autenticação Cognito, o middleware de identidade é mais direto, extraindo as claims relevantes do event.

    Primeiro, definimos o que adicionaremos ao contexto:

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

    Note que definimos uma propriedade adicional opcional ao contexto. O tRPC gerencia garantir que isto esteja definido em procedimentos que tenham configurado corretamente este middleware.

    Em seguida, implementamos o middleware em si. Ele tem a seguinte estrutura:

    export const createIdentityPlugin = () => {
       const t = initTRPC.context<...>().create();
       return t.procedure.use(async (opts) => {
          // Adicione lógica aqui para executar antes do procedimento
    

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

          // Adicione lógica aqui para executar após o procedimento
    

          return response;
       });
    };

    No nosso caso, queremos extrair detalhes sobre o usuário Cognito chamador. Faremos isto extraindo o ID de assunto do usuário (ou “sub”) do evento API Gateway, e recuperando detalhes do usuário do Cognito. A implementação varia ligeiramente dependendo se o evento foi fornecido por uma 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: `Não foi possível determinar o usuário chamador`,
          });
        }
    

        const { Users } = await cognito.listUsers({
          // Assume que o ID do user pool está configurado no ambiente lambda
          UserPoolId: process.env.USER_POOL_ID!,
          Limit: 1,
          Filter: `sub="${sub}"`,
        });
    

        if (!Users || Users.length !== 1) {
          throw new TRPCError({
            code: 'FORBIDDEN',
            message: `Nenhum usuário encontrado com subjectId ${sub}`,
          });
        }
    

        // Fornece a identidade para outros procedimentos no contexto
        return await opts.next({
          ctx: {
            ...opts.ctx,
            identity: {
              sub,
              username: Users[0].Username!,
            },
          },
        });
      });
    };

    Implantando sua API tRPC

    Seção intitulada “Implantando sua API tRPC”

    O gerador de API tRPC cria infraestrutura como código CDK ou Terraform baseado no iacProvider selecionado. Você pode usar isto para implantar sua API tRPC.

    O construct CDK para implantar sua API está na pasta common/constructs. Você pode consumir isto em uma aplicação CDK, por exemplo:

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

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

    Isto configura a infraestrutura da sua API, incluindo um API Gateway REST ou HTTP da AWS, funções Lambda para lógica de negócio, e autenticação baseada no método auth escolhido.

    Integrações

    Seção intitulada “Integrações”

    Os construtos CDK da API REST/HTTP são configurados para fornecer uma interface type-safe para definir integrações para cada uma de suas operações.

    Os construtos CDK fornecem suporte completo a integrações type-safe conforme descrito abaixo.

    Integrações Padrão

    Seção intitulada “Integrações Padrão”

    Você pode usar o método estático defaultIntegrations para utilizar o padrão padrão, que define uma função AWS Lambda individual para cada operação:

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

    Acessando Integrações

    Seção intitulada “Acessando Integrações”

    Você pode acessar as funções AWS Lambda subjacentes através da propriedade integrations do construto da API, de forma type-safe. Por exemplo, se sua API define uma operação chamada sayHello e você precisa adicionar permissões a esta função, você pode fazer isso da seguinte forma:

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

    // sayHello é tipado conforme as operações definidas em sua API
    api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({
      effect: Effect.ALLOW,
      actions: [...],
      resources: [...],
    }));

    Personalizando Opções Padrão

    Seção intitulada “Personalizando Opções Padrão”

    Se você deseja personalizar as opções usadas ao criar a função Lambda para cada integração padrão, pode usar o método withDefaultOptions. Por exemplo, se deseja que todas suas funções Lambda residam em uma VPC:

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

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

    Sobrescrevendo Integrações

    Seção intitulada “Sobrescrevendo Integrações”

    Você também pode sobrescrever integrações para operações específicas usando o método withOverrides. Cada sobrescrita deve especificar uma propriedade integration que é tipada ao construto de integração CDK apropriado para a API HTTP ou REST. O método withOverrides também é type-safe. Por exemplo, se você deseja sobrescrever uma API getDocumentation para apontar para documentação hospedada em um site externo:

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

    Você notará que a integração sobrescrita não terá mais uma propriedade handler quando acessada via api.integrations.getDocumentation.

    Você pode adicionar propriedades adicionais a uma integração que também serão tipadas adequadamente, permitindo que outros tipos de integração sejam abstraídos mas permaneçam type-safe. Por exemplo, se você criou uma integração S3 para uma API REST e depois deseja referenciar o bucket para uma operação específica:

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

    // Posteriormente, talvez em outro arquivo, você pode acessar a propriedade bucket que definimos
    // de forma type-safe
    api.integrations.getFile.bucket.grantRead(...);

    Sobrescrevendo Autorizadores

    Seção intitulada “Sobrescrevendo Autorizadores”

    Você também pode fornecer options em sua integração para sobrescrever opções específicas de método como autorizadores. Por exemplo, se desejar usar autenticação Cognito para sua operação getDocumentation:

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

    Integrações Explícitas

    Seção intitulada “Integrações Explícitas”

    Se preferir, você pode optar por não usar as integrações padrão e fornecer diretamente uma para cada operação. Isso é útil se, por exemplo, cada operação precisar usar um tipo diferente de integração ou se você quiser receber um erro de tipo ao adicionar novas operações:

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

    Padrão de Roteador

    Seção intitulada “Padrão de Roteador”

    Se você preferir implantar uma única função Lambda para atender todas as requisições da API, pode livremente editar o método defaultIntegrations de sua API para criar uma única função em vez de uma por integração:

    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 {
              // Referencia o mesmo router lambda handler em todas as integrações
              integration: new LambdaIntegration(router),
            };
          },
        });
      };
    }

    Você pode modificar o código de outras formas se preferir, por exemplo pode definir a função router como parâmetro para defaultIntegrations em vez de construí-la dentro do método.

    Concedendo Acesso (Somente IAM)

    Seção intitulada “Concedendo Acesso (Somente IAM)”

    Se você selecionou usar autenticação IAM, pode conceder acesso à sua API:

    api.grantInvokeAccess(myIdentityPool.authenticatedRole);

    Servidor tRPC Local

    Seção intitulada “Servidor tRPC Local”

    Você pode usar o target serve para executar um servidor local para sua API, por exemplo:

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

    O ponto de entrada para o servidor local é src/local-server.ts.

    Isto recarregará automaticamente quando você fizer mudanças em sua API.

    Invocando sua API tRPC

    Seção intitulada “Invocando sua API tRPC”

    Você pode criar um cliente tRPC para invocar sua API de forma type-safe. Se estiver chamando sua API tRPC de outro backend, pode usar o cliente em src/client/index.ts, por exemplo:

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

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

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

    Se estiver chamando sua API de um site React, considere usar o gerador API Connection para configurar o cliente.

    Mais Informações

    Seção intitulada “Mais Informações”

    Para mais informações sobre tRPC, consulte a documentação do tRPC.