9. Arquitetura em camadas e acesso a dados
Os exemplos anteriores mantinham seus dados na memória. Uma aplicação real os armazena em um banco de dados e é organizada em camadas (veja o diagrama na introdução):
- a camada web (controllers, views): lê a requisição, chama a camada de negócio e seleciona a view;
- a camada de negócio: regras de negócio;
- a camada DAO: consultas ao banco de dados.
Cada camada conhece apenas a camada imediatamente abaixo dela, e o mínimo possível de detalhes sobre ela: a camada web desconhece o SQL, e a camada de negócio desconhece o HTML. Essa separação torna cada camada mais fácil de entender, testar e evoluir. O Exemplo 28 aplica isso ao gerenciamento de uma lista de pessoas: é, em escala menor, o gerenciamento de médicos e clientes do estudo de caso.
9.1. Exemplo 28: um sistema de três camadas para gerenciar pessoas
| 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. O banco de dados
O banco de dados [dbpersons] é criado por um script SQL. Com o [Laragon], ele pode ser executado, por exemplo, na ferramenta [HeidiSQL] (menu File / Run a SQL file) ou pela linha de comando:
| mysql -u root < database/dbpersons.sql
|
O arquivo [database/dbpersons.sql]:
| -- banco de dados do exemplo 28: uma única tabela, [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),
-- duas pessoas não podem ter o mesmo nome e sobrenome
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);
|
- Linha 3: o conjunto de caracteres [utf8mb4] aceita todos os caracteres (acentos, emojis etc.). A collation [utf8mb4_unicode_ci] compara strings sem diferenciar maiúsculas de minúsculas nem acentos: para o MySQL, [pelissier], e [Pélissier] são iguais;
- linha 8: um número de versão, incrementado a cada modificação da linha (veja “bloqueio otimista”, adiante);
- linha 14: uma restrição de unicidade nomeada: o banco de dados não admite duas pessoas com o mesmo nome e sobrenome. O nome será usado para identificar o erro.
9.1.2. A configuração do TypeORM
O arquivo [src/config/database.config.ts]:
| import { TypeOrmModuleOptions } from '@nestjs/typeorm';
import { Person } from '../entities/person.entity';
// a conexão com o banco de dados; os valores padrão são os do 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],
// o schema é criado pelo script SQL, nunca modificado pelo TypeORM
synchronize: false,
// DB_LOGGING=true: exibe os comandos SQL enviados ao banco de dados
logging: process.env.DB_LOGGING === 'true',
};
}
|
- Linhas 8–11: parâmetros de conexão, lidos de variáveis de ambiente, com os valores padrão do [Laragon] (usuário [root], sem senha);
- linha 13: as classes que o [TypeORM] mapeia para tabelas;
- linha 15: o [TypeORM] poderia criar ou modificar as tabelas por conta própria a partir das classes. Isso é conveniente para um protótipo, mas perigoso para um banco de dados que contém dados: o esquema continua sendo responsabilidade do script SQL;
- linha 17: com a variável de ambiente [DB_LOGGING=true], os comandos SQL enviados ao banco de dados são exibidos no console.
9.1.3. A entidade Person
O arquivo [src/entities/person.entity.ts]:
| import { Column, Entity, PrimaryGeneratedColumn, VersionColumn } from 'typeorm';
// uma linha da tabela [persons] <-> um objeto Person
@Entity('persons')
export class Person {
@PrimaryGeneratedColumn()
id: number;
// incrementado pelo TypeORM a cada modificação (bloqueio otimista)
@VersionColumn()
version: number;
@Column({ name: 'first_name', length: 30 })
firstName: string;
@Column({ name: 'last_name', length: 30 })
lastName: string;
@Column()
age: number;
}
|
- Linha 4: a classe [Person] corresponde à tabela [persons]: cada linha da tabela será um objeto [Person];
- linha 6: a chave primária, gerada pelo banco de dados ([AUTO_INCREMENT]);
- Linha 10: a coluna de versão, gerenciada pelo [TypeORM];
- linhas 13–20: as demais colunas.
9.1.4. A camada DAO
O arquivo [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';
// a camada de ACESSO A DADOS: consultas, sem regras de negócio
@Injectable()
export class PersonsDao {
constructor(@InjectRepository(Person) private readonly repository: Repository<Person>) {}
// dentro de uma transação, devemos passar pelo "manager" da transação
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 });
}
// OUTRA pessoa (id diferente de [exceptId]) com este nome e sobrenome
namesake(firstName: string, lastName: string, exceptId: number, manager?: EntityManager): Promise<Person | null> {
return this.repo(manager).findOneBy({ firstName, lastName, id: Not(exceptId) });
}
// INSERT se a pessoa não tem id, UPDATE caso contrário
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);
}
}
|
- linha 9: o [TypeORM] fornece um repositório ([Repository<Person>]) para cada entidade, capaz de ler e gravar na tabela. [@InjectRepository] o injeta;
- linhas 12–14: dentro de uma transação, todas as consultas devem passar pelo mesmo objeto [EntityManager], o associado à transação. Cada método aceita, portanto, um [manager] opcional;
- linhas 16–18: [find] com ordenação: [SELECT ... ORDER BY last_name, first_name];
- linhas 25–27: uma pessoa com o mesmo nome e sobrenome, diferente de [exceptId] ([Not]): útil para modificar um registro, que não deve entrar em conflito consigo mesmo;
- linhas 30–32: [save] vira [INSERT] se o objeto não tem identificador e [UPDATE] caso contrário.
A camada DAO não contém regras: apenas consultas.
9.1.5. A camada de negócio
O arquivo [src/business/business.exception.ts]:
| // uma regra de negócio rejeita a operação: isto não é uma anomalia,
// a mensagem é destinada ao usuário
export class BusinessException extends Error {}
|
Uma [BusinessException] indica que uma regra de negócio rejeitou uma operação. Não se trata de um erro de programa: a mensagem se destina ao usuário.
O arquivo [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;
}
// a camada de NEGÓCIO: as regras de negócio, e somente elas
@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) => {
// regra 1: duas pessoas não podem ter o mesmo nome e sobrenome
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).');
}
// regra 2: não modificamos um registro modificado nesse meio tempo por outra pessoa
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] executa dentro de uma transação: COMMIT se tiver sucesso, ROLLBACK
// se lançar uma exceção. Uma violação da restrição de unicidade (duas
// inclusões simultâneas, por exemplo) vira uma 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;
}
}
}
|
Vamos analisar este código:
- linhas 16–19: a camada de negócio usa o DAO e o [DataSource] do [TypeORM] (a conexão com o banco de dados) para abrir transações;
- linhas 25–31: uma pessoa inexistente é uma [BusinessException];
- linhas 33–45: inclusão de uma pessoa dentro de uma transação. Regra: não pode haver duas pessoas com o mesmo nome e sobrenome. Isso é verificado antes da operação de gravação, para exibir uma mensagem clara;
- linhas 47–65: modificação. Regra adicional: o bloqueio otimista (linhas 54–56): o formulário de modificação carrega a versão do registro tal como estava quando o formulário foi aberto. Se ela mudou nesse meio-tempo (outro usuário modificou o mesmo registro), a operação é rejeitada, em vez de sobrescrever silenciosamente o trabalho do usuário;
- linhas 76–86: [dataSource.transaction(work)] abre uma transação, executa [work], depois a confirma ([COMMIT]) ou a desfaz ([ROLLBACK]) se [work] lançar uma exceção. Linhas 81–82: a verificação prévia de homônimos nem sempre é suficiente: dois usuários podem adicionar a mesma pessoa ao mesmo tempo, e ambos podem passar na verificação. A restrição de unicidade do banco de dados, porém, não admite exceções; o erro do MySQL [ER_DUP_ENTRY], identificado pela restrição, torna-se então a mesma [BusinessException].
9.1.6. A camada web
O arquivo [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);
// os campos do formulário e suas restrições (comprimentos = colunas 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;
}
|
O formulário e suas restrições (veja o Exemplo 19). A função [validateForm] (arquivo [web/validation.ts]) é a do Exemplo 19, e [web/flash.ts] é a do Exemplo 20, acrescida de um tipo de mensagem (sucesso ou erro).
O arquivo [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';
// a camada WEB: ler a requisição, chamar a camada de negócio, escolher a view
@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) {
// uma regra de negócio rejeitou a inclusão: exibimos o formulário novamente
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;
// nenhum formulário a reexibir: o erro viaja também como flash
flash(res, { type: 'danger', text: e.message });
}
res.redirect('/persons');
}
}
|
Vamos comentar este código:
- linha 12: o controller conhece apenas a camada de negócio;
- linhas 14–16: a raiz do site redireciona para a lista;
- linhas 18–22: uma action assíncrona: a lista é obtida do banco de dados;
- linhas 30–47: a inclusão, em três etapas: validação do formulário (erros → a página é recarregada), chamada à camada de negócio (sucesso → mensagem pop-up e redirecionamento), [BusinessException] (→ a página é recarregada com a mensagem na parte inferior). Qualquer outra exceção é relançada ([throw e]): trata-se de uma anomalia, que o filtro de exceção do [NestJS] converterá em um erro 500;
- linhas 49–54: o formulário de alteração, preenchido com o registro obtido do banco de dados (incluindo sua versão);
- linhas 56–61: mesmo processo da inclusão; a versão devolvida pelo formulário é passada à camada de negócio;
- linhas 78–89: exclusão. Não há formulário a exibir novamente: os eventuais erros também são incluídos na mensagem flash.
O arquivo [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: [
// a conexão com o banco de dados, para toda a aplicação
TypeOrmModule.forRoot(databaseConfig()),
// o Repository<T> injetável neste módulo
TypeOrmModule.forFeature([Person]),
],
controllers: [PersonsController],
// as três camadas: web (controller) -> negócio -> dao
providers: [PersonsBusiness, PersonsDao],
})
export class AppModule {}
|
- linha 12: a conexão com o banco de dados para toda a aplicação;
- linha 14: permite que o [Repository<Person>] seja injetado;
- linha 18: os serviços da camada de negócio e o DAO.
O arquivo [views/form.hbs]:
| <h1 class="h3">{{title}}</h1>
<form method="post" action="{{action}}" novalidate>
{{!-- a versão do registro lido, reenviada junto com a modificação --}}
<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>
|
Linha 4: o campo oculto que carrega a versão do registro. A view é usada para incluir e modificar registros: seu título e a URL de envio ([action]) são fornecidos pelo controller. As views [list.hbs] e [layout.hbs], assim como o script de confirmação, são as mesmas dos Exemplos 20 e 21.
9.1.7. Execução
Os parâmetros de conexão são passados por variáveis de ambiente se os valores padrão não forem adequados. No [Windows] ([PowerShell]):
| $env:DB_USERNAME="root"; $env:DB_PASSWORD=""; $env:DB_LOGGING="true"; npx nest start
|
A lista:

Um formulário inválido:

Um homônimo, escrito em minúsculas e sem acentos: a regra de negócio o detecta, porque o MySQL compara com base na collation do banco de dados:

Uma inclusão bem-sucedida e os comandos SQL correspondentes ([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
|
Vemos a transação ([START TRANSACTION] ... [COMMIT]), a busca por duplicatas, a inserção com a versão 1 e, depois do redirecionamento, a leitura da lista. O bloqueio otimista: dois formulários estão abertos sobre o mesmo registro; o primeiro é salvo (a versão passa a 2); o segundo, que ainda tem a versão 1, é rejeitado:

Exclusão, com confirmação:

