Salta ai contenuti
@aws/nx-plugin
Blog

tRPC

tRPC è un framework per la creazione di API in TypeScript con type safety end-to-end. Utilizzando tRPC, gli aggiornamenti agli input e output delle operazioni API si riflettono immediatamente nel codice client e sono visibili nel tuo IDE senza la necessità di ricostruire il progetto.

Il generatore di API tRPC crea una nuova API tRPC con configurazione dell’infrastruttura AWS CDK o Terraform. Il backend generato utilizza AWS Lambda per il deployment serverless, esposto tramite un’API AWS API Gateway, e include la validazione dello schema utilizzando Zod. Configura AWS Lambda Powertools per l’osservabilità, inclusi logging, tracing AWS X-Ray e Cloudwatch Metrics.

Utilizzo

Sezione intitolata “Utilizzo”

Generare un’API tRPC

Sezione intitolata “Generare un’API tRPC”

Puoi generare una nuova API tRPC in due modi:

Esegui questo generatore@aws/nx-plugin:ts#api

pnpm nx g @aws/nx-plugin:ts#api
Componi il tuo comando9

Obbligatorio

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

Opzioni

Sezione intitolata “Opzioni”
Opzioni del generatore9 opzioni
nameObbligatoriostring

Il nome dell'API (obbligatorio). Utilizzato per generare i nomi delle classi e i percorsi dei file.

frameworkenumPredefinito: trpc

Il framework API da utilizzare.

trpcsmithy
integrationPatternenumPredefinito: isolated

Come vengono generate le integrazioni API Gateway per l'API. Scegli tra isolated (predefinito) e shared.

isolatedshared
authenumPredefinito: iam

Il metodo utilizzato per autenticare con la tua API. Scegli tra iam (predefinito), cognito o custom.

iamcognitocustom
directorystringPredefinito: packages

La directory in cui memorizzare l'applicazione.

iacenumPredefinito: inherit

Il provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.

inheritcdkterraform
infraenumPredefinito: rest-lambda

Il tipo di infrastruttura da utilizzare per distribuire questa API.

rest-lambdahttp-lambdanone
subDirectorystring

La sottodirectory in cui viene posizionato il progetto. Per impostazione predefinita corrisponde al nome del progetto.

preferInstallDependenciesbooleanPredefinito: true

Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Sezione intitolata “Output del Generatore”

Il generatore creerà la seguente struttura di progetto nella directory <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

Infrastruttura

Sezione intitolata “Infrastruttura”

Poiché questo generatore fornisce infrastruttura come codice basata sul tuo iac scelto, creerà un progetto in packages/common che include i costrutti CDK o i moduli Terraform pertinenti.

Il progetto comune di infrastruttura come codice è strutturato come segue:

  • 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

Per il deployment della tua API, vengono generati i seguenti file:

  • 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

Architettura

Sezione intitolata “Architettura”

L’applicazione distribuita ha la seguente architettura: un’API di API Gateway davanti a una funzione Lambda che esegue il tuo handler.

Loading the diagram…

Le REST API includono una Web ACL AWS WAFv2 davanti allo stage di API Gateway con il set di regole predefinito gestito da AWS abilitato.

Implementare la tua API tRPC

Sezione intitolata “Implementare la tua API tRPC”

Ad alto livello, le API tRPC consistono in un router che delega le richieste a procedure specifiche. Ogni procedura ha un input e un output, definiti come schema Zod.

Schema

Sezione intitolata “Schema”

La directory src/schema contiene i tipi condivisi tra il codice client e server. In questo package, questi tipi sono definiti utilizzando Zod, una libreria di dichiarazione e validazione di schemi TypeScript-first.

Un esempio di schema potrebbe apparire come segue:

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

Dato lo schema sopra, il tipo User è equivalente al seguente TypeScript:

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

Gli schemi sono condivisi sia dal codice server che client, fornendo un unico posto da aggiornare quando si apportano modifiche alle strutture utilizzate nella tua API.

Gli schemi vengono automaticamente validati dalla tua API tRPC a runtime, il che evita di dover creare manualmente logica di validazione personalizzata nel tuo backend.

Zod fornisce potenti utility per combinare o derivare schemi come .merge, .pick, .omit e altro. Puoi trovare maggiori informazioni sul sito di documentazione di Zod.

Router e Procedure

Sezione intitolata “Router e Procedure”

