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

tRPC

tRPC é um framework para construir APIs em TypeScript com segurança de tipo de ponta a ponta. Usando tRPC, atualizações nas entradas e saídas de operações da API são imediatamente refletidas no código do cliente e são visíveis no seu IDE sem a necessidade de reconstruir seu 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 uma API AWS API Gateway, e inclui validação de esquema usando Zod. Ele configura AWS Lambda Powertools para observabilidade, incluindo logging, rastreamento AWS X-Ray e Cloudwatch Metrics.

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 maneiras:

Execute este gerador@aws/nx-plugin:ts#api

pnpm nx g @aws/nx-plugin:ts#api
Monte seu comando9

Obrigatório

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

Opções

Seção intitulada “Opções”
Opções do gerador9 opções
nameObrigatóriostring

O nome da API (obrigatório). Usado para gerar nomes de classes e caminhos de arquivos.

frameworkenumPadrão: trpc

O framework de API a ser utilizado.

trpcsmithy
integrationPatternenumPadrão: isolated

Como as integrações do API Gateway são geradas para a API. Escolha entre isolated (padrão) e shared.

isolatedshared
authenumPadrão: iam

O método usado para autenticar com sua API. Escolha entre iam (padrão), cognito ou custom.

iamcognitocustom
directorystringPadrão: packages

O diretório para armazenar a aplicação.

iacenumPadrão: inherit

O provedor IaC preferido. Por padrão, isso é herdado da sua seleção inicial.

inheritcdkterraform
infraenumPadrão: rest-lambda

O tipo de infraestrutura a ser usado para implantar esta API.

rest-lambdahttp-lambdanone
subDirectorystring

O subdiretório onde o projeto é colocado. Por padrão, este é o nome do projeto.

preferInstallDependenciesbooleanPadrão: true

Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

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
    • index.ts Package entrypoint re-exporting the router, context, client and schema
    • init.ts Backend tRPC initialisation
    • handler.ts Lambda handler entrypoint
    • router.ts tRPC router definition
    • Directoryschema Schema definitions using Zod
      • index.ts Barrel re-exporting every schema
      • echo.ts Example definitions for the input and output of the “echo” procedure
      • z-async-iterable.ts Zod helper for subscriptions (REST API only)
    • Directoryprocedures Procedures (or operations) exposed by your API
      • echo.ts Example procedure
    • Directorymiddleware
      • index.ts Barrel re-exporting the middleware, and the procedure context type
      • 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
    • Directoryclient
      • index.ts Type-safe client for machine-to-machine API calls
  • rolldown.config.ts Bundle configuration for the Lambda deployment package
  • tsconfig.json TypeScript configuration
  • tsconfig.lib.json TypeScript configuration for the library sources
  • tsconfig.spec.json TypeScript configuration for the tests
  • vitest.config.mts Vitest configuration
  • package.json Project manifest defining the project’s package name and dependencies
  • project.json Project configuration and build targets
  • README.md Project readme
  • .gitignore Ignores the project’s build output

Infraestrutura

Seção intitulada “Infraestrutura”

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

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

  • Directorypackages/common/constructs
    • Directorysrc
      • Directoryapp/ Constructs for infrastructure specific to a project/generator
        • …
      • Directorycore/ 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 implantar sua API, os seguintes arquivos são gerados:

  • Directorypackages/common/constructs/src
    • Directoryapp
      • Directoryapis
        • <project-name>.ts CDK construct for deploying your API
    • Directorycore
      • Directoryapi
        • 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

Arquitetura

Seção intitulada “Arquitetura”

A aplicação implantada possui a seguinte arquitetura: uma API do API Gateway na frente de uma função Lambda executando seu manipulador.

Loading the diagram…

As REST APIs incluem um Web ACL do AWS WAFv2 na frente do estágio do API Gateway com o conjunto de regras padrão gerenciado pela AWS habilitado.

Implementando sua API tRPC

Seção intitulada “Implementando sua API tRPC”

Em alto nível, APIs tRPC consistem em um roteador que delega solicitaçõ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 que são 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 esquema TypeScript-first.

Um exemplo de esquema pode parecer o seguinte:

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 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 servidor e cliente, fornecendo um único lugar para atualizar ao fazer alterações nas estruturas usadas em sua API.

Esquemas são automaticamente validados pela sua API tRPC em tempo de execução, o que economiza a criação manual de lógica de validação personalizada em seu 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”

