Este guia auxilia revisores a garantir que mudanças no código da BrasilAPI mantenham os mais altos padrões de qualidade, confiabilidade e compatibilidade. A BrasilAPI é usada por milhares de desenvolvedores e empresas importantes, portanto cada mudança deve ser cuidadosamente avaliada.
A compatibilidade retroativa é NON-NEGOTIABLE. Qualquer quebra pode derrubar aplicações em produção.
Código sem documentação não deve ser mergeado, independente da qualidade técnica.
Mudanças que aumentem custos de infraestrutura devem ser recusadas ou otimizadas.
Vulnerabilidades não são aceitáveis. Melhor recusar o PR do que mergear código inseguro.
Verificações Obrigatórias:
- Endpoints existentes não foram removidos
- URLs de endpoints não foram modificadas
- Campos de resposta não foram removidos
- Campos de resposta não foram renomeados
- Tipos de dados de campos não foram alterados
- Códigos de status HTTP permanecem consistentes
- Formato de erros segue o padrão
ErrorMessage - Se há mudanças incompatíveis, nova versão foi criada (v2, v3)
Como Verificar:
# Compare respostas da API antes e depois
git diff main -- pages/api/
# Verifique testes E2E para mudanças em contratos
git diff main -- tests/Perguntas a Fazer:
- Esta mudança quebra aplicações existentes?
- Um cliente que usa a v1 continuará funcionando após o deploy?
- Novos campos são adições, não substituições?
Verificações Obrigatórias:
- Documentação OpenAPI foi atualizada em
/pages/docs/doc/ - Exemplos de requisição/resposta estão corretos e completos
- Novos endpoints têm documentação completa
- Mensagens de erro estão documentadas
- Campos novos têm descrição clara
- README.md foi atualizado se necessário
Como Verificar:
# Verifique se arquivos de documentação foram modificados
git diff main -- pages/docs/
# Valide JSON da documentação
cat pages/docs/doc/[endpoint].json | jq .Perguntas a Fazer:
- A documentação reflete exatamente o comportamento do código?
- Um desenvolvedor conseguiria usar este endpoint apenas lendo a doc?
- Exemplos estão funcionais e realistas?
Verificações Obrigatórias:
- Testes E2E foram criados ou atualizados
- Teste de CORS está presente e correto
- Casos de sucesso estão cobertos
- Casos de erro estão cobertos (404, 400, 500, etc.)
- Validações de entrada estão testadas
- Testes passam localmente e no CI
Como Verificar:
# Execute os testes
npm test
# Verifique cobertura de novos endpoints
git diff main -- tests/Perguntas a Fazer:
- Os testes garantem que o comportamento esperado é mantido?
- Edge cases foram considerados?
- Testes falhariam se o código estivesse errado?
Verificações Obrigatórias:
- Código segue o style guide (ESLint + Prettier)
- Não há código comentado ou console.logs esquecidos
- Nomes de variáveis/funções são claros e descritivos
- Código é DRY (Don't Repeat Yourself)
- Funções têm responsabilidade única
- Complexidade é apropriada (não over-engineering)
Como Verificar:
# Execute linting
npm run fix
# Revise diff manualmente
git diff mainPerguntas a Fazer:
- Este código é fácil de entender?
- Um desenvolvedor novo conseguiria dar manutenção?
- Há duplicação que deveria ser refatorada?
Verificações Obrigatórias:
- Não há loops desnecessários ou processamento pesado
- Cache é usado quando apropriado
- Chamadas a APIs externas são minimizadas
- Não há vazamento de memória (closures, event listeners)
- Queries são otimizadas
- Dependências novas são justificadas e leves
Como Verificar:
# Verifique dependências adicionadas
git diff main -- package.json
# Analise lógica de processamento
# Procure por loops aninhados, recursão sem limite, etc.Perguntas a Fazer:
- Esta mudança aumentará custos de infraestrutura?
- Há maneira mais eficiente de implementar isso?
- Cache poderia reduzir chamadas a APIs externas?
Verificações Obrigatórias:
- Inputs de usuário são validados
- Dados são sanitizados antes de processamento
- Não há credenciais ou secrets no código
- CORS está configurado corretamente (
*para APIs públicas) - Não há injeção SQL, XSS ou outras vulnerabilidades
- Rate limiting é considerado (se aplicável)
- Erros não expõem informações sensíveis
Como Verificar:
# Procure por secrets expostos
git diff main | grep -i "password\|token\|secret\|key"
# Verifique validação de inputs
grep -n "req.query\|req.body" pages/api/[endpoint]Perguntas a Fazer:
- Entrada maliciosa poderia quebrar o sistema?
- Dados sensíveis estão protegidos?
- Erros expõem detalhes de implementação?
Verificações Obrigatórias:
- Segue estrutura de diretórios do projeto
- Usa
next-connectpara endpoints - Serviços estão separados de endpoints
- Middleware está sendo reusado (ex: cors)
- Tratamento de erros é consistente
- Versionamento é apropriado (v1, v2, etc.)
Como Verificar:
# Verifique estrutura
tree pages/api/[novo-endpoint]
tree services/Perguntas a Fazer:
- Código segue os padrões existentes no projeto?
- Há reuso de componentes e serviços?
- Estrutura é intuitiva para outros desenvolvedores?
As seguintes situações devem resultar em rejeição imediata do PR:
-
Quebra de compatibilidade sem nova versão
- Remoção/renomeação de campos
- Mudança de tipos de dados
- Alteração de URLs
-
Documentação ausente ou desatualizada
- Novo endpoint sem documentação
- Mudanças não refletidas na documentação
-
Sem testes
- Código novo sem testes E2E
- Testes falhando
-
Vulnerabilidades de segurança
- Inputs não validados
- Secrets expostos
- SQL injection, XSS
-
Aumento significativo de custos
- Processamento pesado sem justificativa
- Dependências grandes desnecessárias
-
Código não segue padrões
- ESLint falhando
- Estrutura diferente do projeto
Situações que podem ser aprovadas após correções:
- Documentação incompleta → Solicitar complemento
- Testes insuficientes → Solicitar mais casos de teste
- Performance subótima → Sugerir otimizações
- Código complexo → Solicitar simplificação/refatoração
- Nomes ruins → Solicitar renomeação para melhor clareza
❌ Este campo foi removido, mas isso quebra compatibilidade com v1.
Por favor, mantenha o campo ou crie uma v2.
✅ Sugiro adicionar validação para o parâmetro `cep`:
if (!/^\d{8}$/.test(cep)) {
return res.status(400).json({ message: 'CEP inválido' });
}
💡 Esta query poderia ser otimizada usando cache:
const cached = await getCache(key);
if (cached) return cached;❌ "Isso está errado, refaça"
❌ "Não gostei"
❌ "Funciona, mas eu faria diferente"- Seja específico: Aponte exatamente o problema e sugira solução
- Seja construtivo: Critique o código, não a pessoa
- Seja educativo: Explique o "porquê", não apenas o "o que"
- Priorize: Separe crítico de nice-to-have
- Reconheça: Destaque pontos positivos também
Se é sua primeira vez revisando, pergunte-se:
- Eu entendi o que este código faz? Se não, peça esclarecimento.
- Eu conseguiria dar manutenção neste código? Se não, pode estar muito complexo.
- Este código pode quebrar algo? Procure por efeitos colaterais.
- Documentação está clara? Leia como se você fosse usar a API.
- Testes cobrem o essencial? Tente pensar em casos não cobertos.
Para cada PR, verifique rapidamente:
⚠️ CRÍTICO
└─ [ ] Compatibilidade de API mantida
└─ [ ] Documentação atualizada
└─ [ ] Testes passando
⚡ IMPORTANTE
└─ [ ] Código limpo e legível
└─ [ ] Performance aceitável
└─ [ ] Segurança validada
✨ NICE-TO-HAVE
└─ [ ] Comentários úteis
└─ [ ] Código otimizado
└─ [ ] Tratamento de edge cases
- Leia o PR description
- Entenda o objetivo
- Identifique arquivos modificados
- Procure red flags óbvios
- Verifique checklist obrigatória
- Analise lógica do código
- Teste localmente se necessário
- Valide documentação
- Liste problemas críticos (blocking)
- Liste sugestões (não-blocking)
- Destaque pontos positivos
- Seja claro sobre o que precisa ser mudado
- Aprovar: Tudo ok ou apenas sugestões menores
- Request Changes: Problemas que devem ser corrigidos
- Comment: Dúvidas ou discussões necessárias
Não tenha medo de pedir ajuda quando:
- Não entender o código ou tecnologia
- Não ter certeza se algo quebra compatibilidade
- Precisar de opinião sobre segurança
- Mudança impactar área que você não conhece
Mencione outros revisores: @fulano pode revisar a parte de segurança?
- Instruções Copilot - Padrões do projeto
- CONTRIBUTING.md - Guia de contribuição
- README.md - Visão geral do projeto
- OpenAPI Docs - Documentação da API
Lembre-se: Revisão de código é sobre manter qualidade e proteger usuários. Seja rigoroso, mas construtivo. Um PR recusado hoje evita bugs em produção amanhã. 🛡️
Obrigado por contribuir com a qualidade da BrasilAPI! 🇧🇷