Kurs JavaScript i TypeScript · Moduł 10: TypeScript w praktyce
TypeScript z Node.js - praktyczne wzorce
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. Jak typować parametry żądania (params, body, query) w Express z TypeScript?
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: