Orientação da Base de Código
Como ler um repositório de serviço Python - estrutura de pastas, propriedade, convenções e o caminho mais rápido do clone à navegação confiante.
Receita
service/
├── src/billing/ # pacote da aplicação
├── tests/ # espelha o layout de src
├── alembic/ # migrações de DB (se SQLAlchemy)
├── pyproject.toml # deps, ruff, config do pytest
├── uv.lock # resolução reproduzível
├── docs/ # ADRs, onboarding, runbooks
└── .github/workflows/ # fonte da verdade de CIQuando usar isso:
- Primeira semana em uma nova equipe ou serviço
- Retornando após licença longa ou reorganização
- Planejando um refatoramento entre módulos
- Revisando um PR grande fora da sua área usual
Exemplo de Trabalho
# Script de sessão de orientação (30-60 min auto-guiado)
tree -L 2 src/ tests/
rg -l "router|Blueprint|urlpatterns" src/ # encontra pontos de entrada HTTP
cat pyproject.toml | rg "name|requires-python|scripts"
cat docs/adr/0001-*.md 2>/dev/null || ls docs/
gh api repos/:owner/:repo/contents/CODEOWNERS 2>/dev/null || cat CODEOWNERS
uv run pytest --collect-only -q | head # vê módulos de testeRastreie uma história de usuário:
- Encontre o manipulador de rota (
src/billing/api/routes/orders.py). - Siga a camada de serviço (
services/order_service.py). - Encontre o repositório/ORM (
repositories/order_repo.py). - Observe a migração que afeta a mesma tabela (
alembic/versions/).
O que isso demonstra:
- O layout
src/separa o pacote importável da raiz do repositório - A busca por palavras-chave do framework localiza a superfície HTTP rapidamente
- ADRs e CODEOWNERS respondem "quem decide" e "por quê"
- A coleta de testes mapeia módulos para contratos de comportamento
Mergulho Profundo
Como Funciona
- Layout
src- O pacote emsrc/<nome>/evita importações acidentais da raiz do repositório emPYTHONPATH. pyproject.toml- Manifesto único para metadados, dependências, configuração de ferramentas (ruff, pytest, mypy).- Testes espelham
src-tests/billing/api/test_orders.pymapeia parasrc/billing/api/orders.py. - Propriedade -
CODEOWNERSsolicita automaticamente especialistas de domínio em PRs.
O Que Ler Primeiro
| Artefato | Respostas |
|---|---|
| README | Comandos de Quickstart |
docs/onboarding.md | Armadilhas específicas da equipe |
| ADRs | Decisões de framework e esquema |
| Fluxo de CI | Portões de qualidade obrigatórios |
CONTRIBUTING.md | Regras de PR e commit |
Notas Python
# Descobre a versão do pacote e os pontos de entrada programaticamente
import importlib.metadata as m
m.version("billing")
# console_scripts de pyproject [project.scripts]Armadilhas
- Assumir Django quando é FastAPI - Padrões incorretos de middleware e configurações. Correção: ler ADR ou lista de frameworks em
pyproject. - Ignorar caminhos de monorepo - Editar cópia do serviço errado. Correção: confirmar URL remota e nome do diretório.
- Variáveis de ambiente não documentadas -
.env.exampledesatualizado. Correção: documentar o bug no primeiro chave ausente. - Ignorar testes como especificação - Testes mostram contratos reais melhor do que wikis desatualizadas. Correção: ler testes para o módulo que você está tocando.
- Leitura de diretório "big bang" - Esmagador. Correção: rastrear uma fatia vertical.
- Apenas conhecimento tribal - Colega indisponível mais tarde. Correção: capturar respostas em
docs/onboarding.md.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Wiki de diagrama de arquitetura | Apenas alto nível | Diagrama desatualizado em relação ao código |
pydeps / grafos de importação | Desembaraçar ciclos | Primeira hora no repositório |
| Busca de código IDE | Salto de símbolo | Ainda sem clone local |
| Tour de pareamento | Legado complexo | Escala de onboarding auto-atendida |
FAQs
Monorepo com múltiplos pacotes?
Ler README raiz para lista de pacotes; cd services/billing-api por serviço com seu próprio uv.lock.
Onde está a lógica de negócios?
Equipes usam a camada services/ ou o pacote de domínio - evite manipuladores de rota "gordos"; procure por class *Service.
Código gerado?
Verificar Makefile / scripts/generate - não editar manualmente a saída do cliente OpenAPI.
Flags de recursos?
Procurar settings ou inicialização do SDK do LaunchDarkly - flags escondem caminhos incompletos.
Biblioteca interna compartilhada?
Seguir submodule git ou libs/ do monorepo - observar processo de atualização de versão separado.
Pasta `scripts/` legado?
Pode ser pré-migração de src - README deve indicar status da migração; preferir src/ para novo código.
Quem é dono da infra/terraform?
CODEOWNERS em infra/ ou tag da equipe de plataforma no README.
Quão recentes são os ADRs?
Data no nome do arquivo - se mais antigo que 2 anos, verificar se ainda é verdade com um colega.
Layout de apps Django?
Cada apps/* é um contexto delimitado - começar em urls.py e models.py por app.
Encontrando tarefas Celery?
rg "@app.task" src/ ou lista de inclusão de celery.py.
Relacionados
- Checklist de Onboarding de Desenvolvedores - cronograma
- Guia de Convenções e Estilo - idiomatismos
- Layout src e Estrutura de Pacotes - arquitetura
- Registros de Decisão de Arquitetura - processo de ADR
Versões do Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.