DEV Community: Yuri Peixinho

Descomplicando GraphQL

Yuri Peixinho — Sat, 09 May 2026 15:16:33 +0000

Introdução

Podemos dizer que o GraphQL é o filhote de dois conceitos fundamentais na programação: API e Linguagens de Query/SQL

É uma linguagem de consulta para APIs e um runtime para executar essas consultas. É uma alternativa ao REST que dá ao cliente controle preciso sobre os dados que recebem.

O problema que ele resolve

Com REST, os desenvolvedores frequentemente enfrentam dois problemas:

Over-fetching: receber mais dados do que precisa (ex: buscar um usuário e receber 20 campos quando só quer o nome)
Under-fetching: fazer múltiplas requisições para montar uma tabela (ex: buscar → post → buscar autor → buscar comentários)

Com GraphQL, você pede exatamente o que precisa, em uma única requisição.

Conceitos fundamentais

1. Schema

O coração do GraphQL. Define os tipos de dados e as operações disponíveis

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]
}

type Post {
  id: ID!
  title: String!
  body: String!
  author: User!
}

2. Query (leitura)

O cliente especifica exatamente o que quer:

query {
  user(id: "1") {
    name
    posts {
      title
    }
  }
}

Resposta:

3. Mutation (escrita)

Para criar, atualizar ou deletar dados:

mutation {
  createPost(title: "Novo Post", body: "Conteúdo aqui") {
    id
    title
  }
}

4. Subscription (em tempo real)

Para ouvir eventos em tempo real via WebSocket:

subscription {
  newMessage(chatId: "42") {
    text
    sender { name }
  }
}

Quando usar?

✅ Boa escolha quando:

Múltiplos clientes (web, mobile) consomem os mesmos dados de formas diferentes
O frontend precisa de flexibilidade para evoluir sem depender do backend
Você tem dados interconectados (grafos de relacionamentos

⚠️ Talvez não valha a pena quando:

API simples com poucos endpoints
Time pequeno sem familiaridade com o ecossistema
Caching HTTP simples é suficiente (REST se beneficia mais disso)

Descomplicando RPC e gRPC

Yuri Peixinho — Sat, 09 May 2026 14:56:24 +0000

Introdução

A Chamada de Procedimento Remoto (RPC) é um dos paradigmas mais simples de API, em que um cliente executa um bloco de código em outro servidor.

Imagine que você tem um aplicativo no seu computador (Cliente) e ele precisa calcular uma fórmula complexa. Em vez de calcular isso localmente, ele chama uma função chamada CalcularImposto(). A mágica do RPC é que essa função não existe no seu computador; ela está em um servidor do outro lado do mundo.

Para fazer isso parecer local, o RPC usa um conceito chamado Stub:

O Cliente chama o Client Stub (um pedaço de código local que finge ser a função real).
O Stub pega os parâmetros que você passou, empacota tudo (processo chamado de Serialização) e envia pela rede.
O servidor recebe a mensagem, passa para o Server Stub, que desempacota os dados (Desserialização) e chama a função real.
O resultado faz o caminho inverso até chegar ao seu cliente.

O grande objetivo do RPC é esconder a complexidade da rede. O desenvolvedor apenas chama funções, sem se preocupar em montar requisições HTTP ou gerenciar conexões manualmente.

Exemplo

POST
/api/conversations.archive
HOST slack.com
Content-Type: application/x-www-form-urlencoded
Authorization:
Bearer xoxp-1650112-jgc2asDae

channel=C01234

API de Conversação do Slack

Diferente do REST, onde o verbo é passado no argumento do método HTTP, no RPC o verbo é explícito dentro da URI.

Método	Descrição
conversations.archive	Archives a conversation.
conversations.close	Closes a direct message or multi-person direct message.
conversations.create	Initiates a public or private channel-based conversation
conversations.history	Fetches a conversation's history of messages and events.
conversations.info	Retrieve information about a conversation.
conversations.invite	Invites users to a channel.
conversations.join	Joins an existing conversation.
conversations.kick	Removes a user from a conversation.
conversations.leave	Leaves a conversation.
conversations.list	Lists all channels in a Slack team.
conversations.members	Retrieve members of a conversation.
conversations.open	Opens or resumes a direct message or multi-person direct message.

Descomplicando o REST

Yuri Peixinho — Sat, 09 May 2026 14:35:16 +0000

O paradigma REST

A transferência de Estado Representacional (REST) é a escolha mais popular para o desenvolvimento da API nos últimos anos.

Baseado no conceito central de recursos. Um recurso é uma entidade que pode ser identificada, nomeada, endereçada ou tratada na web.

As APIs REST expõem dados como recursos e usam métodos HTTP padrão para representar transações Criar, Ler, Atualizar e Excluir (CRUD) contra esses recursos.
Por exemplo, a API da Stripe representa clientes, encargos, saldos, reembolsos, eventos, arquivos e pagamentos como recursos.

Exemplo na API do Sripe

Requisição HTTP para recuperar uma cobrança da API Stripe

**GET**
/v1/charges/ch_CWyut1Xs9pZyfD
HOST api.stripe.com
Authorization: Bearer YNoJlYq64iCBhzfL9HNO00fzVrsEjtV

Requisição HTTP para enviar uma cobrança na API Stripe

POST 
/v1/charges
HOST api.stripe.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bea
rer
YNoJlYq64iCBhzfL9HNO00fzVrsEjtVl

amount=2000&currency=usd

Uso de métodos HTTP

Métodos HTTP como GET, POST, UPDATE e DELETE informam o servidor sobre a ação a ser realizada.
Diferentes métodos HTTP invocados na mesma URL fornecem funcionalidades diferentes.
Criar: Use o POST, na maioria dos casos, para criar novos recursos.
Ler: Use o GET para ler recursos. Requisições GET nunca mudam o estado do recurso. Elas não têm efeitos colaterais. O GET é idempotente.
Atualização: Use o PUT para substituir um recurso e PATCH para atualizações parciais para os recursos existentes. o PUT também é idempotente
Excluir: Use o DELETE para excluir recursos existentes. O DELETE também é idempotente

Nomenclatura

Os recursos fazem parte de URLs, como /usuarios

Para cada recurso, duas URLs são geralmente implementadas: uma para a coleção, como /usuarios, e uma para elemento específico, como /usuarios/U123

Nomes são usados em vez de verbos para definir recursos. Por exemplo, em vez de /lerInformacaoUsuario/U123, use /usuario/U123.

Códigos de Resposta

Imagine que você envia uma carta para alguém. A resposta que você recebe de volta pode ser:

✅ "Entregue com sucesso!"
🔄 "O destinatário se mudou, tente outro endereço"
❌ "Carta com endereço errado"
💥 "O correio teve um problema interno"

É exatamente assim que funcionam os códigos HTTP — são respostas do servidor ao seu navegador/aplicação.

Geralmente, os códigos na faixa 2XX indicam sucesso, 3XX indicam que um recurso de moveu e códigos na faixa 4XX indicam um erro do lado do cliente (como um parâmetro necessário ausente ou muitas solicitações).

Códigos na faixa 5XX indicam erros do lado do servidor.

Descomplicando Tabela de Códigos

🟢 2XX — Sucesso

O servidor recebeu, entendeu e processou sua requisição.

Código	Nome	Significado
200	OK	Tudo certo! Resposta padrão de sucesso
201	Created	Um recurso foi criado (ex: cadastro feito)
204	No Content	Sucesso, mas sem nada para retornar

🔵 3XX — Redirecionamento

O recurso que você pediu está em outro lugar.

Código	Nome	Significado
301	Moved Permanently	Mudou de endereço para sempre
302	Found	Redirecionamento temporário
304	Not Modified	Use o cache, nada mudou

🟡 4XX — Erro do Cliente

Você fez algo errado na requisição.

Código	Nome	Significado
400	Bad Request	Requisição mal formada
401	Unauthorized	Precisa estar autenticado (fazer login)
403	Forbidden	Autenticado, mas sem permissão
404	Not Found	O recurso não existe
429	Too Many Requests	Você fez requisições demais (rate limit)

🔴 5XX — Erro do Servidor

O servidor que teve um problema, não você.

Código	Nome	Significado
500	Internal Server Error	Erro genérico no servidor
502	Bad Gateway	Servidor intermediário recebeu resposta inválida
503	Service Unavailable	Servidor fora do ar ou sobrecarregado
504	Gateway Timeout	O servidor demorou demais para responder

Formatos de resposta

As APIs REST podem devolver respostas JSON ou XML. E devido à sua simplicidade e facilidade de uso com Javascript, o JSON tornou-se o padrão para APIs modernas.

O XML e outros formatos ainda podem ser suportados para facilitar a adoção para clientes que ainda estão trabalhando nesse formatos usando APIs semelhantes.

No Brasil, o XML é comum em APIs do governo para facilitar a governança dos dados, como NF-E ou E-Social

Convenções para um CRUD com REST

Operação	Verbo HTTP	URL: /usuarios	URL: /usuários/123
Criar	POST	Cria um novo usuário	Não é aplicável
Ler	GET	Lista todos os usuários	Recupera o usuário 123
Atualizar	PUT ou PATCH	Atualiza em lote os usuários	Atualiza o usuário 123
Remover	DELETE	Apaga todos os usuários	Apaga o usuário 123

Verbo HTTP	URI Exemplo	Semântica
POST	/livros/123/autores	Criar os autores para o livro 123
GET	/livros/123/autores/1	Recupera o autor 1 do livro 123
PUT ou PATCH	/livros/123/autores/1	Atualiza os dados do autor 1 do livro 123
DELETE	/livros/123/autores	Apaga todos os autores do livro 123

Operações não CRUD

Além das operações típicas da CRUD que acabamos de olhar, as APIs REST às vezes precisam representar operações não-CRUD.

As seguintes abordagens são comumente usadas nesse caso:

Crie uma ação como um subrecurso.

GET livros/empromocao

Crie uma ação através de parâmetros de entrada

GET livros?tipo=empromocao&categoria=autoajuda

APIs (Application Interface Programming)

Yuri Peixinho — Sat, 09 May 2026 01:55:35 +0000

Introdução

Uma API é a interface que uma aplicação de software apresenta a outras aplicações.

As APIs são os blocos de construção que permitem a interoperabilidade para as principais plataformas de negócios na web.

As APIs permitem que identidades sejam criadas e mantidas em contas de software em nuvem, desde seu endereço de e-mail corporativo, a software de design colaborativo.

Habilitam os compartilhamento de dados de previsão do tempo para aplicações
Processam seus cartões de créditos e permitem que as empresas recebem seus dinheiro sem preocupações regulatórias

APIs simplificam o uso de outro softwares

bd3a18c-8cfd-4e32-80bd-65306503eb1d:image.png)

