Integracja TypeScript z Express: Bezpieczeństwo Typów Obsługi Tras

TypeScript stał się kamieniem węgielnym nowoczesnego rozwoju JavaScript, oferując możliwości statycznego typowania, które poprawiają jakość kodu, jego utrzymywalność i skalowalność. W połączeniu z Express.js, popularnym frameworkiem aplikacji webowych Node.js, TypeScript może znacznie zwiększyć niezawodność twoich interfejsów API. Ten obszerny przewodnik przedstawia, jak wykorzystać TypeScript do osiągnięcia bezpieczeństwa typów obsługi tras w aplikacjach Express.js, dostarczając praktycznych przykładów i najlepszych praktyk do budowania solidnych i łatwych w utrzymaniu interfejsów API dla globalnej publiczności.

Dlaczego bezpieczeństwo typów jest ważne w Express.js

W językach dynamicznych, takich jak JavaScript, błędy są często wykrywane podczas działania aplikacji, co może prowadzić do nieoczekiwanego zachowania i trudnych do debugowania problemów. TypeScript rozwiązuje ten problem, wprowadzając statyczne typowanie, umożliwiając wykrywanie błędów podczas rozwoju, zanim trafią do produkcji. W kontekście Express.js, bezpieczeństwo typów jest szczególnie kluczowe dla obsługi tras, gdzie masz do czynienia z obiektami żądań i odpowiedzi, parametrami zapytań i treściami żądań. Nieprawidłowe obsłużenie tych elementów może prowadzić do awarii aplikacji, uszkodzenia danych i luk w zabezpieczeniach.

• Wczesne wykrywanie błędów: Wykrywaj błędy związane z typami podczas rozwoju, zmniejszając prawdopodobieństwo niespodzianek w czasie działania.
• Lepsza utrzymywalność kodu: Adnotacje typów ułatwiają zrozumienie i refaktoryzację kodu.
• Ulepszone uzupełnianie kodu i narzędzia: Środowiska IDE mogą dostarczać lepsze sugestie i sprawdzanie błędów dzięki informacjom o typach.
• Mniejsza liczba błędów: Bezpieczeństwo typów pomaga zapobiegać typowym błędom programistycznym, takim jak przekazywanie nieprawidłowych typów danych do funkcji.

Konfiguracja projektu TypeScript Express.js

Zanim zagłębimy się w bezpieczeństwo typów obsługi tras, skonfigurujmy podstawowy projekt TypeScript Express.js. Posłuży to jako podstawa dla naszych przykładów.

Wymagania wstępne

• Zainstalowane Node.js i npm (Node Package Manager). Można je pobrać z oficjalnej strony Node.js. Upewnij się, że masz aktualną wersję dla optymalnej kompatybilności.
• Edytor kodu, taki jak Visual Studio Code, który oferuje doskonałe wsparcie dla TypeScript.

Inicjalizacja projektu

1. Utwórz nowy katalog projektu: mkdir typescript-express-app && cd typescript-express-app
2. Zainicjuj nowy projekt npm: npm init -y
3. Zainstaluj TypeScript i Express.js: npm install typescript express
4. Zainstaluj pliki deklaracji TypeScript dla Express.js (ważne dla bezpieczeństwa typów): npm install @types/express @types/node
5. Zainicjuj TypeScript: npx tsc --init (Spowoduje to utworzenie pliku tsconfig.json, który konfiguruje kompilator TypeScript.)

Konfiguracja TypeScript

Otwórz plik tsconfig.json i skonfiguruj go odpowiednio. Oto przykładowa konfiguracja:

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Kluczowe konfiguracje do odnotowania:

• target: Określa docelową wersję ECMAScript. es6 to dobry punkt wyjścia.
• module: Określa generowanie kodu modułów. commonjs to częsty wybór dla Node.js.
• outDir: Określa katalog wyjściowy dla skompilowanych plików JavaScript.
• rootDir: Określa katalog główny twoich plików źródłowych TypeScript.
• strict: Włącza wszystkie rygorystyczne opcje sprawdzania typów dla zwiększonego bezpieczeństwa typów. Jest to wysoce zalecane.
• esModuleInterop: Umożliwia interoperacyjność między modułami CommonJS i ES.

