🚀 API de Usuários - Clean Architecture

Uma API REST enterprise-grade para gerenciamento de usuários implementada usando Clean Architecture com Python, FastAPI e SQLAlchemy.

🏗️ Arquitetura

O projeto segue os princípios da Clean Architecture, organizando o código em camadas bem definidas:

src/
├── Domain/              # Camada de Domínio
│   ├── Entities/        # Entidades de negócio
│   ├── Value_objects/   # Objetos de valor
│   └── Repositories/    # Interfaces dos repositórios
├── Application/         # Camada de Aplicação  
│   ├── Commands/        # Comandos (operações de escrita)
│   ├── Queries/         # Consultas (operações de leitura)
│   └── Services/        # Serviços de aplicação
├── Infra/              # Camada de Infraestrutura
│   ├── ApplicationDbContext/  # Configuração do banco
│   ├── Mappers/         # Mapeadores entidade ↔ modelo
│   └── Services/        # Implementações dos repositórios
├── Interfaces/         # Camada de Interface
│   └── Api/            # Controllers e modelos da API
└── Shared/             # Componentes compartilhados

🚀 Funcionalidades

Funcionalidades de Negócio

• ✅ CRUD completo de usuários
• ✅ Validação de dados com Pydantic
• ✅ Value Objects para Email e Idade
• ✅ Padrão CQRS (Command Query Responsibility Segregation)
• ✅ Paginação inteligente para listagem
• ✅ Health checks detalhados

Segurança Enterprise 🔒

• ✅ Rate Limiting (proteção DDoS)
• ✅ Input Sanitization (SQL Injection/XSS)
• ✅ CORS configurado corretamente
• ✅ Security Headers automáticos
• ✅ Monitoramento Rollbar (opcional)
• ✅ Exception Handling em português

Arquitetura & Qualidade

• ✅ Clean Architecture (4 camadas)
• ✅ Domain-Driven Design (DDD)
• ✅ Documentação automática (Swagger/OpenAPI)
• ✅ Tratamento de erros padronizado
• ✅ Logging estruturado
• ✅ Suporte multi-database (SQLite/SQL Server)

📋 Pré-requisitos

• Python 3.11+
• pip

🛠️ Instalação

1. Clone o repositório:

git clone <url-do-repositorio>
cd "API - Python"

2. Crie um ambiente virtual:

python -m venv venv

3. Ative o ambiente virtual:

# Windows PowerShell (pode precisar ajustar a política de execução)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
.\venv\Scripts\Activate.ps1

# Windows Command Prompt
venv\Scripts\activate.bat

# Linux/Mac
source venv/bin/activate

4. Verifique se o ambiente está ativo:

# Você deve ver (venv) no início do prompt
python --version  # Deve mostrar a versão do Python do ambiente virtual

5. Instale as dependências:

pip install --upgrade pip
pip install -r requirements.txt

5. Configure o banco de dados:

   Para SQLite (padrão):

   # Nenhuma configuração necessária

   Para SQL Server:

   # Copie a configuração do SQL Server
   cp .env.sqlserver .env
   
   # Edite o .env com sua string de conexão
   # Teste a conexão
   python test_sql_server.py

   Personalizado:

   cp .env.example .env
   # Edite o arquivo .env conforme necessário

🏃‍♂️ Executando a aplicação

# Execute a partir da raiz do projeto
python -m src.main

# Ou usando uvicorn diretamente
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

A API estará disponível em:

• API: http://localhost:8000
• Documentação Swagger: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

📚 Endpoints da API

Usuários

Método	Endpoint	Descrição
GET	/	Health check básico
GET	/health	Health check detalhado
POST	/usuarios	Criar novo usuário
GET	/usuarios	Listar usuários (com paginação)
GET	/usuarios/{id}	Obter usuário por ID
GET	/usuarios/email/{email}	Obter usuário por email
PUT	/usuarios/{id}	Atualizar usuário
DELETE	/usuarios/{id}	Deletar usuário

Exemplo de Uso

Criar usuário:

curl -X POST "http://localhost:8000/usuarios" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "João Silva",
    "email": "joao@email.com",
    "idade": 30
  }'

Listar usuários:

curl "http://localhost:8000/usuarios?skip=0&limit=10"

🏗️ Estrutura da Entidade Usuario

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "nome": "João Silva",
  "email": "joao@email.com",
  "idade": 30,
  "is_adulto": true,
  "is_idoso": false
}

Validações

• Nome: Obrigatório, 1-200 caracteres
• Email: Obrigatório, formato válido, único
• Idade: Obrigatório, 0-150 anos

🧪 Testes

# Instalar dependências de teste
pip install pytest pytest-asyncio httpx

# Executar testes
pytest src/Tests/

🗃️ Banco de Dados

SQLite (Padrão)

Por padrão, a aplicação usa SQLite (usuarios.db) - não requer configuração adicional.

SQL Server

Para usar SQL Server, você tem duas opções:

Opção 1: String de Conexão (Recomendado)

1. Configure o arquivo .env:

SQL_SERVER_CONNECTION_STRING=Data Source=HOME\SQLEXPRESS;Integrated Security=True;Persist Security Info=False;Pooling=False;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=True;Application Name="API Usuarios";Command Timeout=30
SQL_SERVER_DATABASE_NAME=UsuariosDB

2. Ou copie o arquivo de exemplo:

cp .env.sqlserver .env

3. Teste a conexão:

python test_sql_server.py

Opção 2: URL SQLAlchemy Direta

DATABASE_URL=mssql+pyodbc://@HOME\SQLEXPRESS/UsuariosDB?driver=ODBC+Driver+17+for+SQL+Server&TrustServerCertificate=yes&Encrypt=yes

Outros Bancos

# PostgreSQL
DATABASE_URL=postgresql://user:password@localhost/dbname

# MySQL
DATABASE_URL=mysql://user:password@localhost/dbname

Pré-requisitos para SQL Server

• SQL Server Express instalado e rodando
• ODBC Driver 17 for SQL Server instalado
• Permissões para criar bancos de dados

🔧 Configurações

As configurações podem ser definidas via:

• Arquivo .env
• Variáveis de ambiente
• Valores padrão no código

Principais configurações:

• DATABASE_URL: URL de conexão do banco
• HOST / PORT: Host e porta do servidor
• CORS_ORIGINS: Origens permitidas para CORS

🤝 Contribuindo

1. Fork o projeto
2. Crie uma feature branch (git checkout -b feature/nova-feature)
3. Commit suas mudanças (git commit -am 'Adiciona nova feature')
4. Push para a branch (git push origin feature/nova-feature)
5. Abra um Pull Request

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

🧠 Conceitos Implementados

• Clean Architecture: Separação clara de responsabilidades
• Domain-Driven Design (DDD): Foco no domínio da aplicação
• CQRS: Separação entre comandos e consultas
• Value Objects: Objetos imutáveis com validação
• Repository Pattern: Abstração da camada de dados
• Dependency Injection: Inversão de controle
• SOLID Principles: Princípios de design orientado a objetos