Clean Architecture com Pokémon

A ideia deste repositório é praticar os conceitos da Clean Architecture de um modo divertido e prático integrando uma API com uma API de Pokémon de Terceiros.

Aqui irei tentar replicar algumas regras do clássico jogo Pokémon Gold do Gameboy.

Pré-Requisitos

• PHP 7.4 ou superior;
• Composer;
• Docker;

Tecnologias

• Slim Framework 4;
• Migrations com PHINX;
• Cache com Redis;
• Especificação de Respostas JSON com JSend;
• Container Injeção de Dependência com PHPDI;

Desenho Macro da Arquitetura

Montei um diagrama mostrando como está arquitetado a aplicação baseado nos meus estudos e no meu entendimento da Clean Architecture. Esse diagrama pode ser atualizado (e com certeza será) no decorrer do desenvolvimento desse estudo:

Camadas e Decisões

Domain | Entities (Camada Amarela)

Definição do autor:

As Entidades reúnem as Regras Cruciais de Negócios da empresa inteira. Uma entidade pode ser um objeto com métodos ou um conjunto de estruturas de dados e funções. Isso não importa, contanto que as entidades possam ser usadas por muitas aplicações diferentes na empresa e são os objetos de negócios da aplicação.

Elas concentram as regras mais gerais e de nível mais alto. No mínimo, são propensas a mudar quando ocorrer alguma mudança externa. Por exemplo, você não gostaria que esses objetos fossem impactados por uma mudança na navegação de página ou na segurança. Nenhuma mudança operacional em qualquer aplicação específica deve influenciar a camada da entidade.

Fonte: Clean Architecture Book (Página 204)

Uma prática que utilizei aqui é que toda Entity deverá ter sua própria Factory, pois não se sabe como as entitdades podem ser criadas no futuro. As factories nos permite ter essa flexibilidade.

Um exemplo prático pode ser visto no BattleFactory.

Use Cases (Camada Vermelha)

Definição do autor:

O software da camada de casos de uso contém as regras de negócio específicas da aplicação. Ele reúne e implementa todos os casos de uso do sistema. Esses casos de uso orquestram o fluxo de dados para e a partir das entidades e orientam essas entidades na aplicação das Regras Cruciais de Negócios a fim de atingir os objetivos do caso de uso.

Não queremos que as mudanças nessa camada afetem as entidades. Também não queremos que essa camada seja afetada por mudanças em externalidades como a base de dados, a UI ou qualquer framework comum. A camada de casos de uso deve ser isolada dessas preocupações. Contudo, esperamos que mudanças na operação da aplicação afetem os casos de uso e, portanto, o software dessa camada.

Fonte: Clean Architecture Book (Página 204)

Os use cases são separados por suas respectivas pastas e devem ter pelo menos 3 classes:

• UseCase.php: classe principal onde será implementado o caso de uso;
• InputBoundary.php: um DTO que representa os dados que serão passados para o caso de uso;
• OutputBoundary.php: um DTO que representa os dados de saída que o caso de uso deverá retornar;

Dentro dessa camada também terá os contratos necessários para que as camadas mais externas possam se comunicar com esta.

Adapters | Interface Adapters (Camada Verde)

Definição do autor:

O software da camada de adaptadores de interface consiste em um conjunto de adaptadores que convertem dados no formato que é mais conveniente para os casos de uso e entidades, para o formato mais conveniente para algum agente externo como a base de dados ou a web.

Os apresentadores (Presenters), visualizações e controladores (Controllers) pertencem à camada de adaptadores de interface. Os modelos provavelmente são apenas estruturas de dados transmitidas dos controladores para os casos de uso e, então, dos casos de uso para os apresentadores e visualizações.

De maneira similar, os dados dessa camada são convertidos da forma mais conveniente para entidades e casos de uso para a forma mais conveniente para o framework de persistência em uso (por exemplo, a base de dados).Nenhum código interno desse círculo deve saber nada sobre a base de dados.

Fluxo do controle: ele começa no controlador (Controller), passa pelo caso de uso (Use Case) e, então, acaba sendo executado no apresentador (Presenter).

Fonte: Clean Architecture Book (Página 205)

Nessa camada estarão as implementações e adaptações necessárias para que a camada de Use Cases e Entities possam se comunicar com o mundo externo.

Infra | Frameworks and Drivers (Camada Azul)

Definição do autor:

A camada mais externa e é geralmente composta de frameworks e ferramentas como a base de dados e o framework web. Em geral, você não programa muita coisa nessa camada além do código de associação que estabelece uma comunicação com o círculo interno seguinte.

Todos os detalhes ficam na camada de frameworks e drivers. A web é um detalhe. A base de dados é um detalhe. Mantemos essas coisas do lado de fora, onde não podem fazer mal nenhum.

Fonte: Clean Architecture Book (Página 205)

Aqui terão as classes que farão acesso ao mundo externo: Frameworks, bibliotecas, UI, WEB, CLI e etc.

Referências e Links

• Introdução a Arquitetura de Software
• Clean Architecture I – Overview
• erandirjunior/vehicle-backend
• erandirjunior/fortbrasil-backend
• rmanguinho/clean-ranking-loader
• In Clean Architecture, where to put validation logic?
• REST, GraphQL, Clean Architecture e TypeScript com Rodrigo Manguinho // Live #69

Casos de Uso

Abaixo estão listadas os casos de uso para termos uma ideia fechada de Domínio e Regras de Negócios:

• Iniciar uma Batalha (Battle Start);
• Capturar um Pokémon (Catch Pokemon);
• Informações do Jogador (Player Info);
• Comprar Items (Purchase);