Forem: Juan Carlos Valderrábano Hernández

🧠 MCP (Module Communication Protocol): El lenguaje común entre módulos y agentes

Juan Carlos Valderrábano Hernández — Sun, 06 Apr 2025 15:39:57 +0000

En sistemas distribuidos modernos, uno de los mayores retos es asegurar que los diferentes componentes de la arquitectura funcionen juntos sin crear dependencias frágiles. Aquí es donde entra el MCP (Module Communication Protocol), un protocolo que permite la comunicación estandarizada entre módulos, servicios y agentes inteligentes.

🧩 ¿Qué es MCP?

MCP es un protocolo de comunicación diseñado para intercambiar información de manera estructurada y estandarizada entre diferentes partes de un sistema (microservicios, módulos, agentes). En lugar de depender de integraciones directas entre servicios, MCP utiliza mensajes estandarizados (generalmente en formato JSON) para asegurar que los eventos se envíen y reciban de forma predecible y eficiente.

🚀 ¿Por qué es importante?

A medida que los sistemas crecen, también lo hace su complejidad. Sin un protocolo común, nos enfrentamos a varios problemas:

Dependencia entre módulos: cada módulo debe entender cómo interactuar con otros.
Falta de trazabilidad: los eventos y cambios no se registran de forma estructurada.
Escalabilidad limitada: agregar nuevos módulos o servicios puede romper integraciones existentes.

Con MCP, estos problemas se resuelven de manera eficiente:

Desacoplamiento funcional: los módulos no dependen directamente entre sí.
Estandarización: los mensajes siguen un formato común.
Escalabilidad: añadir nuevos módulos o agentes es sencillo.
Trazabilidad: cada acción queda registrada de manera clara y completa.

🤖 MCP + Agentes Inteligentes

Una de las características más potentes de MCP es su integración con agentes autónomos. Estos agentes son procesos inteligentes que escuchan eventos, analizan el contexto y toman decisiones automatizadas.

Ejemplo de flujo:

Un módulo detecta un evento relevante (ej. un archivo ha sido subido).
El módulo envía un mensaje MCP con el evento:

 {
   "event": "file_uploaded",
   "module": "data_importer",
   "payload": {
     "file_id": "abc123",
     "filename": "transacciones_marzo.xlsx"
   }
 }

Un agente escucha ese evento, lo interpreta y responde con una acción sugerida:

{
  "event": "suggest_action",
  "module": "smart_agent",
  "payload": {
    "action": "map_columns",
    "file_id": "abc123",
    "confidence": 0.92
  }
}

Gracias a MCP, los agentes pueden actuar de forma autónoma y tomar decisiones basadas en los eventos del sistema, sin depender de integraciones directas con otros módulos.

📊 Comparativa: MCP vs Métodos Tradicionales

Característica	MCP (Module Communication Protocol)	Integración Directa	Webhooks Tradicionales
Desacoplamiento	✅ Muy alto	❌ Bajo	⚠️ Medio
Formato estandarizado	✅ JSON con contrato	❌ Variable	⚠️ Parcial
Escalabilidad	✅ Alta (plug-and-play)	❌ Costosa y frágil	⚠️ Limitada
Soporte para agentes	✅ Nativo	❌ No soportado	⚠️ Adaptación requerida
Trazabilidad	✅ Clara y completa	❌ Difusa	⚠️ Depende del diseño
Reusabilidad	✅ Alta	❌ Baja	⚠️ Media
Automatización de flujos	✅ Facilitada	❌ Manual	⚠️ Parcial

🛠️ ¿Cuándo considerar MCP?

Implementar MCP es ideal en los siguientes casos:

Estás construyendo una plataforma modular con múltiples servicios.
Quieres incorporar agentes autónomos en tu arquitectura.
Necesitas mantener un registro auditable y estandarizado de todos los eventos.
Buscas escalar sin romper la estructura actual.
Estás migrando a una arquitectura orientada a eventos.

Brújula del Propósito: Manteniendo el Rumbo con un Concepto Definido

Juan Carlos Valderrábano Hernández — Wed, 02 Apr 2025 15:55:53 +0000

Hoy quiero compartir algunas reflexiones sobre la importancia de tener un concepto claramente definido para cualquier empresa o negocio, sin importar su tamaño. En particular, me centraré en las consecuencias de navegar sin una "estrella del norte".

Imaginemos una empresa que desarrolla software, ya sea para la venta o para uso interno. Si no se define un propósito claro y limitaciones para ese software, el camino se llenará de obstáculos.

El Peligro de la Expansión Sin Dirección

Consideremos un software diseñado para gestionar citas en un consultorio médico. Inicialmente, el alcance podría definirse como la gestión básica (CRUD: crear, leer, actualizar, eliminar citas). Sin embargo, un simple CRUD podría no ofrecer suficiente valor, ya que una hoja de cálculo o herramientas similares podrían cumplir esa función.

La idea de agregar recordatorios por correo electrónico para los pacientes suena como una mejora lógica que se alinea con el propósito. Extenderlo a recordatorios por llamada telefónica también podría considerarse dentro del mismo ámbito. Incluso la sugerencia de que el software gestione el calendario del médico unificando sus citas podría parecer una evolución natural.

La Trampa de las "Buenas" Ideas

Sin embargo, aquí es donde reside el peligro. La solicitud de integrar el calendario personal del médico, extrayendo información de su correo electrónico y unificándola con las citas del consultorio, comienza a desviar el propósito original. El software, concebido para la gestión de citas médicas, ahora aspira a ser un gestor de calendarios más amplio.

¿Y qué sigue? Tal vez la siguiente petición sea gestionar la agenda telefónica de los pacientes. En este punto, el software estaría peligrosamente cerca de convertirse en una mini red social: si ya tiene contactos y calendarios, ¿por qué no enviar mensajes de cumpleaños o actualizaciones de la clínica?

La Erosión del Propósito

Basta una "buena" idea mal disfrazada, impulsada por alguien con la capacidad de argumentar convincentemente, para comprometer el futuro y el enfoque del producto. Sin un limitador claro, sin un concepto fundamental, sin una estrategia definida, el propósito inicial se desvirtúa por completo.

La Importancia de la Estrella del Norte

¿Qué podemos hacer para evitar esta deriva y mantener el rumbo? La clave está en definir y aferrarse a nuestra "estrella del norte": el propósito fundamental de nuestro software o negocio.

La Fortaleza del "No" Estratégico

Es válido y necesario decir "no":

No al cliente: Cuando una solicitud, aunque parezca atractiva, nos aleja de nuestro propósito central.
No al producto: Cuando una nueva funcionalidad, aunque innovadora, diluye el valor y la especialización de lo que hacemos.

Siempre debemos referirnos a nuestra "estrella del norte". Si una nueva idea o solicitud rompe con ese propósito fundamental, debemos tener la disciplina de rechazarla.

No podemos aspirar a tener un software que lo haga todo. Sin embargo, sí podemos crear un software que haga lo que debe hacer, y que lo haga bien. La claridad de nuestro concepto y la firmeza en nuestros límites son esenciales para lograrlo.

Implementación de "EleganFlow": Arquitectura Modular y Sostenible

Juan Carlos Valderrábano Hernández — Tue, 11 Mar 2025 22:38:34 +0000

Introducción

Hace más de un año, implementamos una arquitectura que inicialmente bauticé como Simplex, la cual fue refinada hasta convertirse en EleganFlow. Este nombre refleja la simplicidad y practicidad que buscábamos al diseñar un flujo modular y robusto para nuestras aplicaciones. En este artículo, compartiré las lecciones aprendidas, las mejoras que implementamos y los buenos patrones que adoptamos a lo largo del camino.

¿Qué es EleganFlow?

EleganFlow es una arquitectura modular diseñada principalmente para NestJS, aunque sus principios pueden aplicarse a otros frameworks. Se basa en la separación de responsabilidades en tres etapas bien definidas: Verificación, Proceso y Presentación. Cada etapa está compuesta por reglas o procesos individuales que se alinean con el principio de responsabilidad única. Este enfoque facilita la comprensión, mantenimiento y extensibilidad del sistema.

