DEV Community: Denis Augusto

Você criou uma tabela de tokens pra proteger PDF. O Laravel já fazia isso.

Denis Augusto — Mon, 17 Aug 2026 18:19:41 +0000

O contrato do cliente tá numa URL que qualquer um adivinha

A tarefa parecia simples: o cliente precisa baixar a nota fiscal dele.

Você salvou em storage/app/public/notas/, rodou php artisan storage:link, mandou o link e foi feliz. https://app.com/storage/notas/nota-1042.pdf.

Semanas depois cai a ficha. Aquele arquivo está aberto na internet. Sem login, sem nada. E o nome é sequencial: quem baixou a nota-1042.pdf só precisa de curiosidade e cinco segundos pra tentar a 1041. E a 1040.

Então você faz a coisa certa: tira do disco público e cria um sistema pra controlar acesso. Tabela download_tokens, model, geração de UUID, coluna expires_at, controller que valida, e um comando no scheduler pra limpar os vencidos.

Sessenta linhas depois, funciona. E aí alguém comenta no PR: "por que você não usou uma URL assinada?"

O sistema que você não precisava construir

// ❌ migration + model + controller + command. tudo isso pra um PDF.
Schema::create('download_tokens', function (Blueprint $table) {
    $table->id();
    $table->uuid('token')->unique();
    $table->string('path');
    $table->foreignId('user_id');
    $table->timestamp('expires_at');
    $table->timestamps();
});

public function gerarLink(NotaFiscal $nota): string
{
    $token = DownloadToken::create([
        'token'      => Str::uuid(),
        'path'       => $nota->arquivo_path,
        'user_id'    => auth()->id(),
        'expires_at' => now()->addMinutes(10),
    ]);

    return route('download', $token->token);
}

Não tem nada de errado tecnicamente. O problema é o custo: mais uma tabela crescendo pra sempre, mais um comando no scheduler, mais um caminho pra testar. E você vai manter isso enquanto o projeto existir.

O Laravel resolve o mesmo problema com uma assinatura criptográfica na própria URL. Sem estado, sem tabela, sem limpeza.

Como uma URL assinada funciona

A ideia é bonita de simples: o Laravel monta a URL com os parâmetros que você quer, calcula um hash disso tudo usando a APP_KEY e cola o hash no final.

/notas/1042/download?expires=1755388800&signature=8f3a9c...

Quando o request chega, ele recalcula o hash e compara. Mexeu em qualquer coisa — o ID, a data de expiração, uma vírgula — a assinatura não fecha e o acesso morre com 403.

Ou seja: o "token" é a própria URL. Não tem o que guardar, porque a validade está embutida nela.

Duas linhas, dois cenários

Cenário 1: o arquivo tá no S3 (ou em qualquer disco que gere URL temporária).

Aqui é literalmente uma linha, e o download nem passa pelo seu servidor:

$url = Storage::disk('s3')->temporaryUrl(
    $nota->arquivo_path,
    now()->addMinutes(5)
);

Cinco minutos depois o link morre. O S3 se recusa a servir. Zero código seu envolvido.

Se você usa disco local, isso também funciona desde o Laravel 11 — só precisa avisar no config/filesystems.php:

'local' => [
    'driver' => 'local',
    'root'   => storage_path('app/private'),
    'serve'  => true, // libera o temporaryUrl no disco local
    'throw'  => false,
],

Cenário 2: você quer uma rota sua, pra registrar o acesso ou aplicar regra.

// gerando o link
return URL::temporarySignedRoute(
    'notas.download',
    now()->addMinutes(10),
    ['nota' => $nota->id]
);

// a rota. o middleware 'signed' faz toda a validação.
Route::get('/notas/{nota}/download', function (NotaFiscal $nota) {
    return Storage::download($nota->arquivo_path, "nota-{$nota->numero}.pdf");
})->name('notas.download')->middleware('signed');

O signed confere a assinatura e a expiração antes do seu código rodar. Se estiver inválido, 403 e pronto — você não escreve um if.

Como usar na prática

Nota fiscal enviada por e-mail: gere com validade de 7 dias. O cliente clica direto do e-mail, sem login, e o link não serve pra mais ninguém depois.

Cancelar inscrição: o caso clássico. URL::signedRoute('unsubscribe', ['user' => $user->id]) sem expiração — o cara clica dois meses depois e funciona, mas ninguém consegue descadastrar outra pessoa trocando o ID na URL.

Convite de cadastro: link com validade de 48 horas que já leva o e-mail assinado dentro. Se o convidado editar o e-mail pra outro, a assinatura quebra.

A pegadinha: assinatura não é autorização

Essa é a confusão que vale gravar.

Uma URL assinada garante que ninguém adulterou o link. Ela não garante que quem está clicando é o dono do arquivo. Se o link vazar no WhatsApp, quem tiver o link entra.

Pra dado sensível, as duas coisas convivem:

Route::get('/notas/{nota}/download', function (NotaFiscal $nota) {
    Gate::authorize('view', $nota); // e ainda precisa ser o dono

    return Storage::download($nota->arquivo_path);
})->middleware(['signed', 'auth']);

Assinatura para quem está fora do login (e-mail, webhook, convite). Policy para quem está dentro. Expiração curta em tudo que for confidencial.

E o outro tropeço, o mais comum de todos: storage:link com disco public é público de verdade. Não é "público pro usuário logado", é público pro Google. Se o arquivo tem dono, ele não mora ali — mora no disco privado, e sai por uma rota.

Bônus: dois detalhes que economizam uma tarde

Trocar a APP_KEY invalida todas as assinaturas em circulação. É até desejável (é o seu "logout de emergência" de links), mas se você rotacionar a chave num dia de disparo de e-mail, prepare o suporte.

Atrás de proxy, cuide da URL. Se APP_URL ou os TrustProxies estiverem tortos, o Laravel calcula a assinatura sobre um host diferente do que o usuário acessou e tudo dá 403. O sintoma é sempre o mesmo: funciona local, quebra em produção.

Antes de você fechar a aba

A lição aqui é maior que URL assinada: antes de criar tabela e comando de limpeza pra resolver algo genérico, dá uma busca na doc. "Expirar um link" é um problema que todo mundo tem — as chances de já vir resolvido são altas.

E o código que você não escreve é o único que nunca tem bug.

Agora fala a verdade: você tem arquivo de cliente numa pasta pública agora? Se der aquele friozinho na barriga, abre o storage/app/public antes de responder. Eu já achei um monte de contratos assinados lá dentro — em projeto que não era meu, felizmente. 😅

Seu log tem 40 mil linhas e nenhuma resposta

Denis Augusto — Mon, 17 Aug 2026 18:17:46 +0000

"Deu erro ao salvar, umas duas da tarde"

É a única informação que você tem. O cliente não lembra o que clicou, não tirou print e já fechou a aba.

Você abre o laravel.log. Quarenta mil linhas no dia.

Faz um grep por "erro". Aparecem 1.200 ocorrências, e a maioria é isso:

[2026-08-14 14:03:11] production.INFO: entrou
[2026-08-14 14:03:11] production.INFO: erro aqui
[2026-08-14 14:03:12] production.INFO: passou
[2026-08-14 14:03:12] production.ERROR: Erro ao salvar

Erro ao salvar o quê? De qual usuário? Qual pedido? Qual valor? Aquele entrou da linha de cima é do mesmo request ou de outro cliente que estava usando o sistema no mesmo segundo?

Você tem log. Você não tem informação. São coisas diferentes.

O problema não é a falta de log. É o excesso de log inútil.

public function emitir(Pedido $pedido)
{
    Log::info('entrou no emitir');

    try {
        $nota = $this->sefaz->emitir($pedido);

        Log::info('emitiu');
    } catch (Throwable $e) {
        // parabéns, você registrou que algo deu errado em algum lugar 🎉
        Log::error('Erro ao emitir nota');

        return back()->withErrors('Falha na emissão');
    }
}

Repara no que esse catch jogou no lixo: a mensagem da exceção, o stack trace, o ID do pedido, o CNPJ, o retorno da SEFAZ. Tudo estava ali, na mão, e foi substituído por uma frase genérica.

E os Log::info('entrou') espalhados? Aquilo foi debug que virou permanente. Hoje eles só servem pra empurrar as linhas úteis pra fora da tela.

Duas perguntas que todo log precisa responder

Um log serve pra duas plateias: você, com sono, às 3h da manhã — e uma máquina, filtrando milhões de linhas.

As duas querem a mesma coisa:

O que aconteceu, numa mensagem que não muda nunca.
Com quem aconteceu, em dados separados da mensagem.

Essa separação é o pulo do gato. Repare na diferença:

// ❌ mensagem única pra cada pedido. impossível agrupar ou contar.
Log::error("Falha ao emitir nota do pedido {$pedido->id} do cliente {$cliente->nome}");

// ✅ mensagem estável + contexto estruturado
Log::error('Falha ao emitir nota fiscal', [
    'pedido_id'  => $pedido->id,
    'cliente_id' => $cliente->id,
    'valor'      => $pedido->total,
    'sefaz_code' => $e->getCode(),
    'exception'  => $e,
]);

A primeira versão gera 4.000 mensagens diferentes. Você nunca vai conseguir dizer "esse erro aconteceu 312 vezes hoje".

A segunda gera uma mensagem com 312 contextos diferentes. Dá pra contar, agrupar, filtrar por cliente e montar alerta. E passar a exceção inteira em 'exception' => $e traz o stack trace de graça.

O trace_id: o fio que costura o request

Agora a parte que muda sua vida de verdade.

Mesmo com bom contexto, seu log é um monte de linhas intercaladas de 200 usuários simultâneos. O que falta é saber quais linhas pertencem à mesma requisição.

Um middleware resolve:

class AdicionarContexto
{
    public function handle(Request $request, Closure $next): Response
    {
        Context::add('trace_id', Str::uuid()->toString());
        Context::add('url', $request->url());
        Context::add('user_id', $request->user()?->id);

        return $next($request);
    }
}

A partir daí, todo log escrito naquele request carrega esses dados automaticamente:

[2026-08-14 14:03:11] production.ERROR: Falha ao emitir nota fiscal
{"pedido_id":1042,"sefaz_code":539}
{"trace_id":"e04e1a11-e75c-4db3-b5b5","url":"https://app.com/pedidos/1042/emitir","user_id":88}

Um grep e04e1a11 e você tem a história completa daquele request, em ordem, sem nada de ninguém mais no meio.

E tem um bônus enorme: o contexto atravessa a fila. Job despachado dentro daquele request leva o trace_id junto e continua logando com ele. Você consegue seguir o rastro do clique do usuário até o job que rodou três minutos depois em outro processo.

Devolva o ID no header também ($response->headers->set('X-Trace-Id', ...)) e mostre na tela de erro. O cliente passa a te mandar o código em vez de "deu erro às duas da tarde".

Níveis existem, use-os

Isso é o que faz seu log ficar pequeno de novo. Meu critério, sem cerimônia:

debug — investigação. Não vai pra produção (LOG_LEVEL=info corta).
info — fato de negócio relevante: "pedido pago", "nota emitida".
warning — deu ruim mas contornamos: API lenta, retry funcionou.
error — o usuário foi prejudicado. Isso deveria virar alerta.
critical — o sistema está fora.

Se tudo no seu projeto é info, você não tem níveis — tem um echo com data.

A pegadinha que dá multa

Essa não é sobre organização, é sobre risco:

// 💀 nunca
Log::info('Request recebido', $request->all());

Aí vai senha, token, número de cartão, CPF — em texto puro, num arquivo que a equipe toda lê, que vai pro backup e talvez pro Datadog. É incidente de segurança e é LGPD.

Logue IDs, não conteúdo. Se precisar do payload, filtre antes com $request->except(['password', 'card_number', 'cpf']).

Bônus: JSON e o próximo passo

Se você já joga log em Loki, CloudWatch ou Datadog, troque o formatter do canal por JsonFormatter. Cada linha vira um objeto pesquisável e aquele grep heroico dá lugar a uma query de verdade.

E se precisar carregar algo no contexto sem que apareça nos logs (um ID interno pra correlacionar com outro sistema), existe Context::addHidden().

Antes de você fechar a aba

Log bom não é log detalhado. É log que responde uma pergunta.

Da próxima vez que você escrever um Log::, faça o teste rápido: daqui a seis meses, de madrugada, essa linha me diz o que fazer? Se a resposta é "eu ia precisar abrir o código pra entender", falta contexto.

Custa cinco segundos escrever um array em vez de uma string. Você recupera esse tempo no primeiro incidente.

Me conta: qual a mensagem de log mais inútil que você já achou em produção? Eu tenho Log::info('aqui'), Log::info('aqui2') e — meu favorito — um Log::error('nao era pra chegar aqui') sem nenhum contexto, num sistema com 300 usuários. Chegou. 😅

Middleware é porteiro, não gerente

Denis Augusto — Mon, 17 Aug 2026 18:17:45 +0000

Ele começou com um `if`. Hoje tem 80 linhas.

Sabe como é: precisava barrar quem não tem assinatura ativa. Um middleware, três linhas, resolvido.

Depois entrou o período de teste. Depois o plano legado que tem regra diferente. Depois "aproveita que já buscou a assinatura e desconta um crédito". Depois o e-mail de aviso quando faltam 3 dias pro vencimento.

Hoje esse arquivo tem 80 linhas, faz quatro queries, altera dado no banco e dispara e-mail. Ele não é mais um middleware. É um Service que mora na pasta errada e roda em todo request.

E o pior: essa regra não existe pro resto do seu sistema.

O middleware que virou gerente

class VerificarAssinatura
{
    public function handle(Request $request, Closure $next): Response
    {
        $assinatura = $request->user()->assinatura;

        if (! $assinatura || $assinatura->venceu()) {
            return redirect()->route('planos');
        }

        // "aproveita que já tá aqui" 🙃
        if ($assinatura->creditos < 1) {
            return redirect()->route('planos')->withErrors('Sem créditos');
        }

        $assinatura->decrement('creditos');
        $assinatura->update(['ultimo_acesso' => now()]);

        if ($assinatura->vence_em->diffInDays(now()) <= 3) {
            Mail::to($request->user())->send(new AssinaturaVencendo($assinatura));
        }

        return $next($request);
    }
}

Funciona. Passa nos testes de feature. E tem quatro problemas escondidos que só aparecem meses depois.

Problema 1: middleware só existe no HTTP

Esse é o grande. Middleware é uma camada de request HTTP. Ela não roda em outro lugar nenhum.

Então:

O comando php artisan relatorio:gerar não desconta crédito.
O job na fila não desconta crédito.
Sua rota de API que você esqueceu de agrupar não desconta crédito.
O tinker passa por cima de tudo.

Você não criou uma regra de negócio. Criou uma regra da porta da frente. Qualquer outra entrada no sistema ignora ela.

E, sério, isso não é hipótese: um dia alguém vai criar um endpoint novo, esquecer o middleware, e a assinatura vira um detalhe decorativo.

Problema 2: cobrou antes de saber se deu certo

Repare na ordem: o decrement('creditos') acontece antes do $next($request).

O controller ainda vai rodar. Pode estourar uma exceção, pode devolver erro de validação, o usuário pode ter mandado um PDF corrompido. Não importa — o crédito já foi.

Cobrança é resultado da operação ter dado certo. Não da requisição ter chegado.

Problema 3: ele decide como responder

redirect()->route('planos') é ótimo pra quem está no navegador. E é péssimo pra todo mundo mais.

Seu app mobile chama a API e recebe... um redirect com HTML de página de planos. O front tenta dar response.json() e explode com um erro que não tem nada a ver com o problema real.

Problema 4: e-mail dentro do middleware

Isso significa que todo request carrega a possibilidade de esperar um SMTP responder. E se o servidor de e-mail estiver lento, seu app inteiro fica lento — inclusive pra quem não tem nada a ver com assinatura vencendo.

O que middleware faz bem

Pensa nele como o porteiro do prédio. Ele tem um trabalho só, e faz muito bem: decide quem passa e quem não passa — e ajusta detalhes na entrada e na saída.

Cabe no middleware:

Autenticação e autorização de acesso (auth, signed, verified)
Rate limit (throttle)
Definir idioma, timezone, tenant do request
Mexer em request/response: limpar strings, adicionar header, forçar HTTPS
Correlação e observabilidade: trace_id no contexto do log

Não cabe: alterar dado de negócio, cobrar, enviar e-mail, disparar evento de domínio, decidir preço.

O porteiro confere se você mora no prédio. Ele não reajusta seu condomínio.

O mesmo código, cada coisa no lugar

O middleware volta a ser o que era: um porteiro.

class VerificarAssinatura
{
    public function handle(Request $request, Closure $next): Response
    {
        abort_unless($request->user()->temAssinaturaAtiva(), 403, 'Assinatura inativa');

        return $next($request);
    }
}

Uma linha, uma decisão. E abort_unless deixa o Laravel resolver o formato da resposta: HTML pra navegador, JSON pra API. Você não escolhe por ele.

O crédito vira responsabilidade de quem executa a ação:

class GerarRelatorio
{
    public function execute(User $user, array $filtros): Relatorio
    {
        $assinatura = $user->assinatura;

        // a regra mora aqui: vale pro controller, pro job e pro comando
        throw_unless($assinatura->temCredito(), SemCreditosException::class);

        return DB::transaction(function () use ($assinatura, $filtros) {
            $relatorio = Relatorio::gerar($filtros);

            $assinatura->consumirCredito(); // cobra depois de dar certo

            return $relatorio;
        });
    }
}

Agora a regra é do negócio, não do HTTP. Rodou pelo painel, pela API, pelo comando agendado ou pela fila? Mesma regra, mesma cobrança, mesma transação.

E o e-mail de "vence em 3 dias" nem devia estar no caminho de request nenhum: é um comando no scheduler rodando uma vez por dia.

A pegadinha: `$request->user()` vindo `null`

Enquanto estamos aqui, a confusão mais comum de middleware: ordem.

Middleware global roda antes do auth. Se você registrar algo global que usa $request->user(), vai receber null e um "call to a member function on null" que não faz sentido nenhum.

Se seu middleware depende de usuário logado, ele é de rota (ou de grupo), depois do auth. Nunca global.

Bônus: e se for coisa pra depois da resposta?

Se a ideia era "registrar o acesso sem atrasar o usuário", existe o lugar certo: middleware terminable, com um método terminate() que roda depois da resposta ir pro navegador.

Mas se o dado importa de verdade, prefira um evento e um listener na fila. Aí funciona igual em qualquer entrada do sistema — e é a mesma lógica de sempre: regra de negócio não deveria depender de como o request chegou.

Antes de você fechar a aba

Teste rápido pro seu middleware: se essa mesma ação rodasse por um comando Artisan, a regra ainda precisaria valer?

Se sim, ela não é do middleware. Ela é do domínio, e o middleware está só escondendo isso de você.

Porteiro barra ou libera. Gerente decide o negócio. Quando o porteiro começa a decidir o negócio, alguém entra pela garagem e ninguém percebe.

Me conta: qual o middleware mais gordo que você já viu? Eu já achei um com 200 linhas que fazia login, criava tenant, populava dado inicial e mandava e-mail de boas-vindas — tudo em handle(). 😬

Seu log tem 40 mil linhas e nenhuma resposta

Denis Augusto — Mon, 17 Aug 2026 18:04:08 +0000

"Deu erro ao salvar, umas duas da tarde"

É a única informação que você tem. O cliente não lembra o que clicou, não tirou print e já fechou a aba.

Você abre o laravel.log. Quarenta mil linhas no dia.

Faz um grep por "erro". Aparecem 1.200 ocorrências, e a maioria é isso:

[2026-08-14 14:03:11] production.INFO: entrou
[2026-08-14 14:03:11] production.INFO: erro aqui
[2026-08-14 14:03:12] production.INFO: passou
[2026-08-14 14:03:12] production.ERROR: Erro ao salvar

Erro ao salvar o quê? De qual usuário? Qual pedido? Qual valor? Aquele entrou da linha de cima é do mesmo request ou de outro cliente que estava usando o sistema no mesmo segundo?

Você tem log. Você não tem informação. São coisas diferentes.

O problema não é a falta de log. É o excesso de log inútil.

public function emitir(Pedido $pedido)
{
    Log::info('entrou no emitir');

    try {
        $nota = $this->sefaz->emitir($pedido);

        Log::info('emitiu');
    } catch (Throwable $e) {
        // parabéns, você registrou que algo deu errado em algum lugar 🎉
        Log::error('Erro ao emitir nota');

        return back()->withErrors('Falha na emissão');
    }
}

Repara no que esse catch jogou no lixo: a mensagem da exceção, o stack trace, o ID do pedido, o CNPJ, o retorno da SEFAZ. Tudo estava ali, na mão, e foi substituído por uma frase genérica.

E os Log::info('entrou') espalhados? Aquilo foi debug que virou permanente. Hoje eles só servem pra empurrar as linhas úteis pra fora da tela.

Duas perguntas que todo log precisa responder

Um log serve pra duas plateias: você, com sono, às 3h da manhã — e uma máquina, filtrando milhões de linhas.

As duas querem a mesma coisa:

O que aconteceu, numa mensagem que não muda nunca.
Com quem aconteceu, em dados separados da mensagem.

Essa separação é o pulo do gato. Repare na diferença:

// ❌ mensagem única pra cada pedido. impossível agrupar ou contar.
Log::error("Falha ao emitir nota do pedido {$pedido->id} do cliente {$cliente->nome}");

// ✅ mensagem estável + contexto estruturado
Log::error('Falha ao emitir nota fiscal', [
    'pedido_id'  => $pedido->id,
    'cliente_id' => $cliente->id,
    'valor'      => $pedido->total,
    'sefaz_code' => $e->getCode(),
    'exception'  => $e,
]);

A primeira versão gera 4.000 mensagens diferentes. Você nunca vai conseguir dizer "esse erro aconteceu 312 vezes hoje".

O trace_id: o fio que costura o request

Agora a parte que muda sua vida de verdade.

Mesmo com bom contexto, seu log é um monte de linhas intercaladas de 200 usuários simultâneos. O que falta é saber quais linhas pertencem à mesma requisição.

Um middleware resolve:

class AdicionarContexto
{
    public function handle(Request $request, Closure $next): Response
    {
        Context::add('trace_id', Str::uuid()->toString());
        Context::add('url', $request->url());
        Context::add('user_id', $request->user()?->id);

        return $next($request);
    }
}

A partir daí, todo log escrito naquele request carrega esses dados automaticamente:

[2026-08-14 14:03:11] production.ERROR: Falha ao emitir nota fiscal
{"pedido_id":1042,"sefaz_code":539}
{"trace_id":"e04e1a11-e75c-4db3-b5b5","url":"https://app.com/pedidos/1042/emitir","user_id":88}

Um grep e04e1a11 e você tem a história completa daquele request, em ordem, sem nada de ninguém mais no meio.

Devolva o ID no header também ($response->headers->set('X-Trace-Id', ...)) e mostre na tela de erro. O cliente passa a te mandar o código em vez de "deu erro às duas da tarde".

Níveis existem, use-os

Isso é o que faz seu log ficar pequeno de novo. Meu critério, sem cerimônia:

debug — investigação. Não vai pra produção (LOG_LEVEL=info corta).
info — fato de negócio relevante: "pedido pago", "nota emitida".
warning — deu ruim mas contornamos: API lenta, retry funcionou.
error — o usuário foi prejudicado. Isso deveria virar alerta.
critical — o sistema está fora.

Se tudo no seu projeto é info, você não tem níveis — tem um echo com data.

A pegadinha que dá multa

Essa não é sobre organização, é sobre risco:

// 💀 nunca
Log::info('Request recebido', $request->all());

Aí vai senha, token, número de cartão, CPF — em texto puro, num arquivo que a equipe toda lê, que vai pro backup e talvez pro Datadog. É incidente de segurança e é LGPD.

Logue IDs, não conteúdo. Se precisar do payload, filtre antes com $request->except(['password', 'card_number', 'cpf']).

Bônus: JSON e o próximo passo

Se você já joga log em Loki, CloudWatch ou Datadog, troque o formatter do canal por JsonFormatter. Cada linha vira um objeto pesquisável e aquele grep heroico dá lugar a uma query de verdade.

E se precisar carregar algo no contexto sem que apareça nos logs (um ID interno pra correlacionar com outro sistema), existe Context::addHidden().

Antes de você fechar a aba

Log bom não é log detalhado. É log que responde uma pergunta.

Custa cinco segundos escrever um array em vez de uma string. Você recupera esse tempo no primeiro incidente.

Idempotência: a palavra difícil que salva seu webhook

Denis Augusto — Mon, 17 Aug 2026 18:02:56 +0000

O cliente pagou uma vez. Seu sistema registrou duas.

Sexta-feira, seis da tarde. Chega a mensagem no suporte: "fui cobrado duas vezes".

Você abre o banco e é pior do que parecia. Não foi o gateway que cobrou duas vezes — foi o seu sistema que criou dois pagamentos, liberou dois créditos e mandou dois e-mails de confirmação. O cliente pagou uma única vez.

Você vai no log do webhook. Dois POST /webhooks/pagamento. Mesmo event_id. Intervalo de 40 segundos.

E aí cai a ficha: o gateway não errou. Ele reenviou. É o comportamento documentado dele. Quem errou foi seu código, que tratou o segundo envio como se fosse um pagamento novo.

Por que todo webhook é reenviado

Isso não é bug do provedor, é o desenho do sistema. Stripe, Mercado Pago, Asaas, PagSeguro — todos funcionam igual: eles te enviam o evento e esperam um 2xx. Se não vier 2xx em alguns segundos, eles tentam de novo. E de novo.

O detalhe cruel: seu processamento pode ter dado certo e a resposta não chegar. Timeout de 30 segundos porque você mandou e-mail dentro do request. Deploy no meio do caminho. Nginx devolvendo 502 depois do commit no banco.

Do lado do gateway, isso é indistinguível de falha. Então ele reenvia. E seu código roda tudo de novo.

O webhook que aceita tudo

public function handle(Request $request)
{
    // "chegou evento, então é pagamento novo" 🙃
    $pagamento = Pagamento::create([
        'pedido_id' => $request->input('data.pedido_id'),
        'valor'     => $request->input('data.valor'),
        'status'    => 'pago',
    ]);

    $pagamento->pedido->liberarAcesso();

    Mail::to($pagamento->pedido->cliente)->send(new PagamentoConfirmado($pagamento));

    return response()->json(['ok' => true]);
}

Funciona perfeitamente no teste. Funciona no primeiro envio real.

No reenvio, cria o segundo pagamento, libera acesso de novo e dispara o segundo e-mail. E como esse método é lento (e-mail dentro do request!), ele aumenta a chance de timeout — ou seja, aumenta a chance de reenvio. O código causa o próprio problema.

Idempotência em uma frase

A palavra assusta, o conceito é bobo: uma operação idempotente pode rodar dez vezes e o efeito é o mesmo de ter rodado uma.

É o botão de elevador. Você aperta o 5 uma vez ou quinze vezes com raiva — o elevador vai uma vez pro quinto andar.

Um DELETE /pedidos/10 é naturalmente idempotente: apagou uma vez, apagar de novo não muda nada. Um INSERT não é. E webhook quase sempre virou INSERT na sua mão.

O que você precisa é de uma forma de perguntar "eu já vi esse evento antes?" — e a resposta tem que ser confiável mesmo com dois requests chegando ao mesmo tempo.

A solução: deixe o banco decidir

Todo provedor manda um ID único no evento. É esse ID que você guarda.

Schema::create('webhook_events', function (Blueprint $table) {
    $table->id();
    $table->string('provider');
    $table->string('event_id');
    $table->timestamps();

    // o guarda de verdade mora aqui
    $table->unique(['provider', 'event_id']);
});

E o controller fica assim:

use Illuminate\Database\UniqueConstraintViolationException;

public function handle(Request $request)
{
    try {
        WebhookEvent::create([
            'provider' => 'gateway',
            'event_id' => $request->input('id'),
        ]);
    } catch (UniqueConstraintViolationException) {
        // já processamos esse evento. responde 200 pra ele parar de reenviar.
        return response()->noContent();
    }

    ProcessarPagamento::dispatch($request->input('id'), $request->all());

    return response()->noContent();
}

Três coisas mudaram, e cada uma resolve um problema diferente:

1. A checagem é um INSERT, não um SELECT. Essa é a parte que quase todo mundo erra. if (WebhookEvent::where('event_id', $id)->exists()) parece resolver, mas não resolve: dois requests simultâneos passam os dois pelo if antes de qualquer um inserir. O unique no banco é o único lugar onde essa disputa tem um vencedor só.

2. Reenvio devolve 200, não erro. Evento repetido não é falha — é o gateway fazendo o trabalho dele. Se você responder 500, ele reenvia mais ainda.

3. O trabalho pesado foi pra fila. O controller agora responde em milissegundos. Menos timeout, menos reenvio, e o e-mail que travava tudo saiu do caminho do request.

Como usar na prática

API pública sua: aceite um header Idempotency-Key do cliente e guarde na mesma tabela. Assim o app mobile pode repetir o POST /pedidos sem medo quando o 4G cair no meio.

Jobs na fila: job também repete. Se o worker morre depois do charge() e antes do save(), o retry cobra de novo. A mesma guarda vale ali dentro.

Importação de planilha: updateOrCreate com uma chave natural (CPF, código externo) em vez de create. Rodar a importação duas vezes deixa de duplicar a base.

A pegadinha: `ShouldBeUnique` não é idempotência

Vejo essa confusão direto. Marcar o job com ShouldBeUnique evita dois jobs iguais na fila ao mesmo tempo. Ele solta o lock quando o job termina.

Se o webhook chegar de novo cinco minutos depois — e vai — o job entra tranquilo e processa tudo outra vez. ShouldBeUnique é controle de concorrência, não memória de longo prazo. A tabela com unique é a memória.

Bônus: não confie no corpo do evento

Enquanto você está aí, uma segunda blindagem que custa pouco: valide a assinatura do webhook (todo provedor manda uma) e, para operações sensíveis, use o evento só como gatilho.

Em vez de confiar no valor que veio no payload, pegue o ID e consulte a API do gateway pra saber o estado real. Payload é aviso; a fonte da verdade é o provedor.

E confira se sua rota de webhook está fora do VerifyCsrfToken e do throttle agressivo — dá pra passar um bom tempo caçando um "webhook que não chega" que na verdade está tomando 419 ou 429.

Antes de você fechar a aba

Idempotência é uma daquelas coisas que ninguém implementa antes do primeiro incidente. E o primeiro incidente costuma envolver dinheiro do cliente.

O bom é que o custo de acertar é ridículo: uma tabela com dois campos, uma constraint unique e um try/catch. Vinte minutos hoje contra uma sexta-feira inteira depois.

Agora me conta: qual foi o seu evento duplicado? Cobrança em dobro, e-mail repetido, estoque baixado duas vezes? Eu já vi um webhook de nota fiscal emitir três notas pro mesmo pedido — e o contador descobriu antes do dev. 😅

O bug não existe: é o cache te enganando

Denis Augusto — Mon, 17 Aug 2026 18:02:53 +0000

"Mas eu já corrigi isso"

O cliente avisa que o preço do produto está errado no site. Você abre o banco: 89,90. Correto.

Abre a página: 129,90.

Você acha que enlouqueceu. Dá um dd() no controller — vem 89,90. Tira o dd(), recarrega: 129,90 de novo. Você começa a duvidar do navegador, do Nginx, da existência.

Aí você lembra daquele Cache::remember() que você mesmo escreveu três meses atrás. Com TTL de 24 horas.

O bug não existe. O cache está te mostrando um retrato de ontem — e defendendo esse retrato com unhas e dentes.

O `remember()` que todo mundo escreve

public function destaques()
{
    // resolvido! a home ficou 400ms mais rápida 🎉
    return Cache::remember('produtos.destaques', 3600 * 24, function () {
        return Produto::destaque()->with('categoria')->get();
    });
}

Essa linha é linda. Ela resolve o problema de performance de verdade, na hora, e o gráfico do APM agradece.

Só que ela responde metade da pergunta. Você definiu como guardar. Não definiu quando esquecer.

E o Produto::update() que roda no painel do admin não tem a menor ideia de que essa chave existe. Ninguém apresentou os dois.

Cache é cópia. E cópia envelhece.

Antes da solução, o jeito certo de pensar: cache não é uma otimização mágica, é uma segunda fonte de verdade que você acabou de criar no seu sistema.

Toda vez que você guarda algo em cache, você assume um compromisso: manter duas coisas sincronizadas. O banco e a cópia.

Só existem três jeitos de honrar esse compromisso. Todo cache decente usa um deles.

Estratégia 1: quem escreve, esquece

A mais direta. Quando o dado muda, mata a chave. Um Observer resolve isso sem espalhar Cache::forget() pelo projeto inteiro:

class ProdutoObserver
{
    public function saved(Produto $produto): void
    {
        Cache::forget('produtos.destaques');
        Cache::forget("produto:{$produto->id}");
    }

    public function deleted(Produto $produto): void
    {
        $this->saved($produto);
    }
}

Funciona bem e é fácil de ler. O ponto fraco aparece com o tempo: cada chave nova que você criar precisa entrar nessa lista. Esquecer uma é o bug do começo do post voltando.

Estratégia 2: chave que se aposenta sozinha

Aqui vem o truque que eu mais gosto, porque não precisa invalidar nada: coloque a versão do dado dentro da chave.

public function fichaTecnica(Produto $produto): array
{
    // updated_at muda no save → a chave muda → o valor velho vira órfão
    $chave = "produto:{$produto->id}:ficha:{$produto->updated_at->timestamp}";

    return Cache::remember($chave, 3600 * 24, function () use ($produto) {
        return $produto->montarFichaTecnica(); // aquele cálculo caro
    });
}

Salvou o produto? O updated_at mudou, a chave mudou, o valor antigo simplesmente nunca mais é pedido e expira sozinho.

Não tem forget(), não tem Observer, não tem lista pra manter. E funciona no driver file, no database, em qualquer um.

O custo é lixo acumulado no cache até o TTL vencer. Em troca você ganha algo raro: é impossível esquecer de invalidar.

Estratégia 3: tags, quando é um grupo inteiro

Quando um único evento invalida vários caches de uma vez, tag é o caminho:

Cache::tags(['produtos', "categoria:{$produto->categoria_id}"])
    ->remember($chave, 3600, fn () => $produto->relacionados());

// depois, quando a categoria muda de nome:
Cache::tags(["categoria:{$id}"])->flush();

Detalhe importante: tags só funcionam em Redis e Memcached. Se seu CACHE_STORE é file ou database, isso estoura na sua cara. É provavelmente o motivo número um de "funciona local, quebra em produção" (ou o contrário) quando o assunto é cache.

A pegadinha: o cache que mente no teste

Essa merece atenção porque é traiçoeira.

No phpunit.xml, o CACHE_STORE normalmente é array — um cache que morre no fim de cada teste. Ótimo pra isolamento, péssimo pra confiança: o teste passa mesmo quando sua invalidação está errada, porque o cache nunca sobrevive o suficiente pra servir dado velho.

Se o cache faz parte da regra de negócio, teste a invalidação de propósito:

it('esquece o cache dos destaques quando um produto muda', function () {
    Cache::put('produtos.destaques', collect(['velho']), 3600);

    Produto::factory()->create()->update(['nome' => 'novo']);

    expect(Cache::has('produtos.destaques'))->toBeFalse();
});

E o parente confuso: php artisan config:cache não tem relação nenhuma com Cache:: — é outro assunto, outro arquivo, outra dor (essa eu já contei em outro post 😄).

Bônus: o dado velho que serve pra caramba

Às vezes o problema não é dado desatualizado, é o oposto: a chave expira, chegam 300 requests ao mesmo tempo e todos vão bater no banco pra recalcular a mesma coisa. É o famoso cache stampede.

O Laravel tem uma resposta pronta:

// fresquinho por 5 min; até 30 min serve o valor velho e recalcula em background
Cache::flexible('relatorio.vendas', [300, 1800], fn () => $this->calcular());

Um request só paga o preço do recálculo. Os outros recebem o valor um pouco velho na hora, em vez de ficarem na fila do banco. Pra dashboard e relatório, isso é troca boa demais pra ignorar.

Antes de você fechar a aba

Antes de escrever Cache::remember(), responda uma pergunta: quem apaga isso, e quando?

Se você não sabe, não é cache — é um bug com data marcada. Pode ser Observer, pode ser chave versionada, pode ser TTL curto porque o dado suporta ficar dois minutos velho. Qualquer resposta serve. A ausência de resposta é que custa caro.

E me conta uma coisa: quanto tempo você já perdeu caçando um bug que era só cache? Eu já passei uma tarde inteira num "erro de cálculo" que era um Cache::remember de 24h que eu mesmo tinha escrito na semana anterior. 🙃

Pare de chamar variável de $data, $info e $temp

Denis Augusto — Tue, 11 Aug 2026 18:05:23 +0000

Você abre o arquivo e encontra $data. De novo.

Sabe aquele método que você precisa ler três vezes? Não porque a lógica é difícil — a lógica é boba. É porque toda variável se chama a mesma coisa com sufixo diferente.

$data. $data2. $dataFinal. $result. $temp. $aux. $arr.

Você lê a linha 40 e precisa subir até a linha 12 pra lembrar o que tem dentro de $result. Aí desce, lê mais três linhas, e esquece de novo.

O código não tá complexo. Ele tá anônimo. E anonimato custa memória de trabalho, que é justamente o recurso mais escasso de quem lê código.

O crime na cena

public function processar(array $data): array
{
    $result = [];
    $temp = 0;

    foreach ($data as $item) {
        $d = $item['discount'] ?? 0;
        $v = $item['price'] * $item['qty'];
        $t = $v - ($v * $d / 100);

        $temp += $t;

        $result[] = [
            'name' => $item['name'],
            'total' => $t,
        ];
    }

    $info = ['items' => $result, 'sum' => $temp];

    return $info;
}

Cinco letras soltas ($d, $v, $t) e três nomes genéricos ($data, $result, $temp, $info) num método de quinze linhas. Pra entender que $t é o total do item com desconto aplicado, você precisa executar o código na cabeça.

E o pior detalhe: $data aqui não é data (calendário) nem dado específico. É "coisas". É o equivalente a nomear uma pasta de "arquivos".

O mesmo método, com nome nas coisas

public function calcularCarrinho(array $itensDoCarrinho): array
{
    $itensCalculados = [];
    $totalDoCarrinho = 0;

    foreach ($itensDoCarrinho as $item) {
        $percentualDesconto = $item['discount'] ?? 0;
        $subtotal = $item['price'] * $item['qty'];
        $totalDoItem = $subtotal - ($subtotal * $percentualDesconto / 100);

        $totalDoCarrinho += $totalDoItem;

        $itensCalculados[] = [
            'name' => $item['name'],
            'total' => $totalDoItem,
        ];
    }

    return [
        'items' => $itensCalculados,
        'sum' => $totalDoCarrinho,
    ];
}

Mesma lógica. Zero comentário adicionado. E agora dá pra ler de cima pra baixo sem parar pra decifrar nada.

Repara que eu também matei o $info do final. Ele existia só pra guardar o retorno por uma linha — variável que só serve de escada pro return geralmente pode sumir.

Sete regras que resolvem 90% dos casos

1. O nome diz o conteúdo, não o tipo. $usuariosArray não ajuda — o PHP já sabe que é array. $usuariosInadimplentes ajuda.

2. Booleano começa com verbo de estado. $ativo é ambíguo (é o objeto ativo? é a flag?). $estaAtivo, $temEstoque, $podeEditar se leem como pergunta com resposta sim/não.

3. Coleção no plural, item no singular. foreach ($pedidos as $pedido). Parece óbvio, mas foreach ($pedido as $p) aparece muito.

4. Abreviação só se for universal. $id, $url, $html tudo bem. $qtdItPed não é economia, é criptografia.

5. Nome curto pra vida curta. Numa closure de uma linha, fn ($u) => $u->email é perfeitamente legível. Numa variável que vive quarenta linhas, o nome precisa se sustentar sozinho.

6. Use a palavra que o negócio usa. Se o pessoal do financeiro fala "inadimplente", a variável se chama $clientesInadimplentes — não $clientesComProblema. Isso encurta reunião.

7. Não nomeie pelo "como", nomeie pelo "o quê". $listaOrdenadaPorDataDesc envelhece na primeira mudança de ordenação. $ultimosPedidos sobrevive.

O nome que mente: pior que o nome ruim

$temp é preguiça, mas pelo menos é honesto: avisa que não vai te ajudar.

O problema sério é o nome que promete uma coisa e faz outra:

// diz que só busca. na verdade cria se não existir e ainda dispara e-mail. 😬
public function getUsuario(string $email): User
{
    $usuario = User::firstOrCreate(['email' => $email]);

    Mail::to($usuario)->send(new BoasVindas());

    return $usuario;
}

Quem lê getUsuario() numa outra classe acha que é operação inofensiva de leitura. Chama dentro de um loop pra montar um relatório. E manda quatrocentos e-mails de boas-vindas pra base inteira.

Com $total acontece a mesma coisa: quem lê assume "valor final". Se aquele $total é antes do frete e do imposto, o nome certo é $subtotal. Um dia alguém vai somar duas vezes.

Nome ruim atrasa a leitura. Nome mentiroso causa bug.

A pegadinha: português, inglês ou os dois?

Aqui vem a parte que sempre gera discussão — e é discussão legítima.

Meu jeito: estrutura do framework em inglês, domínio na língua do negócio. Então public function store(), $request, User::create() ficam em inglês. Mas $clientesInadimplentes, NotaFiscal, calcularComissao() ficam em português, porque é assim que o time e o cliente falam.

O que eu evito com força é a mistura dentro do mesmo conceito: $userInadimplente, getClienteData(), NotaFiscalRepository::findByCliente(). Isso não é bilíngue, é confuso.

Se o time todo escreve em inglês e é consistente, ótimo, funciona também. O pecado mesmo é não ter combinado nada e cada arquivo seguir uma escola.

Bônus: quando o nome não sai

Aquele momento em que você fica cinco minutos travado tentando nomear um método é informação valiosa, não falta de vocabulário.

Se o nome honesto seria processarEValidarEEnviar(), o problema não é o nome. É que o método faz três coisas. Dificuldade de nomear quase sempre é sintoma de responsabilidade demais num lugar só.

Quebra em três, e os nomes aparecem sozinhos.

Antes de você fechar a aba

Nome de variável é o único tipo de documentação que nunca fica desatualizado, porque ele vive dentro do código. Comentário mente com o tempo. README envelhece. O nome, você é obrigado a manter.

E não custa nada. Não é refatoração de arquitetura, não precisa de aprovação, não entra em sprint. É F2 no editor e cinco segundos de atenção na hora de escrever.

Agora eu quero saber: qual o pior nome de variável que você já encontrou em produção? Aceito $xpto, $aux2, $naoMexeAqui e similares. Conta nos comentários que eu começo — já vi um $listaFinal2Corrigida em código rodando com cliente pagando. 😅

DDD no seu CRUD é canhão pra matar mosquito

Denis Augusto — Tue, 11 Aug 2026 18:01:57 +0000

Sete arquivos pra salvar um cadastro

Peguei um projeto uma vez pra fazer uma alteração pequena: adicionar o campo "telefone secundário" no cadastro de cliente. Coisa de dez minutos, né?

Uma hora e meia depois eu tinha mexido em: a entidade Cliente, o value object Telefone, o DTO de entrada, o mapper que traduz DTO pra entidade, a interface do repositório, a implementação Eloquent do repositório, o use case AtualizarClienteUseCase, e o request do controller.

Oito arquivos. Pra um campo de texto que vai direto pra uma coluna varchar.

O sistema não fazia nada de mirabolante com esse cliente. Cadastrava, listava, editava, apagava. Um CRUD. Mas estava vestido com o terno de um sistema bancário.

Já pegou um projeto assim? Ou — pergunta mais desconfortável — já escreveu um?

O que parece sofisticação e é só cerimônia

Olha o caminho que um POST /clientes percorria naquele projeto:

// 1. Controller recebe e converte pra DTO
$dto = new CriarClienteDTO(
    nome: $request->nome,
    email: $request->email,
    telefone: $request->telefone,
);

// 2. Use case recebe o DTO
$useCase->executar($dto);

// 3. Dentro do use case: DTO vira entidade de domínio
$cliente = new ClienteEntity(
    nome: new Nome($dto->nome),
    email: new Email($dto->email),
    telefone: new Telefone($dto->telefone),
);

// 4. Repositório recebe a entidade
$this->repositorio->salvar($cliente);

// 5. Dentro do repositório: entidade vira Model
$model = new ClienteModel();
$model->nome = $cliente->nome->valor();
$model->email = $cliente->email->valor();
$model->telefone = $cliente->telefone->valor();
$model->save();

// 6. E aí volta tudo, agora no sentido contrário 🙃

Cinco traduções do mesmo dado. Nome vira Nome, Nome vira string de novo, string vira coluna.

Agora a pergunta honesta: qual bug isso evitou? Qual regra de negócio ficou protegida? Nesse projeto, nenhuma. O ClienteEntity era um saco de propriedades sem nenhum comportamento — exatamente o que a gente acusa de "modelo anêmico", só que espalhado em quatro camadas.

DDD nunca foi sobre pastas

Aqui mora a confusão. A maior parte do que a galera chama de DDD é a parte tática: entidade, value object, agregado, repositório, use case. É a parte fácil de copiar, porque é estrutura de pasta.

Só que o DDD é sobre a parte estratégica: entender o negócio a fundo, conversar com quem trabalha nele, descobrir que "pedido" pro pessoal do estoque não é a mesma coisa que "pedido" pro financeiro, e desenhar fronteiras a partir disso. Linguagem ubíqua, contextos delimitados.

A estrutura de pastas é consequência disso. Não substituto.

Quando você copia só as pastas, o que sobra é o custo — mais arquivos, mais indireção, mais tempo pra qualquer mudança — sem o benefício, que seria um código que fala a língua do negócio.

A régua: complexidade de dado ou complexidade de regra?

A pergunta que eu faço hoje antes de montar qualquer camada:

Esse dado tem regra ou só tem formulário?

Se o fluxo é "recebe do form, valida formato, salva no banco, mostra numa listagem", isso é complexidade de dado. Laravel já resolve isso lindamente com Form Request, Eloquent e Resource. Adicionar camada aí só aumenta a distância entre você e o varchar.

Agora, se o fluxo é "recebe a solicitação, verifica se o cliente tem limite, calcula juros conforme a modalidade, aplica desconto de fidelidade, agenda a cobrança e emite o título" — aí é complexidade de regra. É aqui que separar as coisas te salva, porque a regra vive mais tempo que o framework e muda por motivos diferentes.

E o ponto que quase ninguém fala: os dois convivem no mesmo projeto. Não precisa escolher.

Como fica na prática

O CRUD continua CRUD. Sem culpa nenhuma:

class ClienteController extends Controller
{
    public function store(StoreClienteRequest $request)
    {
        $cliente = Cliente::create($request->validated());

        return new ClienteResource($cliente);
    }
}

Três linhas. Todo mundo entende, inclusive o dev que entrar no time semana que vem.

O que tem regra ganha uma Action: o caminho do meio que resolve 90% dos casos.

final class AprovarEmprestimo
{
    public function __invoke(Emprestimo $emprestimo, User $analista): void
    {
        // aqui mora a regra, isolada e testável, sem quatro camadas
    }
}

E as peças táticas você usa avulso, onde valem a pena. Value Object pra CPF e Dinheiro, Enum pra status, DTO na fronteira de integração. Não é pacote fechado — dá pra pegar só as ferramentas que resolvem o seu problema.

A pegadinha: "mas e quando o projeto crescer?"

Esse é o argumento que eu mais ouço. E ele tem um erro escondido: assume que refatorar depois é mais caro do que carregar a estrutura desde o começo.

Quase nunca é. Transformar um controller gordo em Action é trabalho de uma tarde, e você faz isso sabendo qual é a regra de verdade, porque o negócio já se revelou.

O contrário é que dói: desmontar uma arquitetura de quatro camadas que ninguém entende e que já espalhou tradução de dado por trinta arquivos. Aí é semana, não tarde.

E tem o custo que não aparece no gráfico: cada dev novo no time leva três semanas pra fazer o primeiro CRUD, porque precisa aprender o dialeto local antes de escrever a primeira linha.

Bônus: o teste do "conta pro estagiário"

Antes de adicionar uma camada, tenta explicar em voz alta pra alguém que acabou de chegar qual problema aquilo resolve.

Se a resposta sair como "é pra desacoplar do framework" ou "é boa prática", segura a onda. Não é justificativa, é slogan.

Se a resposta for "porque a regra de cálculo de comissão muda por estado e a gente precisa testar as 27 combinações sem tocar no banco" — aí sim. Isso é um problema concreto, e a camada tem endereço.

Antes de você fechar a aba

Não estou dizendo que DDD é ruim. Em domínio complexo de verdade, com regra de negócio que muda toda semana e gente do negócio discutindo termo por termo, ele é o que segura o sistema em pé.

O que eu tô dizendo é que arquitetura é resposta a um problema. Sem o problema, ela é só custo com aparência de sofisticação.

Cadastro de cliente não precisa de camada anticorrupção. Precisa de Cliente::create().

E aí, você já pegou (ou construiu) um projeto vestido pra uma complexidade que ele não tinha? Ou é do time que acha que camada nunca é demais? Vem discutir nos comentários — esse tema divide a comunidade ao meio e eu quero ouvir os dois lados. 🍿

Code review: como apontar o problema sem parecer babaca

Denis Augusto — Tue, 11 Aug 2026 18:01:56 +0000

O comentário tecnicamente correto que estraga o dia

Você abre o pull request e lá está:

"Isso tá errado."

Três palavras. Tecnicamente, pode até estar certíssimo. Mas o efeito na pessoa do outro lado é o mesmo de levar um empurrão no corredor.

E aí o PR trava. A pessoa responde defendendo a escolha. Você responde explicando melhor. Ela responde meio seca. Dois dias depois o código sai igual ao que ia sair, só que agora tem um clima estranho na daily.

Já viveu isso? De um lado ou do outro? Eu já vivi dos dois — e o lado de quem escreve o comentário ruim é mais fácil de estar do que a gente imagina.

O problema é o meio, não a maldade

Quase ninguém escreve comentário de review querendo ferir. O problema é estrutural.

Code review é texto, assíncrono e público. Não tem tom de voz, não tem cara, não tem o "risinho" que na mesa amaciaria a frase. E o time inteiro lê.

Quando falta tom, quem lê preenche sozinho. E a pessoa que acabou de passar seis horas naquele código, insegura sobre o resultado, vai preencher pro lado ruim. Sempre.

O mesmo comentário dito de pé, ao lado da mesa, com uma pausa e um "cara, olha só", passa liso. Escrito, vira julgamento.

Então não é sobre ser bonzinho. É sobre compensar o que o meio tira.

Sete coisas que mudaram meus reviews

1. Comente o código, não a pessoa

Trocar "você" por "esse método" muda tudo, e não custa nada:

❌ "Você esqueceu de tratar o retorno nulo aqui."
✅ "Esse retorno pode vir nulo quando o cliente não tem endereço — dá exception na linha de baixo."

Mesma informação. Só que a segunda fala do código, e a primeira aponta o dedo.

2. Diga o porquê e o impacto

Comentário sem motivo vira gosto pessoal — e ninguém aceita gosto pessoal de bom grado.

❌ "Não usa all() aqui."
✅ "Esse all() carrega a tabela inteira na memória. Em produção são uns 800 mil registros, o job vai estourar o limite. chunkById() resolve."

A segunda versão não precisa de autoridade nenhuma pra convencer. O argumento se defende sozinho, e a pessoa aprende algo em vez de só obedecer.

3. Separe o que bloqueia do que é preferência

Essa é a que mais melhora review em time, e é a mais fácil de adotar. Prefixo no comentário:

bloqueante: — não pode subir assim (bug, falha de segurança, quebra de contrato)
sugestão: — melhoraria, mas é decisão sua
nit: — implicância mínima, pode ignorar sem culpa
dúvida: — eu não entendi, me explica

Sem isso, todo comentário pesa igual. Quem recebe dez apontamentos não sabe se tem um problema sério ou dez preferências, e trata tudo como reprovação.

Com prefixo, "nit: acho que esse nome ficaria melhor no plural" é lido em dois segundos e resolvido em cinco.

4. Pergunta de verdade, não pergunta retórica

Existe uma diferença enorme entre curiosidade e ironia disfarçada de pergunta:

❌ "Tem certeza que isso funciona?"
❌ "Por que você fez desse jeito?"
✅ "Fiquei em dúvida no caso do cliente sem contrato ativo — esse where cobre isso? Posso ter perdido alguma coisa."

As duas primeiras são acusação com ponto de interrogação no fim. Todo mundo sente.

E tem um bônus real na terceira: às vezes quem não entendeu foi você. Manter a abertura de "posso ter perdido alguma coisa" já me salvou de várias sugestões erradas ditas com confiança demais.

5. Sugira o código, não só o problema

O GitHub e o GitLab têm bloco de sugestão. Usa. Escrever a alternativa custa trinta segundos e muda a natureza do comentário: em vez de tarefa, vira ajuda.

E força você a conferir se a sua ideia realmente funciona ali. Já desisti de uns bons comentários no meio da escrita da sugestão. 😅

6. Comente o que tá bom também

Não é bajulação nem "elogio sanduíche". É calibragem.

Se você só aparece pra apontar problema, seus comentários viram sinal de perigo — a pessoa vê seu nome na notificação e já se contrai. Um "esse teste do cenário de borda ficou ótimo, eu não tinha pensado nesse caso" custa dez segundos e muda como todo o resto é lido.

E tem um efeito colateral bom: elogiar o que você quer ver mais espalha padrão muito mais rápido do que criticar o que você não quer.

7. Passou de três idas e voltas, sai do texto

Se o mesmo ponto já teve três rodadas de comentário, o problema não é mais técnico. Ou vocês estão discutindo coisas diferentes, ou tem contexto que não cabe em caixa de texto.

Cinco minutos de call resolvem o que dez comentários não resolvem — e depois alguém registra no PR o que ficou combinado.

A pegadinha: review de gosto pessoal

Metade dos comentários azedos do mundo são sobre coisa que máquina deveria resolver.

Aspas simples ou duplas, quebra de linha, ordem dos imports, espaço antes da chave. Se isso aparece em review, o problema não é a pessoa — é que falta Pint (ou Pint + PHPStan) no pipeline.

Configura uma vez, o robô aponta, ninguém se ofende com robô. E aí o review humano fica livre pro que importa: regra de negócio, caso de borda, nome que não descreve o que faz, teste que não testa nada.

Regra que eu tento seguir: se um linter poderia ter dito, um humano não deveria dizer.

Do outro lado: recebendo review

Vale dizer, porque é mão dupla.

Todo comentário é sobre o código. Mesmo o mal escrito — quem escreveu provavelmente estava com pressa entre duas reuniões, não com raiva de você. Se um comentário te irritou, espera vinte minutos antes de responder. E se foi grosseiro mesmo, dá pra falar direto: "esse comentário soou meio seco, o que você quis dizer?". Quase sempre a resposta é "ih, desculpa, escrevi correndo".

E quando discordar, discorda com argumento. Review não é ordem, é conversa — quem revisa também erra.

Bônus: combinem uma página de regras

Meia hora de conversa e um documento de uma página resolvem 80% do atrito: o que é bloqueante de verdade, em quanto tempo se espera resposta num PR, tamanho máximo de PR (o maior favor que você faz pro revisor é o PR pequeno), quem pode aprovar e os prefixos de comentário.

Não é burocracia. É parar de negociar as mesmas coisas em todo PR.

Antes de você fechar a aba

Code review é o único momento em que o time inteiro conversa sobre código de verdade. É onde padrão se espalha, onde gente nova aprende rápido e onde bug morre barato.

E é também onde relação se desgasta silenciosamente, um comentário seco de cada vez, até alguém começar a aprovar tudo só pra evitar a conversa. Aí acabou o review — sobrou o carimbo.

Trinta segundos a mais escrevendo o comentário é o melhor investimento de tempo que existe no processo.

Agora conta: qual o comentário mais babaca que você já recebeu num PR? Ou — se tiver coragem, e eu tenho — qual foi o mais babaca que você já escreveu? Eu abro os trabalhos: já escrevi um "isso não faz sentido" às 19h de sexta e passei o fim de semana inteiro me arrependendo. 🙈

Você testou a API funcionando. E quando ela cair?

Denis Augusto — Tue, 04 Aug 2026 22:58:21 +0000

O caminho feliz sempre passa. O problema é o outro.

Sua integração com o gateway funciona. Você testou. O teste tá verde. Deploy feito, tá em produção há meses.

Aí, numa terça qualquer, o gateway devolve um erro 500. Instabilidade do lado deles.

E o seu app? Cospe uma tela branca com Undefined array key "transaction_id" na cara do cliente. Porque seu código pegou a resposta de erro e tentou ler o transaction_id que não existe ali.

Você testou a API funcionando. Nunca testou ela falhando. E é exatamente aí que mora o bug.

O teste que só conhece o dia bonito

Olha o teste típico de integração. Aposto que o seu se parece com esse:

public function test_processa_o_pagamento(): void
{
    Http::fake([
        'gateway.com/*' => Http::response([
            'status'         => 'aprovado',
            'transaction_id' => 'tx_123',
        ], 200),
    ]);

    $resultado = $this->service->cobrar($pedido);

    $this->assertTrue($resultado->aprovado);
}

Bonito. Verde. E completamente ingênuo.

Ele responde uma única pergunta: "quando dá tudo certo, meu código funciona?". Ótimo. Mas a produção não é só o dia bonito. A API vai devolver 500, vai dar timeout, vai responder um JSON estranho, vai ficar fora do ar. E você nunca escreveu uma linha testando o que acontece nesses casos.

O caminho feliz é o que menos quebra. O caminho de falha é onde o cliente vê tela branca.

O resgate: `Http::fake()` também simula desastre

Aqui tá a beleza de mockar a API — você não fica refém de esperar ela cair pra ver o que acontece. Você manda ela cair. Na hora que quiser, no teste que quiser.

public function test_gateway_fora_do_ar_nao_quebra_o_app(): void
{
    // simula o gateway devolvendo erro 500
    Http::fake([
        'gateway.com/*' => Http::response('Service Unavailable', 500),
    ]);

    $resultado = $this->service->cobrar($pedido);

    // seu código degrada com elegância, em vez de explodir?
    $this->assertFalse($resultado->aprovado);
    $this->assertEquals('gateway_indisponivel', $resultado->motivo);
    $this->assertEquals('pendente', $pedido->fresh()->status);
}

Esse teste vale ouro. Ele te obriga a responder: "quando o gateway cai, meu pedido fica num estado consistente ou vira lixo?". Se o teste passa, você sabe que o cliente vê uma mensagem decente e o pedido fica pendente pra retentar — não uma tela branca.

Os três desastres que você precisa testar

Não é só o erro 500. O mundo real tem sabores variados de falha:

// 1. Erro do servidor (a API respondeu, mas com pau)
Http::fake(['gateway.com/*' => Http::response('', 500)]);

// 2. Resposta inesperada (mudaram o contrato, ou veio corrompido)
Http::fake(['gateway.com/*' => Http::response(['algo' => 'diferente'], 200)]);

// 3. A API nem respondeu (timeout / fora do ar)
Http::fake(fn () => throw new ConnectionException('timeout'));

Cada um exercita um pedaço diferente do seu tratamento de erro. O 500 testa seu throw(). A resposta estranha testa se você valida o que recebeu antes de usar. A ConnectionException testa o que acontece quando a requisição nem chega — o cenário do post sobre timeout e retry, agora coberto por teste.

A pegadinha: caminho de falha sem tratamento não "passa", ele engana

Cuidado com uma armadilha sutil. Se seu código não trata o erro, esse teste de falha pode passar por engano — porque o Laravel lança a exceção e o teste morre com ela, ou o assert bate em cima de um estado que você nem pensou.

O teste de falha só tem valor se você escreveu o teste esperando um comportamento específico e digno: uma flag aprovado = false, um status pendente, uma exceção sua tratada. Se você não sabe o que seu código deveria fazer quando a API cai... esse é o verdadeiro bug, e o teste acabou de te mostrar.

Antes de você fechar a aba

O caminho feliz é o mínimo. Ele prova que seu código funciona no melhor dos mundos — que é justamente o mundo que menos acontece.

O teste que te salva de plantão às 2 da manhã é o do caminho de falha. Pega a sua integração externa mais crítica e se pergunta: "eu tenho um teste que simula essa API caindo?". Se a resposta é não, você já sabe qual teste escrever amanhã.

Me conta: você testa o caminho de falha das suas integrações, ou só o dia bonito? Sem julgamento — a maioria só testa o feliz. 👀

Seu teste bate na API de verdade? Um dia ela vai te trair

Denis Augusto — Tue, 04 Aug 2026 22:57:40 +0000

O teste quebrou. E não foi você.

Segunda de manhã, você abre o projeto e o CI tá vermelho.

Você não mexeu em nada desde sexta. Abre o log: o teste de integração com a API de pagamento falhou. Timeout.

O gateway deles teve uma instabilidade às 3 da manhã. Seu código tá perfeito. Mesmo assim, o build tá vermelho, o deploy travado, e agora você perde meia hora provando que o problema não é seu.

Já passou por isso? Teste que depende de API externa é assim: lento, instável e quebra por motivos que não são culpa sua. E tem o cenário pior — o teste que roda de verdade contra a API de pagamento, e a cada php artisan test você dispara 30 cobranças reais no sandbox até o gateway achar suspeito e bloquear.

O problema: seu teste não deveria conhecer a internet

Olha esse teste. Parece razoável, né?

public function test_busca_o_cep(): void
{
    // isso bate no ViaCEP de VERDADE, toda vez que o teste roda
    $endereco = $this->service->buscarCep('01001000');

    $this->assertEquals('São Paulo', $endereco['cidade']);
}

O que tem de errado? Tudo que importa num teste:

Lento — cada teste espera a ida e volta pela rede.
Instável — a API cair, ficar lenta ou mudar o retorno quebra seu teste sem seu código ter mudado.
Perigoso — se for uma API que cobra, envia e-mail ou cria pedido, você tá fazendo isso pra valer a cada execução.
Sem controle — como você testa "o que acontece quando a API devolve erro 500"? Não dá pra pedir pra ela cair na hora certa.

O teste devia verificar o seu código. Não a saúde do servidor dos outros.

A solução: `Http::fake()` intercepta tudo

Aqui vem o $pedido->restore() dessa história. Se você usa o HTTP Client do Laravel (Http::get(), Http::post()...), uma linha resolve:

use Illuminate\Support\Facades\Http;

public function test_busca_o_cep(): void
{
    // A partir daqui, NENHUMA requisição sai de verdade.
    // Você diz o que cada URL deve responder.
    Http::fake([
        'viacep.com.br/*' => Http::response([
            'localidade' => 'São Paulo',
            'uf'         => 'SP',
        ], 200),
    ]);

    $endereco = $this->service->buscarCep('01001000');

    $this->assertEquals('São Paulo', $endereco['cidade']);
}

Pronto. O Http::fake() intercepta a requisição e devolve a resposta que você mandou, sem tocar na internet. O teste roda offline, em milissegundos, e dá o mesmo resultado toda vez. Você virou dono do comportamento da API.

Como usar na prática

O fake() é flexível. Alguns cenários que você vai usar toda hora:

// Fingir QUALQUER requisição como 200 vazio (o mais simples)
Http::fake();

// Respostas diferentes por URL
Http::fake([
    'github.com/*'  => Http::response(['plano' => 'pro'], 200),
    'viacep.com.br/*' => Http::response('', 404), // simula CEP não achado
]);

// Simular a API fora do ar (erro 500) — o caminho que ninguém testa
Http::fake([
    'gateway.com/*' => Http::response('Erro interno', 500),
]);

Repara no último: agora você consegue testar o caminho de falha. "Se o gateway devolver 500, meu app mostra uma mensagem amigável ou explode na cara do usuário?" Sem fake(), você nunca teve como responder isso.

Não basta simular: confirme que você mandou certo

Aqui mora a pegadinha que separa o teste que testa do teste que só finge.

Simular a resposta não garante que você montou a requisição direito. Passou o header de autenticação? Mandou o valor no campo certo? O Http::assertSent() confere isso:

Http::fake();

$this->service->cobrar(valor: 150, cartao: 'tok_abc');

Http::assertSent(function (Request $request) {
    return $request->url() === 'https://gateway.com/charges'
        && $request->hasHeader('Authorization')
        && $request['amount'] === 150;
});

Agora o teste garante os dois lados: você mandou o que devia e reagiu certo à resposta.

Bônus: proíba requisições reais escaparem

Tem um detalhe traiçoeiro. Se você esquecer de fakear uma URL, a requisição sai de verdade — e você nem percebe que aquele teste ainda depende da internet.

