DEV Community: Erandir Junior

8 Lições sobre microsserviços que todo desenvolvedor precisa saber

Erandir Junior — Tue, 20 Jan 2026 12:50:58 +0000

1 – Não seja extremista

Temos a mania — e até um sonho inalcançável — de encontrar um padrão que resolva 100% dos nossos problemas. Com arquitetura de software, isso não é diferente.

O ponto aqui é simples: você não precisa adotar um padrão e morrer abraçado com ele. Seu sistema não precisa ser apenas um monolito ou exclusivamente composto por microsserviços.

A realidade do mercado mostra que, na maioria dos casos, existe uma mescla dessas arquiteturas, justamente para extrair o melhor que cada uma pode oferecer.

2 – Alinhamento estrutural

Empresa e equipe precisam estar alinhadas em relação às linguagens, ferramentas e diretrizes técnicas.

Um dos problemas que microsserviços podem causar é a mistura descontrolada de tecnologias. Imagine uma empresa sem padrões bem definidos: um desenvolvedor cria um microsserviço em uma linguagem X, outro cria outro serviço na linguagem Y, e assim por diante.
Quando se percebe, pode ser tarde demais. Surgem problemas como:

Apenas uma pessoa domina determinado sistema;
Sistemas sem suporte porque ninguém conhece a linguagem usada;
Falta de controle e governança técnica.

Microsserviços exigem maturidade organizacional, não apenas técnica.

3 – Reutilização é um benefício

Um ponto que considero extremamente benéfico é a reutilização de sistemas.

Um exemplo simples seria um microsserviço responsável por validar CPF e CNPJ em bases governamentais. Esse mesmo serviço poderia ser reutilizado:

No cadastro de clientes;
No RH, para validar dados de funcionários;
No setor de compras, para verificar dados de fornecedores.

Constrói-se uma única aplicação que passa a ser utilizada por diversos outros sistemas, aumentando o retorno sobre o investimento.

4 – A importância da documentação

Se documentação já é importante em qualquer arquitetura, em microsserviços ela se torna crítica.

Quando um microsserviço tem seus campos de entrada ou saída alterados e a documentação não acompanha essas mudanças, seu uso se torna extremamente difícil. O que deveria ser simples pode virar uma grande dor de cabeça.

Sem documentação confiável e contratos bem definidos, microsserviços rapidamente se tornam inviáveis.

5 – Testar é difícil

Em um monolito, os testes tendem a ser mais práticos, pois todo o código está no mesmo contexto. Comportamentos inesperados são mais fáceis de identificar.

Em microsserviços, a complexidade aumenta. É necessário:

Testar cada serviço isoladamente;
Testar a comunicação entre eles;
Testar o fluxo completo de ponta a ponta.

Isso dá trabalho. Por isso, logs, métricas e monitoramento deixam de ser opcionais e passam a ser essenciais.

6 – Isolamento de recursos

Um dos problemas que microsserviços ajudam a resolver é o consumo desigual de recursos.

Imagine uma aplicação onde apenas uma funcionalidade consome muitos recursos. Em um monolito, pode ser necessário aumentar os recursos de toda a aplicação. Já com microsserviços, é possível isolar essa funcionalidade em um serviço separado e alocar apenas os recursos necessários.
Além disso, esse isolamento permite:

Atualizar versões de linguagem de forma incremental;
Usar tecnologias mais adequadas para problemas específicos;
Evoluir sistemas legados aos poucos, sem reescrever tudo de uma vez.

7 – Evolução é algo natural

Muito se fala que, para adotar microsserviços, é necessário ter contextos muito bem definidos. Em parte, isso é verdade. Porém, no mundo real, dificilmente começamos um projeto com tudo perfeitamente mapeado.

Muitas empresas iniciam sistemas com escopo incompleto, regras de negócio ainda em construção e diversos pontos em aberto. Nesse cenário, é comum adotar um padrão sem saber exatamente se ele será o mais adequado no longo prazo.

Na minha experiência, ter tudo bem definido ajuda muito, mas não deve ser visto como um impeditivo para o uso de microsserviços. Com o passar do tempo, contextos mudam: um microsserviço pode ser dividido em outros, crescer, ser unificado ou até abandonado.

Arquitetura é algo vivo. O sistema naturalmente cresce e evolui junto com o negócio.

8 – De solução a problema (e vice-versa)

Os pontos anteriores mostram que microsserviços têm prós e contras. A adoção dessa arquitetura é, inevitavelmente, um depende, ou seja, uma decisão contextual.

Cada aplicação precisa ser analisada individualmente. Um exemplo famoso é o da Amazon Prime Video, que em um determinado contexto acabou migrando de microsserviços para um monólito.

Falando em experiência própria, um projeto do qual participo tem sua arquitetura totalmente baseada em microsserviços. As funcionalidades operam de forma independente, o que aumenta a resiliência: se um serviço falha, as demais partes continuam funcionando, reduzindo o impacto do problema. Ao mesmo tempo, posso afirmar que a equipe enfrentou vários dos desafios e problemas listados neste artigo.

No fim, microsserviços não são um objetivo em si, mas uma ferramenta. Usados no contexto errado, podem virar um grande problema. Usados corretamente, podem ser uma excelente solução.

Clean architecture: problema ou solução?

Erandir Junior — Tue, 22 Jul 2025 16:54:43 +0000

Arquitetura é sempre um assunto muito discutido no ramo do desenvolvimento de software, pois uma escolha ruim, pode não só afetar e dificultar a manutenibilidade de um sistema, como acabar com sua utilização.

E dentre as diversas escolhas arquiteturais para se aplicar em um software, uma que fica entre as mais debatidas é a Clean Architeture. Seu uso e entendimento é motivo de inúmeras discussões até hoje, e para tentar desmistificar, ajudar, simplificar ou mesmo piorar seu entendimento, escrevo este artigo.

O que é arquitetura (limpa)?

Antes de mais nada, precisamos entender/definir o que é uma arquitetura no ramo do desenvolvimento, que para mim, nada mais é do que a definição de como os componentes - as partes do seu software - são organizadas, e como elas se comunicam entre si.

Para ficar mais fácil, pesquisem no google sobre plantas de casa, e coloquem em imagens, você verá inúmeros desenhos diferentes de como os cômodos se adequam para trazer espaço, conforto, beleza, praticidade e etc. No mundo do desenvolvimento é a mesma coisa, construímos partes do sistema de modo que facilitem seu entendimento, teste, implementação e etc.

Já sobre a Clean Architecture, temos uma arquitetura em camadas, isso quer dizer temos partes (camadas) que tratam de responsabilidades específicas. Uncle Bob a dividiu basicamente em 4, que são:

Frameworks and Drivers -> aqui ficam por exemplo: o banco de dados, serviços externos, a "web" e por aí vai.
Interface Adapters -> é onde são adaptados os dados externos para as camadas internas e vice-versa.
Use Cases -> contém as regras da aplicação, manipulam nossas entidades, orquestram o fluxo do sistema.
Entities -> a camada mais interna, encapsula as regras de negócio.

Algo importante a ser destacado é: as camadas mais externas devem depender das mais internas e não o contrário, ou seja, uma alteração em alguma lógica na camada de use case, por exemplo, não deveria impactar na camada de entities, mas o inverso possivelmente seria verdadeiro.

Entendendo na prática

Vamos entender o uso dessa arquitetura desenvolvendo um cálculo de salário, da entrada até a saída dos dados. Não serei tão fiel à realidade, pois um código assim leva muitas variáveis, tentarei ser o mais claro possível.

<?php

class SalerSalary
{
    // Começando pela parte mais complexa do nosso sistema
    // temos um método que recebe um objeto do tipo Employee
    // e um inteiro contendo o número total de vendas
    // com esses parâmetros podemos fazer alguma lógica para retornar
    // o salário final de um vendedor
    public function calculate(Employee $employee, int $saleAmount): float
    {
        // Basicamente se o número de vendas atingir um determinado valor
        // adicionamos um valor a mais no salário
        if ($saleAmount > 50) {
            return $employee->salary + 500;
        }


        if ($saleAmount > 20) {
            return $employee->salary + 100;
        }

        return $employee->salary;
    }
}

<?php

class Employee
{
    // O objeto Employee contém basicamente as informações de um funcionário
    public function __construct(
        public string $name,
        public string $id,
        public string $position,
        public float $salary
    )
    {
    }
}


<?php
class CalculateSalerSalary
{
    // Em um nível mais acima, temos o objeto que manipula nosso fluxo
    public function __construct(private IEmployee $iEmployee)
    {
    }

    public function calculate(string $id): EmployeeSalaryDto
    {
        // Primeiro precisamos obter o funcionário
        $employee = $this->iEmployee->getEmployee($id);

        // Depois pegamos a quantidade de vendas
        $saleAmount = $this->iEmployee->saleAmount($employee);

        // Com base nos dados acima, podemos fazer o cálculo
        $salerSalary = new SalerSalary();
        $finalSalary = $salerSalary->calculate($employee, $saleAmount);

        // Retornamos um outro objeto contendo tudo
        return new EmployeeSalaryDto(
            $employee->name,
            $employee->id,
            $employee->position,
            $employee->salary,
            $saleAmount,
            $finalSalary
        );
    }
}

<?php

// Objeto de transferência de dados
class EmployeeSalaryDto
{
    public function __construct(
        public string $name,
        public string $id,
        public string $position,
        public float $baseSalary,
        public int $saleAmount,
        public float $finalSalary
    )
    {
    }
}

<?php

// Dependência do nosso use case CalculateSalerSalary
interface IEmployee
{
    public function getEmployee(string $id): Employee;

    public function saleAmount(Employee $employee): int;
}

<?php

class EmployeeSalaryController
{
    // Se usarmos um framework qualquer, os valores
    // do construtor seriam preenchidos por alguma
    // biblioteca de injeção de dependência.
    public function __construct(
        private CalculateSalerSalary $calculateSalerSalary,
        private EmployeeSalaryResponse $employeeSalaryResponse
    )
    {
    }

    // Temos a porta de entrada do nosso sistema
    public function getEmployeeSalary(string $id)
    {
        return $this->employeeSalaryResponse->response(
            $this->calculateSalerSalary->calculate($id)
        );
    }
}

<?php

// Implementamos as dependências da camada mais interna
class EmployeeImpl implements IEmployee
{
    // Em uma implementação real, consultaríamos os dados
    // de um banco de dados qualquer
    public function getEmployee(string $id): Employee
    {
        return new Employee('Fulano', 1234, 'Saler', 2000.00);
    }

    public function saleAmount(Employee $employee): int
    {
        return 25;
    }
}

<?php

// Temos um objeto que adapta o retorno da camada mais interna para a mais externa
// neste caso retornamos um json, mas podia ser um xml, gravar em um arquivo, etc.
class EmployeeSalaryResponse
{
    public function response(EmployeeSalaryDto $employeeSalaryDto)
    {
        return \json_encode([
            'id' => $employeeSalaryDto->id,
            'name' => $employeeSalaryDto->name,
            'position' => $employeeSalaryDto->position,
            'base_salary' => $employeeSalaryDto->baseSalary,
            'sale_amount' => $employeeSalaryDto->saleAmount,
            'final_salary' => $employeeSalaryDto->finalSalary,
        ]);
    }
}

Posso informar que independente de como as classes estão organizadas, respeitamos os conceitos da Clean Architecture, mas que, para facilitar a leitura e o entendimento de cada parte, podemos reorganizar o sistema, distribuindo os arquivos em diretórios com o mesmo nome das camadas, isso não é uma regra.

Nosso fluxo fica basicamente o seguinte: Temos a entrada de dados pelo EmployeeSalaryController, que adapta essa entrada para a camada mais interna, essa camada interna solicita mais informações, que ela não sabe de onde vem, com essas informações, envia para uma camada ainda mais interna, que processa tudo isso e retorna um valor para a camada anterior, até voltar para a EmployeeSalaryController, que com esses dados, adapta para uma camada ainda mais externa.

Essa abstração nos possibilita fazer a troca de partes do sistema que não afetariam uma camada mais interna. Por exemplo, se pegarmos a classe EmployeeImpl, que é responsável por retornar alguns dados vindos do banco, poderíamos substituir por uma consulta a outro sistema, e ainda assim teríamos um sistema em pleno funcionamento e o impacto dessa mudança seria sentida apenas nessa classe.

Outro caso seria do nosso EmployeeSalaryResponse, estamos pegando os dados e convertendo para json, possivelmente esse código funcionaria para uma requisição web, mas poderíamos salvar os dados em um arquivo ou mesmo exibir no prompt. No fim das contas temos um sistema desacoplado.

Já na camada de Entities, a mais interna do sistema, encontramos a classe SalerSalary, responsável pelo cálculo de salário de um vendedor. Essa classe está onde está, pois sua responsabilidade é crucial para o negócio, temos uma lógica isolada, que reflete uma regra de negócio e reutilizável. Podemos fazer uso dela para gerar um relatório atual ou final, simular um possível aumento salarial, ou algo do tipo.

Atrapalhando um sistema

No exemplo anterior, temos um sistema complexo de forma simplificada, onde conseguimos aplicar os conceitos da arquitetura limpa, dividindo nosso sistema, abstraindo funcionalidades, tornando-o mais fácil de manter.

Por outro lado, podemos acabar com nosso sistema utilizando os mesmo conceitos, para isto, basta pegar algo muito simples e complicar. No exemplo a seguir, irei realizar um cadastro de usuário, "forçando" - digamos assim - a seguir os conceitos da Clean Architecture:

<?php

class User
{
    public function __construct(
        public string $name,
        public string $email,
    )
    {
        $this->validateName();
    }

    private function validateName()
    {
        // Lançamos uma exceção se o tamanho do atributo name
        // for menor que 3 caracteres
        if (strlen($this->name) < 3) {
            throw new DomainException('Nome deve ter pelo menos 3 caracteres');
        }
    }
}

<?php

class UserRegister
{
    public function __construct(private IUser $IUser)
    {
    }

    public function register(UserDto $userDto): UserDto
    {
        $user = new User($userDto->name, $userDto->email);
        // Lançamos uma exceção se o e-mail
        // já estiver cadastrado na base
        if ($this->IUser->hasEmail($user->email)) {
            throw new LogicException('E-mail já existe no sistema.');
        }

        $this->IUser->save($user);
    }
}

<?php

class UserDto
{
    public function __construct(
        public string $name,
        public string $email
    )
    {
    }
}

<?php

interface IUser
{
    public function hasEmail(string $id): User;

    public function save(User $user): void;
}

<?php

class UserImpl implements IUser
{
    public function hasEmail(string $id): User
    {
        return false;
    }

    public function save(User $user): void
    {
        return;
    }
}

<?php

class UserController
{
    public function __construct(
        private UserRegister $userRegister,
    )
    {
    }

    public function save(string $name, string $email)
    {
        return $this->userRegister->register(
            new UserDto($name, $email)
        );
    }
}

