Kurs JavaScript i TypeScript · Moduł 10: TypeScript w praktyce

TypeScript z Node.js - praktyczne wzorce

9 min czytania ·
W tej lekcji5

Kiedy zarządzasz infrastrukturą Parku Jurajskiego, potrzebujesz niezawodnego backendu: systemu autoryzacji, API do zarządzania strefami i middleware do logowania. Jeden handler, który przyjmie dangerLevel jako tekst zamiast liczby, potrafi zepsuć raport bezpieczeństwa całego parku. TypeScript w połączeniu z Node.js i Express pozwala budować serwery z pełnym type safety i eliminować całe klasy błędów, zanim uruchomisz kod.

Typowanie routes w Express

Domyślnie req.body ma w Expressie typ any, req.query to ogólny słownik ParsedQs, a req.params to słownik napisów. Zawężamy je generykiem Request<Params, ResBody, ReqBody, Query>, w którym kolejność parametrów ma znaczenie. Najpierw opisujemy dane API:

import { Request, Response, NextFunction, Router } from 'express';

// Interfejsy dla danych naszego API
interface Dinosaur {
  id: string;
  species: string;
  diet: 'herbivore' | 'carnivore' | 'omnivore';
  zone: string;
  weight: number;
  dangerLevel: 1 | 2 | 3 | 4 | 5;
}

// Typowany Request - params, body, query
interface GetDinosaurParams {
  id: string;
}

interface ListDinosaursQuery {
  zone?: string;
  diet?: Dinosaur['diet'];
  limit?: string;
  offset?: string;
}

interface CreateDinosaurBody {
  species: string;
  diet: Dinosaur['diet'];
  zone: string;
  weight: number;
  dangerLevel: Dinosaur['dangerLevel'];
}

Dinosaur['diet'] to typ indeksowany: pobiera typ pola z innego interfejsu, więc lista diet istnieje tylko w jednym miejscu. limit i offset są napisami, bo tak przychodzą w adresie URL.

Teraz handler z typowanymi parametrami ścieżki. Pierwszy generyk Request opisuje params, a Response<T> pilnuje kształtu odpowiedzi:

// Typowane handlery
const router = Router();

// GET /dinosaurs/:id - typowane params
router.get('/dinosaurs/:id',
  (req: Request<GetDinosaurParams>, res: Response<Dinosaur | { error: string }>) => {
    const dinoId: string = req.params.id; // typowane!
    // req.params.name; // Błąd kompilacji - nie ma "name" w params

    const dinosaur: Dinosaur = {
      id: dinoId,
      species: 'Velociraptor',
      diet: 'carnivore',
      zone: 'B-7',
      weight: 80,
      dangerLevel: 4
    };
    res.json(dinosaur);
  }
);

Odwołanie do req.params.name to błąd kompilacji, a res.json() przyjmie tylko dinozaura albo obiekt błędu.

Query i body opisujemy kolejnymi generykami, wstawiając {} i any w pozycje, których nie potrzebujemy:

// GET /dinosaurs - typowane query
router.get('/dinosaurs',
  (req: Request<{}, any, any, ListDinosaursQuery>, res: Response<Dinosaur[]>) => {
    const zone = req.query.zone;       // string | undefined
    const diet = req.query.diet;       // Dinosaur['diet'] | undefined
    const limit = parseInt(req.query.limit || '10');

    // Filtrowanie na podstawie typowanych query params
    res.json([]);
  }
);

// POST /dinosaurs - typowane body
router.post('/dinosaurs',
  (req: Request<{}, any, CreateDinosaurBody>, res: Response<Dinosaur>) => {
    const body = req.body;
    // body.species: string - typowane!
    // body.diet: 'herbivore' | 'carnivore' | 'omnivore' - typowane!
    // body.unknownField; // Błąd kompilacji

    const newDinosaur: Dinosaur = {
      id: 'DINO-' + Date.now(),
      ...body
    };
    res.status(201).json(newDinosaur);
  }
);

Pamiętaj, że to obietnica, a nie walidacja: klient może wysłać dowolny JSON, więc w produkcji sprawdzaj dane w runtime, na przykład biblioteką zod. Typ opisuje poprawne dane, ale ich nie gwarantuje.

Typowanie middleware

Middleware w Express to funkcje przetwarzające żądanie przed dotarciem do handlera. Dostają req, res i next, a przerywają łańcuch, wysyłając odpowiedź zamiast wywołać next(). Rozszerzamy interfejs żądania o dane zalogowanego użytkownika:

