Czym są moduły w NestJS?

Question

Accepted Answer

**Moduł** to klasa dekorowana za pomocą `@Module()`, która **grupuje powiązane komponenty** — kontrolery, providery/serwisy — w spójną jednostkę. Moduły to sposób, w jaki NestJS organizuje aplikację na funkcjonalności, a każda aplikacja Nest ma co najmniej główny moduł `AppModule`.

## Definiowanie modułu

```ts
import { Module } from "@nestjs/common";

@Module({
  controllers: [UsersController],    // controllers belonging to this module
  providers: [UsersService],          // providers (services) this module creates
  imports: [DatabaseModule],          // OTHER modules whose exports this module needs
  exports: [UsersService],            // what this module makes available to importers
})
export class UsersModule {}
```

## Cztery kluczowe właściwości

```text
controllers → the controllers (request handlers) in this module
providers   → the providers/services defined and instantiated here (for DI)
imports     → other modules whose EXPORTED providers this module can use
exports     → the subset of THIS module's providers shared with importing modules
```

Moduły tworzą **zakres DI**: provider jest dostępny w obrębie swojego modułu, a dla innych modułów tylko jeśli jest **eksportowany** (a drugi moduł go **importuje**).

## Moduł główny

```ts
@Module({
  imports: [UsersModule, AuthModule, DatabaseModule],   // compose feature modules
})
export class AppModule {}   // the root — bootstrapped to start the app
```

Każda aplikacja ma główny `AppModule`, który importuje moduły funkcjonalności, składając całą aplikację.

## Organizacja oparta na funkcjonalnościach

```text
src/
  app.module.ts            (root — imports feature modules)
  users/
    users.module.ts        (groups users controller + service)
    users.controller.ts
    users.service.ts
  auth/
    auth.module.ts
  database/
    database.module.ts     (shared infrastructure)
```

Konwencją jest **jeden moduł na funkcjonalność/domenę** (użytkownicy, autentykacja, produkty), utrzymując powiązany kod razem i czyniąc zależności jawne.

## Współdzielenie providerów między modułami

```ts
// UsersModule exports UsersService...
@Module({ providers: [UsersService], exports: [UsersService] })
export class UsersModule {}

// ...so AuthModule can use it by importing UsersModule
@Module({ imports: [UsersModule] })   // now AuthModule can inject UsersService
export class AuthModule {}
```

Aby użyć providera z innego modułu, moduł dostarczający musi go **eksportować**, a moduł konsumujący musi **importować** moduł dostarczający — czyniąc zależności jawne.

## Dlaczego to ważne

Moduły to organizacyjny kręgosłup każdej aplikacji NestJS — grupują powiązane kontrolery i providery w spójne jednostki funkcjonalności i definiują granice iniekcji zależności.

Zrozumienie czterech właściwości (`controllers`, `providers`, `imports`, `exports`) i szczególnie **mechanizmu import/export** do współdzielenia providerów między modułami jest niezbędne: to sposób, w jaki NestJS osiąga modularną, luźno sprzężoną architekturę, gdzie każda funkcjonalność jest samowystarczalna, a zależności są jawne.

Struktura modułów oparta na funkcjonalnościach (jeden moduł na domenę) to standardowy sposób organizacji aplikacji Nest w celu skalowalności i łatwości utrzymania.

Moduły, razem z kontrolerami i providerami, tworzą architekturę NestJS, czyniąc je fundamentalną wiedzą — opanowanie sposobu strukturyzacji aplikacji na moduły i połączenia providerów między nimi przez import/export jest konieczne do budowania każdej niebanalnej aplikacji NestJS i jest częstym źródłem zamieszania, które warto dobrze zrozumieć od początku.