NestJS w praktyce: modularny framework Node.js dla dużych projektów backendowych

Masz backend w Node.js, który jeszcze pół roku temu był „małym API”, a dziś ma kilkadziesiąt endpointów, kilka integracji i rosnący zespół. Code review zaczyna przypominać archeologię: ten sam typ walidacji w trzech miejscach, middleware doklejane „na szybko”, a w katalogach pojawiają się foldery w stylu utils2 i helpers-new. W tym momencie pytanie o NestJS przestaje być akademickie. Chodzi o to, czy framework pomoże utrzymać spójną architekturę, przyspieszy wdrażanie nowych osób i obniży koszt zmian, zamiast dorzucić warstwę „magii”.

NestJS jest najbardziej sensowny wtedy, gdy chcesz ustandaryzować sposób budowania backendu: moduły jako jednostki odpowiedzialności, dependency injection jako mechanizm porządkowania zależności oraz wspólny pipeline (pipes/guards/interceptors/filters), który ułatwia walidację, obsługę błędów i logowanie. Jeśli jednak budujesz jednorazową usługę z kilkoma endpointami, narzut wejścia może się nie zwrócić.

NestJS architektura, moduły w NestJS, dependency injection Node.js, NestJS Fastify vs Express, request flow controller service repository, ValidationPipe DTO, filtry wyjątków NestJS, testowanie NestJS, migracja z Express do NestJS, adaptery infrastruktury NestJS

Gdy projekt Node.js „zaczyna rosnąć”: objawy, które NestJS faktycznie leczy

Sygnały ostrzegawcze w codziennej pracy zespołu

W rosnących projektach problem rzadko polega na tym, że Express albo Fastify „nie dają rady”. Problemem jest to, że aplikacja nie ma jednego, egzekwowalnego sposobu organizacji kodu. Jeden programista robi walidację w middleware, drugi w kontrolerze, trzeci w serwisie. Z czasem powstaje kilka „konwencji”, a nie jedna.

Drugi objaw to zależności, które rozlewają się po całym kodzie. Klient HTTP do integracji z zewnętrznym systemem jest importowany w pięciu modułach, bo „tak było szybciej”. Repository do bazy danych zaczyna być używane w kontrolerze, bo ktoś ominął serwis. Refaktor robi się ryzykowny, bo nie wiadomo, co na czym polega.

Trzeci, bardzo praktyczny symptom: testy stają się drogie. Bez jasnych granic i bez DI często kończy się na ręcznym mockowaniu importów, kombinowaniu z singletonami albo odpalaniu pół aplikacji, żeby przetestować jeden fragment logiki.

Co NestJS wnosi poza „ładną strukturą folderów”

NestJS jest opinionated i to jest jego przewaga w dużych systemach. Dostajesz standard: moduły, kontrolery, providery (serwisy), a do tego ustandaryzowany pipeline requestu. Dzięki temu łatwiej odpowiedzieć na pytania: „gdzie w kodzie to powinno leżeć?” i „w którym miejscu to się wykonuje?”.

Drugi element to dependency injection. Nie chodzi o „magiczne dekoratory”, tylko o to, że zależności są jawne (w konstruktorze) i łatwiej je podmieniać w testach oraz w refaktorach. Jeśli aplikacja ma kilka integracji (baza, kolejka, HTTP, cache), DI staje się dźwignią, a nie ozdobą.

Trzeci element to spójne mechanizmy przekrojowe: Pipes (walidacja/transformacja), Guards (autoryzacja), Interceptors (logowanie, metryki, cache), Filters (obsługa wyjątków). W „czystym” Express też to zrobisz, ale płacisz cenę: musisz to zaprojektować, opisać, wymusić i utrzymać.

Granica opłacalności: kiedy NestJS pomaga, a kiedy przeszkadza

Jeśli backend rozwija więcej niż jedna osoba i liczba domen zaczyna rosnąć (np. Users, Orders, Payments, Notifications), NestJS zwykle zmniejsza koszt koordynacji. Ułatwia onboarding i code review, bo struktura nie zależy od „stylu autora”.

Jeśli natomiast masz małe API (kilka endpointów), krótką żywotność projektu lub bardzo prostą domenę, NestJS może być przerostem formy. Wtedy lepiej świadomie zostać przy Express/Fastify i spisać minimalne konwencje (walidacja, błędy, logowanie) bez cięższej warstwy frameworka.

Moduły bez „module spaghetti”: jak ciąć system na kawałki, które da się utrzymać

Moduł domenowy vs moduł infrastruktury — prosta reguła podziału

Najczęstsza pułapka w NestJS to zrobienie modułów jako „warstw” typu ControllersModule, ServicesModule. To wygląda czysto tylko na początku. W praktyce zależności zaczynają iść w poprzek, bo domeny biznesowe przecinają warstwy.

Lepsza reguła: moduł ma jeden powód do zmiany i jest zorientowany na domenę. Zamiast dzielić na warstwy techniczne, tniesz na obszary biznesowe: UsersModule, PaymentsModule, OrdersModule. Każdy moduł zawiera własne kontrolery, serwisy use-case i wewnętrzne elementy infrastruktury (albo odwołuje się do infrastruktury przez porty).

Równolegle tworzysz moduły infrastrukturalne, które są „techniczne” i współdzielone: konfiguracja, baza, klienci HTTP, obserwowalność. Ich zadanie to dostarczenie implementacji, a nie logiki domenowej.

Struktura katalogów, która nie prowokuje chaosu

Nie ma jednej idealnej struktury, ale w dużych projektach dobrze działa układ, który ogranicza „wspólne wszystko”. Przykładowy szkic:

• src/modules — moduły domenowe (Users, Payments…)
• src/infrastructure — baza, klienci HTTP, cache, kolejki
• src/shared — tylko prymitywy naprawdę współdzielone (np. typy błędów, helpery stricte ogólne)
• src/app.module.ts — kompozycja (łączenie modułów)

Jeśli folder shared rośnie najszybciej, to zwykle znak, że granice domen są narysowane za słabo albo że próbujesz współdzielić implementacje zamiast kontraktów.

Importy/eksporty providerów: kiedy to jest kontrakt, a kiedy przeciek implementacji

W NestJS moduł udostępnia funkcjonalność przez eksporty. I tu pojawia się kluczowa decyzja: co eksportujesz. Eksportowanie całej listy providerów „bo może się przyda” szybko zamienia moduły w zlepek zależności. Inne moduły zaczynają używać wewnętrznych serwisów, a potem nie da się nic zmienić bez efektu domina.

Praktyczna zasada: moduł powinien mieć wąskie publiczne API. Najczęściej jest to jeden serwis-fasada (albo kilka use-case), który reprezentuje „co moduł potrafi”. Reszta providerów zostaje prywatna.

Jeśli widzisz, że moduł A importuje moduł B tylko po to, żeby dostać się do jakiegoś wewnętrznego providera, to sygnał: albo provider powinien być częścią publicznego API (świadomie), albo logika jest w złym miejscu i trzeba ją przenieść do właściwego modułu.

DI w NestJS jako dźwignia dla testów i refaktoryzacji (a nie „magia dekoratorów”)

Provider, token, scope — minimum teorii potrzebne w praktyce

Provider w NestJS to dowolna klasa/wartość/fabryka, którą framework potrafi wstrzyknąć jako zależność. W typowym backendzie providerami są: serwisy aplikacyjne, repozytoria, adaptery integracji, klienci zewnętrzni.

Token to identyfikator providera. Najczęściej jest to sama klasa (Nest użyje jej jako tokenu), ale w projektach modularnych bardzo przydatne są tokeny jako string/symbol, bo pozwalają zależeć od kontraktu, a nie od konkretnej klasy.

Scope (singleton/request/transient) też ma znaczenie, ale na start zwykle wygrywa prostota: większość providerów jako singletony. Scope requestowy jest kuszący (np. per-request context), ale zwiększa koszty i złożoność. Jeśli potrzebujesz kontekstu requestu (request id, user), często lepiej zrobić to przez interceptor i storage kontekstu, zamiast przerabiać wszystko na request-scope.

Porty i adaptery: jak nie wciągnąć infrastruktury do domeny

