Skip to content

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]:

1
2
3
// 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:

Image

Um formulário inválido:

Image

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:

Image

Uma inclusão bem-sucedida e os comandos SQL correspondentes ([DB_LOGGING=true]):

Image

1
2
3
4
5
6
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:

Image

Exclusão, com confirmação:

Image

Image