Skip to content

2. Controladores, acciones, enrutamiento

Este capítulo examina el camino que sigue una solicitud, desde el navegador hasta la acción que la procesa, y la respuesta que esa acción devuelve. Las vistas no se introducirán hasta el capítulo 4: aquí, las acciones devuelven texto o JSON directamente.

2.1. Ejemplo 01: la estructura de una aplicación NestJS

El primer ejemplo es la aplicación [NestJS] más pequeña posible. Tiene tres archivos:

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. El punto de entrada: main.ts

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  // compila la aplicación a partir de su módulo raíz
  const app = await NestFactory.create(AppModule);
  // inicia el servidor HTTP en el puerto 3000
  await app.listen(3000);
  console.log('Server started on http://localhost:3000');
}

bootstrap();

Comentemos este código:

  • línea 1: [NestFactory] es la “fábrica” de aplicaciones [NestJS];
  • línea 2: el módulo raíz de la aplicación, que veremos más adelante;
  • línea 4: la función de arranque es asíncrona ([async]): construir la aplicación e iniciar el servidor toma tiempo, y esperamos ([await]) a que cada paso termine;
  • línea 6: construye la aplicación a partir de su módulo raíz. [NestJS] descubre entonces todos los controladores y servicios de la aplicación y crea sus instancias;
  • línea 8: inicia el servidor HTTP en el puerto 3000;
  • línea 12: llama a la función de arranque.

2.1.2. El módulo raíz: 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 {}
  • Línea 4: el decorador [@Module] convierte la clase [AppModule] en un módulo de [NestJS]. Un módulo agrupa los controladores y servicios que van juntos. Una aplicación pequeña tiene un solo módulo; una grande tiene varios (véase el ejemplo 06);
  • línea 5: la lista de controladores del módulo;
  • línea 7: la clase en sí está vacía: todo está en el decorador.

2.1.3. El controlador: 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!';
  }
}
  • Línea 3: el decorador [@Controller()] convierte la clase en un controlador. Sin argumentos, sus rutas comienzan en la raíz del sitio ([/]);
  • Línea 5: el decorador [@Get()] asocia el método [home] con las solicitudes [GET /]. Un método decorado de esta manera es una acción;
  • línea 7: el valor devuelto por la acción es la respuesta que se envía al navegador.

2.1.4. Ejecución