Nesse exemplo, deixo alguns questionamentos: valeria a pena fazer toda essa separação de lógica? Vale a pena seguir a Clean Architecture para esse caso? Para mim, a resposta é não. E a razão para isso é que este exemplo é muito básico, é um contexto muito simples. Você pode duvidar de mim, mas vou te provar que posso fazer a mesma coisa de maneira mais simples.

A seguir, farei o mesmo exemplo utilizando o framework Laravel. Nesse contexto em específico, os recursos contidos no Laravel vão facilitar mais o desenvolvimento.

<?php

use Illuminate\Foundation\Http\FormRequest;

// Classe responsável por fazer a validação dos campos enviados na requisição
class UserRequest extends FormRequest
{
    /**
     * Determine if the user is authorized to make this request.
     */
    public function authorize(): bool
    {
        return true;
    }

    /**
     * Get the validation rules that apply to the request.
     *
     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array|string>
     */
    public function rules(): array
    {
        // Aqui vão as regras de validação dos campos
        return [
            // O campo name é obrigatório e deve ter pelo menos 3 caracteres
            'name' => 'required|min:3',
            // O campo email é obrigatório, deve ser um e-mail válido e não deve existir na tabela de usuários no campo email
            'email' => 'required|email|unique:App\\Models\\User,email',
        ];
    }
    public function messages()
    {
        // Aqui são as mensagens para caso os campos caiam em alguma validação
        return [
            'name.required' => "O campo name é obrigatório.",
            'name.min' => "O campo name deve ter no minímo 3 caracteres.",
            'email.required' => "O campo email é obrigatório.",
            'email.email' => "O campo email deve ser um número.",
            'email.exists' => "O campo email já existe no sistema.",
        ];
    }
}

<?php

class UserController
{
    // Quando eu bater na rota de criação, o sistema irá executar esse
    // método, o framework por meio de seu injetor de dependência é
    // inteligente o suficiente para injetar os parâmetros necessários
    public function save(UserRequest $request)
    {
        // se o código chegar até aqui, significa que já passou da validação
        // aqui basicamente estou salvando os dados no banco
        App\Models\User::create([
            'name' => $request->name,
            'email' => $request->email
        ]);
    }
}

Basicamente eu fiz a mesma coisa, porém com os recursos fornecidos pela ferramenta, sem precisar abstrair, criar vários arquivos, separar em camadas, nada disso.

Abstração e muito arquivos

Nos exemplos mostrados, principalmente os que apliquei os conceitos de Clean Architecture, pode-se notar uma certa quantidade de arquivos, e por causa disso, vejo muitas reclamações, principalmente no caso de alguma alteração na camada mais interna afetar as mais externas e termos que fazer inúmeras alterações. Porém, esse é um preço a se pagar devido às abstrações que criamos. Essas abstrações são importantes na hora de um teste, caso precise simular um comportamento ou outro, em algum momento que precise mudar partes do sistema, aplicar em outros lugares. Então sim, vamos ter muitos arquivos, e não, não é um problema.

Complexidade

Um outro ponto importantíssimo a se falar é em relação a complexidade na qual você aplica essa arquitetura, mostrei na prática que algo simples pode ser bem feito sem arquitetura limpa. Eu particularmente vejo muita gente errando nisso, existem partes do seu sistema que são complexos, então CA cairia bem, mas tem lugares que não são. Para isso eu deixo esse pensamento: Tentar padronizar todo o sistema é um erro, pois você adiciona abstrações de forma desnecessária, deixando o código muito mais complexo do que realmente é.

Camadas

Arquitetura, seja qual você escolher aplicar no seu sistema, tem que ser bem planejado ou pode atrapalhar ainda mais, e se tratando de arquitetura em camadas, que não é uma exclusividade de CA, é necessário entender que mesmo que uma parte do sistema tenha seu grau de complexidade, não precisamos obrigatóriamente utilizar todas as camadas ou mesmo se privar as 4 definidas, e se você que está lendo ou qualquer outro esteja duvidando de mim, basta assistir esse vídeo.

Problema ou solução?

Eu acredito que até essa parte, muitas pessoas já tiraram suas próprias conclusões sobre esse questionamento, mas saliento que a arquitetura limpa, ou qualquer outra, não é um problema se usado no contexto correto, e isso vale para qualquer coisa, por exemplo, temos linguagens de programação que são melhores que outras para determinados problemas, um jogo é melhor ser feito em um linguagem suporta threads. Tem linguagens mais adaptadas a integração com IA e por aí vai. Então resumindo, se um projeto falhou por causa da arquitetura escolhida, o problema não é da arquitetura e sim de quem a escolheu e aplicou.

Em outras palavras, a Clean Architecture é um problema quando aplicada para resolver situações simples, como o exemplo do cadastro de usuário, mas vira uma solução se aplicado em problemas complexos como o de cálculo de salário. No mundo do desenvolvimento não existe algo que seja sempre a solução, tudo tem seus prós e contras, algo bom em um determinado caso, pode se tornar um problema em outro.

Outras soluções

Existem diversas outras arquitetura, mais simples ou mais complexas, umas muito parecidas com CA, outras bem diferentes, mas uma que gostaria de recomendar é a Arquitetura Hexagonal do Alistair Cockburn, eu gosto bastante dela, acho ela mais simples e até mais "livre", digamos assim. Eu não vou me aprofundar, mas espero que leiam sobre.

Capturando dados com Regex

Erandir Junior — Wed, 08 Feb 2023 14:08:01 +0000

No artigo anterior vimos o que é uma expressão regular e até colocamos alguns de seus recursos em prática. Hoje vamos continuar praticando, mas dessa vez iremos aprender a capturar dados utilizando regex.

Estudos de casos

Nosso primeiro exercício nada mais é que capturar todos os números de uma determinada string:

// Vamos criar nosso padrão
let pattern = /(\d{2})(\d{5})(\d{4})/;

'85912345678'.match(pattern);

Aqui utilizamos o metacaractere \d, que representa um número, e fazemos a captura utilizando os caracteres (). Nada muito complexo, porém, podemos utilizar regex com outras funcionalidades da linguagem para termos algo ainda mais poderoso, por exemplo, vamos aplicar um pequena formatação nesses números:

// Neste caso vamos combinar com o método replace.
'85912345678'.replace(pattern, '($1) $2-$3');
// O código acima retorna (85) 91234-5678

No método replace, basicamente trabalhamos com o valor de cada captura por meio do $númeroDaCaptura, então podemos reorganizar, ocultar, etc, você consegue manipular o valor da captura.

Outro exercício, é justamente o inverso, vamos pegar um CPF formatado e exibir apenas os números:

// Vamos criar nosso padrão
pattern = /(\d{3})\.(\d{3})\.(\d{3})-(\d{2})/;

'210.458.522-05'.replace(pattern, '$1$2$3$4');
// O código acima retorna 21045852205

Uma forma diferente de resolver o exercício anterior, é capturar qualquer coisa que não seja número, e substituir por uma string vazia:

// Vamos criar nosso padrão
pattern = /([^\d])/g;

