Skill de Revisão de Design de API Go

Convenções de handler, erro e contexto para revisão automatizada - uma Skill de Agente em estilo de cookbook para auditar handlers HTTP e gRPC do Go 1.26 sem correções automáticas inseguras.

O que esta Skill Faz

Produz uma checklist de revisão estruturada para handlers: propagação de context, mapeamento de erros, códigos de status, validação de requisição, ordenação de middleware e formato de resposta - cada achado com referências de arquivo e linha.

Quando Invocar

• Antes de mesclar alterações de handler ou middleware
• Quando um agente rascunha um novo pacote REST
• Durante a revisão de design para superfícies de API públicas
• Ao padronizar respostas de erro entre serviços
• Após incidentes causados por timeouts ausentes ou códigos de status incorretos

Entradas

Saídas

• Checklist agrupada por: contexto, erros, validação, middleware, respostas
• Severidade: bloqueador / aviso / nit com referências arquivo:linha
• Snippets de sugestão de correção (aplicados pelo humano - sem merge automático)
• Comandos de verificação: go test ./pkg/..., golangci-lint run ./pkg/...

Guardrails

1. Propague r.Context() para todas as I/Os de saída - DB, cliente HTTP, gRPC.
2. Mapeie erros em uma única camada - handlers ou um pacote apierr dedicado, não ambos.
3. Nunca retorne 500 para falhas de validação do cliente - use 400/422 conforme a política da equipe.
4. Nunca registre e retorne strings de erro internas para clientes - use IDs opacos.
5. Não desabilite linters (errcheck, contextcheck) sem exceção de ADR.
6. ServeMux Stdlib no Go 1.22+ - verifique padrões cientes de método antes de sugerir migração para chi.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// Alvos de revisão (handler stdlib)
func getUser(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context() // deve fluir para store.GetUser(ctx, id)
    id := r.PathValue("id")
    if id == "" {
        writeError(w, apierr.BadRequest("id ausente"))
        return
    }
    u, err := store.GetUser(ctx, id)
    if err != nil {
        writeError(w, mapStoreErr(err))
        return
    }
    writeJSON(w, http.StatusOK, u)
}

# Verificação após correções da revisão
go test ./internal/api/...
golangci-lint run ./internal/api/...
go vet ./internal/api/...

Quando usar esta skill:

• O líder técnico precisa de uma revisão de handler consistente antes do deploy de sexta-feira
• O agente rascunhou handlers sem ler o ADR de erros da equipe
• O primeiro PR HTTP de um novo engenheiro precisa de feedback com guardrails

Exemplo de Trabalho

Passo 0 - Coletar entradas

go list ./internal/api/...
grep -r "ServeHTTP\|HandleFunc\|chi\|gin\." internal/api/

Passo 1 - Auditoria de contexto

Verifique se todas as chamadas de saída recebem ctx derivado de r.Context():

// RUIM: context.Background() no handler
user, err := repo.Find(context.Background(), id)
 
// BOM: contexto com escopo de requisição
user, err := repo.Find(r.Context(), id)

• Timeouts do servidor (ReadHeaderTimeout, WriteTimeout) cancelam r.Context() - o downstream deve respeitá-lo
• Veja Cadeias de Middleware e Contexto de Requisição

Passo 2 - Auditoria de mapeamento de erros

func mapStoreErr(err error) apierr.Response {
    if errors.Is(err, store.ErrNotFound) {
        return apierr.NotFound("usuário")
    }
    if errors.Is(err, store.ErrInvalid) {
        return apierr.BadRequest("id de usuário inválido")
    }
    return apierr.Internal("falha na busca de usuário") // opaco para o cliente
}

• Uma função de mapeamento por contexto delimitado
• gRPC: mapeie para codes.InvalidArgument, codes.NotFound - veja padrões grpc-Go nas seções irmãs

Passo 3 - Status e formato da resposta

Passo 4 - Verificar

go test ./internal/api/... -count=1
golangci-lint run ./internal/api/...

Mergulho Profundo

A ordenação de middleware afeta os achados da revisão.

Middleware de log e ID de requisição devem envolver a autenticação, que envolve os handlers de negócios.

A recuperação de pânico pertence à camada mais externa.

Agentes frequentemente inserem autenticação após handlers em rascunhos - sinalize como bloqueador.

A validação pertence à fronteira: parâmetros de caminho, query, corpo JSON.

Use encoding/json com decodificação estrita (DisallowUnknownFields) quando o ADR exigir.

Para chi/gin, confirme se a extração de parâmetros corresponde aos padrões de rota registrados.

Idempotência e métodos: GET e HEAD não devem mutar estado.

A política de POST para criar vs PUT para upsert deve corresponder ao OpenAPI.

O ServeMux do Go 1.22+ com padrões de método (GET /users/{id}) evita handlers acidentais para todos os métodos.

Armadilhas

• http.Error com err.Error() vaza detalhes de implementação e frequentemente usa status incorreto.
• context.WithTimeout aninhado sem defer cancel() - linters pegam alguns; revise manualmente.
• Escrever JSON após WriteHeader - o status é travado na primeira escrita; use um helper que define cabeçalhos uma vez.
• http.Client padrão não tem timeout - sinalize chamadas de saída de handlers usando http.DefaultClient.
• Parâmetros de URL do chi vs PathValue - APIs diferentes; a skill deve conhecer o roteador a partir das entradas.

Alternativas

FAQs

Relacionados

• Fundamentos de Skills de Agente - estrutura de SKILL.md
• Padrões de Servidores, Handlers e ServeMux HTTP - referência de roteamento
• Cadeias de Middleware e Contexto de Requisição - fluxo de contexto
• Validação de Entrada e Tratamento Seguro de HTML/JSON - validação de fronteira
• httptest para Testes de Integração de Handler - padrões de teste
• Melhores Práticas de Skills de Agente - regras para toda a equipe

Versões de Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).