Seu roteador tRPC é definido em src/router.ts, que registra todos os procedimentos. Cada procedimento define a entrada, saída e implementação esperadas. O ponto de entrada do manipulador Lambda está em src/handler.ts, que encaminha solicitações para seu roteador.

O roteador de exemplo gerado para você tem uma única operação, chamada echo:

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


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

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

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

Para detalhar o acima:

  • publicProcedure define um método público na API, incluindo o middleware configurado em src/middleware. Este middleware inclui integração AWS Lambda Powertools para logging, rastreamento e métricas.
  • input aceita um esquema Zod que define a entrada esperada para a operação. Solicitações enviadas para esta operação são automaticamente validadas 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 esteja em conformidade com o esquema.
  • query aceita uma função que define a implementação para sua API. Esta implementação recebe opts, que contém a input passada para sua operação, bem como outro contexto configurado pelo middleware, disponível em opts.ctx. A função passada para query deve retornar uma saída que esteja em conformidade com o esquema output.

O uso de query para definir a implementação indica que a operação não é mutativa. Use isso para definir métodos para recuperar dados. Para implementar uma operação mutativa, use o método mutation em vez disso.

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

infra = rest-lambda

Assinaturas (Streaming)

Seção intitulada “Assinaturas (Streaming)”

Assinaturas tRPC permitem que você transmita dados do servidor para o cliente usando Server-Sent Events (SSE). Quando você seleciona rest-lambda como seu tipo de computação, o gerador configura automaticamente a infraestrutura necessária para streaming, bem como um manipulador Lambda de streaming e o auxiliar de esquema ZodAsyncIterable.

Para definir um procedimento de assinatura, use o método .subscription com uma função geradora assíncrona. Use o auxiliar ZodAsyncIterable de src/schema/z-async-iterable.ts para definir o esquema de saída:

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

Registre a assinatura em seu roteador assim como qualquer outro procedimento:

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

A infraestrutura gerada usa um manipulador Lambda de streaming com ResponseTransferMode.STREAM no API Gateway para todas as operações da API REST, o que permite que assinaturas funcionem junto com consultas e mutações regulares.

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 aos clientes lançando um TRPCError. Estes aceitam um code que indica o tipo de erro, por exemplo:

throw new TRPCError({
  code: 'NOT_FOUND',
  message: 'The requested resource could not be found',
});

Organizando Suas Operações

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

À medida que sua API cresce, você pode desejar 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,
   }),
   ...
})

Os clientes então recebem este agrupamento de operações, por exemplo, invocar a operação listUsers neste caso pode parecer o seguinte:

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 isso para registrar no CloudWatch Logs, e/ou controlar valores adicionais para incluir em cada mensagem de log estruturada. Por exemplo:

export const echo = publicProcedure
   .input(...)
   .output(...)
   .query(async (opts) => {
      opts.ctx.logger.info('Operation called with 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 isso para registrar métricas no CloudWatch sem a necessidade de importar e 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.

Ajuste Fino do Rastreamento X-Ray

Seção intitulada “Ajuste Fino do Rastreamento X-Ray”

O rastreador 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 isso para adicionar rastreamentos com AWS X-Ray para fornecer insights detalhados sobre o desempenho e fluxo de solicitações de API. Por exemplo:

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 mais informações, consulte a documentação do AWS Lambda Powertools Tracer.

Implementando Middleware Personalizado

Seção intitulada “Implementando Middleware Personalizado”

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

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

auth = iam

Este exemplo percorre o middleware de identidade para autenticação IAM. Procuramos o chamador no Cognito usando o sub extraído do evento API Gateway.

A pesquisa usa o cliente Cognito Identity Provider, que não é uma dependência de uma API tRPC gerada. Instale-o em seu projeto de API primeiro:

Terminal window
pnpm add @aws-sdk/client-cognito-identity-provider@3.1126.0 --filter my-api

Primeiro, definimos o que adicionaremos ao contexto:

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

Note que definimos uma propriedade adicional opcional para o contexto. tRPC gerencia garantir que isso seja definido em procedimentos que configuraram corretamente este middleware.

Em seguida, implementaremos o middleware em si. Isso tem a seguinte estrutura:

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

No nosso caso, queremos extrair detalhes sobre o usuário Cognito chamador. Faremos isso 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 dependendo se o evento foi fornecido à nossa função por uma API REST ou uma API HTTP:

import { CognitoIdentityProvider } from '@aws-sdk/client-cognito-identity-provider';
import { initTRPC, TRPCError } from '@trpc/server';
import type { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
import type { 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

Quando você implanta com auth: 'cognito', o autorizador Cognito do API Gateway verifica o JWT que o chamador fornece no cabeçalho Authorization e coloca as reivindicações verificadas no evento Lambda. Nosso middleware apenas lê essas reivindicações — sem chamadas extras do AWS SDK, sem verificação manual de JWT.

Primeiro, definimos o que adicionaremos ao contexto:

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

Note que definimos uma propriedade adicional opcional no contexto. tRPC gerencia garantir que isso seja definido em procedimentos que configuraram corretamente este middleware.

Em seguida, o middleware em si. O tipo de evento e a localização das reivindicações diferem entre uma API REST e uma API HTTP, portanto a implementação depende do seu infra selecionado:

O autorizador Cognito User Pools de uma API REST coloca as reivindicações em event.requestContext.authorizer.claims:

import { initTRPC, TRPCError } from '@trpc/server';
import type { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
import type { 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 ?? claims?.['cognito: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,
        },
      },
    });
  });
};

Você pode então misturar o plugin em qualquer procedimento que precise da identidade do chamador:

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

Implantando sua API tRPC

Seção intitulada “Implantando sua API tRPC”

O gerador de API tRPC cria infraestrutura como código CDK ou Terraform com base no seu iac selecionado. Você pode usar isso para implantar sua API tRPC.

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

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

O construto UserIdentity pode ser gerado usando o gerador ts#website#auth.

Isso configura sua infraestrutura de API, incluindo uma API AWS API Gateway REST ou HTTP, funções AWS Lambda para lógica de negócios e autenticação baseada no seu método auth escolhido.

infra = rest-lambda

WAF

Seção intitulada “WAF”

Para APIs REST, o construto gerado associa um Web ACL do AWS WAFv2 com o estágio do API Gateway por padrão. O Web ACL usa o conjunto de regras padrão gerenciado pela AWS (AWSManagedRulesCommonRuleSet e AWSManagedRulesKnownBadInputsRuleSet), fornecendo proteção contra explorações web comuns, incluindo o OWASP Top 10. Os logs de solicitações do WAF são gravados em um grupo do CloudWatch Logs.

Você pode editar o construto rest-api gerado para adicionar, remover ou ajustar regras (por exemplo, para adicionar regras baseadas em taxa ou grupos de regras gerenciadas adicionais).

Para desativar (por exemplo, para anexar seu próprio Web ACL), defina enableWaf como false:

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

Registro de acesso

Seção intitulada “Registro de acesso”

Para APIs REST, a infraestrutura gerada habilita o registro de acesso por padrão, escrevendo uma linha JSON estruturada por requisição em um grupo dedicado do CloudWatch Logs. O grupo de logs é criptografado com uma chave KMS gerenciada pelo cliente e retido por um ano.

O API Gateway escreve logs de acesso usando uma função do CloudWatch Logs no nível da conta. Esta função é configurada na configuração AWS::ApiGateway::Account, que é um singleton por região por conta — há apenas uma função para cada API REST na região. Para gerenciar isso com segurança em várias pilhas implantadas independentemente, a infraestrutura gerada:

  • Cria uma função compartilhada do CloudWatch Logs e a configura na conta apenas quando nenhuma função funcional já está definida, para que as implantações nunca sobrescrevam uma função que outra pilha possui.
  • Deixa a configuração da conta intocada na desmontagem, para que destruir uma pilha nunca desabilite o registro para outras APIs REST na região.

A função da conta é gerenciada pelo construto ApiGatewayAccount, um singleton com escopo de pilha resolvido via ApiGatewayAccount.ensure(scope). O estágio de cada API REST depende dele, e a função é configurada por um recurso personalizado baseado em Lambda.

O formato do log de acesso é definido pelo construto RestApi que sua API estende. Para personalizá-lo, passe deployOptions para super no packages/common/constructs/src/app/apis/my-api.ts gerado, mantendo o tracingEnabled que o construto já define:

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

AccessLogFormat é importado de aws-cdk-lib/aws-apigateway. Qualquer coisa que você deixar indefinida mantém o padrão do construto — um formato JSON com os campos padrão.

Integrações

Seção intitulada “Integrações”

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

Integrações Padrão

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

Você pode usar o método estático defaultIntegrations para fazer uso do padrão default, 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 algumas 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 is typed to the operations defined in your API
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({
  effect: Effect.ALLOW,
  actions: [...],
  resources: [...],
}));

