Referência

Desempenho e comparação

Quanto o Trilha custa sobre a biblioteca padrão, como medir você mesmo, e como ele se posiciona frente a outras abordagens.

Metodologia#

O único número que faz sentido publicar é o custo do framework sobre a biblioteca padrão, que é a alternativa real em Go. Os benchmarks ficam em bench/ (módulo separado, para o Trilha continuar sem dependências) e medem, em processo (httptest, sem rede), o mesmo trabalho feito de dois jeitos: com o Trilha e com net/http + html/template puros.

git clone https://github.com/emersonjoe/trilha && cd trilha
make bench            # roda; make bench-results regrava bench/RESULTS.md

Cenários: página com layout e 20 itens (h × html/template), resposta JSON, arquivo estático (Public × http.FileServer), 200 rotas com parâmetro (ServeMux nos dois lados) e cadeia de 5 middlewares.

Resultados de referência#

Apple M2, Go 1.25, 2026-09-05 (mediana de 3 execuções; bench/RESULTS.md tem a saída completa). Valores por requisição.

Leitura honesta: o Trilha tem um custo fixo de ~3 µs e ~40 alocações por requisição, independente da rota. Ele paga por: id de requisição (aleatório), nonce da CSP, cabeçalhos de segurança, Ctx com mapa de valores, limite de corpo, medição e log estruturado de cada requisição (slog, que formata a linha mesmo descartada). Em um servidor real uma consulta ao banco custa de 100 µs a alguns ms, e a rede, mais; a diferença desaparece. Se um dia isso importar para você, o caminho é reduzir alocações no Ctx e tornar o log opcional por rota — e o benchmark está aí para provar o ganho.

Observabilidade#

A instrumentação só existe quando Observability.Metrics está configurado; desligada, é uma comparação de ponteiro. Ligada, a chave da série é montada num buffer de pilha e procurada como map[string(bytes)], forma que o compilador resolve sem alocar — por isso a contagem de alocações não muda.

O ciclo editar → ver do trilha dev fica em ~1,2 s no exemplo do blog (recompilação do Go) e ~30 ms para mudanças só em public/ (make reload mede na sua máquina).

Comparação de abordagem#

Sem números de terceiros: versões mudam, configurações diferem e cada projeto otimiza para coisas diferentes. O que dá para comparar com segurança é a abordagem. Confira sempre a documentação de cada um; nomes citados são marcas dos respectivos donos e não há afiliação.

Quando não usar o Trilha: apps que precisam de interface altamente interativa no cliente (editores, dashboards em tempo real com estado complexo) são melhor servidos por React/Next ou por um SPA; e projetos que já têm um roteador Go e templates maduros ganham pouco ao trocar. O Trilha brilha em apps de negócio renderizados no servidor, sites de conteúdo e APIs com painel, onde um binário sem dependências e convenções fortes pesam mais que interatividade fina.

Custo por feature para um agente#

Os números acima são o que o framework custa por requisição. Há um segundo custo, pago por quem escreve o app com uma ferramenta de IA: os tokens que um agente gasta descobrindo o que o projeto já tem, errando uma assinatura, rodando cinco verificações uma de cada vez. É isso que o bench/agent mede.

make bench-agent copia examples/blog ou examples/sso para um módulo próprio, roda um agente de código (claude -p, sem servidores MCP, plugins ou memória do usuário: só o que está dentro do projeto conta) em quatro tarefas fixas e decide passou ou não com um teste escondido:

Cada cenário roda três vezes; bench/agent/RESULTS.md mostra a mediana de tokens de entrada (novos e lidos do cache), de saída, rodadas, chamadas recusadas, tempo e custo, e quantas execuções passaram. A comparação é sempre Trilha antes contra Trilha depois — mesma tarefa, mesmo agente, mesmo modelo — nunca contra outro framework. make bench-agent-dry monta as fixtures e prova que os testes escondidos falham sem agente, sem gastar nada; o CI nunca roda o agente.