9. Arquitectura en capas y acceso a datos
Los ejemplos anteriores mantenían sus datos en memoria. Una aplicación real los almacena en una base de datos y se organiza en capas (véase el diagrama de la introducción):
- la capa web (controladores, vistas): lee la solicitud, llama a la capa de negocio y selecciona la vista;
- la capa de negocio: reglas de negocio;
- la capa DAO: consultas a la base de datos.
Cada capa conoce únicamente la capa inferior y la menor cantidad posible de detalles sobre ella: la capa web desconoce la capa SQL y la capa de negocio desconoce la capa HTML. Esta separación facilita comprender, probar y hacer evolucionar cada capa. El ejemplo 28 aplica esto a la gestión de una lista de personas: es, a menor escala, la gestión de médicos y clientes del caso de estudio.
9.1. Ejemplo 28: un sistema de tres capas para gestionar personas
| 28-layers/
├── database/
│ └── dbpersons.sql
├── public/
│ ├── css/
│ │ └── styles.css
│ └── js/
│ └── app.js
├── src/
│ ├── business/
│ │ ├── business.exception.ts
│ │ └── persons.business.ts
│ ├── config/
│ │ └── database.config.ts
│ ├── dao/
│ │ └── persons.dao.ts
│ ├── entities/
│ │ └── person.entity.ts
│ ├── web/
│ │ ├── flash.ts
│ │ ├── person-form.dto.ts
│ │ ├── persons.controller.ts
│ │ └── validation.ts
│ ├── app.module.ts
│ └── main.ts
├── views/
│ ├── partials/
│ │ └── confirmation.hbs
│ ├── form.hbs
│ ├── layout.hbs
│ └── list.hbs
├── nest-cli.json
└── tsconfig.json
|
9.1.1. La base de datos
La base de datos [dbpersons] se crea mediante un script SQL. Con [Laragon], puede ejecutarse, por ejemplo, en la herramienta [HeidiSQL] (menú File / Run a SQL file), o desde la línea de comandos:
| mysql -u root < database/dbpersons.sql
|
El archivo [database/dbpersons.sql]:
| -- base de datos del ejemplo 28: una sola tabla, [persons]
DROP DATABASE IF EXISTS dbpersons;
CREATE DATABASE dbpersons CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbpersons;
CREATE TABLE persons (
id INT NOT NULL AUTO_INCREMENT,
version INT NOT NULL DEFAULT 1,
first_name VARCHAR(30) NOT NULL,
last_name VARCHAR(30) NOT NULL,
age INT NOT NULL,
PRIMARY KEY (id),
-- dos personas no pueden tener el mismo nombre y apellido
CONSTRAINT unq_persons_first_name_last_name UNIQUE (first_name, last_name)
) ENGINE = InnoDB;
INSERT INTO persons (first_name, last_name, age) VALUES
('Marie', 'Pélissier', 42),
('Jacques', 'Bromard', 35),
('Philippe', 'Jandot', 58);
|
- Línea 3: el conjunto de caracteres [utf8mb4] acepta todos los caracteres (acentos, emojis, etc.). La intercalación [utf8mb4_unicode_ci] compara las cadenas sin distinguir mayúsculas de minúsculas ni acentos: para MySQL, [pelissier] y [Pélissier] son iguales;
- línea 8: un número de versión, que se incrementa cada vez que se modifica la fila (véase «bloqueo optimista», más adelante);
- línea 14: una restricción de unicidad con nombre: la base de datos no admite dos personas con el mismo nombre y apellido. El nombre se usará para identificar el error.
9.1.2. La configuración de TypeORM
El archivo [src/config/database.config.ts]:
| import { TypeOrmModuleOptions } from '@nestjs/typeorm';
import { Person } from '../entities/person.entity';
// la conexión a la base de datos; los valores por defecto son los de Laragon
export function databaseConfig(): TypeOrmModuleOptions {
return {
type: 'mysql',
host: process.env.DB_HOST ?? 'localhost',
port: Number(process.env.DB_PORT ?? 3306),
username: process.env.DB_USERNAME ?? 'root',
password: process.env.DB_PASSWORD ?? '',
database: 'dbpersons',
entities: [Person],
// el esquema lo crea el script SQL, TypeORM nunca lo modifica
synchronize: false,
// DB_LOGGING=true: muestra las sentencias SQL enviadas a la base de datos
logging: process.env.DB_LOGGING === 'true',
};
}
|
- Líneas 8–11: parámetros de conexión, leídos de variables de entorno, con los valores predeterminados de [Laragon] (usuario [root], sin contraseña);
- línea 13: las clases que [TypeORM] asigna a tablas;
- línea 15: [TypeORM] podría crear o modificar las tablas por sí mismo a partir de las clases. Esto es cómodo para un prototipo, pero peligroso para una base de datos que contiene datos: el esquema sigue siendo responsabilidad del script SQL;
- línea 17: con la variable de entorno [DB_LOGGING=true], los comandos SQL enviados a la base de datos se muestran en la consola.
9.1.3. La entidad Person
El archivo [src/entities/person.entity.ts]:
| import { Column, Entity, PrimaryGeneratedColumn, VersionColumn } from 'typeorm';
// una fila de la tabla [persons] <-> un objeto Person
@Entity('persons')
export class Person {
@PrimaryGeneratedColumn()
id: number;
// incrementado por TypeORM en cada modificación (bloqueo optimista)
@VersionColumn()
version: number;
@Column({ name: 'first_name', length: 30 })
firstName: string;
@Column({ name: 'last_name', length: 30 })
lastName: string;
@Column()
age: number;
}
|
- Línea 4: la clase [Person] corresponde a la tabla [persons]: cada fila de la tabla será un objeto [Person];
- línea 6: la clave primaria, generada por la base de datos ([AUTO_INCREMENT]);
- Línea 10: la columna de versión, administrada por [TypeORM];
- líneas 13–20: las demás columnas.
9.1.4. La capa DAO
El archivo [src/dao/persons.dao.ts]:
| import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { EntityManager, Not, Repository } from 'typeorm';
import { Person } from '../entities/person.entity';
// la capa de ACCESO A DATOS: consultas, sin reglas de negocio
@Injectable()
export class PersonsDao {
constructor(@InjectRepository(Person) private readonly repository: Repository<Person>) {}
// dentro de una transacción, debemos pasar por el "manager" de la transacción
private repo(manager?: EntityManager): Repository<Person> {
return manager ? manager.getRepository(Person) : this.repository;
}
list(): Promise<Person[]> {
return this.repository.find({ order: { lastName: 'ASC', firstName: 'ASC' } });
}
read(id: number, manager?: EntityManager): Promise<Person | null> {
return this.repo(manager).findOneBy({ id });
}
// OTRA persona (id distinto de [exceptId]) con este nombre y apellido
namesake(firstName: string, lastName: string, exceptId: number, manager?: EntityManager): Promise<Person | null> {
return this.repo(manager).findOneBy({ firstName, lastName, id: Not(exceptId) });
}
// INSERT si la persona no tiene id, UPDATE en caso contrario
save(person: Person, manager?: EntityManager): Promise<Person> {
return this.repo(manager).save(person);
}
async delete(id: number, manager?: EntityManager): Promise<void> {
await this.repo(manager).delete(id);
}
}
|
- línea 9: [TypeORM] proporciona un repositorio ([Repository<Person>]) para cada entidad, que puede leer y escribir en la tabla. [@InjectRepository] lo inyecta;
- líneas 12–14: dentro de una transacción, todas las consultas deben pasar por el mismo objeto [EntityManager], el asociado a la transacción. Por lo tanto, cada método acepta un [manager] opcional;
- líneas 16–18: [find] con ordenamiento: [SELECT ... ORDER BY last_name, first_name];
- líneas 25–27: una persona con el mismo nombre y apellido, distinta de [exceptId] ([Not]): útil para modificar un registro, que no debe entrar en conflicto consigo mismo;
- líneas 30–32: [save] se convierte en [INSERT] si el objeto no tiene identificador, y en [UPDATE] en caso contrario.
La capa DAO no contiene reglas: solo consultas.
9.1.5. La capa de negocio
El archivo [src/business/business.exception.ts]:
| // una regla de negocio rechaza la operación: esto no es una anomalía,
// el mensaje está destinado al usuario
export class BusinessException extends Error {}
|
Una [BusinessException] indica que una regla de negocio ha rechazado una operación. No es un error del programa: el mensaje está destinado al usuario.
El archivo [src/business/persons.business.ts]:
| import { Injectable } from '@nestjs/common';
import { DataSource, EntityManager } from 'typeorm';
import { PersonsDao } from '../dao/persons.dao';
import { Person } from '../entities/person.entity';
import { BusinessException } from './business.exception';
export interface PersonData {
firstName: string;
lastName: string;
age: number;
}
// la capa de NEGOCIO: las reglas de negocio, y solo ellas
@Injectable()
export class PersonsBusiness {
constructor(
private readonly dao: PersonsDao,
private readonly dataSource: DataSource,
) {}
list(): Promise<Person[]> {
return this.dao.list();
}
async read(id: number): Promise<Person> {
const person = await this.dao.read(id);
if (!person) {
throw new BusinessException('This person does not exist (anymore).');
}
return person;
}
add(data: PersonData): Promise<Person> {
return this.transaction(async (manager) => {
// regla 1: no puede haber dos personas con el mismo nombre y apellido
if (await this.dao.namesake(data.firstName, data.lastName, 0, manager)) {
throw new BusinessException('A person already has these first and last names.');
}
const person = new Person();
person.firstName = data.firstName;
person.lastName = data.lastName;
person.age = data.age;
return this.dao.save(person, manager);
});
}
edit(id: number, version: number, data: PersonData): Promise<Person> {
return this.transaction(async (manager) => {
const person = await this.dao.read(id, manager);
if (!person) {
throw new BusinessException('This person does not exist (anymore).');
}
// regla 2: no modificamos un registro modificado entretanto por otra persona
if (person.version !== version) {
throw new BusinessException('This record has been modified meanwhile: reload it.');
}
if (await this.dao.namesake(data.firstName, data.lastName, id, manager)) {
throw new BusinessException('A person already has these first and last names.');
}
person.firstName = data.firstName;
person.lastName = data.lastName;
person.age = data.age;
return this.dao.save(person, manager);
});
}
async delete(id: number): Promise<Person> {
const person = await this.read(id);
await this.dao.delete(id);
return person;
}
// [work] se ejecuta dentro de una transacción: COMMIT si tiene éxito, ROLLBACK
// si lanza una excepción. Una violación de la restricción de unicidad (dos
// adiciones simultáneas, por ejemplo) se convierte en una BusinessException
private async transaction<R>(work: (manager: EntityManager) => Promise<R>): Promise<R> {
try {
return await this.dataSource.transaction(work);
} catch (e) {
const sqlError = e as { code?: string; message?: string };
if (sqlError.code === 'ER_DUP_ENTRY' && sqlError.message?.includes('unq_persons_first_name_last_name')) {
throw new BusinessException('A person already has these first and last names.');
}
throw e;
}
}
}
|
Analicemos este código:
- líneas 16–19: la capa de negocio utiliza el DAO y [DataSource] de [TypeORM] (la conexión a la base de datos) para abrir transacciones;
- líneas 25–31: una persona ausente es una [BusinessException];
- líneas 33–45: la adición de una persona dentro de una transacción. Regla: no puede haber dos personas con el mismo nombre y apellido. Esto se verifica antes de la operación de escritura para mostrar un mensaje claro;
- líneas 47–65: la modificación. Regla adicional: el bloqueo optimista (líneas 54–56): el formulario de modificación lleva la versión del registro tal como estaba cuando se abrió el formulario. Si cambió mientras tanto (otro usuario modificó el mismo registro), la operación se rechaza en lugar de sobrescribir silenciosamente el trabajo del usuario;
- líneas 76–86: [dataSource.transaction(work)] abre una transacción, ejecuta [work], y luego la confirma ([COMMIT]) o la revierte ([ROLLBACK]) si [work] lanza una excepción. Líneas 81–82: la comprobación previa de homónimos no siempre es suficiente: dos usuarios pueden agregar a la misma persona al mismo tiempo, y ambos pueden pasar la verificación. La restricción de unicidad de la base de datos, en cambio, no admite excepciones; el error de MySQL [ER_DUP_ENTRY], identificado por la restricción, se convierte entonces en la misma [BusinessException].
9.1.6. La capa web
El archivo [src/web/person-form.dto.ts]:
| import { Transform, Type } from 'class-transformer';
import { IsInt, IsNotEmpty, Max, MaxLength, Min } from 'class-validator';
const clean = ({ value }: { value: unknown }) => (typeof value === 'string' ? value.trim() : value);
// los campos del formulario y sus restricciones (longitudes = columnas SQL)
export class PersonFormDto {
@Transform(clean)
@IsNotEmpty({ message: 'The first name is required.' })
@MaxLength(30, { message: 'The first name must not exceed 30 characters.' })
firstName: string;
@Transform(clean)
@IsNotEmpty({ message: 'The last name is required.' })
@MaxLength(30, { message: 'The last name must not exceed 30 characters.' })
lastName: string;
@Type(() => Number)
@IsInt({ message: 'The age must be an integer.' })
@Min(0, { message: 'The age must be positive.' })
@Max(150, { message: 'The age cannot exceed 150.' })
age: number;
}
|
El formulario y sus restricciones (véase el ejemplo 19). La función [validateForm] (archivo [web/validation.ts]) es la del ejemplo 19, y [web/flash.ts] es la del ejemplo 20, complementada con un tipo de mensaje (éxito o error).
El archivo [src/web/persons.controller.ts]:
| import { Body, Controller, Get, Param, ParseIntPipe, Post, Redirect, Render, Res } from '@nestjs/common';
import { Response } from 'express';
import { BusinessException } from '../business/business.exception';
import { PersonsBusiness } from '../business/persons.business';
import { flash } from './flash';
import { PersonFormDto } from './person-form.dto';
import { validateForm } from './validation';
// la capa WEB: leer la solicitud, llamar a la capa de negocio, elegir la vista
@Controller()
export class PersonsController {
constructor(private readonly business: PersonsBusiness) {}
@Get()
@Redirect('/persons')
root(): void {}
@Get('persons')
@Render('list')
async list(): Promise<object> {
return { persons: await this.business.list() };
}
@Get('persons/add')
@Render('form')
addForm(): object {
return { title: 'Add a person', action: '/persons/add', values: {}, errors: {} };
}
@Post('persons/add')
async add(@Body() body: Record<string, string>, @Res() res: Response): Promise<void> {
const view = { title: 'Add a person', action: '/persons/add' };
const { dto, errors } = await validateForm(PersonFormDto, body);
if (Object.keys(errors).length > 0) {
res.render('form', { ...view, values: body, errors, error: 'The form contains errors.' });
return;
}
try {
const p = await this.business.add(dto);
flash(res, { type: 'success', text: `${p.firstName} ${p.lastName} has been added.` });
res.redirect('/persons');
} catch (e) {
// una regla de negocio rechazó la adición: mostramos el formulario de nuevo
if (!(e instanceof BusinessException)) throw e;
res.render('form', { ...view, values: body, errors: {}, error: e.message });
}
}
@Get('persons/:id/edit')
@Render('form')
async editForm(@Param('id', ParseIntPipe) id: number): Promise<object> {
const p = await this.business.read(id);
return { title: 'Edit a person', action: `/persons/${id}/edit`, values: p, errors: {} };
}
@Post('persons/:id/edit')
async edit(
@Param('id', ParseIntPipe) id: number,
@Body() body: Record<string, string>,
@Res() res: Response,
): Promise<void> {
const view = { title: 'Edit a person', action: `/persons/${id}/edit` };
const { dto, errors } = await validateForm(PersonFormDto, body);
if (Object.keys(errors).length > 0) {
res.render('form', { ...view, values: body, errors, error: 'The form contains errors.' });
return;
}
try {
const p = await this.business.edit(id, Number(body.version), dto);
flash(res, { type: 'success', text: `${p.firstName} ${p.lastName} has been modified.` });
res.redirect('/persons');
} catch (e) {
if (!(e instanceof BusinessException)) throw e;
res.render('form', { ...view, values: body, errors: {}, error: e.message });
}
}
@Post('persons/:id/delete')
async delete(@Param('id', ParseIntPipe) id: number, @Res() res: Response): Promise<void> {
try {
const p = await this.business.delete(id);
flash(res, { type: 'success', text: `${p.firstName} ${p.lastName} has been deleted.` });
} catch (e) {
if (!(e instanceof BusinessException)) throw e;
// no hay formulario que volver a mostrar: el error viaja también como flash
flash(res, { type: 'danger', text: e.message });
}
res.redirect('/persons');
}
}
|
Comentemos este código:
- línea 12: el controlador solo conoce la capa de negocio;
- líneas 14–16: la raíz del sitio redirige a la lista;
- líneas 18–22: una acción asíncrona: la lista se obtiene de la base de datos;
- líneas 30–47: la adición, en tres pasos: validación del formulario (errores → recarga de la página), llamada a la capa de negocio (éxito → mensaje emergente y redirección), [BusinessException] (→ recarga de la página con el mensaje al final de la página). Se vuelve a lanzar otra excepción ([throw e]): es una anomalía, que el filtro de excepciones de [NestJS] convertirá en un error 500;
- líneas 49–54: el formulario de actualización, rellenado previamente con el registro obtenido de la base de datos (incluida su versión);
- líneas 56–61: el mismo proceso que para agregar un registro; la versión devuelta por el formulario se pasa a la capa de negocio;
- líneas 78–89: la eliminación. No hay un formulario que volver a mostrar: los errores, si los hay, también se incluyen en el mensaje flash.
El archivo [src/app.module.ts]:
| import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { databaseConfig } from './config/database.config';
import { PersonsDao } from './dao/persons.dao';
import { Person } from './entities/person.entity';
import { PersonsBusiness } from './business/persons.business';
import { PersonsController } from './web/persons.controller';
@Module({
imports: [
// la conexión a la base de datos, para toda la aplicación
TypeOrmModule.forRoot(databaseConfig()),
// el Repository<T> inyectable en este módulo
TypeOrmModule.forFeature([Person]),
],
controllers: [PersonsController],
// las tres capas: web (controlador) -> negocio -> dao
providers: [PersonsBusiness, PersonsDao],
})
export class AppModule {}
|
- línea 12: la conexión a la base de datos para toda la aplicación;
- línea 14: permite inyectar el [Repository<Person>];
- línea 18: los servicios de la capa de negocio y del DAO.
El archivo [views/form.hbs]:
| <h1 class="h3">{{title}}</h1>
<form method="post" action="{{action}}" novalidate>
{{!-- la versión del registro leído, devuelta junto con la modificación --}}
<input type="hidden" name="version" value="{{values.version}}">
<div class="row g-2 mb-3">
<div class="col-sm-5">
<label class="form-label" for="firstName">First name</label>
<input class="form-control {{#if errors.firstName}}is-invalid{{/if}}" id="firstName" name="firstName"
value="{{values.firstName}}" maxlength="30" required>
{{#if errors.firstName}}<div class="invalid-feedback">{{errors.firstName}}</div>{{/if}}
</div>
<div class="col-sm-5">
<label class="form-label" for="lastName">Last name</label>
<input class="form-control {{#if errors.lastName}}is-invalid{{/if}}" id="lastName" name="lastName"
value="{{values.lastName}}" maxlength="30" required>
{{#if errors.lastName}}<div class="invalid-feedback">{{errors.lastName}}</div>{{/if}}
</div>
<div class="col-sm-2">
<label class="form-label" for="age">Age</label>
<input class="form-control {{#if errors.age}}is-invalid{{/if}}" id="age" name="age" type="number"
value="{{values.age}}" required>
{{#if errors.age}}<div class="invalid-feedback">{{errors.age}}</div>{{/if}}
</div>
</div>
<button class="btn btn-primary" type="submit">Save</button>
<a class="btn btn-link" href="/persons">Back to the list</a>
</form>
|
Línea 4: el campo oculto que lleva la versión del registro. La vista se usa para agregar y modificar registros: su título y la URL de envío ([action]) las proporciona el controlador. Las vistas [list.hbs] y [layout.hbs], junto con el script de confirmación, son las mismas que en los ejemplos 20 y 21.
9.1.7. Ejecución
Los parámetros de conexión se pasan mediante variables de entorno si los valores predeterminados no son adecuados. En [Windows] ([PowerShell]):
| $env:DB_USERNAME="root"; $env:DB_PASSWORD=""; $env:DB_LOGGING="true"; npx nest start
|
La lista:

Un formulario no válido:

Un homónimo, escrito en minúsculas y sin acentos: la regla de negocio lo detecta, porque MySQL compara según la intercalación de la base de datos:

Una adición exitosa y las órdenes SQL correspondientes ([DB_LOGGING=true]):

| query: START TRANSACTION
query: SELECT `Person`.`id` AS `Person_id`, `Person`.`version` AS `Person_version`, `Person`.`first_name` AS `Person_first_name`, `Person`.`last_name` AS `Person_last_name`, `Person`.`age` AS `Person_age` FROM `persons` `Person` WHERE ((`Person`.`first_name` = ?) AND (`Person`.`last_name` = ?) AND (`Person`.`id` != ?)) LIMIT 1 -- PARAMETERS: ["Sylvie","Durand",0]
query: INSERT INTO `persons`(`id`, `version`, `first_name`, `last_name`, `age`) VALUES (DEFAULT, 1, ?, ?, ?) -- PARAMETERS: ["Sylvie","Durand",29]
query: SELECT `Person`.`id` AS `Person_id`, `Person`.`version` AS `Person_version` FROM `persons` `Person` WHERE `Person`.`id` = ? -- PARAMETERS: [4]
query: COMMIT
query: SELECT `Person`.`id` AS `Person_id`, `Person`.`version` AS `Person_version`, `Person`.`first_name` AS `Person_first_name`, `Person`.`last_name` AS `Person_last_name`, `Person`.`age` AS `Person_age` FROM `persons` `Person` ORDER BY `Person`.`last_name` ASC, `Person`.`first_name` ASC
|
Se observa la transacción ([START TRANSACTION] ... [COMMIT]), la búsqueda de duplicados, la inserción con la versión 1 y, tras la redirección, la lectura de la lista. El bloqueo optimista: dos formularios están abiertos sobre el mismo registro; el primero se guarda (la versión pasa a 2); el segundo, que todavía tiene la versión 1, es rechazado:

Eliminación, con confirmación:

