DEV Community: He4rt Developers

Do localhost para o mundo

Bruno Freschi — Mon, 22 Jun 2026 15:07:19 +0000

Por muito tempo eu acreditei que programação e desenvolvimento de software como sinônimos. Na prática, descobri que são habilidades diferentes.

Existe uma diferença entre aprender a programar e aprender a trabalhar como desenvolvedor.

Os Exercícios Isolados

Quando você está aprendendo a programar, o cenário é controlado. Você trabalha em exercícios com começo, meio e fim:

O problema é perfeitamente definido.
O código é criado do zero.
Você conhece e domina todas as peças envolvidas.

Muitos concluem cursos, criam projetos pessoais e, ainda assim, não se sentem prontos para uma vaga.

Então, o primeiro emprego chega e, com ele, o choque:

"Eu consigo construir um CRUD, mas não consigo entender o projeto da empresa. Por que não consigo contribuir?"

Isso não significa falta de capacidade. Significa apenas que você treinou programação, o que é totalmente natural, e agora vai começar a desenvolver software em um ambiente real.

Do localhost para o mundo

No primeiro emprego, o cenário muda drasticamente. Você não recebe uma tela em branco; recebe acesso a uma aplicação com milhares de arquivos, dezenas de bibliotecas, regras de negócio acumuladas por anos, débitos técnicos que nunca foram pagos e decisões tomadas por pessoas que nem trabalham mais lá.

O desafio deixa de ser "como criar uma solução" e passa a ser "como entender uma solução que já existe".

A maior dificuldade do mercado não é a sintaxe da linguagem ou escrever código, mas sim compreender o contexto. Seus primeiros meses não serão consumidos por algoritmos complexos (pelo menos não nesse primeiro momento), mas por perguntas como:

Como executar o projeto?
Onde está a regra de negócio?
Quem consome esta API?
Posso alterar isso sem quebrar outra funcionalidade?

O gargalo não é a sintaxe. É o ecossistema.

O que as trilhas tradicionais não ensinam

Grande parte dos cursos foca no básico e salta diretamente para conceitos como:

POO
SOLID
Design Patterns

Tudo isso é importante. Mas quase ninguém ensina habilidades como:

Ler código.
Navegar em bases.
Investigar bugs, depurar aplicações.
Trabalhar com Git.
Participar de code reviews.
Entender requisitos incompletos ou ambíguos.

No trabalho, o foco muda de "Como eu resolvo este problema?" para "Como eu resolvo este problema sem quebrar o restante do sistema?".

Essa mudança transforma completamente a forma de pensar. O desenvolvedor deixa de otimizar apenas a solução e passa a considerar manutenção, impacto, riscos, dependências e custo de mudança.

Sobrevivendo aos Primeiros Meses

Para tentar mudar essa realidade, precisamos de uma base mais próxima do dia a dia profissional. Uma abordagem que foque menos em exercícios isolados e mais em entrar em projetos existentes, corrigir bugs, ler mais código do que escrever e lidar com a regra do negócio.

Porque o que determina o seu sucesso no primeiro emprego raramente é saber um Design Pattern de cor. É a capacidade de entrar em uma base de código desconhecida e, gradualmente, se tornar alguém capaz de fazer mudanças com segurança e gerar valor para o time.

Para tentar aproximar esse cenário de uma forma mais prática, pensei em preparar uma série chamada "Do localhost para o mundo". Junto com ela, pretendo criar um repositório para simular alguns problemas de uma aplicação em produção e expor desafios semelhantes.

O que vem por aí:

Você recebeu acesso ao projeto. E agora?: (O primeiro dia, clonando e rodando o ambiente).
Git: Branches, merges, rebases e pull requests no fluxo real.
Como ler código que você não escreveu: (Identificando o entrypoint, seguindo o fluxo e usando o debugger).
Encontrando sua primeira tarefa: (Entendendo o card, reproduzindo o bug e estimando o impacto).

Prepare o seu café.
Nos vemos no próximo artigo!

De 6 horas para 40 segundos: como um índice de banco de dados salvou um job crítico de produção

Fernando Andrade — Sat, 06 Jun 2026 20:19:13 +0000

De 6 horas para 40 segundos: como um índice de banco de dados salvou um job crítico de produção

"Às vezes, a solução mais elegante não está no código está em ensinar o banco de dados a encontrar o que ele já tem."

Índice

O cenário: um job noturno que virou um problema diurno
O problema cresceu junto com a tabela
O diagnóstico: o Azure Application Insights apontou o caminho
A solução: um índice bem posicionado
O impacto real: economia de tempo total por dia
Mas afinal: o que é um índice de banco de dados?
Como identificar quando você precisa de um índice
Anatomia do índice que resolveu o problema
Conclusão

O cenário: um job noturno que virou um problema diurno

Todo sistema que lida com monitoramento contínuo eventualmente enfrenta o mesmo desafio: quanto mais dados acumulam, mais lenta fica a análise. Foi exatamente isso que aconteceu em um projeto no qual trabalhei.

A arquitetura era simples na teoria: um job agendado rodava durante a madrugada, disparando N processos paralelos cada um cadastrado individualmente pelo cliente. A lógica de cada processo era fazer uma comparação entre o resultado do dia atual (D+0) com o resultado do dia anterior (D-1), algo como:

"O que mudou desde ontem?"

Para isso, cada processo precisava buscar seu último resultado registrado, usando uma query com ORDER BY last_execution DESC filtrada pelo identificador do processo. Parece trivial. E durante um bom tempo, foi.

O problema cresceu junto com a tabela

Com o tempo, a tabela de resultados foi crescendo naturalmente, afinal, cada processo registra um novo resultado a cada execução. O que antes demorava milissegundos começou a demorar segundos. Depois, dezenas de segundos. Até que um dia percebemos:

A janela de execução do job, que deveria ser de até 4 horas, estava chegando a 12 horas.

Isso significava que um job que deveria terminar antes do horário comercial estava ainda em execução quando os usuários começavam a trabalhar de manhã, gerando inconsistências, bloqueios e reclamações.

A pergunta era: onde estava o gargalo?

O diagnóstico: o Azure Application Insights apontou o caminho

Ao analisar as métricas de performance no Azure Application Insights, ficou evidente que o problema estava concentrado em uma única operação: a query que buscava o último resultado de cada processo.

Internamente, a tabela de resultados tinha crescido o suficiente para que um ORDER BY last_execution DESC sem suporte de índice forçasse o banco a fazer um full scan, ou seja, varrer linha por linha até encontrar o registro mais recente. Multiplique isso por dezenas (ou centenas) de processos rodando em paralelo e você tem uma receita para o caos.

Antes da correção

1 linha(s) recuperada(s) — 1.754s, em 2025-08-11 às 09:19:01

Quase 2 segundos por consulta. Para um único processo, tolerável. Para N processos simultâneos, catastrófico.

A solução: um índice bem posicionado

A correção foi aplicar um índice composto na tabela de resultados, cobrindo exatamente os campos usados na query crítica:

CREATE INDEX idx_job_result_process_date
  ON app_schema.job_results (fk_process_id, date_created DESC)
  INCLUDE (id, final_result, report_id, result_payload);

Esse índice foi criado diretamente no ambiente de produção (pode ser gerado localmente também, dependendo da política da equipe) e o resultado foi imediato.

Depois da correção

1 linha(s) recuperada(s) — 0.003s, em 2025-08-11 às 09:32:00

De 1,754 segundos para 0,003 segundos por consulta. Uma redução de 99,8% no tempo de resposta.

O impacto real: economia de tempo total por dia

Cenário	Tempo acumulado de processamento/dia
❌ Antes do índice	~6 horas e 18 minutos
✅ Depois do índice	~40 segundos

O job voltou a terminar bem antes do horário comercial. Os processos diurnos pararam de ser impactados. E tudo isso sem reescrever uma linha de código de negócio.

Mas afinal: o que é um índice de banco de dados?

Se você chegou até aqui e nunca parou para entender o que um índice faz de verdade, esse é o momento.

A analogia do livro

Imagine que você tem um livro enciclopédico com 10.000 páginas e precisa encontrar tudo que fala sobre "fotossíntese". Você tem duas opções:

Sem índice: Ler página por página do início ao fim. Funciona, mas demora.
Com índice: Ir até o índice remissivo no final do livro, localizar "fotossíntese" em segundos e ir direto às páginas certas. Um índice de banco de dados funciona exatamente assim. Ele é uma estrutura de dados separada (geralmente uma B-Tree) que mantém uma cópia ordenada de uma ou mais colunas, com ponteiros para as linhas reais da tabela.

O que um índice resolve?

Buscas por igualdade: WHERE id = 42 o índice encontra o valor direto, sem varrer a tabela
Buscas por intervalo: WHERE date_created BETWEEN '2025-01-01' AND '2025-12-31'
Ordenação: ORDER BY last_execution DESC se o índice já estiver ordenado nessa direção, o banco nem precisa ordenar
Queries cobertas (covering index): Com a cláusula INCLUDE, o banco pode responder à query inteira só pelo índice, sem nem tocar na tabela original ### O que um índice não é (e quando ele atrapalha)

Índice não é gratuito. Ele tem custos:

Espaço em disco: o índice ocupa armazenamento adicional
Custo de escrita: toda vez que um INSERT, UPDATE ou DELETE acontece, os índices afetados também precisam ser atualizados
Manutenção: índices fragmentados precisam ser reorganizados periodicamente Por isso, criar índices sem critério pode ser tão prejudicial quanto não tê-los. A regra de ouro é:

Crie índices nas colunas que aparecem frequentemente em cláusulas WHERE, JOIN, ORDER BY e GROUP BY de queries lentas, especialmente em tabelas grandes.

Como identificar quando você precisa de um índice

Alguns sinais de alerta:

Queries que demoram mais conforme a tabela cresce (como o nosso caso)
Full table scans aparecendo nos planos de execução (EXPLAIN / Query Execution Plan)
Timeouts em operações que antes eram rápidas
CPU do banco de dados consistentemente alta durante períodos de consulta Ferramentas como o Azure Application Insights, pg_stat_statements (PostgreSQL), slow query log (MySQL) e o Query Store (SQL Server) são aliadas valiosas nesse diagnóstico.

Anatomia do índice que resolveu o problema

Voltando ao índice criado:

CREATE INDEX idx_job_result_process_date
  ON app_schema.job_results (fk_process_id, date_created DESC)
  INCLUDE (id, final_result, report_id, result_payload);

Por que esse design?

Componente	Motivo
`fk_process_id`	Filtro principal da query (cada processo tem seu identificador)
`date_created DESC`	A query precisa do resultado mais recente primeiro
`INCLUDE (...)`	Colunas retornadas pela query, incluí-las evita um segundo acesso à tabela

O resultado é um covering index: o banco responde à query inteira consultando apenas o índice, sem precisar buscar dados na tabela principal. É a forma mais eficiente de otimização de leitura possível.

Conclusão

Performance não é só sobre algoritmos ou arquitetura de microsserviços. Às vezes, o gargalo está numa operação aparentemente simples que o banco de dados precisa executar milhares de vezes por dia, e que ninguém percebe até que o custo acumulado se torne um problema real.

Nesse caso, um único índice bem pensado transformou 6 horas de processamento em 40 segundos. Sem refatoração. Sem mudança de arquitetura. Sem downtime.

Se você ainda não tem o hábito de revisar os planos de execução das suas queries críticas, comece agora. O banco de dados tem muito a te contar, basta saber ouvir.

Sugestões de leitura para se aprofundar: B-Tree indexes, covering indexes, query execution plans, índices compostos e ferramentas de profiling como EXPLAIN ANALYZE.

DataAccess: Entity Framework

Bruno Freschi — Thu, 07 May 2026 03:13:39 +0000

O Entity Framework (EF Core) fecha essa trindade do acesso a dados no .NET. Enquanto o ADO.NET te dá o controle mais baixo e o Dapper fica no meio termo, o EF Core é o peso-pesado da produtividade e da abstração.

Aqui está o guia, estruturado.

Entity Framework Core — Guia Prático

1. Visão Geral

O Entity Framework Core (EF Core) é um mapeador objeto-relacional (ORM) moderno, de código aberto e multiplataforma para o .NET. Ele abstrai quase que totalmente o banco de dados, permitindo que você trabalhe com dados usando objetos C# fortemente tipados.