Il tuo router tRPC è definito in src/router.ts, che registra tutte le procedure. Ogni procedura definisce l’input, l’output e l’implementazione previsti. Il punto di ingresso dell’handler Lambda è in src/handler.ts, che inoltra le richieste al tuo router.

Il router di esempio generato per te ha una singola operazione, chiamata echo:

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


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

La procedura di esempio echo viene generata per te in src/procedures/echo.ts:

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

Per analizzare quanto sopra:

  • publicProcedure definisce un metodo pubblico sull’API, incluso il middleware configurato in src/middleware. Questo middleware include l’integrazione di AWS Lambda Powertools per logging, tracing e metriche.
  • input accetta uno schema Zod che definisce l’input previsto per l’operazione. Le richieste inviate per questa operazione vengono automaticamente validate rispetto a questo schema.
  • output accetta uno schema Zod che definisce l’output previsto per l’operazione. Vedrai errori di tipo nella tua implementazione se non restituisci un output conforme allo schema.
  • query accetta una funzione che definisce l’implementazione per la tua API. Questa implementazione riceve opts, che contiene l’input passato alla tua operazione, così come altro contesto configurato dal middleware, disponibile in opts.ctx. La funzione passata a query deve restituire un output conforme allo schema output.

L’uso di query per definire l’implementazione indica che l’operazione non è mutativa. Usalo per definire metodi per recuperare dati. Per implementare un’operazione mutativa, usa invece il metodo mutation.

Se aggiungi una nuova procedura, assicurati di registrarla aggiungendola al router in src/router.ts.

infra = rest-lambda

Subscriptions (Streaming)

Sezione intitolata “Subscriptions (Streaming)”

Le subscriptions tRPC ti permettono di trasmettere dati dal server al client utilizzando Server-Sent Events (SSE). Quando selezioni rest-lambda come tipo di compute, il generatore configura automaticamente l’infrastruttura richiesta per lo streaming, così come un handler Lambda di streaming e l’helper di schema ZodAsyncIterable.

Per definire una procedura di subscription, usa il metodo .subscription con una funzione generatore asincrona. Usa l’helper ZodAsyncIterable da src/schema/z-async-iterable.ts per definire lo schema di output:

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 subscription nel tuo router proprio come qualsiasi altra procedura:

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

L’infrastruttura generata utilizza un handler Lambda di streaming con ResponseTransferMode.STREAM in API Gateway per tutte le operazioni REST API, il che consente alle subscriptions di funzionare insieme a query e mutations regolari.

Personalizzare la tua API tRPC

Sezione intitolata “Personalizzare la tua API tRPC”

Errori

Sezione intitolata “Errori”

Nella tua implementazione, puoi restituire risposte di errore ai client lanciando un TRPCError. Questi accettano un code che indica il tipo di errore, per esempio:

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

Organizzare le Tue Operazioni

Sezione intitolata “Organizzare le Tue Operazioni”

Man mano che la tua API cresce, potresti voler raggruppare operazioni correlate insieme.

Puoi raggruppare operazioni insieme utilizzando router nidificati, per esempio:

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


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

I client ricevono quindi questo raggruppamento di operazioni, per esempio invocare l’operazione listUsers in questo caso potrebbe apparire come segue:

client.users.list.query();

Logging

Sezione intitolata “Logging”

Il logger AWS Lambda Powertools è configurato in src/middleware/logger.ts, e può essere accessibile in un’implementazione API tramite opts.ctx.logger. Puoi usarlo per registrare su CloudWatch Logs, e/o controllare valori aggiuntivi da includere in ogni messaggio di log strutturato. Per esempio:

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


      return ...;
   });

Per maggiori informazioni sul logger, consulta la documentazione di AWS Lambda Powertools Logger.

Registrare Metriche

Sezione intitolata “Registrare Metriche”

Le metriche AWS Lambda Powertools sono configurate in src/middleware/metrics.ts, e possono essere accessibili in un’implementazione API tramite opts.ctx.metrics. Puoi usarle per registrare metriche in CloudWatch senza la necessità di importare e utilizzare l’AWS SDK, per esempio:

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


      return ...;
   });

Per maggiori informazioni, consulta la documentazione di AWS Lambda Powertools Metrics.

Ottimizzare il Tracing X-Ray

Sezione intitolata “Ottimizzare il Tracing X-Ray”

