Forem: Clinton Rocha

Criei uma pipeline de planejamento no OpenCode e olha no que deu

Clinton Rocha — Mon, 09 Mar 2026 04:37:00 +0000

Você é como eu e vem buscando formas de otimizar o uso de ferramentas como o OpenCode? Talvez este conteúdo te ajude a ter novas ideias e até mesmo entender alguns fluxos dessa e de outras ferramentas.

Enquanto eu estudava a documentação do OpenCode, encontrei a aba de plugins feitos pela comunidade. Ali, encontrei três plugins que, na minha visão, se complementam bem. Na verdade, um deles eu já utilizava: o Plannotator.

A partir disso, comecei a estudar como funcionava os comandos, agentes e como eu poderia fazer um fluxo que fizesse sentido e principalmente que funcionasse, calma que já te explico oq cada um dos plugins fazem e qual a ideia final da integração.

Índice

Como eu estava usando o OpenCode
Objetivo da integração
Plannotator: Revisão Visual
Octto: Coleta estruturada de contexto
Subtask2: Orquestração de Pipeline
Comandos
Considerações
Referências

Como eu estava usando o OpenCode

Após começar a utilizar o OpenCode, notei o quão importante é o uso do módulo de planejamento e, principalmente, não apenas o planejamento em si, mas também as perguntas que são feitas durante esse processo. O resultado dessas duas novas abordagens (planejamento e perguntas) melhora bastante não só o código produzido, mas também a minha compreensão sobre a regra de negócio, além de comportamentos e fluxos do sistema.

Mesmo com todas essas descobertas que trouxeram otimizações para o processo, eu ainda sentia que dava para melhorar mais.

O fluxo de uso do OpenCode era basicamente o seguinte: eu enviava o prompt, a ferramenta vasculhava o código para obter contexto, depois vinham algumas perguntas e, em seguida, ela ia para a parte de build, ou seja, para colocar em prática o que tinha sido planejado.

Objetivo da integração

A ideia vai ser conseguir extrair o máximo de contexto com o Octto, usar o subtask2 para orquestrar os comandos e visualizar o plano final com Plannotator.

+---------------------------------------------------------------+
|                                                               |
|  IDEIA -> CONTEXTO -> PLANO -> REFINAMENTO -> REVISAO -> OK   |
|                                                               |
+---------------------------------------------------------------+

O resultado é um único comando que orquestra todo o processo:

/generate-plan "descrição do objetivo"

Plannotator: Revisão visual

O primeiro plugin chegou até mim por recomendação de uma amiga da comunidade (He4rtDevs), a Cherry, e o plugin era o Plannotator.

Esse plugin basicamente faz com que, ao final de um planejamento, seja aberta uma página no navegador contendo todo o plano gerado. Isso facilita muito a visualização em comparação com o terminal. Na interface do navegador, você consegue selecionar trechos do planejamento e dar feedback, que retorna para o processo de planejamento. Também é possível aprovar o plano e seguir diretamente para a etapa de build, ou seja, aplicar o que foi planejado.

Octto: Coleta estruturada de contexto

O Octto quando você envia o primeiro prompt, ele abre uma página no navegador com perguntas relacionadas ao que você pediu inicialmente. Essa página funciona como uma interface interativa de brainstorming. Conforme você responde às perguntas, o sistema utiliza essas respostas para gerar novas perguntas dentro da mesma sessão, aprofundando o entendimento do problema e ajudando a estruturar melhor o contexto antes de seguir para as próximas etapas, ao final ele gera um arquivo .md no diretório /docs/plans dentro do projeto.

A unica configuração que adicionei a ele, foi uma que faz com que a primeira pergunta seja um campo de texto livre onde o usuário consiga descrever o contexto com maior liberdade (colocar uma task completa, por exemplo).

Fluxo de Funcionamento

+----------------------+
|       ask_text       |  <-- Primeira ação obrigatória
+----------+-----------+
           |
           | Campo de texto no browser:
           | "Descreva com detalhes o que
           | você quer planejar..."
           v
+----------------------+
|   create_brainstorm  |  <-- Agente inicia sessão
+----------+-----------+      com contexto coletado
           |
           | Define branches de exploração
           v
+--------------------------------------------------------------+
|                    BRANCHES DE EXPLORAÇÃO                    |
|                                                              |
|  +----------------+  +-------------------+  +---------------+|
|  | Motivação &    |  | Requisitos &      |  | Riscos &      ||
|  | Objetivos      |  | Restrições        |  | Dependências  ||
|  +--------+-------+  +---------+---------+  +-------+-------+|
|           |                    |                    |        |
+-----------+--------------------+--------------------+--------+
            |
            v
+----------------------+
|      BROWSER UI      |
|                      |
|  [ Pergunta 1 ]      |
|  [ Pergunta 2 ]      |
|  [ Pergunta N ]      |
|                      |
|      [Responder]     |
+----------+-----------+
           |
           | Usuário responde
           v
+----------------------+
| await_brainstorm_    |
| complete             |  <-- Agente aguarda respostas
+----------+-----------+
           |
           | Sintetiza respostas
           v
+----------------------+
|      docs/plans/     |
| 2026-03-08-objetivo  |  <-- Arquivo gerado
|        .md           |
+----------------------+

Configuração via Fragments

O comportamento do Octto é customizado através de fragments, instruções adicionadas ao prompt dos agentes internos:

{
    "fragments": {
        "octto": [
            "Sempre pergunte a motivação e o 'porquê' das mudanças",
            "Gere nomes de arquivo no formato: YYYY-MM-DD-slug.md",
            "Salve os planos em docs/plans/"
        ],
        "probe": [
            "Priorize perguntas sobre motivações e restrições",
            "Inclua perguntas sobre requisitos não-funcionais"
        ],
        "bootstrapper": [
            "Crie branches focados em: requisitos, arquitetura, riscos"
        ]
    }
}

Função de cada agente interno:

bootstrapper: cria a estrutura inicial de branches
probe : gera perguntas de aprofundamento
octto: define o comportamento geral da coleta de contexto

Subtask2: Orquestração de pipeline

O Subtask2 permite encadear comandos de forma sequencial. Quando um comando termina, o próximo da cadeia é executado automaticamente.

Nesse meu contexto só vou usar a funcionalidade de return, mas esse plugin tem muitas outras funcionalidades interessantes como:

loop de subtarefas até que a condição do usuário seja atendida
paralela de subtarefas simultaneamente - PR pendente.
$TURN[n] passa turnos da sessão (mensagens do usuário/assistente).
{as:name} + $RESULT[name] captura e referência as saídas das subtarefas.

Sintaxe de Return Chain

---
subtask: true
return:
- /comando-1
- /comando-2
- /comando-3
---

Comandos

Com o subtask2, consigo adicionar comandos ao fluxo, e isso abre muitas possibilidades. Mas, por enquanto, estou com os pés no chão e vou fazer um fluxo simples com alguns novos comandos.

Eu criei esses comandos com o único intuito de usar na pipeline.

Comando Principal

O comando que vai dar inicio a todo o fluxo, vai ser o /generate-plan ao executar, ele da inicio a pipeline de planejamento.

Você é livre para escolher qualquer nome para o comando, para escolher o nome desse aqui eu só segui as vozes da minha cabeça.

Caso queira saber mais sobre como criar e configurar comandos no opencode, a doc é legalzinha.

/generate-plan refatorar sistema de autenticação
/generate-plan "adicionar suporte a múltiplos gateways de pagamento"

As aspas são opcionais: tudo após o comando é passado como $ARGUMENTS.

---
description: Pipeline completo de planejamento 
agent: octto
subtask: true
return:
- /refine-plan
- /review-plan
---

prompt aqui, e lembre de usar o $ARGUMENTS

Caso você queira ver como deixei o meu prompt usado no comando generate-plan é só ir no gist.

Todos os comandos podem ser usados individualmente/isolado no OpenCode, a unica diferença ao usar um comando com o subtask é que ele vai ser executado em um contexto diferente.

Refinamento Técnico

O /refine-plan tem como objetivo expandir um plano existente com detalhes arquiteturais.

/refine-plan # usa plano mais recente
/refine-plan docs/plans/meu-plano.md # plano específico

refine-plan:

---
description: Expande e refina tecnicamente um plano existente com arquitetura e diagramas
subtask: true
---

Mesma coisa que o anterior, aqui você consegue adicionar a instrução que você quiser.

No meu caso, o prompt que estou sando tá no gist 'refine-plan.md'.

Revisão Visual

Por último vem o comando /review-plan com o objetivo de mandar o plano para revisão interativa via Plannotator.

/review-plan # usa plano mais recente
/review-plan docs/plans/meu-plano.md # plano específico

Importante: Este comando não usa subtask: true. Ele roda na sessão primária para que a ferramenta submit_plan possa abrir a interface do Plannotator no browser corretamente. Comandos rodando como subtarefa não conseguem inicializar a UI do browser.

Fluxo Completo de Execução:

Considerações

O mais importante de tudo: funcionou? Sim. É uma bazuca? Sim, hahahaha. Esse projeto acabou saindo porque entrei em hiperfoco ao me fazer a pergunta “será que funciona?”. No fim, tive minha resposta.

Olhando para a usabilidade no dia a dia, acredito que os melhores momentos para utilizar algo assim são em novas features, refatoração de projeto e até mesmo para estruturar estudos, quem sabe. Só não use para algo como “quero trocar a cor de um botão”, aí você acaba complicando.

O ponto que mais curti foi o Octto, com as perguntas geradas de forma dinâmica. Aquilo ali, ao meu ver, auxilia na contextualização de uma baita maneira. Fora que é possível dar instruções para as branches dele, especificar qual tipo de input você quer ou não quer, entre outras coisas (vale ler a documentação).

Já o subtask2 abre portas para muita coisa. Como eu tinha dito antes, acabei indo pelo simples, mas alguém com a mente mais aberta provavelmente vai conseguir extrair o melhor da ferramenta.

Eu pretendo criar novos comandos, refinar mais os prompts e ver o que acontece. É isso, obrigado por ler até aqui e tente brincar com isso ai.

Como meu Tech Lead fala:

Faça codigo inútil e quebre alguma coisa.

Referências

Laravel Modular [anotações]

Clinton Rocha — Tue, 12 Aug 2025 13:13:41 +0000

Salve, tudo bem com você?

Então, este conteúdo é basicamente composto pelas minhas anotações feitas enquanto eu estudava sobre arquitetura modular no Laravel. Meu objetivo durante o estudo era entender quais configurações necessárias no Laravel que me permitiriam utilizar esse tipo de estratégia na arquitetura. Acabou que encontrei informações sobre essas configurações, mas, além disso, também descobri ferramentas que agilizam esse processo.

Além do conteúdo sobre modularização, aqui você vai encontrar informações sobre padrões de design e um pouco de boas práticas. Como isso aqui é um subproduto dos meus estudos, tem muita coisa sobre o Laravel que acabei aprendendo durante o processo. Pode parecer óbvio para você, mas não para o “eu” do passado.