Ele foi projetado para oferecer:

Altíssima produtividade (gera o SQL para você)
LINQ (Language Integrated Query) para escrever queries direto no C#
Migrations para controle de versão do esquema do banco de dados
Rastreamento de mudanças (Change Tracking) automático

Diferente do Dapper e do ADO.NET, o EF Core foca em produtividade e em manter a lógica de dados próxima ao paradigma de orientação a objetos.

Quando usar EF Core

Use EF Core quando:

O foco principal do projeto é a velocidade de desenvolvimento (Time-to-Market)
Você precisa de um CRUD padrão sem querer escrever SQL manualmente
Deseja manter o código independente de banco de dados (fácil portabilidade de SQL Server para PostgreSQL, por exemplo)
Precisa de recursos complexos como carregamento tardio (Lazy Loading) ou carregamento explícito

Evite quando:

Performance extrema de microssegundos for o requisito número um
Você precisa executar queries altamente complexas ou muito específicas do banco
Operações em lote (ETL) gigantescas sem o uso de recursos de Bulk específicos
O overhead de memória do rastreamento de entidades for um problema

2. Instalação

O EF Core é modular. Você instala o pacote principal e o provedor do banco de dados escolhido.

Via CLI:

dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Design

(O pacote Design é necessário para rodar as Migrations).

3. Conceitos Fundamentais

3.1 O DbContext

O DbContext é o coração do EF Core. Ele representa uma sessão com o banco de dados.

public class AppDbContext : DbContext
{
    public DbSet<Cliente> Clientes { get; set; }

    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.UseSqlServer("SuaConnectionStringAqui");
    }
}

3.2 Query (SELECT) com LINQ

Você não escreve SQL. Você usa LINQ, e o EF Core traduz para SQL em tempo de execução:

using var context = new AppDbContext();

// Retorna todos os clientes com e-mail do Gmail
var clientes = context.Clientes
    .Where(c => c.Email.EndsWith("@gmail.com"))
    .ToList();

3.3 FirstOrDefault / SingleOrDefault

Funcionam de forma idêntica ao Dapper, mas usando LINQ:

// Retorna o primeiro ou nulo
var cliente = context.Clientes.FirstOrDefault(c => c.Id == 1);

// Espera exatamente 1 resultado (lança exceção se houver mais de um)
var clienteUnico = context.Clientes.SingleOrDefault(c => c.Email == "email@email.com");

3.4 Operações de Escrita (INSERT, UPDATE, DELETE)

O EF Core rastreia as entidades em memória e só envia os comandos para o banco quando você chama SaveChanges().

Insert:

var novoCliente = new Cliente { Nome = "Gabrielly", Email = "email@email.com" };
context.Clientes.Add(novoCliente);
context.SaveChanges(); // Aqui o SQL INSERT é executado

Update:

var cliente = context.Clientes.Find(1);
cliente.Nome = "Nome Alterado"; 
context.SaveChanges(); // O EF detecta a mudança e gera o UPDATE

4. Parâmetros e Segurança

4.1 SQL Injection? O EF Core já te protege

Como o LINQ gera consultas parametrizadas por padrão, você está automaticamente protegido contra SQL Injection na esmagadora maioria dos casos.

string emailBusca = "usuario@email.com";
// Seguro por padrão. O EF cria o parâmetro @p0 no SQL gerado.
var cliente = context.Clientes.FirstOrDefault(c => c.Email == emailBusca);

4.2 Executando SQL Puro com Segurança

Se precisar rodar SQL manual no EF, use FromSql com interpolação segura:

// O EF Core converte a interpolação em parâmetros de forma segura!
var clientes = context.Clientes
    .FromSql($"SELECT * FROM Clientes WHERE Nome = {nomeVar}")
    .ToList();

5. Mapeamento Avançado

5.1 Carregamento de Relacionamentos (JOIN)

Para trazer dados de tabelas relacionadas, você usa o Include (Eager Loading):

var clientesComPedidos = context.Clientes
    .Include(c => c.Pedidos) // Faz o JOIN com a tabela de Pedidos
    .ToList();

6. Transações

Por padrão, o SaveChanges() já executa tudo dentro de uma transação implícita. Se você precisar envolver múltiplas operações ou múltiplos contextos:

using var context = new AppDbContext();
using var transaction = context.Database.BeginTransaction();

try
{
    context.Clientes.Add(novoCliente);
    context.SaveChanges();

    context.Logs.Add(new Log { Mensagem = "Cliente inserido" });
    context.SaveChanges();

    transaction.Commit();
}
catch
{
    transaction.Rollback();
    throw;
}

7. Performance

7.1 Por que dizem que o EF Core é lento?

O EF Core carrega uma árvore de expressões complexa para traduzir LINQ em SQL e, por padrão, mantém uma cópia de cada objeto lido na memória para rastrear alterações (Change Tracking).

7.2 Como torná-lo ultra rápido (Boas práticas):

Use AsNoTracking(): Para consultas somente leitura (onde você não vai dar Update), desabilite o rastreamento. O consumo de memória despenca e a velocidade dobra.C#

var clientesLeitura = context.Clientes.AsNoTracking().ToList();

Evite trazer todas as colunas: Use Select para trazer apenas o que precisa (Projection).

var nomesClientes = context.Clientes
    .Select(c => new { c.Id, c.Nome })
    .ToList();

Execute Delete/Update em massa: Antigamente era preciso carregar para a memória para deletar. O EF Core permite fazer isso direto no banco:

context.Clientes.Where(c => c.Ativo == false).ExecuteDelete();

8. Uso em ETL

Historicamente, o EF Core era péssimo para ETL devido ao overhead do rastreamento de estado. Hoje, ele se tornou muito viável se usado corretamente:

Use AsNoTracking().
Utilize ExecuteUpdate e ExecuteDelete para manipulação em massa sem carregar dados para a memória.
Se precisar fazer inserções massivas, desabilite o rastreador e insira em lotes (Batches) de 500 a 1000 registros por SaveChanges().

9. Comparação Técnica

Característica	Entity Framework	Dapper	ADO.NET
Performance	Média / Alta (se otimizado)	Alta	Muito Alta
Geração de SQL	Automática	Manual	Manual
Migrations	Sim (Nativo)	Não	Não
Curva de Aprendizado	Alta	Média	Baixa

10. Boas Práticas

Sempre use AsNoTracking() em consultas de leitura.
Não abuse do Lazy Loading (pode gerar o problema de N+1 consultas no banco).
Monitore o SQL que o EF está gerando no console durante o desenvolvimento.
Mantenha suas entidades focadas no domínio e use DTOs para tráfego de dados.

11. Armadilhas Comuns

Problema do N+1: Executar uma query para listar clientes e depois disparar uma nova query de pedidos para cada cliente da lista por não usar o Include.
Esquecer do AsNoTracking em telas de relatórios que carregam milhares de linhas.
Fazer filtros em memória: Usar .ToList() antes do .Where(). Isso traz a tabela inteira para a memória do C# para só depois filtrar.

DataAccess: Dapper

Bruno Freschi — Wed, 22 Apr 2026 17:59:33 +0000

O Dapper é um micro ORM (Object-Relational Mapper) para .NET que estende o ADO.NET. Ele foi projetado para oferecer:

Alta performance (próximo ao ADO.NET puro)
Baixo overhead
Controle total sobre SQL
Mapeamento simples entre objetos e queries

Diferente de ORMs completos como Entity Framework, o Dapper não abstrai o SQL, ele trabalha junto com ele.

Quando usar Dapper

Use Dapper quando:

Performance é crítica (ex: ETL, processamento em lote)
Queries são complexas ou altamente otimizadas
Você quer controle total do SQL
Baixo overhead é necessário

Evite quando:

Precisa de tracking automático de entidades
Quer abstração completa do banco
CRUD simples sem preocupação com performance

Instalação

Via CLI:

dotnet add package Dapper

Ou via NuGet Package Manager:

Install-Package Dapper

Conceitos Fundamentais

3.1 Extensão do IDbConnection

O Dapper funciona como extensão de IDbConnection:

using (var connection = new SqlConnection(connectionString))
{
    var result = connection.Query("SELECT * FROM Clientes");
}

3.2 Query (SELECT)

Retorna dados mapeados automaticamente:

var clientes = connection.Query<Cliente>(
    "SELECT Id, Nome, Email FROM Clientes"
);

Mapeia por convenção:

Nome da coluna = Nome da propriedade

3.3 QueryFirst / QuerySingle

Diferença importante:

// Retorna o primeiro ou default
var cliente = connection.QueryFirstOrDefault<Cliente>(
    "SELECT * FROM Clientes WHERE Id = @Id",
    new { Id = 1 }
);

// Espera exatamente 1 resultado
var cliente = connection.QuerySingle<Cliente>(
    "SELECT * FROM Clientes WHERE Id = @Id",
    new { Id = 1 }
);

Use QuerySingle quando:

Você garante que existe exatamente 1 registro

3.4 Execute (INSERT, UPDATE, DELETE)

var rows = connection.Execute(
    "INSERT INTO Clientes (Nome, Email) VALUES (@Nome, @Email)",
    new { Nome = "Gabrielly", Email = "email@email.com" }
);

Retorna:

Número de linhas afetadas

Parâmetros e Segurança

4.1 Evitando SQL Injection

Sempre use parâmetros:

var cliente = connection.Query<Cliente>(
    "SELECT * FROM Clientes WHERE Email = @Email",
    new { Email = email }
);

Nunca faça isso:

// ERRADO
$"SELECT * FROM Clientes WHERE Email = '{email}'"

4.2 Parâmetros Dinâmicos

var parameters = new DynamicParameters();
parameters.Add("Id", 1);

var cliente = connection.Query<Cliente>(
    "SELECT * FROM Clientes WHERE Id = @Id",
    parameters
);

Mapeamento Avançado

5.1 Multi-mapping (JOIN)

var sql = @"
SELECT c.*, p.*
FROM Clientes c
INNER JOIN Pedidos p ON c.Id = p.ClienteId
";

var result = connection.Query<Cliente, Pedido, Cliente>(
    sql,
    (cliente, pedido) =>
    {
        cliente.Pedidos.Add(pedido);
        return cliente;
    }
);

5.2 Query Multiple

Executa múltiplas queries em uma chamada:

using var multi = connection.QueryMultiple(@"
    SELECT * FROM Clientes;
    SELECT * FROM Pedidos;
");

var clientes = multi.Read<Cliente>();
var pedidos = multi.Read<Pedido>();

Transações

using var connection = new SqlConnection(connectionString);
connection.Open();

using var transaction = connection.BeginTransaction();

try
{
    connection.Execute(sql1, param1, transaction);
    connection.Execute(sql2, param2, transaction);

    transaction.Commit();
}
catch
{
    transaction.Rollback();
    throw;
}

Essencial para:

ETL
Processamento em lote
Consistência de dados

Performance

7.1 Por que o Dapper é rápido?

Usa IL emit (geração dinâmica de código)
Não faz tracking de entidades
Não possui abstrações pesadas
Trabalha direto sobre ADO.NET

7.2 Boas práticas de performance

Reutilize conexões (connection pooling já ajuda)
Use QueryBuffered: false para grandes volumes:

var data = connection.Query<Cliente>(
    sql,
    buffered: false
);

Evite SELECT *
Use índices no banco
Prefira queries específicas

Uso em ETL

Dapper é excelente para ETL por:

Baixo overhead
Controle total do fluxo
Alta velocidade em leitura/escrita

Exemplo simplificado ETL:

var dados = connectionOrigem.Query<Cliente>("SELECT * FROM Clientes");

foreach (var cliente in dados)
{
    connectionDestino.Execute(
        "INSERT INTO Clientes (Id, Nome) VALUES (@Id, @Nome)",
        cliente
    );
}

Otimização recomendada:

Processamento em lote
Uso de transações
Bulk insert quando possível

Comparação Técnica

Característica	Dapper	ADO.NET	Entity Framework
Performance	Alta	Muito Alta	Média
Controle SQL	Total	Total	Parcial
Facilidade	Média	Baixa	Alta
Tracking	Não	Não	Sim
Overhead	Baixo	Muito baixo	Alto

Boas Práticas

Sempre use parâmetros
Evite lógica no banco desnecessária
Separe queries por responsabilidade
Use DTOs específicos
Não misture Dapper com lógica de domínio diretamente
Centralize acesso a dados (Repository ou similar)

Armadilhas Comuns

Esquecer de abrir conexão
Não tratar múltiplos resultados corretamente
Uso incorreto de QuerySingle
Falta de transação em operações críticas
Carregar grandes volumes em memória sem controle

DataAccess: ADO.net

Bruno Freschi — Fri, 10 Apr 2026 11:31:20 +0000

Controle total e performance máxima

Se você usa .NET, precisa entender o ADO.NET. Ele é a base de tudo — inclusive do Dapper e do Entity Framework.

O que é?

ADO.NET é o conjunto de APIs nativas do .NET para acessar banco de dados diretamente. Sem abstrações pesadas. Sem mágica.

👉 Resultado: máxima performance e controle absoluto.

Quando faz sentido usar?

Use ADO.NET quando:

Performance é crítica (ETL, alto volume, baixa latência)
Você precisa de controle fino sobre SQL e transações
Quer evitar dependências externas

Evite quando:

Precisa de produtividade rápida (CRUDs simples)
Não quer escrever mapeamento manual

Como funciona (essencial)

Os 3 principais componentes:

SqlConnection → abre conexão
SqlCommand → executa SQL
SqlDataReader → lê dados (streaming, rápido)

Exemplo direto:

using var connection = new SqlConnection(connectionString);
var command = new SqlCommand("SELECT Id, Nome FROM Clientes", connection);

connection.Open();

using var reader = command.ExecuteReader();
while (reader.Read())
{
    var id = reader.GetInt32(0);
    var nome = reader.GetString(1);
}

Sem ORM. Sem mapeamento automático. Só você e o banco.

Segurança básica (obrigatório)

Nunca faça isso:

$"SELECT * FROM Clientes WHERE Email = '{email}'"

Use parâmetros:

command.Parameters.AddWithValue("@Email", email);

👉 Evita SQL Injection e melhora cache de execução.

Performance: por que é tão rápido?

Sem reflexão
Sem geração de SQL
Leitura em streaming (DataReader)
Controle total de conexões

ETL? Aqui ele brilha

Para cargas massivas no SQL Server:

using var bulkCopy = new SqlBulkCopy(connection);
bulkCopy.DestinationTableName = "Clientes";
bulkCopy.WriteToServer(reader);

👉 Ordens de magnitude mais rápido que INSERT em loop

Comparação rápida

	ADO.NET	Dapper	EF
Performance	🔥 Máxima	Alta	Média
Controle SQL	Total	Total	Parcial
Facilidade	Baixa	Média	Alta

Regra prática

Quer controle e performance → ADO.NET
Quer equilíbrio → Dapper
Quer produtividade → EF

Insight final

Dominar ADO.NET muda seu nível como backend .NET.

Você passa a entender o que realmente acontece entre sua aplicação e o banco.

E isso impacta diretamente em performance, custo e escalabilidade.

Link para o repo.

BrunoSFreschi / DataAccess.Benchmark

DataAccess Benchmark é um laboratório de engenharia de software criado para analisar, o custo das diferentes abordagens de acesso a dados no ecossistema .NET.

DataAccess Benchmark

Ao estudar performance, não estamos apenas medindo tempo de execução Estamos observando a história da engenharia de software se manifestando em código.

Este repositório foi criado para demonstrar, de forma prática, a evolução das abordagens de acesso a dados no ecossistema .NET, comparando:

ADO.NET (baixo nível, controle total)
Dapper (micro-ORM, performance com praticidade)
Entity Framework Core (ORM completo, foco em produtividade)

Tudo medido com precisão usando BenchmarkDotNet, a ferramenta padrão para benchmarks profissionais em .NET.

Este projeto não é apenas um teste Ele é um laboratório para entender como a engenharia de software evoluiu ao longo dos anos.

A História do Acesso a Dados no .NET

Assim como a POO surgiu da Crise do Software, as diferentes formas de acessar banco de dados surgiram de um problema recorrente:

Como acessar dados com segurança, performance e manutenibilidade ao mesmo tempo?

Durante a evolução do .NET, três…

View on GitHub

Por que eu começo 10 projetos e não termino nenhum?

Yuri Souza — Sun, 05 Apr 2026 23:48:52 +0000

Você já passou uma tarde inteira configurando um projeto novo, escolhendo a stack, criando o repositório, estruturando as pastas e sentiu que estava voando? Aquela sensação de que dessa vez vai ser diferente, que essa ideia é boa demais pra morrer na gaveta? Eu também. O problema é que dois dias depois eu estava fazendo exatamente a mesma coisa, só que com outra ideia.

Se você se identificou, esse artigo é pra você. Não porque eu tenho a solução mágica, mas porque finalmente entendi o mecanismo por trás disso. E entender já muda muita coisa.

O prazer de começar
O momento em que tudo desmorona
O objeto brilhante
A culpa que ninguém fala
Não é preguiça. É neurologia.
Conclusão

O prazer de começar

Tem algo muito específico que acontece quando você começa um projeto novo.

O problema ainda não existe de verdade. Tudo é possibilidade. Você ainda não encontrou o bug impossível de reproduzir, ainda não percebeu que a arquitetura que escolheu não escala, ainda não chegou na parte chata de fazer o CRUD de usuário pela décima vez na vida.

Nessa fase, o cérebro libera dopamina. Bastante. A antecipação de uma recompensa futura ativa os mesmos circuitos que uma conquista real. Ou seja: só de imaginar o projeto funcionando, você já sente parte da recompensa.

Isso explica o prazer visceral do setup. Escolher o nome do repositório, montar a estrutura de pastas, escrever o README antes de ter uma linha de código que funciona... tudo isso alimenta aquela sensação.

O problema? É que ela passa.

O momento em que tudo desmorona

Existe um ponto específico em todo projeto onde a magia some. Eu chamo de o vale do tédio.

É quando você já sabe o que precisa fazer, mas o trabalho deixou de ser estimulante. As decisões arquiteturais foram tomadas. O setup tá pronto. Agora é só... executar. Implementar a feature chata. Escrever o teste. Lidar com o caso que você não previu.

Para a maioria das pessoas, esse momento é desconfortável mas passável. Você empurra, entrega, segue.

Para alguns cérebros, incluindo o meu, esse momento é quase fisicamente doloroso. Não é falta de vontade. É que o sistema de recompensa do cérebro simplesmente não libera o combustível necessário pra continuar uma tarefa que deixou de ser nova.

E aí começa o ciclo de autos sabotagem mais clássico do mundo do dev:

"Antes de continuar, vou refatorar essa parte aqui."

"Preciso repensar a arquitetura antes de avançar."

"Deixa eu criar um boilerplate melhor pra usar nos próximos projetos."

Você não está sendo preguiçoso. Você está inconscientemente procurando a dopamina do recomeço dentro do próprio projeto.

O objeto brilhante

E então aparece. Uma ideia nova.

Pode ser um problema que você viu no trabalho, uma conversa no Twitter, um repositório no GitHub que te inspirou. De repente, aquela ideia nova parece muito mais interessante do que o projeto que você abandonou no vale do tédio.

E ela realmente é, pelo mesmo motivo que o projeto anterior era interessante no início. Ela ainda não tem o peso da implementação. Ainda não tem os bugs, as decisões difíceis, o trabalho repetitivo.

Esse fenômeno tem um nome informal: Síndrome do Objeto Brilhante. E ele é mais intenso em cérebros que têm dificuldade de regular dopamina naturalmente.

O que acontece na prática? O projeto antigo não morre oficialmente. Ele só vai pra uma pasta chamada projetos/ e fica lá, acumulando poeira junto com outros oito projetos que passaram pelo mesmo ciclo.

A culpa que ninguém fala

Aqui está a parte que eu não via ninguém discutir: a culpa.

Porque quando você abandona um projeto, você não apenas perde o projeto. Você coleciona evidência contra si mesmo.

"Eu nunca termino nada."
"Eu começo cheio de energia e nunca entrego."
"Por que eu deveria começar esse projeto se vou abandonar igual aos outros?"

E essa narrativa é perigosa por dois motivos.

Primeiro, porque ela não é completamente verdadeira. Você provavelmente termina muita coisa, no trabalho, em tarefas com prazo real, em situações onde tem alguém esperando. O problema não é terminar em si. É terminar coisas que dependem 100% da sua motivação interna, sem deadline, sem stakeholder, sem pressão externa.

Segundo, você começa a acreditar que não é capaz de terminar, então para de tentar de verdade, e aí realmente não termina. O ciclo se fecha.

Não é preguiça. É neurologia.

Vou ser direto: se você se reconheceu em tudo que eu escrevi acima, há uma chance real de que seu cérebro simplesmente funciona de um jeito diferente da média.

Tem um tipo de cérebro que odeia repetição mas ama coisa nova. Não é fraqueza, é como ele funciona. O problema é que todo projeto tem uma fase nova e uma fase chata — e esse cérebro simplesmente apaga na segunda.

Não é falta de disciplina. É que o combustível que o seu cérebro usa pra manter o foco não funciona igual ao de todo mundo.

A diferença entre entender isso e não entender é enorme. Quando você não entende, você passa anos se achando preguiçoso, incompetente, incapaz de terminar o que começa e quando entende você começa a fazer perguntas diferentes:

"Como eu estruturo esse projeto pra ter recompensas menores e mais frequentes?"

"Como eu crio pressão externa pra compensar a falta de pressão interna?"

"Qual é o menor projeto possível que ainda entrega valor?"

Não são perguntas fáceis de responder. Mas são as perguntas certas.

Conclusão

Eu ainda começo projetos demais. Provavelmente sempre vou começar. Mas aprendi a parar de tratar isso como um defeito de caráter e passei a tratar como uma característica que precisa de estratégia.

O problema nunca foi a quantidade de projetos que eu começo. Foi a narrativa que eu construí em volta dos que eu não terminei.

Se você chegou até aqui e se reconheceu em alguma parte desse texto: você não está sozinho. E você provavelmente é melhor em começar coisas do que 90% das pessoas. Isso não é pouco, é uma habilidade real, que só precisa de direção.

O próximo projeto vai começar. A questão é o que você vai fazer diferente dessa vez.

Escrito por alguém que tem pelo menos dez pastas projetos/ abertas no VS Code agora mesmo.

O que uma usina nuclear tem a ver com o seu processo de QA?

Alicia Marianne Gonçalves — Sun, 05 Apr 2026 12:02:52 +0000

A gente sabe que testar e validar um software antes de ir para produção é importante. Mas você já parou para pensar no peso real que isso carrega?

Recentemente, estava revendo a série Chernobyl, e ela me fez refletir sobre muita coisa — especialmente sobre a forma como encaro minha área, sendo QA, e sobre a responsabilidade que ela traz. Resolvi compartilhar isso com vocês.

Para quem não conhece, Chernobyl é uma minissérie dramática lançada em 2019 que retrata o desastre nuclear ocorrido na usina de mesmo nome, na então União Soviética, em 26 de abril de 1986. A história acompanha os eventos logo após a explosão do reator número 4 — o caos, as tentativas do governo soviético de esconder a gravidade do acidente e o enorme esforço de cientistas, bombeiros, militares e trabalhadores que arriscaram, e muitas vezes perderam, suas vidas para evitar uma catástrofe ainda maior. A série também segue o cientista Valery Legasov, que tenta descobrir a verdadeira causa do acidente e expor a verdade por trás da tragédia.

Mas o ponto aqui vai além da série.

O que mais me chamou atenção foi o quanto aquela tragédia conversa com algo que vivemos diariamente no desenvolvimento de software: a responsabilidade nas decisões.

O que aconteceu em Chernobyl?

Mesmo sabendo que existem elementos dramatizados, dá para aprender muita coisa com esse desastre. Não sou física nuclear, mas vou tentar resumir o que aconteceu — porque foi justamente essa parte que mais me fez refletir sobre responsabilidade e tomada de decisão.

Na madrugada do dia 26 de abril de 1986, os operadores da usina realizavam um teste de segurança no reator 4. O objetivo era validar se, em caso de queda de energia, as turbinas ainda conseguiriam gerar eletricidade por alguns segundos — tempo suficiente até que os geradores de emergência fossem acionados. No papel, o teste parecia simples.

O problema é que, para executá-lo, diversos sistemas de segurança foram desativados e a potência do reator foi reduzida para um nível muito abaixo do ideal. Foi aí que tudo começou a sair do controle.

O reator utilizado era do tipo RBMK, um modelo com uma falha crítica de projeto: em determinadas condições, quanto mais vapor era gerado dentro do sistema, maior ficava a potência do reator. Em vez de estabilizar, ele se tornava cada vez mais instável. Para piorar, o teste foi conduzido sob forte pressão da liderança, mesmo diante de sinais claros de que não era seguro continuar.

Ao longo da série, vemos os próprios operadores levantando preocupações — que foram ignoradas. Quando perceberam que a situação era crítica, acionaram o botão de desligamento de emergência. Em teoria, esse comando deveria encerrar a reação. Mas, por uma falha no design das barras de controle, o efeito inicial foi o oposto: a potência disparou. Em poucos segundos, temperatura e pressão subiram de forma descontrolada.

O resultado foram duas explosões que destruíram o topo do reator, expuseram o núcleo à atmosfera e liberaram uma enorme quantidade de material radioativo. O incêndio que se seguiu espalhou radiação por boa parte da Europa, transformando Chernobyl no maior desastre nuclear da história.

O que mais me impactou foi perceber que a tragédia não aconteceu por um único erro. Ela foi consequência de uma cadeia de decisões ruins: falhas técnicas ignoradas, riscos mal avaliados e pessoas que não foram ouvidas.

E o que isso tem a ver com software?

Depois de assistir à série, comecei a fazer um paralelo com a nossa área. Porque, no fim, quantas vezes um incidente em produção também não nasce da mesma forma?

Nem sempre o problema vem de um único bug. Muitas vezes, ele é o resultado de uma sequência de decisões tomadas sem o devido cuidado: um requisito mal definido, um risco não mapeado, uma validação superficial, uma entrega apressada — ou um alerta levantado pelo time que acabou sendo ignorado.

Foi aí que a série me fez enxergar algo que vai além do contexto dela: quando a pressa fala mais alto do que a análise, o custo quase sempre aparece depois.

O maior problema: risco tratado de forma rasa

Um dos maiores desafios que vejo hoje no desenvolvimento de software é justamente o planejamento e o levantamento de riscos feitos de maneira superficial.

Tenho certeza de que você vai concordar: não tem coisa pior do que refazer algo ou ficar apagando incêndios que poderiam ter sido discutidos antes.

Vivemos num mundo onde tempo é dinheiro. E é exatamente por isso que qualidade precisa estar presente desde o início — não como uma etapa final, mas como parte do processo.

Como QA, vou compartilhar duas coisas que considero essenciais.

Ouça sua equipe

Independentemente da sua posição no time, ouça as pessoas ao seu redor.

Ninguém conhece melhor o produto do que quem o construiu, testou e convive com ele diariamente. Antes de uma nova funcionalidade entrar ou de um teste ser executado, converse com o time.

Escute quem desenvolveu. Escute o produto. Escute suporte. Escute quem está mais próximo do usuário.

Muitas vezes, o risco já foi identificado por alguém. Ele só não foi ouvido.

Analise antes de agir

Entender o impacto de uma mudança não é só uma questão técnica — é também uma questão de negócio.

Por exemplo: você vai melhorar a query de uma API. Em teoria, isso pode não alterar nenhuma regra de negócio. Mas como isso afeta o usuário final? A performance realmente melhorou? Existe algum impacto colateral? Como vamos medir se essa mudança foi positiva ou negativa?

Nem toda melhoria técnica gera melhoria de produto. E esse olhar crítico é parte fundamental do papel de QA.

Conclusão

No fim, Chernobyl me fez refletir sobre algo que vai muito além de uma série: a responsabilidade por trás de cada decisão que tomamos no dia a dia.

A gente não está lidando com um reator nuclear. Mas ainda assim lida com impacto real — no usuário, no negócio e no próprio time. Um risco ignorado, um teste mal planejado ou uma decisão tomada sem ouvir a equipe podem não gerar uma catástrofe, mas certamente geram problemas que poderiam ter sido evitados com mais atenção, diálogo e análise.

Para mim, ser QA vai muito além de encontrar bugs.

É questionar antes que o problema aconteça. É analisar cenários com olhar crítico. É antecipar riscos. É provocar conversas importantes dentro do time. É ajudar a construir decisões mais seguras e conscientes.

No final, qualidade não é apenas sobre software funcionando.

É sobre responsabilidade, colaboração e cuidado com tudo aquilo que criamos.

De front-end para UX, e de volta ao código: o que significa ser Design Engineer em 2026

vitoriazzp — Fri, 03 Apr 2026 13:00:00 +0000

Sou UX/UI designer, mas antes disso fui front-end.

Atuei cerca de 5 anos trabalhando com HTML e CSS, transformando layouts em páginas, entendendo hierarquia de informação e estrutura de interface. Depois, tomei o caminho oposto: migrei para UX/UI e agora completo 5 anos atuando em produtos, passando por fintech, utilities e atuando como Product Designer.

Essa trajetória, de front para UX e agora voltando a se aproximar do código, é justamente o que me levou a me reconhecer em um termo que gosto bastante: Design Engineer.

Minha trajetória: 5 anos de front-end, 5 anos de UX

Quando era front-end, eu via a tela como um resultado de código: HTML estruturando a informação, CSS dando forma e layout, um pouco de JavaScript dando comportamento.

Quando migrei para UX, passei a olhar mais para o todo do produto: pesquisa, fluxos, contexto do usuário, design systems, governança, revisão de interfaces, conversa com times de produto e de negócios.
Hoje, percebo que essas duas visões não são opostas. Elas se completam.

O que é design engineer em 2026?

Se você pesquisar sobre "Design Engineer", vai encontrar muitas definições técnicas, mas na prática o que mais faz sentido para mim é:

A pessoa que entende UX, código e um pouco de backend ao mesmo tempo, e usa isso para desenhar interfaces que são pensadas desde o primeiro pixel até a última chamada de API.

Não é só "quem desenha + quem programa"
É quem pensa em experiência e implementação juntas:

Um botão que não só parece bem-desenhado, mas também considera estados de loading, erro, disabled.
Um fluxo de cadastro que não só é bonito, mas que já prevê o que o backend vai precisar para validar, salvar e devolver feedback.
Um produto que pensa em performance, acessibilidade e usabilidade em uma única conversa.

Como front-end e UX mudam sua forma de ver produto

Como eu via a tela como desenvolvedor front-end
HTML estruturando a informação. CSS dando forma. Um pouco de JavaScript dando comportamento. A tela era resultado direto do código.

O que mudou quando migrei para UX/UI
Passei a olhar para o produto como um todo: pesquisa, fluxos, contexto do usuário. O código virou uma consequência, não o ponto de partida.

O que muda agora é que percebo que não preciso mais ficar só de um lado

Por que estou voltando ao código agora

Com o avanço de ferramentas como IA integrada ao Figma, prototipagem cada vez mais próxima do código e experiências acumuladas como Product Designer, foi aí que o conceito de Design Engineer passou a fazer sentido de verdade pra mim.

JavaScript moderno, React e um pouco de backend
Comecei a estudar de forma mais focada para:

Atualizar meu JavaScript (ES2024, async/await, fetch, arrays/objetos)
Reativar React (componentes, hooks, estado compartilhado)
Entender backend leve (Node/Express, rotas simples, persistência básica)
Pensar em performance e otimização das interfaces que ajudo a construir

Como estou usando IA no processo de aprendizado

Hoje, uso o Claude AI não como substituto, mas como apoio para:

Quebrar problemas de código em etapas menores
Revisar fluxos de dados entre front e backend
Organizar pensamentos e lógica de features

Design Engineer não é um cargo. É uma forma de pensar

O que mais gosto de dizer é que, em 2026, Design Engineer não é só um título de empresa grande ou de time específico. Pode existir em qualquer lugar onde UX e código se encontram:

Em um produto próprio
Em um projeto freelancer
Em um repositório público
Em um fluxo de trabalho híbrido, mesmo sem ter um cargo oficial com esse nome

O que importa é a maneira de pensar: UX + código ao mesmo tempo. Protótipos e implementação como parte do mesmo processo. Interfaces que consideram o que o usuário sente e o que o backend precisa.

O que vem por aí: UX data-driven e componentes React

Esse movimento não é só "voltar" ao front-end. É re-aprender JavaScript, entender melhor React e backend, e levar essa visão de UX para dentro do código.
Em breve, quero escrever mais sobre:

Como transformo um fluxo de UX do Figma em componentes React
Como penso em performance e carregamento em UX para web
Como organizar estudos de UX + código em ciclos curtos e práticos

E numa parte que ainda não me sinto confortável, mas sei que é essencial: vou falar sobre como estou começando a me tornar uma UX mais data-driven, porque ser Design Engineer em 2026 também é aprender a ouvir o que os números dizem sobre o UX que eu desenho.

Você também está nesse meio-termo entre UX e código?

Se você chegou até aqui, é bem provável que também se sinta em algum meio-termo entre UX e código.

Que tal comentar:

Como você se vê hoje entre design e desenvolvimento?
Você já tentou voltar pro código depois de virar UX, ou está no caminho invertido?

Esse é o tipo de conversa que me ajuda a entender como o conceito de Design Engineer está se moldando, bem além de títulos de empresa.

Construí um gerador de playlists no Spotify com Claude

Leo Garcez — Tue, 24 Mar 2026 02:01:08 +0000

Eu queria digitar “noite chuvosa, meio melancólica” e receber uma playlist perfeita. Então eu construí isso.

TL;DR

Eu construí um gerador de playlists com IA usando Claude + Spotify API
Você descreve um humor → ele gera 50 músicas → salva direto no Spotify
O maior problema foi OAuth local com NextAuth (sim, foi um inferno)
Claude funciona bem, mas precisa de bastante controle pra não inventar músicas
Streaming com SSE melhorou muito a UX

Links:

Índice

A Ideia
A Stack
O Problema de Trabalhar com OAuth Localmente
Endpoints Deprecated do Spotify
Spotify em Produção
Fazendo o Claude Obedecer
Prompt Engineering Anti-Alucinação
Modo Related Artists
Construindo o Perfil Musical
Streaming com SSE
O Que Aprendi

A Ideia

Fazer um gerador de playlists que realmente entendesse vibes, não só tags de gênero. Algo tipo: você digita "tarde fria num apartamento vazio" e recebe uma playlist boa de verdade, já salva no seu Spotify.

O conceito:

Usuário descreve um humor
Claude retorna 50 músicas em JSON
App busca cada faixa no Spotify
Cria e salva a playlist na conta do usuário

Três APIs, um app.

A Stack

Next.js 14 (App Router)
NextAuth v5 beta
Anthropic Claude API (claude-sonnet-4-6)
Spotify Web API
Supabase (PostgreSQL)
TypeScript + Tailwind CSS + Framer Motion

Escolhi o Claude porque ele tá bem em alta agora e, na prática, é confiável, alucina menos do que eu esperava pra esse tipo de tarefa. Ele é um pouco menos criativo que o GPT nas recomendações, mas compensa sendo mais previsível no formato das respostas, o que importa bastante quando você tá parseando JSON.

O Problema de Trabalhar com OAuth Localmente

Isso me custou algumas horas e sessões de debug. Vou detalhar porque tem várias camadas de problema e você provavelmente vai bater na mesma parede se estiver usando NextAuth v5 com Spotify.

O Spotify não aceita `localhost`

O Spotify proíbe localhost como redirect URI pra URIs de loopback. A solução é usar 127.0.0.1. Cadastrei http://127.0.0.1:3000/api/auth/callback/spotify no dashboard e setei AUTH_URL=http://127.0.0.1:3000 no .env.local.

Não foi suficiente.

O `NextRequest` normaliza URLs pra `localhost`

O Next.js, independente do host que você passa pra next dev -H, normaliza req.url e req.nextUrl.href de volta pra localhost em desenvolvimento. Isso não é bug documentado — é comportamento interno do framework.

O NextAuth v5 tem um utilitário chamado reqWithEnvURL que tenta corrigir exatamente isso, mas falha silenciosamente:

// Dentro do next-auth — simplificado
function reqWithEnvURL(req: NextRequest): NextRequest {
  const url = process.env.AUTH_URL ?? req.url;
  return new NextRequest(url, req); // ← o construtor normaliza de volta pra localhost
}

Mesmo passando 127.0.0.1 explicitamente, o construtor do NextRequest sobrescreve. A "correção" não funciona.

Dois momentos onde o redirect URI importa

O OAuth tem dois momentos distintos onde o redirect URI aparece:

Requisição de autorização — a URL do Spotify onde o usuário loga. O redirect_uri aqui vem dos seus params de configuração, então você pode hardcodar 127.0.0.1 na config do provider. Isso funcionou.
Troca de token — quando o Spotify manda o código de volta, o @auth/core envia um POST pra trocar o código por tokens. O redirect_uri nessa requisição vem de provider.callbackUrl, que é derivado de params.url.origin — ou seja, da URL da requisição de callback. Se essa URL ainda diz localhost, a troca falha com invalid_grant: Invalid redirect URI.

O sintoma era desconcertante: a URL de autorização mostrava 127.0.0.1 corretamente, mas a troca de token continuava falhando. Fui atrás do código do @auth/core pra entender o que tava acontecendo.

A solução: `Auth()` direto com `Request` nativo

Objetos Request nativos do browser/Node não normalizam URLs. A correção é contornar os route handlers do NextAuth e chamar Auth() do @auth/core diretamente, passando um Request nativo com a URL já corrigida:

// src/app/api/auth/[...nextauth]/route.ts
import { Auth } from "@auth/core";
import { authConfig } from "../../../../../auth";
import { NextRequest } from "next/server";

function buildRequest(req: NextRequest): Request {
  const authOrigin = process.env.AUTH_URL ?? `http://${req.headers.get("host")}`;
  const fixedUrl = req.url.replace(/^https?:\/\/[^/]+/, authOrigin);

  const hasBody = req.method !== "GET" && req.method !== "HEAD";
  return new Request(fixedUrl, {
    method: req.method,
    headers: req.headers,
    body: hasBody ? req.body : undefined,
    // duplex necessário para streaming de body no Node.js
    ...(hasBody && ({ duplex: "half" } as object)),
  });
}

const handler = (req: NextRequest) =>
  Auth(buildRequest(req), authConfig as Parameters<typeof Auth>[1]);

export { handler as GET, handler as POST };

Versão do @auth/core: ao usar Auth() diretamente, instale a versão exata que o next-auth usa internamente:

npm ls @auth/core  # veja qual versão o next-auth requer
npm install @auth/core@0.41.0 --save-exact

Versões diferentes criam conflitos de tipo que explodem em runtime.

Configuração explícita no auth.ts: ao contornar os handlers do NextAuth, setEnvDefaults não roda mais. Configure basePath, secret e redirect_uri explicitamente:

// auth.ts
export const authConfig: NextAuthConfig = {
  trustHost: true,
  basePath: "/api/auth",
  secret: process.env.AUTH_SECRET,
  providers: [
    Spotify({
      clientId: process.env.AUTH_SPOTIFY_ID,
      clientSecret: process.env.AUTH_SPOTIFY_SECRET,
      authorization: {
        url: "https://accounts.spotify.com/authorize",
        params: {
          scope: SPOTIFY_SCOPES,
          show_dialog: true,
          redirect_uri: `${process.env.AUTH_URL}/api/auth/callback/spotify`,
        },
      },
    }),
  ],
  // ... callbacks e pages como antes
};

Bônus: problema de domínio do cookie PKCE

Mesmo com tudo acima, pode acontecer mais uma falha: se o usuário acessa http://localhost:3000, o navegador seta o cookie PKCE pro domínio localhost. Quando o Spotify redireciona de volta pra http://127.0.0.1:3000/..., o navegador não envia o cookie — domínios diferentes — e o code_verifier some. A troca falha de novo.

A correção é garantir que localhost:3000 nunca apareça pro usuário, redirecionando via next.config.mjs:

async redirects() {
  return [
    {
      source: "/:path*",
      has: [{ type: "host", value: "localhost:3000" }],
      destination: "http://127.0.0.1:3000/:path*",
      permanent: false,
    },
    {
      source: "/",
      has: [{ type: "host", value: "localhost:3000" }],
      destination: "http://127.0.0.1:3000/",
      permanent: false,
    },
  ];
},

Com isso, todo o fluxo de auth fica em 127.0.0.1 e os cookies PKCE chegam onde precisam chegar.

Endpoints Deprecated do Spotify

Com o auth funcionando, bati num muro de 403s.

O Spotify deprecated alguns endpoints sem muito alarde:

Antigo (deprecated)	Novo
`POST /playlists/{id}/tracks`	`POST /playlists/{id}/items`
`GET /playlists/{id}/tracks`	`GET /playlists/{id}/items`
`GET /audio-features`, `GET /recommendations`	Deprecated, sem substituto

A migração /tracks → /items está documentada, mas é fácil de perder se você seguiu um tutorial de 2022. Audio features e recomendações sumindo foi mais chato — tive que construir contexto de energia de outra forma, mais sobre isso abaixo.

Spotify em Produção

Tem uma limitação que eu não vi muito discutida: no modo de desenvolvimento, o Spotify permite apenas 5 usuários autenticados E eles precisam ser adicionados manualmente via allowlist no dashboard.

Pra ir além disso, você precisa solicitar Extended Quota Mode. E o processo atual é bem pesado:

Entidade jurídica registrada (pessoa física não é aceita desde maio de 2025)
Serviço já lançado e ativo
Mínimo de 250.000 usuários ativos mensais
Viabilidade comercial

A análise pode levar até seis semanas, e sem garantia de aprovação.

Na prática, isso significa que se você tá construindo algo novo como indie dev, vai ficar travado em modo de desenvolvimento. Você consegue testar e mostrar pra até 4 pessoas além de você — e só. Vale saber disso antes de planejar algum lançamento público.

Fazendo o Claude Obedecer

O system prompt instrui o Claude a retornar apenas um array JSON, sem markdown, sem explicações. Essa parte é direta. O problema mais difícil é conseguir 50 faixas que realmente existam.

One-shot prompting

Incluir uma conversa de exemplo completa (usuário + assistente) antes do request real reduziu bastante os erros de formato, especialmente com artistas não-ingleses:

messages: [
  {
    role: "user",
    content: "Create a playlist for this mood/vibe: late night drive, nostalgic",
  },
  {
    role: "assistant",
    content: JSON.stringify([
      { title: "Drive", artist: "The Cars", reason: "Synth-pop clássico com energia perfeita de madrugada" },
      { title: "Running Up That Hill", artist: "Kate Bush", reason: "Art-pop etéreo, emocionalmente assombroso" },
      // ...
    ]),
  },
  { role: "user", content: actualUserMessage },
],

Extração de JSON como fallback

Mesmo com prompting cuidadoso, modelos eventualmente jogam texto de introdução. Sempre extraia o array:

const match = raw.match(/\[[\s\S]*\]/);
if (!match) throw new Error("Nenhum array JSON encontrado");
const suggestions = JSON.parse(match[0]);

Prompt Engineering Anti-Alucinação

Descobri que quanto mais músicas você pede, mais o modelo inventa títulos.

Pedindo 70 músicas, o Claude começa a criar faixas com nomes plausíveis que não existem. Com 50 e restrições explícitas, fica bem melhor.

O que adicionei ao system prompt:

EXISTÊNCIA NO SPOTIFY — CRÍTICO:
Cada música DEVE existir no Spotify. Antes de incluir uma faixa, pergunte:
"Tenho certeza que esta música existe no Spotify com este título e artista exatos?"
Se houver qualquer dúvida, escolha outra música que você tem certeza.

REGRAS DE FORMATO DO TÍTULO:
- Use apenas o título canônico limpo do lançamento
- SEM sufixos: sem "- Remastered", "- Live at...", "- Radio Edit"
- Use o nome do lançamento mais conhecido, não compilações

ARMADILHAS COMUNS DE ALUCINAÇÃO:
- Não invente títulos de músicas que parecem plausíveis mas podem não existir
- Não confunda dois artistas com nomes similares
- Não sugira deep cuts que você não tem certeza

Também removi a abordagem de duas etapas "gerar 70, refinar pra 50". Era cara em tempo e custo, e uma única geração de 50 com boas instruções performa melhor.

O system prompt atual completo

Esse é o prompt que tá rodando em produção hoje:

You are a world-class Spotify playlist curator.

GOAL:
Generate EXACTLY 50 high-quality songs for a playlist.

OUTPUT:
Return ONLY a raw JSON array. No markdown, no explanations.

Each item:
- "title": string — the canonical Spotify title, nothing else
- "artist": string — the primary artist exactly as listed on Spotify
- "reason": string — max 10 words

SPOTIFY EXISTENCE — CRITICAL:
Every song MUST exist on Spotify. Before including a track, ask yourself:
"Am I certain this song exists on Spotify under this exact title and artist?"
If there is any doubt, pick a different song you are certain about.

TITLE FORMAT RULES:
- Use the clean, canonical release title only
- NO suffixes: no "- Remastered", "- Live at...", "- Radio Edit", "- feat. X"
- NO parentheticals unless part of the official title
- Use the most well-known release name, not compilations or bonus versions

COMMON HALLUCINATION TRAPS TO AVOID:
- Do not invent song titles that sound plausible but may not exist
- Do not confuse two artists with similar names
- Do not suggest deep cuts you are uncertain about
- Do not suggest songs only released in specific regions unavailable globally

DISTRIBUTION:
- 50% recognizable hits (high confidence they exist)
- 40% lesser-known but confirmed tracks
- 10% deep cuts you are fully certain about

DIVERSITY:
- At least 2 genres
- At least 3 decades
- Non-English tracks welcome if you are certain they are on Spotify

CURATION:
- Cohesive flow, playlist-worthy, non-random
- No duplicates

Return ONLY the JSON array. Exactly 50 items.

Curiosidade: o prompt tá em inglês mesmo que o usuário escreva em português. O Claude entende o humor no idioma que vier e retorna os dados no formato esperado sem problema.

Melhor resolução de busca no Spotify

Mesmo com um bom prompt, algumas faixas voltam com títulos ou artistas levemente errados. Três ajustes no lado da busca:

1. Buscar 10 candidatos em vez de 1
Em vez de limit=1, buscar limit=10 e escolher o melhor match.

2. Filtro de popularidade
Pular resultados com popularity < 30 — evita gravar versões ao vivo obscuras quando a faixa correta não é encontrada:

const POPULARITY_FLOOR = 30;
const aboveFloor = candidates.filter(t => t.popularity >= POPULARITY_FLOOR);
const pool = aboveFloor.length > 0 ? aboveFloor : candidates;

3. Fuzzy matching + seleção por popularidade
Normalizar strings e verificar correspondência bidirecional de substring, depois escolher o match com maior popularidade:

function fuzzyMatch(candidate: SpotifyTrack, suggestion: ClaudeTrackSuggestion): boolean {
  const trackName = normalizeStr(candidate.name);
  const artistName = normalizeStr(candidate.artists[0]?.name ?? "");
  const sugTitle = normalizeStr(suggestion.title);
  const sugArtist = normalizeStr(suggestion.artist);
  const titleMatch = trackName.includes(sugTitle) || sugTitle.includes(trackName);
  const artistMatch = artistName.includes(sugArtist) || sugArtist.includes(artistName);
  return titleMatch && artistMatch;
}

Modo Related Artists

Playlists geradas por IA alucinam mais quando o humor é específico de artista — tipo "algo como Radiohead". Nesses casos, o grafo de artistas do próprio Spotify é mais confiável que o Claude.

Adicionei detecção automática: uma chamada rápida ao Claude Haiku (~0,5s) classifica o prompt antes da geração principal:

// Retorna { mode: "ai" | "related", artists: ["Radiohead", "Nick Cave"] }
const detected = await detectPlaylistMode(mood);

Se artistas são detectados, o app:

Os resolve no Spotify
Busca artistas relacionados (GET /artists/{id}/related-artists)
Pega top tracks de cada artista relacionado
Monta uma playlist com dados reais do Spotify, sem depender do Claude pra nada

Se não detectar artistas, cai pro fluxo normal com Claude.

if (detected.mode === "related" && detected.artists.length > 0) {
  const { suggestions, resolvedSeeds } = await buildRelatedArtistsPlaylist(
    detected.artists,
    accessToken,
    energy
  );
  if (suggestions.length > 0) {
    return NextResponse.json({ suggestions, mode: "related", seedArtists: resolvedSeeds });
  }
  // fallthrough para modo AI se não encontrou nada
}

Construindo o Perfil Musical

O app deixa usuários escolher uma playlist de referência ou seus top artistas do Spotify (último mês / 6 meses / histórico completo). Esse contexto é passado pro Claude como uma impressão digital musical.

Mandar nomes de faixas brutos confunde o modelo. Em vez disso, agregue num perfil:

// Contar frequência de artistas em todas as faixas da playlist
const artistFreq = new Map<string, { name: string; count: number }>();
for (const track of tracks) {
  const a = track.artists[0];
  const prev = artistFreq.get(a.id);
  artistFreq.set(a.id, { name: a.name, count: (prev?.count ?? 0) + 1 });
}

Pra playlists, também busco dados de gênero dos artistas principais via GET /artists/{id} (5 chamadas paralelas), já que os itens de playlist não retornam gêneros nativamente.

Mesmo sem seleção de referência explícita, o app passa os top artistas e gêneros baseline do usuário como contexto suave pra cada geração.

A instrução no prompt mudou de "não recomende esses artistas" pra algo mais útil:

→ Biase as recomendações em direção a este DNA musical: tempo, humor e estilo de produção similar.
→ Descubra artistas com som SIMILAR — não necessariamente os mesmos artistas.
→ NÃO repita faixas já listadas acima.

Streaming com SSE

O fluxo original: buscar todas as 50 faixas em paralelo, retornar tudo de uma vez, mostrar um spinner.

O problema é que o usuário ficava olhando "Salvando no Spotify..." por 5-10 segundos sem nenhum feedback. Server-Sent Events resolve isso — cada faixa é emitida conforme resolve:

// Na rota da API
const stream = new ReadableStream({
  async start(controller) {
    const send = (data: object) =>
      controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}\n\n`));

    await Promise.all(
      suggestions.map(async (suggestion) => {
        const track = await searchTrack(suggestion, accessToken);
        if (track) {
          foundTracks.push({ track, suggestion });
          send({ type: "track", track, suggestion }); // emitido imediatamente
        }
      })
    );

    // Criar playlist depois que todas as buscas terminam
    const playlist = await createPlaylist(...);
    send({ type: "done", playlist, found: foundTracks.length });
    controller.close();
  },
});

return new Response(stream, {
  headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache" },
});

A busca paralela continua na velocidade máxima. Mas agora o cliente vê cada faixa aparecer com album art conforme resolve, com uma barra de progresso ao vivo — em vez de um spinner em branco por 10 segundos.

O Que Aprendi

Sobre prompt engineering:

Menos é mais (50 > 70)
Exemplos one-shot (par de mensagens usuário + assistente) são mais confiáveis que instruções de formato detalhadas.
Dizer o que não fazer funciona muito bem
Contexto de perfil funciona melhor como guia de DNA musical, não como lista de restrições.

Sobre a API do Spotify:

Sempre verifique se o endpoint ainda é atual. /tracks → /items, audio features sumiu, recomendações sumiram.
GET /artists/{id}/related-artists funciona bem pra descoberta e quase ninguém usa.
O score de popularidade nas faixas é um bom proxy pra "essa faixa existe como esperado."

Sobre streaming no Next.js:

ReadableStream + text/event-stream funciona limpo no App Router.
Promise.all + emit-on-resolve te dá paralelismo real com UI progressiva de graça.

Sobre Next.js + OAuth:

NextRequest normaliza URLs pra localhost em desenvolvimento, mesmo que você passe 127.0.0.1 explicitamente. Use Request nativo quando a URL importa.
O NextAuth v5 tem um utilitário reqWithEnvURL que tenta corrigir isso mas usa new NextRequest() internamente — que normaliza de novo. A correção do framework não funciona.
O OAuth tem dois momentos onde o redirect_uri é verificado: na requisição de autorização e na troca de token. Você precisa garantir que os dois mostrem 127.0.0.1.
provider.callbackUrl é derivado da URL da requisição de callback — não da sua config. Se a URL da requisição ainda diz localhost, a troca falha com invalid_grant.
Ao usar Auth() do @auth/core diretamente, pin a versão exata que o next-auth requer. Versões diferentes causam conflitos de tipo em runtime.
Cookies PKCE são scopados por domínio. Se o usuário começa em localhost e o callback chega em 127.0.0.1, o code_verifier some. Redirecione todo o tráfego de localhost pra 127.0.0.1 no next.config.mjs.
NextAuth v5 é poderoso mas a documentação beta é bem escassa. Ler o código-fonte do @auth/core foi necessário pra entender o que estava acontecendo.

Teste Você Mesmo

O app se chama Moodify. Está OpenSource no GitHub. Se você tá fazendo algo parecido, espero que ajude um pouco.

Como vocês melhorariam esse prompt? Se alguém já passou por algo parecido ou tiver ideias, comenta aí

Construído com Next.js, Claude API, Spotify Web API e Supabase. Deploy no Vercel.

Engenharia de Prompt: Por Que a Forma Como Você Pergunta Muda Tudo(Um guia introdutório)

Fran Borges — Mon, 23 Mar 2026 16:20:34 +0000

Neste artigo irei explicar alguns pontos importantes sobre Engenharia de prompt, e como saber esses pontos pode te ajudar muito no dia a dia lidando com IAs, no seus estudos, pesquisas, trabalho, vibeconding, whatever.

Prefácio
Antes de tudo, para lembrar, o que é uma LLM mesmo?
Fazendo Perguntas
- 1 - Evite a Ambiguidade
- 2 - Delimite o Escopo
- 3 - Forneça Contexto Relevante
Considerações Finais

Prefácio

A base do conhecimento é necessária em tudo que se quer aprender, com LLMs não é diferente. Analisando padrões, conversando com amigos, observei que a grande parte das pessoas que usam LLMs no dia a dia de trabalho, estudo, pessoas que trabalham com tecnologia e principalmente quem está começando na área tech, não tem ideia de como a LLM funciona e de como fazer as perguntas e tirar dúvidas de forma certa para um ChatGPT da vida.

Tendo isso em vista, e como venho estudando bastante sobre esse assunto, como forma de compartilhar o conhecimento, já dizia a poetisa brasileira Cora Coralina: "Feliz aquele que transfere o que sabe, e aprende o que ensina", farei uma série de artigos explicando sobre o tema, e esse é só o primeiro deles...

Antes de tudo, para lembrar, o que é uma LLM mesmo?

A LLM pode ser definida de algumas formas. Uma delas é: "São modelos de linguagem de máquina, que usam algoritmos de aprendizado profundo (Deep Learning) para processar e aprender a linguagem natural", essa é a sua definição estrutural. A definição que mais gosto é: "A LLM, na sua essência, é composta por dois arquivos: um contendo os pesos (parâmetros) com os conhecimentos aprendidos, e o outro com o código necessário para rodar os dados aprendidos.", como uma pessoa visual, consigo imaginar melhor como funciona.

Então, ChatGPT, Claude e muitos outros são exatamente isso, e atualmente têm a capacidade de executar várias atividades, como escrever código, traduzir texto, responder às mais variadas dúvidas e, dependendo da sua capacidade de escrever prompts mais robustos, pode até criar arquiteturas de produtos, te ajudar a resolver bugs complexos, te dar ideias, e até criar um SaaS revolucionário (risos).

O ponto é que a capacidade das LLMs de "compreender" e "criar" chegou a um ponto bem avançado, e você só chega na camada -17 de boas respostas fazendo as perguntas de forma certa!

Nota: Camada -17 se refere à camada onde se acha o minério de ouro no jogo Minecraft ;).

Fazendo Perguntas

Como fazer as perguntas certas? E por que saber isso importa? Vamos lá.

Saber fazer as perguntas certas para uma LLM é tão importante que existe uma área da tecnologia específica só para isso: a Engenharia de Prompts, definida como "a ciência empírica de planejar, criar e testar prompts para gerar melhores respostas em LLMs". Saber fazer as perguntas certas te coloca em outro nível, você consegue obter as melhores respostas, e isso te traz muitos ganhos, sendo o principal deles a produtividade.

Mas afinal, como perguntar de forma certa?

A LLM é poderosa, mas não adivinha sua intenção. Para obter os melhores resultados nas suas buscas, você precisa se concentrar na criação de prompts claros, na especificidade e ser rico em dar contexto. E tudo isso envolve:

1 - Evite a Ambiguidade

"Espaço de possibilidades"

Quando você escreve um prompt muito ambíguo, vago, o modelo enxerga vários caminhos estatisticamente válidos. É como se ele estivesse numa encruzilhada com 50 estradas e todas tivessem placas dizendo "Talvez por aqui", ele vai escolher uma, mas não necessariamente a que você precisa: a estrada com o percurso mais rápido e sem trânsito (a resposta correta de fato).

Exemplos:

Prompt ambíguo:

"Crie uma API."

O que a LLM "vê": Vários caminhos, API REST? GraphQL? Em qual linguagem? Para qual domínio? Com autenticação? Com banco? O modelo vai escolher o caminho mais estatisticamente comum nos dados de treino (provavelmente uma API REST genérica em Node.js com Express), que pode não ter nada a ver com o que você precisa.

Prompt sem ambiguidade:

"Crie um microsserviço em Node.js com Express e TypeScript para processar pagamentos via
Stripe. Endpoints: criar pagamento, confirmar webhook e consultar status. O payload tem:
orderId(UUID), amount(number), currency(enum: BRL, USD) e customerId(string).
Use zod para validação, Prisma com PostgreSQL para persistir as transações e winston
para logs. Retorne status codes apropriados como(201, 200, 400, 422, 500). Trate falhas de
rede com retry automático (máx. 3 tentativas)."

O que a LLM "vê": Um caminho quase único. Cada detalhe funciona como uma restrição que elimina ambiguidade: "Node.js com Express e TypeScript" define runtime, framework e linguagem de uma vez. "Pagamentos via Stripe" restringe o SDK e o domínio. "3 endpoints explícitos + payload com tipos" elimina adivinhações sobre rotas e schema. "Zod, Prisma, PostgreSQL, Winston" travam a stack, o modelo não vai sugerir alternativas. "Status codes específicos + retry com máximo de 3 tentativas" definem os status HTTP e a estratégia com limites claros. A distribuição de probabilidade fica concentrada e o modelo praticamente "só tem uma opção" a cada token gerado.

2 - Delimite o Escopo

"Janela de atenção"

LLMs têm um context window(Janela), uma quantidade de tokens (pedaço de palavra) que conseguem ser processados de uma vez. Isso inclui o seu prompt e a resposta gerada. Dentro dessa janela, existe um fenômeno importante: nem todos os tokens recebem a mesma "atenção" no processamento.

O mecanismo de self-attention (o coração da arquitetura Transformer, não é um cubo rsrsrs, e a arquitetura de rede neural, que seria o framework da LLM se a mesma fosse uma linguagem de programação), ela define a estrutura de tudo, calcula relações entre todos os tokens do prompt. Quanto mais tokens irrelevantes existem, mais o modelo precisa "dividir atenção" entre informações úteis e inúteis.

Exemplos:

Sem escopo:

"Me ensine Docker."

O que acontece internamente: O modelo precisa decidir entre centenas de subtópicos, instalação, conceitos básicos, Dockerfile, docker-compose, volumes, orquestração, a atenção se fragmenta e o resultado é um overview superficial de tudo.

Com escopo:

"Explique o conceito de multi-stage build no Docker para um dev backend pleno que já usa
Docker no dia a dia mas nunca otimizou o tamanho das imagens. Mostre um exemplo prático
com uma aplicação JavaScript, comparando o Dockerfile sem e com multi-stage build,
incluindo o tamanho final de cada imagem."

O que acontece internamente: O mecanismo de atenção se concentra em uma região muito específica, a interseção entre "Docker", "multi-stage build", "otimização de imagem" e "JavaScript". Os pesos de atenção ficam fortemente direcionados.

3 - Forneça Contexto Relevante

"Estado da aplicação"

Uma LLM é stateless por natureza, ela não tem memória entre requisições. Cada prompt é processado do zero, o único "estado" que ela tem é o que você coloca no prompt. Isso significa que todo contexto que você não fornece simplesmente não existe para o modelo.

Internamente, o contexto funciona como um sistema de pesos no mecanismo de atenção. Quando você adiciona informações, elas criam "âncoras" que influenciam a distribuição de probabilidades de todos os tokens subsequentes, é como se cada pedaço de contexto fosse um ímã que puxa a resposta para uma direção específica.

Exemplos:

Sem contexto:

"Revise meu código."

O que a LLM faz: Sem saber a linguagem, o framework, o nível do dev, o objetivo do código, o padrão do time ou o tipo de revisão esperada, ela vai fazer comentários genéricos: "adicione tratamento de erro", "use nomes mais descritivos", "considere adicionar testes".

Com contexto:

"Revise este endpoint Node.js com Express que lida com upload de arquivos para o S3.
O time usa ESLint + Prettier, então ignore estilo. O padrão do time é async/await com
try/catch e erros customizados. Endpoint em produção, recebe 200 uploads/min.
Foque em: memory leaks, tratamento de erros e uso correto do SDK do S3."

O que a LLM faz: Cada informação do prompt funciona como um filtro que elimina ruído e concentra a revisão: "Node.js com Express + upload para S3" ativa conhecimento específico sobre streams, buffers, multipart e AWS SDK. "ESLint + Prettier, ignore estilo" elimina os comentários possíveis que o linter já resolve. "async/await com erros customizados" faz o modelo pular sugestões que o time já aplica e focar em como estão sendo usadas. "Produção, 200 uploads/min" muda o peso de cada problema, um buffer não liberado que seria aceitável em dev vira um incidente crítico sob carga. "Foque em: memory leaks, erros, SDK S3" restringe a revisão a 3 eixos e ignora dezenas de outros tópicos.

Com base nisso, saber as limitações do modelo que você está usando, te ajuda também a entender até aonde você pode ir nas perguntas e inferências, então escolha a sua melhor IA, treine ela, faça as suas perguntas, teste, tente! ;)

É Lembre-se: a LLM não "pensa", ela calcula probabilidades!

Considerações Finais

É isto, tentei resumir cada ponto que achei interessante abordar e explicar nessa primeira etapa, mas há muito mais sobre engenharia de prompt de LLM para falar, como técnicas mais clássicas de engenharia de prompts(Zero-shot prompting, Role prompting), técnicas mais avançadas(Chain-of-Thought (CoT), Prompt Chaining), são muitas camadas que tentarei destrinchar nos próximos artigos, esse é apenas o primeiro que traz a minha volta para a escrita de artigos após alguns bons anos. Espero que você caro leitor tenha entendido e aprendido algo. Obrigado por ler até aqui. ;)

Onde me encontrar:

Meu LinkedIn
Meu GitHub

POO Além do Código #1: Abstração (O Arquiteto de Soluções)

Bruno Freschi — Thu, 12 Mar 2026 19:35:57 +0000

Você já sentiu que seu código está virando um "emaranhado" de funções, mesmo usando classes? Muitas vezes, o problema não é a linguagem ou o framework, mas a falta de um conceito fundamental que separa os digitadores de código dos arquitetos de software: a Abstração.

Neste primeiro artigo da série sobre os pilares da POO, vamos descer um nível e entender por que a abstração é a alma de sistemas escaláveis.

🧐 O que é Abstração, afinal?

Abstrair não é "esconder código". Abstrair é a arte de ignorar o que não importa em um determinado contexto.

Imagine um objeto Carro. Dependendo do sistema que você está construindo, a abstração dele muda completamente:

Contexto	O que importa (Abstração)	O que é irrelevante
GPS / Logística	Latitude, Longitude, Velocidade	Cor do estofado, Tipo de óleo
Oficina Mecânica	Histórico de revisões, Peças, KM	Destino da viagem atual
E-commerce	Preço, Modelo, Ano, Estoque	Pressão dos pneus

Regra de Ouro: Foque no O QUE o objeto faz, e não no COMO ele faz.

🎮 O Exemplo do Controle Remoto

Pense na interface de um controle remoto. Você tem botões para Ligar(), MudarCanal() e AjustarVolume().

Para você, não importa se a TV recebe o sinal via Infravermelho, Bluetooth ou Wi-Fi. A abstração (os botões) permanece a mesma, enquanto a implementação (a eletrônica interna) pode mudar completamente sem que você precise aprender a usar o controle de novo.

💻 Abstração na Prática (C#)

Quando trazemos isso para o código, estamos definindo contratos de comportamento. Veja este exemplo focado no domínio de pagamentos:

// Definimos o "Contrato": Todo meio de pagamento DEVE ser processado.
// O COMO (Pix, Cartão, Boleto) não nos interessa neste nível.

public abstract class MeioDePagamento
{
    public decimal Valor { get; set; }

    // O arquiteto define o comportamento, mas deixa a execução para o futuro.
    public abstract void Processar();
}

Estou aplicando neste repo. alguns conceitos

BrunoSFreschi/Blueprint-OOP

Por que isso é poderoso?

Se amanhã surgir o "CryptoPay", você não precisa alterar a lógica principal do seu sistema. Você apenas cria uma nova classe que herda de MeioDePagamento e implementa o método Processar(). O restante do software continua conversando com a abstração.

🚨 O Erro Comum: O "Procedural Disfarçado"

No ecossistema .NET, é muito comum cairmos na armadilha das classes "Anêmicas" acompanhadas de gerenciadores:

UserService
UserHelper
UserManager

Se o seu objeto User só tem propriedades (get/set) e toda a lógica está em um "Helper", você não está fazendo Orientação a Objetos. Você está fazendo Programação Procedural dentro de classes.

A abstração real acontece quando o objeto possui comportamento e responsabilidades claras dentro do seu contexto.

🧠 Checkpoint Mental

Antes de criar sua próxima classe, faça estas quatro perguntas:

🏦 Domínio: Esta classe representa um objeto real do meu negócio?
🔍 Contexto: Estou colocando detalhes que não pertencem a este cenário?
⚙️ Tecnologia: Se eu trocar o banco de dados ou a UI, essa ideia ainda faz sentido?
🎭 Comportamento: Estou modelando ações ou apenas guardando dados (balde de variáveis)?

🛤️ Próximos Passos

A abstração é o alicerce. Sem ela, os outros pilares perdem o sentido. No próximo post, vamos falar sobre Encapsulamento: como proteger essa abstração e garantir que ninguém "mexa nos fios" por trás do controle remoto.

E você? Já pegou algum sistema onde a falta de abstração tornou uma mudança simples em um pesadelo de refatoração? Deixe nos comentários!

#dotnet #csharp #poo #architecture #programming

Do commit ao deploy: CI/CD de uma API na AWS usando GitHub Actions, ECS e Terraform

Fernando Andrade — Thu, 12 Mar 2026 00:07:27 +0000

Sumário

Introdução
Pré-requisitos
Visão Geral da Arquitetura
Configurando o IAM para o Terraform
Infraestrutura como Código com Terraform
- Recursos Provisionados
- IAM Role para Tarefas ECS
- Task Definition (Fargate)
- ECS Service
- OIDC: Autenticação Sem Credenciais Estáticas
Dockerfile Multi-Stage
Pipeline de CI
Protegendo a Branch Main
Configurando as Secrets no GitHub
Pipeline de CD
Acessando a Aplicação após o Deploy
Segurança: OIDC em Detalhe
Fluxo Completo: Do Commit ao Deploy
Considerações Finais

Introdução

Colocar uma aplicação em produção vai muito além de escrever código. Envolve compilar, testar, empacotar e entregar de forma confiável e repetível. Neste artigo, vou mostrar como construir uma pipeline completa — do commit ao deploy — usando GitHub Actions para CI/CD, Terraform para infraestrutura como código e AWS (ECR, ECS Fargate) como plataforma de execução.

O conceito apresentado aqui é agnóstico de linguagem — funciona para qualquer stack que rode em um container Docker (Node.js, Go, Java, Python, etc.). Para os exemplos práticos, vamos utilizar .NET como referência, mas os workflows, a infraestrutura Terraform e o fluxo de deploy são os mesmos independente da tecnologia escolhida.

O objetivo é demonstrar como essas ferramentas se conectam para formar um fluxo automatizado onde um simples merge na branch main resulta em uma nova versão rodando em produção, sem intervenção manual.

Pré-requisitos

Antes de começar, você precisa ter as seguintes ferramentas instaladas e configuradas:

Ferramenta	Descrição	Link de instalação
Docker	Para construir e executar containers	docs.docker.com/get-docker
Terraform	Para provisionar infraestrutura como código	developer.hashicorp.com/terraform/install
AWS CLI	Para interagir com os serviços da AWS via terminal	docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html
Git	Para versionamento de código	git-scm.com/downloads
Conta AWS	Com permissões para criar recursos (IAM, ECS, ECR)	aws.amazon.com/free
Conta GitHub	Para hospedar o repositório e rodar os workflows	github.com

Nota: Para o exemplo deste artigo, também é necessário o .NET SDK instalado localmente para desenvolvimento. Se você estiver usando outra stack, substitua pelo SDK correspondente (Node.js, Go, JDK, etc.). Outro ponto é que a escolha em utilizar o ECS ao invés de um EKS ou EC2 é devido sua simplicidade na curva de aprendizado, baixo gerenciamento e que para fins de aprendizado os recursos mínimos definidos para esse laboratório não gerem altos gastos para o aprendizado.

Visão Geral da Arquitetura

O fluxo completo funciona assim:

Developer → Feature Branch → Pull Request → Validação (CI)
                                                  ↓
                                            Merge na main
                                                  ↓
                                         Build & Push (CD)
                                                  ↓
                                        Deploy no ECS Fargate

Configurando o IAM para o Terraform

Antes de rodar qualquer terraform apply, é necessário que o Terraform tenha permissões para criar recursos na AWS. Para isso, precisamos de um usuário IAM (ou role) com as permissões adequadas e configurar suas credenciais localmente.

Criando um usuário IAM para o Terraform

No console da AWS (IAM > Users), crie um usuário dedicado para o Terraform:

Acesse IAM > Users > Create User
Nomeie o usuário (ex: terraform-deployer)
Anexe as policies necessárias para os recursos que serão criados:

AmazonECS_FullAccess
AmazonEC2ContainerRegistryFullAccess
AmazonVPCReadOnlyAccess
IAMFullAccess
CloudWatchLogsFullAccess
AmazonS3FullAccess

Nota de segurança: Em um ambiente produtivo, o ideal é criar uma policy customizada com o princípio do menor privilégio, concedendo apenas as permissões estritamente necessárias. Para fins de estudo, as managed policies acima simplificam o setup.

Após criar o usuário, gere um Access Key (IAM > Users > Security credentials > Create access key)
Selecione o caso de uso Command Line Interface (CLI)

Configurando as credenciais localmente

Com o AWS CLI instalado, configure as credenciais:

aws configure

Será solicitado:

AWS Access Key ID: AKIA...
AWS Secret Access Key: wJal...
Default region name: us-east-1
Default output format: json

Isso cria o arquivo ~/.aws/credentials que o Terraform utilizará automaticamente via o provider AWS. Com isso feito, o Terraform tem autorização para provisionar os recursos que definiremos a seguir.

Infraestrutura como Código com Terraform

Antes de qualquer pipeline rodar, a infraestrutura precisa existir. Com o Terraform, declaramos todos os recursos AWS em arquivos .tf e provisionamos com um único comando.

Recursos Provisionados

# Provider AWS
provider "aws" {
  region = "us-east-1"
}

# Repositório ECR para armazenar imagens Docker
resource "aws_ecr_repository" "app_repository" {
  name = "minha-app-repository"
}

# Cluster ECS
resource "aws_ecs_cluster" "app_cluster" {
  name = "minha-app-cluster"
}

IAM Role para Tarefas ECS

O ECS precisa de uma role para puxar imagens e enviar logs:

resource "aws_iam_role" "ecs_task_execution_role" {
  name = "ecs-task-execution-role"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Action    = "sts:AssumeRole"
      Effect    = "Allow"
      Principal = { Service = "ecs-tasks.amazonaws.com" }
    }]
  })
}

resource "aws_iam_role_policy_attachment" "ecs_policy" {
  role       = aws_iam_role.ecs_task_execution_role.name
  policy_arn = "arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy"
}

Task Definition (Fargate)

Aqui definimos como o container será executado:

resource "aws_ecs_task_definition" "app_task" {
  family                   = "minha-app-task"
  network_mode             = "awsvpc"
  requires_compatibilities = ["FARGATE"]
  cpu                      = "256"
  memory                   = "512"
  execution_role_arn       = aws_iam_role.ecs_task_execution_role.arn

  container_definitions = jsonencode([{
    name      = "app"
    image     = "${aws_ecr_repository.app_repository.repository_url}:latest"
    portMappings = [{
      containerPort = 8080
      hostPort      = 8080
    }]
    logConfiguration = {
      logDriver = "awslogs"
      options = {
        "awslogs-group"         = "/ecs/minha-app"
        "awslogs-region"        = "us-east-1"
        "awslogs-stream-prefix" = "ecs"
      }
    }
  }])
}

ECS Service

O service mantém o container rodando e gerencia o deploy:

resource "aws_ecs_service" "app_service" {
  name            = "minha-app-service"
  cluster         = aws_ecs_cluster.app_cluster.id
  task_definition = aws_ecs_task_definition.app_task.arn
  desired_count   = 1
  launch_type     = "FARGATE"

  network_configuration {
    subnets          = data.aws_subnets.default.ids
    security_groups  = [aws_security_group.app_sg.id]
    assign_public_ip = true
  }
}

OIDC: Autenticação Sem Credenciais Estáticas

Este é um dos pontos mais importantes da arquitetura. Em vez de armazenar AWS_ACCESS_KEY e AWS_SECRET_KEY como secrets no GitHub, usamos OIDC (OpenID Connect) para que o GitHub Actions troque um token temporário por credenciais AWS.

# Registra o GitHub como provedor OIDC na AWS
resource "aws_iam_openid_connect_provider" "github" {
  url             = "https://token.actions.githubusercontent.com"
  client_id_list  = ["sts.amazonaws.com"]
  thumbprint_list = ["ffffffffffffffffffffffffffffffffffffffff"]
}

# Role que o GitHub Actions vai assumir
resource "aws_iam_role" "github_actions_role" {
  name = "github-actions-role"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Principal = {
        Federated = aws_iam_openid_connect_provider.github.arn
      }
      Action = "sts:AssumeRoleWithWebIdentity"
      Condition = {
        StringEquals = {
          "token.actions.githubusercontent.com:aud" = "sts.amazonaws.com"
        }
        StringLike = {
          "token.actions.githubusercontent.com:sub" = "repo:meu-usuario/meu-repo:ref:refs/heads/main"
        }
      }
    }]
  })
}

Por que isso importa? Credenciais estáticas são um risco de segurança. Com OIDC, as credenciais são temporárias e o acesso é restrito a uma branch específica de um repositório específico. Mesmo que alguém tenha acesso ao repositório, não consegue assumir a role a partir de outra branch.

Dockerfile Multi-Stage

Usamos um build multi-stage para separar o ambiente de compilação do ambiente de execução, resultando em uma imagem final menor e mais segura:

# Stage 1: Build
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY ["MeuProjeto/MeuProjeto.csproj", "MeuProjeto/"]
RUN dotnet restore "MeuProjeto/MeuProjeto.csproj"
COPY . .
WORKDIR "/src/MeuProjeto"
RUN dotnet build -c Release -o /app/build

# Stage 2: Publish
FROM build AS publish
RUN dotnet publish -c Release -o /app/publish /p:UseAppHost=false

# Stage 3: Runtime
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final
WORKDIR /app
EXPOSE 8080
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "MeuProjeto.dll"]

Benefícios do multi-stage:

A imagem final contém apenas o runtime, não o SDK completo
Reduz significativamente o tamanho da imagem
O código-fonte não fica presente na imagem de produção

Pipeline de CI

A primeira pipeline roda automaticamente quando um Pull Request é aberto contra a branch main. Seu objetivo é validar que o código compila e que os testes passam.

name: PR Validation

on:
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.0.x'

      - name: Restore
        run: dotnet restore MinhaSolution.sln

      - name: Build
        run: dotnet build MinhaSolution.sln --no-restore -c Release

  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.0.x'

      - name: Run Tests with Coverage
        run: |
          dotnet test MinhaSolution.sln \
            --collect:"XPlat Code Coverage" \
            --results-directory ./coverage

O que acontece nesta pipeline:

Job build — Compila a solução para garantir que não há erros de compilação
Job test — Roda os testes unitários com cobertura de código usando Coverlet

Separar em dois jobs traz clareza: se o build falha, você sabe que é erro de compilação. Se o test falha, o código compila mas tem um bug.

Protegendo a Branch Main

Com a pipeline de CI configurada, é fundamental garantir que nenhum código chegue à main sem passar pela validação. Para isso, configuramos uma branch protection rule no GitHub.

Acesse Settings > Branches > Add branch protection rule no seu repositório e configure:

Branch name pattern: main
Marque Require a pull request before merging — impede push direto na main
Marque Require status checks to pass before merging — bloqueia o merge até que os checks passem
Em Status checks that are required, busque e adicione os jobs da pipeline de CI:
- build
- test

Nota: Na primeira vez que configurar, os status checks podem não aparecer na busca. Eles só ficam disponíveis após a pipeline rodar pelo menos uma vez no repositório. Abra um PR de teste para que os checks sejam registrados.

Configurando as Secrets no GitHub

Antes de configurar a pipeline de deploy, é necessário cadastrar as secrets no repositório do GitHub. A pipeline de CD depende delas para autenticar na AWS e saber para onde enviar a imagem Docker.

Acesse Settings > Secrets and variables > Actions > New repository secret no seu repositório e crie as seguintes secrets:

Secret	Valor	Exemplo
`AWS_ROLE`	O ARN completo da IAM Role criada para o GitHub Actions	`arn:aws:iam::123456789012:role/github-actions-role`
`ECR_REPOSITORY`	A URI completa do repositório ECR (não apenas o nome)	`123456789012.dkr.ecr.us-east-1.amazonaws.com/minha-app-repository`
`AWS_ACCOUNT_ID`	O ID numérico da sua conta AWS	`123456789012`

Atenção: Um erro comum é colocar apenas o nome do repositório ECR (ex: minha-app-repository) na secret ECR_REPOSITORY. O valor correto é a URI completa que inclui o domínio do ECR. Você pode obter essa URI no console da AWS em ECR > Repositories ou via CLI:

aws ecr describe-repositories --repository-names minha-app-repository \
  --query "repositories[0].repositoryUri" --output text

Da mesma forma, a secret AWS_ROLE deve conter o ARN (Amazon Resource Name) completo da role, não apenas o nome. Para consultar:

aws iam get-role --role-name github-actions-role \
  --query "Role.Arn" --output text

Com as secrets configuradas, a pipeline de deploy consegue autenticar via OIDC, fazer push da imagem para o ECR e disparar o deploy no ECS.

Pipeline de CD

Quando o PR é aprovado e mergeado na main, a pipeline de deploy entra em ação:

name: Build and Deploy

on:
  push:
    branches: [main]

permissions: #permissões necessárias para autenticação OIDC
  id-token: write
  contents: read 

env:
  AWS_REGION: us-east-1

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS Credentials (OIDC)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Login to Amazon ECR
        uses: aws-actions/amazon-ecr-login@v2

      - name: Build Docker Image
        run: docker build -t minha-app .

      - name: Tag Image
        run: docker tag minha-app:latest ${{ secrets.ECR_REPOSITORY }}:latest

      - name: Push to ECR
        run: docker push ${{ secrets.ECR_REPOSITORY }}:latest

      - name: Deploy to ECS
        run: |
          aws ecs update-service \
            --cluster minha-app-cluster \
            --service minha-app-service \
            --force-new-deployment

O que acontece nesta pipeline:

Autenticação OIDC — O GitHub troca seu token JWT por credenciais AWS temporárias
Login no ECR — Autentica o Docker no registro da AWS
Build e Push — Constrói a imagem Docker e envia para o ECR
Deploy — Dispara um novo deployment no ECS, que puxa a imagem atualizada e substitui o container antigo

O --force-new-deployment garante que o ECS vai iniciar uma nova task mesmo que a tag da imagem (latest) não tenha mudado.

Acessando a Aplicação após o Deploy

Após a pipeline de CD concluir com sucesso, a aplicação estará rodando no ECS Fargate. Como configuramos assign_public_ip = true no Terraform, a task recebe um IP público que pode ser usado para acessar a API.

Obtendo o IP público pelo Console AWS

Acesse ECS > Clusters > minha-app-cluster
Clique na aba Tasks
Clique na task em execução (status RUNNING)
Na seção Network, copie o Public IP
Acesse no navegador: http://<PUBLIC_IP>:8080

Obtendo o IP público via CLI

# 1. Obtenha o ARN da task em execução
TASK_ARN=$(aws ecs list-tasks \
  --cluster minha-app-cluster \
  --service-name minha-app-service \
  --query "taskArns[0]" --output text)

# 2. Obtenha o ID da interface de rede (ENI)
ENI_ID=$(aws ecs describe-tasks \
  --cluster minha-app-cluster \
  --tasks $TASK_ARN \
  --query "tasks[0].attachments[0].details[?name=='networkInterfaceId'].value" \
  --output text)

# 3. Obtenha o IP público
aws ec2 describe-network-interfaces \
  --network-interface-ids $ENI_ID \
  --query "NetworkInterfaces[0].Association.PublicIp" \
  --output text

Importante: O IP público muda toda vez que uma nova task é criada (ou seja, a cada deploy). Para um ambiente produtivo, o ideal é utilizar um Application Load Balancer (ALB) ou um domínio com Route 53 apontando para o serviço ECS, garantindo um endereço fixo. Para fins de estudo, o IP público direto é suficiente.

Segurança: OIDC em Detalhe

Vale reforçar a importância do OIDC neste fluxo. O modelo tradicional funciona assim:

❌ Modelo Tradicional:
   GitHub Secrets → AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
   - Credenciais estáticas que nunca expiram
   - Se vazadas, acesso total até serem rotacionadas manualmente

Com OIDC:

✅ Modelo OIDC:
   GitHub Actions → JWT Token → AWS STS → Credenciais Temporárias
   - Credenciais expiram automaticamente
   - Escopo restrito: apenas uma branch de um repositório específico
   - Sem segredos de longa duração armazenados

A configuração requer:

Registrar o GitHub como OIDC Provider na AWS (via Terraform)
Criar uma IAM Role com trust policy apontando para o repositório
No workflow, usar permissions: id-token: write e a action configure-aws-credentials com role-to-assume

Fluxo Completo: Do Commit ao Deploy

Resumindo o ciclo de vida de uma mudança:

1. git checkout -b feature/minha-feature
2. # Desenvolve e commita
3. git push origin feature/minha-feature
4. # Abre Pull Request → Dispara pr-validation.yml
   │
   ├── ✅ Build compila com sucesso
   └── ✅ Testes passam com cobertura
   │
5. # Code review + Aprovação
6. # Merge na main → Dispara build-and-deploy.yml
   │
   ├── 🔐 Autenticação via OIDC
   ├── 🐳 Build da imagem Docker (multi-stage)
   ├── 📦 Push para o ECR
   └── 🚀 Deploy no ECS Fargate
   │
7. # Nova versão rodando em produção

Considerações Finais

Este setup demonstra como é possível construir uma pipeline profissional de CI/CD com ferramentas modernas e boas práticas:

Infraestrutura como Código — Toda a infraestrutura é versionada e reproduzível
Autenticação Keyless — OIDC elimina o risco de credenciais estáticas
Serverless Containers — Fargate remove a necessidade de gerenciar servidores
Separação CI/CD — Validação em PRs e deploy apenas na main
Imagens otimizadas — Multi-stage build reduz a superfície de ataque

O custo de infraestrutura para um setup como esse é mínimo — com Fargate usando 0.25 vCPU e 512MB de memória, o custo fica na faixa de poucos dólares por mês para ambientes de estudo e projetos pequenos.

A barreira de entrada para CI/CD profissional diminuiu muito. Ferramentas como GitHub Actions e Terraform tornam acessível o que antes exigia equipes dedicadas de DevOps. O importante é começar simples, entender cada peça, e evoluir conforme a necessidade.

Este artigo foi escrito com base em um projeto prático de estudo. Todo o código-fonte está disponível publicamente neste repositório do GitHub.