Skip to content

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:

1
2
3
4
5
6
7
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

1
2
3
4
5
6
7
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

1
2
3
4
5
6
7
8
9
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]:

1
2
3
4
5
6
[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:

Image

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/
1
2
3
4
5
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:

1
2
3
4
5
6
7
8
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]:

1
2
3
4
5
6
7
8
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:

Image

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
1
2
3
4
5
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
1
2
3
4
5
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
1
2
3
4
5
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
1
2
3
4
5
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
1
2
3
4
5
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
1
2
3
4
5
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
1
2
3
4
5
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}

Image

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
1
2
3
4
5
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
1
2
3
4
5
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
1
2
3
4
5
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
1
2
3
4
5
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
1
2
3
4
5
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
HTTP/1.1 204 No Content
curl -i http://localhost:3000/responses/promise
1
2
3
4
5
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
1
2
3
4
5
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:

Image

Image

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
1
2
3
4
5
6
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
1
2
3
4
5
6
7
8
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
1
2
3
4
5
6
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:

Image

curl -i http://localhost:3000/documentation
1
2
3
4
5
6
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
1
2
3
4
5
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
1
2
3
4
5
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
1
2
3
4
5
6
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
1
2
3
4
5
6
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

1
2
3
4
5
6
7
8
9
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

1
2
3
4
5
6
7
8
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
1
2
3
4
5
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
1
2
3
4
5
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
1
2
3
4
5
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
1
2
3
4
5
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.