TypeScript Academy · Lezione

L’architettura tRPC

Scopra come tRPC elimina la duplicazione degli schemi API.

L’architettura tRPC è una lezione TypeScript Academy gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento TypeScript Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso TypeScript Academy include 4 lezioni in totale.

Il problema end-to-end

In una tipica applicazione web, il server definisce un'API e il client la chiama. Mantenere sincronizzati i relativi tipi è difficile: se si modifica un campo sul server, il client si rompe silenziosamente a runtime. tRPC risolve il problema condividendo direttamente i tipi, senza generazione di codice.

// Server: returns { id: number; name: string }
// Client: must know that shape exactly
// Without sync: runtime errors when they drift

Che cos'è tRPC

tRPC è una libreria per creare API completamente tipizzate in TypeScript. Il server definisce le procedure; il client le chiama come se fossero funzioni locali, con autocompletamento completo e controllo dei tipi ricavati dal codice del server.

// Client call looks like a local function:
// const user = await client.user.byId.query(1);
// user is typed automatically from the server

Nessuna generazione di codice

A differenza dei flussi di lavoro basati su GraphQL o OpenAPI, tRPC non richiede alcun passaggio di generazione del codice. Non esiste un file di schema da compilare né un client generato. I tipi passano dal server al client esclusivamente tramite l'inferenza di TypeScript in fase di compilazione.

// No .graphql files, no generated SDK
// Just import a type from the server package

Il router è il contratto

Il centro di tRPC è il router. Si tratta di un albero di procedure (query e mutation). L'oggetto router sul server, e in particolare il suo tipo inferito, è l'unica fonte di verità condivisa con il client.

// appRouter (server) defines every procedure
// type AppRouter = typeof appRouter is the contract

Come vengono condivisi i tipi

Il server esporta solo il tipo del proprio router, non l'implementazione. Il client importa quel tipo e lo usa per tipizzare un client proxy. Nel browser non arriva alcun codice del server: vengono trasferiti solo i tipi, che vengono eliminati durante la compilazione.

// server.ts
export type AppRouter = typeof appRouter;

// client.ts
import type { AppRouter } from '../server';

Query e mutation

Le procedure sono principalmente di due tipi. Una query legge i dati ed è generalmente idempotente. Una mutation modifica i dati. Questa distinzione corrisponde alla semantica della cache e di HTTP e determina il modo in cui il client le chiama.

// client.user.list.query()      -> read
// client.user.create.mutate(...) -> write

Runtime e tipi

tRPC ha due livelli. A runtime, le chiamate sono richieste JSON su HTTP gestite da un adapter. Durante la compilazione, il tipo condiviso AppRouter fa sì che ogni chiamata venga verificata completamente. Il runtime è ridotto all'essenziale; il valore sta nella sicurezza dei tipi.

// Runtime: POST /trpc/user.byId  body: {"input":1}
// Types: client.user.byId.query(1) is checked end to end

Perché l'inferenza è meglio della generazione del codice

Poiché i tipi vengono inferiti, non c'è alcun passaggio di sincronizzazione da dimenticare. Modificando una procedura, il client riflette immediatamente il cambiamento e mostra sottolineature rosse nei punti in cui le chiamate non corrispondono più. Il feedback è immediato ed è disponibile direttamente nell'editor.

// Add a required input field on the server
// -> every client call missing it becomes a type error

Dove si colloca tRPC

tRPC dà il meglio di sé nei monorepo full-stack TypeScript in cui client e server condividono la stessa base di codice, come nelle app Next.js. Non è pensato per API pubbliche utilizzate da altri linguaggi; in questi casi è preferibile uno schema indipendente dal linguaggio, come OpenAPI o GraphQL.

// Great: Next.js app, shared types, internal API
// Not ideal: public API for non-TS consumers

Quadro generale

Il flusso è il seguente: si definiscono le procedure su un router, si esporta il tipo del router, si collega un adapter HTTP e si crea un client tipizzato a partire da quel tipo. Ogni chiamata viene verificata rispetto al contratto del server, senza generare codice. Nelle prossime lezioni verrà costruito ogni elemento.

// Roadmap:
// 1. initTRPC + procedures + appRouter
// 2. export AppRouter, create typed client
// 3. context + middleware for auth

Affidarsi al compilatore

Il cambiamento di mentalità consiste nel considerare che il contratto dell'API risiede nei tipi, applicati dal compilatore, non solo nella documentazione o nella convalida a runtime. Se il codice viene compilato, client e server sono d'accordo. Questa garanzia è ciò che si intende per "sicurezza dei tipi end-to-end".

// If client.ts compiles, it matches the current server.

Verifica rapida

Verifichi la propria comprensione dell'architettura di tRPC.

Riepilogo

Ha appreso il modello di tRPC.

Il router è il contratto; il suo tipo è l'unica fonte di verità.
Il server esporta solo il tipo AppRouter, non il codice.
Le query leggono, le mutation scrivono; il runtime usa JSON su HTTP.
La sicurezza dei tipi deriva dall'inferenza, senza un passaggio di generazione del codice.

Prossimo argomento: definire router e procedure.

Domande Frequenti

La lezione «L’architettura tRPC» è gratuita?

Sì — il testo completo di «L’architettura tRPC» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso TypeScript Academy, passa a CoddyKit PRO. Il corso TypeScript Academy include 4 lezioni in totale.

Cosa imparerò in «L’architettura tRPC»?

Scopra come tRPC elimina la duplicazione degli schemi API. Eserciti TypeScript Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare TypeScript Academy?

Non è richiesta alcuna esperienza precedente. TypeScript Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.

Quanto tempo richiede la lezione «L’architettura tRPC»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione TypeScript Academy?

Sì. Ogni lezione TypeScript Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

← Torna a TypeScript Academy