nestjs-patterns

Padrões de Desenvolvimento NestJS

Padrões de produção NestJS para backends TypeScript modulares.

Quando Ativar

• Construindo APIs ou serviços NestJS
• Estruturando módulos, controladores e provedores
• Adicionando validação de DTO, guards, interceptadores ou filtros de exceção
• Configurando configurações sensíveis ao ambiente e integrações de banco de dados
• Testando unidades NestJS ou endpoints HTTP

Estrutura do Projeto

src/
├── app.module.ts
├── main.ts
├── common/
│   ├── filters/
│   ├── guards/
│   ├── interceptors/
│   └── pipes/
├── config/
│   ├── configuration.ts
│   └── validation.ts
├── modules/
│   ├── auth/
│   │   ├── auth.controller.ts
│   │   ├── auth.module.ts
│   │   ├── auth.service.ts
│   │   ├── dto/
│   │   ├── guards/
│   │   └── strategies/
│   └── users/
│       ├── dto/
│       ├── entities/
│       ├── users.controller.ts
│       ├── users.module.ts
│       └── users.service.ts
└── prisma/ ou database/

• Mantenha o código de domínio dentro dos módulos de funcionalidade.
• Coloque filtros, decoradores, guards e interceptadores transversais em common/.
• Mantenha os DTOs próximos ao módulo ao qual pertencem.

Inicialização e Validação Global

async function bootstrap() {
  const app = await NestFactory.create(AppModule, { bufferLogs: true });

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

  app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));
  app.useGlobalFilters(new HttpExceptionFilter());

  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

• Sempre ative whitelist e forbidNonWhitelisted em APIs públicas.
• Prefira um único pipe de validação global em vez de repetir a configuração de validação por rota.

Módulos, Controladores e Provedores

@Module({
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get(':id')
  getById(@Param('id', ParseUUIDPipe) id: string) {
    return this.usersService.getById(id);
  }

  @Post()
  create(@Body() dto: CreateUserDto) {
    return this.usersService.create(dto);
  }
}

@Injectable()
export class UsersService {
  constructor(private readonly usersRepo: UsersRepository) {}

  async create(dto: CreateUserDto) {
    return this.usersRepo.create(dto);
  }
}

• Controladores devem ser enxutos: analisar entrada HTTP, chamar um provedor e retornar DTOs de resposta.
• Coloque a lógica de negócio em serviços injetáveis, não em controladores.
• Exporte apenas os provedores que outros módulos realmente precisam.

DTOs e Validação

export class CreateUserDto {
  @IsEmail()
  email!: string;

  @IsString()
  @Length(2, 80)
  name!: string;

  @IsOptional()
  @IsEnum(UserRole)
  role?: UserRole;
}

• Valide cada DTO de requisição com class-validator.
• Use DTOs de resposta dedicados ou serializadores em vez de retornar entidades ORM diretamente.
• Evite vazar campos internos como hashes de senha, tokens ou colunas de auditoria.

Autenticação, Guards e Contexto da Requisição

@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('admin')
@Get('admin/report')
getAdminReport(@Req() req: AuthenticatedRequest) {
  return this.reportService.getForUser(req.user.id);
}

• Mantenha estratégias de autenticação e guards locais ao módulo, a menos que sejam verdadeiramente compartilhados.
• Codifique regras de acesso grossas em guards e faça autorização específica de recurso nos serviços.
• Prefira tipos explícitos de requisição para objetos de requisição autenticados.

Filtros de Exceção e Forma do Erro

@Catch()
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const response = host.switchToHttp().getResponse<Response>();
    const request = host.switchToHttp().getRequest<Request>();

    if (exception instanceof HttpException) {
      return response.status(exception.getStatus()).json({
        path: request.url,
        error: exception.getResponse(),
      });
    }

    return response.status(500).json({
      path: request.url,
      error: 'Internal server error',
    });
  }
}

• Mantenha um envelope de erro consistente em toda a API.
• Lance exceções do framework para erros esperados do cliente; registre e envolva falhas inesperadas centralmente.

Configuração e Validação de Ambiente

ConfigModule.forRoot({
  isGlobal: true,
  load: [configuration],
  validate: validateEnv,
});

• Valide variáveis de ambiente na inicialização, não preguiçosamente na primeira requisição.
• Mantenha o acesso à configuração por trás de helpers tipados ou serviços de configuração.
• Separe preocupações de dev/staging/prod em fábricas de configuração em vez de ramificar por todo o código de funcionalidade.

Persistência e Transações

• Mantenha o código de repositório / ORM atrás de provedores que falam a linguagem de domínio.
• Para Prisma ou TypeORM, isole fluxos de trabalho transacionais em serviços que possuem a unidade de trabalho.
• Não permita que controladores coordenem escritas de múltiplas etapas diretamente.

Testes

describe('UsersController', () => {
  let app: INestApplication;

  beforeAll(async () => {
    const moduleRef = await Test.createTestingModule({
      imports: [UsersModule],
    }).compile();

    app = moduleRef.createNestApplication();
    app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
    await app.init();
  });
});

• Teste provedores em isolamento com dependências simuladas.
• Adicione testes no nível de requisição para guards, pipes de validação e filtros de exceção.
• Reutilize os mesmos pipes/filtros globais nos testes que você usa em produção.

Padrões de Produção

• Ative logging estruturado e IDs de correlação de requisição.
• Finalize em caso de env/config inválido em vez de inicializar parcialmente.
• Prefira inicialização assíncrona de provedores para clientes de banco de dados/cache com verificações de saúde explícitas.
• Mantenha jobs em background e consumidores de eventos em seus próprios módulos, não dentro de controladores HTTP.
• Torne rate limiting, autenticação e auditoria explícitos para endpoints públicos.