O preventStrayRequests() fecha essa porta:

Http::preventStrayRequests();

Http::fake([
    'gateway.com/*' => Http::response('ok'),
]);

Http::get('https://gateway.com/charges'); // ok, tá fakeado
Http::get('https://outra-api.com');        // 💥 lança exceção na hora

Qualquer requisição sem fake correspondente estoura na hora, em vez de vazar silenciosamente pra rede. Coloca isso no setUp() da sua suíte de testes e durma tranquilo.

Antes de você fechar a aba

A regra de ouro: teste não conversa com o mundo lá fora. Ele verifica o seu código, de forma rápida e previsível. A conversa real com a API você deixa pra um teste de integração separado, que roda de vez em quando — não a cada commit.

Um detalhe importante: isso só funciona se você usa o HTTP Client do Laravel (Http::). Se ainda chama Guzzle ou cURL na mão, o fake() não te alcança — e migrar pro Http:: é justamente o próximo passo (spoiler: ele também te dá timeout e retry de graça, mas isso é papo pra outro post).

Me conta: você mocka suas APIs nos testes ou ainda reza pro sandbox ficar de pé? 👀

A API de terceiro caiu e derrubou seu app junto

Denis Augusto — Tue, 04 Aug 2026 22:56:07 +0000

A API deles caiu. Por que o SEU app caiu junto?

O fornecedor de frete teve um problema. A API deles ficou lenta — respondendo em 40 segundos em vez de 200 milissegundos.

Do lado deles, um incidente. Do seu lado? Caos.

Cada requisição que seu app fez pra calcular o frete ficou pendurada esperando. Os workers da fila entupiram. As conexões do PHP-FPM esgotaram. Em poucos minutos, seu app inteiro parou de responder — não só o checkout, tudo.

Um problema que era deles virou seu problema. E o pior: era evitável com três linhas.

O código que confia demais no mundo lá fora

Chamada de API é um ato de fé. Você pede algo pra um servidor que não é seu e espera que ele responda rápido, sempre, sem erro. Spoiler: ele não vai.

// Confiança cega: espera pra sempre, e reza pra dar certo
$response = Http::get('https://api-frete.com/cotacao', [
    'cep' => $cep,
]);

return $response->json();

O que tá faltando aqui?

Sem limite de espera. Se a API travar, sua requisição trava junto. Por padrão o HTTP Client espera até 30 segundos — uma eternidade quando isso acontece em cascata.
Sem tentar de novo. Uma falha de rede momentânea (acontece o tempo todo) já derruba a operação inteira.
Sem tratar erro. Se a API devolver 500, o $response->json() segue como se nada fosse, e você processa lixo achando que é cotação.

A blindagem: `timeout`, `retry` e `throw`

O HTTP Client do Laravel já traz o resgate embutido. Você encadeia e pronto:

$response = Http::timeout(5)   // desiste depois de 5s, não fica pendurado
    ->retry(3, 200)            // tenta 3x, esperando 200ms entre as tentativas
    ->get('https://api-frete.com/cotacao', ['cep' => $cep]);

$response->throw();            // erro 4xx/5xx? lança exceção, não segue com lixo

return $response->json();

Três métodos, três problemas resolvidos:

timeout(5) — se em 5 segundos não respondeu, o Laravel desiste e lança uma ConnectionException. Sua requisição não fica travada arrastando o app junto.
retry(3, 200) — falha de rede? Ele tenta de novo, até 3 vezes, com 200ms de intervalo. A instabilidade passageira some sozinha.
throw() — se depois de tudo a resposta for erro, ele lança exceção. Você trata de propósito, em vez de processar dado inválido silenciosamente.

Como usar na prática

Alguns ajustes que valem a pena conhecer:

// Separar timeout de conexão do timeout de resposta
Http::connectTimeout(3)->timeout(10)->get(/* ... */);

// Só relançar em erro de servidor, não em 404 esperado
$response->throwIf($response->serverError());

// Ou garantir que veio exatamente 200
$response->throwUnlessStatus(200);

connectTimeout é quanto você espera pra conectar (3s costuma bastar). timeout é o total até a resposta chegar. Separar os dois te dá controle fino: "conecta rápido, mas se conectou, dou mais um tempinho pra processar".

A pegadinha: retry cego pode cobrar o cartão duas vezes

Aqui mora o perigo que quase ninguém pensa. O retry é maravilhoso pra operações idempotentes — buscar uma cotação, consultar um CEP. Repetir não faz mal.

Mas e uma cobrança? Se a API processou o pagamento e a resposta se perdeu no caminho, o retry vai tentar de novo — e cobrar o cliente duas vezes. 😬

Pra esses casos, o retry aceita uma condição: só repete se for erro de conexão (a requisição nem chegou), nunca se o servidor já respondeu:

use Illuminate\Http\Client\ConnectionException;
use Illuminate\Http\Client\PendingRequest;

Http::retry(3, 200, function ($exception, PendingRequest $request) {
    // só tenta de novo se NEM CHEGOU no servidor
    return $exception instanceof ConnectionException;
})->post('https://gateway.com/charges', $dados);

A régua: repetir consulta, sempre. Repetir cobrança, só se tiver certeza de que nem chegou.

Bônus: e agora?

Trocar Guzzle na mão pelo Http:: do Laravel não é só sintaxe mais bonita. É timeout, retry, throw e — de brinde — a possibilidade de mockar tudo nos testes com Http::fake(), sem tocar na API real (isso rende um post inteiro à parte).

Se você tem uma integração externa crítica sem timeout, essa é sua lição de casa pra hoje. Uma API lenta lá fora não pode ser capaz de derrubar seu app aqui dentro.

Me conta: seu app já foi derrubado por uma API de terceiro? O que travou primeiro — a fila ou o FPM? 👀

DEV Community: Denis Augusto

Você criou uma tabela de tokens pra proteger PDF. O Laravel já fazia isso.

O contrato do cliente tá numa URL que qualquer um adivinha

O sistema que você não precisava construir

Como uma URL assinada funciona

Duas linhas, dois cenários

Como usar na prática

A pegadinha: assinatura não é autorização

Bônus: dois detalhes que economizam uma tarde

Antes de você fechar a aba

Seu log tem 40 mil linhas e nenhuma resposta

"Deu erro ao salvar, umas duas da tarde"

O problema não é a falta de log. É o excesso de log inútil.

Duas perguntas que todo log precisa responder

O trace_id: o fio que costura o request

Níveis existem, use-os

A pegadinha que dá multa

Bônus: JSON e o próximo passo

Antes de você fechar a aba

Middleware é porteiro, não gerente

Ele começou com um if. Hoje tem 80 linhas.

O middleware que virou gerente

Problema 1: middleware só existe no HTTP

Problema 2: cobrou antes de saber se deu certo

Problema 3: ele decide como responder

Problema 4: e-mail dentro do middleware

O que middleware faz bem

O mesmo código, cada coisa no lugar

A pegadinha: $request->user() vindo null

Bônus: e se for coisa pra depois da resposta?

Antes de você fechar a aba

Seu log tem 40 mil linhas e nenhuma resposta

"Deu erro ao salvar, umas duas da tarde"

O problema não é a falta de log. É o excesso de log inútil.

Duas perguntas que todo log precisa responder

O trace_id: o fio que costura o request

Níveis existem, use-os

A pegadinha que dá multa

Bônus: JSON e o próximo passo

Antes de você fechar a aba

Idempotência: a palavra difícil que salva seu webhook

O cliente pagou uma vez. Seu sistema registrou duas.

Por que todo webhook é reenviado

O webhook que aceita tudo

Idempotência em uma frase

A solução: deixe o banco decidir

Como usar na prática

A pegadinha: ShouldBeUnique não é idempotência

Bônus: não confie no corpo do evento

Antes de você fechar a aba

O bug não existe: é o cache te enganando

"Mas eu já corrigi isso"

O remember() que todo mundo escreve

Cache é cópia. E cópia envelhece.

Estratégia 1: quem escreve, esquece

Estratégia 2: chave que se aposenta sozinha

Estratégia 3: tags, quando é um grupo inteiro

A pegadinha: o cache que mente no teste

Bônus: o dado velho que serve pra caramba

Antes de você fechar a aba

Pare de chamar variável de $data, $info e $temp

Você abre o arquivo e encontra $data. De novo.

O crime na cena

O mesmo método, com nome nas coisas

Sete regras que resolvem 90% dos casos

O nome que mente: pior que o nome ruim

A pegadinha: português, inglês ou os dois?

Bônus: quando o nome não sai

Antes de você fechar a aba

DDD no seu CRUD é canhão pra matar mosquito

Sete arquivos pra salvar um cadastro

O que parece sofisticação e é só cerimônia

DDD nunca foi sobre pastas

A régua: complexidade de dado ou complexidade de regra?

Como fica na prática

A pegadinha: "mas e quando o projeto crescer?"

Bônus: o teste do "conta pro estagiário"

Antes de você fechar a aba

Code review: como apontar o problema sem parecer babaca

O comentário tecnicamente correto que estraga o dia

Ele começou com um `if`. Hoje tem 80 linhas.

A pegadinha: `$request->user()` vindo `null`

A pegadinha: `ShouldBeUnique` não é idempotência

O `remember()` que todo mundo escreve

O resgate: `Http::fake()` também simula desastre

A solução: `Http::fake()` intercepta tudo

A blindagem: `timeout`, `retry` e `throw`