// Middleware dodające userId do request
interface AuthenticatedRequest extends Request {
  userId: string;
  role: 'visitor' | 'staff' | 'admin' | 'scientist';
}

function authMiddleware(
  req: Request,
  res: Response,
  next: NextFunction
): void {
  const token = req.headers.authorization?.split(' ')[1];

  if (!token) {
    res.status(401).json({ error: 'Brak tokenu autoryzacji' });
    return;
  }

  // Weryfikacja tokenu (uproszczona)
  try {
    const decoded = verifyToken(token); // Twoja funkcja weryfikacji
    (req as AuthenticatedRequest).userId = decoded.userId;
    (req as AuthenticatedRequest).role = decoded.role;
    next();
  } catch (error) {
    res.status(403).json({ error: 'Nieprawidłowy token' });
  }
}

// Deklaracja pomocnicza
declare function verifyToken(token: string): { userId: string; role: AuthenticatedRequest['role'] };

// Middleware sprawdzające rolę
function requireRole(...roles: AuthenticatedRequest['role'][]) {
  return (req: Request, res: Response, next: NextFunction): void => {
    const authReq = req as AuthenticatedRequest;
    if (!roles.includes(authReq.role)) {
      res.status(403).json({
        error: `Wymagana rola: ${roles.join(' lub ')}`
      });
      return;
    }
    next();
  };
}

// Użycie w routach
router.delete('/dinosaurs/:id',
  authMiddleware,
  requireRole('admin', 'scientist'),
  (req: Request, res: Response) => {
    const authReq = req as AuthenticatedRequest;
    console.log(`User ${authReq.userId} usunął dinozaura ${req.params.id}`);
    res.status(204).send();
  }
);

Kolejność jest więc taka: żądanie trafia do serwera, authMiddleware sprawdza token, requireRole weryfikuje rolę, a handler dostaje żądanie już po kontroli. verifyToken zwraca rolę typu AuthenticatedRequest['role'], więc przypisanie jest bezpieczne, a rzutowanie as AuthenticatedRequest to Twoja obietnica, że middleware wykonał się wcześniej.

Typowanie zmiennych środowiskowych

Zmienne środowiskowe (process.env) domyślnie mają typ string | undefined, bo podczas kompilacji nikt nie wie, czy zostaną ustawione. Walidujemy je więc przy starcie aplikacji:

// Interfejs opisujący wymagane zmienne środowiskowe
interface EnvironmentVariables {
  NODE_ENV: 'development' | 'production' | 'test';
  PORT: string;
  DATABASE_URL: string;
  JWT_SECRET: string;
  PARK_NAME: string;
  MAX_VISITORS: string;
  ALERT_EMAIL: string;
}

// Funkcja walidująca zmienne środowiskowe
function validateEnv(): EnvironmentVariables {
  const required: (keyof EnvironmentVariables)[] = [
    'NODE_ENV', 'PORT', 'DATABASE_URL', 'JWT_SECRET',
    'PARK_NAME', 'MAX_VISITORS', 'ALERT_EMAIL'
  ];

  const missing = required.filter(key => !process.env[key]);

  if (missing.length > 0) {
    throw new Error(
      `Brakujące zmienne środowiskowe: ${missing.join(', ')}`
    );
  }

  return process.env as unknown as EnvironmentVariables;
}

// Użycie - bezpieczne i typowane
const env = validateEnv();
const port = parseInt(env.PORT);           // string -> number
const dbUrl: string = env.DATABASE_URL;    // na pewno string, nie undefined
const maxVisitors = parseInt(env.MAX_VISITORS);

as unknown as to podwójna asercja, którą mówisz kompilatorowi, że wiesz lepiej. Kod sprawdza obecność zmiennych, ale nie to, czy NODE_ENV ma dozwoloną wartość, więc taki test dopisz sam. Aplikacja bez sekretu JWT nie wstanie, zamiast działać z dziurą w zabezpieczeniach.

Wygodniej zamknąć konfigurację w klasie, która raz zamienia napisy na liczby i wartości logiczne:

// Alternatywnie - klasa konfiguracji
class AppConfig {
  readonly port: number;
  readonly databaseUrl: string;
  readonly jwtSecret: string;
  readonly parkName: string;
  readonly maxVisitors: number;
  readonly isDevelopment: boolean;

