Noções Básicas de NestJS

Q: Posso usar ESM com NestJS?

Sim, com "type": "module" e extensões .js nas importações. Verifique a documentação ESM do NestJS 11 para o status de suporte atual.

10 exemplos para entender o modelo mental do NestJS 11 - 7 básicos e 3 intermediários.

Pré-requisitos

npm i -g @nestjs/cli@11
nest new my-api --strict
cd my-api
npm pkg set type=module

Para padrões de DI e preocupações transversais, veja Injeção de Dependência e Guards, Interceptors & Pipes.

Exemplos Básicos

1. Módulo, Controlador, Serviço

// users.module.ts
import { Module } from "@nestjs/common";
import { UsersController } from "./users.controller.js";
import { UsersService } from "./users.service.js";
 
@Module({
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule {}

// users.service.ts
import { Injectable } from "@nestjs/common";
 
@Injectable()
export class UsersService {
  findAll() {
    return [{ id: 1, name: "Ada Lovelace" }];
  }
}

// users.controller.ts
import { Controller, Get } from "@nestjs/common";
import { UsersService } from "./users.service.js";
 
@Controller("users")
export class UsersController {
  constructor(private readonly usersService: UsersService) {}
 
  @Get()
  findAll() {
    return this.usersService.findAll();
  }
}

@Module agrupa controladores e provedores relacionados
@Injectable marca uma classe para DI
@Controller define o prefixo da rota; métodos definem verbos HTTP

2. Parâmetros de Rota e Corpo

import { Controller, Get, Post, Body, Param } from "@nestjs/common";
 
@Controller("users")
export class UsersController {
  @Get(":id")
  findOne(@Param("id") id: string) {
    return { id, name: "Ada" };
  }
 
  @Post()
  create(@Body() body: { name: string; email: string }) {
    return { id: "1", ...body };
  }
}

@Param("id") extrai parâmetros de rota
@Body() extrai o corpo da requisição (parseado pelo adaptador subjacente)
Adicione ValidationPipe para validação automática

3. Módulo Raiz e Bootstrap

// app.module.ts
import { Module } from "@nestjs/common";
import { UsersModule } from "./users/users.module.js";
 
@Module({
  imports: [UsersModule],
})
export class AppModule {}

// main.ts
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module.js";
 
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

AppModule é a raiz; importe módulos de funcionalidade
NestFactory.create inicializa o container de DI
Use NestFactory.create(AppModule, new FastifyAdapter()) para desempenho

4. Prefixo Global

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.setGlobalPrefix("api/v1");
  await app.listen(3000);
}

Todas as rotas prefixadas com /api/v1
Verificações de saúde frequentemente excluídas: setGlobalPrefix("api", { exclude: ["health"] })

5. ValidationPipe

import { ValidationPipe } from "@nestjs/common";
 
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
  await app.listen(3000);
}

import { IsEmail, IsString, MinLength } from "class-validator";
 
export class CreateUserDto {
  @IsString()
  @MinLength(1)
  name!: string;
 
  @IsEmail()
  email!: string;
}

whitelist: true remove propriedades desconhecidas
transform: true converte objetos simples em instâncias de classe DTO
Requer class-validator e class-transformer

6. Filtros de Exceção

import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from "@nestjs/common";
 
@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const status = exception.getStatus();
    response.status(status).json(exception.getResponse());
  }
}

Filtros capturam exceções e moldam respostas de erro
@Catch(HttpException) limita a exceções HTTP
Registre globalmente ou por controlador

7. Configuração de Ambiente

import { Module } from "@nestjs/common";
import { ConfigModule } from "@nestjs/config";
 
@Module({
  imports: [ConfigModule.forRoot({ isGlobal: true })],
})
export class AppModule {}

import { Injectable } from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
 
@Injectable()
export class AppService {
  constructor(private config: ConfigService) {}
 
  getPort() {
    return this.config.get<number>("PORT", 3000);
  }
}

@nestjs/config carrega arquivos .env
ConfigService injeta valores de ambiente
Valide o ambiente com Joi ou Zod na inicialização

Exemplos Intermediários

8. Adaptador Fastify

import { NestFactory } from "@nestjs/core";
import { FastifyAdapter, NestFastifyApplication } from "@nestjs/platform-fastify";
import { AppModule } from "./app.module.js";
 
