DEV Community: Caio Flavio

D do SOLID - Inversão de dependências no Laravel

Caio Flavio — Tue, 07 Mar 2023 17:33:26 +0000

D do SOLID — Inversão de dependências no Laravel

Bom, você deve estar se perguntando por que a inversão de dependências é o D do SOLID e não o I. Pra começar, quase tudo em programação é derivado do inglês assim como essa definição que vem de Inversion Principle. Um conceito que foi definido por Robert C. Martin que diz:

Módulos de alto nível não devem depender de módulos de baixo nível. Ambos devem depender de abstrações.
Abstrações não devem depender de detalhes. Detalhes devem depender de abstrações.

A teoria sempre parece complicada, principalmente quando não entendemos todos os termos da definição. O ponto chave aqui é entender o que são módulos de alto e baixo nível, mas, também, o conceito de abstração. Vamos usar duas classes abaixo pra ilustrar esses conceitos:

UserRepository.php

UserService.php

No caso acima, ambas as classes são de alto nível, pois a UserService depende da classe UserRepository que, por sua vez, depende da classe Module\Database\DBConnection que é a nossa classe de baixo nível. Então, temos definido que:

Classe de alto nível: uma classe que possui dependências de outras classes pra ser executada.

Classe de baixo nível: uma classe que não possui dependências de outras classes.

Normalmente, utilizamos as classes de alto nível para descrever a nossa regra de negócio, e as classes de baixo nível para resolver detalhes da infraestrutura, como, por exemplo, a implementação da conexão com o banco de dados e/ou com o servidor de e-mail.

Nesse caso, estamos usando alguns padrões de projeto como o Service Pattern e o Repository Pattern que nos ajudam a separar as responsabilidades da nossa aplicação, onde a service tem a responsabilidade de encapsular parte da nossa regra de negócio e a repository tem a responsabilidade de persistir os dados de um contexto específico.

Não iremos entrar em detalhes sobre esses padrões de projeto porque não é o objetivo desse artigo, mas os princípios de SOLID são sempre utilizados em conjunto e é quase impossível falar do conceito de inversão de dependência sem utilizar os outros princípios, principalmente o princípio da responsabilidade única.

Então, de maneira bem resumida, quando falamos que as classes de alto nível não devem ser dependentes das classes de baixo nível estamos dizendo que a nossa regra de negocio não deve ser dependente de detalhes de infraestrutura.

Tá, mas e aí? O que são as abstrações? E qual problema há em depender de uma classe de alto nível?

Abstração é um conceito importante da Programação Orientada a Objetos e nós costumamos utilizar esse conceito quando pegamos um problema do mundo real, extraímos o seu contexto para nossas classes e descrevemos esse problema através de métodos e atributos que compõe a nossa classe.
Ou seja, nós criamos uma relação direta entre o comportamento do mundo real com a modelagem da nossa classe de modo que essa classe consiga lidar com o máximo de casos possíveis sem depender dos detalhes do problema. Para ilustrar isso, vamos criar a classe que realiza uma conexão com o banco de dados utilizando a extensão PDO nativa do PHP:

App/Modules/Database/DBConnection.php

Bom, nossa classe cumpre o requisito de conectar com o banco de dados, mas aqui temos o primeiro problema, nossa classe depende de muitos detalhes como: tipo de banco, nome de usuário, senha e o host.
E se o nosso sistema precisa se conectar em dois bancos diferentes? Pra evitar duplicarmos o código podemos abstrair esses dados pra que possamos reaproveitar nossa classe sempre que precisarmos conectar com um banco de dados sem ficarmos dependentes dos detalhes da implementação.

App/Modules/Database/DBConnection.php

Pronto, agora nossa classe não depende mais de detalhes de implementação, pois eles foram abstraídos em atributos da nossa classe. Bom, mas e quanto a depender de classes de alto nível?

O exemplo acima estamos fazendo uma implementação bem básica de conexão com o banco de dados, ainda seria necessário implementarmos muita coisa pra ter um módulo realmente funcional, como a consulta, a inserção, filtros etc.