Já adianto: meu objetivo aqui é trazer pontos que considerei relevantes durante os estudos. Para você, talvez pareçam “informações jogadas”, mas eu geralmente estudo a partir de palavras-chave ou tópicos, usando-os como ponto de partida para outras pesquisas (Google, YouTube e artigos). Então, não tenho a pretensão de ensinar algo neste conteúdo.

Disclaimer

Foi utilizada IA para organizar as minhas anotações em tópicos e gerar o table of contents. Você provavelmente não entenderia a sopa de letrinhas e inúmeros bullet points que produzi durante meus estudos, então utilizei essa famosa ferramenta para auxiliar na organização de tudo por aqui.

1. Configuração de Módulos
- 1.1. Autoloading (PSR-4)
- 1.2. Service Providers
- 1.3. Testes Modulares
2. Modelos, Factories e DTOs
- 2.1. Conectando Factories a Models
- 2.2. Actions
- 2.3. Definindo Status de Modelos
- 2.4. Data Transfer Objects (DTOs)
3. IDE Helper
- 3.1. Instalação e Uso
- 3.2. Scripts para Composer
4. Views Modulares
- 4.1. Vistas Normais
- 4.2. Componentes Anônimos
- 4.3. Componentes de Classe
5. Ferramentas e Plugins
- 5.1. Laravel IDEA
- 5.2. Pacote Laravel Modules
6. Organização de Código: Abordagens
- 6.1. Vertical Slice
- 6.2. Agrupamento por Tipo (Grouping by Type)
7. Padrões de Design e Boas Práticas
- 7.1. Acoplamento Temporal vs. Eventos
8. Outros Tópicos
- 8.1. Sequences em Factories

1. Configuração de Módulos

1.1. Autoloading (PSR-4)

Para usar o Laravel de forma modular, é necessário informar o novo módulo no arquivo composer.json. Isso permite que o autoload funcione, garantindo que as classes do seu módulo sejam encontradas.

Se quiser saber mais: Link

1.2. Service Providers

O Service Provider é o coração de um módulo. Cada provider herda de uma classe base chamada ServiceProvider e possui dois métodos principais:

register(): Chamado primeiro, para registrar serviços e bindings.
boot(): Chamado após todos os métodos register() dos providers, para inicializar serviços e configurar funcionalidades (como rotas e views).

Para registrar um novo provider, ele deve ser informado no arquivo config/app.php (ou configurado para ser descoberto automaticamente).

A doc do Laravel é uma mãe, se quiser mais informação sobre o tópico, recomendo!

1.3. Testes Modulares

Para usar testes de forma modular, é necessário registrar o módulo no arquivo phpunit.xml.

2. Modelos, Factories e DTOs

2.1. Conectando Factories a Models

Por padrão, as factories procuram pelas models no namespace App\Models.
Para conectar uma factory a uma model, defina a model no atributo $model da factory.
Quando o caminho padrão da factory é alterado, é preciso informar ao Laravel onde ela está. Use o método estático newFactory() na model:

use Modules\Product\Database\Factories\ProductFactory;

class Product extends Model
{
    protected static function newFactory()
    {
        return ProductFactory::new();
    }
}

Saiba mais em:

2.2. Actions

No Laravel, é uma convenção usar a pasta Actions para agrupar comportamentos e ações, similar aos conceitos de usecase ou service.

2.3. Definindo Status de Modelos

É possível definir um status em uma instância de model sem persistir no banco de dados. Exemplo:

public const STATUS_PENDING = 'pending';

public static function startForUser(int $userId): self
{
    return self::make([
        'user_id' => $userId,
        'status' => self::STATUS_PENDING,
    ]);
}

2.4. Data Transfer Objects (DTOs)

Os DTOs são úteis para reduzir o acoplamento e melhorar a clareza. Eles podem ser usados para:

Comunicação entre diferentes camadas do código.
Reduzir o número de parâmetros em métodos.
Representar coleções de dados (Collections).
Usar métodos estáticos (fromEloquentModel ou fromEloquentCollection) para instanciar DTOs a partir de models ou collections do Eloquent.

class ProductDTO
{
    public function __construct(
        public readonly int $id,
        public readonly string $name,
        public readonly string $sku,
        public readonly float $price,
    ) {}

    public static function fromEloquentModel(Product $product): self
    {
        return new self(
            id: $product->id,
            name: $product->name,
            sku: $product->sku,
            price: $product->price,
        );
    }

    public static function fromEloquentCollection(Collection $products): Collection
    {
        return $products->map(fn (Product $product) => self::fromEloquentModel($product));
    }
}

Saiba mais em:

3. IDE Helper

3.1. Instalação e Uso

O IDE Helper Generator for Laravel gera PHPDocs que ajudam a IDE a entender as models.

Instalação:

composer require --dev barryvdh/laravel-ide-helper

Gerando PHPDocs:

Para o caminho padrão das models:

php artisan ide-helper:models

Para um caminho personalizado (ex: na pasta modules):

php artisan ide-helper:models --dir=modules

3.2. Scripts para Composer

É possível encurtar o comando adicionando um script no composer.json:

"scripts": {
    "ide": "php artisan ide-helper:models --dir=modules"
}

Uso na CLI:

composer run ide

4. Views Modulares

Para trabalhar com views modulares fora de resources/views, use o método boot() do Service Provider para registrar os novos caminhos.

class OrderServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $this->loadViewsFrom(__DIR__ . '/../../Ui/Views', 'order');
        Blade::anonymousComponentPath(__DIR__ . '/../../Ui/Views/components', 'order');
        Blade::componentNamespace('Modules\\Order\\Ui\\ViewComponents', 'order');
    }
}

4.1. Views Normais

Use loadViewsFrom() para registrar pastas de views com um namespace, evitando conflitos entre módulos.

Exemplo: view('order::checkout') buscará a view em Modules/Order/Ui/Views/checkout.blade.php.

4.2. Componentes Anônimos

Use Blade::anonymousComponentPath() para registrar uma pasta de componentes Blade anônimos.

Eles não têm classe PHP associada, apenas arquivos .blade.php.
Exemplo: <x-order::alert /> renderiza Modules/Order/Ui/Views/components/alert.blade.php.

4.3. Componentes de Classe

Use Blade::componentNamespace() para registrar um namespace PHP de componentes de classe.

São componentes criados com php artisan make:component.
Exemplo: <x-order::checkout-summary /> renderiza o componente de classe CheckoutSummary no namespace Modules\Order\Ui\ViewComponents.

O básico sobre views no Laravel:

Views

5. Ferramentas e Plugins

5.1. Laravel IDEA

É um plugin do PHPStorm que oferece suporte ao Laravel.
Na seção Module System, permite definir a estrutura modular do projeto (ex.: diretório modules com namespace Modules).
Funciona bem quando a estrutura interna de cada módulo segue o padrão do Laravel.

Se não me engano o Laravel IDEA agora tá de graça no PHPStorm, é uma ótima ferramenta, recomendo

5.2. Pacote Laravel Modules

O pacote Laravel Modules é uma ferramenta popular para modularizar projetos.
Fornece uma estrutura organizada para criar e gerenciar módulos.
O Laravel IDEA possui suporte nativo para este pacote.

6. Organização de Código: Abordagens

6.1. Vertical Slice

Organiza o código agrupando por funcionalidade (ex.: Order > Checkout), e não por tipo de arquivo.
Todos os arquivos relacionados a uma funcionalidade ficam juntos.
Facilita a visualização e manutenção de cada funcionalidade como uma unidade coesa.

Mais sobre esse tópico em:

6.2. Agrupamento por Tipo (Grouping by Type)

Organiza o código por tipo de arquivo (ex.: models, controllers).
É possível combinar esta abordagem com a modularização criando uma pasta src dentro do módulo para agrupar arquivos como Models, Events, etc., seguindo o padrão padrão do Laravel.

7. Padrões de Design e Boas Práticas

7.1. Acoplamento Temporal vs. Eventos

Problema: Acoplamento Temporal: Ocorre quando uma ação depende estritamente de outra para ser executada, criando uma ordem rígida e dificultando a manutenção.
Solução: Usar Eventos: Em vez de executar tudo em um único método, separe as responsabilidades. O fluxo principal dispara um evento e outras partes do sistema podem "escutar" e reagir de forma independente (ex.: enviar um e-mail de confirmação ou atualizar o estoque).

8. Outros Tópicos

8.1. Sequences em Factories

O Sequences do Laravel permite variar valores de atributos ao criar várias instâncias de uma factory.
É útil para criar dados de teste com pequenas variações.

use Illuminate\Database\Eloquent\Factories\Sequence;

User::factory()
    ->count(3)
    ->state(new Sequence(
        ['name' => 'Alice'],
        ['name' => 'Bob'],
        ['name' => 'Carol'],
    ))
    ->create();

Referencia: Laravel: sequences

[Boost]

Clinton Rocha — Fri, 27 Dec 2024 15:39:09 +0000

"Ser" ou "estar" Senior?

Jessilyneh ・ Dec 27 '24

#career #productivity #braziliandevs

Um júnior e um teste técnico: The battle.

Clinton Rocha — Sun, 03 Mar 2024 18:35:04 +0000

Alguns dias atrás me deparei com um teste técnico e decidi fazer mesmo após já ter finalizado o período de entrega, não sei bem para que nível foi passado o teste, mas acredito que foi usado em diferentes níveis, o que vai definir a complexidade do projeto é a solução do candidato, ao ver isso, decidi fazer aplicando o que venho aprendendo.

Eu nunca fiz teste técnico, muito menos uma entrevista técnica, então neste artigo pretendo explicar minha solução, motivações, reflexões e opiniões.

Objetivo proposto
Ferramentas escolhidas
Primeiros passos
Arquitetura e padrão de projeto
Tratamento de erros
Testes
Duvida
Questionamentos
Conclusão

Objetivo proposto

Em resumo, o desafio é fazer uma API, um sistema de banco simplificado, nessa API existe dois tipos de usuário, o comum e o lojista, o comum pode transferir dinheiro para o lojista ou outro usuário comum, já o lojista não pode fazer transferência, ele apenas receber, veja mais alguns requisitos:

Validar se o usuário tem saldo antes da transferência.
Antes de finalizar a transferência, deve-se consultar um serviço autorizador externo, e para isso eles disponibilizaram um mock para simular esse serviço.
A operação de transferência deve ser uma transação (ou seja, revertida em qualquer caso de inconsistência) e o dinheiro deve voltar para a carteira do usuário que envia.
No recebimento de pagamento, o usuário ou lojista precisa receber notificação (envio de email, sms) enviada por um serviço de terceiro e eventualmente esse serviço pode estar indisponível/instável. Para isso também foi disponibilizado um mock para simular o envio.