Duże projekty rzadko kończą się na jednym ORM i jednej integracji. Jeśli domena (use-case) zależy bezpośrednio od klienta HTTP albo od konkretnego repozytorium ORM, to zmiana technologii staje się zmianą w wielu miejscach.

Praktyczny wzorzec: domena/aplikacja definiuje port (kontrakt), infrastruktura dostarcza adapter (implementację). W NestJS wygląda to tak, że wstrzykujesz provider po tokenie portu, a nie po klasie adaptera.

Przykład: kontrakt repozytorium jako token

export const PAYMENTS_REPOSITORY = Symbol('PAYMENTS_REPOSITORY');

export interface PaymentsRepository {
  findById(id: string): Promise<Payment | null>;
  save(payment: Payment): Promise<void>;
}

@Injectable()
export class ProcessPaymentService {
  constructor(
    @Inject(PAYMENTS_REPOSITORY)
    private readonly repo: PaymentsRepository,
  ) {}

  async execute(id: string) {
    const payment = await this.repo.findById(id);
    if (!payment) throw new PaymentNotFound(id);

    payment.process();
    await this.repo.save(payment);
    return payment;
  }
}

Konsekwencja jest bardzo praktyczna: test use-case nie potrzebuje bazy ani ORM. Wystarczy mock portu. A jeśli kiedyś zmienisz implementację repozytorium, use-case zostaje nietknięty.

Pułapka „wstrzyknę wszystko do jednego serwisu”

DI potrafi zachęcać do budowania „serwisów-bogów”: jeden serwis ma w konstruktorze 10 zależności i robi „cały biznes”. To działa do pierwszych większych zmian, a potem każdy dotyk powoduje konflikt.

Jeśli liczba zależności w serwisie rośnie, zwykle są dwie przyczyny: brak podziału na use-case (przypadki użycia) albo źle postawione granice modułów. Rozwiązaniem bywa rozbicie na mniejsze serwisy aplikacyjne (np. CreatePayment, ProcessPayment) i wprowadzenie fasady tylko tam, gdzie naprawdę potrzebujesz jednego punktu wejścia.

Request flow w produkcji: od DTO do odpowiedzi, z walidacją i błędami „po drodze”

Minimalny przepływ: Controller → Service (use-case) → Repository/Adapter

W NestJS kontroler nie powinien być miejscem „biznesu”. Kontroler ma: przyjąć dane, uruchomić walidację/transformację (przez pipe), zawołać use-case, zwrócić odpowiedź. Logika domenowa i reguły powinny siedzieć w serwisie aplikacyjnym, który jest łatwy do testowania.

Prosty szkic endpointu pokazuje, jak te elementy współpracują:

export class CreatePaymentDto {
  @IsUUID()
  orderId!: string;

  @IsInt()
  @Min(1)
  amount!: number;
}

@Controller('payments')
export class PaymentsController {
  constructor(private readonly createPayment: CreatePaymentService) {}

  @Post()
  async create(@Body() dto: CreatePaymentDto) {
    const payment = await this.createPayment.execute(dto);
    return { id: payment.id, status: payment.status };
  }
}

Tu widać ważną decyzję: kontroler zwraca response shape, ale nie ujawnia całej struktury domeny. Jeśli domena się zmieni, niekoniecznie musi zmienić się API.

Walidacja: global ValidationPipe i sensowne ustawienia bezpieczeństwa/DX

Walidacja „na produkcji” to nie tylko sprawdzanie typów. To również obrona przed nadmiarowymi polami i niejawna normalizacja danych. W NestJS typowy wybór na start to globalny ValidationPipe z trzema opcjami, które realnie robią różnicę:

• whitelist: true — usuwa pola nieopisane w DTO (mniej podatności na „mass assignment” i przypadkowe dane)
• forbidNonWhitelisted: true — zamiast cichego usunięcia zwraca błąd (lepsze dla API B2B, szybciej wykrywa błędy klienta)
• transform: true — próbuje rzutować typy na podstawie DTO (wygoda, ale wymaga świadomego podejścia)