No entanto, pra nossa sorte hoje existem muitas bibliotecas mantidas pela comunidade que já fazem a maior parte de abstração das operações com banco de dados. E, por isso, não precisamos ficar reinventando a roda, podemos apenas utilizar uma dessas bibliotecas pra facilitar e abstrair esse trabalho pra gente.

Quando trabalhamos com o Laravel Framework, normalmente utilizamos uma biblioteca já inclusa chamada Eloquent para realizar as operações com banco de dados. O Eloquent é um ORM que r̶e̶s̶o̶l̶v̶e abstrai muitos desses problemas relacionados ao banco de dados pra gente.

A principal vantagem de utilizar um ORM é que eles criam uma camada que abstrai os detalhes da implementação dos banco de dados, ou seja, ele não é dependente dos detalhes da implementação do banco de dados. Em um mundo perfeito, onde seguimos todas as recomendações e boas práticas do componente de ORM, caso seja necessário mudar de um banco MYSQL para um PGSQL, por exemplo, não precisaríamos nos preocupar em reescrever nada, pois os métodos do ORM se encarregariam de transformar as ações que são realizadas em um formato que o novo banco de dados é capaz de entender. Tá vendo aí a importância de não depender de detalhes de implementação? Quando menos dependemos dos detalhes mais abrangente é nosso código.

Bom, então vamos trocar a nossa implementação de banco de dados simples pelo Eloquent e ver como as coisas ficam:

App/Modules/User/Models/User.php

Utilizando poucas linhas de código temos uma classe que é responsável por representar a nossa tabela de usuários. Além disso podemos fazer inúmeras ações como criar usuários, atualizar usuários, consultas simples e complexas, mesmo que você não esteja familiarizado, é só seguir a documentação que é bem completa e repleta de exemplos.

Agora, vamos criar a interface e a classe que será responsável pela persistência de dados, para inversão de dependência precisamos definir o contrato da nossa classe, que será a abstração da qual vamos depender.

App\Modules\User\Repositories\UserRepositoryInterface.php

Tests\Unit\App\Modules\User\Repositories\UserRepositoryTest.php

A interface é a camada de abstração da qual nós vamos depender, lembra que no início falamos que devemos depender de abstrações e não de implementações? É exatamente isso que estamos fazendo, mas ainda não estamos prontos, se você tentar executar o teste nesse ponto provavelmente vai se deparar com o seguinte erro:

Target [App\Modules\User\Repositories\UserRepositoryInterface] is not instantiable while building [App\Modules\User\Services\UserService]

Por que não podemos instanciar as interfaces diretamente, eles funcionam apenas como um maneira de criar um "contrato", que diz como a nossa classe vai se comportar, e nesse contrato declaramos os métodos que ela possui e o retorno esperado de cada método. Por isso, agora iremos fazer a implementação desse nosso contrato.

App\Modules\User\Repositories\UserRepositoryEloquent.php

Agora que temos a nossa camada de persistência podemos criar nossa camada de serviço que será responsável pelas regras de negócio da nossa aplicação.

App\Modules\User\Services\UserService.php

Agora que chegamos nesse ponto, ao rodar o teste novamente ainda nos depararemos com o mesmo erro, pois precisamos dizer ao Laravel qual a classe concreta da nossa interface, e ele nos permite fazer esse mapeamento por meio dos Service Providers. Ou seja, ele se encarrega de criar uma referência entre a nossa camada de abstração e a implementação, para isso basta apenas adicionar uma linha no arquivo abaixo:

App\Providers\AppServiceProvider.php

Com o código adicionado na linha 18, o Laravel se encarrega de toda vez que instanciamos a nossa interface ele faz a referência entre a abstração e a implementação. Mas qual a vantagem desse trabalho todo?

Deixar nosso código flexível e bem definido. Vamos supor que as necessidades da sua aplicação tenham evoluído a um ponto que as ferramentas que o Eloquent oferece não são suficientes para resolver algum desafio encontrado, nosso código não é dependente do Eloquent e com poucas linhas de código seriamos capazes de trocar o ORM da nossa aplicação.

App\Modules\User\Models\UserOtherORM.php

App\Modules\User\Models\UserRepositoryORM.php