Para enviar uma mensagem de WhatsApp via código, por exemplo, o desenvolvedor não precisa entender como os servidores da Meta funcionam, nem como a criptografia de ponta a ponta é processada matematicamente. Ele só precisa se comunicar com a API do serviço de mensagens.

Isso garante duas grandes vantagens:

Foco no Produto: Empresas ganham agilidade ao integrar soluções já prontas (como mapas, pagamentos e envios de e-mail) em vez de "reinventar a roda".
Independência de Linguagem: Uma API bem construída não se importa se o seu aplicativo foi programado em Python, Java, PHP ou Node.js. Desde que a mensagem seja enviada no padrão correto, a comunicação acontece.

Tipos de APIs

Nem toda API tem a mesma funcionalidade e propósito. O desenvolvedor deve saber qual o propósito ao construir e resusar a API.

APIs para Soluções Móveis

O número de dispositivos móveis e tablets superou o número de computadores. Os aplicativos para celular são diferentes dos aplicativos de desktop tradicion

ais, já que a maioria dos aplicativos móveis não é autônoma nem autossuficiente.

Os aplicativos precisam se conectar aos servidores na Internet para serem utilizáveis ou, pelo menos, serem utilizáveis em todo o seu potencial.
Os dados entregues pelas APIs precisam ser leves e particionados. Isso garante que a API possa ser consumida por dispositivos com capacidade de processamento limitada e largura de banda limitada de conexão à Internet.

APIs para Soluções de Nuvem

As soluções em nuvem SaaS normalmente consistem em um aplicativo da Web e APIs. O aplicativo da web é visível para os consumidores.
Embaixo do capô, as soluções em nuvem geralmente oferecem uma API também, no entanto, a API normalmente permanece sob a superfície. Essa API pode ser usada para conectar o aplicativo de nuvem a outros aplicativos de nuvem para realizar a automação ou para conectar a solução de nuvem a aplicativos móveis e software de desktop.
O Dropbox é um exemplo para esse tipo de solução em nuvem. A API desta solução de nuvem permite que muitos aplicativos de terceiros se conectem ao Dropbox, incluindo ferramentas de sincronização para dispositivos móveis e desktop.

APIs para Soluções de Integração

APIs fornecem os recursos, que são essenciais para conectar, estender e integrar software. Ao integrar software, as APIs conectam empresas a outras empresas. Eles são usados em soluções de integração de negócios para empresas.
O negócio de uma empresa pode ser expandido conectando-se os negócios aos parceiros para cima e para baixo na cadeia de valor.
Como os negócios são executados pela TI, os negócios podem ser mais bem vinculados, integrando os sistemas de TI de um negócio em toda a cadeia de valor aos sistemas de TI de outras empresas, parceiros, funcionários e, é claro, aos clientes.

APIs para Soluções Multi-Canal

Sistemas diversos oferecem aos clientes a possibilidade de fazer compras em várias plataformas: no celular, na Web ou no tablet.
Para melhorar a experiência de uso, os mesmos dados e ações do usuário precisam estar disponíveis em todos os dispositivos do usuário, mesmo que sejam construídos em hardware diferente, executem sistemas operacionais diferentes e aplicativos diferentes.
Soluções Omni-Canal ou soluções multicanais fornecem exatamente isso. Independentemente do canal usado pelos clientes, eles obtêm uma experiência consistente em todos os dispositivos e podem alternar facilmente entre os dispositivos.

APIs para Soluções IoT

A internet das coisas é composta de dispositivos físicos com uma conexão à internet.
Os dispositivos são controlados por software por meio de seus atores ou os dispositivos podem coletar dados por meio de seus sensores.
Assim, o dispositivo em si não precisa ser "inteligente", no entanto, ele pode se comportar como um dispositivo inteligente.

A Agenda do arquiteto para APIs

Como identificar, escolher e desenhar APIs?
Como implementar e testar APIs?
Como documentar e comunicar APIs?
Como definir tecnologias de APIs?
Como gerenciar APIs?
Como descobrir e reusar APIs?

O processo de construção de APIs

Descobrimos como a maioria dos consumidores gostaria de usar a nova API.
Projetamos a API para que ela se encaixe no portfólio de diferentes APIs que nossa empresa oferece.
Escolhemos o estilo arquitetônico, ou seja, se a API aplica um estilo REST, RPC, SOAP, WebSocket, entre outros.
Projetamos um protótipo da API usando uma linguagem de descrição da API, como RAML ou Open API (Swagger).
Simulamos a API e criamos um protótipo da API.
Selecionamos a plataforma da API, que fornece os blocos de construção reutilizáveis para as APIs.
Implementamos e testamos a API, uma pedaço por vez.
Implantamos e gerenciamos a API em ambiente de produção
Aumentamos o engajamento para descoberta e uso das APIs criadas.

Ciclo de Vida de APIs com Plataformas

ISP — Interface Segregation Principle (Princípio da Segregação de Interface)

Yuri Peixinho — Thu, 29 Jan 2026 21:42:18 +0000

Interface Segregation Principle

O ISP afirma que uma interface não deve forçar a classe a implementar métodos que elas não utilizam. A ideia é quebras grandes interfaces em menores e mais específicas, ou seja, em vez de interfaces gigantes e genéricas (”interfaces gordas”), devemos ter “interfaces magras”, quebradas e mais específicas.

“Clientes não devem ser forçados a depender de métodos que não usam.”

Pense nisso como um menu de restaurante:

Violação do ISP: O restaurante obriga você a comprar o combo com hambúrguer, batata, refrigerante, sorvete e café, mesmo que você só queira o hambúrguer
Aplicação do ISP: O menu é segregado. Você pode pedir itens individuais ou combos menores que façam sentido para o seu "apetite" (necessidade)

Exemplo didático do problema

Imagine que temos a Interface chamada ITrabalhador, ela possui métodos como Codificar(), Testar() e GerenciarProjetos().

Você vai criar uma classe chamada Programador que implementa essa interface. Até esse cenário tudo ocorre como o esperado.
O problema é que se você criar uma classe Gerente, e implementar a mesma interface ela será obrigada a implementar Codificar(), mesmo que o gerente não escreva código.

Essa prática cria um acoplamento desnecessário e “polui” o código com métodos vazios ou que lançam exceções como throw new NotImplementedException.

Exemplo técnico do problema

