📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados em Especialização em Backend com Python e FastAPI. Recomendado revisar antes de começar.

🐍 API de Controle de Gastos com Python & FastAPI

v1.0 — FastAPI, Pydantic v2, SQLAlchemy 2.0 e Swagger OpenAPI Automático

Trilha de Especialização Pedagógica — Projeto 1 de 4

• ➡️ v1 (este): API RESTful Assíncrona · FastAPI · Pydantic v2 · SQLite
• v2: Autenticação OAuth2 com JWT & Hashing Passlib
• v3: Integração com Celery, Redis & Tarefas Assíncronas
• v4: Microsserviços com Docker, Pytest & Cobertura 100%

🎓 Nível Profissional Simulado: Desenvolvedor Python Júnior. FastAPI revolucionou o desenvolvimento backend em Python com sua velocidade extrema, validação automática baseada em Type Hints com Pydantic v2 e documentação Swagger gerada sem nenhum esforço manual.

—`

🎯 Objetivo & Escopo do Projeto

Construir uma API RESTful Assíncrona de Controle Financeiro em Python 3.12 + FastAPI, utilizando Pydantic v2 para validação estrita de esquemas e SQLAlchemy 2.0 para persistência de dados com documentação interativa em /docs.

—`

🧑‍💼 Fase 1 — Levantamento de Requisitos

O Briefing do Cliente (Equipe Financeira)

“Precisamos de uma API moderna em Python para registrar lançamentos de despesas. A API deve validar que nenhum valor seja negativo, que as datas sejam válidas e deve disponibilizar uma interface Swagger interativa para os desenvolvedores testarem os endpoints direto pelo navegador.”

Requisitos Funcionais (RF) e Não-Funcionais (RNF)

—`

📋 Fase 2 — Backlog & User Stories

—`

🌿 Fase 3 — Engenharia em Equipe (Git Flow & Setup)

# Branch da funcionalidade
git checkout -b feature/US01-fastapi-pydantic-crud

# Executar a API com Uvicorn em modo reload
uvicorn main:app --reload --port 8000

—`

🛠️ Fase 4 — Implementação Guiada (main.py)

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel, Field

app = FastAPI(title="Controle de Gastos API", version="1.0.0")

class GastoSchema(BaseModel):
    id: int | None = None
    descricao: str
    valor: float = Field(gt=0, description="O valor deve ser estritamente positivo")

banco_memoria = []

@app.post("/gastos", status_code=status.HTTP_201_CREATED)
def criar_gasto(gasto: GastoSchema):
    gasto.id = len(banco_memoria) + 1
    banco_memoria.append(gasto)
    return gasto

@app.get("/gastos")
def listar_gastos():
    return banco_memoria

—`

🚀 Como Executar no Laboratório

1. Abra o terminal na pasta deste projeto

No seu editor/IDE, abra a pasta deste projeto (File > Open Folder) ou navegue via terminal:

cd python_web_gastos_01_fastapi

2. Execute a aplicação e os testes

pip install -r requirements.txt
uvicorn app:app --reload
# ou python main.py

[!TIP] Dica para execução a partir da raiz do repositório: Se você abriu o repositório completo no VS Code, basta navegar até a pasta antes de executar: cd proj_aplicacoes_full_stack/projetos/python_web_gastos_01_fastapi`

🧭 Decisões de Arquitetura (ADRs)

• ADR 001: Adoção do FastAPI e Pydantic v2 para geração automática de contratos OpenAPI e validação estrita.

—`

🧪 Testes de Validação & Swagger

• Acesse http://localhost:8000/docs para validar o Swagger interativo gerado em tempo de execução.

—`

✅ Checkpoint Final

1. Endpoints RESTful respondendo no FastAPI.
2. Pydantic bloqueando valores <= 0 com código 422.