8. Introdução ao framework web NestJS
8.1. Fontes
Este curso se baseia nas seguintes fontes:
- o site oficial do NestJS: https://nestjs.com e sua documentação https://docs.nestjs.com;
- o repositório do framework no GitHub: https://github.com/nestjs/nest;
8.2. Ferramentas utilizadas
- Node.js, versão LTS (18 ou superior), e seu gerenciador de pacotes npm;
- a CLI do NestJS (@nestjs/cli), uma ferramenta de linha de comando que cria a estrutura de um novo projeto, gera arquivos (controllers, serviços, módulos etc.) a partir de um template pronto e inicia o servidor de desenvolvimento;
- um editor de código: Visual Studio Code, com a extensão TypeScript;
- um cliente (HTTP) para testar os endpoints (URLs) expostos: o Postman, ou simplesmente o comando
curl; - um servidor de banco de dados MySQL.
8.3. O papel do NestJS em uma aplicação web
O NestJS é um framework Node.js escrito em TypeScript, concebido para construir o lado servidor de uma aplicação web, na maioria das vezes uma API REST (jSON), às vezes uma aplicação GraphQL ou em tempo real (WebSockets). Ele não reinventa o tratamento do próprio protocolo HTTP: por padrão, apoia-se no Express, um framework Node.js mais rudimentar, responsável por receber as requisições HTTP brutas e respondê-las (o Fastify é uma alternativa possível ao Express). O NestJS se coloca sobre essa base, oferecendo uma organização de código que nem o Node.js nem o Express impõem por si sós: divisão em módulos, controllers e serviços; injeção de dependência; decoradores...
Sua arquitetura é fortemente inspirada no Angular (decoradores, módulos, injeção de dependência). A ideia geral é a de um ponto de entrada único que recebe todas as requisições da aplicação e as encaminha ao controller apropriado conforme a ação solicitada; cada controller, por sua vez, se apoia em serviços que tratam da lógica de negócio e do acesso a dados, em vez de escrever esse código diretamente no controller.
O NestJS foi concebido principalmente para gerar respostas jSON: por padrão, tudo o que um método de controller retorna é automaticamente convertido em jSON e enviado ao cliente, sem nenhuma configuração especial; verificaremos isso na primeira ação do miniprojeto abaixo. A renderização no servidor de views HTML (com Handlebars, EJS ou Pug) continua possível (de fato a usaremos um pouco mais adiante), mas é uma opção, não o comportamento padrão.
8.4. O modelo de desenvolvimento MVC do NestJS
Três conceitos formam a estrutura de uma aplicação NestJS:
- módulos (decorador @Module): um módulo agrupa um conjunto de funcionalidades inter-relacionadas; ele declara quais controllers e serviços lhe pertencem, de quais outros módulos depende e o que disponibiliza aos demais. Uma aplicação NestJS sempre parte de um módulo raiz, AppModule, que reúne todos os outros módulos do projeto;
- controllers (decorador @Controller): um controller é o ponto de entrada da aplicação, uma classe em que cada método recebe as requisições HTTP correspondentes a uma URL específica e devolve uma resposta ao cliente;
- providers (o decorador @Injectable): um provider é uma classe comum, normalmente responsável pela lógica de negócio ou pelo acesso a dados, que o NestJS pode criar automaticamente e fornecer (ou seja, “injetar”) a qualquer controller ou serviço que precise dela.
Na prática, uma classe que precisa de um provider simplesmente o declara como parâmetro em seu construtor — o NestJS cria a instância necessária e a passa automaticamente, sem que você precise escrever new por conta própria: isso se chama injeção de dependência via construtor, uma prática usada quase sempre no NestJS. Veremos um exemplo concreto disso na linha abaixo.
8.4.1. Um primeiro projeto NestJS
8.4.1.1. O projeto de demonstração
Um projeto bem pequeno, com uma única ação [/hello], para explorar as ferramentas.