Il tracer AWS Lambda Powertools è configurato in src/middleware/tracer.ts, e può essere accessibile in un’implementazione API tramite opts.ctx.tracer. Puoi usarlo per aggiungere tracce con AWS X-Ray per fornire informazioni dettagliate sulle prestazioni e il flusso delle richieste API. Per esempio:

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

Per maggiori informazioni, consulta la documentazione di AWS Lambda Powertools Tracer.

Implementare Middleware Personalizzato

Sezione intitolata “Implementare Middleware Personalizzato”

Puoi aggiungere valori aggiuntivi al contesto fornito alle procedure implementando middleware.

Come esempio, implementiamo un middleware per estrarre alcuni dettagli sull’utente chiamante dalla nostra API in src/middleware/identity.ts.

auth = iam

Questo esempio illustra il middleware di identità per l’autenticazione IAM. Cerchiamo il chiamante in Cognito utilizzando il sub estratto dall’evento API Gateway.

La ricerca utilizza il client Cognito Identity Provider, che non è una dipendenza di un’API tRPC generata. Installalo prima nel tuo progetto API:

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

Prima, definiamo cosa aggiungeremo al contesto:

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

Nota che definiamo una proprietà aggiuntiva opzionale al contesto. tRPC gestisce l’assicurazione che questa sia definita nelle procedure che hanno configurato correttamente questo middleware.

Successivamente, implementeremo il middleware stesso. Questo ha la seguente struttura:

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

Nel nostro caso, vogliamo estrarre dettagli sull’utente Cognito chiamante. Lo faremo estraendo l’ID soggetto dell’utente (o “sub”) dall’evento API Gateway e recuperando i dettagli dell’utente da Cognito. L’implementazione varia a seconda che l’evento sia stato fornito alla nostra funzione da una REST API o da un’HTTP API:

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 effettui il deploy con auth: 'cognito', l’autorizzatore Cognito di API Gateway verifica il JWT che il chiamante fornisce nell’header Authorization e posiziona i claim verificati sull’evento Lambda. Il nostro middleware legge semplicemente quei claim — nessuna chiamata AWS SDK extra, nessuna verifica JWT manuale.

Prima, definiamo cosa aggiungeremo al contesto:

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

Nota che definiamo una proprietà aggiuntiva opzionale sul contesto. tRPC gestisce l’assicurazione che questa sia definita nelle procedure che hanno configurato correttamente questo middleware.

Successivamente, il middleware stesso. Il tipo di evento e la posizione dei claim differiscono tra una REST API e un’HTTP API, quindi l’implementazione dipende dal tuo infra selezionato:

L’autorizzatore Cognito User Pools di una REST API posiziona i claim in 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,
        },
      },
    });
  });
};

Puoi quindi mescolare il plugin in qualsiasi procedura che necessita dell’identità del chiamante:

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

Effettuare il Deploy della tua API tRPC

Sezione intitolata “Effettuare il Deploy della tua API tRPC”

Il generatore di API tRPC crea infrastruttura come codice CDK o Terraform in base al tuo iac selezionato. Puoi usarlo per effettuare il deploy della tua API tRPC.

Il costrutto CDK per il deploy della tua API si trova nella cartella common/constructs. Puoi utilizzarlo in un’applicazione CDK, per esempio:

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

Il costrutto UserIdentity può essere generato utilizzando il generatore ts#website#auth.

Questo configura l’infrastruttura della tua API, inclusa un’API AWS API Gateway REST o HTTP, funzioni AWS Lambda per la logica di business e autenticazione basata sul tuo metodo auth scelto.

infra = rest-lambda

WAF

Sezione intitolata “WAF”

Per le REST API, il costrutto generato associa un Web ACL AWS WAFv2 allo stage di API Gateway per impostazione predefinita. Il Web ACL utilizza il set di regole predefinito gestito da AWS (AWSManagedRulesCommonRuleSet e AWSManagedRulesKnownBadInputsRuleSet), fornendo protezione contro exploit web comuni inclusa la OWASP Top 10. I log delle richieste WAF vengono scritti in un gruppo di CloudWatch Logs.

Puoi modificare il costrutto rest-api generato per aggiungere, rimuovere o regolare le regole (ad esempio, per aggiungere regole basate sulla frequenza o gruppi di regole gestite aggiuntivi).