¿Por qué EleganFlow?

Al inicio, implementar una arquitectura robusta como EleganFlow puede parecer una tarea costosa, pero sus beneficios se vuelven evidentes con el tiempo. A medida que la base de código crecía, los errores fueron disminuyendo considerablemente. Este tipo de arquitectura modular facilita las actualizaciones, simplifica la depuración y asegura que cada componente haga solo una cosa.

Principios Clave de EleganFlow

Responsabilidad Única: Cada módulo, regla o proceso tiene una única responsabilidad dentro de su contexto.
Modularidad: Las etapas del flujo están claramente separadas, permitiendo una fácil integración y extensión.
Estrategias Independientes: Las reglas y procesos se implementan como estrategias independientes, lo que permite modificarlas sin afectar el sistema entero.
Retroalimentación Clara: En cada fase, el sistema proporciona retroalimentación clara al usuario, asegurando que los errores sean fáciles de identificar y corregir.

Etapas de la Arquitectura EleganFlow

1.Verificación
La verificación es la primera etapa en EleganFlow, y tiene dos componentes principales:

Sintaxis:

Validación inicial de la estructura y los tipos de datos utilizando DTOs (Data Transfer Objects).

Semántica:
Validación profunda según las reglas de negocio, asegurando que los datos sean consistentes y lógicamente válidos.

Flujo de trabajo:

Controlador:
Los datos entrantes son recibidos y validados en términos de sintaxis utilizando DTOs. Si la validación falla, se responde con los errores correspondientes.
Servicio: Los datos validados se pasan al servicio, donde se realiza una validación semántica utilizando reglas de negocio.
Ejemplo de Implementación

DTO de Creación:

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

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

  @IsEmail()
  email: string;
}

Controlador:

import { Controller, Post, Body } from '@nestjs/common';
import { CreatePersonDto, PeopleService, Person } from '../.';
import { CreateResponseInterface, HttpStatusEnum } from '../../common';

@Controller('people')
export class PeopleController {
  constructor(private readonly peopleService: PeopleService) {}

  @Post()
  async create(@Body() createPersonDto: CreatePersonDto): Promise<CreateResponseInterface<Person>> {
    return await this.peopleService.create(createPersonDto);
  }
}

Servicio:

import { Injectable } from '@nestjs/common';
import { Person } from '../entities';
import { CreatePersonDto } from '../dtos';
import { PersonChecker } from '../checkers';

@Injectable()
export class PeopleService {
  constructor(private readonly personChecker: PersonChecker) {}

  async create(createPersonDto: CreatePersonDto): Promise<CreateResponseInterface<Person>> {
    const newPerson: Person = CreatePersonDtoToPersonAdjust(createPersonDto);
    await this.personChecker.validateCreate(newPerson);
    return { ok: true, data: newPerson, message: 'Person created successfully' };
  }
}

2. Proceso

En la etapa de proceso, cada paso se implementa como un proceso que sigue el principio de responsabilidad única. Los procesos se agrupan en un blueprint que define el flujo completo de procesamiento. Esta fase puede incluir la iteración y enriquecimiento de datos.

Proceso y Rollback:

Si un paso falla, se puede hacer un rollback, asegurando que los datos previos no se vean comprometidos.

3. Presentación

En esta etapa, se construye la respuesta final que será presentada al usuario. Aquí no se deben generar nuevos registros en la base de datos. Solo se transforma la información previamente procesada.

Beneficios de EleganFlow

1. Modularidad y Flexibilidad
Cada etapa es independiente y puede ser extendida o modificada sin afectar a las demás, lo que permite adaptarse a cambios rápidamente.

2. Claridad y Simplicidad
La arquitectura es fácil de entender y cada componente tiene un propósito claro, lo que facilita el desarrollo y la depuración.

3. Reutilización
Las reglas y procesos son modulares y pueden ser reutilizados en diferentes partes del sistema o incluso en otros proyectos.

4. Retroalimentación Clara
Los usuarios siempre reciben retroalimentación clara y detallada en caso de errores, lo que facilita la identificación de problemas.

Desafíos Iniciales
Aunque EleganFlow trae muchos beneficios, su implementación inicial puede requerir un esfuerzo considerable. Aquí algunos desafíos:

Complejidad Inicial:
La configuración de reglas y procesos puede llevar tiempo, especialmente en aplicaciones más simples.
Sobrecarga de Desarrollo: La necesidad de mantener la modularidad puede incrementar la carga de desarrollo.
Curva de Aprendizaje: Los nuevos desarrolladores pueden necesitar tiempo para adaptarse a este tipo de arquitectura.

Conclusión

La implementación de EleganFlow ha demostrado ser una inversión rentable a largo plazo. Su modularidad, claridad y facilidad de mantenimiento han reducido significativamente los errores y han mejorado la estabilidad del sistema. La clave está en aplicar principios sólidos de arquitectura como la responsabilidad única y modularidad, lo que hace que el sistema sea escalable y fácil de entender.

La implementación de una arquitectura de este tipo no solo es sostenible, sino que también facilita las actualizaciones y mejora la calidad del código a medida que el proyecto crece.

Git: Domina tus commits y evita los dolores de cabeza

Juan Carlos Valderrábano Hernández — Sat, 25 Jan 2025 17:22:43 +0000

¿Alguna vez te has sentido perdido en el laberinto de tus commits? ¡No estás solo! Git es una herramienta increíblemente poderosa, pero también puede ser un poco desafiante para los principiantes. En esta guía, te ayudaremos a evitar los errores más comunes y a convertirte en un maestro del control de versiones.

Los errores más comunes en Git y cómo solucionarlos

Commits incorrectos: ¿Has agregado accidentalmente un archivo que no debería estar ahí? ¡No te preocupes! Con git reset HEAD~1 y git rm --cached <archivo> podrás revertir el último commit y eliminar el archivo del staging area.
Conflictos de fusión: ¿Estás trabajando en una rama y otro desarrollador ha hecho cambios en el mismo archivo? Resuelve los conflictos manualmente y marca los cambios como resueltos con git add <archivo>.
Olvidar hacer commit: ¿Has estado trabajando durante horas y te das cuenta de que no has guardado tus cambios? ¡Utiliza git add . para añadir todos los cambios al staging area y git commit -m "Mensaje descriptivo" para guardarlos en el historial de Git! Si necesitas guardar tus cambios temporalmente, git stash es tu amigo.
Olvidar hacer push: ¿Has realizado cambios pero aún no los has compartido con el equipo? ¡Un simple git push origin <rama> solucionará el problema!
Olvidar el nombre de un comando: ¿Te sientes perdido en la terminal? ¡Utiliza git help o busca en línea! La comunidad de Git es muy activa y siempre está dispuesta a ayudar.

Consejos para convertirte en un maestro de Git

Commits frecuentes: Haz commits pequeños y con frecuencia para tener un historial de cambios claro y conciso.
Commits atómicos: Cada commit debe representar un cambio lógico y completo.
Utiliza alias: Crea alias para los comandos que más utilizas para agilizar tu trabajo.
Visualiza tus cambios: Herramientas como gitk y git log --oneline --graph te ayudarán a entender mejor tu historial de commits.
Practica regularmente: La práctica hace al maestro. ¡Crea pequeños proyectos y experimenta con diferentes comandos!

👮🏻‍♂️ Enfoque en la Verificación de la Arquitectura 'EleganFlow'

Juan Carlos Valderrábano Hernández — Thu, 23 Jan 2025 17:30:41 +0000

La arquitectura "EleganFlow" se destaca por su modularidad y separación clara de responsabilidades. En este artículo, exploraremos la primera etapa del flujo: la Verificación, una fase crucial para asegurar la integridad y validez de los datos antes de que pasen por las etapas de procesamiento y presentación.

Módulo de Verificación