Vamos retomar o exemplo acima e desenvolver com o código com C# de duas formas, uma que viola o ISP e outra que não viola.

1. Violação estrutural

using System;

// Uma "Interface Gorda" que tenta fazer tudo
public interface ITrabalhador
{
    void Codificar();
    void Testar();
    void GerenciarProjeto();
}

public class Programador : ITrabalhador
{
    public void Codificar() => Console.WriteLine("Escrevendo código C#...");
    public void Testar() => Console.WriteLine("Testando bugs...");
    public void GerenciarProjeto() => Console.WriteLine("Atualizando o JIRA..."); 
    // Ok, talvez o programador faça um pouco de tudo.
}

public class Gerente : ITrabalhador
{
    public void Codificar()
    {
        // Oxente! O Gerente não deveria ser obrigado a ter este método.
        throw new NotImplementedException("Gerentes não codificam!");
    }

    public void Testar()
    {
        throw new NotImplementedException("Gerentes não testam!");
    }

    public void GerenciarProjeto() => Console.WriteLine("Gerenciando o time...");
}

2. O Jeito Correto

Agora, vamos segregar (separar) as interfaces. Assim, cada classe só assina o "contrato" que realmente consegue cumprir.

// Interfaces segregadas e específicas (Interfaces Magras)
public interface ICodificador
{
    void Codificar();
}

public interface ITestador
{
    void Testar();
}

public interface IGerente
{
    void GerenciarProjeto();
}

// O Programador implementa apenas o que faz sentido para ele
// Ele pode implementar múltiplas interfaces se necessário!
public class Programador : ICodificador, ITestador
{
    public void Codificar() => Console.WriteLine("Escrevendo código C#...");
    public void Testar() => Console.WriteLine("Testando bugs...");
}

// O Gerente agora está limpo e focado
public class Gerente : IGerente
{
    public void GerenciarProjeto() => Console.WriteLine("Gerenciando o time...");
}

LSP - Liskov Substitution Principle (Princípio da Substituição de Liskov)

Yuri Peixinho — Tue, 27 Jan 2026 01:41:36 +0000

O terceiro princípio é o Liskov Substituition Principle. Ele foi definido por Barbara Liskov em 1987 e, embora que por definição academia pareça ser um “bicho de setes cabeças”, na prática é bem simples e ideal para criar sistemas robustos.

O princípio diz que: Uma classe derivada deve poder ser substituída por sua classe base sem que o comportamento do programa seja alterado ou quebrado.

Para cumprir o príncpio pense assim: “O filho (classe que herda) deve conseguir fazer tudo que o pai (classe pai) prometeu que faria”. Se o pai diz "eu sei somar dois números", o filho não pode dizer "eu só sei somar se os números forem positivos". Isso seria uma surpresa desagradável para quem usa o código.

Analogia com Pássaros

Imagine que você tem um sistema para um zoológico.

Você cria a Entidade Passaro
Você define que todo Passaro tem a habilidade de voar.

Até aqui, tudo bem. Aí você cria os tipos específicos:

Pardal (É um Pássaro): Voa? Sim. ✅ (Tudo certo, segue o princípio).
Águia (É um Pássaro): Voa? Sim. ✅ (Tudo certo).

Agora vem o problema. Você precisa adicionar um Pinguim.

Pinguim (É um Pássaro): Voa? Não. ❌

Onde o princípio quebra?

Se você tem uma parte do seu código que diz: “Pegue todos os pássaros e faça-os voar”, quando chegar a vez do Pinguim o programa vai travar ou dar erro, porque pinguins não voam. Na aplicação promete que todo pássaro voa, mas o pinguim não cumpre essa promessa.

Como consertar o exemplo do Pinguim?

Em vez de colocar "Voar" na categoria principal Passaro, você deve criar uma categoria mais específica ou separar as habilidades:

Classe `Passaro` (Tem bico, bota ovos).
Classe PassaroQueVoa (Herda de Pássaro + sabe voar).
Classe PassaroQueNada Herda de Pássaro + sabe nadar).

Dessa forma o Pardal entra em PassaroQueVoa e o Peguim em PassaroQueNada

E o melhor: ninguém promete o que não pode cumprir, e o código não quebra.

Exemplo aplicado ao código

Vamos retomar o exemplo acima e desenvolver com o código com C# de duas formas, uma que viola o LSP e outra que não viola.

1. Violação Estrutural

Imagine que você tem uma classe abstrata Passaro. Em C#, é comum usarmos classes abstratas ou interfaces para definir contratos.

O exemplo abaixo viola o LSP porque o Pinguim não pode substituir Passaro sem causar efeitos colaterais (a exceção).

Classe Base

public abstract class Passaro
{
    public abstract void Voar();
}

Implementação Concreta

public class Pardal : Passaro
{
    public override void Voar()
    {
        Console.WriteLine("Pardal voando alto!");
    }
}

Implementação que viola o LSP

public class Pinguim : Passaro
{
    public override void Voar()
    {
        // O compilador obriga a implementar Voar(),
        // mas a lógica não permite. O dev lança uma exceção.
        throw new NotImplementedException("Pinguins não voam!");
    }
}

2. O Jeito Correto

Em C#, a melhor forma de resolver isso é segregando as capacidades através de Interfaces. Nem todo pássaro é um IVoador.

Essa implementação abaixo torna impossível passar um Pinguim para um método que espera IVoador. O compilador do C# vai te impedir antes mesmo de você rodar o programa.

Definição de abstração (interface e classe abstrata)

// Define apenas o que é comum a TODOS
public abstract class Ave 
{
    public void Comer() { Console.WriteLine("Comendo..."); }
}

// Interface (Capacidade) separada
public interface IVoador
{
    void Voar();
}

Implementações

// Pardal é uma Ave E sabe voar
public class Pardal : Ave, IVoador
{
    public void Voar() 
    { 
        Console.WriteLine("Pardal voando!"); 
    }
}

// Pinguim é apenas uma Ave (não implementa IVoador)
public class Pinguim : Ave 
{
    // Pode ter métodos de nadar aqui
}

OCP — Open/Closed Principle (Princípio Aberto/Fechado)

Yuri Peixinho — Mon, 26 Jan 2026 23:58:55 +0000

Princípio Aberto/Fechado

Esse é o segunda pilar do SOLID. Sua fundamentação existe para que os softwares criados sejam fáceis de manter e evoluir sem quebrar o que já funciona.

Certo! Mas o que diabos isso significa? Os sistemas não são estáticos, eles tendem a evoluír. O cenário comum no mercado, portanto, é: com novas definições de funcionalidades os desenvolvedores geralmente alteram o código-fonte existente, código este, que já foi testado e homologado. Resultando em um sistema difícil de manter e “sustentar”.

O OCP surge para mitigar esse problema e a definição foi criada por Bertrand Meyer:

"Entidades de software (classes, módulos, funções, etc.) devem estar abertas para extensão, mas fechadas para modificação."

Aberto pra Extensão: Você é deve ser capaz de adicionar novos comportamentos e funcionalidades ao sistema à medida que os requisitos mudam.

Fechada para Modificações: Ao adicionar essa nova funcionalidade, você não deve alterar o código-fonte existente que já foi estado e está funcionando

Metáfora da Tomada

Tenho um professor que comparou esse princípio com uma tomada. elétrica de parede.

Ela é fechada pra modificação, já que você não precisa quebrar a parede e refazer a fiação elétrica da casa toda vez que compra um novo eletrodoméstico
Ela é abertura para extensão, você pode instalar uma TV, ventilador ou carregador estendendo a utilidade daquela rede relétrica, apenas plugando algo novo. A interface (os buracos da tomada) permitee isso.

Exemplo prático

Vamos desenvolver um cálculo de Bônus Anual. Imagine uma classe CalculadoraDeBonus. Inicialmente, a empresa só tem "Desenvolvedores" e "Gerentes".

Exemplo Ruim (Violando OCP)

Nesta abordagem comum (mas ruim), usamos um switch ou if/else para verificar o cargo. O problema: quero adicionar dois novos cargos, diretor e estagiário. Para isso eu preciso abrir a classe e modificá-la diretamente! Isso viola o OCP

public class CalculadoraDeBonus
{
    public decimal Calcular(string cargo, decimal salario)
    {
        if (cargo == "Gerente")
        {
            return salario * 0.2m; 
        }
        else if (cargo == "Desenvolvedor")
        {
            return salario * 0.1m; 
        }

        // Se a empresa criar o cargo "Diretor" amanhã, 
        // VOU TER QUE ALTERAR ESTE ARQUIVO.
        return 0;
    }
}