Tworzenie punktu wejścia

Utwórz katalog src i dodaj plik index.ts:

mkdir src
touch src/index.ts

Wypełnij src/index.ts podstawową konfiguracją serwera Express.js:

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

const app = express();
const port = 3000;

app.get('/', (req: Request, res: Response) => {
  res.send('Hello, TypeScript Express!');
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

Dodawanie skryptu kompilacji

Dodaj skrypt kompilacji do pliku package.json, aby skompilować kod TypeScript:

"scripts": {
  "build": "tsc",
  "start": "node dist/index.js",
  "dev": "npm run build && npm run start"
}

Teraz możesz uruchomić npm run dev, aby zbudować i uruchomić serwer.

Bezpieczeństwo typów obsługi tras: Definiowanie typów żądań i odpowiedzi

Rdzeń bezpieczeństwa typów obsługi tras leży w prawidłowym zdefiniowaniu typów dla obiektów Request i Response. Express.js dostarcza generyczne typy dla tych obiektów, które pozwalają określić typy parametrów zapytania, treści żądania i parametrów trasy.

Podstawowe typy obsługi tras

Zacznijmy od prostej obsługi trasy, która oczekuje nazwy jako parametru zapytania:

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

const app = express();
const port = 3000;

interface NameQuery {
  name: string;
}

app.get('/hello', (req: Request, res: Response) => {
  const name = req.query.name;

  if (!name) {
    return res.status(400).send('Name parameter is required.');
  }

  res.send(`Hello, ${name}!`);
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

W tym przykładzie:

• Request<any, any, any, NameQuery> definiuje typ dla obiektu żądania.
• Pierwsze any reprezentuje parametry trasy (np. /users/:id).
• Drugie any reprezentuje typ treści odpowiedzi.
• Trzecie any reprezentuje typ treści żądania.
• NameQuery to interfejs definiujący strukturę parametrów zapytania.

Dzięki zdefiniowaniu interfejsu NameQuery, TypeScript może teraz zweryfikować, czy właściwość req.query.name istnieje i ma typ string. Jeśli spróbujesz uzyskać dostęp do nieistniejącej właściwości lub przypisać wartość niewłaściwego typu, TypeScript zgłosi błąd.

Obsługa treści żądań

Dla tras, które akceptują treści żądań (np. POST, PUT, PATCH), możesz zdefiniować interfejs dla treści żądania i użyć go w typie Request:

import express, { Request, Response } from 'express';
import bodyParser from 'body-parser';

const app = express();
const port = 3000;

app.use(bodyParser.json()); // Important for parsing JSON request bodies

interface CreateUserRequest {
  firstName: string;
  lastName: string;
  email: string;
}

app.post('/users', (req: Request, res: Response) => {
  const { firstName, lastName, email } = req.body;

  // Validate the request body
  if (!firstName || !lastName || !email) {
    return res.status(400).send('Missing required fields.');
  }

  // Process the user creation (e.g., save to database)
  console.log(`Creating user: ${firstName} ${lastName} (${email})`);

  res.status(201).send('User created successfully.');
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

W tym przykładzie:

• CreateUserRequest definiuje strukturę oczekiwanej treści żądania.
• app.use(bodyParser.json()) jest kluczowe do parsowania treści żądań JSON. Bez tego, req.body będzie niezdefiniowane.
• Typ Request to teraz Request<any, any, CreateUserRequest>, co wskazuje, że treść żądania powinna być zgodna z interfejsem CreateUserRequest.

TypeScript zapewni teraz, że obiekt req.body zawiera oczekiwane właściwości (firstName, lastName i email) oraz że ich typy są poprawne. To znacznie zmniejsza ryzyko błędów wykonania spowodowanych nieprawidłowymi danymi w treści żądania.

Obsługa parametrów trasy

Dla tras z parametrami (np. /users/:id), możesz zdefiniować interfejs dla parametrów trasy i użyć go w typie Request:

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

const app = express();
const port = 3000;

interface UserParams {
  id: string;
}

interface User {
  id: string;
  firstName: string;
  lastName: string;
  email: string;
}

const users: User[] = [
  { id: '1', firstName: 'John', lastName: 'Doe', email: 'john.doe@example.com' },
  { id: '2', firstName: 'Jane', lastName: 'Smith', email: 'jane.smith@example.com' },
];

app.get('/users/:id', (req: Request, res: Response) => {
  const userId = req.params.id;

  const user = users.find(u => u.id === userId);

  if (!user) {
    return res.status(404).send('User not found.');
  }

  res.json(user);
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

W tym przykładzie:

• UserParams definiuje strukturę parametrów trasy, określając, że parametr id powinien być typu string.
• Typ Request to teraz Request<UserParams>, co wskazuje, że obiekt req.params powinien być zgodny z interfejsem UserParams.

TypeScript zapewni teraz, że właściwość req.params.id istnieje i ma typ string. Pomaga to zapobiegać błędom spowodowanym dostępem do nieistniejących parametrów trasy lub używaniem ich z nieprawidłowymi typami.

Określanie typów odpowiedzi

Chociaż skupienie się na bezpieczeństwie typów żądań jest kluczowe, definiowanie typów odpowiedzi również zwiększa czytelność kodu i pomaga zapobiegać niespójnościom. Możesz zdefiniować typ danych, które wysyłasz z powrotem w odpowiedzi.

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

const app = express();
const port = 3000;

interface User {
  id: string;
  firstName: string;
  lastName: string;
  email: string;
}

const users: User[] = [
  { id: '1', firstName: 'John', lastName: 'Doe', email: 'john.doe@example.com' },
  { id: '2', firstName: 'Jane', lastName: 'Smith', email: 'jane.smith@example.com' },
];

app.get('/users', (req: Request, res: Response) => {
    res.json(users);
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

Tutaj, Response<User[]> określa, że treść odpowiedzi powinna być tablicą obiektów User. Pomaga to zapewnić, że spójnie wysyłasz poprawną strukturę danych w odpowiedziach API. Jeśli spróbujesz wysłać dane, które nie są zgodne z typem `User[]`, TypeScript wyda ostrzeżenie.

Bezpieczeństwo typów w middleware

Funkcje middleware są niezbędne do obsługi przekrojowych zagadnień w aplikacjach Express.js. Zapewnienie bezpieczeństwa typów w middleware jest tak samo ważne, jak w obsłudze tras.

Typowanie funkcji middleware

Podstawowa struktura funkcji middleware w TypeScript jest podobna do obsługi trasy:

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

function authenticationMiddleware(req: Request, res: Response, next: NextFunction) {
  // Authentication logic
  const isAuthenticated = true; // Replace with actual authentication check

  if (isAuthenticated) {
    next(); // Proceed to the next middleware or route handler
  } else {
    res.status(401).send('Unauthorized');
  }
}

const app = express();
const port = 3000;

app.use(authenticationMiddleware);

app.get('/', (req: Request, res: Response) => {
  res.send('Hello, authenticated user!');
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

W tym przykładzie:

• NextFunction to typ dostarczany przez Express.js, który reprezentuje następną funkcję middleware w łańcuchu.
• Funkcja middleware przyjmuje te same obiekty Request i Response co obsługa tras.

Rozszerzanie obiektu Request

Czasami możesz chcieć dodać niestandardowe właściwości do obiektu Request w swoim middleware. Na przykład, middleware uwierzytelniający może dodać właściwość user do obiektu żądania. Aby to zrobić w sposób bezpieczny typowo, musisz rozszerzyć interfejs Request.

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

interface User {
  id: string;
  username: string;
  email: string;
}

// Augment the Request interface
declare global {
  namespace Express {
    interface Request {
      user?: User;
    }
  }
}

function authenticationMiddleware(req: Request, res: Response, next: NextFunction) {
  // Authentication logic (replace with actual authentication check)
  const user: User = { id: '123', username: 'johndoe', email: 'john.doe@example.com' };
  req.user = user; // Add the user to the request object
  next(); // Proceed to the next middleware or route handler
}

const app = express();
const port = 3000;

app.use(authenticationMiddleware);

app.get('/', (req: Request, res: Response) => {
  const username = req.user?.username || 'Guest';
  res.send(`Hello, ${username}!`);
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

W tym przykładzie:

• Używamy globalnej deklaracji do rozszerzenia interfejsu Express.Request.
• Dodajemy opcjonalną właściwość user typu User do interfejsu Request.
• Teraz możesz uzyskać dostęp do właściwości req.user w swoich obsługach tras bez narzekania przez TypeScript. Znak `?` w `req.user?.username` jest kluczowy do obsługi przypadków, gdy użytkownik nie jest uwierzytelniony, zapobiegając potencjalnym błędom.

Najlepsze praktyki integracji TypeScript z Express

Aby zmaksymalizować korzyści płynące z TypeScript w aplikacjach Express.js, postępuj zgodnie z tymi najlepszymi praktykami:

• Włącz tryb ścisły: Użyj opcji "strict": true w pliku tsconfig.json, aby włączyć wszystkie rygorystyczne opcje sprawdzania typów. Pomaga to wcześnie wyłapać potencjalne błędy i zapewnia wyższy poziom bezpieczeństwa typów.
• Używaj interfejsów i aliasów typów: Definiuj interfejsy i aliasy typów, aby reprezentować strukturę swoich danych. Dzięki temu kod jest bardziej czytelny i łatwiejszy w utrzymaniu.
• Używaj typów generycznych: Wykorzystaj typy generyczne do tworzenia komponentów wielokrotnego użytku i bezpiecznych typowo.
• Pisz testy jednostkowe: Pisz testy jednostkowe, aby zweryfikować poprawność kodu i upewnić się, że adnotacje typów są dokładne. Testowanie jest kluczowe dla utrzymania jakości kodu.
• Używaj lintera i formatera: Użyj lintera (takiego jak ESLint) i formatera (takiego jak Prettier), aby wymusić spójne style kodowania i wyłapać potencjalne błędy.
• Unikaj any typu: Zminimalizuj użycie typu any, ponieważ omija on sprawdzanie typów i niweczy cel używania TypeScript. Używaj go tylko wtedy, gdy jest to absolutnie konieczne, i rozważ użycie bardziej specyficznych typów lub generyków, gdy tylko jest to możliwe.
• Strukturyzuj projekt logicznie: Organizuj swój projekt w moduły lub foldery w oparciu o funkcjonalność. Poprawi to utrzymywalność i skalowalność aplikacji.
• Używaj wstrzykiwania zależności: Rozważ użycie kontenera wstrzykiwania zależności do zarządzania zależnościami aplikacji. Może to sprawić, że kod będzie łatwiejszy do testowania i utrzymania. Biblioteki takie jak InversifyJS są popularnymi wyborami.

Zaawansowane koncepcje TypeScript dla Express.js

Używanie dekoratorów

Dekoratory zapewniają zwięzły i ekspresyjny sposób dodawania metadanych do klas i funkcji. Możesz używać dekoratorów do uproszczenia rejestracji tras w Express.js.

Najpierw musisz włączyć eksperymentalne dekoratory w pliku tsconfig.json, dodając "experimentalDecorators": true do compilerOptions.

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "experimentalDecorators": true
  }
}

Następnie możesz utworzyć niestandardowy dekorator do rejestracji tras:

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

function route(method: string, path: string) {
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    if (!target.__router__) {
      target.__router__ = Router();
    }

    target.__router__[method](path, descriptor.value);
  };
}

class UserController {
  @route('get', '/users')
  getUsers(req: Request, res: Response) {
    res.send('List of users');
  }

  @route('post', '/users')
  createUser(req: Request, res: Response) {
    res.status(201).send('User created');
  }

  public getRouter() {
    return this.__router__;
  }
}

const userController = new UserController();

const app = express();
const port = 3000;

app.use('/', userController.getRouter());

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

W tym przykładzie:

• Dekorator route przyjmuje jako argumenty metodę HTTP i ścieżkę.
• Rejestruje udekorowaną metodę jako obsługę trasy na routerze powiązanym z klasą.
• Upraszcza to rejestrację tras i sprawia, że kod jest bardziej czytelny.

Używanie niestandardowych strażników typów

Strażnicy typów to funkcje, które zawężają typ zmiennej w określonym zakresie. Możesz używać niestandardowych strażników typów do walidacji treści żądań lub parametrów zapytania.

interface Product {
    id: string;
    name: string;
    price: number;
}

function isProduct(obj: any): obj is Product {
    return typeof obj === 'object' &&
           obj !== null &&
           typeof obj.id === 'string' &&
           typeof obj.name === 'string' &&
           typeof obj.price === 'number';
}

import express, { Request, Response } from 'express';
import bodyParser from 'body-parser';

const app = express();
const port = 3000;

app.use(bodyParser.json());

app.post('/products', (req: Request, res: Response) => {
    if (!isProduct(req.body)) {
        return res.status(400).send('Invalid product data');
    }

    const product: Product = req.body;
    console.log(`Creating product: ${product.name}`);
    res.status(201).send('Product created');
});

app.listen(port, () => {
    console.log(`Server running at http://localhost:${port}`);
});

W tym przykładzie:

• Funkcja isProduct to niestandardowy strażnik typów, który sprawdza, czy obiekt jest zgodny z interfejsem Product.
• Wewnątrz obsługi trasy /products, funkcja isProduct jest używana do walidacji treści żądania.
• Jeśli treść żądania jest prawidłowym produktem, TypeScript wie, że req.body jest typu Product w bloku if.

Uwzględnianie globalnych aspektów w projektowaniu API

Podczas projektowania interfejsów API dla globalnej publiczności należy wziąć pod uwagę kilka czynników, aby zapewnić dostępność, użyteczność i wrażliwość kulturową.

• Lokalizacja i internacjonalizacja (i18n i L10n):
  • Negocjacja treści: Wspieraj wiele języków i regionów poprzez negocjację treści w oparciu o nagłówek Accept-Language.
  • Formatowanie daty i godziny: Używaj formatu ISO 8601 do reprezentacji daty i godziny, aby uniknąć dwuznaczności w różnych regionach.
  • Formatowanie liczb: Obsługuj formatowanie liczb zgodnie z ustawieniami regionalnymi użytkownika (np. separatory dziesiętne i separatory tysięcy).
  • Obsługa walut: Obsługuj wiele walut i dostarczaj informacje o kursach wymiany tam, gdzie to konieczne.
  • Kierunek tekstu: Uwzględnij języki pisane od prawej do lewej (RTL), takie jak arabski i hebrajski.
• Strefy czasowe:
  • Przechowuj daty i godziny w UTC (Coordinated Universal Time) po stronie serwera.
  • Pozwól użytkownikom określić preferowaną strefę czasową i odpowiednio konwertuj daty i godziny po stronie klienta.
  • Używaj bibliotek takich jak moment-timezone do obsługi konwersji stref czasowych.
• Kodowanie znaków:
  • Używaj kodowania UTF-8 dla wszystkich danych tekstowych, aby wspierać szeroki zakres znaków z różnych języków.
  • Upewnij się, że twoja baza danych i inne systemy przechowywania danych są skonfigurowane do używania UTF-8.
• Dostępność:
  • Postępuj zgodnie z wytycznymi dotyczącymi dostępności (np. WCAG), aby twoje API było dostępne dla użytkowników z niepełnosprawnościami.
  • Dostarczaj jasne i opisowe komunikaty o błędach, które są łatwe do zrozumienia.
  • Używaj semantycznych elementów HTML i atrybutów ARIA w dokumentacji API.
• Wrażliwość kulturowa:
  • Unikaj używania odniesień specyficznych dla kultury, idiomów lub humoru, które mogą być niezrozumiałe dla wszystkich użytkowników.
  • Pamiętaj o różnicach kulturowych w stylach komunikacji i preferencjach.
  • Rozważ potencjalny wpływ swojego API na różne grupy kulturowe i unikaj utrwalania stereotypów lub uprzedzeń.
• Prywatność i bezpieczeństwo danych:
  • Przestrzegaj przepisów dotyczących prywatności danych, takich jak RODO (Ogólne rozporządzenie o ochronie danych) i CCPA (California Consumer Privacy Act).
  • Wdrażaj silne mechanizmy uwierzytelniania i autoryzacji w celu ochrony danych użytkowników.
  • Szyfruj wrażliwe dane zarówno podczas przesyłania, jak i w spoczynku.
  • Zapewnij użytkownikom kontrolę nad ich danymi i umożliw im dostęp, modyfikację i usuwanie ich danych.
• Dokumentacja API:
  • Dostarczaj kompleksową i dobrze zorganizowaną dokumentację API, która jest łatwa do zrozumienia i nawigacji.
  • Używaj narzędzi takich jak Swagger/OpenAPI do generowania interaktywnej dokumentacji API.
  • Dołącz przykłady kodu w wielu językach programowania, aby sprostać zróżnicowanej publiczności.
  • Tłumacz dokumentację API na wiele języków, aby dotrzeć do szerszej publiczności.
• Obsługa błędów:
  • Dostarczaj konkretne i informatywne komunikaty o błędach. Unikaj ogólnych komunikatów o błędach, takich jak \"Coś poszło nie tak.\".
  • Używaj standardowych kodów statusu HTTP do wskazywania typu błędu (np. 400 dla Nieprawidłowego Żądania, 401 dla Nieautoryzowanego, 500 dla Błędu Wewnętrznego Serwera).
  • Dołącz kody błędów lub identyfikatory, które mogą być użyte do śledzenia i debugowania problemów.
  • Loguj błędy po stronie serwera w celu debugowania i monitorowania.
• Ograniczenie szybkości (Rate Limiting): Wdrażaj ograniczenie szybkości, aby chronić API przed nadużyciami i zapewnić sprawiedliwe użytkowanie.
• Wersjonowanie: Używaj wersjonowania API, aby umożliwić zmiany kompatybilne wstecz i uniknąć uszkodzenia istniejących klientów.

Podsumowanie

Integracja TypeScript z Express znacząco poprawia niezawodność i utrzymywalność twoich interfejsów API. Wykorzystując bezpieczeństwo typów w obsłudze tras i middleware, możesz wcześnie wykrywać błędy w procesie rozwoju i budować bardziej solidne i skalowalne aplikacje dla globalnej publiczności. Definiując typy żądań i odpowiedzi, zapewniasz, że twoje API przestrzega spójnej struktury danych, zmniejszając prawdopodobieństwo błędów wykonania. Pamiętaj, aby przestrzegać najlepszych praktyk, takich jak włączanie trybu ścisłego, używanie interfejsów i aliasów typów oraz pisanie testów jednostkowych, aby zmaksymalizować korzyści płynące z TypeScript. Zawsze bierz pod uwagę czynniki globalne, takie jak lokalizacja, strefy czasowe i wrażliwość kulturowa, aby zapewnić, że twoje interfejsy API są dostępne i użyteczne na całym świecie.