El módulo de verificación tiene como objetivo principal garantizar que los datos proporcionados por los usuarios o sistemas cumplan con los criterios de calidad y consistencia necesarios para ser procesados correctamente. Este proceso se divide en dos niveles:

1. Verificación de Sintaxis

La validación inicial de la estructura y los tipos de datos se realiza mediante DTOs (Data Transfer Objects).

2. Verificación de Semántica

Una validación más profunda basada en las reglas de negocio, asegurando que los datos sean lógicamente consistentes con las expectativas del sistema.

Flujo de Trabajo

El proceso de verificación comienza en el controlador y se complementa en el servicio. A continuación, se detalla el flujo:

Controlador: Los datos entrantes son recibidos y validados a nivel de sintaxis utilizando los DTOs. Si la validación falla, se responde de inmediato con los errores correspondientes.
Servicio: Los datos validados a nivel de sintaxis son enviados al servicio, donde se ejecuta la validación semántica utilizando un conjunto de reglas de negocio. Si alguna regla falla, se detiene el flujo y se notifica al usuario con retroalimentación clara.

Interfaces y DTOs

`CreatePersonDto`

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

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

  @IsEmail()
  email: string;
}

`CreateResponseInterface`

export interface CreateResponseInterface<T> {
  ok: boolean;
  data: T;
  constraints: string[];
  message: string;
}

Ejemplo de Implementación

Controlador

import {
  Controller,
  Post,
  Body,
} from '@nestjs/common';
import { CreatePersonDto, PeopleService, Person } from '../.';
import {
  CreateResponseInterface,
  HttpStatusEnum,
} from '../../common';
import { ApiResponse, ApiTags } from '@nestjs/swagger';

@ApiTags('people')
@Controller('people')
export class PeopleController {
  constructor(private readonly peopleService: PeopleService) {}

  @Post()
  @ApiResponse({
    status: HttpStatusEnum.Created,
    description: 'The record has been successfully created.',
  })
  async create(
    @Body() createPersonDto: CreatePersonDto,
  ): Promise<CreateResponseInterface<Person>> {
    return await this.peopleService.create(createPersonDto);
  }
}

Servicio

import { Injectable, Logger } from '@nestjs/common';
import { Person } from '../entities';
import { CreatePersonDto } from '../dtos';
import { PersonChecker } from '../checkers';

@Injectable()
export class PeopleService {
  private readonly logger = new Logger(PeopleService.name);

  constructor(private readonly personChecker: PersonChecker) {}

  async create(createPersonDto: CreatePersonDto): Promise<CreateResponseInterface<Person>> {
    // Conversión del DTO a entidad
    const newPerson: Person = CreatePersonDtoToPersonAdjust(createPersonDto);

    // Validación de reglas de negocio
    await this.personChecker.validateCreate(newPerson);

    // Lógica adicional y retorno de respuesta
    return { ok: true, data: newPerson, constraints: [], message: 'Person created successfully' };
  }
}

Validador de Reglas

import { Injectable } from '@nestjs/common';
import { Person } from '../entities';
import { SingleEmailPerPersonRule } from '../rules';

@Injectable()
export class PersonChecker {
  async validateCreate(person: Person): Promise<void> {
    const rules = [
      new SingleEmailPerPersonRule(),
    ];

    for (const rule of rules) {
      await rule.validate(person);
    }
  }
}

Regla de Negocio

import { Person } from '../entities';

export class SingleEmailPerPersonRule {
  async validate(person: Person): Promise<void> {
    if (!person.email.includes('@example.com')) {
      throw new Error('Email domain must be @example.com');
    }
  }
}

Test Unitario

Ejemplo de Prueba para el Servicio

import { Test, TestingModule } from '@nestjs/testing';
import { PeopleService } from '../services/people.service';
import { PersonChecker } from '../checkers';
import { CreatePersonDto } from '../dtos';
import { Person } from '../entities';

describe('PeopleService', () => {
  let service: PeopleService;
  let checker: PersonChecker;

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [
        PeopleService,
        {
          provide: PersonChecker,
          useValue: {
            validateCreate: jest.fn(),
          },
        },
      ],
    }).compile();

    service = module.get<PeopleService>(PeopleService);
    checker = module.get<PersonChecker>(PersonChecker);
  });

  it('should create a person successfully', async () => {
    const dto: CreatePersonDto = { name: 'John Doe', email: 'john.doe@example.com' };
    const expectedPerson: Person = { id: 1, ...dto };

    jest.spyOn(service, 'create').mockResolvedValue({
      ok: true,
      data: expectedPerson,
      constraints: [],
      message: 'Person created successfully',
    });

    const result = await service.create(dto);

    expect(result.ok).toBe(true);
    expect(result.data).toEqual(expectedPerson);
  });
});

Ventajas de la Verificación en "EleganFlow"

Modularidad: Las validaciones se agrupan en reglas independientes, lo que facilita su reutilización y mantenimiento.
Claridad: La separación entre validación de sintaxis y semántica mejora la comprensión del flujo.
Retroalimentación: Los errores se identifican rápidamente y se comunican de manera clara al usuario.

Conclusión

El módulo de verificación en la arquitectura "EleganFlow" asegura que solo los datos válidos ingresen a las etapas posteriores del flujo, mejorando la calidad del sistema y reduciendo la probabilidad de errores. Este enfoque estructurado facilita la extensibilidad y el mantenimiento a largo plazo.

🚀 Guía para: Workshop de Introducción a la API de ChatGPT utilizando NestJS/Node.js

Juan Carlos Valderrábano Hernández — Fri, 16 Aug 2024 14:05:41 +0000

¡Bienvenidos al Workshop de Introducción a la API de ChatGPT utilizando NestJS/Node.js! En este taller, aprenderemos a integrar la API de ChatGPT en aplicaciones desarrolladas con NestJS o Node.js, explorando desde la configuración inicial hasta la implementación de casos prácticos y avanzados.

📍 Objetivos del Workshop

Comprender la API de ChatGPT: Familiarizarnos con la API de ChatGPT, su estructura de mensajes, y cómo puede ser utilizada en aplicaciones basadas en Node.js y NestJS.
Configuración del Entorno: Preparar un entorno de desarrollo con NestJS/Node.js, incluyendo la instalación de dependencias y configuración de claves API.
Realización de Solicitudes a la API: Aprender a realizar solicitudes a la API de ChatGPT dentro de un proyecto NestJS/Node.js, utilizando ejemplos claros y documentados.
Implementación de Funcionalidades Clave: Desarrollar funcionalidades como análisis de texto, detección de sentimientos y generación de respuestas conversacionales en una API REST.
Aplicación Práctica en Proyectos Reales: Implementar los conceptos aprendidos en un proyecto práctico, creando endpoints que interactúen con la API de ChatGPT.
Documentación y Mejores Prácticas: Explorar cómo documentar adecuadamente el código y seguir las mejores prácticas en el desarrollo de APIs.

📅 Estructura del Taller

1. Introducción y Objetivos

Presentación del Taller: Introducción a los objetivos y alcance del taller.
Requisitos Previos: Conocimientos básicos de NestJS/Node.js y acceso a la API de OpenAI.

2. Configuración Inicial

2.1 Instalación de Node.js y NestJS

Instalación de Node.js: Descarga e instalación de Node.js desde la página oficial.
Creación de un Proyecto NestJS: Usar el CLI de NestJS para crear un nuevo proyecto:
```
 npm i -g @nestjs/cli
 nest new chatgpt-workshop
```
Configuración Inicial: Configuración del entorno y estructura del proyecto.

2.2 Instalación de Dependencias

Axios: Una biblioteca para realizar solicitudes HTTP:
```
 npm install axios
```
Dotenv: Para manejar variables de entorno de manera segura:
```
 npm install dotenv
```
Configuración de Variables de Entorno: Crear un archivo .env para almacenar la clave API de OpenAI:
```
 OPENAI_API_KEY=tu_clave_api_aqui
```

3. Primeros Pasos con la API en Node.js/NestJS

