2. Controllers, ações, roteamento
Este capítulo examina o caminho que uma requisição percorre, do navegador até a ação que a processa, e a resposta que essa ação devolve. As views só serão introduzidas no Capítulo 4: aqui, as ações devolvem texto ou JSON diretamente.
2.1. Exemplo 01: A estrutura de uma aplicação NestJS
O primeiro exemplo é a menor aplicação [NestJS] possível. Ela tem três arquivos:
| 01-structure/
├── src/
│ ├── app.controller.ts
│ ├── app.module.ts
│ └── main.ts
├── nest-cli.json
└── tsconfig.json
|
2.1.1. O ponto de entrada: main.ts
| import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
async function bootstrap() {
// constrói a aplicação a partir do seu módulo raiz
const app = await NestFactory.create(AppModule);
// inicia o servidor HTTP na porta 3000
await app.listen(3000);
console.log('Server started on http://localhost:3000');
}
bootstrap();
|
Vamos comentar este código:
- linha 1: [NestFactory] é a “fábrica” de aplicações [NestJS];
- linha 2: o módulo raiz da aplicação, que veremos mais adiante;
- linha 4: a função de inicialização é assíncrona ([async]): construir a aplicação e iniciar o servidor leva tempo, e aguardamos ([await]) a conclusão de cada etapa;
- linha 6: constrói a aplicação a partir de seu módulo raiz. O [NestJS] descobre então todos os controllers e serviços da aplicação e cria suas instâncias;
- linha 8: inicia o servidor HTTP na porta 3000;
- linha 12: chama a função de inicialização.
2.1.2. O módulo raiz: app.module.ts
| import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
@Module({
controllers: [AppController],
})
export class AppModule {}
|
- Linha 4: O decorador [@Module] transforma a classe [AppModule] em um módulo [NestJS]. Um módulo agrupa controllers e serviços que pertencem ao mesmo conjunto. Uma aplicação pequena tem apenas um módulo; uma grande tem vários (veja o Exemplo 06);
- linha 5: a lista de controllers do módulo;
- linha 7: a própria classe está vazia — tudo está no decorador.
2.1.3. O controller: app.controller.ts
| import { Controller, Get } from '@nestjs/common';
@Controller()
export class AppController {
@Get()
home(): string {
return 'Hello from NestJS!';
}
}
|
- Linha 3: O decorador [@Controller()] transforma a classe em um controller. Sem argumentos, suas rotas começam na raiz do site ([/]);
- Linha 5: O decorador [@Get()] associa o método [home] às requisições [GET /]. Um método decorado dessa maneira é uma ação;
- linha 7: o valor retornado pela ação é a resposta enviada ao navegador.
2.1.4. Execução
Em um console aberto na pasta [01-structure], digite [npx nest start]:
| [Nest] 12654 - 09/23/2026, 4:02:05 PM LOG [NestFactory] Starting Nest application...
[Nest] 12654 - 09/23/2026, 4:02:05 PM LOG [InstanceLoader] AppModule dependencies initialized +9ms
[Nest] 12654 - 09/23/2026, 4:02:05 PM LOG [RoutesResolver] AppController {/}: +4ms
[Nest] 12654 - 09/23/2026, 4:02:05 PM LOG [RouterExplorer] Mapped {/, GET} route +2ms
[Nest] 12654 - 09/23/2026, 4:02:05 PM LOG [NestApplication] Nest application successfully started +2ms
Server started on http://localhost:3000
|
O [NestJS] exibe as rotas que encontrou: neste caso, apenas uma, [{/, GET}], atendida por [AppController]. Vamos consultar a URL [http://localhost:3000/] usando um navegador:

depois com o [curl]. A opção [-i] também exibe os cabeçalhos HTTP da resposta (mostraremos aqui apenas alguns deles):
| curl -i http://localhost:3000/
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 18
Hello from NestJS!
|
Uma string retornada por uma ação é enviada com o cabeçalho [Content-Type: text/html]: o navegador a interpreta como HTML.
2.2. Exemplo 02: Roteamento
O roteamento associa uma URL e um método HTTP (GET, POST...) a uma ação. O Exemplo 02 tem dois controllers:
| 02-routing/
├── src/
│ ├── app.controller.ts
│ ├── app.module.ts
│ ├── first.controller.ts
│ └── main.ts
├── nest-cli.json
└── tsconfig.json
|
O arquivo [src/app.module.ts]:
| import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { FirstController } from './first.controller';
@Module({
controllers: [AppController, FirstController],
})
export class AppModule {}
|
Linha 6: O módulo declara seus dois controllers.
O arquivo [src/app.controller.ts]:
| import { Controller, Get } from '@nestjs/common';
@Controller()
export class AppController {
// GET /
@Get()
home(): string {
return `<h2>Example 02 - routing</h2>
<ul>
<li><a href="/first">/first</a></li>
<li><a href="/first/action01">/first/action01</a></li>
<li><a href="/first/products/17">/first/products/17</a></li>
<li><a href="/first/products/17/reviews/3">/first/products/17/reviews/3</a></li>
<li><a href="/first/files/images/logo.png">/first/files/images/logo.png</a></li>
<li><a href="/unknown">/unknown</a></li>
</ul>`;
}
}
|
A ação [home] (linhas 6–17) devolve uma página HTML que contém links para as ações do outro controller:

O arquivo [src/first.controller.ts]:
| import { Controller, Get, Param, Post } from '@nestjs/common';
@Controller('first')
export class FirstController {
// GET /first
@Get()
index(): string {
return 'Action [index] of the [first] controller';
}
// GET /first/action01
@Get('action01')
action01(): string {
return 'Action [action01] of the [first] controller, GET request';
}
// POST /first/action01: mesmo caminho, outro método HTTP
@Post('action01')
action01Post(): string {
return 'Action [action01Post] of the [first] controller, POST request';
}
// GET /first/products/17: [:id] é um parâmetro de rota
@Get('products/:id')
product(@Param('id') id: string): string {
return `Product no. ${id}`;
}
// GET /first/products/17/reviews/3: dois parâmetros de rota
@Get('products/:id/reviews/:number')
review(@Param() params: { id: string; number: string }): string {
return `Review no. ${params.number} of product no. ${params.id}`;
}
// GET /first/files/...: [*] aceita qualquer final de caminho
@Get('files/*')
file(@Param('0') path: string): string {
return `Requested file: ${path}`;
}
}
|
Vamos detalhar este código:
- linha 3: [@Controller('first')] define o prefixo comum a todas as rotas do controller: suas ações tratam as rotas de URL que começam com [/first];
- linhas 6–7: [@Get()] sem argumentos: a ação [index] trata [GET /first];
- linhas 12–13: a ação [action01] processa [GET /first/action01]. A URL é a concatenação do prefixo do controller com o caminho da ação;
- linhas 18–19: o mesmo caminho, mas para o método POST: [@Post] substitui [@Get]. Também existem [@Put], [@Delete], [@Patch], [@All]... O nome do método [TypeScript] ([action01Post]) é arbitrário: apenas os decoradores importam para o roteamento;
- Linhas 24–25: [:id] é um parâmetro de rota: esse segmento da URL pode assumir qualquer valor. O decorador [@Param('id')] injeta seu valor no parâmetro [id] da ação. Esse valor é sempre uma string: para [/first/products/17], [id] é ['17'], e não o número 17;
- linhas 30–31: dois parâmetros de rota. [@Param()] sem argumento injeta um objeto que contém todos eles: [{ id: '17', number: '3' }];
- linhas 36–37: o caractere [*] aceita qualquer final de URL, inclusive [/]. A parte correspondente é o parâmetro chamado [0].
Na inicialização, o [NestJS] exibe todas as rotas:
| [Nest] 12690 - 09/23/2026, 4:02:10 PM LOG [NestFactory] Starting Nest application...
[Nest] 12690 - 09/23/2026, 4:02:10 PM LOG [InstanceLoader] AppModule dependencies initialized +17ms
[Nest] 12690 - 09/23/2026, 4:02:10 PM LOG [RoutesResolver] AppController {/}: +8ms
[Nest] 12690 - 09/23/2026, 4:02:10 PM LOG [RouterExplorer] Mapped {/, GET} route +7ms
[Nest] 12690 - 09/23/2026, 4:02:10 PM LOG [RoutesResolver] FirstController {/first}: +0ms
[Nest] 12690 - 09/23/2026, 4:02:10 PM LOG [RouterExplorer] Mapped {/first, GET} route +1ms
[Nest] 12690 - 09/23/2026, 4:02:10 PM LOG [RouterExplorer] Mapped {/first/action01, GET} route +0ms
[Nest] 12690 - 09/23/2026, 4:02:10 PM LOG [RouterExplorer] Mapped {/first/action01, POST} route +1ms
[Nest] 12690 - 09/23/2026, 4:02:10 PM LOG [RouterExplorer] Mapped {/first/products/:id, GET} route +0ms
[Nest] 12690 - 09/23/2026, 4:02:10 PM LOG [RouterExplorer] Mapped {/first/products/:id/reviews/:number, GET} route +1ms
[Nest] 12690 - 09/23/2026, 4:02:10 PM LOG [RouterExplorer] Mapped {/first/files/*, GET} route +1ms
[Nest] 12690 - 09/23/2026, 4:02:10 PM LOG [NestApplication] Nest application successfully started +2ms
Server started on http://localhost:3000
|
Aqui estão as respostas a algumas requisições:
| curl -i http://localhost:3000/first
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 40
Action [index] of the [first] controller
|
| curl -i http://localhost:3000/first/action01
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 56
Action [action01] of the [first] controller, GET request
|
| curl -i http://localhost:3000/first/products/17
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 14
Product no. 17
|
| curl -i http://localhost:3000/first/products/17/reviews/3
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 30
Review no. 3 of product no. 17
|
| curl -i http://localhost:3000/first/files/images/logo.png
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 31
Requested file: images/logo.png
|
Para enviar uma requisição POST, use a opção [-X POST] do [curl]:
| curl -i -X POST http://localhost:3000/first/action01
|
| HTTP/1.1 201 Created
Content-Type: text/html; charset=utf-8
Content-Length: 61
Action [action01Post] of the [first] controller, POST request
|
Observe o código de status 201 Created: é o código que o [NestJS] usa por padrão para responder a um POST. Veremos como alterá-lo. Por fim, uma URL que nenhuma rota trata produz um erro 404, que o [NestJS] converte por padrão em JSON:
| curl -i http://localhost:3000/unknown
|
| HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Content-Length: 70
{"message":"Cannot GET /unknown","error":"Not Found","statusCode":404}
|

O Capítulo 7 mostrará como substituir esse JSON por uma página HTML.
2.3. Exemplo 03: Respostas de uma ação
O que uma ação retorna determina a resposta HTTP. O Exemplo 03 revisa os principais casos:
O arquivo [src/responses.controller.ts]:
| import { Controller, Get, Header, HttpCode, NotFoundException } from '@nestjs/common';
@Controller('responses')
export class ResponsesController {
// uma string: enviada como está, com o tipo [text/html]
@Get('html')
html(): string {
return '<h1>Action [html]</h1>';
}
// a mesma string, mas declarada como texto simples
@Get('text')
@Header('Content-Type', 'text/plain; charset=utf-8')
text(): string {
return '<h1>Action [text]</h1>';
}
// um objeto: serializado em JSON, com o tipo [application/json]
@Get('json')
json(): object {
return { lastName: 'Martin', firstName: 'Jean', age: 42 };
}
// um array: também serializado em JSON
@Get('array')
array(): string[] {
return ['Mme', 'Mlle', 'Mr'];
}
// um código de status escolhido: 201 (Created) em vez de 200 (OK)
@Get('created')
@HttpCode(201)
created(): object {
return { message: 'resource created' };
}
// sem resposta: o código 204 (No Content) significa "nada a exibir"
@Get('empty')
@HttpCode(204)
empty(): void {}
// um método assíncrono: o NestJS espera a promise ser resolvida
@Get('promise')
async promise(): Promise<object> {
const start = Date.now();
await new Promise((done) => setTimeout(done, 500));
return { wait: `${Date.now() - start} ms` };
}
// uma exceção: o NestJS a transforma em uma resposta de erro
@Get('error')
error(): string {
throw new NotFoundException('This resource does not exist');
}
}
|
Vamos detalhar este código:
- linhas 6–9: uma string é enviada como está, com o cabeçalho [Content-Type: text/html; charset=utf-8];
- linhas 12–16: o decorador [@Header] define um cabeçalho da resposta. Declarada como texto simples ([text/plain]), a mesma string deixa de ser interpretada pelo navegador;
- linhas 19–22: um objeto é serializado como JSON, com o cabeçalho [Content-Type: application/json];
- linhas 25–28: um array também é serializado como JSON;
- linhas 31–35: [@HttpCode(201)] altera o código de status da resposta (o padrão é 200 para um GET);
- linhas 38–40: o código 204 (No Content) significa “sem conteúdo”: a ação não retorna nada;
- linhas 43–48: uma ação pode ser assíncrona ([async]): nesse caso, ela retorna uma promessa ([Promise]), e o [NestJS] espera que ela seja resolvida antes de responder. É o caso de todas as ações que consultam um banco de dados;
- Linhas 51–54: Uma ação pode lançar uma exceção. As exceções do [NestJS] ([NotFoundException], [BadRequestException], [ForbiddenException]...) carregam, cada uma, um código de status HTTP (aqui 404), que o [NestJS] usa em sua resposta.
As respostas recebidas:
| curl -i http://localhost:3000/responses/html
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 22
<h1>Action [html]</h1>
|
| curl -i http://localhost:3000/responses/text
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 22
<h1>Action [text]</h1>
|
| curl -i http://localhost:3000/responses/json
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 49
{"lastName":"Martin","firstName":"Jean","age":42}
|
| curl -i http://localhost:3000/responses/array
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 19
["Mme","Mlle","Mr"]
|
| curl -i http://localhost:3000/responses/created
|
| HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Content-Length: 30
{"message":"resource created"}
|
| curl -i http://localhost:3000/responses/empty
|
| curl -i http://localhost:3000/responses/promise
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 17
{"wait":"501 ms"}
|
| curl -i http://localhost:3000/responses/error
|
| HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Content-Length: 79
{"message":"This resource does not exist","error":"Not Found","statusCode":404}
|
Em um navegador, a diferença entre [text/html] e [text/plain] é visível:


2.4. Exemplo 04: Redirecionamentos
Uma ação pode responder com um redirecionamento: um código de status 301 ou 302 e um cabeçalho [Location] que informa ao navegador qual URL deve ser requisitada em seguida. O navegador a requisita imediatamente, sem intervenção do usuário. Os redirecionamentos estão por toda parte em uma aplicação web: após o envio bem-sucedido de um formulário, após o login, após a troca de idioma...
O arquivo [src/redirects.controller.ts]:
| import { Controller, Get, Param, Redirect } from '@nestjs/common';
@Controller()
export class RedirectsController {
// redirecionamento fixo: o endereço e o código são conhecidos de antemão
@Get('old')
@Redirect('/new', 301)
oldPage(): void {}
@Get('new')
newPage(): string {
return 'You are on the [new] page';
}
// redirecionamento calculado: o objeto retornado substitui o endereço de @Redirect()
@Get('go/:destination')
@Redirect()
go(@Param('destination') destination: string): { url: string } {
return { url: `/page/${destination}` };
}
@Get('page/:name')
page(@Param('name') name: string): string {
return `You are on the [${name}] page`;
}
// redirecionamento para outro site
@Get('documentation')
@Redirect('https://docs.nestjs.com')
documentation(): void {}
}
|
Vamos detalhar este código:
- linhas 6–8: [@Redirect('/new', 301)]: um redirecionamento permanente. O código 301 (Moved Permanently) indica que a página mudou de endereço em caráter permanente; o código padrão é 302 (Found), um redirecionamento temporário;
- linhas 16–20: um redirecionamento calculado: [@Redirect()] sem argumento, e a ação retorna um objeto [{ url: ... }] que define o endereço de destino;
- linhas 28–30: é possível redirecionar para outro site.
O [curl] mostra o redirecionamento sem segui-lo:
| curl -i http://localhost:3000/old
|
| HTTP/1.1 301 Moved Permanently
Location: /new
Content-Type: text/plain; charset=utf-8
Content-Length: 38
Moved Permanently. Redirecting to /new
|
Com a opção [-L], o [curl] segue o redirecionamento, exatamente como faria um navegador. Vemos então as duas respostas sucessivas:
| curl -i -L http://localhost:3000/old
|
| HTTP/1.1 301 Moved Permanently
Location: /new
Content-Type: text/plain; charset=utf-8
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
You are on the [new] page
|
| curl -i http://localhost:3000/go/contact
|
| HTTP/1.1 302 Found
Location: /page/contact
Content-Type: text/plain; charset=utf-8
Content-Length: 35
Found. Redirecting to /page/contact
|
No navegador, apenas a página final é visível; a barra de endereços exibe a nova URL:

| curl -i http://localhost:3000/documentation
|
| HTTP/1.1 302 Found
Location: https://docs.nestjs.com
Content-Type: text/plain; charset=utf-8
Content-Length: 45
Found. Redirecting to https://docs.nestjs.com
|
2.5. Exemplo 05: Os objetos Request e Response do Express
O [NestJS] se apoia no servidor web [Express]. Uma ação pode acessar diretamente os objetos [Request] e [Response] do [Express]. Isso às vezes é necessário, e o faremos no estudo de caso (para definir um cookie, por exemplo), mas é preciso ter consciência do que se perde.
O arquivo [src/express.controller.ts]:
| import { Controller, Get, Req, Res } from '@nestjs/common';
import { Request, Response } from 'express';
@Controller('express')
export class ExpressController {
// a requisição Express: método, URL, cabeçalhos...
@Get('request')
request(@Req() req: Request): object {
return {
method: req.method,
url: req.url,
path: req.path,
browser: req.get('user-agent'),
};
}
// a resposta Express: a action envia ela mesma a resposta
@Get('response')
response(@Res() res: Response): void {
res.status(200).type('text/plain').send('Response sent by [res.send]');
}
// redirecionamento com a resposta Express
@Get('redirect')
redirect(@Res() res: Response): void {
res.redirect('/express/response');
}
// passthrough: usamos a resposta (aqui para um cabeçalho), mas o NestJS
// ainda envia o valor retornado pela própria action
@Get('passthrough')
passthrough(@Res({ passthrough: true }) res: Response): string {
res.setHeader('X-Example', '05-express');
return 'Response sent by NestJS, with an added header';
}
// ERRO a não cometer: @Res() sem passthrough, e nada é enviado
@Get('blocked')
blocked(@Res() res: Response): string {
return 'This string will never be sent: the browser keeps waiting...';
}
}
|
Vamos detalhar este código:
- linha 2: os tipos [Request] e [Response] do [Express];
- Linhas 7–15: [@Req()] injeta a requisição do [Express]: método HTTP, URL, caminho, cabeçalhos ([req.get(...)])... ;
- linhas 18–21: [@Res()] injeta a resposta do [Express]. Atenção: Assim que uma ação usa [@Res()], o [NestJS] presume que é ela quem envia a resposta e ignora o que ela retorna. Aqui, a ação define o código de status e o tipo, e envia o corpo com [res.send];
- linhas 24–27: um redirecionamento 302 feito pelo [Express] com [res.redirect(url)];
- linhas 31–35: Com a opção [passthrough: true], a ação usa a resposta (aqui, para adicionar um cabeçalho), mas deixa que o [NestJS] envie o que ela retorna. É o melhor dos dois mundos;
- linhas 38–41: o erro a evitar: [@Res()] sem [passthrough] e sem chamadas a [res.send], [res.redirect], [res.render].... A string retornada é ignorada, nenhuma resposta é enviada e o navegador espera indefinidamente.
Respostas recebidas:
| curl -i -A "Mozilla/5.0 (example)" http://localhost:3000/express/request
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 101
{"method":"GET","url":"/express/request","path":"/express/request","browser":"Mozilla/5.0 (example)"}
|
(a opção [-A] do [curl] define o cabeçalho [User-Agent], que identifica o navegador)
| curl -i http://localhost:3000/express/response
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 27
Response sent by [res.send]
|
| curl -i http://localhost:3000/express/redirect
|
| HTTP/1.1 302 Found
Location: /express/response
Content-Type: text/plain; charset=utf-8
Content-Length: 39
Found. Redirecting to /express/response
|
| curl -i http://localhost:3000/express/passthrough
|
| HTTP/1.1 200 OK
X-Example: 05-express
Content-Type: text/html; charset=utf-8
Content-Length: 45
Response sent by NestJS, with an added header
|
Para a última ação, limitamos a espera a 3 segundos com a opção [-m 3]:
| curl -i -m 3 http://localhost:3000/express/blocked
|
| curl: (28) Operation timed out after 3002 milliseconds with 0 bytes received
|
No restante deste documento, usaremos [@Res()] quando uma ação precisar escolher entre várias respostas de tipos diferentes (uma página ou um redirecionamento), e garantiremos que cada caminho do código envie uma resposta.
2.6. Exemplo 06: Módulos, serviços e injeção de dependência
Os controllers não devem conter lógica de aplicação; eles a delegam a serviços. O Exemplo 06 divide uma pequena aplicação em dois módulos:
| 06-modules/
├── src/
│ ├── clients/
│ │ ├── clients.controller.ts
│ │ └── clients.module.ts
│ ├── products/
│ │ ├── products.controller.ts
│ │ ├── products.module.ts
│ │ └── products.service.ts
│ ├── app.module.ts
│ └── main.ts
├── nest-cli.json
└── tsconfig.json
|
2.6.1. O serviço ProductsService
| import { Injectable } from '@nestjs/common';
export interface Product {
id: number;
name: string;
price: number;
}
@Injectable()
export class ProductsService {
private readonly products: Product[] = [
{ id: 1, name: 'pen', price: 1.5 },
{ id: 2, name: 'notebook', price: 3.2 },
{ id: 3, name: 'eraser', price: 0.8 },
];
findAll(): Product[] {
return this.products;
}
findById(id: number): Product | undefined {
return this.products.find((p) => p.id === id);
}
}
|
- Linhas 3–7: A interface [Product] descreve um produto;
- linha 9: o decorador [@Injectable()] transforma a classe em um serviço (também chamado de provider): o [NestJS] cria uma única instância dele, que fornece (injeta) a todos que precisam dela;
- linhas 11–15: os dados, aqui em memória;
- linhas 17–23: os dois métodos do serviço.
2.6.2. O controller ProductsController
| import { Controller, Get, NotFoundException, Param } from '@nestjs/common';
import { Product, ProductsService } from './products.service';
@Controller('products')
export class ProductsController {
// injeção de dependência: o NestJS fornece a instância de ProductsService
constructor(private readonly productsService: ProductsService) {}
@Get()
list(): Product[] {
return this.productsService.findAll();
}
@Get(':id')
oneProduct(@Param('id') id: string): Product {
const product = this.productsService.findById(Number(id));
if (!product) {
throw new NotFoundException(`Product no. ${id} not found`);
}
return product;
}
}
|
- linha 7: injeção de dependência. O controller declara em seu construtor que precisa de um [ProductsService]; o [NestJS] fornece a ele a instância única do serviço. O controller nunca chama [new ProductsService()]. A sintaxe [private readonly productsService: ProductsService] do [TypeScript] declara ao mesmo tempo o parâmetro e o campo [this.productsService];
- Linhas 9–12: A ação delega ao serviço;
- linhas 14–21: [Number(id)] converte o parâmetro de rota (uma string) em número. Um produto inexistente dispara uma exceção 404.
2.6.3. O módulo ProductsModule
| import { Module } from '@nestjs/common';
import { ProductsController } from './products.controller';
import { ProductsService } from './products.service';
@Module({
controllers: [ProductsController],
providers: [ProductsService],
exports: [ProductsService],
})
export class ProductsModule {}
|
- linha 6: o controller do módulo;
- linha 7: os serviços do módulo. Apenas os serviços declarados aqui (ou importados, veja abaixo) podem ser injetados nas classes do módulo;
- linha 8: o serviço é exportado: os módulos que importam [ProductsModule] também poderão recebê-lo por injeção.
2.6.4. O módulo ClientsModule
| import { Module } from '@nestjs/common';
import { ClientsController } from './clients.controller';
import { ProductsModule } from '../products/products.module';
@Module({
imports: [ProductsModule],
controllers: [ClientsController],
})
export class ClientsModule {}
|
Linha 6: [ClientsModule] importa [ProductsModule] e, portanto, tem acesso aos serviços que este exporta.
O arquivo [src/clients/clients.controller.ts]:
| import { Controller, Get } from '@nestjs/common';
import { ProductsService } from '../products/products.service';
@Controller('clients')
export class ClientsController {
// um serviço de OUTRO módulo, exportado por esse módulo
constructor(private readonly productsService: ProductsService) {}
@Get('cart')
cart(): object {
const products = this.productsService.findAll();
const total = products.reduce((sum, p) => sum + p.price, 0);
return { client: 'Jean Martin', items: products.length, total };
}
}
|
- Linha 7: [ClientsController] recebe por injeção um serviço de outro módulo;
- linhas 9–14: ele usa esse serviço para calcular o total de um carrinho de compras.
2.6.5. O módulo raiz
| import { Module } from '@nestjs/common';
import { ProductsModule } from './products/products.module';
import { ClientsModule } from './clients/clients.module';
@Module({
imports: [ProductsModule, ClientsModule],
})
export class AppModule {}
|
linha 6: o módulo raiz não tem mais controller; ele apenas importa os dois módulos da aplicação.
2.6.6. Execução
| [Nest] 12976 - 09/23/2026, 4:02:35 PM LOG [NestFactory] Starting Nest application...
[Nest] 12976 - 09/23/2026, 4:02:35 PM LOG [InstanceLoader] AppModule dependencies initialized +9ms
[Nest] 12976 - 09/23/2026, 4:02:35 PM LOG [InstanceLoader] ProductsModule dependencies initialized +1ms
[Nest] 12976 - 09/23/2026, 4:02:35 PM LOG [InstanceLoader] ClientsModule dependencies initialized +0ms
[Nest] 12976 - 09/23/2026, 4:02:35 PM LOG [RoutesResolver] ProductsController {/products}: +3ms
[Nest] 12976 - 09/23/2026, 4:02:35 PM LOG [RouterExplorer] Mapped {/products, GET} route +2ms
[Nest] 12976 - 09/23/2026, 4:02:35 PM LOG [RouterExplorer] Mapped {/products/:id, GET} route +1ms
[Nest] 12976 - 09/23/2026, 4:02:35 PM LOG [RoutesResolver] ClientsController {/clients}: +0ms
[Nest] 12976 - 09/23/2026, 4:02:35 PM LOG [RouterExplorer] Mapped {/clients/cart, GET} route +0ms
[Nest] 12976 - 09/23/2026, 4:02:35 PM LOG [NestApplication] Nest application successfully started +2ms
Server started on http://localhost:3000
|
| curl -i http://localhost:3000/products
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 111
[{"id":1,"name":"pen","price":1.5},{"id":2,"name":"notebook","price":3.2},{"id":3,"name":"eraser","price":0.8}]
|
| curl -i http://localhost:3000/products/2
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 38
{"id":2,"name":"notebook","price":3.2}
|
| curl -i http://localhost:3000/products/9
|
| HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Content-Length: 74
{"message":"Product no. 9 not found","error":"Not Found","statusCode":404}
|
| curl -i http://localhost:3000/clients/cart
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 46
{"client":"Jean Martin","items":3,"total":5.5}
|
O estudo de caso é estruturado exatamente assim: controllers enxutos que delegam a serviços injetados, e módulos que agrupam componentes relacionados.