W praktyce te trzy flagi ustalają „twardość” granicy wejścia. Jeśli API obsługują różne klienckie aplikacje i integracje, forbidNonWhitelisted szybko wychwytuje rozjazdy wersji kontraktu. Jeśli masz frontend, który czasem dosyła „śmieci” z formularza, whitelist ogranicza szkody. A transform bywa zbawienne przy query params (np. page, limit), ale potrafi też ukryć problem: klient wysyła string, serwer „jakoś” to przerobi i błąd wychodzi dopiero dalej. Dobry kompromis: transform włączony, ale typy krytyczne (np. pieniądze) i tak walidowane twardo.

Konkretny setup zwykle ląduje w main.ts:

app.useGlobalPipes(new ValidationPipe({
  whitelist: true,
  forbidNonWhitelisted: true,
  transform: true,
  transformOptions: { enableImplicitConversion: false },
}));

Wyłączenie enableImplicitConversion to mały, ale istotny bezpiecznik. Wymusza jawne deklaracje (np. przez @Type(() => Number)) tam, gdzie naprawdę chcesz konwersji. Dzięki temu przypadkowe „1e3” w polu kwoty nie przejdzie tylko dlatego, że JavaScript potrafi zaskakująco dużo.

Błędy po drodze: filtry wyjątków, mapowanie domeny na HTTP i spójny format

Use-case powinien móc rzucać sensowne wyjątki domenowe (np. PaymentNotFound, PaymentAlreadyProcessed) bez myślenia o statusach HTTP. Dopiero na granicy transportu mapujesz je na odpowiedź. W NestJS robi się to filtrem wyjątków albo (przy mniejszej skali) przez własny adapter w kontrolerze. Filtr wygrywa, gdy zależy Ci na jednolitym formacie błędów i porządku w logowaniu.

@Catch()
export class HttpErrorFilter implements ExceptionFilter {
  catch(err: unknown, host: ArgumentsHost) {
    const res = host.switchToHttp().getResponse();
    const req = host.switchToHttp().getRequest();

    if (err instanceof PaymentNotFound) {
      return res.status(404).json({
        code: 'PAYMENT_NOT_FOUND',
        message: err.message,
        path: req.url,
      });
    }

    if (err instanceof PaymentAlreadyProcessed) {
      return res.status(409).json({
        code: 'PAYMENT_ALREADY_PROCESSED',
        message: err.message,
        path: req.url,
      });
    }

    return res.status(500).json({
      code: 'INTERNAL_ERROR',
      message: 'Unexpected error',
      path: req.url,
    });
  }
}

Jeśli od razu ustalisz kontrakt błędów (np. code, message, opcjonalne details dla walidacji), oszczędzasz sobie później „refaktoru API” wymuszonego przez aplikacje klienckie. To też wygodne w observability: code jest stabilniejszy niż message, więc łatwiej agregować metryki i alerty. W typowych systemach to różnica między „mamy dużo 500” a „mamy konkretnie skok konfliktów w przetwarzaniu płatności”.

Decyzje startowe, które oszczędzają czas po kilku sprintach (krótka checklista)

• Granice modułów: jeśli coś ma własne reguły i lifecycle (np. Payments, Subscriptions), to zasługuje na moduł; jeśli jest „narzędziem” (cache, http client), ląduje w infrastructure.
• Publiczne API modułu: eksportuj fasadę/use-case, nie „wnętrzności”. Jeśli ktoś potrzebuje wewnętrznego serwisu, to sygnał do przerysowania granic.
• Tokeny dla portów: repozytoria i integracje wstrzykuj po tokenach (symbol/string), żeby testy i zmiany implementacji nie rozlały się po kodzie.
• Walidacja wejścia: globalny ValidationPipe z whitelist i zakazem pól nadmiarowych; transform włączony świadomie, bez implicit conversion.
• Format błędów: jeden filtr wyjątków i stabilne code dla klas problemów, zamiast przypadkowych message i różnych struktur odpowiedzi.

Dwa scenariusze z rosnącego projektu: nowa domena i nowa integracja

Scenariusz 1: dochodzi nowa domena i zaczyna się „przeciąganie” odpowiedzialności

W pewnym momencie do systemu dokleja się kolejny obszar: nowy zestaw reguł, nowe endpointy, nowe raporty. Jeśli wcześniej wszystko było „wspólnym serwisem”, nowa domena zwykle zaczyna żyć w tych samych plikach co stara – bo to najszybsze. Problem pojawia się sprint lub dwa później: zmiana w jednym miejscu psuje coś w drugim, a testy nie mówią jasno, co jest odpowiedzialne za co.