3.1 Integración con Axios

Configuración de Axios: Crear un servicio en NestJS que utilice Axios para realizar solicitudes a la API de OpenAI.

Ejemplo de Código:

 import { Injectable } from '@nestjs/common';
 import axios from 'axios';

 @Injectable()
 export class ChatGptService {
   private readonly apiKey = process.env.OPENAI_API_KEY;
   private readonly apiUrl = 'https://api.openai.com/v1/chat/completions';

   async sendMessage(messages: Array<{ role: string; content: string }>) {
     const response = await axios.post(
       this.apiUrl,
       {
         model: 'gpt-4',
         messages: messages,
       },
       {
         headers: {
           Authorization: `Bearer ${this.apiKey}`,
           'Content-Type': 'application/json',
         },
       },
     );

     return response.data;
   }
 }

Documentación:
- apiKey: Clave API obtenida desde el archivo .env.
- apiUrl: URL base para la API de OpenAI.
- sendMessage(): Método que envía un array de mensajes a la API de ChatGPT.

3.2 Realización de Solicitudes Básicas

Estructura de Mensajes:

role: Define el rol del participante en la conversación (system, user, assistant).
content: Contenido del mensaje.
Ejemplo de Solicitud:

   {
     "model": "gpt-4",
     "messages": [
       {"role": "system", "content": "You are a helpful assistant."},
       {"role": "user", "content": "What is the capital of France?"}
     ]
   }

Respuesta:

   {
     "id": "chatcmpl-abc123",
     "object": "chat.completion",
     "created": 1689988888,
     "choices": [
       {
         "index": 0,
         "message": {
           "role": "assistant",
           "content": "The capital of France is Paris."
         },
         "finish_reason": "stop"
       }
     ],
     "usage": {
       "prompt_tokens": 13,
       "completion_tokens": 9,
       "total_tokens": 22
     }
   }

4. Análisis de Texto y Conversaciones

4.1 Generación de Respuestas

Descripción: Uso de la API para generar respuestas automáticas basadas en la entrada del usuario.

Ejemplo de Código:

 import { Controller, Post, Body } from '@nestjs/common';
 import { ChatGptService } from './chatgpt.service';

 @Controller('chat')
 export class ChatController {
   constructor(private readonly chatGptService: ChatGptService) {}

   @Post('message')
   async sendMessage(@Body('message') message: string) {
     const messages = [{ role: 'user', content: message }];
     const response = await this.chatGptService.sendMessage(messages);
     return response.choices[0].message.content;
   }
 }

Explicación:
- ChatController: Define un endpoint POST para enviar mensajes a la API de ChatGPT.
- sendMessage(): Recibe un mensaje de usuario y lo envía a la API, devolviendo la respuesta generada.

4.2 Manejo del Contexto en Conversaciones

Descripción: Mantener el contexto de una conversación mediante la gestión de un historial de mensajes.

Ejemplo de Código:

 let chatHistory = [
   { role: 'system', content: 'You are a helpful assistant.' },
 ];

 @Post('conversation')
 async continueConversation(@Body('message') message: string) {
   chatHistory.push({ role: 'user', content: message });
   const response = await this.chatGptService.sendMessage(chatHistory);
   chatHistory.push(response.choices[0].message);
   return response.choices[0].message.content;
 }

Explicación:
- chatHistory: Un array que almacena el historial de la conversación.
- continueConversation(): Añade el nuevo mensaje al historial, lo envía a la API y actualiza el historial con la respuesta.

5. Análisis de Sentimientos

5.1 Implementación de Detección de Sentimientos

Descripción: Utilizar la API para analizar el tono y los sentimientos en un texto dado.

Ejemplo de Código:

 @Post('sentiment')
 async analyzeSentiment(@Body('message') message: string) {
   const messages = [
     { role: 'system', content: 'You are an assistant specialized in sentiment analysis.' },
     { role: 'user', content: message },
   ];
   const response = await this.chatGptService.sendMessage(messages);
   return response.choices[0].message.content;
 }

Explicación:
- analyzeSentiment(): Envia un texto a la API con el contexto de análisis de sentimientos y devuelve la interpretación.

6. Aplicación Práctica: Creación de una API REST Completa

6.1 Proyecto de Ejemplo: API RESTful

Descripción: Desarrollo de una API RESTful completa en NestJS que integra las funcionalidades de ChatGPT para generación de texto, manejo de conversaciones, y análisis de sentimientos.
Endpoints:
- POST /chat/message: Genera una respuesta simple basada en el input del usuario.
- POST /chat/conversation: Mantiene el contexto de la conversación para respuestas más complejas.
- POST /chat/sentiment: Analiza el sentimiento del texto proporcionado.

6.2 Manejo de Errores y Validaciones

Descripción: Implementar validaciones y manejo de errores en la API para asegurar la robustez.

Ejemplo de Manejo de Errores:

 import { HttpException, HttpStatus } from '@nestjs/common';

 async sendMessage(messages: Array<{ role: string; content: string }>) {
   try {
     const response = await axios.post(this.apiUrl, {
       model: 'gpt-4',
       messages: messages,
     }, {
       headers: {
         Authorization: `Bearer ${this.apiKey}`,
         'Content-Type': 'application/json',
       },
     });

     return response.data;
   } catch (error) {
     throw new HttpException('Error comunicándose con la API de ChatGPT', HttpStatus.BAD_REQUEST);
   }
 }

7. Documentación y Mejores Prácticas

7.1 Documentación de la API

Descripción: Documentar la API utilizando Swagger y OpenAPI para facilitar la comprensión y uso por otros desarrolladores.

Implementación de Swagger:

 import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

 const options = new DocumentBuilder()
   .setTitle('ChatGPT API')
   .setDescription('API de ejemplo integrando ChatGPT con NestJS')
   .setVersion('1.0')
   .build();

 const document = SwaggerModule.createDocument(app, options);
 SwaggerModule.setup('api', app, document);

8. Preguntas y Respuestas

9. Conclusión

🛠️ Recursos Adicionales

Documentación Oficial de OpenAI: Revisión detallada de las capacidades y funcionalidades de la API.
NestJS Documentation: Guía completa para trabajar con NestJS.
Axios Documentation: Referencia para realizar solicitudes HTTP con Axios.

Mantén las Cosas Simples: El Poder del Principio KISS en el Desarrollo de Software

Juan Carlos Valderrábano Hernández — Sat, 10 Aug 2024 22:03:57 +0000

En el mundo del desarrollo de software, la simplicidad es clave. Constantemente enfrentamos decisiones que afectan la complejidad y el mantenimiento de nuestros proyectos. Uno de los principios fundamentales que nos guía hacia la simplicidad es el principio KISS, que significa "Keep It Simple, Stupid" (Manténlo Simple, Estúpido). Aunque el término puede sonar algo brusco, su mensaje es poderoso: cuanto más simple sea tu diseño y código, menos errores cometerás y más fácil será mantenerlo.

¿Qué es el Principio KISS?

El principio KISS se basa en la idea de que los sistemas funcionan mejor cuando se diseñan y construyen de la manera más simple posible. La complejidad innecesaria no solo aumenta la probabilidad de errores, sino que también hace que el código sea más difícil de entender, mantener y modificar.

Cuando aplicas KISS, te obligas a tomar decisiones conscientes sobre lo que realmente es necesario para resolver el problema en cuestión. En lugar de prever y codificar para todas las posibles eventualidades futuras (la mayoría de las cuales probablemente nunca ocurrirán), te concentras en lo que es esencial ahora. Esto no significa que no debas pensar en la escalabilidad o la flexibilidad, sino que debes hacerlo de una manera que no complique innecesariamente el presente.

La Trampa de la Sobreingeniería

Uno de los mayores enemigos de la simplicidad es la sobreingeniería. Esto ocurre cuando intentas prever todos los posibles escenarios futuros y diseñar tu sistema para manejarlos desde el principio. A primera vista, esto puede parecer prudente, pero en realidad, la mayoría de esas eventualidades probablemente nunca sucederán. El resultado es una cantidad innecesaria de código que debe mantenerse, lo que complica el proyecto y aumenta el riesgo de errores.

