tRPC
tRPC è un framework per costruire API in TypeScript con sicurezza dei tipi 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 bisogno di ricompilare il progetto.
Il generatore di API tRPC crea una nuova API tRPC con configurazione dell’infrastruttura AWS CDK. Il backend generato utilizza AWS Lambda per la distribuzione serverless e include la validazione degli schemi tramite Zod. Configura AWS Lambda Powertools per l’osservabilità, inclusi logging, tracciamento AWS X-Ray e metriche CloudWatch.
Utilizzo
Generare un’API tRPC
Puoi generare una nuova API tRPC in due modi:
- Installa il Nx Console VSCode Plugin se non l'hai già fatto
- Apri la console Nx in VSCode
- Clicca su
Generate (UI)
nella sezione "Common Nx Commands" - Cerca
@aws/nx-plugin - ts#trpc-api
- Compila i parametri richiesti
- Clicca su
Generate
pnpm nx g @aws/nx-plugin:ts#trpc-api
yarn nx g @aws/nx-plugin:ts#trpc-api
npx nx g @aws/nx-plugin:ts#trpc-api
bunx nx g @aws/nx-plugin:ts#trpc-api
Puoi anche eseguire una prova per vedere quali file verrebbero modificati
pnpm nx g @aws/nx-plugin:ts#trpc-api --dry-run
yarn nx g @aws/nx-plugin:ts#trpc-api --dry-run
npx nx g @aws/nx-plugin:ts#trpc-api --dry-run
bunx nx g @aws/nx-plugin:ts#trpc-api --dry-run
Opzioni
Parametro | Tipo | Predefinito | Descrizione |
---|---|---|---|
name Obbligatorio | 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. |
Output del Generatore
Il generatore creerà la seguente struttura del progetto nella directory <directory>/<api-name>
:
Directoryschema
Directorysrc
- index.ts Punto d’ingresso dello schema
Directoryprocedures
- echo.ts Definizioni condivise dello schema per la procedura “echo”, usando Zod
- tsconfig.json Configurazione TypeScript
- project.json Configurazione del progetto e target di build
Directorybackend
Directorysrc
- init.ts Inizializzazione backend tRPC
- router.ts Definizione del router tRPC (punto d’ingresso API per l’handler Lambda)
Directoryprocedures Procedure (o operazioni) esposte dalla tua API
- echo.ts Procedura di esempio
Directorymiddleware
- error.ts Middleware per la gestione degli errori
- logger.ts Middleware per configurare AWS Powertools per il logging Lambda
- tracer.ts Middleware per configurare AWS Powertools per il tracciamento Lambda
- metrics.ts Middleware per configurare AWS Powertools per le metriche Lambda
- local-server.ts Punto d’ingresso dell’adapter standalone tRPC per server di sviluppo locale
Directoryclient
- index.ts Client type-safe per chiamate API machine-to-machine
- tsconfig.json Configurazione TypeScript
- project.json Configurazione del progetto e target di build
Il generatore creerà anche costrutti CDK utilizzabili per distribuire la tua API, residenti nella directory packages/common/constructs
.
Implementare la tua API tRPC
Come visto sopra, ci sono due componenti principali di un’API tRPC, schema
e backend
, definiti come singoli package nel tuo workspace.
Schema
Il package schema definisce i tipi condivisi tra il codice client e server. In questo package, questi tipi sono definiti usando Zod, una libreria TypeScript-first per la dichiarazione e validazione di schemi.
Uno schema di esempio potrebbe apparire così:
import { z } from 'zod';
// Definizione dello schemaexport const UserSchema = z.object({ name: z.string(), height: z.number(), dateOfBirth: z.string().datetime(),});
// Tipo TypeScript corrispondenteexport 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 punto di aggiornamento per modifiche alle strutture usate nella tua API.
Gli schemi sono automaticamente validati dalla tua API tRPC a runtime, evitando la necessità di scrivere logiche di validazione manuali nel backend.
Zod fornisce utility potenti per combinare o derivare schemi come .merge
, .pick
, .omit
e altri. Puoi trovare maggiori informazioni sul sito della documentazione Zod.
Backend
La cartella annidata backend
contiene l’implementazione della tua API, dove definisci le operazioni API e i loro input, output e implementazione.
Il punto d’ingresso della tua API si trova in src/router.ts
. Questo file contiene l’handler Lambda che instrada le richieste alle “procedure” in base all’operazione invocata. Ogni procedura definisce l’input atteso, l’output e l’implementazione.
Il router di esempio generato ha una singola operazione chiamata echo
:
import { echo } from './procedures/echo.js';
export const appRouter = router({ echo,});
La procedura echo
di esempio è generata in src/procedures/echo.ts
:
export const echo = publicProcedure .input(EchoInputSchema) .output(EchoOutputSchema) .query((opts) => ({ result: opts.input.message }));
Analizzando il codice sopra:
publicProcedure
definisce un metodo pubblico sull’API, includendo il middleware configurato insrc/middleware
. Questo middleware include l’integrazione con AWS Lambda Powertools per logging, tracciamento e metriche.input
accetta uno schema Zod che definisce l’input atteso per l’operazione. Le richieste per questa operazione sono automaticamente validate rispetto a questo schema.output
accetta uno schema Zod che definisce l’output atteso. Vedrai errori di tipo nell’implementazione se non restituisci un output conforme allo schema.query
accetta una funzione che definisce l’implementazione della tua API. Questa implementazione riceveopts
, che contiene l’input
passato all’operazione, oltre ad altro contesto configurato dal middleware, disponibile inopts.ctx
. La funzione passata aquery
deve restituire un output conforme allo schemaoutput
.
L’uso di query
per definire l’implementazione indica che l’operazione non è mutativa. Usalo per definire metodi di recupero dati. Per implementare un’operazione mutativa, usa invece il metodo mutation
.
Se aggiungi una nuova operazione, assicurati di registrarla aggiungendola al router in src/router.ts
.
Personalizzare la tua API tRPC
Errori
Nella tua implementazione, puoi restituire errori ai client lanciando un TRPCError
. Questi accettano un code
che indica il tipo di errore, ad esempio:
throw new TRPCError({ code: 'NOT_FOUND', message: 'La risorsa richiesta non è stata trovata',});
Organizzare le Operazioni
Man mano che la tua API cresce, potresti voler raggruppare operazioni correlate.
Puoi raggruppare operazioni usando router annidati, ad 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 riceveranno questo raggruppamento, ad esempio invocare l’operazione listUsers
in questo caso apparirebbe così:
client.users.list.query();
Logging
Il logger AWS Lambda Powertools è configurato in src/middleware/logger.ts
e può essere accesso in un’implementazione API via opts.ctx.logger
. Puoi usarlo per loggare su CloudWatch Logs e/o controllare valori aggiuntivi da includere in ogni messaggio di log strutturato. Ad esempio:
export const echo = publicProcedure .input(...) .output(...) .query(async (opts) => { opts.ctx.logger.info('Operazione chiamata con input', opts.input);
return ...; });
Per maggiori informazioni sul logger, consulta la documentazione AWS Lambda Powertools Logger.
Registrare Metriche
Le metriche AWS Lambda Powertools sono configurate in src/middleware/metrics.ts
e possono essere accessibili in un’implementazione API via opts.ctx.metrics
. Puoi usarle per registrare metriche in CloudWatch senza bisogno di importare e usare l’AWS SDK, ad esempio:
export const echo = publicProcedure .input(...) .output(...) .query(async (opts) => { opts.ctx.metrics.addMetric('Invocations', 'Count', 1);
return ...; });
Per maggiori informazioni, consulta la documentazione AWS Lambda Powertools Metrics.
Ottimizzare il Tracciamento X-Ray
Il tracer AWS Lambda Powertools è configurato in src/middleware/tracer.ts
e può essere accesso in un’implementazione API via opts.ctx.tracer
. Puoi usarlo per aggiungere tracce con AWS X-Ray e ottenere insight dettagliati sulle prestazioni e il flusso delle richieste API. Ad esempio:
export const echo = publicProcedure .input(...) .output(...) .query(async (opts) => { const subSegment = opts.ctx.tracer.getSegment()!.addNewSubsegment('MyAlgorithm'); // ... logica del mio algoritmo da tracciare subSegment.close();
return ...; });
Per maggiori informazioni, consulta la documentazione AWS Lambda Powertools Tracer.
Implementare Middleware Personalizzati
Puoi aggiungere valori aggiuntivi al contesto fornito alle procedure implementando middleware.
Come esempio, implementiamo un middleware per estrarre dettagli sull’utente chiamante dalla nostra API in src/middleware/identity.ts
.
Questo esempio assume che auth
sia impostato a IAM
. Per autenticazione Cognito, il middleware identity è più diretto, estraendo i claim rilevanti dall’event
.
Prima definiamo cosa aggiungeremo al contesto:
export interface IIdentityContext { identity?: { sub: string; username: string; };}
Nota che definiamo una proprietà opzionale aggiuntiva al contesto. tRPC gestisce l’assicurazione che questa sia definita nelle procedure che hanno configurato correttamente questo middleware.
Successivamente, implementiamo il middleware stesso. Ha la seguente struttura:
export const createIdentityPlugin = () => { const t = initTRPC.context<...>().create(); return t.procedure.use(async (opts) => { // Aggiungi logica qui da eseguire prima della procedura
const response = await opts.next(...);
// Aggiungi logica qui da eseguire dopo la procedura
return response; });};
Nel nostro caso, vogliamo estrarre dettagli sull’utente Cognito chiamante. Lo faremo estraendo l’ID subject (o “sub”) dell’utente dall’evento API Gateway e recuperando i dettagli utente da Cognito. L’implementazione varia leggermente a seconda che l’evento sia fornito da un’API REST o 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: `Impossibile determinare l'utente chiamante`, }); }
const { Users } = await cognito.listUsers({ // Assume che l'ID del user pool sia configurato nell'ambiente lambda UserPoolId: process.env.USER_POOL_ID!, Limit: 1, Filter: `sub="${sub}"`, });
if (!Users || Users.length !== 1) { throw new TRPCError({ code: 'FORBIDDEN', message: `Nessun utente trovato con subjectId ${sub}`, }); }
// Fornisci l'identity alle altre procedure nel contesto return await opts.next({ ctx: { ...opts.ctx, identity: { sub, username: Users[0].Username!, }, }, }); });};
import { CognitoIdentityProvider } from '@aws-sdk/client-cognito-identity-provider';import { initTRPC, TRPCError } from '@trpc/server';import { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';import { APIGatewayProxyEventV2WithIAMAuthorizer } from 'aws-lambda';
export interface IIdentityContext { identity?: { sub: string; username: string; };}
export const createIdentityPlugin = () => { const t = initTRPC.context<IIdentityContext & CreateAWSLambdaContextOptions<APIGatewayProxyEventV2WithIAMAuthorizer>>().create();
const cognito = new CognitoIdentityProvider();
return t.procedure.use(async (opts) => { const cognitoIdentity = opts.ctx.event.requestContext?.authorizer?.iam ?.cognitoIdentity as unknown as | { amr: string[]; } | undefined;
const sub = (cognitoIdentity?.amr ?? []) .flatMap((s) => (s.includes(':CognitoSignIn:') ? [s] : [])) .map((s) => { const parts = s.split(':'); return parts[parts.length - 1]; })?.[0];
if (!sub) { throw new TRPCError({ code: 'FORBIDDEN', message: `Impossibile determinare l'utente chiamante`, }); }
const { Users } = await cognito.listUsers({ // Assume che l'ID del user pool sia configurato nell'ambiente lambda UserPoolId: process.env.USER_POOL_ID!, Limit: 1, Filter: `sub="${sub}"`, });
if (!Users || Users.length !== 1) { throw new TRPCError({ code: 'FORBIDDEN', message: `Nessun utente trovato con subjectId ${sub}`, }); }
// Fornisci l'identity alle altre procedure nel contesto return await opts.next({ ctx: { ...opts.ctx, identity: { sub, username: Users[0].Username!, }, }, }); });};
Distribuire la tua API tRPC
Il generatore backend tRPC crea un costrutto CDK per distribuire la tua API nella cartella common/constructs
. Puoi utilizzarlo in un’applicazione CDK, ad esempio:
import { MyApi } from ':my-scope/common-constructs`;
export class ExampleStack extends Stack { constructor(scope: Construct, id: string) { // Aggiungi l'api allo stack const api = new MyApi(this, 'MyApi', { integrations: MyApi.defaultIntegrations(this).build(), }); }}
Questo configura l’infrastruttura della tua API, inclusi un AWS API Gateway REST o HTTP API, funzioni AWS Lambda per la logica di business, e autenticazione basata sul metodo auth
scelto.
Integrazioni Type-Safe
I costrutti CDK per le API REST/HTTP sono configurati per fornire un’interfaccia type-safe per definire le integrazioni per ciascuna delle tue operazioni.
Integrazioni predefinite
Puoi utilizzare il metodo statico defaultIntegrations
per sfruttare il pattern predefinito, che definisce una singola funzione AWS Lambda per ogni operazione:
new MyApi(this, 'MyApi', { integrations: MyApi.defaultIntegrations(this).build(),});
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 hai bisogno di aggiungere alcune autorizzazioni a questa funzione, puoi farlo come segue:
const api = new MyApi(this, 'MyApi', { integrations: MyApi.defaultIntegrations(this).build(),});
// sayHello è tipizzato in base alle operazioni definite nella tua APIapi.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: [...], resources: [...],}));
Personalizzazione delle opzioni predefinite
Se desideri personalizzare le opzioni utilizzate durante la creazione della funzione Lambda per ogni integrazione predefinita, puoi usare il metodo withDefaultOptions
. Ad esempio, se vuoi che tutte le tue funzioni Lambda risiedano in una Vpc:
const vpc = new Vpc(this, 'Vpc', ...);
new MyApi(this, 'MyApi', { integrations: MyApi.defaultIntegrations(this) .withDefaultOptions({ vpc, }) .build(),});
Override delle integrazioni
Puoi anche sovrascrivere le integrazioni per operazioni specifiche usando il metodo withOverrides
. Ogni override deve specificare una proprietà integration
tipizzata secondo l’appropriato costrutto CDK di integrazione per l’API HTTP o REST. Il metodo withOverrides
è anch’esso type-safe. Ad esempio, se desideri sovrascrivere un’API getDocumentation
per puntare a documentazione ospitata su un sito esterno:
new MyApi(this, 'MyApi', { integrations: MyApi.defaultIntegrations(this) .withOverrides({ getDocumentation: { integration: new HttpIntegration('https://example.com/documentation'), }, }) .build(),});
Noterai che l’integrazione sovrascritta non avrà più una proprietà handler
quando vi accedi tramite api.integrations.getDocumentation
.
Puoi aggiungere proprietà aggiuntive a un’integrazione che saranno anch’esse tipizzate correttamente, permettendo l’astrazione di altri tipi di integrazione mantenendo il type-safety. Ad esempio, se hai creato un’integrazione S3 per un’API REST e successivamente vuoi riferirti al bucket per una specifica operazione:
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(),});
// Successivamente, magari in un altro file, puoi accedere alla proprietà bucket che abbiamo definito// in modo type-safeapi.integrations.getFile.bucket.grantRead(...);
Override degli autorizzatori
Puoi anche fornire options
nelle tue integrazioni per sovrascrivere opzioni specifiche dei metodi come gli autorizzatori. Ad esempio, se desideri usare l’autenticazione Cognito per l’operazione getDocumentation
:
new MyApi(this, 'MyApi', { integrations: MyApi.defaultIntegrations(this) .withOverrides({ getDocumentation: { integration: new HttpIntegration('https://example.com/documentation'), options: { authorizer: new CognitoUserPoolsAuthorizer(...) // per REST, o HttpUserPoolAuthorizer per un'API HTTP } }, }) .build(),});
Integrazioni esplicite
Se preferisci, puoi scegliere di non usare le integrazioni predefinite e fornirne direttamente una per ogni operazione. Questo è utile se, ad esempio, ogni operazione necessita di un tipo diverso di integrazione o vuoi ricevere un errore di tipo quando aggiungi nuove operazioni:
new MyApi(this, 'MyApi', { integrations: { sayHello: { integration: new LambdaIntegration(...), }, getDocumentation: { integration: new HttpIntegration(...), }, },});
Pattern Router
Se preferisci distribuire una singola funzione Lambda per gestire tutte le richieste API, puoi modificare liberamente il metodo defaultIntegrations
della tua API per creare una singola funzione invece di una per integrazione:
export class MyApi<...> extends ... {
public static defaultIntegrations = (scope: Construct) => { const router = new Function(scope, 'RouterHandler', { ... }); return IntegrationBuilder.rest({ ... defaultIntegrationOptions: {}, buildDefaultIntegration: (op) => { return { // Riferimento allo stesso router lambda handler in ogni integrazione integration: new LambdaIntegration(router), }; }, }); };}
Puoi modificare il codice in altri modi se preferisci, ad esempio potresti definire la funzione router
come parametro di defaultIntegrations
invece di costruirla all’interno del metodo.
Concedere Accesso (Solo IAM)
Se hai selezionato l’autenticazione IAM
, puoi usare il metodo grantInvokeAccess
per concedere accesso alla tua API, ad esempio potresti voler concedere accesso agli utenti Cognito autenticati:
api.grantInvokeAccess(myIdentityPool.authenticatedRole);
Server tRPC Locale
Puoi usare il target serve
per eseguire un server locale per la tua API, ad esempio:
pnpm nx run @my-scope/my-api:serve
yarn nx run @my-scope/my-api:serve
npx nx run @my-scope/my-api:serve
bunx nx run @my-scope/my-api:serve
Il punto d’ingresso per il server locale è src/local-server.ts
.
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 usare il client in src/client/index.ts
, ad 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 React, considera l’uso del generatore API Connection per configurare il client.
Ulteriori Informazioni
Per maggiori informazioni su tRPC, consulta la documentazione di tRPC.