Tema 1 · Arquitectura Limpia

1. Arquitectura en Capas: Controller, Service y Data Access Repository

Estructura proyectos escalables separando responsabilidades: controladores del ciclo HTTP, servicios con lógica de negocio pura y repositorios de persistencia desacoplados.

El Patrón Controller-Service-Repository en Express.js

A medida que una API de Express crece, colocar la lógica de negocio, consultas SQL y respuestas HTTP en un único manejador de ruta resulta en código monolítico e intesteable. La arquitectura por capas separa cada responsabilidad en un componente aislado y reutilizable.

Arquitectura en Capas de Express.js

Figura 1.1: Flujo unidireccional de datos entre Router, Middlewares, Controller, Service y Repository.

1. Responsabilidades de Cada Capa

Capa Rol Principal ¿Conoce a Express (req, res)? Ejemplo de Tarea
Router & Middlewares Mapeo de URL/método HTTP, autenticación, rate limiting y validación de esquemas Zod. Sí router.post('/usuarios', validate(createUserSchema), userController.create)
Controller Orquestador del protocolo HTTP: extrae parámetros de req.body/req.params, invoca al Service y devuelve códigos de estado (201, 200, 400). Sí const user = await userService.register(req.body); res.status(201).json(user);
Service Reglas de negocio puras, cálculos, llamadas a pasarelas de pago, envío de correos y orquestación de operaciones. No (Agnóstico a HTTP) Verificar si el email ya existe, hashear la contraseña y disparar evento de bienvenida.
Repository Acceso a la persistencia (PostgreSQL, MySQL, Redis, MongoDB). Consultas SQL nativas o mediante ORM/Query Builder. No (Agnóstico a HTTP) pool.query('SELECT * FROM users WHERE email = $1', [email])
Principio de Inversión de Dependencias y Testeabilidad

Al mantener el Service y el Repository completamente libres de objetos de Express (req, res, next), puedes testear toda la lógica crítica de tu negocio mediante pruebas unitarias rápidas con Vitest o Jest sin necesidad de mockear peticiones HTTP.

⚡ Estructura en Capas para Registro de Usuarios (ES Modules)

Implementación limpia de Controller, Service y Repository en Node.js con Express.

userModule.js
Solo lectura
// ==========================================
// 1. REPOSITORY (persistencia en base de datos)
// ==========================================
export class UserRepository {
  constructor(dbPool) {
    this.pool = dbPool;
  }

  async findByEmail(email) {
    const { rows } = await this.pool.query(
      'SELECT id, nombre, email, password_hash, rol FROM usuarios WHERE email = $1',
      [email]
    );
    return rows[0] || null;
  }

  async create({ nombre, email, passwordHash }) {
    const { rows } = await this.pool.query(
      `INSERT INTO usuarios (nombre, email, password_hash, rol)
       VALUES ($1, $2, $3, 'cliente')
       RETURNING id, nombre, email, rol, created_at`,
      [nombre, email, passwordHash]
    );
    return rows[0];
  }
}

// ==========================================
// 2. SERVICE (reglas de negocio puras)
// ==========================================
import bcrypt from 'bcrypt';

export class UserService {
  constructor(userRepository) {
    this.userRepo = userRepository;
  }

  async register({ nombre, email, password }) {
    // Regla de negocio: unicidad de email
    const existing = await this.userRepo.findByEmail(email);
    if (existing) {
      const err = new Error('El correo electrónico ya se encuentra registrado.');
      err.statusCode = 409;
      throw err;
    }

    // Hash criptográfico con factor de coste 12
    const passwordHash = await bcrypt.hash(password, 12);

    // Persistir y retornar DTO público (sin exponer hash)
    return await this.userRepo.create({ nombre, email, passwordHash });
  }
}

// ==========================================
// 3. CONTROLLER (gestión del ciclo HTTP)
// ==========================================
export class UserController {
  constructor(userService) {
    this.service = userService;
  }

  create = async (req, res, next) => {
    try {
      const { nombre, email, password } = req.body;
      const newUser = await this.service.register({ nombre, email, password });
      
      return res.status(201).json({
        success: true,
        data: newUser,
        message: 'Usuario registrado exitosamente.'
      });
    } catch (error) {
      next(error); // Pasa el error al middleware global de excepciones
    }
  };
}
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Cuál de las siguientes afirmaciones describe mejor la responsabilidad de la capa de Servicio (Service) en una arquitectura limpia con Express.js?
🦉
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.

🚀 ¿Quieres dominar Express.js: Framework Backend & APIs Empresariales 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.