Se sua API usa o padrão shared, o Lambda router compartilhado é exposto como api.integrations.$router:

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


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

Observe que $router não está mais disponível se você substituir todas as operações via withOverrides, já que nenhuma operação resta usando a integração de router padrão.

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, você pode usar o método withDefaultOptions. Por exemplo, se você deseja que todas as 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(),
});

Personalizando Opções Por Operação

Seção intitulada “Personalizando Opções Por Operação”

Para personalizar as opções usadas para criar a integração padrão para operações específicas (sem afetar as outras), você pode usar o método withOperationOptions. Por exemplo, se você deseja aumentar o timeout da função Lambda para apenas uma operação:

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

As opções que você especifica são mescladas com as opções de integração padrão (e quaisquer opções definidas via withDefaultOptions). Observe que você não pode especificar opções para operações que você substituiu via withOverrides, pois estas não usam mais a integração padrão.

Você encontrará um erro de tipo se a mesma operação for alvo de ambos withOperationOptions e withOverrides, independentemente da ordem em que você os chamar.

Substituindo Integrações

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

Você também pode substituir integrações para operações específicas usando o método withOverrides. Cada substituição deve especificar uma propriedade integration que é tipada para o 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 substituir uma API getDocumentation para apontar para documentação hospedada por algum site externo, você pode fazer isso da seguinte forma:

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

Você também notará que a integração substituída não tem mais uma propriedade handler ao acessá-la 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, você pode fazer isso da seguinte forma:

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

Substituindo Autorizadores

Seção intitulada “Substituindo Autorizadores”

Você também pode fornecer options em sua integração para substituir opções de método específicas, como autorizadores, por exemplo, se você deseja 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(...) // for REST, or HttpUserPoolAuthorizer for an HTTP API
        }
      },
    })
    .build(),
});

Integrações Explícitas

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

Se você preferir, pode optar por não usar as integrações padrão e, em vez disso, fornecer diretamente uma para cada operação. Isso é útil se, por exemplo, cada operação precisa usar um tipo diferente de integração ou você deseja 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 Integração

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

APIs geradas suportam dois padrões de integração:

  • isolated cria uma função Lambda por operação. Esta é a opção padrão e recomendada para APIs.
  • shared cria um único Lambda router padrão e o reutiliza para cada operação, a menos que você substitua integrações específicas.

isolated oferece permissões e configuração mais granulares por operação, bem como melhor separação para logs e traces. shared reduz a probabilidade de encontrar cold-starts para APIs de baixo uso.

O padrão de integração pode ser alterado a qualquer momento no CDK atualizando seu construto de API. Por exemplo, definir pattern como 'shared' cria 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) => {
    ...
    return IntegrationBuilder.rest({
      pattern: 'shared',
      ...
    });
  };
}
iac = terraform, infra = rest-lambda
Limite de Profundidade de Caminho da REST API no Terraform
Seção intitulada “Limite de Profundidade de Caminho da REST API no Terraform”
auth = iam

Concedendo Acesso (Somente IAM)

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

Você pode conceder acesso à sua API da seguinte forma:

api.grantInvokeAccess(myIdentityPool.authenticatedRole);

Bundle Target

Seção intitulada “Bundle Target”

O gerador configura automaticamente um target bundle que usa Rolldown para criar um pacote de implantação:

Terminal window
pnpm nx bundle <project-name>

A configuração do Rolldown pode ser encontrada em rolldown.config.ts, com uma entrada por pacote a ser gerado. O Rolldown gerencia a criação de múltiplos pacotes em paralelo, se definidos.

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

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

Isso recarregará automaticamente quando você fizer alterações 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 maneira type-safe. Se você estiver chamando sua API tRPC de outro backend, você 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 você estiver chamando sua API de um site React, considere usar o gerador 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.

Conexões

Seção intitulada “Conexões”

Use o gerador connection para integrar este projeto com outros em seu workspace. As seguintes conexões envolvem este projeto:

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