  constructor() {
    const env = validateEnv();
    this.port = parseInt(env.PORT);
    this.databaseUrl = env.DATABASE_URL;
    this.jwtSecret = env.JWT_SECRET;
    this.parkName = env.PARK_NAME;
    this.maxVisitors = parseInt(env.MAX_VISITORS);
    this.isDevelopment = env.NODE_ENV === 'development';
  }
}

// Singleton - jedna instancja konfiguracji
const config = new AppConfig();
console.log(`${config.parkName} startuje na porcie ${config.port}`);

Pól readonly nie nadpiszesz po utworzeniu obiektu. Typ mapowany Readonly<T>, zapisany jako { readonly [K in keyof T]: T[K] }, robi to samo dla wszystkich pól naraz.

Typowanie obiektów konfiguracyjnych

Złożone konfiguracje wymagają głębokiego typowania. Każda sekcja dostaje własny interfejs, a całość łączy AppConfiguration:

// Konfiguracja bazy danych
interface DatabaseConfig {
  host: string;
  port: number;
  name: string;
  credentials: {
    username: string;
    password: string;
  };
  pool: {
    min: number;
    max: number;
    idleTimeout: number;
  };
  ssl: boolean;
}

// Konfiguracja serwera
interface ServerConfig {
  port: number;
  host: string;
  cors: {
    origins: string[];
    methods: ('GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH')[];
    credentials: boolean;
  };
  rateLimit: {
    windowMs: number;
    max: number;
  };
}

// Konfiguracja parku
interface ParkConfig {
  zones: Record<string, {
    name: string;
    maxCapacity: number;
    dangerLevel: number;
    fenceVoltage: number;
  }>;
  alertThresholds: {
    temperature: { min: number; max: number };
    humidity: { min: number; max: number };
    windSpeed: number;
  };
}

// Pełna konfiguracja aplikacji
interface AppConfiguration {
  server: ServerConfig;
  database: DatabaseConfig;
  park: ParkConfig;
}

// Funkcja ładująca konfigurację z walidacją
function loadConfiguration(): AppConfiguration {
  return {
    server: {
      port: parseInt(process.env.PORT || '4000'),
      host: process.env.HOST || '0.0.0.0',
      cors: {
        origins: (process.env.CORS_ORIGINS || 'http://localhost:3000').split(','),
        methods: ['GET', 'POST', 'PUT', 'DELETE'],
        credentials: true
      },
      rateLimit: {
        windowMs: 15 * 60 * 1000,
        max: 100
      }
    },
    database: {
      host: process.env.DB_HOST || 'localhost',
      port: parseInt(process.env.DB_PORT || '27017'),
      name: process.env.DB_NAME || 'jurassic_park',
      credentials: {
        username: process.env.DB_USER || '',
        password: process.env.DB_PASS || ''
      },
      pool: { min: 2, max: 10, idleTimeout: 30000 },
      ssl: process.env.NODE_ENV === 'production'
    },
    park: {
      zones: {
        'zone-a': { name: 'Strefa Herbivore', maxCapacity: 200, dangerLevel: 1, fenceVoltage: 5000 },
        'zone-b': { name: 'Strefa Raptor', maxCapacity: 50, dangerLevel: 5, fenceVoltage: 15000 },
        'zone-c': { name: 'Strefa T-Rex', maxCapacity: 30, dangerLevel: 5, fenceVoltage: 20000 }
      },
      alertThresholds: {
        temperature: { min: -5, max: 45 },
        humidity: { min: 20, max: 95 },
        windSpeed: 120
      }
    }
  };
}

// Użycie
const appConfig = loadConfiguration();
console.log(`Strefy parku: ${Object.keys(appConfig.park.zones).length}`);
console.log(`Max raptor capacity: ${appConfig.park.zones['zone-b'].maxCapacity}`);

Literówka w nazwie pola albo napis zamiast liczby w fenceVoltage to błąd kompilacji, a nie awaria ogrodzenia o trzeciej w nocy. Record<string, {...}> opisuje strefy o dowolnych nazwach, ale jednakowym kształcie.

Typowanie odpowiedzi API (response wrappers)

Na koniec wspólny format odpowiedzi. Pole success o wartości true albo false tworzy unię dyskryminowaną (discriminated union):

// Standardowa odpowiedź API
interface ApiSuccessResponse<T> {
  success: true;
  data: T;
  meta?: {
    total: number;
    page: number;
    limit: number;
  };
}

interface ApiErrorResponse {
  success: false;
  error: {
    code: string;
    message: string;
    details?: Record<string, string>;
  };
}

type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;

// Helper functions
function sendSuccess<T>(res: Response, data: T, meta?: ApiSuccessResponse<T>['meta']): void {
  const response: ApiSuccessResponse<T> = { success: true, data };
  if (meta) response.meta = meta;
  res.json(response);
}

function sendError(res: Response, code: string, message: string, status: number = 400): void {
  const response: ApiErrorResponse = {
    success: false,
    error: { code, message }
  };
  res.status(status).json(response);
}

// Użycie w route
router.get('/zones/:zoneId/dinosaurs',
  (req: Request<{ zoneId: string }, any, any, { page?: string; limit?: string }>, res: Response) => {
    const zoneId = req.params.zoneId;
    const page = parseInt(req.query.page || '1');
    const limit = parseInt(req.query.limit || '20');

    // Symulacja danych
    const dinosaurs: Dinosaur[] = [];
    sendSuccess(res, dinosaurs, { total: 0, page, limit });
  }
);

Klient, który sprawdzi if (response.success), ma w tej gałęzi dostęp do data, a w drugiej do error, bo kompilator zawęża typ na podstawie jednego pola.

TypeScript z Node.js to potężne połączenie: typowane route'y, middleware, konfiguracja i odpowiedzi API sprawiają, że backend parku jest bezpieczny jak ogrodzenie pod napięciem 20 000 woltów, a kompilator wyłapie błędy, zanim uruchomisz serwer. Moja rada: zmienne środowiskowe waliduj przy starcie, a dane od klienta na wejściu do handlera, bo typy znikają po kompilacji. W edytorze poniżej zbudujesz typowane API parku, a w kolejnej lekcji zobaczysz, jak rozszerzać cudze typy przez module augmentation.

Pamiętaj: typy w backendzie to plan ogrodzeń, a walidacja w runtime to prąd w drutach, więc bezpieczny park potrzebuje obu.

Kod do tej lekcji: index.ts
// TypeScript z Node.js - praktyczne wzorce
// Park Jurajski - Backend API

// 1. Typowane interfejsy dla API
interface Dinosaur {
  id: string;
  species: string;
  diet: 'herbivore' | 'carnivore' | 'omnivore';
  zone: string;
  weight: number;
  dangerLevel: 1 | 2 | 3 | 4 | 5;
}

interface ListDinosaursQuery {
  zone?: string;
  diet?: Dinosaur['diet'];
  limit?: number;
  offset?: number;
}

interface CreateDinosaurBody {
  species: string;
  diet: Dinosaur['diet'];
  zone: string;
  weight: number;
  dangerLevel: Dinosaur['dangerLevel'];
}

// 2. Typowanie zmiennych środowiskowych
interface EnvironmentVariables {
  NODE_ENV: 'development' | 'production' | 'test';
  PORT: string;
  DATABASE_URL: string;
  PARK_NAME: string;
  MAX_VISITORS: string;
}

function validateEnv(required: string[]): Record<string, string> {
  const missing = required.filter(key => !process.env[key]);
  if (missing.length > 0) {
    // W prawdziwym projekcie: throw new Error(...)
    console.log(`Uwaga: brakuje zmiennych: ${missing.join(', ')}`);
  }
  return process.env as Record<string, string>;
}

// 3. Typowane obiekty konfiguracyjne
interface DatabaseConfig {
  host: string;
  port: number;
  name: string;
  pool: { min: number; max: number };
}

interface ServerConfig {
  port: number;
  cors: {
    origins: string[];
    methods: ('GET' | 'POST' | 'PUT' | 'DELETE')[];
  };
}

interface ParkZoneConfig {
  name: string;
  maxCapacity: number;
  dangerLevel: number;
  fenceVoltage: number;
}

interface AppConfig {
  server: ServerConfig;
  database: DatabaseConfig;
  zones: Record<string, ParkZoneConfig>;
}