W NestJS sensowny ruch to potraktowanie nowej domeny jak osobnego modułu domenowego, nawet jeśli na początku ma tylko 2–3 klasy. Zyskujesz od razu trzy rzeczy: osobne publiczne API, własne zależności, własne testy integracyjne modułu.

Minimalny szkielet modułu domenowego

// orders/orders.module.ts
@Module({
  controllers: [OrdersController],
  providers: [
    CreateOrderService,
    { provide: ORDERS_REPOSITORY, useClass: OrdersOrmRepository },
  ],
  exports: [CreateOrderService], // tylko to, co naprawdę ma wyjść na zewnątrz
})
export class OrdersModule {}

Praktyczna decyzja, która robi różnicę: nie eksportuj repozytorium/adaptrera. Jeśli inny moduł „musi” sięgnąć do repozytorium Orders, to zwykle oznacza, że:

• albo brakuje use-case w Orders (np. GetOrderSummary),
• albo granica jest źle narysowana (moduły mieszają się w modelu danych),
• albo próbujesz zrobić transakcję obejmującą dwie domeny bez świadomego wzorca (np. orchestrator / saga).

Jeśli sytuacja jest „pomiędzy” (dwie domeny muszą się zsynchronizować), lepiej zadziałać kontraktem: zdarzenie domenowe, prosty interfejs, albo osobny use-case orkiestrujący proces. NestJS pomaga tu przez DI i moduły, ale decyzja jest architektoniczna: kto jest właścicielem reguły i gdzie kończy się odpowiedzialność.

Scenariusz 2: dochodzi integracja z zewnętrzną usługą i kuszą skróty

Nowa integracja (np. dostawca powiadomień, antyfraud, wysyłka plików) najczęściej wjeżdża „na szybko” w serwisie aplikacyjnym: import klienta HTTP, wywołanie, obsługa błędów na miejscu. Działa, ale potem integracja zaczyna mieć retry, timeouts, kilka endpointów i różne typy błędów. Wtedy każdy use-case robi to po swojemu.

Czystszy układ: port po stronie domeny/aplikacji + adapter w module infrastruktury, a do tego jeden punkt, gdzie mapujesz błędy i ustawiasz politykę wywołań.

Port integracji jako kontrakt

export const NOTIFICATIONS_PORT = Symbol('NOTIFICATIONS_PORT');

export interface NotificationsPort {
  sendPaymentConfirmed(input: { userId: string; paymentId: string }): Promise<void>;
}

@Injectable()
export class ConfirmPaymentService {
  constructor(
    @Inject(NOTIFICATIONS_PORT)
    private readonly notifications: NotificationsPort,
  ) {}

  async execute(paymentId: string) {
    // ... logika potwierdzania
    await this.notifications.sendPaymentConfirmed({ userId: '...', paymentId });
  }
}

Adapter infrastrukturalny warto umieścić w czymś typu InfrastructureModule albo w module konkretnej integracji (np. NotificationsModule). Zależnie od skali: jeśli integracji jest kilka i mają wspólne narzędzia (HTTP client, retry, metrics), moduł infrastruktury zwykle upraszcza reużycie.

Adapter: jedno miejsce na timeouty, mapowanie błędów i obserwowalność

@Injectable()
export class NotificationsHttpAdapter implements NotificationsPort {
  constructor(private readonly http: HttpService) {}

  async sendPaymentConfirmed(input: { userId: string; paymentId: string }) {
    try {
      await firstValueFrom(
        this.http.post('/notify/payment-confirmed', input, { timeout: 3000 }),
      );
    } catch (e) {
      throw new NotificationsUnavailable('Failed to send notification', { cause: e });
    }
  }
}

Najważniejsze jest to, co dzieje się z błędem. Jeśli adapter rzuca NotificationsUnavailable, use-case może zdecydować: przerwać proces (twarde wymaganie) czy np. zapisać retry-job (miękkie wymaganie). Gdyby błąd był „surowym” wyjątkiem z klienta HTTP, ta decyzja byłaby rozlana po całym kodzie.

