Desenvolvimento

Esta seção descreve o processo de desenvolvimento para a API de Gerenciamento de Carros, incluindo práticas recomendadas, ferramentas e workflows.

Ambiente de Desenvolvimento

Configuração Inicial

Para configurar seu ambiente de desenvolvimento:

Clone o repositório:

git clone <URL_DO_REPOSITORIO>
cd car_api

Instale as dependências:
```
poetry install
```
Ative o ambiente virtual:
```
poetry shell
```

Configure as variáveis de ambiente:

cp .env.example .env
# Edite .env com as configurações apropriadas

Execute as migrações do banco de dados:
```
alembic upgrade head
```

Execução em Desenvolvimento

Para executar a aplicação em modo de desenvolvimento com recarga automática:

poetry run fastapi dev car_api/app.py

Ou alternativamente:

poetry run uvicorn car_api.app:app --reload --host 0.0.0.0 --port 8000

Ferramentas de Desenvolvimento

FastAPI

O framework FastAPI é usado para criar a API REST. Algumas de suas funcionalidades importantes incluem:

Tipagem de dados: Utiliza Pydantic para validação e serialização
Documentação automática: Gera automaticamente documentação Swagger e ReDoc
Assincronicidade: Suporte nativo a funções assíncronas
Injeção de dependências: Sistema poderoso de injeção de dependências

SQLAlchemy

Utilizado como ORM (Object-Relational Mapping) para interação com o banco de dados:

Suporte a múltiplos bancos: SQLite, PostgreSQL, MySQL
Assincronicidade: Compatível com drivers assíncronos
Tipagem: Totalmente compatível com type hints do Python

Pydantic

Responsável pela validação de dados e serialização:

Validação automática: Validação baseada em type hints
Transformação de dados: Conversão automática entre tipos
Performance: Alta performance graças ao uso de Rust em alguns componentes

Ruff

Linter e formatador de código Python:

Alta velocidade: Muito mais rápido que outros linters
Integração com editor: Funciona com a maioria dos editores de texto
Compatibilidade: Compatível com flake8, isort, pydocstyle, e outros

Práticas de Desenvolvimento

Ciclo de Desenvolvimento

Planejamento: Defina os requisitos e escopo da funcionalidade
Criação de branch: Crie uma branch para a nova funcionalidade
Codificação: Implemente a funcionalidade seguindo os padrões do projeto
Testes: Escreva e execute testes para garantir qualidade
Formatação: Formate o código usando as ferramentas do projeto
Commit: Faça commits com mensagens claras e descritivas
Pull Request: Abra um PR para revisão de código
Revisão: Receba feedback e faça as alterações necessárias
Merge: Após aprovação, merge na branch principal

Padrões de Codificação

Siga os padrões estabelecidos no projeto:

PEP 8: Siga as convenções de estilo do Python
Tipagem: Use type hints sempre que possível
Nomenclatura: Use nomes descritivos para variáveis, funções e classes
Comentários: Comente decisões complexas ou não óbvias
Docstrings: Documente funções públicas com docstrings

Versionamento de Código

Git Flow: Use branches para features, releases e hotfixes
Commits semânticos: Siga o padrão de commits semânticos
Pull Requests: Sempre use PRs para revisão de código

Estrutura de Desenvolvimento

Adicionando Novas Funcionalidades

Para adicionar uma nova funcionalidade à API:

Modelo: Crie o modelo SQLAlchemy em car_api/models/
Schema: Defina os esquemas Pydantic em car_api/schemas/
Rota: Crie o endpoint em car_api/routers/
Testes: Escreva testes em tests/
Documentação: Atualize a documentação conforme necessário

Exemplo de Adição de Funcionalidade

Suponha que você queira adicionar um novo recurso para gerenciar categorias de carros:

Modelo (car_api/models/categories.py):

class Category(Base):
    __tablename__ = 'categories'

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(50), unique=True)
    description: Mapped[Optional[str]] = mapped_column(Text)

Schema (car_api/schemas/categories.py):

class CategorySchema(BaseModel):
    name: str
    description: Optional[str] = None

class CategoryPublicSchema(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    id: int
    name: str
    description: Optional[str] = None

Rota (car_api/routers/categories.py):

@router.post('/', response_model=CategoryPublicSchema)
async def create_category(
    category: CategorySchema,
    db: AsyncSession = Depends(get_session)
):
    db_category = Category(**category.model_dump())
    db.add(db_category)
    await db.commit()
    await db.refresh(db_category)
    return db_category

Ferramentas de Apoio

Debugging

Logs: Use logging apropriado para debugar problemas
FastAPI Debug Mode: Ative o modo debug para informações detalhadas
Pydantic Validation Errors: Leia cuidadosamente mensagens de erro de validação

Profiling

Para analisar o desempenho da aplicação:

# Instale ferramentas de profiling
poetry add py-spy --group dev

# Execute profiling
py-spy top --pid <PID_DA_APLICACAO>

Monitoramento

Considere implementar monitoramento para:

Métricas de desempenho: Tempo de resposta, throughput
Erros: Frequência e tipos de erros
Uso de recursos: CPU, memória, banco de dados

Melhorias de Desenvolvimento

Performance

Consulta eficiente: Use eager loading para evitar N+1 queries
Cache: Implemente cache para dados frequentemente acessados
Indexação: Adicione índices apropriados no banco de dados
Paginação: Sempre implemente paginação para endpoints de listagem

Segurança

Validação rigorosa: Valide todos os dados de entrada
Sanitização: Sanitize dados de saída quando apropriado
Atualizações: Mantenha dependências atualizadas
Auditoria: Implemente logging de ações críticas

Manutenibilidade

Código limpo: Escreva código legível e bem documentado
Testes: Mantenha cobertura de testes alta
Refatoração: Refatore código duplicado ou complexo
Documentação: Atualize documentação com mudanças de comportamento

Integração Contínua

O projeto pode ser configurado com CI/CD pipelines para:

Testes automatizados: Execução de testes em cada commit
Linting: Verificação de padrões de código
Build: Compilação e empacotamento da aplicação
Deploy: Implantação automatizada em ambientes de teste e produção

Dicas de Desenvolvimento

Produtividade

Atalhos de teclado: Aprenda atalhos do seu editor
Snippets: Use snippets para código repetido
Atalhos do terminal: Aprenda comandos úteis do terminal
Ambientes virtuais: Use Poetry para gerenciar dependências

Colaboração

Code reviews: Revise código de colegas e peça revisões
Comunicação: Comunique mudanças significativas à equipe
Documentação: Mantenha a documentação atualizada
Issues: Use issues para rastrear tarefas e bugs

Aprendizado Contínuo

Leitura: Mantenha-se atualizado com as últimas práticas
Experimentação: Teste novas bibliotecas e ferramentas
Feedback: Peça e forneça feedback construtivo
Comunidade: Participe de comunidades de desenvolvedores