Peor aún, cuando ese código adicional no se usa, se convierte en un desperdicio de recursos, tanto en términos de tiempo de desarrollo como de mantenimiento. Esto generalmente sucede porque no se tomó el tiempo suficiente para analizar adecuadamente lo que realmente se necesitaba. En lugar de agregar capas de complejidad para manejar situaciones hipotéticas, es mejor centrarse en lo que es necesario ahora y mantener la posibilidad de escalar y adaptar el sistema de manera sencilla en el futuro.

¿Por Qué Mantenerlo Simple?

Menos código, menos errores: Cada línea de código adicional es una oportunidad para que se introduzca un error. Al mantener tu código simple y directo, reduces las oportunidades de que algo salga mal.
Facilidad de mantenimiento: Un código simple es más fácil de entender, tanto para ti como para cualquier otra persona que pueda trabajar en el proyecto en el futuro. Esto facilita la resolución de problemas y la implementación de cambios.
Ahorro de recursos: Mantener las cosas simples ahorra tiempo y recursos, tanto en el desarrollo inicial como en el mantenimiento a largo plazo. Al evitar la sobreingeniería, puedes concentrar tus esfuerzos en lo que realmente importa.
Mayor enfoque en el análisis: Al simplificar el código, obligas a un análisis más profundo y preciso de las necesidades actuales. Esto asegura que estás resolviendo el problema correcto de la manera más eficiente posible.

Conclusión

El principio KISS es una guía poderosa para mantener tus proyectos de software manejables, eficientes y libres de errores innecesarios. Si bien es importante tener en cuenta la escalabilidad y la flexibilidad, es crucial no perderse en la trampa de la sobreingeniería. Mantén tu código simple y enfocado en lo esencial, y estarás en el camino correcto para construir software que no solo funcione bien hoy, sino que también sea fácil de mantener y adaptar en el futuro.

En resumen, siempre toma el tiempo para analizar lo que realmente necesitas. Deja el código listo para las necesidades actuales, pero no te preocupes por todas las posibles eventualidades futuras. La simplicidad es tu mejor aliada para evitar errores, reducir costos y crear software que funcione. Recuerda, menos es más, y en el desarrollo de software, lo más simple es menos propenso a fallar.

Validación de Sintaxis y Semántica en NestJS: Asegurando un Código Robusto y Seguro

Juan Carlos Valderrábano Hernández — Sat, 10 Aug 2024 03:05:43 +0000

Cuando desarrollamos aplicaciones con NestJS, una de las prácticas más importantes es la validación de los datos que nuestras APIs reciben. Validar adecuadamente los datos no solo mejora la seguridad de la aplicación, sino que también garantiza que los datos sean coherentes y estén correctamente formateados antes de ser procesados por las capas de negocio.

En este artículo, exploraremos cómo realizar la validación de sintaxis y semántica en NestJS, utilizando Data Transfer Objects (DTOs), class-validator, y servicios. También veremos cómo la transformación de datos en los controladores puede ser una herramienta útil y cómo estas prácticas pueden hacer que nuestro código sea más robusto y seguro.

1. Validación de Sintaxis con DTOs y `class-validator`

La validación de sintaxis se centra en asegurarse de que los datos que recibimos cumplen con el formato y tipo de datos esperados. En NestJS, esto se logra utilizando DTOs (Data Transfer Objects) junto con la biblioteca class-validator.

1.1 ¿Qué es un DTO?

Un DTO es una clase que define la estructura de los datos que se esperan recibir. NestJS utiliza estas clases para validar automáticamente los datos de entrada antes de que lleguen a la lógica de negocio. Aquí hay un ejemplo básico de un DTO:

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

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

  @IsInt()
  @Min(0)
  readonly age: number;

  @IsEmail()
  readonly email: string;
}

Este DTO asegura que, al crear un nuevo usuario, el nombre sea una cadena, la edad sea un número entero y que el correo electrónico tenga un formato válido.

1.2 Validación Automática con `class-validator`

Cuando usamos class-validator, podemos aplicar diferentes decoradores a las propiedades del DTO para definir las reglas de validación. Algunas de las más comunes incluyen:

@IsString(): Valida que el valor sea una cadena.
@IsInt(): Valida que el valor sea un número entero.
@Min(valor): Valida que el valor sea mayor o igual al valor mínimo especificado.
@IsEmail(): Valida que el valor sea un correo electrónico válido.

Estos decoradores permiten definir reglas de sintaxis claras y precisas, garantizando que cualquier dato que no cumpla con estos criterios sea rechazado automáticamente antes de llegar al servicio.

1.3 Custom Pipes para Validaciones Adicionales

En ocasiones, es necesario aplicar validaciones más complejas o personalizadas, como asegurarse de que un valor pertenezca a un conjunto específico de valores. Para esto, podemos usar pipes personalizados.

Ejemplo de un pipe personalizado para validar un enum:

import { PipeTransform, BadRequestException } from '@nestjs/common';

export class ParseEnumPipe implements PipeTransform<string, any> {
  constructor(private readonly enumType: object) {}

  transform(value: string): any {
    if (!(value in this.enumType)) {
      throw new BadRequestException(`${value} is not a valid option`);
    }
    return this.enumType[value];
  }
}

Uso del pipe en un controlador:

@Post()
createTask(@Body('status', new ParseEnumPipe(TaskStatus)) status: TaskStatus) {
  return this.taskService.createTask(status);
}

Aquí, ParseEnumPipe se asegura de que el valor de status pertenezca a los valores permitidos por el enum TaskStatus. Esta validación adicional ayuda a mantener la integridad de los datos desde las etapas más tempranas del procesamiento.

2. Validación de Semántica en los Servicios: Garantizando la Coherencia del Negocio

La validación de semántica se realiza en los servicios, donde se verifica que los datos no solo estén correctamente formateados, sino que también tengan sentido dentro del contexto de la aplicación. Este tipo de validación asegura que los datos cumplan con las reglas de negocio antes de que se realice cualquier operación, como la inserción o actualización en la base de datos.

2.1 Ejemplo de Validación Semántica en un Servicio

Supongamos que estamos trabajando con órdenes de compra. Queremos asegurarnos de que una orden exista y que esté en un estado válido (PENDING) antes de confirmarla. Esta validación se realiza en el servicio:

@Injectable()
export class OrderService {
  async validateOrder(orderId: string): Promise<Order> {
    const order = await this.orderRepository.findOne(orderId);
    if (!order) {
      throw new NotFoundException(`Order with ID ${orderId} not found`);
    }

    if (order.status !== 'PENDING') {
      throw new BadRequestException('Order is not in a valid state');
    }

    return order;
  }

  async confirmOrder(order: Order): Promise<Order> {
    order.status = 'CONFIRMED';
    return this.orderRepository.save(order);
  }
}

En este ejemplo, el método validateOrder se asegura de que la orden cumpla con todas las condiciones necesarias antes de que se realice cualquier operación en la base de datos. Este tipo de validación protege contra errores y asegura que solo se procesen datos válidos.

3. Transformación de Datos en los Controladores: Manejando los Datos para la Coherencia

En algunos casos, es necesario transformar los datos antes de que lleguen a los servicios o después de recibir la respuesta. Esto puede incluir convertir datos de un formato a otro, agregar o eliminar propiedades, o realizar cálculos adicionales.

3.1 ¿Por qué y cuándo transformar los datos?

Transformar los datos puede ser necesario para mantener la coherencia entre las diferentes capas de la aplicación o para cumplir con las expectativas de la interfaz de usuario o las API externas. Algunos escenarios comunes donde es útil transformar datos incluyen:

Normalización de datos: Convertir los datos a un formato estándar.

  @Post()
  createUser(@Body() createUserDto: CreateUserDto) {
    const normalizedDto = {
      ...createUserDto,
      email: createUserDto.email.toLowerCase(),
    };
    return this.userService.createUser(normalizedDto);
  }

