TypeScript Academy · Lektion

Router und Procedures definieren

Erstellen Sie Queries und Mutations mit Eingabevalidierung.

Router und Procedures definieren ist eine kostenlose TypeScript Academy-Lektion auf CoddyKit. Dies ist Lektion 2 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des TypeScript Academy-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der TypeScript Academy-Kurs umfasst insgesamt 4 Lektionen.

tRPC initialisieren

Jedes tRPC-Backend beginnt damit, mit initTRPC eine Instanz zu erstellen. Diese liefert Builder für Router und Procedures. Normalerweise erstellen Sie sie einmal und exportieren die benötigten Bausteine.

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

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

Eine erste Procedure

Eine Procedure ist ein einzelner API-Endpunkt. Die einfachste Variante ist eine Query, die einen Wert zurückgibt. publicProcedure.query definiert einen Endpunkt zum Lesen ohne Eingabe.

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

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

Eingaben validieren

Procedures deklarieren ihre Eingabe mit einem Validator, üblicherweise einem zod-Schema. .input(schema) validiert die Eingabe zur Laufzeit und leitet zugleich den Eingabetyp für den Resolver und den Client ab.

import { z } from 'zod';

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

Eingaben auslesen

Im Resolver ist die validierte Eingabe als input verfügbar und anhand des Schemas vollständig typisiert. Eine manuelle Typumwandlung ist nicht erforderlich; zod und tRPC leiten die Struktur gemeinsam ab.

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

Mutationen

Verwenden Sie .mutation für Vorgänge, die Daten ändern. Die Struktur entspricht der einer Query, signalisiert jedoch einen Schreibvorgang und wirkt sich dadurch auf das Client-Caching und die HTTP-Methode aus.

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

Den App-Router erstellen

Sie fassen Procedures zu einem Router zusammen, indem Sie ein Objekt an router(...) übergeben. Jeder Schlüssel wird zum Namen einer aufrufbaren Procedure. Dieser appRouter ist Ihre gesamte API.

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

Verschachtelte Router

Router lassen sich verschachteln, um große APIs zu strukturieren. Ein Wert im Router-Objekt kann selbst ein Router sein. Dadurch entstehen Aufrufe mit Namensräumen wie user.byId.

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

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

Den Router-Typ exportieren

Der wichtigste Export ist der Router-Typ. Der Client importiert ihn, um vollständige Typsicherheit zu erhalten. Exportieren Sie den Wert für den Serveradapter und den Typ für den Client.

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

Einen Adapter anbinden

Um den Router über HTTP bereitzustellen, binden Sie einen Adapter an. tRPC bietet Adapter für eigenständiges Node, Express, Next.js, Fetch und weitere Umgebungen. Der Adapter wandelt eingehende Anfragen in Procedure-Aufrufe um.

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

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

Dateien organisieren

Eine gängige Struktur besteht aus einer trpc.ts mit initTRPC und den exportierten Buildern router/publicProcedure, Feature-Routern in eigenen Dateien sowie einem Root-appRouter, der sie zusammenführt. Wenn Sie initTRPC an einer Stelle aufbewahren, vermeiden Sie mehrere Instanzen.

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

Zusammenfassung zur Eingabeinferenz

Da .input(schema) sowohl validiert als auch ableitet, schreiben Sie das Schema einmal und erhalten gleichzeitig eine Laufzeitprüfung und einen statischen Typ. Der Client erkennt genau die Eingabe, die jede Procedure erwartet, abgeleitet aus diesen Schemata.

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

Kurzer Test

Testen Sie Ihr Verständnis von Routern und Procedures.

Zusammenfassung

Sie haben ein tRPC-Backend erstellt.

initTRPC.create() liefert Builder für router und procedure.
.input(schema) validiert die Eingabe und leitet ihren Typ ab.
.query liest; .mutation schreibt.
Fassen Sie Procedures zu appRouter zusammen und exportieren Sie type AppRouter = typeof appRouter.

Als Nächstes: das Backend mit einem vollständig typisierten Client verwenden.

Häufig gestellte Fragen

Ist die Lektion „Router und Procedures definieren“ kostenlos?

Ja — der vollständige Text von „Router und Procedures definieren“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des TypeScript Academy-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der TypeScript Academy-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Router und Procedures definieren“?

Erstellen Sie Queries und Mutations mit Eingabevalidierung. Du übst TypeScript Academy mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um TypeScript Academy zu starten?

Keine Vorkenntnisse erforderlich. TypeScript Academy auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 2 von 4.

Wie lange dauert die Lektion „Router und Procedures definieren“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser TypeScript Academy-Lektion Code schreiben und ausführen?

Ja. Jede TypeScript Academy-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

← Zurück zu TypeScript Academy