Testowanie bez bólu: unit vs integracja modułu i sensowne mockowanie providerów

Co testować unitowo, żeby nie przepalać czasu

Unit test w NestJS ma sens, jeśli testujesz logikę use-case lub domeny bez infrastruktury. To działa najlepiej, gdy wstrzykujesz porty (tokeny) i możesz podmienić implementacje. Wtedy test ma mało zależności i jasno mówi, jaka reguła nie działa.

Test use-case z mockiem portu

describe('ProcessPaymentService', () => {
  it('marks payment as processed and saves', async () => {
    const repo: PaymentsRepository = {
      findById: async () => ({ id: 'p1', status: 'NEW', process() { this.status = 'PROCESSED'; } }),
      save: async () => undefined,
    };

    const moduleRef = await Test.createTestingModule({
      providers: [
        ProcessPaymentService,
        { provide: PAYMENTS_REPOSITORY, useValue: repo },
      ],
    }).compile();

    const service = moduleRef.get(ProcessPaymentService);
    const result = await service.execute('p1');

    expect(result.status).toBe('PROCESSED');
  });
});

Jeśli w takim teście nagle potrzebujesz uruchamiać bazę lub robić realne HTTP, to sygnał, że use-case zależy od detali infrastruktury. Wtedy wracasz do granic: port powinien być prosty, adapter powinien brać na siebie „brud”.

Test integracyjny modułu: szybki feedback bez pełnego E2E

Druga kategoria, która często się opłaca, to integracyjne testy modułu: budujesz TestingModule z realnymi providerami z danego modułu, ale podstawiasz stuby na granicach (np. klient zewnętrzny). To dobry kompromis, gdy moduł ma sporo konfiguracji (pipes/guards/interceptors) albo skomplikowany wiring providerów.

W praktyce to test, który łapie błędy typu: „zapomniałem dodać export”, „dodałem cykliczną zależność”, „token źle nazwany” — czyli problemy, które w dużym projekcie pojawiają się częściej niż czysta logika biznesowa.

Override provider w testach modułu

const moduleRef = await Test.createTestingModule({
  imports: [PaymentsModule],
})
  .overrideProvider(NOTIFICATIONS_PORT)
  .useValue({ sendPaymentConfirmed: async () => undefined })
  .compile();

Ten mechanizm jest prosty, ale wymaga dyscypliny: provider musi być wstrzykiwany po tokenie, a nie „po konkretnej klasie adaptera”, inaczej override robi się kłopotliwy.

Techniczne decyzje, które zwykle wracają po miesiącu: platforma HTTP, konfiguracja i cross-cutting

Express vs Fastify: wybór przez wymagania, nie przez „modę”

Jeśli zależy Ci na minimalnym ryzyku integracyjnym (middleware, biblioteki oparte o expressowe request/response), Express jest najbezpieczniejszy. Fastify zaczyna wygrywać, gdy masz wysoką presję na wydajność albo zależy Ci na strictejszym podejściu do schematów i walidacji po stronie platformy.

W NestJS różnica w kodzie aplikacji bywa niewielka, ale w praktyce liczą się krawędzie: biblioteki do uploadów, reverse proxy, niestandardowe middleware. Jeśli zespół już ma zestaw sprawdzonych klocków pod Express, „przesiadka” na Fastify na starcie potrafi dać więcej pracy niż zysku.

Konfiguracja: jedna warstwa dostępu zamiast importowania process.env wszędzie

Gdy projekt rośnie, process.env rozlane po kodzie staje się cichym źródłem błędów (literówki, brak walidacji, różne domyślne wartości). W NestJS naturalny kierunek to ConfigModule + własny serwis konfiguracji, który:

• waliduje zmienne na starcie (fail fast),
• trzyma typy (TS widzi, co jest wymagane),
• pozwala testom podstawiać konfigurację bez globalnych side-effectów.

@Injectable()
export class AppConfig {
  constructor(private readonly config: ConfigService) {}

  get databaseUrl(): string {
    return this.config.getOrThrow<string>('DATABASE_URL');
  }
}