async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter({ logger: true })
  );
  await app.listen({ port: 3000, host: "0.0.0.0" });
}
bootstrap();

O adaptador Fastify remove a sobrecarga do Express
Veja Realidade de Desempenho do NestJS

9. Exportações de Módulo de Funcionalidade

@Module({
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}
 
@Module({
  imports: [UsersModule],
  controllers: [OrdersController],
})
export class OrdersModule {}
// OrdersController pode injetar UsersService

exports torna os provedores disponíveis para módulos importadores
Sem exports, os provedores são privados ao módulo

10. Hooks de Ciclo de Vida

import { Injectable, OnModuleInit, OnModuleDestroy } from "@nestjs/common";
 
@Injectable()
export class DatabaseService implements OnModuleInit, OnModuleDestroy {
  async onModuleInit() {
    console.log("Conectando ao banco de dados...");
  }
 
  async onModuleDestroy() {
    console.log("Fechando conexões do banco de dados...");
  }
}

onModuleInit é executado após as dependências do módulo serem resolvidas
onModuleDestroy é executado no desligamento gracioso
Use para configuração e desativação de pool de conexões

FAQs

Quando devo escolher NestJS em vez de Fastify?

NestJS quando você precisa de DI, arquitetura modular, guards/interceptors e padrões de microsserviços. Fastify para APIs enxutas. Veja Checklist de Seleção de Framework.

O NestJS 11 está pronto para produção?

Sim. NestJS 11 suporta adaptadores Express 5 e Fastify 5 no Node 24 LTS.

O NestJS requer TypeScript?

Fortemente recomendado. NestJS é baseado em decorators e projetado para TypeScript. JavaScript funciona, mas perde a segurança de tipos.

Como o NestJS se compara ao Spring Boot?

Modelo mental semelhante: módulos, DI, decorators, guards. NestJS é o equivalente mais próximo no Node.

Posso usar ESM com NestJS?

Sim, com "type": "module" e extensões .js nas importações. Verifique a documentação ESM do NestJS 11 para o status de suporte atual.

Relacionados

Injeção de Dependência - padrões de DI
Guards, Interceptors & Pipes - transversais
NestJS + Prisma/TypeORM - camada de dados
Noções Básicas de Fastify - adaptador subjacente
Melhores Práticas do NestJS - checklist da seção

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Pré-requisitos

npm i -g @nestjs/cli@11
nest new my-api --strict
cd my-api
npm pkg set type=module

Para padrões de DI e preocupações transversais, veja Injeção de Dependência e Guards, Interceptors & Pipes.

Exemplos Básicos

1. Módulo, Controlador, Serviço

// users.module.ts
import { Module } from "@nestjs/common";
import { UsersController } from "./users.controller.js";
import { UsersService } from "./users.service.js";
 
@Module({
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule {}

// users.service.ts
import { Injectable } from "@nestjs/common";
 
@Injectable()
export class UsersService {
  findAll() {
    return [{ id: 1, name: "Ada Lovelace" }];
  }
}

// users.controller.ts
import { Controller, Get } from "@nestjs/common";
import { UsersService } from "./users.service.js";
 
@Controller("users")
export class UsersController {
  constructor(private readonly usersService: UsersService) {}
 
  @Get()
  findAll() {
    return this.usersService.findAll();
  }
}

@Module agrupa controladores e provedores relacionados
@Injectable marca uma classe para DI
@Controller define o prefixo da rota; métodos definem verbos HTTP

2. Parâmetros de Rota e Corpo

import { Controller, Get, Post, Body, Param } from "@nestjs/common";
 
@Controller("users")
export class UsersController {
  @Get(":id")
  findOne(@Param("id") id: string) {
    return { id, name: "Ada" };
  }
 
  @Post()
  create(@Body() body: { name: string; email: string }) {
    return { id: "1", ...body };
  }
}

@Param("id") extrai parâmetros de rota
@Body() extrai o corpo da requisição (parseado pelo adaptador subjacente)
Adicione ValidationPipe para validação automática

3. Módulo Raiz e Bootstrap

// app.module.ts
import { Module } from "@nestjs/common";
import { UsersModule } from "./users/users.module.js";
 
@Module({
  imports: [UsersModule],
})
export class AppModule {}

// main.ts
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module.js";
 
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

AppModule é a raiz; importe módulos de funcionalidade
NestFactory.create inicializa o container de DI
Use NestFactory.create(AppModule, new FastifyAdapter()) para desempenho

4. Prefixo Global

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.setGlobalPrefix("api/v1");
  await app.listen(3000);
}

Todas as rotas prefixadas com /api/v1
Verificações de saúde frequentemente excluídas: setGlobalPrefix("api", { exclude: ["health"] })

5. ValidationPipe

import { ValidationPipe } from "@nestjs/common";
 
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
  await app.listen(3000);
}

import { IsEmail, IsString, MinLength } from "class-validator";
 
export class CreateUserDto {
  @IsString()
  @MinLength(1)
  name!: string;
 
  @IsEmail()
  email!: string;
}

whitelist: true remove propriedades desconhecidas
transform: true converte objetos simples em instâncias de classe DTO
Requer class-validator e class-transformer

6. Filtros de Exceção

import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from "@nestjs/common";
 
@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const status = exception.getStatus();
    response.status(status).json(exception.getResponse());
  }
}

Filtros capturam exceções e moldam respostas de erro
@Catch(HttpException) limita a exceções HTTP
Registre globalmente ou por controlador

7. Configuração de Ambiente

import { Module } from "@nestjs/common";
import { ConfigModule } from "@nestjs/config";
 
@Module({
  imports: [ConfigModule.forRoot({ isGlobal: true })],
})
export class AppModule {}

import { Injectable } from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
 
@Injectable()
export class AppService {
  constructor(private config: ConfigService) {}
 
  getPort() {
    return this.config.get<number>("PORT", 3000);
  }
}

@nestjs/config carrega arquivos .env
ConfigService injeta valores de ambiente
Valide o ambiente com Joi ou Zod na inicialização

Exemplos Intermediários

8. Adaptador Fastify

import { NestFactory } from "@nestjs/core";
import { FastifyAdapter, NestFastifyApplication } from "@nestjs/platform-fastify";
import { AppModule } from "./app.module.js";
 
async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter({ logger: true })
  );
  await app.listen({ port: 3000, host: "0.0.0.0" });
}
bootstrap();

O adaptador Fastify remove a sobrecarga do Express
Veja Realidade de Desempenho do NestJS

9. Exportações de Módulo de Funcionalidade

@Module({
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}
 
@Module({
  imports: [UsersModule],
  controllers: [OrdersController],
})
export class OrdersModule {}
// OrdersController pode injetar UsersService

exports torna os provedores disponíveis para módulos importadores
Sem exports, os provedores são privados ao módulo

10. Hooks de Ciclo de Vida

import { Injectable, OnModuleInit, OnModuleDestroy } from "@nestjs/common";
 
@Injectable()
export class DatabaseService implements OnModuleInit, OnModuleDestroy {
  async onModuleInit() {
    console.log("Conectando ao banco de dados...");
  }
 
  async onModuleDestroy() {
    console.log("Fechando conexões do banco de dados...");
  }
}

onModuleInit é executado após as dependências do módulo serem resolvidas
onModuleDestroy é executado no desligamento gracioso
Use para configuração e desativação de pool de conexões

FAQs

Quando devo escolher NestJS em vez de Fastify?

NestJS quando você precisa de DI, arquitetura modular, guards/interceptors e padrões de microsserviços. Fastify para APIs enxutas. Veja Checklist de Seleção de Framework.

O NestJS 11 está pronto para produção?

Sim. NestJS 11 suporta adaptadores Express 5 e Fastify 5 no Node 24 LTS.

O NestJS requer TypeScript?

Fortemente recomendado. NestJS é baseado em decorators e projetado para TypeScript. JavaScript funciona, mas perde a segurança de tipos.

Como o NestJS se compara ao Spring Boot?

Modelo mental semelhante: módulos, DI, decorators, guards. NestJS é o equivalente mais próximo no Node.

Posso usar ESM com NestJS?

Sim, com "type": "module" e extensões .js nas importações. Verifique a documentação ESM do NestJS 11 para o status de suporte atual.

Relacionados

Injeção de Dependência - padrões de DI
Guards, Interceptors & Pipes - transversais
NestJS + Prisma/TypeORM - camada de dados
Noções Básicas de Fastify - adaptador subjacente
Melhores Práticas do NestJS - checklist da seção

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Noções Básicas de NestJS

Buscar na documentação

Noções Básicas de NestJS