/fastapi-user-manager

Avaliação técnica - Sankhya

Primary LanguagePython

Teste Prático: API de Gerenciamento de Usuários

Esta é uma API REST desenvolvida em Python com FastAPI para o gerenciamento de usuários.
O projeto foi estruturado utilizando princípios da Arquitetura Hexagonal (Ports and Adapters) para garantir um código limpo, desacoplado e de fácil manutenção.

Funcionalidades

  • Autenticação: Sistema de login seguro com tokens JWT
  • CRUD de Usuários: Criação, Leitura, Atualização e Deleção
  • Paginação: Listagem paginada para performance eficiente
  • Proteção de Rotas: Autenticação obrigatória em operações críticas
  • Documentação Automática: Swagger UI e ReDoc gerados automaticamente

Requisitos Técnicos Atendidos

  • Framework: FastAPI
  • Banco de Dados: SQLite
  • Arquitetura: Hexagonal (Ports and Adapters)
  • Autenticação: JWT (JSON Web Tokens)
  • Testes: Unitários na camada de serviço
  • Versionamento: Código organizado para publicação no GitHub

Instalação e Configuração

1. Pré-requisitos

  • Python 3.8 ou superior
  • Git

2. Clone o Repositório

git clone https://github.com/cssbreno/fastapi-user-manager.git
cd fastapi-user-manager

3. Crie e Ative um Ambiente Virtual

# Criação
python3 -m venv venv

# Ativação
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

Após ativar, você verá (venv) no início da linha do terminal.

4. Configure as Variáveis de Ambiente

IMPORTANTE: Este projeto requer configuração de variáveis de ambiente para funcionar corretamente.

# Copie o arquivo de exemplo
cp .env.example .env

# Gere uma chave secreta única
# Python (recomendado, pois já é um pré-requisito)
python -c "import secrets; print(secrets.token_hex(32))"

# Ou use o comando abaixo para gerar uma chave secreta única
# Windows:
powershell -Command "openssl rand -hex 32"
# Linux/Mac:
openssl rand -hex 32

# Copie a chave secreta gerada para o arquivo .env
echo "SECRET_KEY=sua_chave_secreta_aqui" >> .env

# Edite o arquivo .env com suas configurações (opcional)
nano .env  # ou use seu editor preferido

Configurações no .env:

  • SECRET_KEY: Chave secreta para JWT (obrigatória para produção)
  • ACCESS_TOKEN_EXPIRE_MINUTES: Tempo de expiração do token (padrão: 30 min)
  • DATABASE_URL: URL do banco de dados (padrão: SQLite local)
  • ALGORITHM: Algoritmo de criptografia JWT (padrão: HS256)

Exemplo de .env preenchido:

SECRET_KEY=sua_chave_secreta_gerada_aqui_com_64_caracteres
ACCESS_TOKEN_EXPIRE_MINUTES=30
DATABASE_URL=sqlite:///./database.db
ALGORITHM=HS256

Nota: O projeto funcionará com os valores padrão, mas é altamente recomendado configurar uma SECRET_KEY única em produção.

5. Instale as Dependências

pip install -r requirements.txt

Como Executar a Aplicação

Na raiz do projeto:

uvicorn src.main:app --reload
  • src.main:app: aponta para o objeto app em src/main.py
  • --reload: reinicia o servidor automaticamente a cada alteração

O servidor estará disponível em: http://127.0.0.1:8000

Como Usar a API (Documentação)

Fluxo de Uso Básico

Baixe o arquivo postman_requests.json pronto para importação no Postman ou siga os passos abaixo:

  1. Crie um usuário → POST /users/ (com username, email e password)
  2. Crie um token de acesso → POST /token (com email e password)
  3. Autentique-se → Clique em Authorize no Swagger e insira:
    • email: seu email (não username)
    • password: sua senha
    • Deixe client_id e client_secret em branco
  4. Acesse rotas protegidas → Endpoints como GET /users/me ou PUT /users/{user_id} estarão liberados com o token gerado.

Nota: O sistema usa email (não username) para autenticação, conforme implementado na API.

Exemplos de Uso com cURL (Postman)

1. Criar usuário:

curl -X POST "http://127.0.0.1:8000/users/" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "usuario_teste",
    "email": "teste@exemplo.com",
    "password": "senha123"
  }'

2. Obter token de acesso:

curl -X POST "http://127.0.0.1:8000/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=teste@exemplo.com&password=senha123"

Nota: O endpoint /token espera email e password como form data, não JSON.

3. Acessar rota protegida:

curl -X GET "http://127.0.0.1:8000/users/me" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"

4. Listar usuários:

curl -X GET "http://127.0.0.1:8000/users/" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"

5. Atualizar usuário:

curl -X PUT "http://127.0.0.1:8000/users/1" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "usuario_teste_atualizado",
    "email": "teste@exemplo.com",
    "password": "senha123"
  }'

6. Deletar usuário:

curl -X DELETE "http://127.0.0.1:8000/users/1" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"

Como Executar os Testes

Na raiz do projeto:

# Executar todos os testes
pytest

# Executar com mais detalhes
pytest -v