Mock: É um objeto simulado que imita o comportamento de um componente real. É usado principalmente em testes de software para isolar o código em teste de suas dependências externas, garantindo testes mais rápidos e previsíveis.

O teste técnico não avalia:

Fluxo de cadastro de usuários e lojistas
Autenticação

Mas em desencargo de consciência vou explicar o que poderia ser usado, na autenticação poderia ser usado um JWT e para validar os campos da requisição existem diversas estratégias, geralmente eu uso express-validator como middleware ou o class-validator como seus decorators, e podendo ser validado na camada de controller ou também como middleware.

Ferramentas escolhidas

Para começar com chave de ouro nesse teste técnico, nada mais, nada menos do que o amigo da galera, sim, ele mesmo, nosso tão amado Javascript, na verdade, vou usar o Typescript junto ao Express. Como é a linguagem que tenho uma boa base, a sintaxe não seria mais um problema nesse projeto, me permitindo focar em arquitetura e estrutura do código. As ferramentas que usei foram:

Primeiros passos

Acredito que não exista uma ordem perfeita para se começar um projeto, já me deparei com pessoas começando pelas rotas, criando estrutura de pastas primeiro que tudo, outras criando os testes para depois implementar as funcionalidades, sendo essa ultima talvez a mais famosa e mais indicada que vejo pela internet, entre outras abordagens, enfim, não sei qual é melhor, após instalar as ferramentas escolhidas e tripagem comecei a desenvolver a tabela do banco.

Confesso que modelagem ainda não é meu forte, e por isso deixei essas duas tabelas o mais simples possível.

BEGIN;
      CREATE TABLE IF NOT EXISTS users (
        id SERIAL PRIMARY KEY,
        firstName VARCHAR(255) NOT NULL,
        lastName VARCHAR(255) NOT NULL,
        document VARCHAR(14) UNIQUE NOT NULL,
        email VARCHAR(255) UNIQUE NOT NULL,
        password VARCHAR(255) NOT NULL,
        balance INT,
        userType VARCHAR(7) NOT NULL
    );

      CREATE TABLE IF NOT EXISTS transactions (
        id SERIAL PRIMARY KEY,
        payer INT NOT NULL,
        payee INT NOT NULL,
        amount INT NOT NULL,
        date_transaction TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
        FOREIGN KEY (payer) REFERENCES users(id),
        FOREIGN KEY (payee) REFERENCES users(id)
      );
COMMIT;

Tabelas prontas, agora eu posso criar os types que vão existir dentro da minha aplicação.

type User = {
  id?: number;
  firstName: string;
  lastName: string;
  document: string;
  password: string;
  email: string;
  balance: number;
  usertype: "comum" | "lojista";
};

type Transaction = {
  id?: number;
  amount: number;
  payer: number;
  payee: number;
  date_transaction?: Date;
}

Após perguntas para alguns amigos e pesquisar como geralmente é feito uma modelagem desse tipo, levantei essas duas possíveis melhorias:

Fazer mais uma tabela para guardar os cargos, imagine um cenário onde poderiam existir outros cargos do usuário, em vez de ter direto na tabela user, poderia salvar esses cargos em outra tabela e relaciona ao usuário, resultado em uma normalização dos dados.
Ter outra tabela onde eu salvaria o saldo da conta do cliente, assim eu não precisaria ficar atualizando a tabela do usuário toda vez que for feita uma transferência.

Arquitetura e padrão de projeto

Acabei optando por utilizar uma arquitetura em camadas. Pelo que venho estudando, essa estratégia é bastante interessante por alguns motivos:

Desacoplamento de código.
Separação de responsabilidade.
Modularidade e reutilização de código.
Facilidade na hora de criar testes.

Não posso deixar de citar os pontos negativos:

Complexidade adicional.
Dificuldade de implementação no início do projeto.

Além disso, foi usado alguns princípios da orientação a objetos, sim, o famoso SOLID. No meu código você pode encontrar princípios como:

Responsabilidade única, onde exemplo é o seguinte método que se comunica com a camada de repositório e procura um usuário pelo id:

async userById(id: number) {
    const user = await this.userRepository.userById(id);
    if (!user) {
      throw new InvalidUser("Usuario invalido");
    }
    return user;
  }

Inversão da dependência e aberto-fechado: usando a interface como uma abstração do banco de dados, o UserService não vai mais precisar saber qual o banco minha aplicação está usando:

//abstração
export interface IUserRepository {
  newUser(user: User): Promise<User>;
  userById(id: number): Promise<User>;
  emailExist(email: string): Promise<boolean>;
  documentExist(document: string): Promise<boolean>;
}

export class UserService {
  constructor(private userRepository: IUserRepository) {}

  async newUser(user: User) {
 
    const EmailExist = await this.userRepository.emailExist(user.email);
    
    if (!EmailExist) {
      throw new InvalidEmail("Email invalido");
    }
    
    const DocumentExist = await this.userRepository.documentExist(
      user.document
    );

    if (!DocumentExist) {
      throw new InvalidDocument("Document invalid");
    }

    const newUser = await this.userRepository.newUser(user);
    
    return newUser;
  }
  //...
}

A meu ver, o código fica muito mais limpo, só se deve ter cuidado com a quantidade de abstração, o uso excessivo pode acarreta um emaranhado de código.

Em outro artigo/post explico melhor sobre SOLID, nele eu trago alguns exemplos em código e imagens que podem te ajudar a entender melhor sobre esses princípios: Era SOLID o que me faltava. Agora entrando na parte de organização de projeto, vou explicar um pouco das funções de cada camada, o projeto tem três camadas, são elas:

Repository: camada responsável por interagir com o banco de dados.
Service: camada onde a lógica de negócio acontece, interações com outros serviços e manipulação dos dados enviados/recebidos dorepository.
Controller: camada onde recebemos o corpo da requisição do cliente, podendo ser feito validações, verificações nas informações recebidas e enviadas, também podendo chamar diferentes serviços.

Tratamento de erros

No Javascript o try catch é uma estrutura usada para lidar com exceções durante a execução de código, mas isso gera uma repetição de estrutura tremenda no código, fora que faz com que uma funcionalidade possa ter diferentes tipos de retorno, acaba deixando o código desorganizado e muito difícil de se entender.

Tendo esse detalhe da linguagem em mente, optei pelo uso de middleware de erros e uma pequena biblioteca express-async-errors fazendo com que minhas exceções não saiam de controle.

export const errorMiddleware = (
  error: Error & Partial<ApiError>,
  request: Request,
  response: Response,
  next: NextFunction
) => {
  const statusCode = error.statusCode ?? 500;
  const message = error.statusCode ? error.message : "Internal Server Error";

  return response.status(statusCode).json({ error: message, code: statusCode });
};

Com o uso desse middleware eu posso lançar exceções e não quebrar a aplicação e nem mostrar erros tenebrosos para o usuário, mas não para por aqui, para deixar os erros ainda mais fáceis de se ler, eu fiz uma pequena personalização.

export class ApiError extends Error {
  public readonly statusCode: number;

  constructor(message: string, statusCode: number) {
    super(message);
    this.statusCode = statusCode;
  }
}

// Um dos erros que usei na aplicação 
export class UnauthorizedTransaction extends ApiError {
  constructor(message: string) {
    super(message, 401);
  }

}

//Caso de uso.
const isAuthorized = await this.authorizationService.authorizeTransaction();

if (!isAuthorized) {
  throw new UnauthorizedTransaction("Transação não autorizada");
}

Em outro artigo/post que fiz falo mais sobre esse assunto do try-catch e middleware de erros: Lidando com exceções.

Testes

Esse projeto me fez melhor muito na maneira que desenvolvo os meus testes e a estrutura escolhida para esse projeto auxiliou muito para isso, mais alguns benefícios que a estrutura do projeto proporcionou:

Me permite criar mocks em camadas especificas
In Memory Test Database

Os mocks são interessantes de se usar, eu pensava que poderia sair colocando mock em tudo, mas não é bem assim que funciona, como qualquer coisa na tecnologia, toda ferramenta tem seu lugar na atuação, onde eu acredito que ele brilhe é em pontos específicos do teste, por exemplo:

test("authorizeTransaction should return false when authorization is not successful", async () => {
    global.fetch = vi.fn().mockResolvedValue({
      json: () => Promise.resolve({ message: "Not authorized" }),
    });
    
    const result = await authService.authorizeTransaction();

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

Esse é um exemplo onde o mock me permitiu testa o retorno de algo que não tenho controle, no caso seria uma API de autorização de transação.

test("It should not be possible to create a user with an email that already exists", async () => {
    const { fakeUser, userService } = makeSut();
    await userService.newUser(fakeUser);

    await expect(userService.newUser(fakeUser)).rejects.toThrow(
      "Email invalido"
    );
  });

O In Memory Database é uma abordagem que aprendi faz pouco tempo, no link que disponibilizei fala mais sobre os benefícios do uso dessa estratégia, mas no caso dessa minha aplicação, o ponto de destaque foi os testes onde eu esperava retornos de falha, sem o uso de banco de dados eu consigo testa de maneiras simples e rápida pontos de falhas.

Nos testes E2E foram usados o supertest em conjunto de um container Docker rodando um banco de dados postgreSQL, para que não tivesse problema entre esses testes E2E foi usado um pequeno script para limpar o banco.

Duvida

A maioria das vezes as soluções que pensei nesse desafio e também em outros projetos que já fiz, são consideradas como overengineering, e pelo que vejo pela internet, provavelmente quase todo júnior na hora do desenvolvimento de alguma aplicação já passou por isso. Tendo isso em mente, eu me questionei, como que esse overengineering seria visto pelo entrevistador? Eu estaria mostrando conhecimento ou iria parecer esta copiando ''modelo'' de solução? Provavelmente o que responderia essas perguntas seria minha entrevista.

Overengineering: É quando você cria uma solução mais complexa ou robusta do que realmente precisa. É como usar um canhão para matar uma mosca. Isso pode resultar em desperdício de tempo, recursos e dificuldade de manutenção. Em resumo, é quando você torna algo mais complicado do que é necessário para resolver o problema em questão.

Questionamentos

Após finalizar boa parte desse artigo, mostrei o rascunho para a galera da comunidade He4rt Developers resultando em um bate-papo bem legal, nele eu fui levado a questionar ainda mais as escolhas em relação às tecnologias usadas no processo de desenvolvimento. Eu vou esta fugindo um pouco do tema principal desse artigo, mas esses questionamentos são necessários para todo desenvolvedor e acredito que vão fazer você evoluir de alguma maneira.

Usar ou não usar um framework? Convenhamos que usar determinado framework iria facilitar e muito o processo de desenvolvimento, mas temos que entender uma coisa, um framework é ferramenta que se encaixa em situações especificas e resolvem problemas específicos, e não para por aí, o desenvolvedor tem que entender o contexto do problema que ele vai solucionar, existem limitações e requisitos referente a estrutura, tem toda uma análise antes de se escolher uma tecnologia. O mesmo questionamento vale para linguagens.

Após levantar esses pontos, quero mostrar questionamentos que normalmente se deve ter antes de escolher uma tecnologia:

Qual a quantidade de usuários que vai utilizar?
O que está disponível para a utilização na infraestrutura da empresa?
Terá novas implementações dentro desta lógica?
Qual a criticidade do processo?
Qual o tempo ideal de resposta para cada rota?

Você já tinha se perguntado isso alguma vez antes? Pelo que vejo de outros desenvolvedores mais experientes, esses questionamentos fazem total diferença.

Conclusão

Como foi dito no início, eu nunca tinha feito um teste técnico antes, acredito que após de ter feito essa solução e ao fazer esse artigo, me fez pensar em muita coisa em relação a tudo isso, provavelmente eu não teria a mesma postura que tive nesse projeto, mas de qualquer forma eu saí aprendendo algo.

E você leitor, aprendeu algo com esse artigo? Tem algum feedback? Se tiver alguma explicação errada nesse artigo, eu ficaria grato com sua correção. Será que eu iria passar nesse teste? Fica essa dúvida no ar.

Quase que esqueço, caso você queira ver minha solução por completo, ela está no meu Github e também o repositório do desafio original. Você pode me encontrar no Twitter ou no Discord da He4rt Developers.

Gostaria de agradecer ao @carloseduardodb e a @cherryramatis pela revisão desse conteúdo, feedbacks e dicas. Os questionamentos foram levantados pelo Carlos e eu achei de grande ajuda, para esse artigo e ainda mais para mim.

"Eu tentaria fazer uma solução mais próxima da realidade do pessoal de lá para ganhar uns pontinhos. Às vezes, nem é utilizar a mesma linguagem que eles, mas entender os problemas que eles têm e como eles solucionam hoje."

@carloseduardodb

Fica aí mais uma dica.

Obrigado por ler até aqui.

Primeiros passos no Docker

Clinton Rocha — Wed, 07 Feb 2024 12:22:42 +0000

Desenvolvendo de forma simples e direta, é hoje que você vai começar a usar o Docker. Nada de termos complicados, apenas uma abordagem fácil para que você possa usar containers sem stress. Você provavelmente já deve ter ouvido falar de Docker em requisitos de vagas ou em projetos de algum outro desenvolvedor e com isso tentou usá-lo e não conseguiu ou então não entendeu como usar. Nesse artigo vou te mostrar de maneira simples como é o processo de conteinerização de uma aplicação.

Objetivo
Requisitos
O que é
- Dockerfile
- Docker Image
- Container
- Volume
- Compose
CLI do Docker
Botando a mão na massa
- Seu primeiro Dockerfile
- Configuração do Vite
- Criando a imagem do front
- Criando o container do front
- Criando uma network
- Baixando a imagem do Postgres
- Criando um volume para persistência de dados
- Executando container Postgres
- Criando a imagem do back
- Criando o container do back
Compose
Conteúdo complementar
Conclusão

Objetivo

Meu principal objetivo é ajudar você leitor com os primeiros passos com Docker no desenvolvimento de seus projetos. Pretendo ter uma abordagem pautada no contexto da aplicação que vou usar, vamos começar explicando as ferramentas de uma forma diferente das que encontrei pela internet, em seguida vou mostrá-las mais a prática, usando uma pequena aplicação como exemplo. Esse artigo conciliado ao conteúdo teórico que vou disponibilizar por links durante e ao final vão te dar uma boa base do que é essa ferramenta e como ela funciona por baixo dos panos, ao fim de tudo eu espero que você seja capaz de dar seus primeiros passos criando container de tudo 🐳.

Requisitos

Ter instalado:

Docker
- Windows
- Mac
- Linux
Docker-compose

O que é

Dockerfile

É um arquivo de configuração, onde está o passo inicial para a criação de uma Docker Image. Nele contem as instruções para configurar sua aplicação no container. Veja o dockerfile como um manual que lista o passo a passo de como montar algo (sua aplicação no caso) e as instruções de como ligar esse algo na tomada.

Docker Image

A Docker Image é o aglomerado de tudo o que é necessário para sua aplicação funcionar, é onde se encontra o código-fonte, bibliotecas, dependências e mais o que for necessário para que ela funcione. Seu app em uma foto.

Container

Imagine que você queira fazer uma festa independente do local que esteja, e para isso você carrega uma caixa com balões, caixinha de som e luzes coloridas, coisas leves. Pronto sua festa pode ser feita em qualquer lugar, essa caixa é o nosso container, ele reúne tudo o que é necessário para uma aplicação funcionar. Ele resolve aquele famoso problema de "Na minha máquina funciona".

Em outras palavras, os containers são ambientes de software leves, portáteis e isolados que permitem aos desenvolvedores executar e empacotar aplicativos com suas dependências, de forma consistente em diferentes plataformas. Eles ajudam a agilizar os processos de desenvolvimento, implantação e gerenciamento de aplicativos, garantindo ao mesmo tempo que os aplicativos sejam executados de forma consistente, independentemente da infraestrutura.

Volume

Em termos simples, um volume no contexto do Docker é um mecanismo que permite que dados sejam compartilhados e persistam entre o host e os containers. Ele oferece uma maneira de armazenar e compartilhar informações de forma independente do ciclo de vida dos containers.

Por exemplo, se você tiver um container de banco de dados, pode usar um volume para armazenar os dados do banco de forma que esses dados persistam mesmo se o container for removido. Isso proporciona flexibilidade e consistência na gestão de dados em ambientes Docker.

Compose

O Docker Compose é uma ferramenta que simplifica a gestão de aplicações Docker compostas por vários containers. Ele permite definir, configurar e executar vários serviços, redes e volumes em um arquivo YAML, facilitando a criação e a execução de ambientes complexos com apenas um comando.

CLI do Docker

Existe o Docker Desktop onde você pode fazer a maioria das configurações, ele é até amigável, porem o mais indicado é você se acostumar com os comandos pelo terminal, até por que em caso de qualquer dúvida as respostas que você vai encontrar pela internet na sua grande maioria vão ser em formato de comandos, caso você queria configurar através do aplicativo desktop recomendo você olhar a documentação. Nesse tópico eu pretendo mostrar alguns comandos básicos e fala o que cada um faz.

docker --help

Começando pelo mais simples, mas também muito importante, o --help mostra todos os comandos do Docker junto a uma pequena explicação, ele também pode ser usado em conjunto com os próximos comandos que vou mostrar no caso de você não se lembrar das opções que aquele comando tem.

Todos os comandos que vou usar são da nova versão feita para fornecer uma experiência de usuário mais estruturada ao usar a linha de comando. Que eu saiba, ainda não houve nenhum anúncio oficial para abandonar o suporte aos comandos antigos (como docker ps e outros), embora possa ser razoável supor que isso possa acontecer em algum momento no futuro.

Para gerenciar containers:

Criar e executar container:

docker container run nome-da-imagem

Listar containers em execução:

docker container ls

Listar todos os containers (Inclusive parados):

docker container ls -a

Parar um container:

docker container stop nome-ou-ID-do-container

Iniciar um container parado:

docker container start nome-ou-ID-do-container

Remover um container (deve estar parado):

docker container rm nome-ou-ID-do-container
## com a opção '-f' ele força a parada do container e em seguida o remove

Para Gerenciar Imagens:

Listar imagens locais:

docker image ls

Baixar uma imagem do Docker Hub:

docker pull nome-da-imagem

Construir uma imagem a partir de um Dockerfile:

docker build -t nome-da-imagem caminho-do-Dockerfile

Remover uma imagem local:

docker rm nome-da-imagem

Para Gerenciar Redes:

Listar redes Docker:

docker network ls

Criar uma rede Docker:

docker network create nome-da-rede

Conectar um container a uma rede:

docker network connect nome-da-rede nome-ou-ID-do-container

Desconectar um container de uma rede:

docker network disconnect nome-da-rede nome-ou-ID-do-container

Outros comandos úteis:

Logs de um container:

docker logs nome-ou-ID-do-container

Informações Detalhadas de um container:

docker inspect nome-ou-ID-do-container

Botando a mão na massa

Nesse tópico vamos abordar as ferramentas acima citadas um pouco mais prática, e para isso vamos usar uma pequena aplicação com as tecnologias React, Vite,Express e PostgreSQL.

Link do repositório da aplicação🐳

Seu primeiro Dockerfile

No diretório ./front podemos ver o arquivo .dockerignore que funcionar parecido com o .gitignore, nele você define arquivos ou pastas que não são necessárias na imagem da sua aplicação. O arquivo Dockerfile tem a seguinte estrutura:

FROM node:18.17.0-alpine
WORKDIR /app
COPY package*.json ./
COPY . .
RUN npm install
RUN npm run build
EXPOSE 8080
CMD [ "npm", "run", "preview" ]

`FROM`

Aqui é o ponto de partida da sua imagem, é onde você define a base do seu container, e para essa aplicação eu estou baixando a imagem do node na versão 18.17.0-alpine e quando você ver o alpine em alguma imagem significa que a imagem foi construída usando Alpine Linux como base. Essas imagens são populares porque são eficientes, rápidas de baixar e fornecem um ambiente leve para executar aplicativos em containers.

`WORKDIR`

Define o diretório de trabalho dentro do container como /app. Isso significa que os próximos comandos serão executados dentro deste diretório.

`COPY`

Copia o arquivo package.json (e qualquer arquivo que comece com "package") do diretório local para o diretório /app no container.

O segundo COPY copia todos os outros arquivos do diretório local para o diretório /app no container.

`RUN`

Executa o comando npm install dentro do container, que instala as dependências especificadas no arquivo package.json.

O segundo RUN executa o comando npm run build para construir a aplicação. Esse comando é geralmente usado para compilar e preparar a aplicação para execução.

`EXPOSE`

Informa que a aplicação dentro do container estará escutando na porta 8080. Isso não faz com que a porta seja automaticamente aberta, mas é uma informação útil para quem está usando a imagem para entender qual porta a aplicação espera ser exposta.

`CMD`

Define o comando padrão a ser executado quando um container baseado nesta imagem for iniciado. Neste caso, o comando é npm run preview, que inicia o servidor da aplicação para que ela possa ser acessada.

Essas vão ser as instruções mais básicas que vamos usar, existem algumas outras e recomendo você dá uma olhada na documentação para ter uma base melhor.

Configuração do Vite

No Vite para que nossa aplicação rode na porta 8080 é necessário configurar o arquivo vite.config.ts. Caso você queira abordar outras configurações recomendo ler a documentação do Vite .

Artigo que me ajudou a entender a configuração usada nesse projeto.

Criando a imagem do front

Pronto, com o Dockerfile preenchido corretamente podemos criar nossa primeira imagem. Se você prestou atenção no tópico CLI do Docker já deve ter uma ideia de como vamos fazer isso, vá no terminal e acesse o diretório ./front e execute o seguinte comando:

docker image build -t front .

-t ou -tag é usado para dar nome e dar tag para a imagem, nesse exemplo estou dando o nome da imagem como front caso eu quisesse ter diferentes versões dessa imagem poderia ser usado o segundo argumento para uma tag como front:nome-da-tag, geralmente na tag é colocado a versão ou algo que facilite a identificação front:1.0.
No terminal eu estou no diretório ./front que é onde está o dockerfile é por isso que só uso o . (ponto).

Se você presta atenção no seu terminal, vai notar que o Docker esta seguindo as instruções feitas no Dockerfile.

No gif a build da imagem foi rápido porque boa parte dessa imagem no meu pc já estava em cache, no seu deve demorar mais.

Criando o container do front

Já temos a imagem do front e com ela podemos criar o tão sonhado container, novamente vá no seu terminal e execute o comando:

docker container run -d -p 8080:8080 front

-d: É usado para executar um container em segundo plano, ou seja, em modo "detached". Quando você executa um container Docker, por padrão, ele é iniciado em primeiro plano.
-p 8080:8080: essa opção indica que estamos mapeando a porta 8080 do container para a porta 8080 do host.
front: é o nome da imagem o container vai usar.

Acessando o http://localhost:8080 em seu navegador já vamos conseguir acessar o front da nossa aplicação, mas ainda falta o nosso back e banco esta no ar.

Criando uma network

O docker network é um recurso do Docker que permite criar redes isoladas para containers. As redes do Docker desempenham um papel fundamental ao fornecer comunicação entre containers, garantindo isolamento, segurança e flexibilidade nas interações entre os diferentes componentes de um sistema distribuído.

docker network artigo

O nome da rede vai ser artigo😁.

Baixando a imagem do Postgres

O próximo passo é baixar a imagem do Postgres a partir do Docker Hub. Para fazer isso, execute o seguinte comando em seu terminal:

docker pull postgres

Criando um volume para persistência de dados

Antes de executar o containers do banco e do back, é importante criar um volume para persistência de dados. Isso garantirá que os dados do Postgres não sejam perdidos quando o container for interrompido ou excluído. Para criar um volume, execute o seguinte comando em seu terminal:

docker volume create pgdata

O nome do volume vai ser pgdata.

Executando container Postgres

Com o volume criado, agora você pode executar o container Postgres. Para fazer isso, execute o seguinte comando em seu terminal:

docker container run -d --name postgres --network=artigo -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_HOST=postgres -e POSTGRES_DATABASE=postgres -e POSTGRES_PASSWORD=password -v pgdata:/var/lib/postgresql/data postgres

-d: essa opção indica que o container será executado em segundo plano.
--name postgres: com essa opção, você pode dar um nome ao seu container. Neste caso, estamos nomeando o container como "postgres".
--network: essa opção é utilizada para especificar a rede à qual um container deve ser conectado durante sua execução.
-p 5432:5432: essa opção indica que estamos mapeando a porta 5432 do container para a porta 5432 do host. A porta 5432 é a porta padrão do Postgres.
-e POSTGRES_USER=postgres: essa opção define a variável de ambiente POSTGRES_USER com o user que você escolher. Por padrão, o user do PostgreSQL é postgres.
-e POSTGRES_HOST=postgres: normalmente se refere ao endereço do host onde o banco de dados PostgreSQL está em execução. Se você está executando o PostgreSQL em um container Docker, o POSTGRES_HOST pode ser o nome do container ou o endereço IP do container, dependendo de como você está configurando a comunicação.
-e POSTGRES_DATABASE=postgres: essa opção é usada para especificar o nome do banco de dados ao qual você deseja se conectar.
-e POSTGRES_PASSWORD=sua-senha: essa opção define a variável de ambiente POSTGRES_PASSWORD com a senha que você escolher.
-v pgdata:/var/lib/postgresql/data: essa opção define o volume pgdata criado anteriormente como o local onde os dados do Postgres serão armazenados.
postgres: esse é o nome da imagem que estamos utilizando para criar o container.
-d (ou --detach)
-p (ou --publish)
-e (ou --env)
-v (ou --volume)

Criando a imagem do back

O Dockerfile que esta no diretório /back não muda muita coisa do que fizemos no front, apenas o EXPOSE e o CMD para fazer o start na aplicação.

FROM node:18.17.0-alpine
WORKDIR /app
COPY package*.json ./
COPY . .
RUN npm install
EXPOSE 3000
CMD ["npm", "run", "start"]

No terminal e acesse o diretório ./back e execute o seguinte comando:

docker image build -t back .

Criando o container do back

Sem segredo algum, vamos fazer o mesmo processo que fizemos com o container do front. Já temos a imagem do back e com ela podemos criar o tão sonhado container, novamente vá no seu terminal e execute o comando:

docker container run -d --network=artigo -p 3000:3000 back

Agora nossa aplicação está funcionando completamente, você pode acessar http://localhost:8080 e criar uma tarefa e deletar.

Docker Compose

Podemos notar a quantidade de comandos no terminal que foi necessário para que essa pequena aplicação fosse ao ar, com o compose vamos encurtar todo esse processo colocando tudo em um só lugar, facilitando o nosso desenvolvimento. A estrutura do compose.yaml lembra um pouco o Dockerfile.

version: '3'
services:
  back:
    build: ./back/.
    ports:
      - 3000:3000
    depends_on:
      - postgres
  front:
    build: ./front/.
    ports:
      - 8080:8080
  postgres:
    image: postgres:latest
    environment:
      POSTGRES_USER: postgres
      POSTGRES_HOST: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DATABASE: postgres
    volumes:
      - api-postgres-data:/var/lib/postgresql/data
    ports:
      - 5432:5432
volumes:
  api-postgres-data:

version: '3': Especifica a versão da sintaxe do Docker Compose que está sendo usada. Neste caso, é a versão 3.
services: Define os serviços que serão executados.
- back: Configurações para o serviço chamado "back".
  - build: ./back/.: Especifica que a imagem para o serviço "back" deve ser construída a partir do diretório ./back/.
  - ports: - 3000:3000: Mapeia a porta 3000 do contêiner para a porta 3000 do host.
  - depends_on: - postgres: Indica que o serviço "back" depende do serviço "postgres", garantindo que o serviço "postgres" seja iniciado antes do serviço "back".
- front: Configurações para o serviço chamado "front".
  - build: ./front/.: Especifica que a imagem para o serviço "front" deve ser construída a partir do diretório ./front/.
  - ports: - 8080:8080: Mapeia a porta 8080 do contêiner para a porta 8080 do host.
- postgres: Configurações para o serviço chamado "postgres".
  - image: postgres:latest: Usa a imagem oficial mais recente do PostgreSQL disponível no Docker Hub.
  - environment:: Define variáveis de ambiente para configurar o PostgreSQL.
    - POSTGRES_USER, POSTGRES_HOST, POSTGRES_PASSWORD, e POSTGRES_DATABASE são configurados para criar um usuário, host, senha e banco de dados no PostgreSQL.
  - volumes: - api-postgres-data:/var/lib/postgresql/data: Mapeia um volume chamado "api-postgres-data" para o diretório onde os dados do PostgreSQL são armazenados dentro do contêiner.
  - ports: - 5432:5432: Mapeia a porta 5432 do contêiner para a porta 5432 do host. volumes::
Define um volume chamado "api-postgres-data". Este volume é usado para persistir os dados do PostgreSQL, permitindo que os dados persistam mesmo se o contêiner for removido.

Antes de executar o comando do Compose finalize os dois containers feitos anteriormente para que não de conflito nas portas. Após isso no seu terminal acesse o diretório raiz do projeto, onde está o compose.yaml e use o seguinte comando:

docker compose up -d

O processo de build demora um pouco, lembre-se que esse comando faz o build de 3 containers, no gif é nessa velocidade porque o build esta em cash.

Espero que você tenha percebido o quão maravilhoso é o Compose, a quantidade de trabalho que ele te poupa é absurdo. Apenas com um comando ele cria a imagem do front e back, cria um container a partir da imagem criada para o front, back e para o postgres e ainda cria uma network para que os container possam se comunicar entre eles. Existem muitas outras funcionalidades e opções para se fazer no compose, espero que você tenha ficado curioso com o que possa ser feito.

Conteúdo complementar

Tenha a documentação oficial como sua melhor amiga no processo de estudo, mas além dela existe o treinamento da LINUXtips, feito pelo Jeferson Fernando. Ele disponibilizou completamente de graça o:
Livro Descoplicando o Docker

Treinamento completo no Youtube:
Descomplicando Docker

Para quem é muito agoniado, tem o resumo:
Tudo o que você precisa saber sobre docker em 2h

Para quem quer se especializar um pouco mais:
Roadmap Docker (english)

Conclusão

Esse conteúdo foi o resultado de um aglomerado de anotações e abstrações que tive durante meu processo de estudo sobre docker, a parte que mais bati cabeça foi com o network, durante os meus testes eu ficava tentando fazer os container se comunicarem entre eles, mas um não encontrava o outro, foi uma grande dor de cabeça, mas no fim deu tudo certo. Algumas explicações acabei sendo bem raso, mas foi no intuito de tentar facilitar seu entendimento sobre alguns tópicos.

Caso eu tenha feito alguma explicação errada, ficarei agradecido com seu feedback, você pode me encontrar no Twitter ou no Discord da He4rt.

Obrigado por ler ate aqui.

Lidando com exceções: como fazer erros práticos e elegantes no Express js

Clinton Rocha — Tue, 16 Jan 2024 00:00:29 +0000

Para você, desenvolvedor(a) que esta construindo sua API no Express e se questiona sobre maneiras de aprimorar o tratamento de erros, este artigo promete demonstrar práticas comuns adotadas por muitos e os desafios que podem surgir. Mas a história não para por aí! Vou te apresentar uma abordagem para melhorar a qualidade e personalizar o tratamento de erros na sua aplicação.

Entendendo o que é uma exceção
Try catch em ação
Quando o try catch se torna um obstáculo
Middleware de manipulação de erros
Middleware como solução elegante
Personalizando os erros
Personalizando o middleware de erros
Erros assíncronos
Recomendações
Conclusão

Entendendo o que é uma exceção

Na programação, uma exceção é um evento ou condição que acontece durante a execução de um programa e que pode parar o fluxo da aplicação. O objetivo de lidar com exceções é garantir que o programa possa reagir da melhor maneira a esses eventos anormais, em vez de simplesmente quebrar ou encerrar com seu programa.

import express, { NextFunction, Request, Response } from "express";
import fs from "fs";

const app = express();

app.use(express.json());

app.use("/", (req: Request, res: Response) => {
  const file = fs.readFileSync("naoExiste.txt");
  return res.json(file.toString());
});

Temos um código simples que tenta ler um arquivo txt quando o usuário acessa a rota /, você sabe o que acontece quando o usuário acessa essa rota sendo que o arquivo não existe? Isso mesmo, um erro 😯 e dos feios, o usuário recebe:

Não para por aí, para piorar sua situação a aplicação para de funcionar e nenhum usuário vai conseguir acessar ela porque seu código não tem tratamento de erro:

No seu console o erro vai se maior que isso...

Entender e lidar com exceções é crucial para garantir a estabilidade do programa. No exemplo acima, a falta de tratamento de exceções resulta em mensagens de erro desagradáveis para o usuário e na interrupção da aplicação.

Try catch em ação

No JavaScript, try catch é uma estrutura usada para lidar com exceções (erros) durante a execução do código. O bloco try envolve o código que pode gerar uma exceção, enquanto o bloco catch é usado para lidar com a exceção se ela ocorrer. Vamos por o try catch em ação:

app.use("/", (req: Request, res: Response) => {
  try {
    const file = fs.readFileSync("naoExiste.txt");
    return res.json(file.toString());
  } catch (error) {
    return res.status(404).json("Arquivo não encontrado");
  }
});

O usuário vai receber:

Bom, agora podemos tratar nossos erros, e note que nossa aplicação não caiu, isso é um avanço. Usar try catch é uma prática comum para tornar o código mais robusto e controlar erros de maneira elegante, em vez de permitir que o programa pare de funcionar quando ocorre uma exceção.

Quando o try catch se torna um obstáculo

O problema que quero destacar neste momento está relacionada à quantidade de vezes que é necessário usar a estrutura try-catch em uma simples aplicação. A implementação apresentada mostra a repetição do bloco try-catch em cada endpoint, o que pode tornar o código menos eficiente e mais suscetível a erros de manutenção quando sua aplicação for crescer.

//No mundo real essa variável 'livros' provavelmente seria uma interação com banco de dados
const livros = [
  { id: 1, titulo: "Livro 1", autor: "Autor 1" },
  { id: 2, titulo: "Livro 2", autor: "Autor 2" },
];

app.get("/livros", (req: Request, res: Response) => {
  try {
      if(!livros){
          throw new Error("Nenhum Livro encontrado");
      }
    res.status(200).json(livros);
  } catch (error) {
        res.status(404).json(error.message);
  }
});

app.get("/livros/:id", (req: Request, res: Response) => {
  try {
      const livroId = parseInt(req.params.id);
      if(!livroId){
          throw new Error("ID Invalido");
      }
      const livro = livros.find((l) => l.id === livroId);
      if (!livro) {
        throw new Error("Livro não encontrado");
      }
      res.status(200).json(livro);
  } catch (error) {
      res.status(404).json(error.message);
  }
});

app.post("/livros", (req: Request, res: Response) => {
    try {
        const novoLivro = req.body;
        if(!novoLivro){
            throw new Error("Informações invalida");
        }
        livros.push(novoLivro);
        res.status(201).json("Livro adicionado com sucesso");
    } catch (error) {
        res.status(500).json(error.menssage);
    }
});

Podemos ver a repetição que é usar essa estrutura para lidar com as exceções, mas não é só isso, existem momentos em que é necessário lidar com peculiaridades dessa estrutura, por exemplo, no exemplo anterior existe uma rota que pode gerar 3 tipos de status:

Status Code 400 (Bad Request):

if(!livroId){
  throw new Error("ID Invalido");
}

Status Code 404 (Not Found):

if (!livro) {
    throw new Error("Livro não encontrado");
}

Até daria para fazer um amontoado de if e else como podemos ver em:

catch (error) { 
    if (error.message === "ID Inválido") {
        res.status(400).json(error.message);
    } else if (error.message === "Livro não encontrado"){
        res.status(404).json(error.message);
    } else { 
        res.status(500).json("Erro interno do servidor"); 
    } 
}

Mas convenhamos que isso deixa o código um pouco poluído e dificulta consequentemente a leitura e futuras manutenções. É importante considerar alternativas que permitam manter a manipulação de erros de forma eficaz, sem a sobrecarga de código.

Middleware de manipulação de erros

Vamos explorar uma solução para o nosso problema em específico, visando simplificar a estrutura, melhorar a legibilidade e facilitar futuras modificações na API.

Deixa eu te apresentar nosso amigo Middleware, ele tem acesso ao objeto de solicitação (req), o objeto de resposta (res) e com isso podemos solucionar os problemas que foram citados anteriormente, esse colega é atua entre o usuário e sua aplicação, podemos usar ele em situações diversas, no nosso caso vamos usá-lo na manipulação de erros.

app.use((error: Error, req: Request, res: Response, next: NextFunction)=> {
    //aqui que entra a magica =D
    return res.json(error.message);
});

Sempre defina os middlewares de manipulação de erros por último, após outros app.use() e camadas de rota.

Middlewares de manipulação de erros sempre levam quatro argumentos. Você deve fornecer quatro argumentos para identificá-lo como uma função de middleware de manipulação de erros. Mesmo se você não precisar usar o objeto next, você deve especificá-lo para manter a assinatura. Caso contrário, o objeto next será interpretado como um middleware comum e a manipulação de erros falhará.

Essa é a estrutura básica de um Middleware no Express especificamente para manipulação de erros.

Como ilustrado acima, o Middleware de erro atua entre o usuário e as rotas. Tente ver ele como o responsável por lidar com problemas. Qualquer exceção ocorrida em qualquer camada da aplicação pode ser interceptada por esse middleware. Ele desempenha um papel crucial ao capturar e tratar erros, garantindo uma resposta apropriada ao usuário e facilitando a identificação e resolução de problemas na aplicação.

Middleware como solução elegante

Agora que você compreendeu o funcionamento do middleware e reconheceu sua importância na prevenção de falhas, surge a pergunta: "Devo deixar de usar o try-catch?"

Calma, pequeno Padawan. O try-catch tem seus problemas como foi citado ao decorrer desse conteúdo, essa estrutura é bastante útil em aplicações de pequeno porte, é necessário cogitar a retirada dessa estrutura quando sua aplicação começa a crescer e ter um aumento no nível de complexidade, é aqui que nosso aliado, o Middleware, entra em cena para simplificar e aprimorar a manipulação de erros.

Padawan significa aprendiz , iniciante , e é um termo utilizado nos filmes Star Wars.

No exemplo a seguir apresentado, utilizamos o Middleware para lidar com erros de forma centralizada. Ao invés de repetir a estrutura try-catch em cada rota, delegamos essa responsabilidade ao Middleware de erros.

app.get("/livros", (req: Request, res: Response) => {
  if(!livros){
      throw new Error("Não existe nenhum livro");
  }
      res.status(200).json(livros);
});

app.get("/livros/:id", (req: Request, res: Response) => {
  const livroId = parseInt(req.params.id);
  if (!livroId) {
    throw new Error("ID invalido")
  }
  const livro = livros.find((l) => l.id === livroId);
  if (!livro) {
    throw new Error("O livro que você procura não existe")
  }
  res.status(200).json(livro);
});

app.post("/livros", (req: Request, res: Response) => {
  const novoLivro = req.body; 
  if(!novoLivro){
      throw new Error("Informe um livro valido");
  }
   livros.push(novoLivro);
   res.status(201).json("Livro adicionado com sucesso");
});

app.use((error: Error, req: Request, res: Response, next: NextFunction) => {
    //aqui que entra a magica =D
    return res.status(400).json(error.message);
});

O resultado é notável, o middleware intercepta esses erros, evitando a necessidade de try-catch em cada rota. Além disso, conseguimos personalizar as respostas de erro de maneira mais controlada e esteticamente agradável.

Você deve ter notado que não conseguimos mudar o status code, mas não se preocupe ainda vamos aprimorar esse código, ajustando os códigos de status e refinando as respostas de erro. O importante é que sua aplicação não falha catastroficamente, e agora, estamos trilhando um caminho mais elegante na gestão de exceções.

Personalizando os erros

Você deve saber que a quantidade de status code é limitada, e isso pode diminuir muito mais ao depender da sua aplicação, tendo isso em mente, vamos usar o principio Princípio da responsabilidade única do SOLID para melhorar a legibilidade do nosso código e consequente deixando mais organizado.

export class ApiError extends Error {
  public readonly statusCode: number;

  constructor(message: string, statusCode: number) {
    super(message);
    this.statusCode = statusCode;
  }
}

export class BadRequestError extends ApiError {
  constructor(message: string) {
    super(message, 400);
  }
}

export class NotFoundError extends ApiError {
  constructor(message: string) {
    super(message, 404);
  }
}

export class UnauthorizedError extends ApiError {
  constructor(message: string) {
    super(message, 401);
  }
}

Vamos usar a classe ApiError como classe base que estende a classe nativa Error e adicionar statusCode. No tópico acima, ao falar do middleware foi dito que não dava para mudar o status code do erro ao usar throw new Error(), mas com essa implementação podemos ver que esse problema foi solucionado.

throw new BadRequestError("ID Invalido");

throw new NotFoundError("Livro não encontrado");

throw new UnauthorizedError("Não autorizado!");

Personalizando o middleware de erros

Ao implementar as melhorias no lançamento de erros é necessário melhorar o responsável por lidar com esses erros, confesso que não tem muito segredo.

import { NextFunction, Request, Response } from "express";
import { ApiError } from "./helpers/api-errors";

export const errorMiddleware = (
  error: Error & Partial<ApiError>,
  request: Request,
  response: Response,
  next: NextFunction
) => {
  const statusCode = error.statusCode ?? 500;
  const message = error.statusCode ? error.message : "Internal Server Error";

  return response.status(statusCode).json({ message });
};

Acredito que a parte que você precisa ter cuidado para não se esquecer é em relação ao type do parâmetro error que é Error & Partial<ApiError> lembre-se que statusCode não existe no type nativo Error, sendo necessário fazer essa intersecção e o uso do Partial<> do Typescript porque nem sempre o erro lançado vai ser gerado pelo seu código, às vezes pode ser algo relacionado ao baco de dados ou algum outro problema.

Erros assíncronos

Legal, já melhoramos nosso código e estamos preparados para todo erro que aparecer, será mesmo? Todos os exemplos utilizados até agora foram códigos síncronos e nenhum nenhum assíncrono.

app.get("/livros", async (req: Request, res: Response) => { 
    const livros = await buscarLivrosDoBancoDeDados(); 
    if (!livros) { 
     throw new NotFoundError("Livro não encontrado"); 
    } 
    res.status(200).json(livros); 
}

Se ocorrer algum problema no banco de dados no exemplo acima, seu middleware seria incapaz de capturar o erro, resultando na quebra da aplicação.

app.get("/livros", async (req: Request, res: Response, next: NextFunction) => { 
    try { 
        const livros = await buscarLivrosDoBancoDeDados(); 
        if (!livros) { 
            throw new NotFoundError("Livro não encontrado"); 
        } 
        res.status(200).json(livros); 
        } catch (error) { 
            next(error); 
        } 
});

Para que nosso middleware funcionasse teríamos que voltar a usar o try catch em conjunto do next(error) e só assim o Express conseguiria ter acesso a esse erro, mas não se preocupe que existe uma solução para isso.

A lib express-async-errors oferece um suporte simples e eficaz para lidar com funções assíncronas utilizando ES6 async/await no Express. O principal objetivo é simplificar a manipulação de erros em funções assíncronas, eliminando a necessidade de chamar manualmente a função next para propagar erros.

npm i express-async-errors

Em seguida, adicione no topo do seu arquivo index.ts:

import "express-async-errors";

Pronto, agora podemos voltar a lançar os erros sem o uso do try catch. Essencialmente, a lib express-async-errors simplifica a manipulação de erros em funções assíncronas no Express, permitindo que você use exceções para tratar erros sem a necessidade de chamar explicitamente next.

Recomendações

Todos os links que foram utilizados nesse artigo são bastante uteis para sua compreensão, não pule nenhum. Fora isso eu tenho algumas recomendações:

Daniel Reis com sua didática excepcional fez o artigo Criando Exceptions para impressionar no Teste Técnico a abordagem dele é parecida com a usada nesse artigo, provavelmente você vai conseguir melhorar ainda mais seu código ao ler esse artigo.

Miguel Barbosa tem um artigo muito maneiro com tratamento de erro, Como tratar erros http no Spring Boot , eu nunca fiz algo em Java, mas a explicação é tão legal e com uma abordagem super compreensível que chega a ser impossível você não entender, recomendo.

Erick Wendel tem um vídeo muito maneiro sobre erros no Javascript Sistemas feitos em JavaScript não são confiáveis?! Error Handling lá ele fala um pouco sobre o try catch e muito mais.

Conclusão

Esse conteúdo foi mais complicado do que imaginei, espero que você leitor tenha entendido e aprendido algo novo. No casso de algum erro no código ou falha na explicação eu ficarei grato com seu feedback, você consegue me encontrar no twitter ou no Discord da He4rt.

Obrigado por ler até aqui.

Era SOLID o que me faltava

Clinton Rocha — Tue, 02 Jan 2024 22:16:37 +0000

Começou agora na programação orientada a objetos e não sabe sobre SOLID? Não se preocupe, nesse artigo vou te explicar e dar exemplos de como usá-lo no desenvolvimento do seu código.

O que é SOLID?
S - Princípio da responsabilidade única
O - Princípio Aberto-Fechado
L - Princípio da substituição de Liskov
I - Princípio da Segregação da Interface
D - Princípio da inversão da dependência
Conclusão

O que é SOLID?

Na programação orientada a objetos, o termo SOLID é um acrônimo para cinco postulados de design, destinados a facilitar a compreensão, o desenvolvimento e a manutenção de software.

Ao usar esse conjunto de princípios é notável a redução na produção de bugs, melhora na qualidade do código, produção de códigos mais organizados, na redução de acoplamento, na melhora da refatoração e estimula o reaproveitamento do código.

S - Princípio da responsabilidade única

SRP - Single Responsibility Principle

Esse principio diz que uma classe deve ter um, e somente um, motivo para mudar

É isso ai, nada de fazer classes que tenha varias funcionalidades e responsabilidades. Provavelmente você já fez ou se deparou com alguma classe que faz de tudo um pouco, a tal da God Class. Pode parecer que está tudo bem naquele momento, porem quando for necessário fazer alguma alteração na logica dessa classe é certeza que os problemas vão começar a aparecer.

God Class - Classe Deus: Na programação orientada a objetos, é uma classe que sabe demais ou faz demais.

class Task {
    createTask(){/*...*/}
    updateTask(){/*...*/}
    deleteTask(){/*...*/}

    showAllTasks(){/*...*/}

    existsTask(){/*...*/}

    TaskCompleter(){/*...*/}
}

Essa classe Task esta quebrando o princípio do SRP por esta fazendo QUATRO tarefas diferentes. Ela está lidando com os dados, exibição, validação e verificação da Task.

Problemas que isso pode causar:

Falta de nexo - uma classe não deve assumir responsabilidades que não são suas;
Muita informação junta - sua classe vai ficar com muitas dependências e uma grande dificuldade para alterações;
Dificuldades na implementação de testes automatizados - é difícil de “mockar” esse tipo de classe;

Agora aplicando SRP na classe Task, vamos ver a melhora que esse principio pode causar:

class TaskHandler{ 
    createTask() {/*...*/} 
    updateTask() {/*...*/} 
    deleteTask() {/*...*/} 
} 

class TaskViewer{ 
    showAllTasks() {/*...*/} 
} 

class TaskChecker { 
    existsTask() {/*...*/} 
} 

class TaskCompleter { 
    completeTask() {/*...*/} 
}

Daria para colocar create, update e delete em classes separadas, mas ao depender do contexto e tamanho do projeto é bom evitar complexidade desnecessária.

Talvez você tenha se perguntado só vou conseguir aplicar isso em classes? não, pelo contrário, da para aplicar em métodos e funções também.

//❌
function emailClients(clients: IClient[]) {

    clients.forEach((client)=>{
        const clientRecord = db.find(client);

        if(clientRecord){
            sendEmail(client);
        }
    })
}

//✅
function isClientActive(client: IClient):boolean { 
    const clientRecord = db.find(client); 
    return !!clientRecord; 
}

function getActiveClients(clients: IClient[]):<IClient | undefined> { 
    return clients.filter(isClientActive); 
}

function emailClients(clients: IClient[]):void { 
    const activeClients = getActiveClients(clients);
    activeClients?.forEach(sandEmail); 
}

Código mais bonito, elegante e organizado. Esse principio é a base para os outros, ao conseguir aplicá-lo você estará fazendo um código de ótima qualidade, de fácil leitura e de fácil manutenção.

O - Princípio Aberto Fechado

OCP - Open-Closed Principle

Esse principio diz que Objetos ou entidades devem estar abertos para extensão, mas fechados para modificação, se for necessário adicionar uma funcionalidade é melhor estender e não alterar seu código fonte.

Imagine um pequeno sistema para secretaria de escolar, nele existem duas classes que representa a grade de aulas dos alunos, ensino fundamental e ensino médio. Além de uma classe que é para definir as aulas do aluno.

class EnsinoFundamental {
    gradeCurricularFundamental(){}
}

class EnsinoMedio {
    gradeCurricularMedio(){}
}

class SecretariaEscola {
    aulasDoAluno: string; 

    cadastrarAula(aulasAluno){
        if(aulasAluno instanceof EnsinoFundamental){
            this.aulasDoAluno = aulasAluno.gradeCurricularFundamental();
        } else if(aulasAluno.ensino instanceof EnsinoMedio){
            this.aulasDoAluno = aulasAluno.gradeCurricularMedio();
        }
    }
}

A classe SecretariaEscola é responsável por verificar qual o ensino do aluno para conseguir aplicar a regra de negócio certa na hora do cadastrar as aulas. Agora imagine que essa escola tenha adicionado o ensino técnico e sua grade de aulas no sistema, vai ser necessário modificar essa classe, certo?, só que ai você esbarra em um problema, o de violar o Princípio Aberto-Fechado do SOLID.

Qual a solução que te vem a cabeça? Provavelmente adicionar um else if na classe e pronto, problema resolvido 😁. Não pequeno Padawan 😐, ai que está o problema!

Alterar uma classe já existente para adicionar um novo comportamento, corremos um sério risco de introduzir bugs em algo que já estava funcionando.

Lembre-se: OCP preza que uma classe deve estar fechada para alteração e aberta para extensão.

Veja a beleza que fica ao refatorar o código:

interface gradeCurricular {
    gradeDeAulas();
}

class EnsinoFundamental implements gradeCurricular {
    gradeDeAulas(){}
}

class EnsinoMedio implements gradeCurricular {
    gradeDeAulas(){}
}

class EnsinoTecnico implements gradeCurricular {
    gradeDeAulas(){}
}

class SecretariaEscola {
    aulasDoAluno: string;

    cadastrarAula(aulasAluno: gradeCurricular) {
        this.aulasDoAluno = aulasAluno.gradeDeAulas();
    }
}

Veja a classe SecretariaEscola ela não precisa mais saber quais os métodos chamar para cadastrar a aula. Ela será capaz de cadastrar a grade de aulas corretamente de qualquer novo tipo de modalidade de ensino que seja criado, observe que adicionei o EnsinoTecnico sem nenhuma necessidade de mudar o código-fonte.

Desde que implemente a interface gradeCurricular.

Separe o comportamento extensível por trás de uma interface e inverta as dependências.

Uncle Bob

Aberto para extensão: você pode adicionar alguma nova funcionalidade ou comportamento a classe sem alterar seu código-fonte.
Fechado para modificação: se sua classe já tem uma funcionalidade ou comportamento que não apresenta problema algum, não altere o código-fonte dela para colocar algo novo.

L - Princípio da substituição de Liskov

LSP - Liskov Substitution Principle

Princípio da substituição de Liskov — Uma classe derivada deve ser substituível por sua classe base.

Esse principio que o mano Liskov introduziu em uma conferência no ano de 1987 é um pouco complicada de se entender ao ler a explicação dele, mas não se preocupe, vou mostrar outra explicação e um exemplo que vai te ajudar a entender.

Se para cada objeto o1 do tipo S há um objeto o2 do tipo T de forma que, para todos os programas P definidos em termos de T, o comportamento de P é inalterado quando o1 é substituído por o2 então S é um subtipo de T

Entendeu? Não né, eu também não entendi na primeira vez que li isso (nem nas outras dez vezes), mas calma aí, existe outra explicação:

Se S é um subtipo de T, então os objetos do tipo T, em um programa, podem ser substituídos pelos objetos de tipo S sem que seja necessário alterar as propriedades deste programa. — Wikipedia.

Se você é mais visual calma que tenho exemplos em código:

class Fulano {
    falarNome() {
        return "sou fulano!";
    }
}

class Sicrano extends Fulano {
    falarNome() {
        return "sou sicrano!";
    }
}

const a = new Fulano();
const b = new Sicrano();

function imprimirNome(msg: string) {
    console.log(msg);
}

imprimirNome(a.falarNome()); // sou fulano!
imprimirNome(b.falarNome()); // sou sicrano!

A classe pai e a classe derivada estão passando como parâmetro e o código continua funcionando da forma esperada, magica? Que nada, é o princípio do nosso mano Liskov.

Exemplos de violações:

Sobrescrever/implementar um método que não faz nada;
Lançar uma exceção inesperada;
Retornar valores de tipos diferentes da classe base;

I - Princípio da Segregação da Interface

ISP - Interface Segregation Principle

Princípio da Segregação da Interface — Uma classe não deve ser forçada a implementar interfaces e métodos que não irão utilizar.

Esse principio diz que é melhor criar interfaces mais especificas do que uma interface genérica.

No exemplo a seguir foi criado uma interface Animal para abstrair os comportamentos de animais e em seguida as classes implementam essa interface, veja:

interface Animal {
    comer();
    dormir();
    voar();
}

class Pato implements Animal{
    comer(){/*faz algo*/};
    dormir(){/*faz algo*/};
    voar(){/*faz algo*/};
}

class Peixe implements Animal{
    comer(){/*faz algo*/};
    dormir(){/*faz algo*/};

    voar(){/*faz algo*/};
    // Esta implementação não faz sentido para um peixe 
    // ela viola o Princípio da Segregação da Interface
}

A interface genérica Animal esta forçando a classe Peixe a ter um comportamento que faz sentido e acaba viola o principio ISP e o LSP também.

Resolvendo esse problema usando o ISP:

interface Animal {
    comer();
    dormir();
}

interface AnimalQueVoa extends Animal {
    voar();
}

class Peixe implements Animal{
    comer(){/*faz algo*/};
    dormir(){/*faz algo*/};
}

class Pato implements AnimalQueVoa {
    comer(){/*faz algo*/};
    dormir(){/*faz algo*/};
    voar(){/*faz algo*/};
}

Agora ficou melhor, foi retirado o método voar() da interface Animal e adicionamos em uma interface derivada AnimalQueVoa. Com isso o comportamento foi isolado de maneira correta dentro do nosso contexto e ainda respeitamos o principio de segregação das interfaces.

D - Princípio da inversão da dependência

DIP — Dependency Inversion Principle

Princípio da Inversão de Dependência — Dependa de abstrações e não de implementações.

Módulos de alto nível não devem depender de módulos de baixo nível. Ambos devem depender da abstração.

Abstrações não devem depender de detalhes. Detalhes devem depender de abstrações.

Uncle Bob

No exemplo a seguir vou mostrar um codigo simples para ilustrar o DIP. Nesse exemplo temos um sistema de notificação que envia mensagens por diferentes meios, como e-mail e SMS. Primeiro vamos criar classes concretas para esses meios de notificação:

class EmailNotification {
  send(message) {
    console.log(`Enviando e-mail: ${message}`);
  }
}

class SMSNotification {
  send(message) {
    console.log(`Enviando SMS: ${message}`);
  }
}

Agora, vamos criar uma classe de serviço que depende dessas implementações concretas:

class NotificationService {
  constructor() {
    this.emailNotification = new EmailNotification();
    this.smsNotification = new SMSNotification();
  }

  sendNotifications(message) {
    this.emailNotification.send(message);
    this.smsNotification.send(message);
  }
}

No exemplo acima, NotificationService depende diretamente das implementações concretas de EmailNotification e SMSNotification. Isso viola o DIP, pois a classe de alto nível NotificationService está diretamente dependente de classes de baixo nível.

Vamos corrigir esse código usando DIP. Em vez de depender de implementações concretas, a classe de alto nível NotificationService deve depender de abstrações. Vamos criar uma interface Notification como abstração:

// Abstração para o envio de notificações
interface Notification { 
    send(message: string): void
}

Agora, as implementações concretas EmailNotification e SMSNotification devem implementar essa interface:

class EmailNotification implements Notification {
  send(message: string) {
    console.log(`Enviando e-mail: ${message}`);
  }
}

class SMSNotification implements Notification {
  send(message: string) {
    console.log(`Enviando SMS: ${message}`);
  }
}

Finalmente, a classe de serviço de notificação pode depender da abstração Notification:

class NotificationService {

private notificationMethod: Notification;

  constructor(notificationMethod: Notification) {
    this.notificationMethod = notificationMethod;
  }

  sendNotification(message: string) {
    this.notificationMethod.send(message);
  }
}

Dessa forma, a classe de serviço NotificationService depende de uma abstração Notification, e não das implementações concretas, cumprindo assim o Princípio da Inversão de Dependência.

Conclusão

Ao adotar esses princípios, os desenvolvedores podem criar sistemas mais resilientes às mudanças, facilitando a manutenção e melhorando a qualidade do código ao longo do tempo.

Todo esse conteúdo foi baseado em anotações, outros artigos e vídeos que encontrei pela internet durante meu estudo sobre POO, as explicações são próximas aos autores dos princípios, já os códigos usados nos exemplos eu criei baseado no meu entendimento dos princípios. Espero ter ajudado a você leitor na progressão dos seus estudos.

Sem Stress, Só Perguntas: Um mini guia para perguntar de maneira eficiente

Clinton Rocha — Mon, 04 Dec 2023 12:03:45 +0000

Se você já se viu diante de um problema de código ou teve dúvidas sobre alguma tecnologia, mas não soube como formular a pergunta de maneira eficiente, este artigo é para você.

No twitter ou em grupos do Discord me deparo com perguntas que demandam tempo ou que são desgastantes para serem respondidas, e não é porque o problema é complexo ou algo do tipo, mas porque a pergunta é feita contendo pouca informação e de forma muito abrangente, dificultando uma resposta rápida e direta.

Sumário

O que deve ser comunicado?
Pesquise no Google
Escrevendo perguntas
Conclusão

O que deve ser comunicado?

Ao buscar ajuda, se coloque no lugar de quem vai analisar o seu problema. Antes de enviar qualquer mensagem pedindo auxílio, pergunte a si:
"O que a pessoa que está olhando meu problema precisa para me ajudar?"
Quem for olhar seu problema caiu de paraquedas e precisa entender a situação da melhor maneira possível para poder te ajudar.

Contextualize a situação: Antes de compartilhar seu código, forneça um contexto claro, fale do proposito do código e um pouco do que você está fazendo.
Descreva suas tentativas e objetivos: Fale o que você já tentou para resolver o problema. Isso não apenas evita sugestões repetitivas, mas também mostra que você está se esforçando resolver o problema. Inclua detalhes sobre mensagens de erro específicas que você encontrou e qualquer ideia que tenha tido durante o processo.
Capturas de Tela e Códigos Relevantes: Se o problema estiver relacionado a uma mensagem de erro, capture a tela dessa mensagem. Imagens podem oferecer uma visão instantânea do problema. Além disso, compartilhe pequenos blocos de código diretamente relacionados à questão. Isso simplifica a análise para quem está ajudando e aumenta a probabilidade de uma resposta eficaz.

Use carbon, gist ou codepen para compartilhar seu código de maneira limpa e organizada.

Evite tire fotos usando o celular, use alguma ferramenta de captura de tela.

Pesquise no Google

Isso pode ser um conselho muito obvio, mas vejo muita gente perguntando algo que com apenas uma pesquisa resolveria o problema dela.

Seu problema não é especial, provavelmente alguém já passou por ele e perguntou em algum lugar da internet. Pesquisar no Google não apenas economiza tempo. Além disso, ao explorar fóruns, comunidades online e sites, você pode descobrir soluções detalhadas para problemas comuns.

Tenha cuidado com sites e fóruns que tenham respostas antigas, provavelmente aquela solução esteja desatualizada.

É importante destacar que a documentação da linguagem, biblioteca ou framework que você está utilizando é a fonte primária de informações. Ler a documentação pode fornecer inspirações valiosos sobre funcionalidades, métodos e práticas recomendadas.

Portanto, antes de postar sua pergunta em um fórum ou comunidade, reserve um tempo para pesquisar no Google. Essa abordagem não apenas fortalecerá suas habilidades de resolução de problemas, mas também o conectará com a riqueza de conhecimento disponível na vasta rede de desenvolvedores.

Escrevendo perguntas

Agora vou te mostrar como perguntar de maneira mais eficiente, facilitando a sua vida e a vida do programador que vai te ajudar.

Não pergunte assim❌

Pergunte assim ✅

As perguntas acima foram feitas apenas para ilustrar o meu ponto.

Na maioria das vezes a primeira pergunta é ignorada ou então atrai pessoas que não vão conseguir solucionar seu problema. O que a pessoa perguntou, na verdade, aqui é:

Qualquer programador que esteja disposto a se comprometer a investigar meu problema, seja ele qual for, mesmo que não seja realmente relacionado a programação ou se alguém que não sabe nada sobre programação poderia realmente responder à minha pergunta?

Agora veja duas perguntas feitas em uma comunidade do Discord, você vai notar a diferença de resposta.

No segundo, um pequeno contexto do problema, a dúvida que a pessoa tinha e em seguida uma captura de tela do erro, dá para perceber que as pessoas já aparecem com diferentes soluções.

No primeiro, tem menos diálogo, e as pessoas precisam perguntar o contexto e o seu objetivo para tentar te ajudar, isso parece algo pequeno, mas demanda energia e disposição.

Referências

Conclusão

Esse é meu primeiro post no dev.to e espero ter ajudado alguém😁. Foi um processo interessante.

Forem: Clinton Rocha

Criei uma pipeline de planejamento no OpenCode e olha no que deu

Índice

Como eu estava usando o OpenCode

Objetivo da integração

Plannotator: Revisão visual

Octto: Coleta estruturada de contexto

Fluxo de Funcionamento

Configuração via Fragments

Subtask2: Orquestração de pipeline

Sintaxe de Return Chain

Comandos

Comando Principal

Refinamento Técnico

Revisão Visual

Considerações

Referências

Laravel Modular [anotações]

Table of contents

1. Configuração de Módulos

1.1. Autoloading (PSR-4)

1.2. Service Providers

1.3. Testes Modulares

2. Modelos, Factories e DTOs

2.1. Conectando Factories a Models

2.2. Actions

2.3. Definindo Status de Modelos

2.4. Data Transfer Objects (DTOs)

3. IDE Helper

3.1. Instalação e Uso

3.2. Scripts para Composer

4. Views Modulares

4.1. Views Normais

4.2. Componentes Anônimos

4.3. Componentes de Classe

5. Ferramentas e Plugins

5.1. Laravel IDEA

5.2. Pacote Laravel Modules

6. Organização de Código: Abordagens

6.1. Vertical Slice

6.2. Agrupamento por Tipo (Grouping by Type)

7. Padrões de Design e Boas Práticas

7.1. Acoplamento Temporal vs. Eventos

8. Outros Tópicos

8.1. Sequences em Factories

[Boost]

"Ser" ou "estar" Senior?

Jessilyneh ・ Dec 27 '24

Um júnior e um teste técnico: The battle.

Table of contents

Objetivo proposto

Ferramentas escolhidas

Primeiros passos

Arquitetura e padrão de projeto

Tratamento de erros

Testes

Duvida

Questionamentos

Conclusão

Primeiros passos no Docker

Table of contents

Objetivo

Requisitos

O que é

Dockerfile

Docker Image

Container

Volume

Compose

CLI do Docker

Para gerenciar containers:

Para Gerenciar Imagens:

Para Gerenciar Redes:

Outros comandos úteis:

Botando a mão na massa

Seu primeiro Dockerfile

FROM

WORKDIR

COPY

RUN

`FROM`

`WORKDIR`

`COPY`

`RUN`

`EXPOSE`

`CMD`