ps-hero-fastapi-lib 0.1.0

Biblioteca do model de Heróis com banco de dados.

ps_hero_fastapi_lib

Lib de Cadastro de Equipes e Heróis desenvolvida com SQLModel. Aplicação de Cadastro de Equipes e Heróis desenvolvida com FastAPI e a lib implementada.

Explicando o código

API de exemplo para gerenciar Heróis usando FastAPI, SQLModel (SQLAlchemy + Pydantic), e o padrão MVC com Repository:

• Controller (Router) → recebe HTTP
• Service → regras de negócio
• Repository → acesso ao banco
• Model (SQLModel) → entidades e DTOs
• Database → criação do engine e sessão

---

✨ Principais recursos

• Estrutura limpa em camadas (Controller → Service → Repository → DB)
• SQLModel (tipagem forte + ORM)
• Injeção de dependência com Depends
• Tratamento de erros HTTP padronizado
• Pronto para trocar SQLite por PostgreSQL

---

📂 Estrutura do projeto

.
├── LICENSE
├── Makefile
├── README.md
├── app
│   ├── controller                   # Controller (Router)
│   │   ├── __init__.py
│   │   ├── generic.py
│   │   ├── hero.py
│   │   └── team.py
│   ├── main.py                      # inicialização da app e rotas
│   └── test
│       ├── __init__.py
│       └── test_controller.py
├── ps_hero_fastapi_lib
│   ├── __init__.py
│   ├── model                        # SQLModel: entidades e schemas (Create/Update/Public)
│   │   ├── __init__.py
│   │   ├── dto.py
│   │   └── models.py
│   ├── repository
│   │   ├── __init__.py
│   │   └── base.py                  # Acesso ao banco (CRUD)
│   ├── service
│   │   ├── __init__.py
│   │   └── base.py                  # Regras de negócio
│   ├── test
│   │   ├── __init__.py
│   │   └── test_models.py
│   └── util
│       ├── __init__.py
│       └── database.py              # Engine, sessão e inicialização do schema
├── requirements.txt
└── setup.py

---

🧰 Stack & Requisitos

• Python 3.10+
• FastAPI
• SQLModel
• Uvicorn

requirements.txt:

fastapi==0.114.2
uvicorn[standard]==0.30.6
SQLModel==0.0.22

Para PostgreSQL, adicione também: psycopg[binary]==3.*

---

⚙️ Configuração & Execução

1. Crie o ambiente e instale dependências:

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. (Opcional) Defina o banco via variável de ambiente:

• SQLite (padrão) – já funciona sem configurar nada.

• PostgreSQL:

  export DATABASE_URL="postgresql+psycopg://app:app@localhost:5432/appdb"
  

3. Rode a aplicação:

uvicorn app.main:app --reload

4. Acesse:

• Healthcheck: http://127.0.0.1:8000/
• Docs (Swagger): http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

---

🧱 Modelos (resumo)

• Hero (tabela): id, name, secret_name?, age?
• HeroCreate (entrada POST)
• HeroUpdate (entrada PATCH, campos opcionais)
• HeroPublic (saída nas respostas)

---

🔌 Endpoints (Heroes)

Base path: /heroes

Método	Rota	Body	Resposta	Descrição
POST	/	HeroCreate	HeroPublic	Cria um herói
GET	/	—	List[HeroPublic]	Lista heróis (offset/limit)
GET	/{hero_id}	—	HeroPublic	Busca por ID
PATCH	/{hero_id}	HeroUpdate	HeroPublic	Atualiza campos parciais
DELETE	/{hero_id}	—	204 No Content	Remove herói

---

🧪 Exemplos (cURL)

Criar:

curl -X POST http://127.0.0.1:8000/heroes/ \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","secret_name":"The Enchantress","age":28}'

Listar:

curl "http://127.0.0.1:8000/heroes/?offset=0&limit=100"

Buscar por ID:

curl http://127.0.0.1:8000/heroes/1

Atualizar (parcial):

curl -X PATCH http://127.0.0.1:8000/heroes/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada Lovelace"}'

Remover:

curl -X DELETE http://127.0.0.1:8000/heroes/1 -i

---

🧠 Como as camadas se conectam

HTTP (FastAPI)
   ↓
Controller (app/controllers/heroes.py)
   ↓
Service (app/services/hero_service.py)
   ↓
Repository (app/repositories/hero_repository.py)
   ↓
DB Session (app/database.py) + SQLModel (app/models.py)

• Controller: lida com requisições/respostas e validações de query/path; injeta dependências com Depends.
• Service: regras de negócio (ex.: checar nome duplicado).
• Repository: SQL puro via SQLModel/SQLAlchemy (CRUD).
• Database: engine, sessão e criação de schema.

Reference:

Documento Fast API : Documentação do FAST API.