O Risco: Ao editar esse arquivo para adicionar o "Diretor", você pode sem querer apagar uma linha ou mudar a lógica do "Gerente", causando bugs em algo que já estava testado.

Solução (Aplicando OCP)

Vou trazer duas abordagens para fechar a classe para modificação e abri-las para extensão. Ambas abordagens resolvem o OCP, mas elas comunicam intenções diferentes sobre o seu sistema.

Abordagem com Classe Abstrata
Abordagem com Interfaces

1. Abordagem com Classe Abstrata

Use essa abrodagem quando existe uma relação forte de herança e você quer reaproveitar propriedades ou métodos

Cenário: Todo funcionário tem Nome e Salario (código compartilhado), mas o cálculo do bônus muda.

Contrato

public abstract class FuncionarioBase
{
    // Código compartilhado (Reuso)
    public string Nome { get; set; }
    public decimal Salario { get; set; }

    // Obriga as classes filhas a implementarem a lógica específica
    public abstract decimal CalcularBonus();

    // Método comum que já funciona para todos (não precisa sobrescrever)
    public string ObterCracha() => $"Funcionário: {Nome}";
}

Aberto para extensões:

public class Gerente : FuncionarioBase
{
    public override decimal CalcularBonus()
    {
        return Salario * 0.2m;
    }
}

public class Desenvolvedor : FuncionarioBase
{
    public override decimal CalcularBonus()
    {
        return Salario * 0.1m;
    }
}

Uso


public void Processar(FuncionarioBase funcionario) 
{
    Console.WriteLine(funcionario.CalcularBonus()); 
}

2. Abordagem com Interface

Use esta abordagem quando o foco é o "O QUE FAZ" (Comportamento). Interfaces são contratos puros. Elas não carregam "bagagem" (estado ou variáveis) e permitem maior flexibilidade, pois uma classe pode implementar múltiplas interfaces.
Cenário: Aqui não nos importamos se é um funcionário, um prestador de serviço ou um robô. Só nos importamos se ele tem uma regra de bônus. Isso é frequentemente chamado de Strategy Pattern.

Contrato

// --- O Contrato (Interface) ---
public interface IRegraDeBonus
{
    decimal Calcular(decimal salarioBase);
}

public class BonusParaDesenvolvedor : IRegraDeBonus
{
    public decimal Calcular(decimal salarioBase)
    {
        return salarioBase * 0.1m;
    }
}

Aberto para extensões:


// Note que não herdamos de ninguém, apenas assinamos o contrato
public class BonusParaGerente : IRegraDeBonus
{
    public decimal Calcular(decimal salarioBase)
    {
        return salarioBase * 0.2m;
    }
}

Uso

public class CalculadoraServico
{
    // Recebemos a INTERFACE. Baixíssimo acoplamento.
    public decimal ExecutarCalculo(decimal salario, IRegraDeBonus regra)
    {
        return regra.Calcular(salario);
    }
}

Comparação entre abordagens: Abstract Class vs. Interface

Característica	Abstract Class	Interface
Relacionamento	"É um" (Hierarquia estrita). Um Gerente é um Funcionário.	"Faz isso" (Capacidade). Essa classe sabe calcular bônus.
Reuso de Código	Alto. Permite compartilhar propriedades (`Nome`, `ID`) e métodos concretos.	Baixo/Nenhum. Apenas define as assinaturas dos métodos.*
Herança	Limitada. C# só permite herdar de 1 classe. Se usar Abstract, você "gasta" essa cartada.	Múltipla. Uma classe pode implementar 5 interfaces diferentes (`IBonificavel`, `IAutenticavel`, etc).
Acoplamento	Médio. As filhas dependem da classe pai.	Baixíssimo. As classes só dependem do contrato.
Quando usar no OCP?	Quando você tem uma família de objetos intimamente relacionados que compartilham estrutura.	Quando você quer plugar comportamentos diferentes (Strategy Pattern) ou testabilidade máxima (Mocks).

No desenvolvimento moderno de C# (.NET Core/Dependency Injection), Interfaces são usadas em 90% dos casos para garantir o OCP, pois facilitam muito os testes unitários (Mocking).

SRP — Single Responsibility Principle (Princípio da Responsabilidade Única)

Yuri Peixinho — Mon, 26 Jan 2026 23:36:18 +0000

Single Responsability Principle

Esse é o primeiro pilar do SOLID. A definição clássica é “Uma classse deve ter um, e apenas um motivo pra mudar.”.

Na prática, isso quer dizer que uma classe deve ser responsável por uma funcionalidade/parte específica do software. Em sistemas “blocos de cimentos”, é comum encontrarmos as chamadas “God Objects” (Objeto Deus), uma classe gigantesca que sabem e fazem tudo. O que contradiz o princípio da responsabilidade única.

Analogia

Imagine um funcionário de um restaurante que é, ao mesmo tempo, o cozinheiro, o garçom e o faxineiro . Se ele precisar mudar a forma como limpa o chão, o serviço de cozinha e o atendimento podem ser afetados ou interrompidos. No SRP, dividimos essas tarefas entre especialistas para que um não atrapalhe a evolução do outro.

Exemplo

Vamos imaginar um cenário em que o princípio não foi aplicado e após isso vamos transformá-lo em um código modular. Imagine um sistema que gerencia pedidos de e-commerce.

Exemplo Problema

Na classe Pedido abaixo, temos três motivos diferentes para serem alterados. Se a regra de calculo, banco e e-mail mudar. Cada método representa uma responsabilidade diferente para a classe Pedido

class Pedido:
    def calcular_total(self):
        # Lógica de negócio (Preço, impostos, descontos)
        pass

    def salvar_no_banco(self):
        # Lógica de infraestrutura (Conexão SQL, tabelas)
        pass

    def enviar_email_confirmacao(self):
        # Lógica de comunicação (Servidor SMTP, template do e-mail)
        pass

Exemplo Solução

Para aplicar o SRP, separamos as tarefas em “especialistas”. Cada classe agora tem apenas uma razão para existir e mudar.

Pedido vai conter apenas a lógica de cálculo calcular_total
salvar_no_banco vai ser uma nova classe chamada PedidoRepository, que vai implementar o Padrão Repository
enviar_email_confirmacao vai ser um serviço separado apenas por enviar comunicações

Desse modo, se você decidir trocar o e-mail por uma mensagem no WhatsApp, você altera apenas o serviço respectivo. A regra de cálculo do Pedido então permanece segura e intocada, como uma peça LEGO independente

Exemplo aplicado a contexto: Clean Architecture, Mediator, CQRS e DDD

Veja como o SRP se manifesta em um CommandHandler usando Mediator:

// Este Handler tem UMA única razão para mudar: 
// Se o fluxo de "Criação de Pedido" for alterado.
public class CriarPedidoHandler : IRequestHandler<CriarPedidoCommand, Guid>
{
    private readonly IPedidoRepository _repository; // Interface (DIP)
    private readonly IMediator _mediator;

    public async Task<Guid> Handle(CriarPedidoCommand request, CancellationToken ct)
    {
        // 1. Regra de Negócio (DDD: Entidade decide se pode ser criada)
        var pedido = new Pedido(request.ClienteId, request.Itens);

        // 2. Persistência (Clean Arch: O Handler não sabe se é SQL ou NoSQL)
        await _repository.SalvarAsync(pedido);

        // 3. Comunicação (Mediator: Dispara um evento para quem interessar)
        // Isso separa a criação do pedido do envio de e-mail (SRP puro!)
        await _mediator.Publish(new PedidoCriadoEvent(pedido.Id));

        return pedido.Id;
    }

Veja o conteúdo completo aqui!

Princípios SOLID

Yuri Peixinho — Fri, 23 Jan 2026 01:57:50 +0000

Contexto do SOLID

Antigamente os sistemas eram desenvolvidos com um único objetivo: fazer o software funcionar. Os padrões utilizados eram monolíticos e rígidos, com forte acoplamento e com tudo interligado. Atualmente sistemas conhecidos como “Código espaguete” ou “Grande Bola de Lama”. Como tudo estava interligado, corrigir um erro em uma ponta do sistema geralmente causava erros em outras partes do sistema.

Crise do Software

Na década de 70 e 80 o desenvolvimento de software enfrentava uma crise. O hardware estava ficando incrivelmente potente e barato, mas o software estava se tornando tão complexo que as equipes não conseguiam mantê-los de forma eficiente.

Introdução ao SOLID

O SOLID veio pra transformar o desenvolvimento de software em uma tarefa artesanal em uma engenharia, focada em criar peças que se encaixam sem estarem “soldadas” umas nas outras. Ele é um conjunto de cinco princípios de design de software para a programação orientada a objetos (POO).

Em resumo, podemos dizer que os princípios funcionam como uma base/guia para os desenvolvedores arquitetarem soluções fáceis de manter, testar e evoluír ao longo do tempo.

Ao invés de desenvolvermos sistemas como “um grande bloco de cimento”, o SOLID nos ensina a construir softwares como peças “LEGO”, que se encaixam de forma inteligente.

1. Princípio da Responsabilidade Única

Esse é o primeiro pilar do SOLID. A definição clássica é “Uma classse deve ter um, e apenas um motivo pra mudar.”.

Analogia

Exemplo

Vamos imaginar um cenário em que o princípio não foi aplicado e após isso vamos transformá-lo em um código modular. Imagine um sistema que gerencia pedidos de e-commerce.

Exemplo Problema

class Pedido:
    def calcular_total(self):
        # Lógica de negócio (Preço, impostos, descontos)
        pass

