Skip to content

Guidelines e Padrões

Este documento define os padrões e diretrizes de desenvolvimento para manter a consistência e qualidade do código na API de Gerenciamento de Carros.

Padrões de Codificação

Python

O projeto segue os padrões definidos pelo PEP 8, com algumas adaptações especificadas no arquivo pyproject.toml:

  • Tamanho de linha: Máximo de 79 caracteres por linha
  • Estilo de aspas: Aspas simples (' ') para strings
  • Nomenclatura:
  • Classes: PascalCase
  • Funções e variáveis: snake_case
  • Constantes: UPPER_CASE

Linting e Formatação

O projeto utiliza o Ruff para linting e formatação automática:

# Verificar problemas de estilo
poetry run ruff check

# Corrigir automaticamente problemas
poetry run ruff check --fix

# Formatar código
poetry run ruff format

Todos os commits devem passar pelas verificações do Ruff antes de serem aceitos.

Estrutura de Código

Organização de Pastas

car_api/
├── app.py              # Ponto de entrada da aplicação
├── core/               # Componentes centrais (configuração, segurança, banco de dados)
│   ├── settings.py     # Configurações da aplicação
│   ├── security.py     # Funções de segurança e autenticação
│   └── database.py     # Configuração do banco de dados
├── models/             # Modelos do SQLAlchemy
│   ├── base.py         # Classe base para modelos
│   ├── cars.py         # Modelos relacionados a carros
│   └── users.py        # Modelos relacionados a usuários
├── schemas/            # Esquemas Pydantic para validação
│   ├── cars.py         # Esquemas para carros
│   ├── users.py        # Esquemas para usuários
│   └── ...
├── routers/            # Rotas da API
│   ├── cars.py         # Rotas para carros
│   ├── users.py        # Rotas para usuários
│   └── ...
└── ...

Importações

Siga a ordem recomendada para importações:

  1. Bibliotecas padrão do Python
  2. Bibliotecas de terceiros
  3. Importações locais do projeto
# Exemplo
from datetime import datetime
from typing import Optional

from fastapi import APIRouter, Depends
from sqlalchemy.ext.asyncio import AsyncSession

from car_api.core.database import get_session
from car_api.models.cars import Car
from car_api.schemas.cars import CarSchema

Documentação de Código

Docstrings

Todas as funções públicas devem ter docstrings claras e descritivas, seguindo o formato Google:

def create_car(car: CarSchema, db: AsyncSession = Depends(get_session)):
    """
    Cria um novo carro no sistema.

    Args:
        car: Objeto contendo os dados do carro a ser criado
        db: Sessão do banco de dados

    Returns:
        Car: Objeto do carro criado

    Raises:
        HTTPException: Se o carro já existir ou dados forem inválidos
    """
    # Implementação aqui

Comentários

  • Use comentários para explicar decisões complexas ou não óbvias
  • Evite comentários óbvios que apenas repetem o código
  • Prefira nomes de variáveis e funções autoexplicativos

Padrões de API

Nomenclatura de Endpoints

  • Use substantivos no plural para coleções: /cars, /users, /brands
  • Use substantivos no singular para recursos individuais: /cars/{id}
  • Use hífens para endpoints compostos: /user-profile

Status HTTP

  • 200 OK: Requisição bem-sucedida para operações GET
  • 201 Created: Requisição bem-sucedida para operações POST
  • 204 No Content: Requisição bem-sucedida para operações DELETE
  • 400 Bad Request: Dados inválidos fornecidos pelo cliente
  • 401 Unauthorized: Autenticação necessária ou falhou
  • 403 Forbidden: Acesso negado mesmo após autenticação
  • 404 Not Found: Recurso não encontrado
  • 500 Internal Server Error: Erro do servidor

Respostas de Erro

As respostas de erro devem seguir o formato:

{
  "detail": "Mensagem descritiva do erro"
}

Padrões de Banco de Dados

Modelos SQLAlchemy

  • Use Mapped e mapped_column para tipagem
  • Defina constraints apropriadas (unique, nullable, etc.)
  • Use enums para campos com valores fixos
  • Adicione timestamps created_at e updated_at quando apropriado

Relacionamentos

  • Use relationship para definir relações entre modelos
  • Especifique back_populates para relações bidirecionais
  • Use lazy="select" ou lazy="joined" conforme necessário

Padrões de Segurança

Autenticação

  • Use JWT para autenticação baseada em tokens
  • Armazene senhas com hash usando Argon2
  • Proteja endpoints sensíveis com decoradores de autenticação

Autorização

  • Implemente verificação de propriedade para recursos (ex: somente o proprietário pode editar seu carro)
  • Use decorators para verificar permissões

Padrões de Testes

Estrutura de Testes

  • Coloque testes em diretório tests/
  • Nomeie arquivos de teste como test_*.py
  • Use pytest para execução de testes

Escrita de Testes

  • Escreva testes unitários para funções individuais
  • Escreva testes de integração para endpoints da API
  • Teste casos de sucesso e falha
  • Use fixtures para dados de teste

Controle de Versão

Commits

  • Use mensagens de commit claras e descritivas
  • Siga o padrão: <tipo>(<escopo>): <descrição>
  • Tipos comuns: feat, fix, docs, style, refactor, test, chore

Exemplos: - feat(cars): adiciona endpoint para criar carros - fix(auth): corrige validação de token expirado - docs(readme): atualiza instruções de instalação

Branches

  • Use main para código estável em produção
  • Use develop para desenvolvimento ativo
  • Crie branches com nomes descritivos: feature/nova-funcionalidade, bugfix/nome-do-bug

Qualidade de Código

Cobertura de Testes

  • Mantenha cobertura de testes acima de 80%
  • Teste caminhos críticos e casos de borda
  • Use ferramentas como coverage.py para medir cobertura

Revisões de Código

  • Realize revisões de código antes de fazer merge
  • Verifique conformidade com padrões
  • Verifique segurança e desempenho
  • Confirme que testes passam

Desempenho

Consultas ao Banco de Dados

  • Use eager loading para evitar problema N+1
  • Otimize consultas com filtros apropriados
  • Use paginação para coleções grandes

Cache

  • Considere implementar cache para dados frequentemente acessados
  • Use cache de nível de aplicação para dados estáticos

Boas Práticas

Tratamento de Erros

  • Use exceções específicas do FastAPI quando apropriado
  • Forneça mensagens de erro claras e úteis
  • Registre erros para fins de depuração (quando implementado)

Validação de Dados

  • Use Pydantic para validação de entrada
  • Implemente validadores personalizados quando necessário
  • Valide dados tanto na entrada quanto na saída

Tipagem

  • Use tipagem estática sempre que possível
  • Defina tipos claros para funções e variáveis
  • Use Union types para valores opcionais