Per disattivare (ad esempio, per collegare il tuo Web ACL), imposta enableWaf su false:

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

Logging degli Accessi

Sezione intitolata “Logging degli Accessi”

Per le REST API, l’infrastruttura generata abilita la registrazione degli accessi per impostazione predefinita, scrivendo una riga JSON strutturata per richiesta in un gruppo CloudWatch Logs dedicato. Il gruppo di log è crittografato con una chiave KMS gestita dal cliente e conservato per un anno.

API Gateway scrive i log di accesso utilizzando un ruolo CloudWatch Logs a livello di account. Questo ruolo è configurato sull’impostazione AWS::ApiGateway::Account, che è un singleton per regione per account — esiste un solo ruolo per ogni REST API nella regione. Per gestire questo in modo sicuro tra più stack distribuiti indipendentemente, l’infrastruttura generata:

  • Crea un ruolo CloudWatch Logs condiviso e lo configura sull’account solo quando non è già impostato un ruolo funzionante, in modo che le distribuzioni non sovrascrivano mai un ruolo di proprietà di un altro stack.
  • Lascia intatta l’impostazione dell’account durante lo smantellamento, in modo che la distruzione di uno stack non disabiliti mai la registrazione per altre REST API nella regione.

Il ruolo dell’account è gestito dal costrutto ApiGatewayAccount, un singleton con ambito stack risolto tramite ApiGatewayAccount.ensure(scope). Ogni stage della REST API dipende da esso e il ruolo è configurato da una risorsa personalizzata supportata da Lambda.

Il formato del log di accesso è impostato dal costrutto RestApi che la tua API estende. Per personalizzarlo, passa deployOptions a super nel file generato packages/common/constructs/src/app/apis/my-api.ts, mantenendo il tracingEnabled che il costrutto già imposta:

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

AccessLogFormat è importato da aws-cdk-lib/aws-apigateway. Tutto ciò che lasci non impostato mantiene il valore predefinito del costrutto — un formato JSON con i campi standard.

Integrazioni

Sezione intitolata “Integrazioni”

I costrutti CDK REST/HTTP API sono configurati per fornire un’interfaccia type-safe per definire integrazioni per ciascuna delle tue operazioni.

Integrazioni Predefinite

Sezione intitolata “Integrazioni Predefinite”

Puoi utilizzare il metodo statico defaultIntegrations per utilizzare il pattern predefinito, che definisce una funzione AWS Lambda individuale per ogni operazione:

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

Accesso alle Integrazioni

Sezione intitolata “Accesso alle Integrazioni”

Puoi accedere alle funzioni AWS Lambda sottostanti tramite la proprietà integrations del costrutto API, in modo type-safe. Ad esempio, se la tua API definisce un’operazione chiamata sayHello e devi aggiungere alcune autorizzazioni a questa funzione, puoi farlo come segue:

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 la tua API utilizza il pattern shared, il router Lambda condiviso è esposto come api.integrations.$router:

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


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

Nota che $router non è più disponibile se sovrascrivi ogni operazione tramite withOverrides, poiché nessuna operazione rimane ad utilizzare l’integrazione router predefinita.

Personalizzazione delle Opzioni Predefinite

Sezione intitolata “Personalizzazione delle Opzioni Predefinite”

Se desideri personalizzare le opzioni utilizzate durante la creazione della funzione Lambda per ogni integrazione predefinita, puoi utilizzare il metodo withDefaultOptions. Ad esempio, se desideri che tutte le tue funzioni Lambda risiedano in un Vpc:

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


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

Personalizzazione delle Opzioni per Operazione

Sezione intitolata “Personalizzazione delle Opzioni per Operazione”

Per personalizzare le opzioni utilizzate per creare l’integrazione predefinita per operazioni specifiche (senza influenzare le altre), puoi utilizzare il metodo withOperationOptions. Ad esempio, se desideri aumentare il timeout della funzione Lambda solo per un’operazione:

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

Le opzioni che specifichi vengono unite alle opzioni di integrazione predefinite (e a qualsiasi opzione impostata tramite withDefaultOptions). Nota che non puoi specificare opzioni per operazioni che hai sostituito tramite withOverrides, poiché queste non utilizzano più l’integrazione predefinita.

Incontrerai un errore di tipo se la stessa operazione è targetizzata sia da withOperationOptions che da withOverrides, indipendentemente dall’ordine in cui li chiami.