    def salvar_no_banco(self):
        # Lógica de infraestrutura (Conexão SQL, tabelas)
        pass

    def enviar_email_confirmacao(self):
        # Lógica de comunicação (Servidor SMTP, template do e-mail)
        pass

Exemplo Solução

Para aplicar o SRP, separamos as tarefas em “especialistas”. Cada classe agora tem apenas uma razão para existir e mudar.

Pedido vai conter apenas a lógica de cálculo calcular_total
salvar_no_banco vai ser uma nova classe chamada PedidoRepository, que vai implementar o Padrão Repository
enviar_email_confirmacao vai ser um serviço separado apenas por enviar comunicações

Exemplo aplicado a contexto: Clean Architecture, Mediator, CQRS e DDD

Veja como o SRP se manifesta em um CommandHandler usando Mediator:

// Este Handler tem UMA única razão para mudar: 
// Se o fluxo de "Criação de Pedido" for alterado.
public class CriarPedidoHandler : IRequestHandler<CriarPedidoCommand, Guid>
{
    private readonly IPedidoRepository _repository; // Interface (DIP)
    private readonly IMediator _mediator;

    public async Task<Guid> Handle(CriarPedidoCommand request, CancellationToken ct)
    {
        // 1. Regra de Negócio (DDD: Entidade decide se pode ser criada)
        var pedido = new Pedido(request.ClienteId, request.Itens);

        // 2. Persistência (Clean Arch: O Handler não sabe se é SQL ou NoSQL)
        await _repository.SalvarAsync(pedido);

        // 3. Comunicação (Mediator: Dispara um evento para quem interessar)
        // Isso separa a criação do pedido do envio de e-mail (SRP puro!)
        await _mediator.Publish(new PedidoCriadoEvent(pedido.Id));

        return pedido.Id;
    }

2. Princípio Aberto/Fechado

Esse é o segunda pilar do SOLID. Sua fundamentação existe para que os softwares criados sejam fáceis de manter e evoluir sem quebrar o que já funciona.

O OCP surge para mitigar esse problema e a definição foi criada por Bertrand Meyer:

"Entidades de software (classes, módulos, funções, etc.) devem estar abertas para extensão, mas fechadas para modificação."

Aberto pra Extensão: Você é deve ser capaz de adicionar novos comportamentos e funcionalidades ao sistema à medida que os requisitos mudam.

Fechada para Modificações: Ao adicionar essa nova funcionalidade, você não deve alterar o código-fonte existente que já foi estado e está funcionando

Metáfora da Tomada

Tenho um professor que comparou esse princípio com uma tomada. elétrica de parede.

Ela é fechada pra modificação, já que você não precisa quebrar a parede e refazer a fiação elétrica da casa toda vez que compra um novo eletrodoméstico
Ela é abertura para extensão, você pode instalar uma TV, ventilador ou carregador estendendo a utilidade daquela rede relétrica, apenas plugando algo novo. A interface (os buracos da tomada) permitee isso.

Exemplo prático

Vamos desenvolver um cálculo de Bônus Anual. Imagine uma classe CalculadoraDeBonus. Inicialmente, a empresa só tem "Desenvolvedores" e "Gerentes".

Exemplo Ruim (Violando OCP)

public class CalculadoraDeBonus
{
    public decimal Calcular(string cargo, decimal salario)
    {
        if (cargo == "Gerente")
        {
            return salario * 0.2m; 
        }
        else if (cargo == "Desenvolvedor")
        {
            return salario * 0.1m; 
        }

        // Se a empresa criar o cargo "Diretor" amanhã, 
        // VOU TER QUE ALTERAR ESTE ARQUIVO.
        return 0;
    }
}

O Risco: Ao editar esse arquivo para adicionar o "Diretor", você pode sem querer apagar uma linha ou mudar a lógica do "Gerente", causando bugs em algo que já estava testado.

Solução (Aplicando OCP)

Vou trazer duas abordagens para fechar a classe para modificação e abri-las para extensão. Ambas abordagens resolvem o OCP, mas elas comunicam intenções diferentes sobre o seu sistema.

Abordagem com Classe Abstrata
Abordagem com Interfaces

Abordagem com Classe Abstrata

Use essa abrodagem quando existe uma relação forte de herança e você quer reaproveitar propriedades ou métodos

Cenário: Todo funcionário tem Nome e Salario (código compartilhado), mas o cálculo do bônus muda.

Contrato

public abstract class FuncionarioBase
{
    // Código compartilhado (Reuso)
    public string Nome { get; set; }
    public decimal Salario { get; set; }

    // Obriga as classes filhas a implementarem a lógica específica
    public abstract decimal CalcularBonus();

    // Método comum que já funciona para todos (não precisa sobrescrever)
    public string ObterCracha() => $"Funcionário: {Nome}";
}

Aberto para extensões:

public class Gerente : FuncionarioBase
{
    public override decimal CalcularBonus()
    {
        return Salario * 0.2m;
    }
}

public class Desenvolvedor : FuncionarioBase
{
    public override decimal CalcularBonus()
    {
        return Salario * 0.1m;
    }
}

Uso


public void Processar(FuncionarioBase funcionario) 
{
    Console.WriteLine(funcionario.CalcularBonus()); 
}

Abordagem com Interface

Contrato

// --- O Contrato (Interface) ---
public interface IRegraDeBonus
{
    decimal Calcular(decimal salarioBase);
}

public class BonusParaDesenvolvedor : IRegraDeBonus
{
    public decimal Calcular(decimal salarioBase)
    {
        return salarioBase * 0.1m;
    }
}

Aberto para extensões:


// Note que não herdamos de ninguém, apenas assinamos o contrato
public class BonusParaGerente : IRegraDeBonus
{
    public decimal Calcular(decimal salarioBase)
    {
        return salarioBase * 0.2m;
    }
}

Uso

public class CalculadoraServico
{
    // Recebemos a INTERFACE. Baixíssimo acoplamento.
    public decimal ExecutarCalculo(decimal salario, IRegraDeBonus regra)
    {
        return regra.Calcular(salario);
    }
}

Comparação entre abordagens: Abstract Class vs. Interface

Característica	Abstract Class	Interface
Relacionamento	"É um" (Hierarquia estrita). Um Gerente é um Funcionário.	"Faz isso" (Capacidade). Essa classe sabe calcular bônus.
Reuso de Código	Alto. Permite compartilhar propriedades (`Nome`, `ID`) e métodos concretos.	Baixo/Nenhum. Apenas define as assinaturas dos métodos.*
Herança	Limitada. C# só permite herdar de 1 classe. Se usar Abstract, você "gasta" essa cartada.	Múltipla. Uma classe pode implementar 5 interfaces diferentes (`IBonificavel`, `IAutenticavel`, etc).
Acoplamento	Médio. As filhas dependem da classe pai.	Baixíssimo. As classes só dependem do contrato.
Quando usar no OCP?	Quando você tem uma família de objetos intimamente relacionados que compartilham estrutura.	Quando você quer plugar comportamentos diferentes (Strategy Pattern) ou testabilidade máxima (Mocks).

No desenvolvimento moderno de C# (.NET Core/Dependency Injection), Interfaces são usadas em 90% dos casos para garantir o OCP, pois facilitam muito os testes unitários (Mocking).

3. Princípio da Substituição de Liskov

O princípio estabelece que uma classe derivada deve poder substituir sua classe base sem alterar ou comprometer o comportamento esperado do programa. Em outras palavras, ao herdar a classe B a partir da classe A, o desenvolvedor deve conseguir realizar tudo o que era possível com A utilizando B, mantendo as mesmas garantias de funcionamento e, se necessário, acrescentando novos comportamentos, mas nunca removendo ou quebrando os existentes.

Analogia com Pássaros

Imagine que você tem um sistema para um zoológico.

Você cria a Entidade Passaro
Você define que todo Passaro tem a habilidade de voar.

Até aqui, tudo bem. Aí você cria os tipos específicos:

Pardal (É um Pássaro): Voa? Sim. ✅ (Tudo certo, segue o princípio).
Águia (É um Pássaro): Voa? Sim. ✅ (Tudo certo).

Agora vem o problema. Você precisa adicionar um Pinguim.

Pinguim (É um Pássaro): Voa? Não. ❌

Onde o princípio quebra?

Como consertar o exemplo do Pinguim?

Em vez de colocar "Voar" na categoria principal Passaro, você deve criar uma categoria mais específica ou separar as habilidades:

Classe `Passaro` (Tem bico, bota ovos).
Classe PassaroQueVoa (Herda de Pássaro + sabe voar).
Classe PassaroQueNada Herda de Pássaro + sabe nadar).

Dessa forma o Pardal entra em PassaroQueVoa e o Peguim em PassaroQueNada

E o melhor: ninguém promete o que não pode cumprir, e o código não quebra.

Exemplo aplicado ao código

Vamos retomar o exemplo acima e desenvolver com o código com C# de duas formas, uma que viola o LSP e outra que não viola.

Violação Estrutural

Imagine que você tem uma classe abstrata Passaro. Em C#, é comum usarmos classes abstratas ou interfaces para definir contratos.

O exemplo abaixo viola o LSP porque o Pinguim não pode substituir Passaro sem causar efeitos colaterais (a exceção).

Classe Base

public abstract class Passaro
{
    public abstract void Voar();
}

Implementação Concreta

public class Pardal : Passaro
{
    public override void Voar()
    {
        Console.WriteLine("Pardal voando alto!");
    }
}

Implementação que viola o LSP

public class Pinguim : Passaro
{
    public override void Voar()
    {
        // O compilador obriga a implementar Voar(),
        // mas a lógica não permite. O dev lança uma exceção.
        throw new NotImplementedException("Pinguins não voam!");
    }
}

O Jeito Correto

Em C#, a melhor forma de resolver isso é segregando as capacidades através de Interfaces. Nem todo pássaro é um IVoador.

Essa implementação abaixo torna impossível passar um Pinguim para um método que espera IVoador. O compilador do C# vai te impedir antes mesmo de você rodar o programa.

Definição de abstração (interface e classe abstrata)

// Define apenas o que é comum a TODOS
public abstract class Ave 
{
    public void Comer() { Console.WriteLine("Comendo..."); }
}

// Interface (Capacidade) separada
public interface IVoador
{
    void Voar();
}

Implementações

// Pardal é uma Ave E sabe voar
public class Pardal : Ave, IVoador
{
    public void Voar() 
    { 
        Console.WriteLine("Pardal voando!"); 
    }
}

// Pinguim é apenas uma Ave (não implementa IVoador)
public class Pinguim : Ave 
{
    // Pode ter métodos de nadar aqui
}

4. Principio da Segragação de Interface

“Clientes não devem ser forçados a depender de métodos que não usam.”

Pense nisso como um menu de restaurante:

Violação do ISP: O restaurante obriga você a comprar o combo com hambúrguer, batata, refrigerante, sorvete e café, mesmo que você só queira o hambúrguer
Aplicação do ISP: O menu é segregado. Você pode pedir itens individuais ou combos menores que façam sentido para o seu "apetite" (necessidade)

Exemplo didático do problema

Imagine que temos a Interface chamada ITrabalhador, ela possui métodos como Codificar(), Testar() e GerenciarProjetos().

Você vai criar uma classe chamada Programador que implementa essa interface. Até esse cenário tudo ocorre como o esperado.
O problema é que se você criar uma classe Gerente, e implementar a mesma interface ela será obrigada a implementar Codificar(), mesmo que o gerente não escreva código.

Essa prática cria um acoplamento desnecessário e “polui” o código com métodos vazios ou que lançam exceções como throw new NotImplementedException.

Exemplo técnico do problema

Vamos retomar o exemplo acima e desenvolver com o código com C# de duas formas, uma que viola o ISP e outra que não viola.

1. Violação estrutural

using System;

// Uma "Interface Gorda" que tenta fazer tudo
public interface ITrabalhador
{
    void Codificar();
    void Testar();
    void GerenciarProjeto();
}

public class Programador : ITrabalhador
{
    public void Codificar() => Console.WriteLine("Escrevendo código C#...");
    public void Testar() => Console.WriteLine("Testando bugs...");
    public void GerenciarProjeto() => Console.WriteLine("Atualizando o JIRA..."); 
    // Ok, talvez o programador faça um pouco de tudo.
}

public class Gerente : ITrabalhador
{
    public void Codificar()
    {
        // Oxente! O Gerente não deveria ser obrigado a ter este método.
        throw new NotImplementedException("Gerentes não codificam!");
    }

    public void Testar()
    {
        throw new NotImplementedException("Gerentes não testam!");
    }

    public void GerenciarProjeto() => Console.WriteLine("Gerenciando o time...");
}

2. O Jeito Correto

Agora, vamos segregar (separar) as interfaces. Assim, cada classe só assina o "contrato" que realmente consegue cumprir.

// Interfaces segregadas e específicas (Interfaces Magras)
public interface ICodificador
{
    void Codificar();
}

public interface ITestador
{
    void Testar();
}

public interface IGerente
{
    void GerenciarProjeto();
}

// O Programador implementa apenas o que faz sentido para ele
// Ele pode implementar múltiplas interfaces se necessário!
public class Programador : ICodificador, ITestador
{
    public void Codificar() => Console.WriteLine("Escrevendo código C#...");
    public void Testar() => Console.WriteLine("Testando bugs...");
}

// O Gerente agora está limpo e focado
public class Gerente : IGerente
{
    public void GerenciarProjeto() => Console.WriteLine("Gerenciando o time...");
}

5. Princípio da Inversão de Dependência

A definição formal do quinto princípio parece um pouco técnica:

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

O conceito de Dependency Inversion (DI) pode deixar desenvolvedores imaturos confuso, isso porque esse conceito geralmente surge de uma necessidade prática e real e as explicações geralmente possuem níveis de abstrações que exiga a compreensão por completo do fluxo de um sistema. Antes de entendermos sobre o assunto temos que entender o que são os módulos de baixo e alto nível de um sistema

Módulos de alto e baixo nível

Entender como o sistema de comporta em níveis de módulos e a relação entre eles é de extrema importância para a compreensão do conceito de DI.

Alto nível

O foco aqui é a regra de negócio, lógica central, é aqui que existe o “valor” do que é o sistema. Deve ser algo estável e mudar pouco. Por exemplo: calcular o frete de um pedido, gerar uma fatura ou processar um pagamento.

Baixo nível

O foco é os detalhes de implementação, mecanismos concretos. São os braços e as pernas que executam o que é demandado pelo módulo de alto nível, mas não definem as regras. Isto posto, está mais sujeito a mudanças e alguns exemplos são: bancos de dados específicos, frameworks de interfaces, etc…

Relação entre alto e baixo nível

De forma resumida, podemos dizer que:

Alto nível = o que o sistema faz (regras de negócio).

Baixo nível = como o sistema faz (detalhes técnicos).

Abstração = a ponte que une os dois, mantendo o alto nível protegido dos detalhes.

Didaticamente explicando o conceito:

O alto nível diz: “Preciso calculas fretes”
O baixo nível responde: “Ok, sei falar com os Correios e calcular o valor”

Se o alto nível depender diretamente dos detalhes (Correios), ele fica preso apenas a um serviço, então se amanhã mudar para FedEx, a alteração deverá ser feita na alta escala do sistema (alto nível), o que é uma péssima prática.

Para resolver a problemática acima, podemos utilizar a seguinte abordagem:

O alto nível só conhece a regra “alguém que calcule frete”
O desenvolvedor cria a abstração ICalculadoraFrete
O baixo nível (Correios ou FedEx) implementa essa abstração
O alto nível não precisa mudar quando trocarmos serviço postal

Inversão de dependência

A ideia central da inversão de dependência é “desamarrar” as regras de negócios a um detalhe específico de implementação. Já que essa prática deixa o sistema rígido e difícil de mudar.

Analogia do dia a dia

Sem DI: Um carro que só funciona se você abastecer com a gasolina da “Bandeira X”
Com DI: O carro depende apenas da abstação (interface) “combustível líquido inflamável”
- Pode ser gasolina comum, aditivada, etanol ou até biocombustível

Com base na analogia acima, a gente é capaz de perceber que com a Inversão de dependência o carro não se prende aos detalhe da gasolina (baixo nível), ele só depende da abstração de um combustível

Aplicando o princípio da Inversão de Dependência

Para utilizar a inversão de dependência vamos aplicar a Inversão de Controle (IoC) e Injeção de Dependência (DI)

1. Criamos uma interface (um contrato)

public interface INotificacaoService
{
    void Enviar(string mensagem);
}

Aqui estamos dizendo: "Eu não me importo como a mensagem será enviada. Só quero que exista alguém capaz de executar o método Enviar()." Isso é lindo. Porque o PedidoService não quer saber de e-mail, SMS, WhatsApp, sinal de fumaça... ele só quer enviar.

2. Criamos implementações dessa interface

Enviar por E-mail:

public class EmailService : INotificacaoService
{
    public void Enviar(string mensagem)
    {
        Console.WriteLine("Enviando Email: " + mensagem);
    }
}

3. PedidoService não se importa mais com o como

Agora ele só recebe a dependência via construtor:

public class PedidoService
{
    private readonly INotificacaoService _notificacaoService;