Com as classes criadas, agora basta apenas alteramos a referências de service provider.

App\Providers\AppServiceProvider.php

Inclusive, nosso teste não depende da classe concreta, precisaríamos apenas executar os testes unitários, e, uma vez que eles nos digam que está tudo ok, podemos prosseguir com a substituição do ORM sem tanta preocupação em quebrar o nosso sistema.

Nesse nosso cenário temos apenas uma classe dependendo da nossa lógica de usuários, mas imagine em um sistema complexo onde quase tudo dependeria da classe de usuários, imagine ter que procurar arquivo por arquivo pra fazer essa alteração? Sem ter a certeza que realmente trocou onde deveria trocar? A inversão de dependência facilita muito a manutenção da nossa aplicação!

Conclusão

Você pode estar pensando, mas quais as chances de eu precisar trocar meu ORM ou qualquer outra biblioteca que eu esteja utilizando? Pra ser sincero, em projetos pequenos, são bem baixas. Mas mesmo pra projetos pequenos se seu objetivo é criar um software de qualidade, de fácil entendimento, escalável e de fácil manutenção, a inversão de dependências junto com as demais letras do SOLID e demais boas práticas de desenvolvimento de software podem ser uma luz no seu caminho. E como você chegou até aqui acredito que seja esse o seu objetivo.

A inversão de dependência é um conceito muito importante para manter nosso software escalável e com fácil manutenção, mas como diz o ditado popular, uma andorinha só não faz verão, ele precisa sempre estar acompanhado dos outros princípios da SOLID.

Se você ficou com alguma dúvida sobre o conceito e/ou implementação da inversão de dependências ou de qualquer outro conceito utilizado nesse artigo, fique à vontade pra comentar aqui!

CQS Pattern - Quando, como e por quê utilizar?

Caio Flavio — Fri, 29 Apr 2022 17:29:54 +0000

Introdução

Este post tem como objetivo fazer um resumo sobre o que aprendi sobre Command Query Separation (CQS) e compartilhar com outras pessoas que estejam pesquisando sobre esse assunto.
Eu particularmente tenho uma certa dificuldade em definir a responsabilidade de cada uma da minhas classes quando estou levando em consideração o Principio da Responsabilidade Única e o que tem me ajudado a organizar melhor essas responsabilidades é entender como outros programadores mais experientes fazem isso. E durante uma sessão de estudos fui apresentado ao Command Query Segregation (CQS) um pattern que foi introduzido por Bertrand Meyer que tem como princípio que todo método deve executar uma ação ou retornar dados, mas nunca os dois ao mesmo tempo. É importante frisar que como todo design pattern ele não é uma bala de prata que vai resolver todos os nossos problemas e por isso iremos discutir um pouco sobre como e quando podemos aplicar esse padrão de desenvolvimento.

Definições

O autor definiu que todo método deve executar uma ação ou retornar dados, mas nunca os dois aos mesmo tempo. Nesse momento você pode estar pesando: "mas retornar dados não é uma ação?". Quando falamos em CQS ações ou Commands são operações que possuem efeitos colaterais, ou seja, alteram o estado de uma variável, um registro no banco, etc... quando há alguma alteração envolvida estamos estamos executando uma ação ou Command. E quando estamos apenas consultando um dado de onde quer que seja sem causar efeitos colaterais no sistema estamos executando uma consulta ou Query.

Casos de uso

É sempre bom lembrar que o uso de CQS é uma escolha de arquitetura e não quer dizer que realizar ação e retornar dados na mesma função seja errado. Existem os prós e contras quando utilizamos um determinado padrão e com CQS não é diferente.
Um exemplo clássico e amplamente utilizado pela comunidade PHP que não faz uso do CQS é o Eloquent ORM. Como podemos ver abaixo, quando criamos um objeto a classe nos retorna um instância contendo os dados do objeto criado.

<?php
namespace App\Services;

use App\Domain\Users\UserTypes\BaseUser\Entities\UserEntity;

class UserService
{
    public function createEloquentUser(array $params = []): UserEntity
    {
        return UserEntity::create($params);
    }
}

O retorno dessa função é uma instância de UserEntity:

Quando pensamos em principio da responsabilidade única, nossa função createEloquentUser acaba tendo duas responsabilidades: Criar o usuário e Retornar os dados do usuário em projetos pequenos isso acaba não sendo um problema, mas, quando nosso projeto começa a crescer o CQS pode nos oferecer as seguintes vantagens:

Performance: A maioria das aplicações executam mais leitura do que escrita então quando separamos as Queries e os Commands temos um ganho de perfomance, pois só executaremos essas ações onde é realmente necessário.
Mantenabilidade: Como cada classe e método terão apenas uma a responsabilidade de ler com as Queries ou escrever com os Commands torna o código mais legível pois temos mais clareza do que está sendo executado apenas ao olhar o código.
Fácil de testar: Como as responsabilidades das classes e métodos estão bem definidos acaba facilitando o processo de criação de testes unitários.
Fácil de implementar: É fácil de implementar, pois basta lembrar que se é uma consulta criaremos uma classe Query se é ação que cria ou altera alguma parte do nosso sistema criaremos uma classe de Command. O exemplo abaixo mostra as classes necessárias para um CRUD de usuários:

Implementação

A criação, atualização e deleção de usuários são considerados ações, pois, elas causam efeitos colaterais ao alterar o estado de onde estão armazenamos os dados dos nossos usuários. Então, para esses casos devemos criar classes de Command:

UserCreateCommand.php

<?php
namespace App\Infrastructure\User\Commands;

use App\Infrastructure\Database\DatabaseORM;

class UserCreateCommand
{
    public function __invoke(array $creationParams = []): void
    {
        DatabaseORM::create($creationParams);
    }
}

UserUpdateCommand.php

<?php
namespace App\Infrastructure\User\Commands;

use App\Infrastructure\Database\DatabaseORM;

class UserUpdateCommand
{
    public function __invoke(int $userId, array $updateParams = []): void
    {
        DatabaseORM::update($userId, $creationParams);
    }
}

UserDeleteCommand.php

<?php
namespace App\Infrastructure\User\Commands;

use App\Infrastructure\Database\DatabaseORM;

class UserDeleteCommand
{
    public function __invoke(int $userId): void
    {
        DatabaseORM::delete($creationParams);
    }
}

Como nossas classes tem responsabilidades únicas e bem definidas então nesse caso optei por utilizar o método mágico __invoke. Note também que nossas funções sempre retornam void pois utilizando CQS o Command deve apenas executar uma ação e nada além disso.

Agora, para retornar os dados que foram armazenados vamos criar nossas classes de Query:

UserFindOneByIdQuery.php

<?php
namespace App\Infrastructure\User\Queries;

use App\Infrastructure\Database\DatabaseORM;

class UserFindOneByIdQuery
{
    public function __invoke(int $userId): array
    {
        return DatabaseORM::findOne($userId);
    }
}

UserFindByQuery.php

<?php
namespace App\Infrastructure\User\Queries;

use App\Infrastructure\Database\DatabaseORM;

class UserFindByQuery
{
    public function __invoke(array $queryParams = []): array
    {
        return DatabaseORM::findBy($queryParams);
    }
}

Mas nem tudo são flores, como você pode ver pra executar uma tarefa simples de CRUD de usuários foi preço criar 5 classes distintas e em um cenário com mais ações para cada outra ação ou consulta precisaríamos de mais classes, ou seja, apesar de termos um código mais limpo e organizado, temos um aumento na complexidade que nem sempre faz sentido em projetos pequenos. Por isso é importante ter em mente se as vantagens como ganho de perfomance e mantenabilidade a longo prazo realmente farão diferença invés de aplicar somente por estética.

Conclusão

O Command Query Separation é um padrão de projeto que como qualquer outro tem seus prós e contras, ele nos ajuda a compreender melhor como separar as responsabilidades das nossas ações e consultas. E como os outros padrões deve ser utilizado com sabedoria em casos onde as vantagens compensam as suas desvantagens. Quando mais nos aprofundamos em padrões de projeto e arquitetura de software mais ferramentas teremos pra enfrentar os problemas do dia-a-dia e escolher a melhor ferramenta para cada problema.