Override delle Integrazioni

Sezione intitolata “Override delle Integrazioni”

Puoi anche sovrascrivere le integrazioni per operazioni specifiche utilizzando il metodo withOverrides. Ogni override deve specificare una proprietà integration che è tipizzata al costrutto di integrazione CDK appropriato per l’API HTTP o REST. Il metodo withOverrides è anche type-safe. Ad esempio, se desideri sovrascrivere un’API getDocumentation per puntare alla documentazione ospitata da un sito web esterno, potresti ottenere questo come segue:

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

Noterai anche che l’integrazione sovrascritta non ha più una proprietà handler quando vi accedi tramite api.integrations.getDocumentation.

Puoi aggiungere proprietà aggiuntive a un’integrazione che saranno anche tipizzate di conseguenza, consentendo ad altri tipi di integrazione di essere astratti ma rimanere type-safe, ad esempio se hai creato un’integrazione S3 per un’API REST e successivamente desideri fare riferimento al bucket per una particolare operazione, puoi farlo come segue:

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

Override degli Authorizer

Sezione intitolata “Override degli Authorizer”

Puoi anche fornire options nella tua integrazione per sovrascrivere particolari opzioni del metodo come gli authorizer, ad esempio se desideri utilizzare l’autenticazione Cognito per la tua operazione 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(),
});

Integrazioni Esplicite

Sezione intitolata “Integrazioni Esplicite”

Se preferisci, puoi scegliere di non utilizzare le integrazioni predefinite e invece fornirne direttamente una per ogni operazione. Questo è utile se, ad esempio, ogni operazione deve utilizzare un tipo diverso di integrazione o desideri ricevere un errore di tipo quando aggiungi nuove operazioni:

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

Pattern di Integrazione

Sezione intitolata “Pattern di Integrazione”

Le API generate supportano due pattern di integrazione:

  • isolated crea una funzione Lambda per operazione. Questa è l’opzione predefinita e consigliata per le API.
  • shared crea un singolo router Lambda predefinito e lo riutilizza per ogni operazione a meno che non si sovrascrivano integrazioni specifiche.

isolated ti offre autorizzazioni e configurazione più granulari per operazione, oltre a una migliore separazione per log e tracce. shared riduce la probabilità di incontrare cold-start per API a basso utilizzo.

Il pattern di integrazione può essere modificato in qualsiasi momento in CDK aggiornando il tuo costrutto API. Ad esempio, impostando pattern su 'shared' si crea una singola funzione invece di una per integrazione:

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
Terraform REST API Path Depth Limit
Sezione intitolata “Terraform REST API Path Depth Limit”
auth = iam

Concedere l’Accesso (Solo IAM)

Sezione intitolata “Concedere l’Accesso (Solo IAM)”

Puoi concedere l’accesso alla tua API come segue:

api.grantInvokeAccess(myIdentityPool.authenticatedRole);

Bundle Target

Sezione intitolata “Bundle Target”

Il generatore configura automaticamente un target bundle che utilizza Rolldown per creare un pacchetto di distribuzione:

Terminal window
pnpm nx bundle <project-name>

La configurazione di Rolldown si trova in rolldown.config.ts, con una voce per ogni bundle da generare. Rolldown gestisce la creazione di più bundle in parallelo se definiti.

Server tRPC Locale

Sezione intitolata “Server tRPC Locale”

Puoi utilizzare il target serve per eseguire un server locale per la tua API, per esempio:

Terminal window
pnpm nx serve my-api

Il punto di ingresso per il server locale è src/local-server.ts.

Questo si ricaricherà automaticamente quando apporti modifiche alla tua API.

Invocare la tua API tRPC

Sezione intitolata “Invocare la tua API tRPC”

Puoi creare un client tRPC per invocare la tua API in modo type-safe. Se stai chiamando la tua API tRPC da un altro backend, puoi utilizzare il client in src/client/index.ts, per esempio:

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 stai chiamando la tua API da un sito web React, considera l’utilizzo del generatore Connection per configurare il client.

Maggiori Informazioni

Sezione intitolata “Maggiori Informazioni”

Per maggiori informazioni su tRPC, consulta la documentazione di tRPC.

Connessioni

Sezione intitolata “Connessioni”

Usa il generatore connection per integrare questo progetto con altri nel tuo workspace. Le seguenti connessioni coinvolgono questo progetto:

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