function loadConfig(): AppConfig {
  return {
    server: {
      port: 4000,
      cors: {
        origins: ['http://localhost:3000'],
        methods: ['GET', 'POST', 'PUT', 'DELETE']
      }
    },
    database: {
      host: 'localhost',
      port: 27017,
      name: 'jurassic_park',
      pool: { min: 2, max: 10 }
    },
    zones: {
      'zone-a': { name: 'Herbivore Valley', maxCapacity: 200, dangerLevel: 1, fenceVoltage: 5000 },
      'zone-b': { name: 'Raptor Paddock', maxCapacity: 50, dangerLevel: 5, fenceVoltage: 15000 },
      'zone-c': { name: 'T-Rex Kingdom', maxCapacity: 30, dangerLevel: 5, fenceVoltage: 20000 }
    }
  };
}

// 4. Typowane odpowiedzi API
interface ApiSuccess<T> {
  success: true;
  data: T;
  meta?: { total: number; page: number; limit: number };
}

interface ApiError {
  success: false;
  error: { code: string; message: string };
}

type ApiResponse<T> = ApiSuccess<T> | ApiError;

function createSuccess<T>(data: T, meta?: ApiSuccess<T>['meta']): ApiSuccess<T> {
  const response: ApiSuccess<T> = { success: true, data };
  if (meta) response.meta = meta;
  return response;
}

function createError(code: string, message: string): ApiError {
  return { success: false, error: { code, message } };
}

// 5. Symulacja serwera
const config = loadConfig();
const dinosaurs: Dinosaur[] = [
  { id: 'D001', species: 'T-Rex', diet: 'carnivore', zone: 'zone-c', weight: 7000, dangerLevel: 5 },
  { id: 'D002', species: 'Triceratops', diet: 'herbivore', zone: 'zone-a', weight: 6000, dangerLevel: 2 },
  { id: 'D003', species: 'Velociraptor', diet: 'carnivore', zone: 'zone-b', weight: 80, dangerLevel: 4 },
];

console.log(`=== ${config.database.name.toUpperCase()} API ===`);
console.log(`Server: port ${config.server.port}`);
console.log(`Database: ${config.database.host}:${config.database.port}/${config.database.name}`);
console.log(`Zones: ${Object.keys(config.zones).length}\n`);

// Symulacja GET /dinosaurs
console.log("GET /dinosaurs?zone=zone-b");
const query: ListDinosaursQuery = { zone: 'zone-b' };
const filtered = dinosaurs.filter(d => !query.zone || d.zone === query.zone);
const response1 = createSuccess(filtered, { total: filtered.length, page: 1, limit: 20 });
console.log(JSON.stringify(response1, null, 2));

// Symulacja POST /dinosaurs
console.log("\nPOST /dinosaurs");
const body: CreateDinosaurBody = {
  species: 'Stegosaurus',
  diet: 'herbivore',
  zone: 'zone-a',
  weight: 3500,
  dangerLevel: 1
};
const newDino: Dinosaur = { id: 'D004', ...body };
const response2 = createSuccess(newDino);
console.log(JSON.stringify(response2, null, 2));

// Symulacja GET /dinosaurs/unknown
console.log("\nGET /dinosaurs/D999");
const notFound = createError('NOT_FOUND', 'Dinozaur o id D999 nie istnieje');
console.log(JSON.stringify(notFound, null, 2));

// Zone info
console.log("\n=== Strefy Parku ===");
for (const [id, zone] of Object.entries(config.zones)) {
  console.log(`${id}: ${zone.name} (danger: ${zone.dangerLevel}, fence: ${zone.fenceVoltage}V)`);
}

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Jak typować parametry żądania (params, body, query) w Express z TypeScript?

  2. 2. Jaki typ mają domyślnie zmienne z process.env w TypeScript?

Zadania praktyczne w grze

  • Edytor kodu

    Zdefiniuj interfejsy konfiguracji serwera i bazy danych, oraz funkcję ładującą konfigurację.

  • Układanie w poziomie

    Ułóż elementy typowanego route handlera Express:

  • Układanie w pionie

    Ułóż kolejność przetwarzania żądania HTTP w typowanym Express:

  • Układanie w poziomie

    Ułóż elementy mapped type w odpowiedniej kolejności:

  1. PytanieTypowanie routes w Express
  2. PytanieTypowanie zmiennych środowiskowych
  3. Zadanie z kodemĆwiczenie: Typowana konfiguracja aplikacji
  4. Ułóż w kolejnościTypowany route handler w Express
  5. Ułóż w kolejnościKolejność obsługi żądania w Express z TypeScript
  6. Ułóż w kolejnościPowtórzenie: Kolejność: Mapped type

Przydatne artykuły