    // INJEÇÃO DE DEPENDÊNCIA VIA CONSTRUTOR
    public PedidoService(INotificacaoService notificacaoService)
    {
        _notificacaoService = notificacaoService;
    }

    public void FinalizarPedido()
    {
        _notificacaoService.Enviar("Pedido finalizado!");
    }
}

Deploy: Cenário: Azure App Service + Github + SQL Server

Yuri Peixinho — Thu, 08 Jan 2026 23:07:31 +0000

Introdução

Deploy não é um botão. É um processo consciente de levar software para o mundo real. Geralmente quando não temos conhecimento sobre os processos de deploy ficamos com algumas questões pendentes em nossa mente:

Onde o código roda?
Como ele chega lá?
Como ele acessa o banco?
Como configuro sem expor segredo (secret)?
Como atualizo sem quebrar tudo?

Vamos passar por todo esse processo com aplicação em um cenário real.

As peças do cenário que vamos montar

Azure App Service: onde a aplicação roda
Github: onde seu código vive
Github Actions (opcional, mas recomendado): automação de build e deploy
Azure SQL Database (SQL Server): onde seus dados ficam

GitHub (código)
↓
Pipeline (build / deploy)
↓
Azure App Service (API / App)
↓
Azure SQL Database (dados)

1. O que é o Azure App Service?

Como já vimos nos tipos de servidores, podemos dizer que o Azure Service é um serviço gerenciado. Isso significa que você:

Não cria servidor
Não instala Windows/Linux
Configura IIS, Kestrel, Nginx manualmente

1.1 App Service

A plataforma Azure cuida de todas essas questões pra você e quando você cria um App Service, você está definindo

Runtime (ex: .NET 8)
Plano de hospedagem (CPU / memória / custo)
Região (onde o servidor fica)

Que resulta em uma URL pública e um ambiente pronto pra a execução do seu código:

https://minha-api.azurewebsites.net

Nesse momento, não tem código nenhum rodando ainda.

1.2 Como o código chega na Azure? (Github Actions)

Após a configuração do Azure App Service ser concluída precisamos efetivamente subir o nosso código de um determinado repositório para o Azure. Em nossa abordagem vamos utilizar o Github Actions e entender o problema que ele resolve.

1.1.1 Processo manual

Antes do Github Actions, o deploy normalmente era assim:

O desenvolvedor faz o seguinte processo:

Compila local
Publica manualmente
Sobre arquivo por FTP

Esse processo gera problemas como inconsistência, erro humano, falta de histórico e deploys imprevisíveis

1.1.2 Github Actions

Podemos dizer que o GitHub Actions é um robô configurável que roda dentro do GitHub sempre que algo acontece no repositório.

Esse “algo” pode ser:

push
pull request
criação de tag
horário agendado

Esse robô pode compilar código, rodar testes, gerar build, fazer deploy, enviar notificações, etc. Isso tudo só acontece porque um workflow é configurado.

1.3 O que é um workflow e o que ele tem a ver com tudo isso?

Um workflow é um arquivo .yml que diz sugere: “Quando X acontecer, execute Y passos nessa ordem”, então, por exemplo:

SE alguém fizer push na branch main
ENTÃO:
  - compile
  - teste
  - publique
  - faça deploy

E esse arquivo fica em:

.github/workflows/deploy.yml

Esse arquivo é código, portanto, o Deploy passa a ser versionado, auditável e repetível.

2. Criando o SQL Server no Azure

Ao criar um banco de dados no Azure, você já vai ter backup automático, alta disponibilidade e sem precisar instalar nada.

Ao final do processo você vai ter o nome do servidor, nome do banco, usuário e senha. Essas informações nunca deve ir no código.

Quando você cria o Azure SQL Database, o Azure cria duas coisas:

2.1 Servidor Lógico (SQL Server)

Não é uma VM (Virtual Machine) e sim um endpoint gerenciado para autenticação e conexões. Esse servidor:

Pode ter vários bancos
Centraliza segurança
Controla firewall

No portal do Azure:

Azure SQL → Create
Você define:
- Server name → meu-servidor.database.windows.net
- Admin login
- Senha

2.2 Banco de dados

Dentro do servidor:

Você cria o banco nomeDoBanco
Define
- Camada (Basic / General Purpose / Business Critical)
- DTUs / vCores

2.3 Firewall do SQL Server

Por padrão ninguém consegue acessar o banco.

Você precisa configurar: Networking → Firewall rules

Opções:

✔️ Allow Azure services
✔️ Adicionar IP da sua máquina (para migrations locais)

⚠️ Sem isso:

App não conecta
Migration falha
Erro de timeout

👉 Em produção real:

Ideal é Private Endpoint
Mas para início: firewall simples resolve

3. Connection String, o elo entre a aplicação e o banco

Essa é uma das partes mais importante de todo deploy. Sem essa conexão, nada conecta com a base de dados.

Sem ela:

A aplicação sobe ✔️
O banco existe ✔️
Mas nada se comunica ❌

Ou seja: API no ar, mas toda requisição que depende de dados falha.

3.1 O que você já criou no Azure SQL Database

Ao criar sua base de dados no Azure (SQL Server), você definiu:

Nome do servidor
Nome da base de dados
Admin Login
Senha
Tipo de autenticação (SQL Authentication)

Essas informações são a base da sua connection string.

3.2 O que é, na prática, uma Connection String?

É um texto que informa à aplicação:

Onde está o banco
Qual banco acessar
Como autenticar
Como se comportar durante a conexão

Exemplo genérico:

Server=...
Database=...
User Id=...
Password=...

3.3 De onde vem o valor da Connection String?

No Azure SQL Database:

SQLDatabase
 → Settings
     → Connection strings

Normalmente você verá algo como:

Server=tcp:meuservidor.database.windows.net,1433;
Initial Catalog=MinhaBase;
PersistSecurityInfo=False;
User ID=adminuser;
Password=********;
MultipleActiveResultSets=False;
Encrypt=True;
TrustServerCertificate=False;
Connection Timeout=30;

Copie exatamente essa string e cole no campo Value.

3.4 Agora vamos ligar App → Banco

Essa configuração é feita diretamente no Azure App Service, sem precisar alterar código.

3.4.1 Caminho no Azure Portal

App Service
 → Settings
 → Configuration
 → Connection strings

Essa área funciona como um cofre de segredos da aplicação.

✅ Mais seguro

✅ Separado do código

✅ Ideal para ambientes (Dev / Homologação / Produção)

3.4.2 Nome da Connection String (Muito Importante)

Se você usa Entity Framework Core, o nome mais comum (e recomendado) é:

DefaultConnection

Esse nome precisa bater exatamente com o que está no seu Program.cs ou appsettings.json.

Exemplo comum no código:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(
        builder.Configuration.GetConnectionString("DefaultConnection")));

Se o nome for diferente no Azure:

❌ A aplicação sobe

❌ Mas não encontra o banco

❌ Erro clássico: The ConnectionString property has not been initialized

4. Migrações

Agora vem a parte mais importante do deploy com banco. Vamos separar em três trilhas bem práticas:

Migration Manual Local → Azure SQL
Migration via GithubActions → Azure SQL (Pipeline)
Migration por script SQL (práticas usadas por empresas)

