Czysty projekt API w Node.js
Większość API w Node.js zaczyna się od pojedynczego pliku server.js i kilku tras. To działa, gdy aplikacja jest mała.
Potem aplikacja rośnie.
Liczba tras rośnie. Logika biznesowa przenika do handlerów tras. Obsługa błędów staje się chaosem skopiowanego kodu. Nowi programiści mają trudności ze znalezieniem odpowiednich miejsc. API nadal działa, ale staje się trudne w utrzymaniu.
Czysty projekt API zapobiega temu. Potrzebujesz struktury, która oddziela poszczególne odpowiedzialności.
Oto jak budować profesjonalne API warstwa po warstwie:
- Struktura projektu: Używaj folderów funkcjonalnych (feature folders). Każda domena powinna posiadać własny router, kontroler, serwis i schemat.
- Wersjonowanie: Zacznij od
/api/v1/od pierwszego dnia. Dodaniev2w przyszłości powinno polegać na przeniesieniu folderu, a nie na pełnej refaktoryzacji. - Warstwa kontrolerów (Controller Layer): Kontrolery obsługują HTTP. Tłumaczą żądania na wywołania serwisów i wysyłają odpowiedzi. Nie zawierają logiki biznesowej.
- Warstwa serwisów (Service Layer): To tutaj znajduje się Twoja logika biznesowa. Serwisy nie powinny wiedzieć nic o obiektach
reqanires. Interesują je tylko dane i reguły. - Walidacja: Użyj Zod na granicy systemu (boundary). Waliduj dane wejściowe, zanim trafią do kontrolerów. Zapobiega to uszkodzeniu logiki przez błędne dane.
- Centralna obsługa błędów: Użyj jednego, wspólnego handlera błędów dla całej aplikacji. Zapewnia to, że każda odpowiedź o błędzie ma tę samą strukturę.
- Spójne odpowiedzi: Użyj helpera do kształtowania odpowiedzi o sukcesie i błędach. Przewidywalny format JSON ułatwia życie programistom frontendowym.
- Rate Limiting: Chroń swoje punkty końcowe (endpoints) przed nadużyciami za pomocą middleware.
- Dokumentacja: Użyj Swaggera, aby automatycznie generować interaktywną dokumentację API.
Dlaczego to jest ważne:
Rozdzielając te warstwy, zyskujesz elastyczność. Jeśli będziesz musiał zmienić bazę danych z mock na prawdziwą, zmienisz tylko serwis. Kontrolery i routery pozostaną nienaruszone.
Jeśli zależy Ci na lepszej wydajności i wbudowanym wsparciu dla TypeScript, rozważ Fastify. Zasady strukturalne pozostają takie same, ale framework wykonuje więcej pracy za Ciebie.
Przestań wrzucać wszystko do jednego pliku „na teraz”. Budowanie odpowiedniej struktury na wczesnym etapie to nie overengineering. To minimalne wymaganie dla łatwego w utrzymaniu backendu.
Jak wygląda Twoja obecna konfiguracja Express? Używasz architektury warstwowej czy organicznej?
Źródło: https://dev.to/gavincettolo/clean-api-design-in-nodejs-a-practical-guide-3a32