'210.458.522-05'.replace(pattern, '’);
// O código acima retorna 21045852205

Em nosso padrão, capturamos tudo dentro do agrupador [], dentro dele, informamos que queremos tudo que seja número, por meio do \d, mas antes invertemos essa lógico por meio do caractere ^. A gente já viu isso no primeiro artigo, lembram?

Algo novo fica por conta do g após a expressão. Ele informa que toda a string deve ser analisada, capturando todos os elementos que casem com nosso padrão. Veremos isso melhor em outro exemplo.

Poderíamos simplificar o código acima, alterando o conteúdo dentro de [], para o código abaixo:

// Vamos criar nosso padrão
pattern = /([\D])/g;

'210.458.522-05'.replace(pattern, '’);
// O código acima retorna 21045852205

Substituímos o código ^\d pelo metacaractere \D que representa qualquer coisa que não seja um número.

Agora vamos para outro desafio, nele temos uma string contendo vários números de cpf, nomes de pessoas e datas de nascimento, e temos a tarefa de capturar todas as datas de nascimento. Com tudo o que vimos até aqui, não fica tão difícil de criar o código, vejam:

const data = `210.458.522-05;Erandir Junior;1950-12-12
543.341.836-05;Marcos Antonio;1979-05-20
948.183.538-05;Maria Joaquina;1982-03-28
472.729.923-05;João da Silva;1990-10-01`;

// Podemos utilizar o método match para fazer a captura
data.match(/(\d{4}-\d{2}-\d{2})/);

Se formos executar o código acima, teremos um retorno positivo, porém, podemos ver que a única data capturada foi a primeira, para resolver isso, precisamos informar a regex que é necessário analisar todo o conteúdo em busca de todos os dados que atendam ao padrão definido, para isso basta adicionar um g após do fechamento da regex:

data.match(/(\d{4}-\d{2}-\d{2})/g);

Agora sim temos um retorno com todas as datas que atendem nosso padrão. O g, informa que devemos buscar em toda a string todos os casos que atendem a regex informada. Acredito que com esse exemplo tenha ficado mais fácil de entender seu uso.

Uma outra pequena atividade seria capturar todas as datas, e retornar a mesma string com as datas em padrão brasileiro:

data.replace(/((\d{4})-(\d{2})-(\d{2})/g, '$4/$3/$2');

Aqui continuamos trabalhando com capturas, pegando todos os casos, a diferença é que eu ignoro a primeira captura, que seria a data inteira, substituindo seu valor pela data formatada.

Finalizando

O foco principal deste artigo foi realmente mostrar como trabalhar com grupos de captura, e manipular os valores capturados, existem muitos outros recursos que uma expressão regular oferece, eu mesmo não teria como passar tudo, então o dever de casa de vocês é procurar outros conteúdos e estudar. Vejo você no próximo artigo, até mais.

Validando dados com Regex

Erandir Junior — Mon, 06 Feb 2023 15:07:29 +0000

Expressões Regulares, em inglês Regular Expression (Regex), nada mais são do que padrões para validação ou captura de informações. Em outras palavras, é um recurso muito poderoso e útil para manipular dados.

Estudo de caso simples

Nada melhor do que aprender algo na prática, não é mesmo? Pensando nisso, tive a ideia de fazermos uma validação de e-mails, assim conseguiremos pôr em prática alguns recursos que uma regex oferece.

Os códigos abaixo serão feitos com JavaScript, pois acho que vai ser mais simples de explicar e de praticar, vocês podem utilizar o console do navegador para executar os códigos.

// Primeiramente vamos definir uma variável que contenha um e-mail qualquer
let email = 'erandirjunior@email.com';

Agora com a ajuda do método match, iremos criar nossa primeira expressão, e validar se o dado informado atende o nosso padrão:

/*
Em JS podemos definir uma expressão regular de forma literal ou pelo uso do objeto RegExp.
Nos exemplos utilizarei a forma literal, bastando definir a expressão por meio do //.

O código abaixo vai retornar um array contendo algumas informações,
caso nossa verificação falhasse, receberíamos null como retorno
*/
email.match(/erandirjunior@email.com/);

Para primeira validação, não temos nada complicado, passamos basicamente o mesmo valor contido na nossa variável email. A partir de agora vamos deixar nossa expressão mais genérica e ver o quão poderoso e útil pode ser uma regex.

Um recurso interessante que podemos utilizar é o metacaractere \w, ele serve para representar uma letra, número e o underline, vejam abaixo:

email.match(/\w\w\w\w\w\w\w\w\w\w\w\w\w@email.com/);
// Obtemos o mesmo resultado que o código anterior

Só reforçando, o metacaractere \w substitui letras de a-z, A-Z e números de 0-9 e o caractere _.

O exemplo acima não tá legal pois estamos sendo repetitivos, vamos melhorar nosso código informando que determinado caractere pode se repetir uma quantidade específica de vezes:

email.match(/\w{13}@email.com/);

Acima informamos que um caractere - dentro da regra explicada anteriormente - deve aparecer no mínimo e no máximo 13 vezes.

Nosso padrão até então aceita letras, números e _ no início do nosso e-mail, vamos informar que também podemos aceitar ., para isso vamos fazer uso de um agregador de caracteres, vejam:

email.match(/[a-zA-Z0-9._]{13}@email.com/);

Podemos agrupar caracteres por meio do [], e dentro colocamos tudo o que é aceito. Em nosso caso, informamos que é aceito exclusivamente letras de a até z minúsculas, letras de A até Z maiúsculas, números, o ponto e o underline. Outro ponto a se destacar, é que a ordem do caracteres não importa, então poderíamos ter um e-mail iniciando com . ou _ por exemplo.

Continuando, nossa validação passou, porém, se passarmos um e-mail diferente, com caracteres a menos ou a mais, teremos comportamentos estranhos, executem o código abaixo e notem o retorno:

'erandir.junior@email.com'.match(/[a-zA-Z0-9._]{13}@email.com/);
// Verifiquem o conteúdo do retorno e vejam que foi ignorado a primeira letra

Para corrigir isso, podemos fazer de duas formas, a primeira é informar uma quantidade mínima e deixar a máxima em aberto:

// O valor mínimo aceito é de 1 caractere e não temos valor máximo, mas podemos definir.
email.match(/[a-zA-Z0-9._]{1,}@email.com/);

'erandir.junior@email.com'.match(/[a-zA-Z0-9._]{1,}@email.com/);

Já a segunda forma de corrigir é substituir o quantificador {}, por +:

email.match(/[a-zA-Z0-9._]+@email.com/);

'erandir.junior@email.com'.match(/[a-zA-Z0-9._]+@email.com/);

A grande diferença entre eles, é que o quantificador + informa que um caractere ou mais deve existir, já no quantificador {}, podemos definir uma quantidade fixa, apenas a mínima ou a quantidade mínima e máxima.

Até aqui estamos indo bem, agora vamos trabalhar em cima do host do e-mail, aquela parte depois do @:

email.match(/[a-zA-Z0-9._]+@[a-zA-Z0-9]+.com/);

Existem e-mails que contém o identificador do país, por exemplo e-mails que terminam em .com.br. No código abaixo, vamos informar que o .algumacoisa, após o .com, é completamente opcional:

email.match(/[a-zA-Z0-9._]+@[a-zA-Z0-9._]+.com(?:.[a-z]+)?/);

Explicando de forma mais detalhada a modificação realizada:

Primeiramente envolvemos um código em um grupo de captura por meio de (), veremos isso mais detalhadamente em outro artigo;
Em segundo lugar, informamos que não queremos capturar o grupo, isso por meio do ?:;
Depois informamos que os caracteres aceitos são o . e obrigatoriamente depois um conjunto de caracteres, neste caso, de a até z, sendo no mínimo 1 caractere;
E por último, Utilizando o ?, informamos que um caractere, grupo, etc, é opcional. No nosso caso, todo o grupo é opcional.

Espero que tenham entendido até aqui, mesmo assim, vai ficar muito mais claro com outros exemplos.

Até aqui passamos de uma validação fixa para uma dinâmica. Agora vamos adicionar mais uma regra, particularmente quando me cadastro em um site, costumo adicionar algo no e-mail que me permita identificar esse e-mail posteriormente como único, em outras palavras, posso me cadastrar assim: erandirjunior+teste@email.com. Onde o +teste, por exemplo, poderia ser o nome do site, ou algo do tipo. Vamos aplicar essa regra em nosso código:

email.match(/[a-zA-Z0-9._]+(?:\+[a-zA-Z0-9._]+)?@[a-zA-Z0-9._]+.com(?:.[a-z]+)?/);

'erandir.junior@email.com'.match(/[a-zA-Z0-9._]+(?:\+[a-zA-Z0-9._]+)?@[a-zA-Z0-9._]+.com(?:.[a-z]+)?/);

'erandir.junior@email.com.br'.match(/[a-zA-Z0-9._]+(?:\+[a-zA-Z0-9._]+)?@[a-zA-Z0-9._]+.com(?:.[a-z]+)?/);

'erandir.junior+teste@email.com.br'.match(/[a-zA-Z0-9._]+(?:\+[a-zA-Z0-9._]+)?@[a-zA-Z0-9._]+.com(?:.[a-z]+)?/);

O detalhe dos códigos acima ficam por conta da necessidade de escapar o caractere +, para que não seja entendido como um quantificador e sim como um caractere comum.

Calma que não paramos por aqui, quero explicar mais uma coisa, digamos que a string que contenha o e-mail venha com um espaço no início ou fim. Isso pode ser um problema, então vamos informar que o dado que vier tem que obrigatoriamente iniciar e terminar com nossa validação, para isso basta adicionar os caracteres ^ no início e $ no final:

email.match(/^[a-zA-Z0-9._]+(?:\+[a-zA-Z0-9._]+)?@[a-zA-Z0-9._]+.com(?:.[a-z]+)?$/);

// Isso não funciona
' erandir.junior@email.com'.match(/^[a-zA-Z0-9._]+(?:\+[a-zA-Z0-9._]+)?@[a-zA-Z0-9._]+.com(?:.[a-z]+)?$/);

// Isso não funciona
'erandir.junior@email.com.br '.match(/^[a-zA-Z0-9._]+(?:\+[a-zA-Z0-9._]+)?@[a-zA-Z0-9._]+.com(?:.[a-z]+)?$/);

// Funciona
'erandir.junior+teste@email.com.br'.match(/^[a-zA-Z0-9._]+(?:\+[a-zA-Z0-9._]+)?@[a-zA-Z0-9._]+.com(?:.[a-z]+)?$/);

Gostaria de lembrar que definimos uma regra onde aceitamos letras, números, ponto e undeline na primeira parte de um e-mail, porém, isso não impede de termos . ou _ como primeiro caractere, então vamos definir uma regra, na qual o primeiro caractere só pode ser letra, e o caractere seguinte pode ser qualquer outro.

email.match(/^[^0-9._][a-zA-Z0-9._]+(?:\+[a-zA-Z0-9._]+)?@[a-zA-Z0-9._]+.com(?:.[a-z]+)?$/);

Pode parecer confuso, e realmente é, não vou mentir pra vocês, mas com calma vocês vão entender: lembrando que dentro de [] nós definimos o que é aceito, e que ^ no começo de uma regex, informa que a string a ser manipulada deve iniciar exatamente com as regras definidas no padrão, porém, quando utilizamos o ^ dentro do agrupador [], dizemos que tudo definido dentro de [], não é aceito. Viram como não é complicado?

Um último ponto que gostaria de falar, é sobre o host de um e-mail, digamos que agora só vamos validar e-mails com host xpto ou ywz, então podemos alterar um pouco a nossa regra, veja abaixo:

// Aqui vai falhar pois nosso e-mail tem o host diferente do aceito
email.match(/^[^0-9._][a-zA-Z0-9._]+(?:\+[a-zA-Z0-9._]+)?@(?:xpto|xwz).com(?:.[a-z]+)?$/);

// Aqui vai funcionar pois nosso host é um dos aceitos
'erandir.junior@xpto.com.br'.match(/^[^0-9._][a-zA-Z0-9._]+(?:\+[a-zA-Z0-9._]+)?@(?:xpto|xwz).com(?:.[a-z]+)?$/);

Dica

Um site muito útil e que utilizo sempre que vou definir uma regex, é o https://regex101.com/, nele eu consigo testar regex, ver os recursos disponíveis e ainda exportar o código para a linguagem de programação que utilizo, vejam a imagem a seguir para maiores detalhes:

Finalizando

Neste artigo pude mostrar alguns recursos bem úteis que uma expressão pode oferecer, acredito que apesar de não vermos tudo que uma regex oferece, com os recursos mostrados, pode-se fazer a validação de outras coisas, bastando adaptar os exemplos mostrados acima. Nos próximos artigos veremos outras funcionalidades, vejo você por lá, até mais.

Construindo aplicação do zero com node.js: Parte 5

Erandir Junior — Thu, 17 Nov 2022 15:53:29 +0000

Faaaaaala devs, chegamos ao nosso último artigo, se você chegou até aqui, meus sinceros parabéns e muito obrigado.

Mão na massa

Vamos começar configurando toda a nossa comunicação com o banco de dados, então dentro de src/infra/persistence, crie um arquivo chamado database.js, nele nós criaremos a nossa conexão com o banco:

import { Sequelize } from 'sequelize';

export default class Database {
    static async getConnection() {
        const database = process.env.DB_DATABASE;
        const user = process.env.DB_USER;
        const password = process.env.DB_PASSWORD;
        const host = process.env.DB_HOST;
        const dialect = process.env.DB_DIALECT;

        const sequelize = new Sequelize(database, user, password, {
            host,
            dialect,
            logging: false
        });

        try {
            await sequelize.authenticate();
            console.log('Connection has been established successfully.');
            return sequelize;
        } catch (error) {
            console.error('Unable to connect to the database:', error);
        }
    }
}

Percebam que todas as informações foram definidas em nosso .env. Neste código, utilizei um método estático, mas se quiserem utilizar uma função ou qualquer outra forma, fique à vontade.

Em seguida, vamos definir o nosso modelo, que seria basicamente a representação de uma tabela do banco, crie um arquivo chamado model.js, com o conteúdo abaixo:

import Database from './database.js';
import { DataTypes } from 'sequelize';

const loadModel = async () => {
    const connection = await Database.getConnection();
    const model = connection.define('User', {
        id: {
            type: DataTypes.INTEGER,
            required: true,
            primaryKey: true,
            autoIncrement: true
        },
        email: {
            type: DataTypes.STRING,
            required: true,
            allowNull: false
        },
        password: {
            type: DataTypes.STRING,
            required: true,
            allowNull: false
        },
        expired: {
            type: DataTypes.BOOLEAN,
            default: false
        },
        token: {
            type: DataTypes.STRING
        },
        email_token: {
            type: DataTypes.STRING
        }
    }, {
        tableName: 'users'
    });

    await model.sync();
    return model;
}

export default loadModel;

Um detalhe interessante, é que o código acima também vai funcionar como uma migration, isso é, ele vai criar a tabela no banco, com as colunas e tipos definidos acima. Vejam também que não adicionei muitas informações a essa tabela, se forem adequar este projeto em algum sistema, provavelmente vocês vão precisar adicionar mais alguma informação, e para isso, basta modificar este arquivo.

Agora que temos a nossa conexão e nosso modelo, vamos implementar as dependências que nosso domínio precisa, nesse caso aqui eu joguei tudo em um arquivo chamado repository.js:

import IRepository from './../../domain/irepository.js';
import ITokenRepository from './../../domain/itoken-repository.js';
import User from './../../domain/user.js';

export class Repository extends IRepository {
    #model;

    constructor(model) {
        super();
        this.#model = model
    }

    async findByEmail(email) {
        const result = await this.#model.findOne({ where: {
                email
            }
        });

        if (!result) {
            return undefined;
        }

        return new User({
            id: result.dataValues.id,
            token: result.dataValues.token,
            emailToken: result.dataValues.email_token,
            email: result.dataValues.email,
            password: result.dataValues.password,
        })
    }

    async update(user) {
        const data = {
            token: user.token,
            email_token: user.emailToken,
            expired: user.expired
        }

        await this.#model.update(data, {
            where: {
                id: user.id
            }
        });
    }
}

export class TokenRepository extends ITokenRepository {
    #model;

    constructor(model) {
        super();
        this.#model = model
    }

    updateExpiredFieldToTrue(id) {
        throw Error('Must be implemented');
    }

    async findByToken(token) {
        const result = await this.#model.findOne({ where: {
                token: token.token,
                email_token: token.emailToken,
            }
        });

        if (!result) {
            return undefined;
        }

        return new User({
            id: result.dataValues.id,
            token: result.dataValues.token,
            emailToken: result.dataValues.email_token,
            email: result.dataValues.email,
            password: result.dataValues.password,
            expired: result.dataValues.expired
        })
    }

    async updateExpiredFieldToTrue(id) {
        const data = {
            expired: true
        }

        await this.#model.update(data, {
            where: {
                id
            }
        });
    }
}

Pode ser que por algum motivo, o nosso database não tenha sido criado corretamente, para que tenhamos a certeza, acesse no navegador o endereço: http://localhost:8081, que é a interface do adminer, selecione o sistema como postgres, e preencha os dados do servidor, usuário e senha, no meu caso ficou assim:

Todas as informações preenchidas nessa configuração são as mesmas que estão no arquivo .env, definido no segundo artigo.

Clique em entrar, depois verifique se existe um database com o mesmo nome do campo DB_DATABASE definido em nosso .env, se não existir, clique em Sql Command e execute o comando sql abaixo:

create database two_factor;

Só é necessário caso nosso database não tenha sido criado.

Agora que encerramos nossa parte de banco, vamos configurar nossas rotas. Dentro de src/infra/http/hapi, crie um arquivo chamado server.js, com o conteúdo abaixo:

import Hapi from '@hapi/hapi';
import Vision from '@hapi/vision';
import Inert from '@hapi/inert';
import HapiSwagger from 'hapi-swagger';

const init = async () => {
    const server = Hapi.server({
        port: process.env.APP_PORT,
    });

    const swaggerOptions = {
        info: {
            title: 'API Two-Factor Authentication',
            version: 'v1.0',
        }
    };

    await server.register([
        Inert,
        Vision,
        {
            plugin: HapiSwagger,
            options: swaggerOptions
        }
    ]);

    await server.start();
    console.log('Server running on %s', server.info.uri);
    return server;
};

export default init;

Aqui adicionamos alguns plugins para o hapi, basicamente vai servir para gerarmos a documentação da nossa api, veremos isso com calma depois.

Agora vamos voltar a modificar o arquivo index.js, que está na raiz do nosso projeto, vamos importar nosso serviço de rotas:

import loadEnv from './src/infra/env/load-env.js';
import init from './src/infra/http/hapi/server.js';

async function run() {
    await loadEnv();
    await init();
}

run();

Para saber se está tudo funcionando, basta ir no terminal do serviço node e executar o seguinte comando:

node index.js

O servidor vai subir, agora acesse o endereço: http://localhost:8001/, provavelmente vamos ter um retorno 404.

Agora vamos começar a chamar nossas regras e passar para elas todos os serviços criado anteriormente, para isso, crie o diretório actions, dentro de src/infra, e crie os arquivos user-authetication-action.js e user-authetication-action.js, com o conteúdo abaixo:

// src/infra/action/token-authentication-action.js
import loadModel from '../persistence/model.js';
import { Repository } from '../persistence/repository.js';
import UserAuthentication from '../../domain/user-authentication.js';
import Email from '../email/email.js';
import PasswordHash from '../hash/password-hash.js';
import TokenService from '../token/token-service.js';
import LoginPayload from '../../domain/login-payload.js';

const createUserAuthentication = async (payload) => {
    const userModel = await loadModel();
    const repository = new Repository(userModel);
    const userAuthentication = new UserAuthentication(
        repository,
        new Email(),
        new PasswordHash(),
        new TokenService()
    );

    const loginPayload = new LoginPayload(payload.email, payload.password);
    return await userAuthentication.authenticate(loginPayload);
}

export default createUserAuthentication;

// src/infra/action/token-authentication-action.js
import loadModel from '../persistence/model.js';
import { TokenRepository } from '../persistence/repository.js';
import TokenAuthentication from '../../domain/token-authentication.js';
import Jwt from '../jwt/jwt.js';
import Token from '../../domain/token.js';

const createTokenAuthentication = async (payload) => {
    const userModel = await loadModel();
    const repository = new TokenRepository(userModel);
    const tokenAuthentication = new TokenAuthentication(
        repository,
        new Jwt()
    );

    const token = new Token(payload);
    return await tokenAuthentication.authenticate(token);
}

export default createTokenAuthentication;

Estamos chamando nossas lógicas de domínio e passando para elas todas as dependências implementadas, fizemos isso nos testes, só que lá injetamos comportamentos que simulam as ações.

Voltemos para diretório src/infra/http/hapi, nele vamos criar um arquivo chamado routes.js, onde vamos definir nossas rotas e suas ações:

import Joi from 'joi';
import InvalidArgumentError from './../../../domain/invalid-argument-error.js';
import GatewayError from './../../../domain/gateway-error.js';
import Boom from '@hapi/boom';
import createUserAuthentication from '../../actions/user-authentication-action.js';
import createTokenAuthentication from '../../actions/token-authentication-action.js';

const handlerError = (error) => {
    if (error instanceof GatewayError) {
        return Boom.badGateway(error.message);
    }

    if (error instanceof InvalidArgumentError) {
        return Boom.badRequest(error.message);
    }

    return Boom.badImplementation(error);
}

const failAction = (request, h, err) => {
    throw err;
};

const routes = [
    {
        options: {
            tags: ['api'],
            description: 'Get temporary token',
            notes: 'Login with email and password',
            validate: {
                payload: Joi.object({
                    email: Joi.string().email().required(),
                    password: Joi.string().min(6).required()
                }),
                failAction
            }
        },
        method: 'POST',
        path: '/login',
        handler: async (request, h) => {
            try {
                const { payload } = request;
                const result = await createUserAuthentication(payload);
                return {
                    token: result
                };
            } catch (e) {
                return handlerError(e);
            }
        }
    },
    {
        options: {
            tags: ['api'],
            description: 'Login in the application',
            notes: 'Login with token and the token receive in e-mail',
            validate: {
                payload: Joi.object({
                    token: Joi.string().min(35).required(),
                    emailToken: Joi.string().min(22).required()
                }),
                failAction
            }
        },
        method: 'POST',
        path: '/token',
        handler: async (request, h) => {
            try {
                const { payload } = request;
                const result = await createTokenAuthentication(payload);
                return {
                    token: result
                };
            } catch (e) {
                return handlerError(e);
            }
        }
    }
]