Agregar información adicional: Enriquecer los datos con información adicional requerida por los servicios.

  @Post(':orderId/items')
  addItemToOrder(
    @Param('orderId') orderId: string,
    @Body() addItemDto: AddItemDto,
  ) {
    const enhancedDto = {
      ...addItemDto,
      orderId,
    };
    return this.orderService.addItemToOrder(enhancedDto);
  }

Transformación de formatos: Cambiar el formato de los datos para cumplir con los requisitos de un servicio o API.

  @Post()
  createReport(@Body() reportDto: ReportDto) {
    const transformedDto = {
      ...reportDto,
      date: new Date(reportDto.date).toISOString(),
    };
    return this.reportService.createReport(transformedDto);
  }

3.2 Uso de pipes para transformar datos

Los pipes no solo son útiles para la validación, sino también para la transformación de datos. Puedes crear pipes personalizados que realicen transformaciones antes de que los datos lleguen al controlador.

Ejemplo de un pipe para transformar una fecha:

import { PipeTransform, Injectable, BadRequestException } from '@nestjs/common';
import { isDate, parseISO } from 'date-fns';

@Injectable()
export class ParseDatePipe implements PipeTransform<string, Date> {
  transform(value: string): Date {
    const date = parseISO(value);
    if (!isDate(date)) {
      throw new BadRequestException('Invalid date format');
    }
    return date;
  }
}

Este pipe convierte una cadena en una instancia de Date y se asegura de que sea válida.

Utilizando el pipe en un controlador:

@Post()
createEvent(@Body('date', ParseDatePipe) date: Date) {
  return this.eventService.createEvent({ date });
}

Aquí, ParseDatePipe transforma la cadena de fecha antes de que llegue al servicio eventService.

4. Validación de Sintaxis y Semántica: Garantizando un Código Robusto y Seguro

Es crucial validar tanto la sintaxis como la semántica de los datos recibidos antes de realizar cualquier operación que modifique la base de datos, como insertar o actualizar registros. Este enfoque no solo asegura la integridad de los datos, sino que también fortalece la robustez y seguridad del código.

4.1 Validación de Sintaxis con DTOs y `class-validator`

La validación de sintaxis se lleva a cabo utilizando DTOs (Data Transfer Objects) junto con el paquete class-validator. Esto garantiza que los datos cumplan con las reglas de formato y tipos de datos esperados antes de que lleguen al servicio.

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

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

  @IsInt()
  @Min(0)
  readonly age: number;

  @IsEmail()
  readonly email: string;
}

Con esta validación, cualquier dato

que no cumpla con los requisitos especificados en el DTO será rechazado automáticamente, protegiendo así la integridad del sistema.

4.2 Validación Semántica en los Servicios

La validación semántica ocurre en la capa de servicios, donde se aseguran que los datos no solo estén correctamente formateados, sino que también sean coherentes dentro del contexto de negocio.

@Injectable()
export class OrderService {
  async validateOrder(orderId: string): Promise<Order> {
    const order = await this.orderRepository.findOne(orderId);
    if (!order) {
      throw new NotFoundException(`Order with ID ${orderId} not found`);
    }

    if (order.status !== 'PENDING') {
      throw new BadRequestException('Order is not in a valid state');
    }

    return order;
  }

  async confirmOrder(order: Order): Promise<Order> {
    order.status = 'CONFIRMED';
    return this.orderRepository.save(order);
  }
}

En este ejemplo, la orden se valida tanto en términos de existencia como en el estado adecuado antes de proceder con cualquier operación, lo que evita errores y garantiza que solo se procesen datos válidos.

5. Conclusión

La combinación de la validación de sintaxis y semántica en NestJS resulta esencial para construir aplicaciones robustas y seguras. Validar los datos a través de DTOs, class-validator, y servicios no solo mejora la calidad del código, sino que también asegura que los datos procesados sean correctos y estén alineados con las reglas de negocio.

El uso de pipes personalizados para la validación y transformación de datos añade un nivel adicional de flexibilidad y control, permitiendo crear soluciones a medida que cumplen con los requisitos específicos de la aplicación.

Al seguir estas prácticas, podemos crear APIs más confiables, reducir la posibilidad de errores y asegurar que nuestra aplicación maneje los datos de manera efectiva y segura.

Validación de Datos en NestJS: De la Sintaxis a la Semántica

Juan Carlos Valderrábano Hernández — Sat, 10 Aug 2024 02:54:31 +0000

Introducción:

En el mundo del desarrollo de aplicaciones web, la validación de datos es una de las tareas más críticas. Los datos que llegan a un servidor deben ser verificados para asegurarse de que cumplen con las expectativas de la aplicación y no comprometen su funcionamiento. En NestJS, un poderoso framework basado en Node.js, la validación se puede dividir en dos etapas clave: validación de sintaxis y validación semántica. En este artículo, exploraremos cómo NestJS permite manejar ambas etapas de manera efectiva, utilizando DTOs para la sintaxis y servicios para la semántica. Además, discutiremos cómo y cuándo transformar datos en los controladores para garantizar un flujo de datos limpio y coherente.

1. Validación de Sintaxis en NestJS: Un Enfoque a Través de DTOs

La validación de sintaxis se refiere a la verificación de que los datos recibidos en una petición HTTP tienen la estructura y el formato correcto. NestJS proporciona una manera eficiente de realizar esta validación utilizando DTOs (Data Transfer Objects) y la librería class-validator. Esta etapa es crucial porque garantiza que los datos que ingresan al sistema están en el formato correcto antes de ser procesados más a fondo.

1.1 ¿Qué son los DTOs en NestJS?

Los DTOs son clases TypeScript que definen la forma esperada de los datos en las peticiones HTTP. Al definir un DTO, estás especificando explícitamente qué campos espera tu aplicación, qué tipos de datos son aceptables y qué reglas deben cumplirse. Estos DTOs actúan como una capa protectora entre el cliente y tu aplicación, asegurando que solo los datos que cumplen con las reglas establecidas lleguen a los controladores.

Ejemplo básico de DTO:

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

export class CreateUserDto {
  @IsNotEmpty()
  @IsString()
  firstName: string;

  @IsNotEmpty()
  @IsString()
  lastName: string;

  @IsNotEmpty()
  @IsEmail()
  email: string;

  @IsOptional()
  @IsString()
  phone?: string;
}

En este ejemplo, CreateUserDto define un DTO para crear un nuevo usuario. Aquí, estamos utilizando varios decoradores de class-validator:

@IsNotEmpty() asegura que el campo no sea nulo o vacío.
@IsString() verifica que el campo sea una cadena de texto.
@IsEmail() valida que el campo sea un correo electrónico válido.
@IsOptional() indica que el campo phone es opcional.

1.2 Uso de `class-validator` para validaciones complejas de sintaxis

La librería class-validator proporciona una amplia gama de decoradores para realizar validaciones de sintaxis. Algunos de los más comunes incluyen:

@IsInt(): Verifica que el valor sea un número entero.

  @IsInt()
  age: number;

@IsBoolean(): Verifica que el valor sea un booleano.

  @IsBoolean()
  isActive: boolean;

@Length(min: number, max: number): Verifica que la longitud de la cadena esté dentro de un rango específico.

  @Length(10, 20)
  username: string;

@IsArray(): Verifica que el valor sea un array.

  @IsArray()
  tags: string[];

@ArrayMinSize(size: number): Verifica que el array tenga un tamaño mínimo.

  @ArrayMinSize(1)
  tags: string[];

Validación condicional y lógica más avanzada:

class-validator también permite realizar validaciones más avanzadas utilizando decoradores como @ValidateIf() y @Matches():

@ValidateIf(condition: (obj, value) => boolean): Este decorador permite aplicar una validación solo si se cumple una cierta condición.

  @ValidateIf(o => o.isActive)
  @IsNotEmpty()
  activationDate: string;

En este caso, activationDate solo será requerido si isActive es true.

@Matches(pattern: RegExp, message?: string): Verifica que el valor coincida con una expresión regular.

  @Matches(/^[A-Z][a-z]*$/, {
    message: 'The lastName must start with an uppercase letter.',
  })
  lastName: string;

1.3 Pipes personalizados: Añadiendo validaciones de sintaxis personalizadas

Mientras que class-validator cubre la mayoría de las necesidades de validación de sintaxis, en algunos casos, es necesario aplicar validaciones más específicas o personalizadas. Aquí es donde los pipes personalizados entran en juego. Los pipes son clases que implementan la interfaz PipeTransform y pueden ser utilizados para transformar o validar datos antes de que lleguen a un controlador.

Creando un pipe personalizado para validar un enum:

Imaginemos que tenemos un enum de roles y queremos asegurarnos de que un campo en particular solo acepte valores dentro de ese enum.

import { ArgumentMetadata, BadRequestException, PipeTransform } from '@nestjs/common';

enum UserRole {
  ADMIN = 'admin',
  USER = 'user',
  GUEST = 'guest',
}

export class ParseEnumPipe implements PipeTransform {
  constructor(private readonly enumType: object) {}

  transform(value: any, metadata: ArgumentMetadata) {
    if (!Object.values(this.enumType).includes(value)) {
      throw new BadRequestException(`Invalid value: ${value}`);
    }
    return value;
  }
}

En este pipe, ParseEnumPipe valida que el valor de UserRole esté dentro de los valores permitidos en el enum. Si no es así, lanza una excepción de tipo BadRequestException.

Utilizando el pipe personalizado en un controlador:

@Post()
createUser(
  @Body('role', new ParseEnumPipe(UserRole)) role: UserRole,
  @Body() createUserDto: CreateUserDto,
) {
  return this.userService.createUser(createUserDto);
}

Aquí estamos utilizando el ParseEnumPipe para asegurarnos de que el campo role solo reciba valores válidos según el enum UserRole. Si el valor no es válido, el pipe lanzará una excepción antes de que la solicitud llegue al servicio.

2. Validación Semántica en NestJS: Más Allá de la Sintaxis

Mientras que la validación de sintaxis garantiza que los datos tienen la forma correcta, la validación semántica se centra en verificar que los datos tienen sentido en el contexto de la aplicación. Esto es crucial para mantener la integridad de la lógica de negocio y garantizar que las acciones realizadas por los usuarios estén permitidas según las reglas de la aplicación.

2.1 ¿Qué es la validación semántica?

La validación semántica se ocupa de la lógica del negocio. Verifica si los datos, aunque sean sintácticamente correctos, son semánticamente válidos. Por ejemplo, si se intenta realizar una transacción en una cuenta bancaria, la validación semántica se encargaría de verificar que la cuenta existe, que tiene suficientes fondos y que la transacción está permitida según las reglas del negocio.

Ejemplos de validación semántica:

Verificación de existencia en la base de datos:

  async validateUser(userId: string) {
    const user = await this.userRepository.findOne(userId);
    if (!user) {
      throw new NotFoundException(`User with ID ${userId} not found`);
    }
    return user;
  }

En este ejemplo, el método validateUser en un servicio verifica si un usuario con un userId específico existe en la base de datos. Si no existe, se lanza una excepción de tipo NotFoundException.

Validación de reglas de negocio:

  async validateTransaction(amount: number, accountId: string) {
    const account = await this.accountRepository.findOne(accountId);
    if (account.balance < amount) {
      throw new BadRequestException('Insufficient funds');
    }
    return true;
  }

Aquí, el método validateTransaction se asegura de que una cuenta tenga suficientes fondos antes de permitir una transacción.

2.2 Implementando validación semántica en los servicios

La validación semántica generalmente se implementa en los servicios de la aplicación. Esto permite que la lógica de negocio esté encapsulada y separada de la lógica de enrutamiento que maneja el controlador. Esto es importante para mantener el código modular, fácil de mantener y testear.

Ejemplo de un servicio con validación semántica:

@Injectable()
export class OrderService {
  constructor(private readonly orderRepository: OrderRepository) {}

  async validateOrder(orderId: string): Promise<Order> {
    const order = await this.orderRepository.findOne(orderId);
    if (!order) {
      throw new NotFoundException(`Order with ID ${orderId} not found`);
    }

    if (order.status !== 'PENDING') {
      throw new BadRequestException('Order is not in a valid state');
    }

    return order;
  }
}

En este servicio, validateOrder verifica si una orden con un orderId específico existe y está en un estado válido (PENDING). Si alguna de estas condiciones no se cumple, se lanzan excepciones apropiadas.

Utilizando la validación semántica en un controlador:

@Post(':orderId/confirm')
async confirmOrder(
  @Param('orderId') orderId: string,
) {
  const order = await this.orderService.validateOrder(orderId);
  return this.orderService.confirmOrder(order);
}

En este controlador, confirmOrder utiliza el método validateOrder para asegurarse de que la orden existe y está en un estado válido antes de proceder con la confirmación.

3. Transformación de Datos en los Controladores: Manejando los Datos para la Coherencia

3.1 ¿Por qué y cuándo transformar los datos?

Normalización de datos: Convertir los datos a un formato estándar.

  @Post()
  createUser(@Body() createUserDto: CreateUserDto) {
    const normalizedDto = {
      ...createUserDto,
      email: createUserDto.email.toLowerCase(),
    };
    return this.userService.createUser(normalizedDto);
  }

Agregar información adicional: Enriquecer los datos con información adicional requerida por los servicios.

  @Post(':orderId/items')
  addItemToOrder(
    @Param('orderId') orderId: string,
    @Body() addItemDto: AddItemDto,
  ) {
    const enhancedDto = {
      ...addItemDto,
      orderId,
    };
    return this.orderService.addItemToOrder(enhancedDto);
  }

Transformación de formatos: Cambiar el formato de los datos para cumplir con los requisitos de un servicio o API.

  @Post()
  createReport(@Body() reportDto: ReportDto) {
    const transformedDto = {
      ...reportDto,
      date: new Date(reportDto.date).toISOString(),
    };
    return this.reportService.createReport(transformedDto);
  }

3.2 Uso de pipes para transformar datos

Ejemplo de un pipe para transformar una fecha:

import { PipeTransform, Injectable, BadRequestException } from '@nestjs/common';
import { isDate, parseISO } from 'date-fns';

@Injectable()
export class ParseDatePipe implements PipeTransform<string, Date> {
  transform(value: string): Date {
    const date = parseISO(value);
    if (!isDate(date)) {
      throw new BadRequestException('Invalid date format');
    }
    return date;
  }
}

Este pipe convierte una cadena en una instancia de Date y se asegura de que sea válida.

Utilizando el pipe en un controlador:

@Post()
createEvent(@Body('date', ParseDatePipe) date: Date) {
  return this.eventService.createEvent({ date });
}

Aquí, ParseDatePipe transforma la cadena de fecha antes de que llegue al servicio eventService.

Conclusión

La validación de datos en NestJS es una práctica fundamental que garantiza la integridad y seguridad de una aplicación. A través de la validación de sintaxis con DTOs y class-validator, y la validación semántica dentro de los servicios, NestJS permite construir aplicaciones robustas y resistentes a errores. Además, el uso estratégico de pipes para la transformación de datos asegura que las diferentes capas de la aplicación se mantengan coherentes y alineadas con las necesidades del negocio. Con estas herramientas, los desarrolladores pueden crear aplicaciones que no solo funcionan correctamente, sino que también son fáciles de mantener y escalar.

Introducción a la arquitectura “EleganFlow”

Juan Carlos Valderrábano Hernández — Fri, 09 Aug 2024 01:48:10 +0000

EleganFlow: Arquitectura Modular, Robusta y Elegante

