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.
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.
// ==========================================
// 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¿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.