TypeScript Academy · Lezione

Definire router e procedure

Costruisca query e mutation con validazione degli input.

Lezione 2 di 413 passaggi

Definire router e procedure è una lezione TypeScript Academy gratuita su CoddyKit. Questa è la lezione 2 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.

Inizializzare tRPC

Ogni backend tRPC inizia creando un'istanza con initTRPC. Questa restituisce i builder per router e procedure. In genere l'istanza viene creata una sola volta e si esportano gli elementi necessari.

import { initTRPC } from '@trpc/server';

const t = initTRPC.create();
export const router = t.router;
export const publicProcedure = t.procedure;

Una prima procedura

Una procedura è un singolo endpoint dell'API. La procedura più semplice è una query che restituisce un valore. publicProcedure.query definisce un endpoint di sola lettura senza input.

import { router, publicProcedure } from './trpc';

const appRouter = router({
  health: publicProcedure.query(() => 'ok'),
});

Convalidare l'input

Le procedure dichiarano il proprio input tramite un validator, comunemente uno schema zod. .input(schema) esegue sia la convalida a runtime sia l'inferenza del tipo di input per il resolver e per il client.

import { z } from 'zod';

const greet = publicProcedure
  .input(z.object({ name: z.string() }))
  .query(({ input }) => 'Hello, ' + input.name);

Leggere l'input

Nel resolver, l'input convalidato è disponibile come input ed è tipizzato completamente in base allo schema. Non è necessario alcun cast manuale: zod e tRPC ne inferiscono insieme la struttura.

const byId = publicProcedure
  .input(z.object({ id: z.number() }))
  .query(({ input }) => {
    // input.id is number
    return { id: input.id, name: 'Alice' };
  });

Mutation

Usi .mutation per le operazioni che modificano i dati. La struttura è uguale a quella di una query, ma indica un'operazione di scrittura, influenzando la cache del client e il metodo HTTP.

const createUser = publicProcedure
  .input(z.object({ name: z.string() }))
  .mutation(({ input }) => {
    return { id: 1, name: input.name };
  });

Costruire l'App Router

Raccolga le procedure in un router passando un oggetto a router(...). Ogni chiave diventa il nome di una procedura chiamabile. Questo appRouter costituisce l'intera API.

const appRouter = router({
  greet,
  byId,
  createUser,
});

Router annidati

I router possono essere annidati per organizzare API di grandi dimensioni. Un valore nell'oggetto del router può essere a sua volta un router, producendo chiamate con namespace come user.byId.

const userRouter = router({ byId, createUser });

const appRouter = router({
  user: userRouter,
  greet,
});
// call paths: user.byId, user.createUser, greet

Esportare il tipo del router

L'esportazione più importante è il tipo del router. Il client lo importerà per ottenere la piena sicurezza dei tipi. Esporti il valore per l'adapter del server e il tipo per il client.

export const appRouter = router({ user: userRouter });
export type AppRouter = typeof appRouter;

Collegare un adapter

Per esporre il router tramite HTTP, è necessario collegare un adapter. tRPC fornisce adapter per Node standalone, Express, Next.js, Fetch e altri ambienti. L'adapter trasforma le richieste in ingresso in chiamate alle procedure.

import { createHTTPServer } from '@trpc/server/adapters/standalone';

createHTTPServer({ router: appRouter }).listen(3000);

Organizzare i file

Una struttura comune prevede un file trpc.ts con initTRPC e i router/publicProcedure esportati, router delle funzionalità nei rispettivi file e un appRouter radice che li compone. Mantenere initTRPC in un unico punto evita di creare più istanze.

// trpc.ts: initTRPC.create(), export router + publicProcedure
// routers/user.ts: userRouter
// router.ts: appRouter = router({ user: userRouter })

Riepilogo dell'inferenza dell'input

Poiché .input(schema) esegue sia la convalida sia l'inferenza, è sufficiente scrivere lo schema una sola volta per ottenere un controllo a runtime e un tipo statico. Il client vedrà esattamente l'input previsto da ogni procedura, derivato da questi schemi.

const search = publicProcedure
  .input(z.object({ q: z.string(), page: z.number().optional() }))
  .query(({ input }) => ({ q: input.q, page: input.page ?? 1 }));

Verifica rapida

Verifichi la propria comprensione di router e procedure.

Rispondi nella lezione interattiva

Riepilogo

Ha creato un backend tRPC.

initTRPC.create() restituisce i builder router e procedure.
.input(schema) convalida e inferisce l'input.
.query legge; .mutation scrive.
Componendo le procedure si crea appRouter e si esporta type AppRouter = typeof appRouter.

Prossimo argomento: utilizzare l'API con un client completamente tipizzato.

Gratis per iniziare

Impara TypeScript con un tutor IA — gratis

Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.

Corsi: 101
Lezioni: 352

Inizia a imparare gratis Visualizza il corso completo

Domande Frequenti

La lezione «Definire router e procedure» è gratuita?

Sì — il testo completo di «Definire router e procedure» è 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 «Definire router e procedure»?

Costruisca query e mutation con validazione degli input. 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 2 di 4.

Quanto tempo richiede la lezione «Definire router e procedure»?

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