La arquitectura de software EleganFlow es un enfoque modular diseñado para aplicaciones construidas con el framework NestJS, aunque puede ser implementada en otros lenguajes y frameworks. Esta arquitectura se basa en la separación de responsabilidades en tres etapas claramente definidas: Verificación, Proceso y Presentación. Cada etapa se compone de reglas o procesos individuales que se alinean con el principio de responsabilidad única, lo que facilita la comprensión, el mantenimiento y la extensibilidad del sistema.

Justificación

En la mayoría de las aplicaciones modernas, la necesidad de mantener un código limpio, modular y fácilmente extensible es crucial. La arquitectura EleganFlow ofrece un marco estructurado donde cada componente tiene un propósito claro y se puede modificar o ampliar sin afectar otras partes del sistema. Además, el uso de principios de diseño como el principio de estrategia y responsabilidad única asegura que las reglas y procesos sean independientes, permitiendo un desarrollo más ágil y un código más robusto.

Principios

1. Principio de Responsabilidad Única

Cada regla o proceso tiene una única responsabilidad dentro de su contexto, lo que facilita su mantenimiento y comprensión.

2. Principio de Estrategia

Las reglas y procesos se implementan como estrategias independientes que pueden ser fácilmente modificadas o reemplazadas sin afectar el sistema en su totalidad.

3. Modularidad

Cada etapa del flujo (Verificación, Proceso, Presentación) es modular y funciona de manera autónoma, lo que permite una fácil integración y extensión.

4. Retroalimentación

En caso de falla en cualquier etapa, el sistema proporciona retroalimentación clara al usuario, indicando el estatus del proceso.

Estructura de la Arquitectura

Primera Etapa: Verificación

Sintaxis: Validación inicial de la estructura y tipos de datos mediante DTOs (Data Transfer Objects).
Semántica: Validación profunda basada en reglas de negocio. Cada regla es una implementación de la estrategia y se agrupan en una lista de verificación. La lista de verificación asegura que todas las reglas se cumplan antes de proceder al siguiente paso. Si alguna regla falla, se proporciona retroalimentación al usuario.

Segunda Etapa: Proceso

Process: Cada paso del procesamiento de datos se implementa como un “process” que sigue el principio de responsabilidad única. Estos procesos se agrupan en un “blueprint” que define el flujo completo de procesamiento.
Iteración y Enriquecimiento: Los procesos pueden depender de la información generada en etapas previas. Estos datos se pasan a través de un objeto común que alimenta las funciones o clases estratégicas de cada proceso.
Rollback y Retroalimentación: En caso de falla en algún proceso, se puede realizar un rollback para deshacer las acciones previas o informar al usuario sobre el estatus del proceso.

Tercera Etapa: Presentación de Datos

Transformación y Respuesta: En esta etapa se construye la respuesta final que se presentará al usuario. Puede involucrar consultas a la base de datos o simplemente formatear los resultados de las etapas previas. La función de presentación no debe generar nuevos registros en la base de datos.
Interfaz de Salida Común: Para mantener la simplicidad y consistencia en las respuestas, se utiliza una interfaz de salida común con la siguiente estructura:

{
  "ok": boolean,
  "constraints": [],
  "message": string,
  "data": object
}

Ventajas

Modularidad y Flexibilidad: La separación clara de etapas y la implementación de reglas y procesos como estrategias independientes permiten una mayor flexibilidad en el desarrollo y mantenimiento del sistema.
Claridad y Simplicidad: Cada etapa y componente tiene un propósito claro, lo que facilita la comprensión del flujo de trabajo y la depuración del código.
Reutilización: Las reglas y procesos, al ser independientes y modulares, pueden reutilizarse en diferentes partes del sistema o en otros proyectos.
Retroalimentación Clara: El sistema proporciona información detallada en caso de errores, facilitando la identificación de problemas.

Desventajas

Complejidad Inicial: La implementación de la arquitectura EleganFlow puede requerir un esfuerzo inicial considerable para definir todas las reglas, procesos y la interfaz de salida común.
Sobrecarga de Desarrollo: La necesidad de mantener la modularidad y responsabilidad única en cada componente puede resultar en un incremento de la carga de desarrollo, especialmente en proyectos más simples.
Curva de Aprendizaje: Los desarrolladores nuevos en el equipo pueden necesitar tiempo para adaptarse a esta arquitectura y comprender su funcionamiento.

Forem: Juan Carlos Valderrábano Hernández

🧠 MCP (Module Communication Protocol): El lenguaje común entre módulos y agentes

🧩 ¿Qué es MCP?

🚀 ¿Por qué es importante?

🤖 MCP + Agentes Inteligentes

Ejemplo de flujo:

📊 Comparativa: MCP vs Métodos Tradicionales

🛠️ ¿Cuándo considerar MCP?

Brújula del Propósito: Manteniendo el Rumbo con un Concepto Definido

Implementación de "EleganFlow": Arquitectura Modular y Sostenible

Introducción

¿Qué es EleganFlow?

¿Por qué EleganFlow?

Principios Clave de EleganFlow

Etapas de la Arquitectura EleganFlow

Flujo de trabajo:

2. Proceso

3. Presentación

Beneficios de EleganFlow

Conclusión

Git: Domina tus commits y evita los dolores de cabeza

Los errores más comunes en Git y cómo solucionarlos

Consejos para convertirte en un maestro de Git

👮🏻‍♂️ Enfoque en la Verificación de la Arquitectura 'EleganFlow'

Módulo de Verificación

1. Verificación de Sintaxis

2. Verificación de Semántica

Flujo de Trabajo

Interfaces y DTOs

CreatePersonDto

CreateResponseInterface

Ejemplo de Implementación

Controlador

Servicio

Validador de Reglas

Regla de Negocio

Test Unitario

Ejemplo de Prueba para el Servicio

Ventajas de la Verificación en "EleganFlow"

Conclusión

🚀 Guía para: Workshop de Introducción a la API de ChatGPT utilizando NestJS/Node.js

📍 Objetivos del Workshop

📅 Estructura del Taller

1. Introducción y Objetivos

2. Configuración Inicial

2.1 Instalación de Node.js y NestJS

2.2 Instalación de Dependencias

3. Primeros Pasos con la API en Node.js/NestJS

3.1 Integración con Axios

3.2 Realización de Solicitudes Básicas

4. Análisis de Texto y Conversaciones

4.1 Generación de Respuestas

4.2 Manejo del Contexto en Conversaciones

5. Análisis de Sentimientos

5.1 Implementación de Detección de Sentimientos

6. Aplicación Práctica: Creación de una API REST Completa

6.1 Proyecto de Ejemplo: API RESTful

6.2 Manejo de Errores y Validaciones

7. Documentación y Mejores Prácticas

7.1 Documentación de la API

8. Preguntas y Respuestas

9. Conclusión

🛠️ Recursos Adicionales

Mantén las Cosas Simples: El Poder del Principio KISS en el Desarrollo de Software

¿Qué es el Principio KISS?

La Trampa de la Sobreingeniería

¿Por Qué Mantenerlo Simple?

Conclusión

Validación de Sintaxis y Semántica en NestJS: Asegurando un Código Robusto y Seguro

1. Validación de Sintaxis con DTOs y class-validator

1.1 ¿Qué es un DTO?

1.2 Validación Automática con class-validator

1.3 Custom Pipes para Validaciones Adicionales

Ejemplo de un pipe personalizado para validar un enum:

Uso del pipe en un controlador:

2. Validación de Semántica en los Servicios: Garantizando la Coherencia del Negocio

2.1 Ejemplo de Validación Semántica en un Servicio

3. Transformación de Datos en los Controladores: Manejando los Datos para la Coherencia

3.1 ¿Por qué y cuándo transformar los datos?

3.2 Uso de pipes para transformar datos

`CreatePersonDto`

`CreateResponseInterface`

1. Validación de Sintaxis con DTOs y `class-validator`

1.2 Validación Automática con `class-validator`

4.1 Validación de Sintaxis con DTOs y `class-validator`

1.2 Uso de `class-validator` para validaciones complejas de sintaxis