Melhorando a observabilidade: Boas práticas na escrita de LOGS

Caio Flavio — Fri, 25 Mar 2022 19:17:41 +0000

Introdução

Esse artigo tem como objetivo dismitificar o uso de logs nas nossa aplicações. E para nos guiarmos nesse processo tentaremos responder algumas perguntas como: O que são logs? Para que servem? Como escrever logs relevantes?. Esse é um tema pode parecer simples mas grande parte dos engenheiros de software apesar de conhecerem não são familiarizados com o conceito, segundo esse artigo da equipe de engenharia do linkedin e nos iremos mudar isso hoje!

Definição

Uma possível definição técnica que eu particularmente gosto é de que talvez os logs sejam a forma mais simples possível de abstração de armazenamento, eles são sequências de registros ordedenados pela data de criação e possuem duas propriedades, todo arquivo de log deve ser append-only e totally-ordered. De modo simples, append-only significa que o arquivo de log suporta apenas inserção de dados e os dados já existentes devem ser imutáveis e totally-ordered é uma propriedade que nos grante que existe uma ordem em todos elementos do conjunto (nesse caso nosso arquivo de log) e que pegando quaisquer dois elementos desse conjunto conseguimos dizer qual veio primeiro e qual veio por último.

Principais finalidades

Existem diversos tipos e finalidades de logs como os transaction logs que são utilizados por diversos bancos de dados para realizar um fallback dos dados em caso de falha de uma transação. Existem também os logs utlizados por serviços de mensageria para criação de tópicos e mensagens apesar de ser bom saber que um mesmo conceito pode ser aplicado em situações diferentes nosso objetivo aqui é focar na utilização de logs para monitoramento e auxilio na solução de possíveis problemas na nossa aplicação e esses logs são popularmente conhecidos como application logs.

Observabilidade

Os logs são comumente utilizados para auxiliar no diágnostico de problemas e no processo de observação do comportamento de uma aplicação, principalmente em sistemas de arquitetura monolitica. Porém com a popularização da arquitetura de microsserviços apesar de eles continuarem sendo utilizados para esse fim eles passaram a ser considerados como parte de um conceito mais amplo a observabilidade. Os pilares da observabilidade segundo este artigo são as métricas, eventos, traces e logs. Neste texto iremos abordar boas práticas na escrita de logs focando no objetivo de melhorar a observabilidade de nossas aplicações e os outros pilares serão abordados em posts futuros.

Como escrever LOGs relavantes?

Tendo em mente o conceito de observabilidade e como os logs funcionam reuni algumas dicas de como escrever logs para que eles nos forneçam informações detalhadas sobre o que acontece na nossa e de fato nos ajudar no processo de monitoramento e correção de problemas no fluxo da nossa aplicação.

1. Padronize a escrita de logs

Os PSRs (PHP Stardard Recommendation) tem uma seção especifica para como devemos escrever nossas classes de logs. Mas nem sempre precisamos reinventar a roda, existem diversos pacotes mantidos pela comunidade e amplamente utilizados que podemos utilizar em nossos projetos sem nos precuparmos em implementar essas diretrizes, mas é sempre importante entender o que estamos fazendo.

1.1. Pacotes populares para logs em php

Monolog - É uma das bibliotecas mais utilizadas no mercado e é utilizada nativamente pelos principais frameworks PHP da atualidade como: Laravel, Symphony, Lumen, CakePHP, Slim, entre outros...
Analog - Apesar de não ser tão popular essa biblioteca tem a premissa de ser otimizada para criação de logs de forma simples, configurável e extensível.
KLogger - Essa biblioteca também mantida pela comunidade é utilizada em algumas universades dos EUA e assim como as outras segue as especificações da PSR-3.

2. Sempre use os níveis de log

Os PSRs especificam oito níveis de mensagens de log que não são arbitrários, eles seguem o protocolo RFC-5424 que faz parte de um conjunto de regras definidas para padrozinar o que é implementado na internet. E por esse motivo temos oito níveis de logs, que são eles em ordem de criticidade:

emergency: Deve ser utilizado quando o sistema está completamente não utilizavel.
alert: Deve ser utilizado quando uma ação precisa ser tomada imediatamente.
critical: Deve ser utilizado quando algum componente está indisponível, normalmente quando é uma exceção não esperada.
error: Deve ser utilizado para erros de execução que normalmente não precisam de uma ação no momento em que ocorrem mas precisam ser monitorados.
warning: Deve ser utilizado para comportamentos anormais no sistema que não necessáriamente sejam erros, como por exemplo, uso de API's desafadas ou mal uso de uma API.
notice: Deve ser utilizado para eventos que ocorrem normalmente mas que são siginificantes para o monitoramento.
info: Deve ser utilizado para eventos que são interessantes de serem observados no fluxo da aplicação, como por exemplo: "Usuário {id} logou no MYSQL".
debug: Deve ser utilizado para salvar informação detalhada de depuração de erros e/ou um determinado fluxo do sistema.

3. Escreva mensagens descritivas e contextualizadas

Os logs precisam nos ajudar a entender o fluxo da nossa aplicação então messagens como os exemplos abaixo dificilmente irão nos ajudar nisso:



  LoggerLibrary::error("Algo deu errado");
  LoggerLibrary::error("Banco de dados não esta funcionando");

As mensagens acima não nos dão um caminho de o que e nem onde está acontecendo o problema Um exemplo de mensagem que nos ajuda a entender problemas no fluxo precisa espeficar



  LoggerLibrary::error("[Atualização Usuário] Não foi foi possível atualizar dados do usuário de id: {$id}");
  LoggerLibrary::info("[App\Services\ExternalApiService] Protolo número {$protocolNumber} atualizado com sucesso.");
  LoggerLibrary::warning("[App\Services\ExternalApiService] Não foi possível atualizar o protolo número {$protocolNumber}: API Indisponível.");

4. Não logue apenas exceções

Caso haja a necessidade de criar logs para determinadas exceções evite logar somente a stacktrace pois ela normalmente devolve apenas quais linhas de código geraram aquela exceção e díficilmente tem os dados geraram aquele problema, por isso evite fazer como no exemplo abaixo:



try {
  $data = ['some' => 'data'];
  $this->apiService->getUserData($data);
} catch (\AnErrorException $e) {
  LoggerLibrary::debug("Caiu em uma excessão.", ['exception' => $e])
}

Lembre-se que os logs são uma parte importante da observabilidade e é preciso que ele forneça um contexto que possa ajudar a quem está monitorando a situação a entender aquele determinado fluxo para sanar eventuais problemas.



try {

  $data = ['some' => 'data'];

  $this->apiService->getUserData($data);

} catch (\AnErrorException $e) {

  LoggerLibrary::debug("[Serviço de API XPTO] Falha ao receber dados de cliente da API XPTO. Os seguintes dados foram utilizados.", ['exception' => $e, 'data' => $data])

}

Isso é realmente necessário?

Quando vamos escrever mensagens de log para nossa aplicação precisamos lembrar que estamos descrevendo um fluxo do nosso sistema que precisa ser monitorado. Então antes de sair criando mensagens de log para cada trecho do código precisamos compreender o contexto e se a criação dessas mensagens irá colaborar de maneira positiva para o monitoramento do funcionamento da nossa aplicação.

6. Padronize, mas tenha em mente que as coisas podem mudar

Sabemos que os logs podem ser feitos para serem lidos por humanos e por máquinas e além disso conforme a nossa aplicação evolui novas necessidades surgem e utilizar textos planos pode deixar de ser uma boa opção. Por isso é importante a outras maneiras de realizar o parsing de nossos logs como por exemplo em JSON. A biblioteca Monolog possui um parser pronto pra você salvar seus logs em JSON e neste link você encontra algumas dicas de como criar bons logs em JSON.

Conclusão

Os logs são um dos pilares da observabilidade e quanto mais entendemos da nossa aplicação mais fácil se torna escrever fluxos que nos ajudem a entender a saúde de nossos serviços. Essas dicas são um caminho para a escrita de logs que podem contribuir para melhorar a observabilidade dos nossos sistemas.