4.1. Migration Manual (local → Azure SQL)

Pré-requisitos:

Projeto com EF Core
Migrations já criadas

Isso não mexe no banco ainda, apenas gera os arquivos C#.

4.2. Liberar o acesso ao banco no Azure

Por padrão, o Azure SQL bloqueia tudo e precisamos autorizar nossa máquina local, sem isso nosso sistema dará o erro: Login failed / Timeout expired

O que isso faz:

Autoriza sua máquina local
Permite que o dotnet ef conecte no banco remoto

No Portal Azure:

Azure SQL Server
Networking
Firewall rules
Add your client IPv4 address
Save

4.3. Garantir que sua aplicação aponta para o Azure

Garante que seu arquivo appsettings.Development.json está apontando para o SQL Server no azure.

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=tcp:meuservidor.database.windows.net;..."
  }
}

4.4. Executar a migration

dotnet ef database update

O que acontece por trás:

EF abre conexão com o Azure SQL
Verifica se existe a tabela:

__EFMigrationsHistory

Se não existir → cria
Se existir → lê quais migrations já rodaram
Compara:
- Migrations no código
- Migrations no banco
Executa somente as pendentes
Registra a versão aplicada

Introdução ao Deploy

Yuri Peixinho — Thu, 08 Jan 2026 23:06:12 +0000

Introdução

Quando estamos desenvolvendo uma aplicação escrevemos o código em nosso computador. Esse código depois de escrito só consegue ser rodado em ambiente local e a aplicaçõo só pode ser acessada pelo seu próprio dispositivo.

Mas como faz pra esse código rodar 24h por dia e acessível para outras pessoas? O deploy é a resposta. É o processo de “pegar” um software e colocá-lo em um ambiente que execute ele continuamente de forma estável, segura e acessível.

O que precisa pra rodar o software?

Todo sistema em produção precisa de 4 coisas básicas.

Código (sua aplicação)
Máquina pra executar o código
Dados (banco de dados, arquivos)
Rede (internet)

Mais afinal, onde onde o deploy acontece?

O Deploy acontece no servidor. O servidor é um computador ligado 24h, com CPU, memória, disco, sistema operacional, internet, etc. Uma observação importante é que você pode usar seu computador como um servidor (mas não é recomendado)

Tipos de servidores (do mais simples ao moderno)

Servidor Físico

É uma máquina real em um datacenter, você cuida de tudo. Geralmente é caro e complexo

Máquina Virtual (VM)

Um servidor virtual dentro de outro servidor, você controla o SO (Sistema Operacional).

Azure VM
EC2 (AWS)

Plataforma Gerenciada (PaaS)

Você só cuida do código e a nuvem cuida do servidor

Azure App Service

Containers (Docker)

Seu aplicativo é empacotado com tudo que precisa e roda igual em qualquer lugar

Orquestração (Kubernates)

Gerencia vários containers, alta escala e complexidade

O que acontece durante um deploy?

Agora que sabemos o que é o deploy e quais são os tipos de servidores, vamos imaginar um deploy manual?

Desenvolvedor escreve o código
Compila o código (build)
Copia os arquivos para o servidor
Configura variáveis de ambiente (ex: string de conexão, senhas de integrações, etc.).
Inicia a aplicação
Abre porta de rede
Aponta um domínio
Monitora erros

Camadas de Validações de um Sistema backend

Yuri Peixinho — Mon, 10 Nov 2025 23:46:55 +0000

Introdução

Como você já deve saber, sistemas geralmente têm entrada e saída de dados (Input/Output). Esses dados de entradas são armazenados em alguma base de dados existente. Portanto, esses dados precisam ser controlados e validados para manter a consistência de sua aplicação.

Por exemplo, se temos um campo de CPF (11 dígitos fixos) não podemos deixar o usuário inserir em nossa base de dados um CPF que contém 8 ou 15 dígitos ou que ele consiga criar dois CPFs iguais.

Tipos de validações

No backend existem três níveis principais de validação e é importante entender a diferença entre os conceitos.

Validação de Entrada (Camada de API/Controller)
Validação de Negócio (Camada de Aplicação /Domain Service)\
Validação de Consistência/Infraestrutura

Validação de Entrada (Camadas de API/Controller)

Ocorre logo no início da aplicação (entrada de dados) e o objetivo é garantir que os dados cheguem válidos na camada de aplicação. É nessa camada que será realizado a validação posterior, de negócios. É aqui que o sistema valida a estrutura e o formato, mas nunca a lógica do negócio.

Exemplo: verificar se o CPF tem 11 dígitos, mas não se ele existe no banco.

Validação de Negócio (Camada da Aplicação/Domain Service)

Essa camada é posterior a validação de entrada. Caso todas as informações fornecidas no input da aplicação esteja correta, passamos para a fase da validação de negócio, seu objetivo é garantir que a ação faça sentido pra o sistema.

Existem dois níveis de validação de regra de negócio.

Regras de Entidades (invariantes)
Regras de negócio entre entidades (Serviço de Domínio)

Regras de Entidades (invariantes)

São regras auto-suficientes que pertencem a uma única entidade e vão dentro da própria classe. As invariantes servem pra garantir consistência do domínio.

Exemplos:

Não permitir criar um boleto para um cliente bloqueado.
Impedir alteração de uma remessa já enviada.
Garantir unicidade de um registro lógico (ex: CPF de uma pessoa).

public class Remessa
{
    public Guid RemessaId { get; private set; }
    public int BancoId { get; private set; }
    public Header Header { get; private set; }
    public string ArquivoTXT { get; private set; }

    public Remessa(int bancoId, Header header, string arquivoTXT)
    {
        BancoId = bancoId;
        Header = header;
        ArquivoTXT = arquivoTXT;

        ValidarDominio();
    }

    public void ValidarDominio()
    {
        if (Header is null)
            throw new DomainException("Header da remessa não pode ser nulo.");

        if (string.IsNullOrWhiteSpace(ArquivoTXT))
            throw new DomainException("Arquivo TXT não pode estar vazio.");

        if (Header.Agencia.Length != 4)
            throw new DomainException("A agência deve ter 4 dígitos.");
    }
}

Repare que:

ValidarDominio() garante que nenhum objeto Remessa inválido possa existir.
O construtor força a validação logo na criação.
As propriedades têm private set, ou seja, ninguém de fora pode alterar o estado diretamente.

E você pode criar uma DomainException personalizada (mais elegante do que ValidationException):

public class DomainException : Exception
{
    public DomainException(string message) : base(message) { }
}

Regras de negócios entre Entidades

Essa camada geralmente valida as relações entre entidades, processos e cenário do negócio. Ele é o ponto que entende o contexto e orquestra o uso correto das entidades.

Essa validação não valida formatos ou invariantes. Ele valida cenários de negócios como:

“Um cliente não pode ter duas assinaturas ativas”
“Não é possível emitir uma fatura para um pedido cancelado”
“O banco informado precisa existir e estar ativo”

Percebe que são regras contextuais e relacionais e não estruturais?

Em qua fluxo de processo ela se encaixa? Ela vive entre o application Service e o Domain, e geralmente é acionada logo depois que os dados foram validados e antes de criar ou persistir entidades.

Controller  
  ⇣  
DTO Validation (FluentValidation) (Validação de formato)
  ⇣  
Application Service  
  ⇣  
Business Validation (processo / contexto) <- É aqui que entra!
  ⇣  
Domain Validation (invariantes da entidade)  
  ⇣  
Repository / Persistência

Normalmente essa etapa de validação se localiza den tro de Application:

Application/
│
├── Validation/
│   ├── DTO/                # FluentValidation
│   ├── Business/           # Regras contextuais
│   └── Domain/             # (opcional: regras complexas do domínio)

Essa camada de validação geralmente utiliza repositórios, serviços de domínios e contexto de processos. Isto é:

Repositório: verificar estados do sistema (se já exist algo no banco)
Serviços de Domínio: se a regra envolve lógica consolidada, por exemplo: verificar limite de crédito, calcular juros, validar estoque
Contexto de Processo: estado do sistema e coerência entre entidades, exemplo: impedir fatura de pedido cancelado, proibir duplicidade de remessa.

Validação de Consistência/Infraestrutura

Essa é a última etapa de validação e a mais crucial. O objetivo é proteger o sistema e o banco de dados de inconsistências estruturais. Ocorre na camada de repository e banco de dados.

Exemplos:

Chaves únicas (UNIQUE, PRIMARY KEY).
Relacionamentos (FOREIGN KEY).
Restrições de tipo (CHECK, NOT NULL).