To wygląda „jak dodatkowa klasa”, ale usuwa setki drobnych decyzji z całego kodu. W kontekście zespołu to standardyzacja: każdy wie, skąd brać konfigurację i jak ją testować.

Cross-cutting bez chaosu: interceptory, guardy i logowanie na granicy

W rosnącym backendzie szybko pojawia się potrzeba rzeczy przekrojowych: request-id, spójne logowanie, pomiar czasu, autoryzacja. NestJS ma na to gotowe punkty zaczepienia (interceptor/guard), ale ważne jest, gdzie je stosujesz:

• globalnie — jeśli dotyczy całego API (np. request-id, format odpowiedzi błędu)
• na module/kontrolerze — jeśli dotyczy domeny (np. auth scope dla części endpointów)
• na pojedynczej metodzie — jeśli to wyjątek, nie reguła

Jeśli wszystko ląduje na metodach kontrolera, po kilku sprintach nikt nie wie, co jest „standardem”, a co wyjątkiem. Jeśli wszystko jest globalne, łatwo przesadzić i utrudnić testy. Granularność jest decyzją projektową, nie techniczną.

Kiedy NestJS zaczyna przeszkadzać: sygnały, że to zbyt ciężkie na dany etap

NestJS jest opłacalny, gdy potrzebujesz spójnej architektury i pracy zespołowej. Jeśli jednak większość poniższych punktów jest prawdziwa, framework może być „ramą”, która spowalnia:

• aplikacja to kilka endpointów i proste CRUD-y bez realnych reguł domenowych,
• zespół nie używa TypeScript (albo używa go minimalnie),
• wdrożenie ma być krótkotrwałe (prototype / narzędzie jednorazowe) i nikt nie będzie tego utrzymywał,
• największym problemem nie jest architektura, tylko brak jasnych wymagań i częste zwroty w produkcie.

Z drugiej strony, jeśli projekt ma już objawy „rozjeżdżających się konwencji”, testy są bolesne przez brak granic, a integracje rosną szybciej niż reszta kodu — wtedy NestJS zwykle nie jest „frameworkiem dla frameworka”, tylko narzędziem do odzyskania kontroli. W takiej sytuacji najbardziej opłaca się zacząć od: jasnych modułów domenowych, portów/adapetrów na granicach i jednego standardu walidacji + błędów. Reszta (dekoratory, guardy, interceptory) może dojść wtedy, gdy naprawdę jest na to potrzeba.

Kluczowe Wnioski

• Jeśli API rośnie i zespół zaczyna „mieszać” konwencje (walidacja raz w middleware, raz w kontrolerze, raz w serwisie), NestJS pomaga narzucić jeden, egzekwowalny standard organizacji kodu.
• Największy zysk w dużych systemach daje podejście opinionated: moduły + kontrolery + providery oraz jednolity pipeline requestu (pipes/guards/interceptors/filters), dzięki czemu wiadomo, gdzie co się dzieje i gdzie daną logikę dopisać.
• Dependency Injection to nie ozdoba dekoratorami: jawne zależności w konstruktorze ograniczają „rozlewanie się” integracji po kodzie i ułatwiają podmianę komponentów w testach oraz podczas refaktorów.
• Spójne mechanizmy przekrojowe (np. ValidationPipe dla DTO, filtry wyjątków, interceptory do logowania/metryk) obniżają koszt utrzymania — w Express/Fastify da się to zrobić, ale trzeba to samemu zaprojektować i konsekwentnie wymuszać.
• Granica opłacalności jest praktyczna: przy wielu domenach (Users/Orders/Payments) i kilku osobach w zespole NestJS zwykle zmniejsza koszt koordynacji; przy małym, krótkowiecznym API narzut wejścia może się nie zwrócić.
• Moduły warto ciąć po domenach, nie po warstwach technicznych — zamiast „ControllersModule/ServicesModule” lepiej budować UsersModule/PaymentsModule, a infrastrukturę (DB, HTTP clients, cache, observability) trzymać w osobnych modułach technicznych.
• Eksporty z modułów traktuj jak kontrakt: eksportowanie „wszystkiego, bo może się przyda” szybko powoduje przecieki implementacji i efekt domina przy zmianach; lepsze są wąskie, świadomie dobrane punkty dostępu.