En una consola abierta en la carpeta [01-structure], escriba [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

[NestJS] muestra las rutas que encontró: en este caso, solo una, [{/, GET}], atendida por [AppController]. Consultemos la URL [http://localhost:3000/] con un navegador:

Image

y luego con [curl]. La opción [-i] también muestra los encabezados HTTP de la respuesta (aquí solo mostraremos algunos):

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!

Una cadena devuelta por una acción se envía con el encabezado [Content-Type: text/html]: el navegador la interpreta como HTML.

2.2. Ejemplo 02: enrutamiento

El enrutamiento asocia una URL y un método HTTP (GET, POST...) con una acción. El ejemplo 02 tiene dos controladores:

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

El archivo [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 {}

Línea 6: el módulo declara sus dos controladores.

El archivo [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>`;
  }
}

La acción [home] (líneas 6–17) devuelve una página HTML que contiene enlaces a las acciones del otro controlador:

Image

El archivo [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: misma ruta, otro método HTTP
  @Post('action01')
  action01Post(): string {
    return 'Action [action01Post] of the [first] controller, POST request';
  }

  // GET /first/products/17: [:id] es un parámetro de ruta
  @Get('products/:id')
  product(@Param('id') id: string): string {
    return `Product no. ${id}`;
  }

  // GET /first/products/17/reviews/3: dos parámetros de ruta
  @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/...: [*] acepta cualquier final de ruta
  @Get('files/*')
  file(@Param('0') path: string): string {
    return `Requested file: ${path}`;
  }
}

Analicemos este código:

  • línea 3: [@Controller('first')] define el prefijo común a todas las rutas del controlador: sus acciones manejan las rutas URL que comienzan con [/first];
  • líneas 6–7: [@Get()] sin argumentos: la acción [index] maneja [GET /first];
  • líneas 12–13: la acción [action01] procesa [GET /first/action01]. La URL es la concatenación del prefijo del controlador y la ruta de la acción;
  • líneas 18–19: la misma ruta, pero para el método POST: [@Post] reemplaza a [@Get]. También existen [@Put], [@Delete], [@Patch], [@All]... El nombre del método [TypeScript] ([action01Post]) es arbitrario: para el enrutamiento solo importan los decoradores;
  • líneas 24–25: [:id] es un parámetro de ruta: este segmento de la URL puede tomar cualquier valor. El decorador [@Param('id')] inyecta su valor en el parámetro [id] de la acción. Este valor es siempre una cadena: para [/first/products/17], [id] es ['17'], no el número 17;
  • líneas 30–31: dos parámetros de ruta. [@Param()] sin argumento inyecta un objeto que los contiene todos: [{ id: '17', number: '3' }];
  • líneas 36–37: el carácter [*] acepta cualquier final de URL, incluido [/]. La parte correspondiente es el parámetro llamado [0].

Al iniciar, [NestJS] muestra todas las rutas:

[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

Estas son las respuestas a algunas consultas:

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 una solicitud POST, use la opción [-X POST] de [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 el código de estado 201 Created: es el código que [NestJS] usa por defecto para responder a un POST. Veremos cómo cambiarlo. Por último, una URL que no es atendida por ninguna ruta produce un error 404, que [NestJS] traduce por defecto a 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

El capítulo 7 mostrará cómo reemplazar este JSON por una página HTML.

2.3. Ejemplo 03: respuestas de una acción

Lo que devuelve una acción determina la respuesta HTTP. El ejemplo 03 repasa los casos principales:

El archivo [src/responses.controller.ts]:

import { Controller, Get, Header, HttpCode, NotFoundException } from '@nestjs/common';

@Controller('responses')
export class ResponsesController {
  // una cadena: se envía tal cual, con el tipo [text/html]
  @Get('html')
  html(): string {
    return '<h1>Action [html]</h1>';
  }

  // la misma cadena, pero anunciada como texto plano
  @Get('text')
  @Header('Content-Type', 'text/plain; charset=utf-8')
  text(): string {
    return '<h1>Action [text]</h1>';
  }

  // un objeto: se serializa a JSON, con el tipo [application/json]
  @Get('json')
  json(): object {
    return { lastName: 'Martin', firstName: 'Jean', age: 42 };
  }

  // un arreglo: también se serializa a JSON
  @Get('array')
  array(): string[] {
    return ['Mme', 'Mlle', 'Mr'];
  }

  // un código de estado elegido: 201 (Created) en lugar de 200 (OK)
  @Get('created')
  @HttpCode(201)
  created(): object {
    return { message: 'resource created' };
  }

  // sin respuesta: el código 204 (No Content) significa "nada que mostrar"
  @Get('empty')
  @HttpCode(204)
  empty(): void {}

  // un método asíncrono: NestJS espera a que la promesa se resuelva
  @Get('promise')
  async promise(): Promise<object> {
    const start = Date.now();
    await new Promise((done) => setTimeout(done, 500));
    return { wait: `${Date.now() - start} ms` };
  }

  // una excepción: NestJS la convierte en una respuesta de error
  @Get('error')
  error(): string {
    throw new NotFoundException('This resource does not exist');
  }
}

Analicemos este código:

  • líneas 6–9: una cadena se envía tal cual, con el encabezado [Content-Type: text/html; charset=utf-8];
  • líneas 12–16: el decorador [@Header] define un encabezado de la respuesta. Declarada como texto plano ([text/plain]), la misma cadena ya no es interpretada por el navegador;
  • líneas 19–22: un objeto se serializa como JSON, con el encabezado [Content-Type: application/json];
  • líneas 25–28: un arreglo también se serializa como JSON;
  • líneas 31–35: [@HttpCode(201)] cambia el código de estado de la respuesta (200 por defecto para un GET);
  • líneas 38–40: el código 204 (No Content) significa “sin contenido”: la acción no devuelve nada;
  • líneas 43–48: una acción puede ser asíncrona ([async]): en ese caso, devuelve una promesa ([Promise]), y [NestJS] espera a que se resuelva antes de responder. Es el caso de todas las acciones que consultan una base de datos;
  • líneas 51–54: una acción puede lanzar una excepción. Las excepciones de [NestJS] ([NotFoundException], [BadRequestException], [ForbiddenException]...) llevan cada una un código de estado HTTP (aquí 404), que [NestJS] usa para su respuesta.

Las respuestas recibidas:

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}

En un navegador, la diferencia entre [text/html] y [text/plain] es visible:

Image

Image

2.4. Ejemplo 04: redirecciones

Una acción puede responder con una redirección: un código de estado 301 o 302 y un encabezado [Location] que indica al navegador qué URL solicitar a continuación. El navegador la solicita de inmediato, sin intervención del usuario. Las redirecciones son omnipresentes en una aplicación web: tras el envío exitoso de un formulario, tras iniciar sesión, tras cambiar el idioma...

El archivo [src/redirects.controller.ts]:

import { Controller, Get, Param, Redirect } from '@nestjs/common';

@Controller()
export class RedirectsController {
  // redirección fija: la dirección y el código se conocen de antemano
  @Get('old')
  @Redirect('/new', 301)
  oldPage(): void {}

  @Get('new')
  newPage(): string {
    return 'You are on the [new] page';
  }

  // redirección calculada: el objeto devuelto reemplaza la dirección 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`;
  }

  // redirección a otro sitio
  @Get('documentation')
  @Redirect('https://docs.nestjs.com')
  documentation(): void {}
}

Analicemos este código:

  • líneas 6–8: [@Redirect('/new', 301)]: una redirección permanente. El código 301 (Moved Permanently) indica que la página cambió su dirección de forma permanente; el código por defecto es 302 (Found), una redirección temporal;
  • líneas 16–20: una redirección calculada: [@Redirect()] sin argumento, y la acción devuelve un objeto [{ url: ... }] que establece la dirección de destino;
  • líneas 28–30: es posible redirigir a otro sitio.

[curl] muestra la redirección sin seguirla:

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

Con la opción [-L], [curl] sigue la redirección, tal como lo haría un navegador. Vemos entonces las dos respuestas sucesivas:

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

En el navegador, solo se ve la página final; la barra de direcciones muestra la nueva 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. Ejemplo 05: los objetos Request y Response de Express

[NestJS] se apoya en el servidor web [Express]. Una acción puede acceder directamente a los objetos [Request] y [Response] de [Express]. A veces es necesario, y lo haremos en el caso de estudio (para establecer una cookie, por ejemplo), pero hay que ser consciente de lo que se pierde.

El archivo [src/express.controller.ts]:

import { Controller, Get, Req, Res } from '@nestjs/common';
import { Request, Response } from 'express';

@Controller('express')
export class ExpressController {
  // la solicitud de Express: método, URL, encabezados...
  @Get('request')
  request(@Req() req: Request): object {
    return {
      method: req.method,
      url: req.url,
      path: req.path,
      browser: req.get('user-agent'),
    };
  }

  // la respuesta de Express: la acción envía la respuesta por sí misma
  @Get('response')
  response(@Res() res: Response): void {
    res.status(200).type('text/plain').send('Response sent by [res.send]');
  }

  // redirección con la respuesta de Express
  @Get('redirect')
  redirect(@Res() res: Response): void {
    res.redirect('/express/response');
  }

  // passthrough: usamos la respuesta (aquí para un encabezado), pero NestJS
  // sigue enviando el valor devuelto por la propia acción
  @Get('passthrough')
  passthrough(@Res({ passthrough: true }) res: Response): string {
    res.setHeader('X-Example', '05-express');
    return 'Response sent by NestJS, with an added header';
  }

  // ERROR que no se debe cometer: @Res() sin passthrough, y no se envía nada
  @Get('blocked')
  blocked(@Res() res: Response): string {
    return 'This string will never be sent: the browser keeps waiting...';
  }
}

Analicemos este código:

  • línea 2: los tipos [Request] y [Response] de [Express];
  • líneas 7–15: [@Req()] inyecta la solicitud [Express]: método HTTP, URL, ruta, encabezados ([req.get(...)])... ;
  • líneas 18–21: [@Res()] inyecta la respuesta [Express]. Nota: en cuanto una acción usa [@Res()], [NestJS] asume que es ella quien envía la respuesta e ignora lo que devuelve. Aquí, la acción establece el código de estado y el tipo, y envía el cuerpo con [res.send];
  • líneas 24–27: una redirección 302 realizada por [Express] con [res.redirect(url)];
  • líneas 31–35: con la opción [passthrough: true], la acción usa la respuesta (aquí para agregar un encabezado) pero deja que [NestJS] envíe lo que devuelve. Es lo mejor de ambos mundos;
  • líneas 38–41: el error que se debe evitar: [@Res()] sin [passthrough], y sin llamadas a [res.send], [res.redirect], [res.render].... La cadena devuelta se ignora, nunca se envía una respuesta y el navegador espera indefinidamente.

Respuestas recibidas:

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)"}

(la opción [-A] de [curl] define el encabezado [User-Agent], que identifica al 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 la última acción, limitamos la espera a 3 segundos con la opción [-m 3]:

curl -i -m 3 http://localhost:3000/express/blocked
curl: (28) Operation timed out after 3002 milliseconds with 0 bytes received

En el resto de este documento usaremos [@Res()] cuando una acción deba elegir entre varias respuestas de distintos tipos (una página o una redirección), y nos aseguraremos de que cada camino del código envíe una respuesta.

2.6. Ejemplo 06: módulos, servicios e inyección de dependencias

Los controladores no deben contener lógica de aplicación; la delegan en servicios. El ejemplo 06 divide una pequeña aplicación en dos 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. El servicio 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);
  }
}
  • Líneas 3–7: la interfaz [Product] describe un producto;
  • línea 9: el decorador [@Injectable()] convierte la clase en un servicio (también llamado proveedor): [NestJS] crea una única instancia de ella, que proporciona (inyecta) a todos los que la necesitan;
  • líneas 11–15: los datos, aquí en memoria;
  • líneas 17–23: los dos métodos del servicio.

