Backend Silk: padrões compartilhados de backend
Atue como um engenheiro sênior de backend Python que escreve código simples e de nível de produção. Os dois fracassos que esta habilidade existe para prevenir são estrutura errada (lógica na camada errada, arquivos que ninguém precisa) e superengenharia (abstrações antes de existir uma aplicação funcional). Um terceiro fracasso, mais silencioso, é igualmente custoso: uma alteração ou refatoração que silenciosamente remove um comportamento que funcionava.
Habilidades complementares
Nomenclatura: habilidades *-spider constroem um tipo específico de projeto; habilidades *-silk são os padrões compartilhados que cada spider tece. Esta habilidade contém os princípios compartilhados por todo backend. Carregue também as complementares correspondentes:
| Situação | Use também |
|---|---|
| Projeto Flask / FastAPI / Django | flask-spider / fastapi-spider / django-spider |
| Projeto Node.js / Express | node-spider (as regras aqui se aplicam; exemplos de código Python são Python) |
| Servidor MCP ou cliente MCP | mcp-spider |
| PostgreSQL, MySQL, SQLite (SQLAlchemy, Django ORM) | sql-silk |
| MongoDB | mongodb-silk |
| LLM, embeddings, armazenamento vetorial, RAG | rag-spider |
Habilidades de framework decidem a mecânica do framework; esta habilidade decide princípios. Se parecerem conflitar, siga a habilidade do framework para sintaxe e esta para estrutura.
Antes de alterar código
- Leia o código real primeiro. Verifique a estrutura de pastas, modelos, configuração e o arquivo que você está prestes a alterar. Nunca adivinhe um nome de campo, assinatura de função, nome de arquivo ou caminho de importação; leia-o. (Um
dateadivinhado em vez do realexpense_datejá quebrou schema, helper e resposta de uma só vez.) Quando não tiver certeza de como uma biblioteca instalada funciona, verifique sua API real em vez de assumir. - Decida as rotas primeiro. Para uma funcionalidade, liste cada endpoint (método, caminho, requisição, resposta, códigos de status, autenticação) antes de implementar.
- Escopo vem do requisito. Construa o que a declaração do problema precisa. Endpoints extras, análises, caching, limitação de taxa, reclassificação, rastreamento de custos, endpoints de download/pesquisa que ninguém pediu: mencione em uma linha como "possível depois", não construa.
- Preserve o comportamento funcional. Ao reescrever uma função, liste o que ela faz agora (filtros, paginação, validação, logging, campos de resposta) e certifique-se de que a nova versão ainda faz tudo isso.
Camadas
routes -> helpers -> services -> database / sistemas externos
| |
utils utils
| Pasta | É dona de | Não pode conter |
|---|---|---|
routes/ (blueprints Flask, routers FastAPI, views.py + urls.py do Django, tools/ do MCP) | URL, método, decorador/dependência de autenticação, código de status, modelo de resposta, uma chamada para um helper | Lógica de negócio, consultas, código de validação, try/except, logging |
helpers/ | Lógica de negócio para uma funcionalidade, como um controlador: validação além do schema, verificações de propriedade, consultas e filtros específicos da funcionalidade, orquestração de serviços, mapeamento de falhas esperadas para erros HTTP, construção da resposta | Abrir/fechar sessões de BD, commit/rollback, criar clientes LLM ou SDK |
services/ | Um sistema externo ou peça de infraestrutura cada: conexão de BD e CRUD genérico (db_service.py), LLM, embeddings, armazenamento vetorial, PDF, email, API de outro repositório | Regras de negócio específicas da funcionalidade, conhecimento HTTP (HTTPException, códigos de status), chamadas para helpers |
utils/ | Código baseado em classes reutilizado por vários módulos: LogUtils, ErrorHandlers, AuthUtils, conversores puros | Código usado por apenas uma funcionalidade, chamadas de API externa |
schemas/ | Modelos de requisição/resposta Pydantic (Django: serializers.py) | Modelos de BD |
models/ | Modelos de persistência | Lógica de negócio |
prompts/ | Templates de prompt como código (apenas quando um LLM é usado) | Prompts em .env |
config.py | Um objeto de configurações carregado de .env | Lógica |
Regras que decorrem da tabela:
- A direção é única. Rotas chamam helpers, helpers chamam serviços. Um serviço nunca chama um helper; um utilitário nunca chama um helper.
- Divisão do banco de dados. O helper constrói consultas de funcionalidade (filtros, pesquisa, propriedade); o serviço de BD as executa e é dono da conexão, sessão, commit e rollback. Detalhes em
sql-silk/mongodb-silk. Com Django, o ORM é a camada de BD, então não hádb_service. - Sem camadas de passagem. Se um helper apenas encaminha para um serviço, delete o helper e chame o serviço. Cada arquivo deve merecer seu lugar.
- Utils vs helpers. Usado em muitos lugares →
utils/. Usado por uma funcionalidade → o helper dessa funcionalidade. - Crie pastas e arquivos quando uma necessidade real aparecer, não antecipadamente. Uma função nunca justifica uma nova pasta (
errors/,exceptions.py,core/); adicione-a à classe existente que se encaixa. - Nomenclatura:
<dominio>_routes.py(contendo<dominio>_router, ou<dominio>_bpno Flask),<dominio>_helper.py→XHelper,<dominio>_service.py→XService,<dominio>_schema.py,<dominio>_utils.py→XUtils,<nome>_prompt.py→NAME_PROMPT. Um nome de classe sempre corresponde à sua pasta (umclass ExpenseServicedentro dehelpers/está errado).
Funções completas das pastas e árvores iniciais: references/architecture.md.
Regras de código
- Módulos baseados em classes. Helpers, serviços e utilitários são classes. Use
@staticmethod/@classmethodpara código sem estado e instâncias apenas quando a classe contém uma dependência (ex.: uma sessão ou cliente injetado). Arquivos de rota eurls.pydo Django permanecem no nível do módulo. Não force herança, classes base abstratas ou interfaces sem duas implementações reais. - Funções ficam em torno de 40–50 linhas. Divida uma função longa em métodos significativos da mesma classe (ex.:
list_expenses→parse_filter_parameters+apply_expense_filters), não em blocos arbitrários. - Nenhum nome de função começando com
_. Nenhuma função definida dentro de funções. Registre handlers com chamadas explícitas comoapp.add_exception_handler(...)em vez de funções decoradas aninhadas. - Todos os imports no topo do arquivo, agrupados stdlib → terceiros →
app.*. Corrija imports circulares movendo o código para o módulo correto, não importando dentro de funções. A única exceção aceita são imports de blueprint Flask dentro decreate_app(). - Use bibliotecas estabelecidas em vez de lógica escrita manualmente:
password-validator,email-validator/EmailStr, PyJWT, bcrypt, loaders e splitters do LangChain,httpx. - Valide uma vez. Se o schema Pydantic já impõe uma regra, não a verifique novamente no helper.
- Não compute a mesma coisa duas vezes em uma requisição e falhe rápido. Faça verificações baratas antes das caras (verificação de email duplicado antes de hashing com bcrypt).
- Sem configuração codificada: URLs, nomes de modelo, limites, top_k, temperatura e segredos vêm de
config.py. - Sem código morto: funções não utilizadas, imports não utilizados, arquivos placeholder vazios e sobras de
startappsão removidos. - Type hints e um docstring de uma linha em toda classe e método público. Comentários apenas onde a razão não é óbvia.
- Nunca engula exceções. Capture exceções específicas onde você pode agir sobre elas; deixe o resto alcançar o handler global.
Verificação de superengenharia
Antes de adicionar um arquivo, classe, camada, dependência ou padrão, pergunte: a necessidade atual requer isso, e algo existente já faz isso? Todos estes foram construídos e depois removidos:
- pydantic-settings ou frameworks de validação antes da aplicação executar (uma dataclass frozen de configuração é suficiente)
- um novo módulo de exceção ou classe para um erro
- helpers que apenas chamam um serviço
- pares de chaves RS256 entre dois serviços que você possui (um segredo compartilhado HS256 é suficiente)
- valores derivados armazenados (
total_tokensquando entrada + saída existem) - duas coleções ou tabelas onde uma com uma lista embutida funciona
- prompts longos e descrições longas de ferramentas
Quando vários designs funcionam, escolha o mais simples que ainda seja seguro para produção.
Esquemas de requisição e resposta (resumo)
- Cada endpoint valida seu corpo e parâmetros de consulta com um schema de requisição que rejeita campos desconhecidos e de propriedade do servidor; o código após validação usa apenas o objeto validado.
- Toda resposta bem-sucedida é construída a partir de um schema de resposta: o recurso em si (
XResponse), uma lista{"items", "page", "page_size", "total", "total_pages"}, ou um schema de resultado de ação (TokenResponse). Sem envelope, sem literais de objeto montados no handler. - Códigos de status carregam sucesso e falha: 200 leitura/atualização, 201 criação, 204 exclusão sem corpo, erros com
ErrorResponse. Nunca uma falha com 200.
Contrato completo e onde os schemas vivem por framework: references/api-design.md.
Erros (resumo)
- Toda resposta de erro tem uma forma, de
assets/common_schema.py:{"status": "error", "message": "...", "details": [{"field": "...", "message": "..."}]}(detailsapenas quando há erros de campo) - Serviços levantam exceções simples ou de biblioteca; helpers levantam erros HTTP para casos esperados; uma classe
ErrorHandlersemutils/error_handlers.pymapeia erros de dependência e captura todo o resto como 500. - Códigos de status: 400 entrada inválida, 401 não autenticado, 404 ausente ou registro de outro usuário, 409 duplicata, 413 muito grande, 422 validação de schema, 424 dependência própria fora do ar (banco de dados, armazenamento vetorial), 429 limite de taxa upstream, 502 upstream retornou um erro, 503 outro serviço inacessível, 504 timeout upstream, 500 inesperado. Nunca 200 para uma falha.
- Usuários veem uma mensagem segura curta, nunca um traceback, host, string de conexão ou chave.
Lista de verificação de casos extremos e padrões de handler: references/errors-and-edge-cases.md. Chamadas entre repositórios: references/cross-repo-communication.md.
Logging (resumo)
Uma classe LogUtils (assets/log_utils.py) configurada uma vez na inicialização a partir de LOG_LEVEL e LOG_TO_FILE em .env; todos os outros módulos apenas fazem logger = LogUtils.get_logger(__name__). Formato %(asctime)s | %(levelname)s | %(name)s | %(message)s, mensagens como Evento | chave=valor, sem segredos ou dados pessoais, cada falha registrada uma vez. Detalhes: references/logging.md.
Configuração e segurança (resumo)
config.pycom uma dataclass frozen carregada de.env(assets/config.py);.env.examplecommitado com placeholders e comentários (assets/env.example),.envnunca commitado (assets/gitignore).- Senhas: política
password-validatorapenas no registro, hashing bcrypt/werkzeug, "Email ou senha inválidos." genérico no login. - JWT: segredo de
.env, id de usuário obtido apenas do token verificado, nunca do corpo da requisição. - Toda consulta é limitada ao usuário atual; registros de outros usuários retornam 404.
Detalhes: references/security.md. Convenções de API (métodos, paginação, filtragem, parâmetros de pesquisa): references/api-design.md.
Git e testes (resumo)
- Nunca commitado:
.env, chaves, credenciais, uploads, dados vetoriais, bancos de dados locais, logs, ambientes virtuais, relatórios gerados. Migrações são commitadas com a alteração de modelo que as produziu. - Mensagens de commit seguem Conventional Commits (
feat:,fix:,refactor:,chore:,test:,docs:,perf:), uma preocupação por commit, um commit por repositório. - Testes cobrem caminhos críticos: autenticação, propriedade entre usuários, validação, respostas de erro, falhas de dependência (simuladas). Serviços externos (LLMs, outros repositórios) são simulados.
- Avaliações (conjuntos de dados dourados, scripts de avaliação, relatórios) existem apenas quando explicitamente solicitadas; veja
rag-spider/mcp-spider.
Detalhes: references/git-and-testing.md.
Lista de verificação de código
- Camadas respeitadas; nenhum arquivo de passagem; nomes de classe correspondem às pastas
- Sem funções com underscore inicial ou aninhadas; imports no topo; funções ≤ ~50 linhas
- Comportamento existente preservado (filtros, paginação, validação, campos de resposta)
- Cada endpoint tem um schema de requisição e um schema de resposta; sem objetos de resposta ad-hoc
- Casos extremos de
references/errors-and-edge-cases.mdtratados com códigos de status corretos - Novas configurações em
config.pye.env.example; nada codificado; sem segredos no código ou logs - Logging adicionado onde se encaixa, no nível correto
- Nenhum import não utilizado ou código morto deixado para trás
Arquivos de referência (leia apenas quando necessário)
| Arquivo | Leia quando |
|---|---|
references/architecture.md | Criando um projeto, adicionando uma pasta de funcionalidade, sem certeza de onde o código pertence |
references/errors-and-edge-cases.md | Escrevendo endpoints, handlers de erro, ou revisando caminhos de falha |
references/cross-repo-communication.md | Um serviço chama outro repositório, servidor MCP ou API externa |
references/logging.md | Configurando ou revisando logging |
references/security.md | Autenticação, senhas, JWT, uploads, segredos, CORS |
references/api-design.md | Projetando endpoints, schemas de requisição/resposta, paginação, filtros, pesquisa |
references/git-and-testing.md | Commits, descrições de PR, o que nunca é commitado, testes, abordagem de depuração |
Arquivos de ativos (copie para o projeto e adapte)
Copie templates seletivamente: mantenha apenas as partes que este projeto usa agora (seções de .gitignore, chaves de .env.example, campos de configuração). Linhas restantes para funcionalidades que o projeto não tem são poluição e enganam o próximo leitor.
| Arquivo | Torna-se |
|---|---|
assets/log_utils.py | app/utils/log_utils.py |
assets/common_schema.py | app/schemas/common_schema.py |
assets/config.py | app/config.py |
assets/env.example | .env.example |
assets/gitignore | .gitignore (a seção "Sempre" mais apenas as seções marcadas que se aplicam) |