# Executar com cobertura de código
pytest --cov=src --cov-report=html

# Após executar, abra o relatório HTML:
# Abra o arquivo htmlcov/index.html no seu navegador

# Executar testes específicos
pytest tests/test_user_service.py -v

Cobertura Atual dos Testes:

  • ✅ UserService: Testes unitários completos com mocks
  • ✅ SQLiteUserRepository: Testes de persistência com mocks
  • ✅ Autenticação: Sistema JWT e hash de senhas testado
  • ✅ Configuração: Validação de variáveis de ambiente
  • ✅ Validação: Schemas e validações testados
  • ✅ Rotas da API: Endpoints testados com TestClient

Estrutura de Testes:

  • tests/test_user_service.py: Testes unitários da camada de serviço
  • tests/test_sqlite_repository.py: Testes do repositório de dados
  • tests/test_auth.py: Testes de autenticação e JWT
  • tests/test_config.py: Testes de configuração
  • tests/test_api_endpoints.py: Testes de integração dos endpoints da API

Tipos de Testes Implementados:

  • Testes Unitários: tests/test_user_service.py - Testa a lógica de negócio isoladamente
  • Testes de Repositório: tests/test_sqlite_repository.py - Testa a camada de persistência
  • Testes de Autenticação: tests/test_auth.py - Testa JWT, hash de senhas e validação de tokens
  • Testes de Configuração: tests/test_config.py - Testa carregamento de variáveis de ambiente
  • Testes de API: tests/test_api_endpoints.py - Testa os endpoints com TestClient
  • Mocks: Uso de unittest.mock para isolamento de dependências
  • Fixtures: Reutilização de dados de teste entre diferentes testes

Desenvolvimento

Estrutura do Projeto

fastapi-user-manager/
├── src/
│   ├── core/                    # Lógica de negócio (domínio)
│   │   ├── models.py           # Modelos de domínio (Pydantic)
│   │   ├── ports/              # Interfaces (contratos)
│   │   │   └── user_repository.py
│   │   └── services/           # Serviços de negócio
│   │       └── user_service.py
│   ├── infrastructure/          # Implementações concretas
│   │   ├── database/           # Camada de persistência
│   │   │   ├── models.py       # Modelos SQLAlchemy
│   │   │   ├── database.py     # Configuração do banco
│   │   │   └── sqlite_user_repository.py
│   │   └── web/                # Camada de apresentação
│   │       ├── api.py          # Controllers/rotas
│   │       ├── auth.py         # Autenticação JWT
│   │       ├── schemas.py      # Validação de entrada/saída
│   │       └── dependencies.py # Injeção de dependências
│   ├── config.py               # Configurações e variáveis de ambiente
│   └── main.py                 # Ponto de entrada da aplicação
├── tests/                      # Testes automatizados
│   ├── test_user_service.py   # Testes unitários
│   └── test_api_endpoints.py  # Testes de integração
├── requirements.txt            # Dependências Python
├── pytest.ini                 # Configuração do pytest
└── .env.example               # Exemplo de variáveis de ambiente

Arquitetura e Separação de Responsabilidades

Core (Domínio):

  • models.py: Entidades de negócio (User) usando Pydantic
  • ports/: Interfaces que definem contratos (UserRepository)
  • services/: Lógica de negócio (UserService)

Infrastructure (Implementação):

  • database/: Persistência de dados com SQLAlchemy
  • web/: API REST com FastAPI, autenticação e validação

Schemas vs Models:

  • core/models.py: Modelos de domínio para lógica de negócio
  • infrastructure/web/schemas.py: Schemas para validação de entrada/saída da API
  • infrastructure/database/models.py: Modelos SQLAlchemy para persistência

Adicionando Novos Testes

Para adicionar novos testes:

  1. Testes Unitários: Crie arquivos em tests/test_*.py
  2. Use Mocks: Para isolar dependências externas
  3. Fixtures: Para reutilizar dados de teste
  4. Cobertura: Execute pytest --cov=src --cov-report=html

Padrões de Código

  • Arquitetura Hexagonal: Separação clara entre domínio e infraestrutura
  • Dependency Injection: Uso de Depends() para injeção de dependências
  • Validação: Schemas Pydantic para entrada/saída da API
  • Tratamento de Erros: HTTP status codes apropriados
  • Separação de Modelos:
    • Modelos de domínio (core) para lógica de negócio
    • Schemas (web) para validação de API
    • Modelos de persistência (database) para SQLAlchemy

Troubleshooting

Problemas Comuns

1. Erro "Module not found":

# Certifique-se de estar no diretório raiz do projeto
cd fastapi-user-manager

# Ative o ambiente virtual
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate     # Windows

2. Erro de banco de dados:

# Verifique se o arquivo .env está configurado
cat .env

# Certifique-se de que o DATABASE_URL está correto

3. Erro de autenticação:

  • Verifique se SECRET_KEY está configurada no .env
  • Certifique-se de que o token não expirou
  • Use o endpoint /token para obter um novo token
  • IMPORTANTE: Use email (não username) para autenticação

4. Porta já em uso:

# Use uma porta diferente
uvicorn src.main:app --reload --port 8001