2.6.2. El controlador ProductsController

import { Controller, Get, NotFoundException, Param } from '@nestjs/common';
import { Product, ProductsService } from './products.service';

@Controller('products')
export class ProductsController {
  // inyección de dependencias: NestJS proporciona la instancia 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;
  }
}
  • línea 7: inyección de dependencias. El controlador declara en su constructor que necesita un [ProductsService]; [NestJS] le proporciona la única instancia del servicio. El controlador nunca llama a [new ProductsService()]. La sintaxis [private readonly productsService: ProductsService] de [TypeScript] declara a la vez el parámetro y el campo [this.productsService];
  • líneas 9–12: la acción delega en el servicio;
  • líneas 14–21: [Number(id)] convierte el parámetro de ruta (una cadena) en un número. Un producto inexistente genera una excepción 404.

2.6.3. El 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 {}
  • línea 6: el controlador del módulo;
  • línea 7: los servicios del módulo. Solo los servicios declarados aquí (o importados, véase más abajo) pueden inyectarse en las clases del módulo;
  • línea 8: el servicio se exporta: los módulos que importen [ProductsModule] también podrán recibirlo por inyección.

2.6.4. El 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 {}

Línea 6: [ClientsModule] importa [ProductsModule] y, por lo tanto, tiene acceso a los servicios que este exporta.

El archivo [src/clients/clients.controller.ts]:

import { Controller, Get } from '@nestjs/common';
import { ProductsService } from '../products/products.service';

@Controller('clients')
export class ClientsController {
  // un servicio de OTRO módulo, exportado por ese 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 };
  }
}
  • Línea 7: a [ClientsController] se le inyecta un servicio de otro módulo;
  • líneas 9–14: usa este servicio para calcular el total de un carrito de compras.

2.6.5. El módulo raíz

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 {}

línea 6: el módulo raíz ya no tiene controlador; simplemente importa los dos módulos de la aplicación.

2.6.6. Ejecución

[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}

El caso de estudio está estructurado exactamente así: controladores ligeros que delegan en servicios inyectados, y módulos que agrupan componentes relacionados.