Tutorial Nest: Métodos POST en controladores

Una de las funcionalidades clave en cualquier aplicación web es la capacidad de manejar solicitudes HTTP, y con NestJS, esto se hace mediante controladores.

Un controlador es responsable de manejar las solicitudes entrantes para un módulo particular y devolver una respuesta.

Para definir un controlador en NestJS, se utiliza el decorador @Controller, seguido por un prefijo que indica la ruta del controlador. Dentro de este controlador, para manejar una solicitud POST, se utiliza el decorador @Post.

Esta es una de las muchas anotaciones de métodos de solicitud HTTP disponibles en NestJS, como @Get para solicitudes GET, @Put para solicitudes PUT, entre otras.

¿Qué es un método POST?

El método POST es uno de los métodos de solicitud HTTP utilizados para enviar datos a un servidor. Es comúnmente usado para enviar datos de formulario o información que se desea guardar en una base de datos.

A diferencia del método GET, que recupera información, POST envía información al servidor.

Creación de un controlador POST en NestJS

En NestJS, para crear una ruta que maneje solicitudes POST, se utiliza el decorador @Post() en una función dentro de un controlador.

Veamos un ejemplo básico:

import { Controller, Post, Body } from '@nestjs/common';

@Controller('items')
export class ItemsController {

  @Post()
  create(@Body() createItemDto: CreateItemDto) {
    // Lógica para guardar el item
    return 'Item creado con éxito';
  }
}

En este ejemplo, se ha definido un controlador para la ruta 'items'. La función create está adornada con el decorador @Post(), lo que indica que esta función manejará las solicitudes POST a la ruta '/items'.

El decorador @Body() se utiliza para recuperar el cuerpo de la solicitud, que en este caso se espera que sea una instancia de CreateItemDto.

DTO (Data Transfer Object)

En el ejemplo anterior, se hizo referencia a un CreateItemDto. Un DTO es un objeto que define cómo deben ser los datos que se envían al método.

Usar DTOs en NestJS permite la validación automática de los datos que se envían al API, lo que puede mejorar significativamente la seguridad y la robustez de la aplicación.

Aquí hay un ejemplo de cómo podría verse el CreateItemDto:

export class CreateItemDto {
  readonly name: string;
  readonly description: string;
  readonly price: number;
}

Validación

Para agregar validación al DTO, se pueden usar decoradores proporcionados por el paquete class-validator.

import { IsString, IsInt, IsNotEmpty } from 'class-validator';

export class CreateItemDto {
  @IsNotEmpty()
  @IsString()
  readonly name: string;

  @IsNotEmpty()
  @IsString()
  readonly description: string;

  @IsNotEmpty()
  @IsInt()
  readonly price: number;
}

Con estos decoradores, se asegura que los datos enviados al método cumplan con ciertas condiciones antes de que se procesen.

Manejo de respuestas y errores

Una vez que se ha recibido y validado el cuerpo de la solicitud, es importante responder adecuadamente. NestJS proporciona herramientas para facilitar el manejo de respuestas y errores.

Enviando una respuesta

El método de controlador puede devolver directamente un valor, y NestJS se encargará de convertirlo en una respuesta HTTP.

Sin embargo, para un control más preciso sobre la respuesta, se puede inyectar el objeto Response de Express.

import { Controller, Post, Body, Res } from '@nestjs/common';
import { Response } from 'express';

@Controller('items')
export class ItemsController {

  @Post()
  create(@Body() createItemDto: CreateItemDto, @Res() res: Response) {
    // Lógica para guardar el item
    const newItem = {
      id: Date.now(),
      ...createItemDto
    };
    res.status(201).send(newItem);
  }
}

En este ejemplo, después de "crear" un nuevo item, se envía una respuesta con un código de estado 201 (Created) junto con el item recién creado.

Manejo de errores

NestJS proporciona un mecanismo de filtrado de excepciones que permite un manejo de errores centralizado.

Para lanzar un error, se utiliza la clase HttpException.

Supongamos que se quiere lanzar un error si un item con el mismo nombre ya existe:

import { Controller, Post, Body, Res, HttpException, HttpStatus } from '@nestjs/common';
import { Response } from 'express';

@Controller('items')
export class ItemsController {
  
  private readonly items = [];

  @Post()
  create(@Body() createItemDto: CreateItemDto, @Res() res: Response) {
    const exists = this.items.find(item => item.name === createItemDto.name);
    if(exists) {
      throw new HttpException('Item ya existe', HttpStatus.BAD_REQUEST);
    }

    const newItem = {
      id: Date.now(),
      ...createItemDto
    };
    this.items.push(newItem);
    res.status(201).send(newItem);
  }
}

El HttpException interrumpe la ejecución del método y envía una respuesta con el código de estado y el mensaje proporcionados.

Conclusión

El manejo de solicitudes POST en NestJS es un proceso que involucra definir rutas, validar el cuerpo de la solicitud, gestionar la respuesta y tratar errores de forma adecuada. Con la combinación de decoradores, DTOs y herramientas de manejo de respuestas y errores, NestJS ofrece una estructura robusta y eficiente para construir APIs confiables.