export default routes;

Detalhando o código acima: a função handlerError vai trabalhar em cima do tipo de erro para retornar uma resposta personalizada, utilizamos o Boom para nos auxiliar nessas respostas. A constante routes, recebe um array de objetos contendo as duas rotas do nosso sistemas, ambas são do tipo POST, definimos uma tag para elas, isso é útil para o swagger, que vai documentar nossa api. Fizemos uso do Joi para validar os dados enviados pela requisição e finalmente chamamos nossas ações passando os dados da requisição, acredito que tenha ficado fácil de entender o código acima.

Agora a gente precisa informar essa rotas ao hapi, para isso, altere o arquivo server.js, e deixe ele assim:

import Hapi from '@hapi/hapi';
import Vision from '@hapi/vision';
import Inert from '@hapi/inert';
import HapiSwagger from 'hapi-swagger';
import routes from './routes.js';

const init = async () => {
    const server = Hapi.server({
        port: process.env.APP_PORT,
    });

    const swaggerOptions = {
        info: {
            title: 'API Two-Factor Authentication',
            version: 'v1.0',
        }
    };

    await server.register([
        Inert,
        Vision,
        {
            plugin: HapiSwagger,
            options: swaggerOptions
        }
    ]);

    server.route(routes);

    await server.start();
    console.log('Server running on %s', server.info.uri);
    return server;
};

export default init;

E pronto, se tudo estiver ok, a gente pode acessar o seguinte endereço: http://localhost:8001/documentation, que vai carregar a documentação da api, com os campos a serem enviados, o tipo da requisição, etc, lembre-se de parar e subir o servidor novamente.

Se precisarmos modificar algo no código acima, a reinicialização do servidor é necessária, se quiserem evitar isso, basta configurar o uso do nodemon, conforme explicado no artigo anterior, ele vai identificar uma mudança e fazer o recarregamento do servidor. Se quiserem utilizá-lo, alterem o arquivo package.json, e adicione um novo script. O exemplo abaixo mostra a adição do campo start e o uso do nodemon:

{
  "name": "two-factor-authentication",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
    "scripts": {
      "start": "node_modules/nodemon/bin/nodemon.js index.js",
      "test": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js ./tests/* --coverage --config='{ \"coverageReporters\": [\"html\"] }'\n"
    },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "module",
  "dependencies": {
    "@hapi/boom": "^10.0.0",
    "@hapi/hapi": "^20.2.2",
    "@hapi/inert": "^7.0.0",
    "@hapi/vision": "^7.0.0",
    "bcrypt": "^5.1.0",
    "dotenv": "^16.0.3",
    "hapi-swagger": "^14.5.5",
    "joi": "^17.6.3",
    "jsonwebtoken": "^8.5.1",
    "nodemailer": "^6.8.0",
    "pg": "^8.8.0",
    "pg-hstore": "^2.3.4",
    "sequelize": "^6.25.3",
    "short-uuid": "^4.2.0"
  },
  "devDependencies": {
    "jest": "^29.2.1",
    "nodemon": "^2.0.20"
  }
}

Após essa alteração rode o seguinte comando:

npm start

Esse comando vai subir o servidor e se qualquer modificação for realizada, o servidor vai ser reinicializado automaticamente.

E antes de irmos para um postman ou qualquer outra ferramenta, vamos criar um teste para saber se tudo está funcionando, crie um arquivo de teste chamado login.test.js, dentro de tests/feature, com o conteúdo abaixo:

import loadEnv from '../../src/infra/env/load-env.js';
import init from '../../src/infra/http/hapi/server.js';
let api = {};
let token = {};
let user = {
    email: 'email@email.com',
    password: '123456'
}
import Bcrypt from 'bcrypt';
import loadModel from '../../src/infra/persistence/model.js';
let model = {};
beforeAll(async () => {
    await loadEnv();
    api = await init();
    model = await loadModel();
    const pass = await Bcrypt.hash(user.password, 3);
    await model.destroy({ where : { email: user.email }});
    await model.create({
        email: user.email,
        password: pass
    });
});

test('Should get token', async () => {
    const result = await api.inject({
        method: 'POST',
        url: '/login',
        payload: user
    });
    const data = JSON.parse(result.payload);
    token = data.token;
    expect(token.length).toBeGreaterThan(35);
});

test('Should get jwt token', async () => {
    const user = await model.findOne({where: {token}, raw: true});
    const result = await api.inject({
        method: 'POST',
        url: '/token',
        payload: {
            token,
            emailToken: user.email_token
        }
    });
    const data = JSON.parse(result.payload);
    expect(data.token.length).toBeGreaterThan(40);
    expect(data.token).toBeTruthy();
    await model.destroy({ where : { email: user.email }});
});

Aqui, primeiro criamos um usuário temporário e depois começamos a fazer as requisições, primeiro com login e senha, e depois a requisição passando os tokens. Observe o uso da lib Bcrypt para fazer um hash da nossa senha.

Antes de executarmos o teste, duplique o conteúdo do arquivo .env, para um arquivo chamado .env.test, isso é bem útil pois podemos realizar testes utilizando outro banco por exemplo.

Agora sim podemos executar nossos testes mais uma vez:

npm t

Se você tiver seguido todos os passos, todos os testes vão passar corretamente. Minha dica é sempre olharem o relatório de cobertura.

Fim

Bem devs, chegamos ao fim do nosso projeto, espero que tenham aprendido algo, assim como aprendi. No primeiro artigo da série, eu deixei o link do repositório do código do projeto.

Novamente deixo meus agredecimentos por terem chegado até aqui. Nos vemos em outros artigos, até mais.

Construindo aplicação do zero com node.js: Parte 4

Erandir Junior — Mon, 14 Nov 2022 14:42:06 +0000

Depois de desenvolver toda a regra principal da aplicação, vamos começar a implementar de fato as nossas dependências.

Mão na massa

Primeiramente vamos alterar o arquivo .env, que foi criado lá parte 2, deixe o arquivo com as seguintes informações:

APP_PORT=8001

DB_DIALECT=postgres
DB_HOST=db_two_factor
DB_DATABASE=two_factor
DB_USER=root
DB_PASSWORD=root

JWT_SECRET=My@jwt#Secret%

EMAIL_HOST=smtp.gmail.com
EMAIL_USER=email_de_exemplo@gmail.com
EMAIL_PASS=sua_senha
EMAIL_PORT=465

Essas são todas as credenciais necessárias nesse projeto. Recomendo parar e subir os containers novamente, depois, acesse o terminal do serviço node para que possamos instalar nossas bibliotecas.

Outro detalhe é que os dados acima são somente de exemplo, se você tem uma conta do google, assim como eu, altere somente os campos EMAIL_USER e EMAIL_PASS, agora caso queiram utilizar algo diferente, é necessário alterar o EMAIL_HOST e talvez o EMAIL_POST.

Dependências

A primeira dependência que vamos instalar, é uma biblioteca que fará o carregamento das informações contidas no arquivo .env, no terminal, execute o comando abaixo para fazer a instalação:

npm i dotenv

Após isso, crie um arquivo chamado load-env.js dentro de src/infra/env. Nesse arquivo vamos implementar a lógica para que ele consiga ler as informações do nosso arquivo .env. Adicione o código abaixo no arquivo:

import { config } from 'dotenv';

const loadEnv = async () => {
    let env = '';

    if (process.env.NODE_ENV) {
        env = `.${process.env.NODE_ENV}`;
    }

    const configPath = `.env${env}`;

    const result = config({
        path: configPath
    });

    if (result.error) {
        throw result.error
    }
}

export default loadEnv;

Agora, na raiz da nossa aplicação, crie um arquivo chamado index.js com o seguinte conteúdo:

import loadEnv from './src/infra/env/load-env.js';

async function run() {
    await loadEnv();
}

run();

Esse arquivo será o ponto de partida da nossa aplicação. Por enquanto deixemos ele assim, voltaremos a modificá-lo no futuro.

Em seguida, vamos instalar uma biblioteca para manipular senhas, ela será útil por exemplo para criptografar senhas e fazer comparações de hashs:

npm i bcrypt

Agora crie um arquivo chamado password-hash.js, dentro de src/infra/hash, com o conteúdo abaixo:

import IPasswordHash from './../../domain/ipassword-hash.js';
import Bcrypt from 'bcrypt';
import { promisify } from 'util';
const compareAsync = promisify(Bcrypt.compare);

export default class PasswordHash extends IPasswordHash {
    constructor() {
        super();
    }

    compare(password, hash) {
        return compareAsync(password, hash);
    }
}

Basicamente implementamos nosso comparativo de senha, detalhe para o uso da função interna do node chamada promisify, que converte funções callback para promise, facilitando o use de qualquer recurso.

Agora vamos instalar duas bibliotecas muito úteis, a primeira vai servir para gerar um token jwt, e o segundo nos servirá para gerar uuids:

npm i jsonwebtoken short-uuid

Após a instalação, vamos começar por configurar a nossa geração de token jwt. Dentro de src/infra/jwt, crie o arquivo jwt.js, com o seguinte conteúdo:

import IToken from './../../domain/itoken.js';
import JWT from 'jsonwebtoken';

export default class Jwt extends IToken {
    constructor() {
        super();
    }

    generateWebToken(user) {
        const token = JWT.sign({
            id: user.id,
            email: user.email,
        }, process.env.JWT_SECRET);

        return token;
    }
}

Aqui não tenho muito o que falar a não ser recomendar pesquisarem um pouco sobre essa biblioteca para terem noção do quão poderosa ela é.

Agora vamos configurar nosso gerador de uuids, dentro de src/infra/token, crie o arquivo token-service.js, e insira o conteúdo abaixo:

import Short from 'short-uuid';
import IGenerateToken from '../../domain/igenerate-token.js';

export default class TokenService extends IGenerateToken {
    constructor() {
        super();
    }

    getToken() {
        return Short.uuid();
    }

    getEmailToken() {
        return Short.generate();
    }
}

Essa biblioteca vai nos fornecer dois recursos: o primeiro é a geração de um uuid completo, algo como fd5c084c-ff7c-4651-9a52-37096242d81c, além disso, ela também permite a geração de identificadores menores, então o método generate() retornaria algo parecido com isso mhvXdrZT4jP5T8vBxuvm75.

Agora vamos instalar a biblioteca que vai fazer o envio de e-mail:

npm i nodemailer

Após a instalação, vamos configurar nosso serviço de e-mail, dentro do diretório src/infra/email, crie um arquivo chamado body-email-html.js, ele vai conter o conteúdo html que será enviado para o cliente:

const bodyEmailHtml = (token) => {
    return `<!DOCTYPE html>
        <html>
        <head>
        <style>
            .container {
                margin: 10% 20%;
                border-radius: 10px;
                background-color: white;
            }

            .title {
                padding: 1% 0% 0%;
                text-align: center
            }

            p {
                color:blue;
                text-align: center;
                font-family: Arial, sans-serif;
                font-size: 30px;
                padding-bottom: 5%;
            }
        </style>
        </head>
        <body>
            <div class="container">
                <div class="title">
                    <h3>Use the token below to finish login.</h3>
                </div>
                <hr/>
                <p>${token}</p>
            </div>
        </body>
        </html>`;
};

export default bodyEmailHtml;

Ainda dentro do mesmo diretório, crie um arquivo chamado email.js, nele vamos realmente implementar a funcionalidade de envio:

import IEmail from './../../domain/iemail.js';
import nodemailer from "nodemailer";
import bodyEmailHtml from './body-email-html.js';

export default class Email extends IEmail {
    constructor() {
        super();
    }

    async send(user) {
        const transporter = nodemailer.createTransport({
            host: process.env.EMAIL_HOST,
            port: process.env.EMAIL_PORT,
            auth: {
                user: process.env.EMAIL_USER,
                pass: process.env.EMAIL_PASS,
            },
        });

        await transporter.sendMail({
            from: process.env.EMAIL_USER,
            to: user.email,
            subject: "Hello, see you token",
            html: bodyEmailHtml(user.emailToken)
        });
    }
}

Como podem ver, não tem nada de complexo, basicamente informamos a configuração de conexão, e após isso enviamos o e-mail para o remetente correto. Outra recomendação é olhar mais detalhadamente essa biblioteca para ter uma noção dos inúmeros outros recursos que ela oferece.

Bem pessoal, a partir de agora faremos algumas instalações bem úteis, porém só vamos configurá-las no próximo artigo. Vamos começar pelo hapi, que fará todo o intermédio entre as requisições web e a nossa aplicação:

npm i @hapi/boom @hapi/hapi @hapi/inert @hapi/vision hapi-swagger joi

Muitos devem conhecer o express ou outra lib que faça a mesma coisa, caso queira utilizar algo diferente do hapi, fiquem a vontade.

Em seguida, vamos instalar um orm, que vai servir para intermediar nossa comunicação e manipulação do banco, eu optei pelo sequelize, mas fique a vontade se quiser utilizar outro:

npm i pg pg-hstore sequelize

E por último, mas não menos importante, vamos instalar uma lib, que é bem útil enquanto você desenvolve.

npm i --save-dev nodemon

O nodemon é bem útil enquanto desenvolvemos, pois não precisaremos reiniciar o servidor a cada alteração. Para vocês que estão seguindo esses artigos, não será tão útil, devido eu ter feito de uma forma mais organizada, mas para mim que fazia o projeto e não segui exatamente a ordem dos artigos, ajudou bastante.

Outro ponto é que essa biblioteca, assim como a de teste, vai ser instalada somente para ambiente de desenvolvimento.

Resumo

Neste artigo, vimos a instalação e uso de algumas dependências, recomendo novamente que pesquisem um pouco mais sobre cada biblioteca instalada, seus recursos, etc.

Se você for um dev mais experiente, e conheça ou queira utilizar outras bibliotecas, deixei claro que você pode fazer isso tranquilamente. Repare que essas mudanças não afetam a nossa lógica principal, esse é um benefício de adotar uma arquitetura que tenha como foco a camada de regras de negócio. Até o próximo artigo.

Construindo aplicação do zero com node.js: Parte 3

Erandir Junior — Thu, 10 Nov 2022 14:53:55 +0000

Chegamos a parte 3 desta série de artigos, e agora vamos construir nossa lógica de login com os tokens.

Lógica

Nessa parte de validar os tokens, pensei na seguinte lógica: recebo os tokens, valido eles, pesquiso um usuário pelos tokens enviados, verifico se os tokens ainda não foram utilizados e se tiver tudo certo, eu atualizo o campo expired para true, assim bloqueamos caso seja feita nova tentativa de logar com os mesmos tokens, e por último, retornamos um novo token, que em nosso caso, utilizaremos uma lib para retornar um jwt.

Mão na massa

A primeira coisa que vamos fazer, é definir nossas 3 dependências, sendo nossas interfaces de comunicação, e o objeto da requisição.

// src/domain/itoken-repository.js
export default class ITokenRepository {
    findByToken(token) {
        throw Error('Method must be implemented!');
    }

    updateExpiredFieldToTrue(id) {
        throw Error('Method must be implemented!');
    }
}

// src/domain/itoken.js
export default class IToken {
    generateWebToken(user) {
        throw Error('Method must be implemented!');
    }
}

// src/domain/token.js
import InvalidArgumentError from './invalid-argument-error.js';
import throwError from './throw-error.js';

export default class Token {
    constructor({token, emailToken}) {
        if (!token || !emailToken) {
            throwError(InvalidArgumentError, 'Fields token and emailToken cannot be empty!');
        }
        this.token = token;
        this.emailToken = emailToken;
    }
}

Agora que já temos nossas dependências, vamos construir nossa classe de regra de negócio:

// src/domain/token-authentication.js

import IToken from './itoken.js';
import ITokenRepository from './itoken-repository.js';
import Token from './token.js';
import isInstanceOf from './instanceof.js';
import DomainError from './domain-error.js';
import GatewayError from './gateway-error.js';
import InvalidArgumentError from './invalid-argument-error.js';
import throwError from './throw-error.js';
import User from './user.js';

export default class TokenAuthentication {
    #repository;
    #webToken;

    constructor(repository, webToken) {
        this.#validateDependencies(repository, webToken)
        this.#repository = repository;
        this.#webToken = webToken;
    }

    #validateDependencies(repository, webToken) {
        if (!this.#isInstanceOf(repository, ITokenRepository)) {
            throwError(DomainError, 'Invalid repository dependency');
        }

        if (!this.#isInstanceOf(webToken, IToken)) {
            throwError(DomainError, 'Invalid token dependency');
        }
    }

    async authenticate(token) {
        this.#throwExceptionIfTokenIsInvalid(token);
        const user = await this.#getUser(token);
        this.#throwExceptionIfInvalidUser(user);

        try {
            await this.#repository.updateExpiredFieldToTrue(user.id);
            return this.#webToken.generateWebToken(user);
        } catch (error) {
            throwError(GatewayError, 'Generic error, check the integrations!');
        }
    }

    #throwExceptionIfInvalidUser(user) {
        if (!user) {
            throwError(InvalidArgumentError, 'Tokens sent are invalids. Try again!');
        }

        if (!isInstanceOf(user, User)) {
            throwError(DomainError, 'Invalid user instance!');
        }

        if (user.expired) {
            throwError(InvalidArgumentError, 'Token expired. Try login again!');
        }
    }

    async #getUser(token) {
        try {
            return await this.#repository.findByToken(token);
        } catch (e) {
            throwError(GatewayError, 'Invalid database connection!');
        }
    }

    #throwExceptionIfTokenIsInvalid(token) {
        if (!this.#isInstanceOf(token, Token)) {
            throwError(DomainError, 'Invalid token object!');
        }
    }

    #isInstanceOf(object, instanceBase) {
        return isInstanceOf(object, instanceBase)
    }
}

Aqui não fiz nada que já não viram anteriormente, foram feitas algumas validações de instância e levantamos erros personalizados. A grande observação fica realmente sobre o campo expired, já que se ele vier como true, significa que esses tokens já foram utilizados.

Testes

E assim como fizemos no artigo anterior vamos construir nossos testes. Primeiro vamos simular nossas dependências:

// tests/unit/mocks/web-token-mock.js

import ITokenRepository from '../../../src/domain/itoken-repository.js';
import User from '../../../src/domain/user.js';

class TokenRepositoryMock extends ITokenRepository {
    throwException = false;
    throwExceptionUpdate = false;
    throwExceptionTokenExpired = false;
    returnEmpty = false;
    returnEmptyObj = false;

    constructor() {
        super();
    }

    findByToken(token) {
        if (this.returnEmpty) {
            return '';
        }

        if (this.returnEmptyObj) {
            return {};
        }

        if (this.throwException) {
            throw Error();
        }

        const obj = {id: 1, email: 'erandir@email.com', password: '123456'};

        if (this.throwExceptionTokenExpired) {
            obj.expired = true;
        }

        let user = new User(obj);

        return Promise.resolve(user);
    }

    updateExpiredFieldToTrue(id) {
        if (this.throwExceptionUpdate) {
            throw Error();
        }
        return Promise.resolve(true);
    }
}

export default new TokenRepositoryMock();

// tests/unit/mocks/token-repository-mock.js

import IToken from '../../../src/domain/itoken.js';

class WebTokenMock extends IToken {
    throwException = false;

    constructor() {
        super();
    }

    generateWebToken(user) {
        if (this.throwException) {
            throw Error();
        }

        return Promise.resolve('763a5b89-9c96-4f9b-8daa-0b411c7c671e');
    }
}

export default new WebTokenMock();

Criamos nossa arquivo chamado token-authentication.test.js dentro de tests/unit/, e adicionamos o conteúdo abaixo:

import TokenAuthentication from '../../src/domain/token-authentication.js';
import TokenRepositoryMock from './mocks/token-repository-mock.js';
import WebTokenMock from './mocks/web-token-mock.js';
import Token from '../../src/domain/token.js';
const tokenAuthentication = new TokenAuthentication(TokenRepositoryMock, WebTokenMock);
const token = new Token({
    token: '13eb4cb6-35dd-4536-97e6-0ed0e4fb1fb3',
    emailToken: '4RV651gR93hDAGiTCYhmhh'
});

test('Invalid object repository', function () {
    const result = () => new TokenAuthentication(
        {},
        {}
    );
    expect(result).toThrowError('Invalid repository dependency');
});

test('Invalid object web token', function () {
    const result = () => new TokenAuthentication(
        TokenRepositoryMock,
        {}
    );
    expect(result).toThrowError('Invalid token dependency');
});

test('Invalid object token', function () {
    const result = async () => await tokenAuthentication.authenticate({});
    expect(result).rejects.toThrow('Invalid token object!');
});

test('Throw exception get user', function () {
    TokenRepositoryMock.throwException = true;
    const result = async () => await tokenAuthentication.authenticate(token);
    expect(result).rejects.toThrow('Invalid database connection!');
});

test('Throw exception get empty user', function () {
    TokenRepositoryMock.throwException = false;
    TokenRepositoryMock.returnEmpty = true;
    const result = async () => await tokenAuthentication.authenticate(token);
    expect(result).rejects.toThrow('Tokens sent are invalids. Try again!');
});

test('Throw exception invalid user object', function () {
    TokenRepositoryMock.returnEmpty = false;
    TokenRepositoryMock.returnEmptyObj = true;
    const result = async () => await tokenAuthentication.authenticate(token);
    expect(result).rejects.toThrow('Invalid user instance!');
});

test('Throw exception token expired', function () {
    TokenRepositoryMock.returnEmptyObj = false;
    TokenRepositoryMock.throwExceptionTokenExpired = true;
    const result = async () => await tokenAuthentication.authenticate(token);
    expect(result).rejects.toThrow('Token expired. Try login again!');
});

test('Throw exception update user', function () {
    TokenRepositoryMock.throwExceptionTokenExpired = false;
    TokenRepositoryMock.throwExceptionUpdate = true;
    const result = async () => await tokenAuthentication.authenticate(token);
    expect(result).rejects.toThrow('Generic error, check the integrations!');
});

test('Throw exception generate web token', function () {
    TokenRepositoryMock.throwExceptionUpdate = false;
    WebTokenMock.throwException = true
    const result = async () => await tokenAuthentication.authenticate(token);
    expect(result).rejects.toThrow('Generic error, check the integrations!');
});

test('Generate token', async () => {
    const expected = '763a5b89-9c96-4f9b-8daa-0b411c7c671e';
    WebTokenMock.throwException = false;
    const result = await tokenAuthentication.authenticate(token);

    expect(result).toBe(expected);
});

Se rodarmos os testes, vamos ter um novo relatório de cobertura. Se observarmos esse relatório, percebemos que nosso diretório domain, não está 100% testado, vamos aplicar os testes nas classes que encapsulam dados e também nas que simulam interfaces:

// tests/unit/dependecy.test.js

import IEmail from "./../../src/domain/iemail.js";
import IGenerateToken from '../../src/domain/igenerate-token.js';
import IPasswordHash from '../../src/domain/ipassword-hash.js';
import IRepository from '../../src/domain/irepository.js';
import ITokenRepository from '../../src/domain/itoken-repository.js';
import IToken from '../../src/domain/itoken.js';
import LoginPayload from '../../src/domain/login-payload.js';
import Token from '../../src/domain/token.js';
import User from '../../src/domain/user.js';
const email = new IEmail({});
const generateToken = new IGenerateToken({});
const passwordHash = new IPasswordHash();
const repository = new IRepository();
const tokenRepository = new ITokenRepository();
const tokenWeb = new IToken();

test('Error email not implemented', () => {
    const result = () => email.send();
    expect(result).toThrowError('Method must be implemented!');
});

test('Error get token not implemented', () => {
    const result = () => generateToken.getToken();
    expect(result).toThrowError('Method must be implemented!');
});

test('Error get email token implemented', () => {
    const result = () => generateToken.getEmailToken();
    expect(result).toThrowError('Method must be implemented!');
});

test('Error password compare implemented', () => {
    const result = () => passwordHash.compare();
    expect(result).toThrowError('Method must be implemented!');
});

test('Error find by email implemented', () => {
    const result = () => repository.findByEmail();
    expect(result).toThrowError('Method must be implemented!');
});

test('Error update implemented', () => {
    const result = () => repository.update({});
    expect(result).toThrowError('Method must be implemented!');
});

test('Error find by token implemented', () => {
    const result = () => tokenRepository.findByToken({});
    expect(result).toThrowError('Method must be implemented!');
});

test('Error update expire field implemented', () => {
    const result = () => tokenRepository.updateExpiredFieldToTrue();
    expect(result).toThrowError('Method must be implemented!');
});

test('Error generate implemented', () => {
    const result = () => tokenWeb.generateWebToken();
    expect(result).toThrowError('Method must be implemented!');
});

test('Error parameter not send to login payload object', () => {
    const result = () => new LoginPayload();
    expect(result).toThrowError('Fields email and password must be filled!');
});

test('Error parameter not send to token object', () => {
    const result = () => new Token({});
    expect(result).toThrowError('Fields token and emailToken cannot be empty!');
});

test('Error parameter not send to user object', () => {
    const result = () => new User({});
    expect(result).toThrowError('Invalid user data!');
});

Rodamos os testes novamente para garantir que tudo está validado e funcionando corretamente.

Resumo

Este artigo foi bem menor e bem mais simples que o anterior, tecnicamente validamos nossas lógicas, bastando agora realmente implementar nossas dependências, para aí sim, começarmos a utilizar esse projeto realmente.

A partir do próximo artigo, iremos instalar algumas bibliotecas, encapsular comportamentos e ter um projeto cada vez mais sólido e pronto para ser utilizado no mundo real.

Construindo aplicação do zero com node.js: Parte 2

Erandir Junior — Mon, 07 Nov 2022 14:41:46 +0000

Fala galera, depois de um primeiro artigo bem teórico, dessa vez iremos colocar a mão na massa. Mas antes, é necessário informar que os códigos a seguir já estão adaptados para a versão final do projeto, isso é, todos os exemplos já serão utilizando Jest e ES6 Module, além de algumas correções que encontrei pelo caminho.

Configurando Docker

Inicialmente você precisa ter configurado tanto o docker quanto o docker compose em sua máquina, até mesmo para termos um padrão no ambiente de desenvolvimento.

Com a máquina já configurada, crie um diretório qualquer, no meu caso foi Two-Factor-Authentication e dentro dele vamos criar os arquivos Dockerfile, sem extensão, e o arquivo docker-compose.yml.

No arquivo Dockerfile, deixaremos ele assim:

FROM node:lts

RUN mkdir /app

WORKDIR /app

COPY --chown=node:node . .

CMD /bin/sh

No arquivo docker-compose.yml, deixaremos ele assim:

version: '3.9'
services:
  two_factor_authentication:
    container_name: authentication_project
    build: .
    volumes:
      - .:/app:rw
    ports:
      - "${APP_PORT}:${APP_PORT}"
    restart: "no"
    command: sh
    stdin_open: true
    tty: true
    environment:
      - CHOKIDAR_USEPOLLING=true
    depends_on:
      - db_two_factor
    networks:
      - pg-network
  adminer:
    image: adminer
    container_name: adminer_sgbd_two_factor_authentication
    ports:
      - "8081:8080"
    depends_on:
      - db_two_factor
    restart: always
    networks:
      - pg-network
  db_two_factor:
    image: postgres:latest
    container_name: db_two_factor_authentication
    ports:
      - 5432:5432
    environment:
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=${DB_DATABASE}
      - POSTGRES_HOST_AUTH_METHOD=trust
    networks:
      - pg-network
    volumes:
      - dba:/var/lib/postgresql

volumes:
  dba:

networks:
  pg-network:
    driver: bridge

Só para esclarecer o que estamos fazendo, iremos utilizar a última versão do node lts, usaremos a última versão do postgres, para armazenar os dados, e utilizaremos o adminer, que é uma ferramenta visual para auxiliar no gerenciamento do banco de dados.

Além disso, algumas informações da nossa configuração acima são dinâmicas, como por exemplo as informações de conexão com o banco e a porta da aplicação, para isso, vamos criar um arquivo de configuração chamado .env, com o seguinte conteúdo;

APP_PORT=8001

DB_DIALECT=postgres
DB_HOST=db_two_factor
DB_DATABASE=two_factors
DB_USER=root
DB_PASSWORD=root

Esse arquivo será bem útil posteriormente.

Agora iremos subir todos os nossos serviços. Acesse o terminal e rode o comando abaixo:

docker-compose up --buid

Ou se quiser deixar os serviços rodando em segundo plano, basta rodar o comando abaixo:

docker compose up -d --build

Agora que estamos com nossos serviços rodando, vamos entrar no serviço onde está o node para começarmos a construir nossa aplicação, no terminal, rode o comando abaixo:

docker exec -it authentication_project bash

authentication_project é o nome do meu serviço node, para verificar o seu, basta rodar o comando docker ps.

Iniciando estrutura do projeto

Depois de entrarmos no serviço do node, vamos rodar o seguinte comando para de fato iniciarmos o projeto:

npm init -y

Um arquivo chamado package.json vai ser criado, ele será bem útil, por enquanto o deixaremos de lado. Em relação a organização do projeto, deixei claro que me baseei na arquitetura hexagonal (falarei um pouco mais posteriormente), então vamos criar diretórios que vão facilitar o entendimento do projeto, minha estrutura ficou como o da imagem abaixo:

src/domain: onde ficará toda a nossa regra de negócio;
src/infra: onde ficará todas as implementações das dependências do nosso projeto, irá encapsular os recursos de libs, por exemplo;
tests: onde ficará nossos testes.

Fluxo do projeto

O fluxo do projeto será dividido em duas partes: Primeiro vamos construir a lógica de login "tradicional", com e-mail e senha, depois vamos construir a lógica de logar com o token.

E pensando na primeira lógica do sistema, a gente vai ter uma entrada de e-mail e senha, vamos precisar buscar as informações do usuário pelo e-mail, validar sua senha, gerar um token e mandar por e-mail. Nesta breve descrição, podemos perceber que teremos uma comunicação com o banco de dados, uma validação de senha, comunicação com o serviço de e-mail e geração de token, ou seja, temos 4 dependências.

Vamos primeiramente definir essas "interfaces", lembrando que JS não possui o recurso de interface como conhecemos em outras linguagens, então dentro de src/domain, vamos criar alguns arquivos:

// src/domain/iemail.js
export default class IEmail {
    send(user) {
        throw new Error('Method must be implemented!');
    }
}

// src/domain/irepository.js
export default class IRepository {
    findByEmail(email) {
        throw Error('Method must be implemented!');
    }

    update(user) {
        throw Error('Method must be implemented!');
    }
}

// src/domain/ipassword-hash.js
export default class IPasswordHash {
    compare(password, hash) {
        throw Error('Method must be implemented!');
    }
}

// src/domain/igenerate-token.js
export default class IGenerateToken {
    getToken() {
        throw Error('Method must be implemented!');
    }

    getEmailToken() {
        throw Error('Method must be implemented!');
    }
}

Basicamente definimos nossas "interfaces" de comunicação. Um detalhe muito importante fica por conta da classe IGenerateToken, contendo 2 métodos de geração de token, isso porque pensei na seguinte lógica: quando o usuário logar, ele vai receber por e-mail um token, porém também vai receber um outro token como resposta da requisição (que será armazenada temporariamente pelo cliente), quando o usuário for fazer a segunda autenticação, ele vai precisar mandar os 2 tokens, aqui basicamente é uma forma de aumentar a segurança.

Outra coisa que vamos encapsular, é em relação ao erros, eu basicamente criei 3 classes de erros, isso vai ser útil mais na frente:

// src/domain/domain-error.js
export default class DomainError extends Error {
    constructor(message) {
        super(message);
    }
}

// src/domain/gateway-error.js
export default class GatewayError extends Error {
    constructor(message) {
        super(message);
    }
}

// invalid-argument-error.js
export default class InvalidArgumentError extends Error {
    constructor(message) {
        super(message);
    }
}

Também vamos criar uma ação para trabalhar com esses erros:

// throw-error.js
const throwError = (error, message) => {
    throw new error(message);
};

export default throwError;

Agora vamos construir a classe de login:

// src/domain/user-authentication.js
import IRepository from './irepository.js';
import IEmail from './iemail.js';
import IPasswordHash from './ipassword-hash.js';
import IGenerateToken from './igenerate-token.js';
import DomainError from './domain-error.js';
import GatewayError from './gateway-error.js';
import InvalidArgumentError from './invalid-argument-error.js';
import throwError from './throw-error.js';

export default class UserAuthentication {
    #repository;
    #emailGateway;
    #hashService;
    #tokenService;

    constructor(
        repository,
        emailGateway,
        passwordHash,
        tokenService
    ) {
        this.#repository = repository;
        this.#emailGateway = emailGateway;
        this.#hashService = passwordHash;
        this.#tokenService = tokenService;
    }
}

Como JS é uma linguagem de tipagem fraca, vamos criar algo que valide a instância dos objetos recebidos, para isso vamos criar um novo arquivo para fazer essa validação:

// src/domain/intanceof.js
const isInstanceOf = (instance, instanceBase) => instance instanceof instanceBase;

export default isInstanceOf;

Agora importamos em UserAuthentication e vamos validar as entradas:

import IRepository from './irepository.js';
import IEmail from './iemail.js';
import IPasswordHash from './ipassword-hash.js';
import IGenerateToken from './igenerate-token.js';
import isInstanceOf from './instanceof.js';
import DomainError from './domain-error.js';
import GatewayError from './gateway-error.js';
import InvalidArgumentError from './invalid-argument-error.js';
import throwError from './throw-error.js';

export default class UserAuthentication {
    #repository;
    #emailGateway;
    #hashService;
    #tokenService;

    constructor(
        repository,
        emailGateway,
        passwordHash,
        tokenService
    ) {
        this.#validateDependencies(repository, emailGateway, passwordHash, tokenService);
        this.#repository = repository;
        this.#emailGateway = emailGateway;
        this.#hashService = passwordHash;
        this.#tokenService = tokenService;
    }

    #validateDependencies(repository, emailGateway, passwordHash, tokenService) {
        if (!this.#isInstanceOf(repository, IRepository)) {
            throwError(DomainError, 'Invalid repository dependency');
        }

        if (!this.#isInstanceOf(emailGateway, IEmail)) {
            throwError(DomainError, 'Invalid email gateway dependency');
        }

        if (!this.#isInstanceOf(passwordHash, IPasswordHash)) {
            throwError(DomainError, 'Invalid hash service dependency');
        }

        if (!this.#isInstanceOf(tokenService, IGenerateToken)) {
            throwError(DomainError, 'Invalid token service dependency');
        }
    }

    #isInstanceOf(object, instanceBase) {
        return isInstanceOf(object, instanceBase);
    }
}

Antes de criarmos nosso método de autenticação, vamos criar duas classes, uma que vai encapsular os dados de entrada, e outra que vai encapsular os dados do usuário que vem do banco:

// src/domain/login-payload.js
import InvalidArgumentError from './invalid-argument-error.js';
import throwError from './throw-error.js';

export default class LoginPayload {
    #email;
    #password;

    constructor(email, password) {
        if (!email || !password) {
            throwError(InvalidArgumentError, 'Fields email and password must be filled!');
        }

        this.#email = email;
        this.#password = password;
    }

    get email() {
        return this.#email;
    }

    get password() {
        return this.#password;
    }
}

// src/domain/user.js
import DomainError from'./domain-error.js';
import throwError from './throw-error.js';

export default class User {
    token;
    emailToken;

    #id;
    #email;
    #password;
    #expired;

    constructor({id, email, password, token, emailToken, expired}) {
        if (!id || !email || !password) {
            throwError(DomainError, 'Invalid user data!')
        }

        this.#id = id;
        this.#email = email;
        this.#password = password;
        this.token = token;
        this.emailToken = emailToken;
        this.#expired = expired;
    }

    get id() {
        return parseInt(this.#id);
    }

    get expired() {
        return !!this.#expired;
    }

    get email() {
        return this.#email;
    }

    get password() {
        return this.#password;
    }
}

Importem essas classes na nossa classe de negócio, e agora vamos implementar nossa lógica de autenticação, observe o fluxo abaixo:

async authenticate(loginPayload) {
        this.#validateUserDataInput(loginPayload);
        const registeredUser = await this.getUserRegistered(loginPayload);

        try {
            const user = this.#getUserWithUpdatedData(registeredUser);
            await this.#repository.update(user);
            this.#emailGateway.send(user);
            return user.token;
        } catch (error) {
            throwError(GatewayError, 'Generic error, see the integrations!');
        }
    }

    #validateUserDataInput(loginPayload) {
        if (!this.#isInstanceOf(loginPayload, LoginPayload)) {
            throwError(DomainError, 'Invalid payload dependency');
        }
    }

    async getUserRegistered(user) {
        let registeredUser = null;

        try {
            registeredUser = await this.#repository.findByEmail(user.email);
        } catch (e) {
            throwError(GatewayError, 'Error connection database!');
        }

        return this.#getUserValidated(registeredUser, user);
    }

    async #getUserValidated(registeredUser, user) {
        if (!registeredUser) {
            throwError(InvalidArgumentError, 'User not found with data sent!');
        }

        if (!this.#isInstanceOf(registeredUser, User)) {
            throwError(DomainError, 'Invalid user instance!');
        }

        const passwordsAreEquals = await this.#hashService.compare(user.password, registeredUser.password);

        if (!passwordsAreEquals) {
            throwError(InvalidArgumentError, 'Invalid user data!');
        }

        return registeredUser;
    }

    #isInstanceOf(object, instanceBase) {
        return isInstanceOf(object, instanceBase);
    }

    #getUserWithUpdatedData(user) {
        return new User({
            id: user.id,
            email: user.email,
            ...this.#getTokens(),
            password: user.password,
            expired: false
        });
    }

    #getTokens() {
        return {
            token: this.#tokenService.getToken(),
            emailToken: this.#tokenService.getEmailToken()
        }
    }
}

Temos o método authenticate que recebe um objeto de entrada, é feita a validação desse objeto, depois é feita a busca do usuário pelo e-mail e novamente validamos o objeto recebido, e por último validamos a senha. Volte ao código acima e veja que a gente envolve algumas chamadas em try/catch e em caso de erro, ou validações mal sucedidas, lançamos sempre as nossas classes de erros personalizados.

Após obtermos o usuário válido com a chamada do método #getUserRegistered, nós vamos criar um outro objeto, contendo tanto as informações do usuário do banco, como também as informações dos tokens. Tudo isso chamando o método #getUserWithUpdatedData, após isso, a gente chama o método de atualização do banco, depois manda os dados necessários por e-mail e retornamos um dos tokens gerados.

Note que o método de envio de e-mail, não esperamos o fim da execução, pois provavelmente o envio de e-mail seja um processo demorado, que pode travar a execução do nosso sistema.

Agora observem o objeto User, e principalmente o campo expired, esse campo é o responsável por verificar se os tokens enviados já foram utilizados ou não (trabalharemos nisso depois). Fazendo com que um par de tokens seja utilizado apenas uma vez.

Por fim, o arquivo user-authentication, deverá ficar com o conteúdo abaixo:

import User from './user.js';
import IRepository from './irepository.js';
import IEmail from './iemail.js';
import IPasswordHash from './ipassword-hash.js';
import IGenerateToken from './igenerate-token.js';
import LoginPayload from './login-payload.js';
import isInstanceOf from './instanceof.js';
import DomainError from './domain-error.js';
import GatewayError from './gateway-error.js';
import InvalidArgumentError from './invalid-argument-error.js';
import throwError from './throw-error.js';

export default class UserAuthentication {
    #repository;
    #emailGateway;
    #hashService;
    #tokenService;

    constructor(
        repository,
        emailGateway,
        passwordHash,
        tokenService
    ) {
        this.#validateDependencies(repository, emailGateway, passwordHash, tokenService);
        this.#repository = repository;
        this.#emailGateway = emailGateway;
        this.#hashService = passwordHash;
        this.#tokenService = tokenService;
    }

    #validateDependencies(repository, emailGateway, passwordHash, tokenService) {
        if (!this.#isInstanceOf(repository, IRepository)) {
            throwError(DomainError, 'Invalid repository dependency');
        }

        if (!this.#isInstanceOf(emailGateway, IEmail)) {
            throwError(DomainError, 'Invalid email gateway dependency');
        }

        if (!this.#isInstanceOf(passwordHash, IPasswordHash)) {
            throwError(DomainError, 'Invalid hash service dependency');
        }

        if (!this.#isInstanceOf(tokenService, IGenerateToken)) {
            throwError(DomainError, 'Invalid token service dependency');
        }
    }

    async authenticate(loginPayload) {
        this.#validateUserDataInput(loginPayload);
        const registeredUser = await this.#getUserRegistered(loginPayload);

        try {
            const user = this.#getUserWithUpdatedData(registeredUser);
            await this.#repository.update(user);
            this.#emailGateway.send(user);
            return user.token;
        } catch (error) {
            throwError(GatewayError, 'Generic error, see the integrations!');
        }
    }

    #validateUserDataInput(loginPayload) {
        if (!this.#isInstanceOf(loginPayload, LoginPayload)) {
            throwError(DomainError, 'Invalid payload dependency');
        }
    }

    async #getUserRegistered(user) {
        let registeredUser = null;

        try {
            registeredUser = await this.#repository.findByEmail(user.email);
        } catch (e) {
            throwError(GatewayError, 'Error connection database!');
        }

        return this.#getUserValidated(registeredUser, user);
    }

    async #getUserValidated(registeredUser, user) {
        if (!registeredUser) {
            throwError(InvalidArgumentError, 'User not found with data sent!');
        }

        if (!this.#isInstanceOf(registeredUser, User)) {
            throwError(DomainError, 'Invalid user instance!');
        }

        const passwordsAreEquals = await this.#hashService.compare(user.password, registeredUser.password);

        if (!passwordsAreEquals) {
            throwError(InvalidArgumentError, 'Invalid user data!');
        }

        return registeredUser;
    }

    #isInstanceOf(object, instanceBase) {
        return isInstanceOf(object, instanceBase);
    }

    #getUserWithUpdatedData(user) {
        return new User({
            id: user.id,
            email: user.email,
            ...this.#getTokens(),
            password: user.password,
            expired: false
        });
    }

    #getTokens() {
        return {
            token: this.#tokenService.getToken(),
            emailToken: this.#tokenService.getEmailToken()
        }
    }
}

Teste

Agora que nossa lógica foi feita, vamos testar todos os fluxos. Acesse o terminal do container e rode o comando abaixo para instalar o Jest:

npm i --save-dev jest

Instamos essa biblioteca somente como dependência de desenvolvimento. Outra coisa que faremos é alterar o comando padrão de testes, para que ele chame o Jest, então, em nosso arquivo package.json, altere ele modificando o campo script para isso:

"scripts": {
    "test": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js ./tests/* --coverage --config='{ \"coverageReporters\": [\"html\"] }'\n"
  }

E agora vamos criar nossos testes, dentro do diretório tests, crie um diretório chamado unit, e dentro dele um diretório chamado mocks, essa pasta mocks vai servir para armazenar todas as implementações das interfaces do domínio. Poderíamos utilizar alguma lib para fazer isso, mas eu preferi fazer tudo na mão, então dentro de mocks, crie os arquivos abaixo contendo os seguintes códigos:

// tests/unit/mocks/email-mock.js
import IEmail from '../../../src/domain/iemail.js';

class EmailMock extends IEmail {
    throwException = false;

    send(user) {
        if (this.throwException) {
            throw Error();
        }
        return Promise.resolve('Sent!');
    }
}

export default new EmailMock();

// tests/unit/mocks/repository-mock.js
import IRepository from '../../../src/domain/irepository.js';
import User from '../../../src/domain/user.js';

class RepositoryMock extends IRepository {
    throwException = false;
    throwExceptionUpdate = false;
    returnEmptyObject = false;
    returnEmpty = false;

    constructor() {
        super();
    }

    findByEmail(email) {
        if (this.throwException) {
            throw Error();
        }

        if (this.returnEmpty) {
            return '';
        }

        if (this.returnEmptyObject) {
            return {};
        }

        const user = new User({id: 1, email: 'erandir@email.com', password: '123456'});

        return Promise.resolve(user);
    }

    update(user) {
        if (this.throwExceptionUpdate) {
            throw Error();
        }
        return Promise.resolve(true);
    }
}

export default new RepositoryMock();

// tests/unit/mocks/hash-mock.js
import IPasswordHash from '../../../src/domain/ipassword-hash.js';

class HashMock extends IPasswordHash {
    passwordsAreEquals = true;

    constructor() {
        super();
    }

    compare(password, hash) {
        return this.passwordsAreEquals;
    }
}

export default new HashMock();

// tests/unit/mocks/token-mock.js
import IGenerateToken from '../../../src/domain/igenerate-token.js';

class TokenMock extends IGenerateToken {
    constructor() {
        super();
    }

    getToken() {
        return '13eb4cb6-35dd-4536-97e6-0ed0e4fb1fb3'
    }

    getEmailToken() {
        return  '4RV651gR93hDAGiTCYhmhh';
    }
}

export default new TokenMock();

Agora dentro de tests/unit, crie um arquivo chamado user-authentication.test.js, é nesse arquivo que escreveremos todos os nosso testes para a classe UserAuthentication:

import UserAuthentication from '../../src/domain/user-authentication.js';
import EmailMock from './mocks/email-mock.js';
import RepositoryMock from './mocks/repository-mock.js';
import HashMock from './mocks/hash-mock.js';
import TokenMock from './mocks/token-mock.js';
import LoginPayload from '../../src/domain/login-payload.js';
const payload = new LoginPayload('erandir@email.com', '1234567');
const userAuthentication = new UserAuthentication(
    RepositoryMock,
    EmailMock,
    HashMock,
    TokenMock
);

test('Invalid object repository', function () {
    const result = () => new UserAuthentication(
        {},
        EmailMock,
        HashMock,
        TokenMock
    );
    expect(result).toThrow('Invalid repository dependency');
});

test('Invalid object email', function () {
    const result = () => new UserAuthentication(
        RepositoryMock,
        {},
        HashMock,
        TokenMock
    );
    expect(result).toThrow('Invalid email gateway dependency');
});

test('Invalid object hash', function () {
    const result = () => new UserAuthentication(
        RepositoryMock,
        EmailMock,
        {},
        TokenMock
    );
    expect(result).toThrow('Invalid hash service dependency');
});

test('Invalid object token', function () {
    const result = () => new UserAuthentication(
        RepositoryMock,
        EmailMock,
        HashMock,
        {}
    );
    expect(result).toThrow('Invalid token service dependency');
});

test('Invalid object login payload', async () => {
    const result = async () => await userAuthentication.authenticate({});
    expect(result).rejects.toThrow('Invalid payload dependency');
});

test('Error exception find user', async () => {
    RepositoryMock.throwException = true;
    const result = async () => await userAuthentication.authenticate(payload);
    expect(result).rejects.toThrow('Error connection database!');
});

test('Error find user empty', async () => {
    RepositoryMock.throwException = false;
    RepositoryMock.returnEmpty = true;
    const result = async () => await userAuthentication.authenticate(payload);
    expect(result).rejects.toThrow('User not found with data sent!');
});

test('Error user without id', async () => {
    RepositoryMock.returnEmpty = false;
    RepositoryMock.returnEmptyObject = true;
    const result = async () => await userAuthentication.authenticate(payload);
    expect(result).rejects.toThrow('Invalid user instance!');
});

test('Error update user', async () => {
    RepositoryMock.returnEmptyObject = false;
    RepositoryMock.throwExceptionUpdate = true;
    const result = async () => await userAuthentication.authenticate(payload);
    expect(result).rejects.toThrow('Generic error, see the integrations!');
});

test('Error email exception', async () => {
    RepositoryMock.throwExceptionUpdate = false;
    EmailMock.throwException = true;
    const result = async () => await userAuthentication.authenticate(payload);
    expect(result).rejects.toThrow('Generic error, see the integrations!');
});

test('Error user divergent password', async () => {
    EmailMock.throwException = false;
    HashMock.passwordsAreEquals = false;
    const result = async () => await userAuthentication.authenticate(payload);
    expect(result).rejects.toThrow('Invalid user data!');
});

test('Get token', async () => {
    HashMock.passwordsAreEquals = true;
    const result = await userAuthentication.authenticate(payload);
    expect(result).toBe('13eb4cb6-35dd-4536-97e6-0ed0e4fb1fb3');
});

Importamos as dependências e fizemos todos os testes em cima da nossa classe de negócios, seja passando dados errados, ou gerando exceção, passando por todos os caminhos errados, para só no final realizarmos o teste de caminho feliz.

Antes de executarmos nossos testes, precisamos configurar a modularização do nosso projeto, que por padrão é a do commonjs, e em nosso caso, utilizamos a do es6 module, então precisamos informar isso nas configurações, modifique o arquivo package.json e deixe-o assim:

{
  "name": "nome_do_seu_projeto",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "directories": {
    "test": "tests"
  },
  "scripts": {
    "test": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js ./tests/* --coverage --config='{ \"coverageReporters\": [\"html\"] }'\n"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "jest": "^29.2.2"
  },
  "type": "module"
}

Vá ao terminal do serviço node e executar o código abaixo:

npm t

Será executado todos os teste e após isso uma pasta chamada coverage será criada na raiz do projeto. Dentro de coverage, vai ter inúmeros arquivos html, procure o index.html e abra ele no seu navegador. Você notará que temos um relatório de cobertura de testes, onde sabemos o que foi testado, o que falta testar, etc. Isso é muito útil.

Tópicos interessantes

Sabe-se que em JavaScript, podemos definir objetos de algumas formas diferentes, nesse projeto, fiz uso de classes, que é algo mais recente, isso porque tenho mais familiaridade com essa forma. O projeto inteiro poderia ter sido feito utilizando objetos literais, funções construtoras, etc.

Ainda falando sobre classes, perceba que para criar atributos e métodos privados, eu faço uso do caractere #, que também é um recurso recente. Outro detalhe fica por conta das subclasses, que sempre definimos um construtor e que sempre o primeiro comando é chamar o construtor do pai.

Além disso, percebam como estamos isolando nossa camada de regra de negócio, dependemos sempre de interfaces, isso nos possibilita simular comportamentos, o que nos ajudou nos testes.

Se você é um desenvolvedor mais experiente, possivelmente pode ter notado que não implementei uma validação importante, que é se os tokens gerados são únicos, isso foi de certa forma proposital, caso alguém queira mexer no código, alterar e adicionar essa validação.

E sobre a questão da modularização do projeto, caso quiséssemos utilizar a padrão, que é o commonjs, iriamos substituir os comando de exportar e importar, por exemplo:

// es6 Module
export default class InvalidArgumentError extends Error {
    constructor(message) {
        super(message);
    }
}

// E para importar fazemos assim
import InvalidArgumentError from './invalid-argument-error.js';

// Em commonjs fariamos da seguinte forma
module.exports = class InvalidArgumentError extends Error {
    constructor(message) {
        super(message);
    }
}

// E para importar faríamos assim
const InvalidArgumentError = require('./invalid-argument-error.js');

Existem algumas pequenas diferenças entre usar uma ou outra, mas eu gosto de utilizar a modularização do ES6.

Resumo

Neste artigo, começamos a montar nosso projeto, criamos testes, relatório de teste, aprendemos a importar e exportar módulos, validamos objetos, etc. Vale a pena notar que essa aqui foi a minha linha de raciocínio, talvez você tenha pensado em uma forma diferente de fazer tudo que fiz nessa primeira parte, você pode implementar do jeito. Continuaremos desenvolvendo nossa lógica no próximo artigo, até lá.

Construindo aplicação do zero com node.js: Parte 1

Erandir Junior — Thu, 03 Nov 2022 14:55:50 +0000

Fala devs, no mundo do desenvolvimento, para você melhorar ou adquirir uma nova habilidade, não tem como fugir da prática. E eu precisa desenvolver algo para melhorar minhas habilidades em node.js, além é claro de poder ajudar os outros. E depois de muito pensar, resolvi desenvolver o projeto descrito abaixo.

Two-Factor Authentication

Um sistema de autenticação em 2 fatores, nada mais é do que se autenticar em um sistema em duas formas. Diferentemente de acessar um sistema qualquer com apenas o seu e-mail e senha, neste outro tipo de sistema, você posteriormente deve informar alguma outra informação, que provavelmente foi enviada por e-mail, ligação, sms, etc.

Um exemplo claro disso são os sistemas do Google, normalmente quando acesso minha conta de algum equipamento "desconhecido", é necessário que eu informe um código que aparece na tela do meu smartphone.

Motivo

Falei inicialmente sobre praticar, mas eu também queria mostrar como fazer algo do zero, não que uma aplicação desse nível seja algo extremamente complexo, mas eu acho útil e bem diferente dos padrões de crud.

Tecnologia

Para quem não conhece, node é um plataforma que nos permite utilizar JavaScript para desenvolver do lado servidor/backend. Caso você não conheça, essa é uma ótima forma de aprender, ou caso já tenha familiaridade, nada melhor do que praticar, não é mesmo?

Algo que posso dizer é que não utilizei TypeScript, então por esse motivo tive certas "limitações" digamos assim, que pude contornar obviamente, porém trazendo um pouco de complexidade ao projeto.

Outros pontos importantes foram o uso de docker para auxiliar no desenvolvimento, testes, além de aplicar o conceito da arquitetura hexagonal para organizar a aplicação.

Aprendizado

Acredito que mesmo os sistemas mais simples podem te ensinar bastante, e eu por exemplo, aprendi muito, posso destacar de antemão uma maior prática de testes. Inicialmente utilizei a biblioteca mocha para me ajudar, construindo todo o código com a modularização do commonjs, e no final fiz a conversão para o ES6 module. O que me deu uma dorzinha de cabeça.

Essa "pequena" alteração, fez com que eu tivesse uma perda um tanto importante: não consegui gerar o relatório de cobertura de testes. A biblioteca utilizada tinha um certa limitação com o ES6 module, e aí que resolvi mudar para o Jest- outra ferramenta de testes - aí refatorei os testes e consegui voltar com o relatório de cobertura, como podem ver abaixo:

Apesar de algumas coisas não terem um nível tão alto de cobertura, a parte central da aplicação src/domain, está 100% testada, sendo realizado testes unitários e de ponta a ponta.

Prepare-se

Se você realmente quer seguir e executar os códigos dos próximos artigos, um pouco de conhecimento em JS e Docker são imprescindíveis.

Projeto

Nos próximos artigos vou detalhar a construção do sistema, informando escolhas, bibliotecas, melhorias, etc. E antes que me esqueça, já vou deixando aqui o link para o código fonte, seja para estudar, utilizar, melhorar, ou mesmo ignorar completamente.

Vejo vocês nos próximos artigos.

PlugRoute: Refactoring, Clean Code, etc.

Erandir Junior — Tue, 16 Aug 2022 21:26:00 +0000

Há aproximadamente 2 anos, resolvi criar uma lib em PHP como forma de praticar conhecimento, além é claro, de ajudar outros devs. Na época, não fiz nada muito complexo, a ideia foi fazer uma biblioteca de rotas, parecido com o que os frameworks tem, só que mais simples.

O tempo passou, adicionei mais recursos a ela, também cometi erros ao "abandonar" os testes, um grande pecado diga-se de passagem. A biblioteca não era mais tão confiável. Foi nesse momento que pensei em refatorar-la, e aplicar algumas técnicas que tinha aprendido.

Passo 1: Analisar o código

Os códigos abaixo são referentes a versão 4.4 da biblioteca. No primeiro exemplo vamos ver como definimos uma rota:

$route->get('/', function() {
    echo 'basic route';
});

O código acima é bem parecido com outras bibliotecas e até pode parecer inofensivo, porém se você for analisar com um pouco mais de calma, verá que temos um problema.

Agora te mostro um exemplo mais complexo, passando algumas configurações extras em um agrupamento de rotas:

$route->group(['prefix' => '/sports', 'middlewares' => [OtherMiddleware::class], 'namespace' => 'Controllers\\'], function($route) {
    $route->get('/soccer', function () {
        return 'Index Page';
    })->name('index');

    $route->get('/soccer', 'SoccerController@index')->name('soccer');
    $route->get('/f1', 'SoccerController@index')->name('f1');
    $route->get('/boxing', 'BoxingController@index')->name('boxing');
    $route->get('/motorcycling', 'MotorcyclingController@index')->name('motorcycling');
    $route->get('/tennis', 'TennisController@index')->name('tennis');
});

Passo 2: Entender o problema

Eu me incomodava ao ver o código acima, principalmente mas não exclusivamente pelos motivos abaixo:

O callback de um rota, no caso o segundo parâmetro, pode ser tanto uma função anônima quanto uma classe. Isso trás uma confusão para quem lê e usa o código.
E o segundo motivo é que as configurações de um grupo de rotas são do tipo array, o que poderia causar confusão com os nomes das chaves ou mesmo informações que acabam dificultando a leitura do código.

Em resumo, eu queria um código mais legível, testado, confiável. Era necessário refatorar essa biblioteca, tirar comportamentos estranhos, torná-la mais agradável para quem a usasse.

Passo 3: Refatorando

Comecei a refatorar a aplicação, aplicando conhecimentos adquiridos após a leitura do livro Clean Code, como também conhecimentos adquiridos de outros livros, artigos e vídeos. E aos poucos pude notar alguns ganhos, tanto estéticos quanto funcionais. Vejam como ficou o código na versão mais nova da lib:

$this->plugRoute
    ->get('/people/{id}')
    ->callback(function (Request $request) {
        return $request->parameter('id');
    })
    ->rule('id', '\d+')
    ->name('people.get.id');

A primeira coisa que apliquei foi nomear melhor as ações para evitar ambiguidades e confusões, melhorar a tipagem dos parâmetros, e também usar o conceito de Interface Fluente, um nome chique para esse aninhamento de chamadas, muito utilizado em ORMs.

Um ponto que ficou bem mais legível, e que talvez ainda possa ser melhorado foi em relação ao callback da rota, no exemplo acima tem uma ação para quem quiser usar uma função, e no exemplo abaixo, mostro um exemplo para quem quiser usar uma classe, dessa forma temos métodos diferentes que definem ações diferentes.

$this->plugRoute
    ->get('/people/{id}')
    ->controller(MyController::class, 'method')
    ->rule('id', '\d+')
    ->name('people.get.id');

Em relação a definir um agrupamento de rotas, e consequentemente passar algumas configurações extras, foi definido métodos para cada configuração, evitando a passagem de array e tornando o código mais legível:

$route
    ->middleware(MiddlewareA::class, MiddlewareB::class)
    ->middleware(MiddlewareC::class)
    ->namespace('\\MyNamespace')
    ->prefix('/sports')
    ->group(function ($route) {
        $route->get('/xadrez')->controller("PlugRoute\\Example\\Home", "rankingXadrez");

        $route->prefix('/f1')
            ->group(function ($route) {
                $route->get('/ranking')
                    ->controller("PlugRoute\\Example\\Home", "rankingF1");
            });

        $route->middleware('MiddlewareSoccer')
            ->prefix('/soccer')
            ->namespace("PlugRoute\\")
            ->group(function ($route) {
                $route->get('/champions-league')
                    ->controller("PlugRoute\\Example\\Home", "rankingChampions");
                $route->get('//europe-league')
                    ->controller("PlugRoute\\Example\\Home", "rankingEurope");
            });
    });

Na minha visão, o código ficou muito mais claro de entender e usar. Claro, toda essa refatoração teve um preço, alguns recursos foram removidos, seja em definitivo ou mesmo para serem adicionados posteriormente.

Passo 4: Usar recursos da linguagem

Alguns recursos que utilizei podem até ferir o Clean Code, como no caso da passagem de middlewares, prefixos ou mesmo namespaces, em cada método dessas ações, você pode passar apenas um dado, ou vários em uma mesma chamada. Para mim, era um recurso precioso que não poderia deixar de usar nesse caso.

Passo 5: Usar recursos da comunidade

As PSRs estão aí para criar uma padronização e consequentemente melhorar o código para um entendimento geral. Porém optei por não seguir algumas, por exemplo, a PSR-7 não é implementada única e exclusivamente por motivos pessoais, lembrando que esse componente, inicialmente era algo somente para praticar, e hoje ainda é. Isso não quer dizer que você não possa utilizá-la em uma aplicação profissional, pelo contrário, eu mesmo já utilizei em 2 ou 3 projetos reais.

Passo 6: Nível de testes

Uma coisa que havia falhado anteriormente era em relação a cobertura de testes, mas dessa vez fiz minha redenção, apliquei um conjunto de testes sobre a aplicação, chegando a 97% de cobertura, e com a tendência de que aos poucos e espero que com ajuda, possa chegar a 100%.

E por fim a cooperação

Bem, refatorei a biblioteca, corrigir vários pontos, apliquei uma cobertura de testes minimamente decente, porém isso não é tudo, desde o primeiro commit, esse componente foi pensado em praticar e desenvolver minhas habilidades, mas muito além disso, foi pensando em receber ajuda comunitária, ou pelo menos ajudar devs iniciantes a entender como funcionam alguns recursos de um framework.

Então, esse não é um projeto fechado, se alguém quiser estudar o código, corrigir, melhorar ou adicionar algo, fique a vontade. Por hoje é só e até o próximo artigo.

#SQL na unha: recursos do SGBD

Erandir Junior — Thu, 03 Feb 2022 15:52:25 +0000

Seja muito bem vindo, caso seja sua primeira vez aqui, saiba que este é o 4º artigo abordando sobre banco de dados. Confira abaixo os artigos anteriores antes de prosseguir a leitura deste:

Resumão

Nos artigos anteriores, vimos como criar um banco, tabelas e como manipular registros. Aquilo tudo é o básico para que uma pessoa consiga fazer uma atividade de um nível de complexidade não muito alta.

Caso ainda não tenha percebido, o conteúdo passado até agora é só uma fração dos inúmeros recursos disponíveis. Veremos hoje mais alguns mecanismos à nossa disposição. Apesar de tudo, deixo aqui novamente a minha recomendação para que visite a documentação do SGBD utilizado.

Funções da data

Não importa a linguagem que esteja utilizando, não é nada fácil manipular uma data. Pensando nisso, vamos ver alguns recursos que podem simplificar nossa vida, vejam abaixo:

select now(); -- retorna a data e hora atual

select year('2000-01-01'); -- retorna o ano da data informada

select month('2010-10-12');  -- retorna o mês da data informada

select monthname('2014-01-07'); -- retorna o nome do mês da data informada

select day(now()); -- retorna o dia da data informada

select dayname(now()); -- retorna o nome do dia da data informada

select dayofmonth(now()); -- retorna o dia do mês da data passada

select dayofweek(now()); -- retorna o dia da semana, onde domingo = 1, segunda = 2, terça = 3, quarta = 4, quinta = 5, sexta = 6, sábado = 7

select dayofyear(now()); -- retorna o dia do ano da data informada

select datediff('2022-06-07', '2020-06-07'); -- retorna a diferença em dias, das datas duas datas informadas

select date_add(now(), INTERVAL 10 DAY); -- retorna uma data incrementada nos dias informados

select date_add(now(), INTERVAL 3 MONTH); -- retorna uma data incrementada nos meses informados

select date_add(now(), INTERVAL 4 YEAR); -- retorna uma data incrementada nos anos informados

select date_add(now(), INTERVAL 5 HOUR); -- retorna uma data incrementada nas horas informadas

select date_format(now(), '%d/%m/%Y'); -- retorna uma data formatada

select date_format(now(), '%d/%m/%y %H:%i:%s'); -- outro exemplo de formatação de data, lembrando que letras maiúsculas e minúsculos alteram o formato de saída

Funções de String

Assim como existem funções para manipulação de datas, também temos funções para manipulação de strings, vejamos algumas delas:

select concat('a', 'b','c', '...'); -- concatena os dados passados

select concat_ws(',', 'a', 'b','c', '...'); -- concatena os dados enviados pelo separador informado no primeiro parâmetro

select char_length('erandir'); -- retorna o tamanho da string

select character_length('erandir'); -- retorna o tamanho da string

select replace(email, 'email', 'company') as email from user; -- substitui um parte da string por nos valores da coluna informada no primeiro parâmetro

Funções de fluxo

Algumas vezes queremos retornar um valor alternativo se o valor de um determinado campo estiver vazio, para isso, temos uma função específica, veja seu uso:

select IFNULL(description, 'Campo vazio') as description from product;

Podemos aplicar uma condição para retornar um valor específico:

select if (value >= 2000, 2000 - (2000 * 0.1), value) as product_price from product; -- se o valor do produto for maior ou igual a 2000, damos um desconto de 10%, caso não, retorna o valor normal do produto

Funções agregadas

Podemos verificar a quantidade de registros em uma tabela:

select count(id) as total from user;

Podemos pegar a média de valor de alguma coluna:

select avg(value) as total from product; -- é somado todos os valores da coluna informada e dividido pela quantidade de registros

Podemos pegar o maior valor de uma determinada coluna:

select max(value) as max from product;

Podemos pegar o menor valor de uma determinada coluna:

select min(value) as min from product;

Finalizando

Vimos mais uma série de funcionalidades bem úteis, mesmo assim, volto a dizer que a melhor amiga de vocês é a documentação. Minha dica final é que pratiquem bastante, e caso queiram se aprofundar ainda mais a documentação é o caminho. Por hoje é só, até mais.

#SQL na unha: manipulando dados

Erandir Junior — Tue, 01 Feb 2022 15:35:25 +0000

Se é a primeira que está aqui, saiba que essa é a terceira parte de uma série de artigos abordando banco de dados. E para te ajudar, já deixo aqui os links para que leio tanto o primeiro quanto o segundo artigo. Agora vamos para o que interessa.

Inserindo dados

Podemos fazer uma inserção informando os campos que devem ser preenchidos, lembre-se que a ordem importa:

insert into user (id, name, email, updated_at, created_at) value (1, 'erandir', 'erandir@email.com', now(), now());

Podemos fazer uma inserção apenas seguindo a ordem das colunas definidas na tabela:

insert into user value (2, 'maria', 'maria@email.com', now(), now());

Podemos fazer uma inserção ignorando todos os campos com valores padrão, eles serão preenchidos pelo própio SGBD:

insert into user (name, email) value ('erandir junior', 'erandirjr@email.com');

Podemos fazer várias inserções de uma única vez:

insert into user (name, email) values ('joao', 'joao@email.com'), ('jessica', 'jessica@email.com'), ('ricardo', 'ricardo@email.com'), ('fernanda', 'fernanda@email.com'), ('jessica', 'jessica@email.com');

insert into product (name, value, description, user_id) values ('TV 50', 1000.00, 'Tv de 50 polegadas', 4), ('Smartphone', 2000.00, NULL, 5), ('Notebook', 1000.00, NULL, 6), ('Geladeira', 1000.00, 'Geladeira daquelas caras, que sai água da porta', 7);

Listando dados

Podemos listar todos os registros de uma tabela específica:

select * from user;

Não recomendo o uso do * em um select. Ele traz todas as colunas e muito provavelmente você não vai precisar de todas elas. Sempre liste somente o que você vai precisar.

Podemos exibir somente os registros das colunas informadas:

select name, email from user;

select email, name from user;

Podemos dar um apelido para as colunas especificadas:

select name, email, created_at as creation from user;

A cláusula WHERE, nos permite filtrar nossas listagens, observe bem e execute os comandos abaixo:

select id, name from user where id = 3; -- retorna apenas os dados com id igual a 3

select id, name from user where name = 'erandir'; -- retorna apenas os dados com name igual a erandir

select id, name from user where id > 4; -- retorna apenas os registros com o id sendo maior 4

select id, name from user where id < 3; -- retorna apenas os registros com id menor que 3

select id, name from user where id <> 1; -- retorna apenas os registros com id diferente de 1

select id, name from product where description IS NULL; -- retorna apenas os registros que tem o campo descrição como nulo

select id, name from product where description IS NOT NULL; -- retorna apenas os registros que tem o campo descrição preenchida

select id, name from user where id = 1 AND id = 2; -- retorna todos os registros que atendem às duas condições

select id, name from user where id = 1 OR id = 2; -- retorna todos os registros que atendem a uma das duas condições

O comando LIKE, permite verificar se um determinado valor está contido nos registros de uma coluna especificada:

select id, name, email from user where email like 'erandir%'; -- retorna todos os registros onde os valores da coluna informada começa com o dado passado, independente do que vier depois

select id, name, email from user where email like '%email%'; -- retorna todos os registros onde os valores da coluna informada contém o valor passado, independentemente se começa ou termina com  o valor informado

select id, name, email from user where email like '%email'; -- retorna todos os registros onde os valores da coluna informada termina com o dado passado, independente do que vier antes, neste caso não retorna nenhum registro pois não existe nenhum que termine com email

O comando ORDER BY, permite ordenar os registros retornados:

select id, name from user order by id desc; -- ordena de forma decrescente se baseando nos valores da coluna informada

select id, name from user order by id asc; -- ordena de forma crescente se baseando nos valores da coluna informada

O comando GROUP BY, ele nos permite agrupar registros idênticos das colunas informadas:

select name from user GROUP BY name; -- em nossa base, temos dados onde o nome 'jessica' é o mesmo, esse comando vai agrupar os registros duplicados em apenas 1

O comando INNER JOIN, permite juntar tabelas em uma listagem. Com esse comando, somente os registros das tabelas que atendem a condição informada serão listados:

SELECT
    *
FROM
    user
    INNER JOIN product ON product.user_id = user.id;
-- retorna todos os dados das tabelas user e product, onde o valor do campo user_id da tabela product for igual ao campo id da tabela user

Se olharmos o resultado da consulta acima, percebemos que a coluna name está contida nas duas tabelas, podemos ter algum erro ao tentar manipular essa coluna de alguma das duas tabelas especificamente. Para contornar isso, podemos adicionar apelidos as colunas:

SELECT
    U.name as user,
    U.email as email,
    P.name as product,
    P.value as value
FROM
    user U
    INNER JOIN product P ON P.user_id = U.id;

Um comando bem semelhante ao anterior é o LEFT JOIN, com ele, os registros retornados são todos os que estão na tabela anterior ao comando, e os que atendem a condição:

SELECT
    U.name as user,
    U.email as email,
    P.name as product,
    P.value as value
FROM
    user U
    LEFT JOIN product P ON P.user_id = U.id;
-- traz todos os resultados da tabela user e somente os dados da tabela product que atendem a condição

O comando RIGHT JOIN, faz o inverso do comando anterior. Oberserve bem a query abaixo e os resultados obtidos:

SELECT
    U.name as user,
    U.email as email,
    P.name as product,
    P.value as value
FROM
    product P
    RIGHT JOIN user U ON U.id = P.user_id;
-- traz apenas os dados da tabela product que atendem a condição, e todos os dados da tabela user

Precisei inverter a ordem das tabelas para trazer um resultado mais fácil de ser entendido.

A imagem abaixo mostra um resumo dos comandos JOIN, tanto os apresentados aqui, como outros que não mostrei:

Podemos fazer consultas utilizando subqueries:

select * from product where user_id = (select id from user where id = 6);

Continuando com subqueries, podemos fazê-las no início de um select:

select *, (select name from user where id = product.user_id) as user from product; --

Nos exemplos de subqueries exibidos, apenas um campo pode ser retornado da subquery.

Atualizando dados

Para atualizar um registro é muito simples, basta informar tabela, os campos e os novos valores:

update user set name = 'marcos', email = 'marcos@email.com' where id = 1; -- vai atualizar os campos name e email da tabela user onde o id for igual a 1

Lembre-se sempre de iniciar um comando UPDATE pela cláusula WHERE, caso vocês esqueçam do WHERE, todos os registros da tabela serão atualizados. Já tive muitos problemas por causa disso.

Deletando dados

Excluir um registro do nosso banco tão simples quando uma listagem, basta informar a tabela e uma recomendação minha: utilizar em conjunto com a cláusula WHERE.

delete from user where id = 1;

Novamente, lembre-se de iniciar um comando DELETE com a cláusula WHERE. Evite problemas.

Outro detalhe importante é que em nosso caso, não conseguiremos excluir um registro da tabela user, caso exista uma referência na tabela product, é necessário primeiro remover as referências:

delete from user where id = 4;
-- ERROR 1451 (23000): Cannot delete or update a parent row: a foreign key constraint fails (`dev_article`.`product`, CONSTRAINT `product_ibfk_1` FOREIGN KEY (`user_id`) REFERENCES `user` (`id`));

delete from product where id = 1; -- removemos primeiro o produto

delete from user where id = 4; -- e só então conseguimos remover no registro de user

Se pegarmos uma tabela com a mesma estrutura da tabela user, inserirmos 10 registros, depois apagarmos esses mesmo registros, e inserimos um novo registro novamente, veremos que a chave primária desse registro será 11 e não 1, como pode-se pensar. Isso ocorre por causa do índice da tabela, que sempre vai apontar para o próximo. Para resolver o problema acima, podemos usar o comando abaixo que irá limpar toda nossa tabela, e limpar o índice da mesma:

truncate table product;

Tome muito cuidado ao executar este comando.

Outros comandos...

Galera, gostaria de falar que esses não são os únicos comandos que existem, ok? Os que abordei aqui são os que normalmente mais utilizo. Recomendo um estudo por mais comandos como por exemplo: HAVING, LIMIT, UNION, etc, vasculhem a documentação.

Está sendo bem cansativo fazer estes artigos, é verdade, porém, está sendo muito gratificante, espero que estejam gostando.