Tema 3 · Controladores HTTP

3. Controladores (@Controller), Enrutamiento y Decoradores HTTP (@Get, @Post, @Param, @Body)

Construye endpoints REST limpios utilizando decoradores de ruta, extracción declarativa de parámetros, códigos de estado (@HttpCode) y cabeceras.

El Rol del Controlador en NestJS

Los controladores son responsables de recibir las solicitudes HTTP entrantes, extraer parámetros de la URL o del cuerpo JSON, delegar la operación al servicio correspondiente y devolver la respuesta al cliente.

Al decorar una clase con @Controller('cursos'), NestJS agrupa todas las rutas internas bajo el prefijo /cursos. Además, cualquier objeto o arreglo retornado por un método se serializa automáticamente a JSON con cabecera application/json.

Decoradores de Extracción de Datos HTTP

En lugar de acoplar tu código al objeto nativo req de Express, NestJS proporciona decoradores dedicados que hacen la firma de tus métodos limpia y fácil de probar en tests unitarios:

Decorador NestJS Equivalente en Express Uso Recomendado
@Param('id') req.params.id Extraer identificadores dinámicos de la ruta (ej: GET /cursos/:id).
@Query('categoria') req.query.categoria Extraer filtros o paginación de la URL (ej: ?categoria=backend&pagina=1).
@Body() req.body Capturar el payload JSON completo enviado en peticiones POST, PUT o PATCH.
@Headers('x-tenant') req.headers['x-tenant'] Leer cabeceras HTTP específicas enviadas por el cliente.
⚠️ Códigos de Estado por Defecto: En NestJS, todas las peticiones devuelven HTTP 200 OK por defecto, excepto las peticiones @Post() que devuelven automáticamente HTTP 201 Created. Puedes cambiarlo con @HttpCode(HttpStatus.NO_CONTENT).

⚡ Controlador RESTful Completo para el Catálogo de Cursos

Implementación de rutas GET, POST, PATCH y DELETE con extracción declarativa de parámetros:

src/cursos/cursos.controller.ts
Solo lectura
import {
  Controller,
  Get,
  Post,
  Patch,
  Delete,
  Param,
  Query,
  Body,
  HttpCode,
  HttpStatus,
} from '@nestjs/common';
import { CursosService } from './cursos.service';
import { CrearCursoDto } from './dto/crear-curso.dto';

@Controller('cursos')
export class CursosController {
  constructor(private readonly cursosService: CursosService) {}

  // GET /api/v1/cursos?nivel=intermedio
  @Get()
  listarTodos(@Query('nivel') nivel?: string) {
    return this.cursosService.listar(nivel);
  }

  // GET /api/v1/cursos/nestjs-profesional
  @Get(':slug')
  obtenerPorSlug(@Param('slug') slug: string) {
    return this.cursosService.buscarPorSlug(slug);
  }

  // POST /api/v1/cursos -> Responde 201 Created automáticamente
  @Post()
  crear(@Body() dto: CrearCursoDto) {
    return this.cursosService.crear(dto);
  }

  // DELETE /api/v1/cursos/42 -> Responde 204 No Content
  @Delete(':id')
  @HttpCode(HttpStatus.NO_CONTENT)
  eliminar(@Param('id') id: string): void {
    this.cursosService.eliminar(Number(id));
  }
}
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Qué código de estado HTTP devuelve NestJS por defecto cuando un método decorado con @Post() finaliza exitosamente sin que especifiques @HttpCode()?
🦉
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.

🚀 ¿Quieres dominar NestJS Framework Profesional y crear proyectos reales?

Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.