8.4.1.2. Configuração do projeto
Este projeto já está incluído, pronto para uso, no diretório de scripts que você baixou — é a pasta nestjs-course/hello-nest/ mostrada na captura de tela acima (rótulo [3]), com todos os arquivos já no lugar. Portanto, você não precisa criar nada: basta abrir essa pasta existente no VSCode (execute npm install se ainda não o fez — veja a introdução deste documento) e passar diretamente para a próxima seção.
Para sua informação, se você quisesse recriar este projeto do zero (em uma pasta vazia, fora da estrutura de diretórios do curso), foi assim que ele foi gerado:
Este comando gera um projeto contendo os seguintes arquivos essenciais:
8.4.1.3. A arquitetura de uma aplicação NestJS
Esses quatro arquivos, por si sós, ilustram a arquitetura MVC do NestJS: um ponto de entrada (main.ts), um módulo raiz (app.module.ts), um controller (app.controller.ts) e um serviço (app.service.ts).
8.4.1.4. O controller C
src/app.service.ts
Vamos comentar este código:
- linha 1: [// src/app.service.ts] — um simples comentário indicando o arquivo em questão, sem efeito na execução — útil para se orientar quando vários arquivos são exibidos em sequência.
- linha 2: [import { Injectable } from '@nestjs/common';] — como em TypeScript padrão, importamos explicitamente cada elemento utilizado, neste caso de @nestjs/common, o módulo que contém a maior parte dos decoradores e das classes utilitárias do NestJS.
- linha 4: [@Injectable()] — um decorador é uma anotação colocada imediatamente acima de uma classe, método ou parâmetro em TypeScript (precedida pelo símbolo @), que modifica ou estende seu comportamento sem alterar seu código — o mecanismo no qual se baseia praticamente todo o vocabulário do NestJS. @Injectable() marca esta classe como um provider: o NestJS a criará por conta própria e a fornecerá automaticamente a qualquer outra classe que a solicitar em seu construtor, sem que seja preciso escrever new AppService().
- Linha 5: [export class AppService {] — uma classe TypeScript comum, exportada para poder ser importada em outro lugar (aqui, pelo controller) — nada específico do NestJS neste ponto, além do decorador que a precede.
- linha 6: [ getHello(): string {] — um método comum; : string declara o tipo do valor de retorno — um recurso específico do TypeScript, ausente no JavaScript.
- Linha 7: [ return 'Hello, world!';] — o conteúdo efetivamente retornado — por enquanto, uma simples string fixa.
src/app.controller.ts
Vamos comentar este código:
- linha 1: [// src/app.controller.ts] — mesma observação de antes: um comentário sem efeito na execução.
- linha 2: [import { Controller, Get } from '@nestjs/common';] — importa os dois decoradores usados adiante: @Controller (para a classe) e @Get (para um método).
- linha 3: [import { AppService } from './app.service';] — importa o serviço definido logo antes, para que ele possa ser injetado no construtor abaixo.
- Linha 5: [@Controller()] — @Controller() decora a classe seguinte para transformá-la em um controller: o NestJS lhe enviará as requisições HTTP correspondentes às suas rotas. O argumento entre parênteses é um prefixo opcional, adicionado ao início de todas as rotas da classe — com @Controller('api'), um método decorado com @Get('x') responderia em /api/x. Aqui, o prefixo está vazio: a rota “hello”, definida abaixo, responde, portanto, diretamente em /hello.
- Linha 6: [export class AppController {] — a classe do controller, convencionalmente nomeada <Name>Controller.
- Linha 7: [ constructor(private readonly appService: AppService) {}] — o construtor declara um parâmetro appService do tipo AppService, precedido pelo modificador TypeScript private readonly, que, em uma única linha, o declara E o registra como propriedade da instância (this.appService). O NestJS detecta que o controller precisa de um AppService, cria uma instância dele (uma só, compartilhada por toda a aplicação) e a fornece automaticamente aqui: é a injeção de dependência via construtor mencionada anteriormente — você nunca escreve
new AppService(). - linha 9: [ @Get('hello')] — @Get('hello') associa o método seguinte à rota HTTP GET /hello: é esse decorador que torna a ação acessível no endereço testável http://localhost:3000/hello assim que o servidor estiver em execução. Outros decoradores têm a mesma função para os demais verbos — @Post(), @Put(), @Delete(), @Patch() — que veremos em detalhe no próximo capítulo.
- Linha 10: [ hello(): string {] — o nome do método,
hello, não tem ligação intrínseca com a rota: o NestJS o chama unicamente porque ele está decorado com@Getlogo acima. Dar-lhe um nome que reflita a ação é apenas uma convenção para facilitar a leitura. - Linha 11: [ return this.appService.getHello();] — o controller delega o trabalho ao serviço injetado em vez de codificar a resposta por conta própria: ele continua sendo uma simples camada de roteamento, enquanto a lógica de negócio reside no serviço.
src/app.module.ts
Vamos comentar este código:
- linha 1: [// src/app.module.ts] — ainda o mesmo tipo de comentário de identificação, sem efeito na execução.
- linha 2: [import { Module } from '@nestjs/common';] — importa o decorador @Module, usado na linha 6.
- linha 6: [@Module({] — @Module({...}) decora a classe seguinte para transformá-la em um módulo: ele agrupa uma parte coerente da aplicação e declara, no objeto passado como argumento, do que ela é composta. Quatro propriedades são possíveis (aqui usamos apenas duas): controllers (os controllers expostos por este módulo), providers (os serviços fornecidos por este módulo, disponíveis para injeção dentro dele), imports (os outros módulos dos quais este depende) e exports (os providers que este módulo disponibiliza aos módulos que o importam).
- Linha 7: [ controllers: [AppController],] — declara que AppController, definido anteriormente, pertence a este módulo — sem essa declaração, o NestJS ignoraria este controller e suas rotas não responderiam a nenhuma requisição.
- Linha 8: [ providers: [AppService],] — de modo semelhante, declara que AppService pertence a este módulo, tornando-o disponível para injeção de dependência — é esse array que permite ao controller recebê-lo em seu construtor.
- Linha 10: [export class AppModule {}] — o módulo raiz da aplicação, convencionalmente nomeado AppModule: é ele que main.ts usa para iniciar o servidor.
8.4.1.5. Execução
Ao abrir http://localhost:3000/hello em um navegador, você recebe a resposta “Hello, world!”. O decorador @Get('hello') associa o método hello() ao endpoint /hello da URL; o NestJS envia a string retornada tal como está. Por padrão, npm run start:dev inicia o servidor na porta 3000 — é a porta que veremos em todos os exemplos dos capítulos seguintes.
8.4.1.6. Conclusão
O trio controller/serviço/módulo que acabamos de escrever é a espinha dorsal de qualquer aplicação NestJS; é a estrutura que veremos, em maior escala, nos capítulos seguintes e no estudo de caso do Capítulo 6.
8.4.2. A arquitetura MVC do NestJS
8.4.2.1. Os módulos
O decorador @Module aceita quatro propriedades principais: imports (os outros módulos dos quais este módulo depende), controllers (os controllers que ele expõe), providers (os serviços que ele fornece, tanto a si mesmo quanto aos módulos que o importam) e exports (os providers que ele disponibiliza a outros módulos). Uma aplicação NestJS é uma árvore de módulos, com um módulo raiz — AppModule — que os reúne todos na inicialização, de forma semelhante a uma visão geral do projeto (quem conhece o Spring reconhecerá aqui o papel de um arquivo central de configuração).
8.4.2.2. Controllers
Um controller é uma classe anotada com @Controller(prefixo): ele recebe requisições HTTP e devolve uma resposta ao cliente. O prefixo, que é opcional, é adicionado ao início de todas as rotas da classe — com @Controller('users'), um método decorado com @Get(':id') responderia em /users/:id, e não em /:id. Cada método do controller é associado a uma rota por meio de um decorador correspondente ao verbo desejado: @Get para ler, @Post para criar, @Put para substituir, @Patch para modificar parcialmente, @Delete para excluir. O caminho de uma rota pode conter segmentos variáveis, introduzidos por :, como em @Get('users/:id') (:id captura então o valor presente nessa posição da URL requisitada). No próximo capítulo, detalharemos os decoradores que permitem recuperar as informações fornecidas pela requisição (@Query, @Param, @Body...).
8.4.2.3. Providers e injeção de dependência
Uma classe anotada com @Injectable() é um provider: o NestJS a instancia e a injeta automaticamente onde quer que seja solicitada em um construtor, desde que esteja listada no array providers de um módulo (o próprio ou um módulo que a exporte). Por padrão, um provider do NestJS é um singleton: uma única instância é criada quando a aplicação inicia, e essa mesma instância é compartilhada por todos os componentes que precisam dela — em vez de uma nova instância ser recriada a cada requisição (quem conhece o Spring reconhecerá aqui o comportamento padrão de um bean).
8.4.2.4. Comparação resumida com o Spring MVC
A tabela a seguir tem caráter meramente informativo: destina-se a leitores que já conhecem o Spring MVC e desejam aproveitar seus conhecimentos. Não é necessário entendê-la para acompanhar o restante deste curso — todos os termos do NestJS listados aqui são explicados, independentemente do Spring, neste capítulo e nos seguintes.
- @Controller (Spring) ↔ @Controller (NestJS)
- @GetMapping / @RequestMapping (Spring) ↔ @Get(), @Post()... (NestJS)
- @RequestParam (Spring) ↔ @Query() (NestJS)
- @PathVariable (Spring) ↔ @Param() (NestJS)
- @RequestBody (Spring) ↔ @Body() (NestJS)
- @Service / @Repository + @Autowired (Spring) ↔ @Injectable() + injeção via construtor (NestJS)
- arquivo de configuração / varredura de componentes (Spring) ↔ @Module (NestJS)
- ResponseEntity<T> (Spring) ↔ objeto retornado diretamente, ou @Res() para controle total (NestJS)
8.5. Ações: a resposta

Este capítulo explora, ação por ação, as diferentes maneiras pelas quais um controller do NestJS pode construir a resposta enviada ao cliente. Cada ação pode ser testada com curl ou Postman em um novo projeto criado com nest new actions-response; como no capítulo anterior, npm run start:dev inicia o servidor na porta 3000, de modo que todas as URLs das ações abaixo têm a forma http://localhost:3000/.... Todas as ações deste capítulo são métodos de um único controller, AppController, anotado com @Controller() sem prefixo — como no capítulo anterior, o argumento entre parênteses de @Get(...) em cada ação fornece, portanto, diretamente a sua URL.
8.5.1. Componentes da aplicação NestJS
A aplicação é composta por três arquivos (veja 4 acima)
8.5.1.1. src/app.controller.ts
Este arquivo reúne seis métodos em uma única classe, AppController, com os decoradores (Header, HttpCode, Redirect, Res) usados por um ou mais desses métodos agrupados no início do arquivo.
Voltaremos a esses seis métodos um pouco mais adiante.
8.5.1.2. src/app.module.ts
Vamos comentar este código:
- linha 5: @Module({ — diferentemente do módulo raiz do projeto hello-nest visto no capítulo anterior, aqui não há a propriedade
providers: este projeto não define nenhum serviço; toda a lógica está contida nos próprios métodos do controller. - linha 6: controllers: [AppController], — a única declaração necessária: ela associa AppController — e, portanto, suas seis rotas — a este módulo.
8.5.1.3. src/main.ts
O ponto de entrada permanece o mesmo entre os projetos: ele usa exatamente o mesmo esqueleto de bootstrap() do projeto hello-nest do capítulo anterior, que cria a aplicação a partir do módulo raiz e depois escuta na porta 3000.
8.5.1.4. [/a01]: retornar texto
Vamos comentar este código:
- linha 1: [@Get('a01')] — @Get('a01') associa este método à rota GET /a01 — como no capítulo anterior, esse decorador liga uma URL a um método. Esta ação fica, portanto, acessível em http://localhost:3000/a01 depois que o servidor é iniciado (npm run start:dev).
- Linha 2: [a01(): string {] — o nome do método, a01, não tem ligação intrínseca com a rota: o NestJS o chama unicamente porque ele está decorado com @Get logo acima. Dar-lhe o mesmo nome da ação, como é feito ao longo deste capítulo, é apenas uma convenção para facilitar a leitura, adotada para encontrar facilmente a ação correspondente a uma URL.
- Linha 3: [ return 'Hello from the action [/a01]';] — o método simplesmente retorna uma string.
O NestJS envia a string retornada tal como está ao cliente, com um cabeçalho Content-Type definido como text/html.
8.5.1.5. [/a02]: retornar um objeto, serializado automaticamente em JSON
Vamos comentar este código:
- linha 1: [@Get('a02')] — acessível em http://localhost:3000/a02.
- linha 2: [a02(): object {] — desta vez, o método declara que retorna um object em vez de uma string — é esse tipo de retorno que mudará o comportamento do NestJS; veja abaixo.
- Linha 3: [ return { message: 'Hello', value: 42 };] — um literal de objeto JavaScript/TypeScript, com duas propriedades.
Assim que um método retorna um objeto (ou um array), o NestJS o serializa automaticamente em JSON e define o cabeçalho Content-Type como: application/json — você não precisa fazer nada de especial para obter uma resposta JSON, ao contrário da string de [/a01], que produz texto simples.
8.5.1.6. [/a03]: alterar o código de status HTTP
Vamos analisar este código:
- linha 1: [import { Get, HttpCode } from '@nestjs/common';] — importa os dois decoradores usados abaixo.
- linha 3: [@Get('a03')] — acessível em http://localhost:3000/a03. Por padrão, uma ação @Get responde com o código de status HTTP 200 (o número de três dígitos retornado em toda resposta, que informa ao cliente se a requisição foi bem-sucedida — 200: sucesso, 404: recurso não encontrado, 500: erro do servidor etc.).
- Linha 4: [@HttpCode(201)] — @HttpCode(201) força explicitamente o código de status retornado por esta ação, neste caso 201 (Created), em vez do 200 padrão — uma escolha puramente didática aqui, para ilustrar o decorador, que normalmente seria reservado a uma ação que realmente cria um recurso (tipicamente um @Post em vez de um @Get). Um navegador comum não exibe o código de status recebido; para verificá-lo, use o Postman ou a aba Rede (Network) das ferramentas de desenvolvedor.
8.5.1.7. [/a04]: adicionar um cabeçalho HTTP
Vamos comentar este código:
- linha 1: [import { Get, Header } from '@nestjs/common';] — importa os dois decoradores usados abaixo.
- linha 3: [@Get('a04')] — acessível em http://localhost:3000/a04.
- linha 4: [@Header('X-My-Header', 'a-value')] — um cabeçalho (HTTP) é uma informação adicional enviada com a resposta, separada do corpo da mensagem — o Content-Type mencionado acima é um exemplo padrão. @Header(nome, valor) adiciona aqui um cabeçalho personalizado, X-My-Header, com o valor a-value. Assim como no código de status, um navegador comum não exibe os cabeçalhos recebidos por padrão: é preciso usar o Postman ou as ferramentas de desenvolvedor para vê-los.
8.5.1.8. [/a05]: redirecionar o cliente
Vamos comentar este código:
- linha 1: [import { Get, Redirect } from '@nestjs/common';] — importa os dois decoradores usados abaixo.
- linha 3: [@Get('a05')] — acessível em http://localhost:3000/a05 — quando aberta em um navegador, essa URL redireciona imediatamente para https://nestjs.com.
- linha 4: [@Redirect('https://nestjs.com', 302)] — @Redirect(url, código) faz com que a ação responda com um redirecionamento HTTP para url, com o código de status código (302, Found, é o valor padrão se esse segundo argumento for omitido) — o navegador segue automaticamente esse redirecionamento, sem intervenção do usuário.
- Linha 5: [a05() {}] — o corpo do método está vazio: todo o trabalho é feito pelo decorador @Redirect logo acima; o método em si não tem nada a retornar.
8.5.1.9. [/a06]: acesso direto ao objeto de resposta do Express
Vamos comentar este código:
- linha 1: [import { Get, Res } from '@nestjs/common';] — importa o decorador @Res, usado na linha 5, além do já conhecido @Get.
- linha 2: [import { Response } from 'express';] — importa o tipo TypeScript Response fornecido pelo Express (o servidor HTTP no qual o NestJS se apoia por padrão; veja o capítulo “Introdução”), usado para tipar o parâmetro abaixo.
- Linha 4: [@Get('a06')] — acessível em http://localhost:3000/a06.
- Linha 5: [a06(@Res() res: Response): void {] — @Res() passa diretamente o objeto de resposta bruto do Express como argumento do método, chamado aqui de res. É o oposto de [/a01]/[/a02]: em vez de deixar o NestJS construir a resposta a partir do valor retornado, o código aqui assume o controle total de toda a resposta HTTP.
- Linha 6: [ res.status(200).json({ response: 'built by hand' });] — chama diretamente os métodos da API do Express — status(200) define o código de status, json({...}) serializa o objeto em JSON e efetivamente envia a resposta (essas duas etapas normalmente são automáticas, como em [/a02]).
Executando a aplicação NestJS

Em um terminal, na raiz do projeto, digite o comando:
Você receberá a seguinte resposta:
8.5.2. Testes no Postman
Para os testes no Postman, você pode usar a seguinte coleção de requisições:

Aqui estão os testes no Postman para as seis ações:
8.5.2.1. Ação a01

8.5.2.2. Ação a02

8.5.2.3. Ação a04

Para ver o cabeçalho enviado pelo servidor:

8.5.2.4. Ação a05

Em [1], o site para o qual o cliente Postman foi redirecionado.
8.5.2.5. Ação a06

8.5.3. Conclusão
O NestJS oferece, portanto, duas abordagens para construir uma resposta: deixar que o framework a construa automaticamente com base no valor retornado pelo método — o caso mais comum, ilustrado de [/a01] a [/a05] — ou, usando @Res(), assumir o controle total e manual da resposta HTTP, ao custo de ter que gerenciar tudo por conta própria ([/a06]).
8.6. Ações: o modelo

Este capítulo é a contrapartida do anterior: o foco não é mais a construção da resposta, mas a recuperação das informações fornecidas pela requisição do cliente (parâmetros de URL, corpo enviado, cabeçalhos etc.). Como no capítulo anterior, todas as ações são métodos do mesmo controller AppController anotado com @Controller() sem prefixo, e o servidor escuta por padrão na porta 3000 — as URLs abaixo têm, portanto, todas a forma http://localhost:3000/....
8.6.1. Os componentes da aplicação NestJS
Vamos examinar mais de perto os arquivos (veja 4 acima) que compõem o projeto actions-model.
8.6.1.1. src/app.controller.ts
Uma única classe, AppController, contém oito métodos, com todos os decoradores (@Query, @Param, @Body, @Headers, @Session, @Req) e o CalculationDto (veja [/m04] e [/m05]) usados por um ou mais deles. Falaremos desses métodos em breve.
8.6.1.2. src/app.module.ts
Mesma observação do capítulo anterior: também aqui não há providers , pois este projeto não define serviços separados.
8.6.1.3. src/main.ts
Vamos comentar este código:
- linha 9: app.use(session({ secret: 'xxx', resave: false, saveUninitialized: false })); — instala o middleware do Express
express-session— é essa linha, que aparece apenas uma vez aqui e se aplica a toda a aplicação, que habilita o contador de sessão visto em [/m07]. O secret é usado para assinar o cookie de sessão; em produção, ele deve vir de uma variável de ambiente e nunca deve ser escrito em texto simples no código. - linhas 10–15: app.useGlobalPipes(new ValidationPipe({ ... })); — declara globalmente, para todos os controllers da aplicação, o mesmo ValidationPipe que foi aplicado localmente em [/m05] com @UsePipes. As duas opções
transform: trueeenableImplicitConversion: truehabilitam a conversão automática de tipos (especificamente, de strings daURLpara números) antes da validação.
8.6.1.4. [/m01]: parâmetros de um GET
Vamos comentar este código:
- linha 1: [@Get('m01')] — como no capítulo anterior, esse decorador associa o método à rota GET /m01.
- linha 2: [m01(@Query('name') name: string, @Query('age') age: string): object {] — @Query(nome) é um novo decorador, aplicado desta vez a um parâmetro de método, e não à classe ou ao próprio método: ele extrai um parâmetro da query string (a parte da URL após o ?, na forma chave=valor separados por &) e o fornece diretamente como argumento — já nomeado e tipado — sem que você precise recuperá-lo. Aqui, @Query('name') extrai o parâmetro "name" e o atribui à variável
name, e o mesmo vale paraage. Esta ação pode, portanto, ser testada em http://localhost:3000/m01?name=Serge&age=60, que retornará name = "Serge" e age = "60" (um valor de query string é sempre recebido como string, mesmo que se pareça com um número). - Linha 3: [ return { name, age };] — notação abreviada para { name: name, age: age }: quando o nome da propriedade e o nome da variável são idênticos, basta escrever o nome uma vez.
8.6.1.5. [/m02]: elementos de uma URL
Vamos comentar este código:
- Linha 1: [@Get('m02/:id')] — o :id no caminho da rota é um segmento variável (um parâmetro de rota): o NestJS captura o que aparece nessa posição específica da URL requisitada. Uma requisição para http://localhost:3000/m02/5 captura, portanto, 5; uma requisição para /m02/abc capturaria abc.
- Linha 2: [m02(@Param('id') id: string): object {] — @Param(nome) é o decorador complementar de @Query, visto em [/m01]: enquanto @Query lê a query string (após o ?), @Param lê um segmento variável do próprio caminho (aqui: id). @Param('id') injeta, portanto, o valor capturado na variável id.
- Linha 3: [ return { id };] — simplesmente retorna o valor recebido, encapsulado em um objeto.
8.6.1.6. [/m03]: parâmetros de um POST
Vamos comentar este código:
- Linha 1: [@Post('m03')] — @Post() é o decorador equivalente a @Get() para o verbo HTTP POST, normalmente usado para enviar dados ao servidor (criar um recurso, enviar um formulário etc.) em vez de simplesmente ler uma URL. Ao contrário das ações anteriores, esta não pode ser testada apenas digitando a URL em um navegador (que só faz requisições GET): é necessário um cliente capaz de enviar uma requisição POST
- linha 2: [ m03(@Body() body: any): object {] — @Body(), sem argumentos, injeta desta vez o corpo inteiro da requisição (ao contrário de @Query/@Param, que leem cada um um único campo nomeado);
anyé o tipoTypeScriptque significa “qualquer tipo”, usado aqui porque nenhum formato específico foi imposto ainda aos dados recebidos (veja[/m04]para uma versão tipada). - linha 3: [ return body;] — retorna o corpo recebido tal como está, para verificar o que foi enviado.
8.6.1.7. [/m04]: mapear os parâmetros postados para uma classe
dto/calculation.dto.ts
Vamos comentar este código:
- Linha 1: [// dto/calculation.dto.ts] — um comentário para identificar o arquivo; não tem efeito na execução.
- linha 2: [export class CalculationDto {] — uma classe que descreve unicamente o formato dos dados esperados, sem nenhum método — isso se chama DTO (Data Transfer Object), uma estrutura de dados simples e tipada usada para transferir informações de uma parte do programa para outra (neste caso, do cliente para o controller).
- Linha 3: [ married: string;] — uma propriedade tipada: married deve ser uma string — o TypeScript verificará esse tipo em tempo de compilação.
- Linha 4: [ children: number;] — “children” deve ser um número.
- Linha 5: [ salary: number;] — O salário deve ser um número.
Vamos analisar este código:
- Linha 1: [@Post('m04')] — mesma observação de [/m03]: teste com o Postman ou com curl, e não diretamente na barra de endereço de um navegador.
- linha 2: [m04(@Body() data: CalculationDto): CalculationDto {] — ainda @Body(), como em [/m03], mas desta vez a variável
dataé tipada como CalculationDto em vez deany: o NestJS converte automaticamente o JSON recebido em uma instância dessa classe, com suas propriedades nomeadas e tipadas (married, children, salary) em vez de um objeto genérico e sem tipo — o que permite a verificação pelo compilador TypeScript e o autocompletar no editor. Observação: nesta etapa, ainda não há garantia de que os dados recebidos realmente estejam em conformidade com esse formato (um cliente poderia enviar qualquer coisa) — veja[/m05]para a validação propriamente dita.
8.6.1.8. [/m05]: validando o modelo da ação
Instalamos duas bibliotecas complementares para o NestJS para a validação:
dto/calculation.dto.ts
Vamos comentar este código:
- linha 1: [import { IsIn, IsInt, Min } from 'class-validator';] — class-validator é uma biblioteca independente do NestJS (mas muito usada com ele) que permite definir regras de validação diretamente nas propriedades de uma classe por meio de decoradores — como @IsIn, @IsInt, e Min, que são importados aqui.
- Linha 4: [ @IsIn(['yes', 'no'])] — @IsIn([...]) exige que o valor da propriedade seguinte (married) faça parte da lista fornecida — neste caso, apenas 'yes' ou 'no'; qualquer outro valor será rejeitado.
- Linha 7: [ @IsInt() @Min(0)] — dois decoradores podem ser aplicados à mesma propriedade, um após o outro: @IsInt() exige um inteiro, e @Min(0) exige um valor maior ou igual a 0 — as duas regras se aplicam em conjunto a “children”.
Vamos comentar este código:
- linha 1: [import { Body, Post, UsePipes, ValidationPipe } from '@nestjs/common';] — importa, além dos decoradores já conhecidos, UsePipes e ValidationPipe
- linha 3: [@Post('m05')] — para ser testada com o Postman ou com curl (POST), e não na barra de endereço de um navegador.
- Linha 4: [@UsePipes(new ValidationPipe())] — um pipe do NestJS é um mecanismo que se interpõe entre a requisição recebida e o código do método para transformar ou validar os dados antes que cheguem ao controller. ValidationPipe, fornecido pelo NestJS, é o pipe de validação padrão: ele avalia os decoradores de class-validator aplicados ao DTO (@IsIn, @IsInt, @Min...) e rejeita automaticamente qualquer requisição cujos dados não os respeitem — com uma resposta HTTP 400 (Bad Request) — sem que você precise escrever um único
if. @UsePipes() é o decorador que habilita um pipe em um método específico.
8.6.1.9. [/m06]: acessando um cabeçalho HTTP
Vamos comentar este código:
- Linha 1: [@Get('m06')] — acessível em http://localhost:3000/m06.
- linha 2: [m06(@Headers('user-agent') userAgent: string): object {] — @Headers(nome) lê um cabeçalho HTTP específico da requisição recebida (em oposição a @Header(), discutido no capítulo anterior, que adicionava um cabeçalho à resposta enviada — a mesma palavra, com sentido oposto conforme você esteja lendo ou escrevendo). Aqui, @Headers('user-agent') recupera o cabeçalho User-Agent (o nome do navegador ou da ferramenta que enviou a requisição, enviado automaticamente por qualquer cliente). Sem argumento, @Headers() retornaria um objeto contendo todos os cabeçalhos da requisição.
- Linha 3: [ return { userAgent };] — retorna o valor lido, encapsulado em um objeto.
8.6.1.10. [/m07]: acessando a sessão
main.ts
Vamos comentar este código:
- Linha 2: [app.use(session({ secret: 'xxx', resave: false, saveUninitialized: false }));] — app.use(...) registra um middleware do Express — um processo executado para cada requisição recebida antes que ela chegue a qualquer controller. Aqui, o middleware session (fornecido pela biblioteca express-session) configura o gerenciamento de sessão para toda a aplicação:
secreté usado para assinar o cookie de sessão (para impedir que seja adulterado), eresaveesaveUninitializedsão opções que controlam quando a sessão é efetivamente salva no lado do servidor.
Vamos analisar este código:
- linha 1: [import { Get, Session } from '@nestjs/common';] — importa o @Session decorador
- linha 3: [@Get('m07')] — acessível em http://localhost:3000/m07 — atualizar a página várias vezes incrementa o contador; seu valor é preservado no lado do servidor entre as requisições.
- linha 4: [m07(@Session() session: Record<string, any>): object {] — uma sessão é um espaço de armazenamento associado a um visitante específico, mantido no lado do servidor ao longo de várias requisições sucessivas — ao contrário de uma variável comum, que seria reinicializada a cada nova requisição. O cliente é identificado por um cookie contendo um ID de sessão, que o navegador envia automaticamente a cada requisição depois de recebê-lo. @Session() injeta diretamente esse espaço de armazenamento como argumento do método.
- linha 5: [ session.counter = (session.counter ?? 0) + 1;] — o operador ?? (null coalescing) retorna seu lado direito somente se o lado esquerdo for null ou undefined — aqui, ele inicializa o contador com 0 na primeiríssima visita, antes de incrementá-lo em 1 a cada requisição seguinte.
- Linha 6: [ return { counter: session.counter };] — retorna o valor atual do contador, armazenado na sessão.
É exatamente o express-session que usamos no Capítulo 6 para armazenar a autenticação e a lista de simulações do servidor de cálculo de imposto.
8.6.1.11. [/m08]: acessando a requisição inteira
Vamos analisar este código:
- linha 1: [import { Get, Req } from '@nestjs/common';] — importa o @Req decorador
- linha 2: [import { Request } from 'express';] — importa o tipo TypeScript Request fornecido pelo Express, para tipar o parâmetro abaixo.
- Linha 4: [@Get('m08')] — disponível em http://localhost:3000/m08.
- Linha 5: [m08(@Req() req: Request): object {] — @Req() injeta diretamente o objeto de requisição bruto do Express, com tudo o que ele contém (método, URL, cabeçalhos, corpo, parâmetros...), em vez de uma única informação por vez, como fazem @Query, @Param, @Body, @Headers ou @Session. Do lado da requisição, é o equivalente exato do que @Res() era do lado da resposta em [/a06] no capítulo anterior: menos automação fornecida pelo NestJS, mas acesso total, sem restrições.
- Linha 6: [ return { method: req.method, url: req.url };] — lê diretamente duas propriedades do objeto de requisição do Express: method (o verbo HTTP utilizado) e url (o caminho requisitado).
Executando a aplicação NestJS

Em um terminal, na raiz do projeto, digite o comando:
Você receberá a seguinte resposta:
8.6.2. Testes no Postman
Para os testes no Postman, você pode usar a seguinte coleção de requisições:

Aqui estão os testes no Postman para os oito métodos da aplicação:
8.6.2.1. Ação m01

8.6.2.2. Ação m02

8.6.2.3. Ação m03

8.6.2.4. Ação m04

8.6.2.5. Ação m05


8.6.2.6. Ação m06

8.6.2.7. Ação m07
Após 3 requisições:

8.6.2.8. Ação m08

8.6.3. Conclusão
@Query, @Param, @Body, @Headers e @Session cobrem a grande maioria das necessidades; @Req() continua disponível para um acesso total, sem restrições, à requisição — é a opção escolhida pela ação [m06] do nosso estudo de caso, pelas mesmas razões da ação [/a06] .
8.7. Acesso a dados: NestJS e bancos de dados
O NestJS oferece várias maneiras de acessar um banco de dados: três abordagens coexistem no ecossistema Node, da mais próxima do SQL à mais próxima de um ORM com entidades decoradas — ao contrário do Spring Data, que impõe uma única abordagem aos desenvolvedores Java.

8.7.1. O driver nativo: uma camada [DAO] codificada à mão
O Node oferece drivers leves para cada SGBD (mysql2 para MySQL, pg para PostgreSQL...) que expõem diretamente o SQL: você escreve as consultas por conta própria, sem camada de abstração entre o código e o banco de dados. É a abordagem usada pela camada [DAO] do nosso estudo de caso: um serviço @Injectable() abre uma conexão e executa consultas SQL explícitas.

Trecho de src/model/server-dao.service.ts (capítulo [case study]):
Vamos comentar este código:
- linha 1: [import mysql from 'mysql2/promise';] — o driver MySQL/MariaDB para Node.js é importado (o pacote mysql2); o subcaminho mysql2/promise fornece a variante baseada em Promises (e, portanto, utilizável com
await), em vez da variante legada baseada em callbacks; - linha 3: [@Injectable()] — este decorador marca a classe seguinte como um provider do NestJS: uma classe que o NestJS pode instanciar por conta própria e injetar no construtor de outra classe (aqui, ServerDaoService será injetado em um controller de ação; veja o próximo capítulo) — sem esse decorador, o NestJS não conseguiria criá-la automaticamente;
- linha 6: [const connection = await mysql.createConnection({ ... })] — mysql.createConnection(...) abre uma nova conexão de rede com o servidor MySQL/MariaDB, com o host, o banco de dados, o nome de usuário e a senha fornecidos diretamente como parâmetros;
awaitsuspende a execução da função até que a conexão seja estabelecida com sucesso; - linha 12: [const [brackets] = await connection.query('select ... order by id')] — connection.query(...) executa a consulta SQL passada como string; o método retorna um array de dois elementos, o primeiro dos quais (recuperado aqui por desestruturação, [brackets]) contém as linhas lidas — nenhum SQL é gerado e não há mapeamento objeto-relacional: é exatamente o texto que é escrito para o banco de dados;
- linha 16: [await connection.end();] — a conexão é fechada explicitamente depois que a leitura termina — com o driver nativo, o gerenciamento do ciclo de vida da conexão é inteiramente responsabilidade do código, ao contrário dos dois exemplos de ORM apresentados mais adiante.
Essa abordagem oferece controle total sobre o SQL executado, sem nenhuma “mágica” nem geração automática de consultas: o que você vê no código é exatamente o que é enviado ao MySQL (a mesma filosofia do JdbcTemplate no Spring MVC, ou do PDO usado diretamente em PHP, para quem conhece um desses ambientes).
8.7.2. TypeORM: o equivalente do Spring Data JPA
O TypeORM é o ORM mais usado com o NestJS: aqui, as tabelas são definidas como classes TypeScript decoradas (as “entidades”), e o banco de dados é consultado por meio de um Repository injetado, sem escrever nenhuma consulta SQL nos casos simples (é o ORM mais parecido, em conceito, com o Spring Data JPA / Hibernate, para quem conhece esse ambiente).

8.7.2.1. Configuração do módulo
No módulo raiz da aplicação (app.module.ts), a conexão com o banco de dados é declarada uma única vez, com TypeOrmModule.forRoot(...):
app.module.ts
Vamos comentar este código:
- linha 1: [// app.module.ts] — este comentário apenas indica a origem do trecho: este bloco, TypeOrmModule.forRoot({...}), é um elemento da lista
importsdo@Module({...})raiz da aplicação, e não um arquivo independente; - linha 2: [TypeOrmModule.forRoot({ ... })] — forRoot(...) configura, uma única vez para toda a aplicação, a conexão com o banco de dados — o equivalente do DataSource que vimos antes com o TypeORM, fora do NestJS (Capítulo 2); cada módulo que precisar de uma entidade específica a declarará, então, simplesmente com TypeOrmModule.forFeature(...), como mostrado abaixo;
- linha 9: [entities: [Bracket],] — a lista de classes de entidade (aqui, apenas uma: Bracket) que o TypeORM deve reconhecer para estabelecer a correspondência entre as classes TypeScript e as tabelas SQL;
- Linha 10: [synchronize: false,] — se definido como true, o TypeORM modificaria automaticamente o esquema do banco de dados para que corresponda às entidades — útil bem no início de um projeto, mas perigoso quando um banco de dados em produção já contém dados: vamos deixá-lo como false aqui, como é recomendado sempre que se trabalha com um banco de dados existente.
8.7.2.2. Entidades
Uma entidade é uma classe TypeScript comum, à qual decoradores acrescentam as informações necessárias para mapeá-la a uma tabela SQL e a suas colunas:
entities/bracket.entity.ts
Vamos comentar este código:
- linha 1: [import { Entity, PrimaryGeneratedColumn, Column } from 'typeorm';] — importamos os três decoradores usados mais adiante neste arquivo do pacote typeorm;
- linha 3: [@Entity('tbbrackets')] — este decorador declara que a classe seguinte representa uma tabela SQL: o argumento 'tbbrackets' especifica o nome real dessa tabela no banco de dados — sem ele, o TypeORM teria inferido um nome de tabela a partir do nome da classe, o que não é adequado aqui, já que a tabela existente se chama tbbrackets e não bracket;
- linha 5: [@PrimaryGeneratedColumn()] — marca a propriedade seguinte (id) como a chave primária da tabela, cujo valor é gerado automaticamente pelo banco de dados (auto-incremento) — portanto, você nunca precisa especificar um valor para id por conta própria ao criar um registro;
- linha 8: [@Column('decimal')] — designa a propriedade seguinte (limits) como uma coluna comum da tabela; o argumento 'decimal' especifica o tipo SQL da coluna — as outras duas colunas (coeffR, coeffN) são declaradas da mesma forma.
@Entity, @Column, @PrimaryGeneratedColumn: a terminologia usada é quase idêntica à do JPA (@Entity, @Column, @Id + @GeneratedValue) — o TypeORM foi deliberadamente projetado para ser familiar a quem conhece o Hibernate, mas nada aqui pressupõe esse conhecimento: esses decoradores, por si sós, bastam para mapear a classe à tabela.
8.7.2.3. O Repository
O Repository é o objeto que fornece acesso às linhas da tabela, sem exigir que você escreva suas próprias consultas SQL para as operações comuns:
brackets.service.ts
Vamos comentar este código:
- linha 1: [import { InjectRepository } from '@nestjs/typeorm';] — InjectRepository é o decorador específico de @nestjs/typeorm que permite solicitar a injeção de um Repository específico (veja abaixo);
- linha 4: [@Injectable()] — como acima, este decorador transforma BracketsService em um provider que o NestJS pode instanciar e injetar em outros lugares — neste caso, no controller abaixo;
- linha 7: [@InjectRepository(Bracket)] — colocado antes de um parâmetro do construtor, este decorador instrui o NestJS a injetar o Repository já configurado para a entidade Bracket — aquele que TypeOrmModule.forFeature([Bracket]) registra no módulo (veja abaixo); sem ele, o NestJS não saberia qual Repository fornecer;
- linha 11: [return this.bracketsRepository.find({ order: { id: 'ASC' } });] — find(...) lê todas as linhas da tabela, ordenadas por id em ordem crescente, e retorna uma Promise de um array de Bracket — nenhuma consulta SQL escrita à mão, ao contrário da abordagem do driver nativo vista acima.
Repository<Bracket> é um objeto fornecido pelo TypeORM, pronto para uso assim que é injetado: ele já oferece os métodos comuns (find, findOne, save, delete...) para a tabela associada à entidade Bracket , sem que você precise escrevê-los (exatamente o mesmo papel desempenhado por JpaRepository<Bracket, Integer> no lado do Spring Data, para quem conhece esse ambiente).
8.7.2.4. Um controller que usa o Repository
Resta declarar um módulo que liga a entidade, o serviço e o controller, e depois um controller que expõe o serviço via HTTP:
brackets.module.ts
- linha 1: [@Module({ ... })] — este decorador, que já vimos, marca a classe como um módulo do NestJS: uma unidade que agrupa elementos relacionados (neste caso, tudo o que diz respeito às faixas do imposto);
- linha 2: [imports: [TypeOrmModule.forFeature([Bracket])],] — forFeature([Bracket]) registra, para este módulo específico, o Repository da entidade “Bracket” (construído a partir da conexão já aberta por forRoot(...) no módulo raiz) — é esse Repository que @InjectRepository(Bracket) recuperará mais acima;
- linha 3: [providers: [BracketsService],] — a lista de classes @Injectable() que este módulo disponibiliza — aqui, o serviço que usa o Repository;
- linha 4: [controllers: [BracketsController],] — a lista de controllers (classes @Controller()) que este módulo expõe.
brackets.controller.ts
Vamos comentar este código:
- linha 1: [@Controller('brackets')] — este decorador marca a classe como um controller e define o prefixo de URL, comum a todas as suas rotas: 'brackets', ou seja, /brackets — cada método anotado dentro dele acrescentará seu próprio segmento de URL, se for o caso;
- linha 3: [constructor(private readonly service: BracketsService) {}] — injeção via construtor, como vimos anteriormente: o NestJS fornece automaticamente uma instância de BracketsService;
- linha 5: [@Get()] — associa o método seguinte às requisições GET; quando usado sem argumentos, como aqui, ele responde diretamente à URL base do controller — nenhum segmento adicional, portanto simplesmente /brackets (e não, por exemplo, /brackets/all);
- linha 7: [return this.service.findAll();] — o array de Bracket retornado pelo serviço é serializado automaticamente em JSON pelo NestJS e enviado como corpo da resposta HTTP.
8.7.3. Executando o projeto
Depois que o projeto for iniciado (npm run start:dev, após criar o banco de dados dbtaxes-2019 com o script SQL fornecido), esta ação pode ser testada na URL http://localhost:3000/brackets (método GET, sem parâmetros): ela retorna a lista das faixas do imposto no formato JSON.
Em um terminal, na raiz da pasta [typeorm], digite o comando:
O terminal exibe o seguinte texto:
8.7.4. Teste no Postman

8.7.5. Prisma: uma alternativa moderna
O Prisma é outro framework muito popular no ecossistema Node. Sua filosofia difere da do TypeORM: o esquema é definido em um arquivo, e um cliente totalmente tipado é gerado (prisma generate) a partir desse esquema — mais próximo, em espírito, de um gerador de código do que de uma abordagem “baseada em anotações”.

schema.prisma
Vamos analisar este código:
- linha 1: [// schema.prisma] — este arquivo não é TypeScript, mas um arquivo escrito na linguagem de descrição própria do Prisma, a Prisma Schema Language;
- linha 2: [model Bracket {] — a palavra-chave
modeldeclara um modelo Prisma chamadoBracket— é a partir desse modelo queprisma generateproduzirá mais tarde uma classeTypeScripte os métodos associados; - linha 3: [id Int @id @default(autoincrement())] — @id marca o campo id como a chave primária do modelo; @default(autoincrement()) indica que seu valor é gerado automaticamente pelo banco de dados por auto-incremento — o equivalente no Prisma ao @PrimaryGeneratedColumn() do TypeORM visto acima;
- linha 7: [@@map("tbbrackets")] — um atributo de “bloco” (prefixado com dois símbolos @, pois se aplica ao modelo inteiro e não a um único campo) que especifica o nome real da tabela SQL, tbbrackets — o equivalente do argumento passado a @Entity('tbbrackets') no TypeORM.
O arquivo [brackets.service.ts] é o seguinte:
Vamos comentar este código:
- linha 1: [const brackets = await this.prisma.bracket.findMany({ ... })] — this.prisma refere-se aqui a um PrismaService injetado (não abordado neste curso), que expõe o cliente gerado por
prisma generate;bracketé a propriedade gerada automaticamente a partir do modeloBracketno esquema acima, efindMany(...)lê todas as suas linhas — o equivalente no Prisma ao métodofind(...)deRepositoryvisto anteriormente; - Linha 2: [orderBy: { id: 'asc' },] — especifica a ordenação dos resultados — o equivalente no Prisma à opção
order: { id: 'ASC' }passada ao métodofind(...)do TypeORM.
8.7.6. Qual abordagem escolher?
- O driver nativo: simples, com controle total sobre o SQL executado — é a escolha padrão para o estudo de caso do Capítulo 6, para permanecer fiel ao servidor PHP original, que por sua vez usava o PDO diretamente;
- TypeORM: o mais próximo do Spring Data JPA / Hibernate, útil à medida que o número de entidades e de relacionamentos cresce;
- Prisma: a abordagem mais “moderna” (tipagem totalmente gerada), atualmente recomendada para novos projetos, mas menos imediatamente familiar se você vem do Spring Data JPA.