Jak zbudować działający szkielet backendu FastAPI w kilka minut

Za każdym razem, gdy zaczynam nowy projekt FastAPI, utykam w dniu świstaka. Muszę ponownie ustawiać strukturę katalogów, łączyć bazę danych, pisać migracje, podpinać zmienne środowiskowe, budować Dockerfile i konfigurować lintery. Łatwo zmarnować cały wieczór na tej rutynie, zanim pojawi się pierwszy prawdziwy endpoint.

Oczywiście możesz skopiować strukturę z poprzedniego repozytorium. Ale zwykle ma ono mnóstwo starych obejść, niepotrzebnych zależności i przestarzałych bibliotek. Gotowe boilerplate'y ze stron z wynikami wyszukiwania również rzadko trafiają w punkt, ponieważ autor wybrał TortoiseORM, ale ty potrzebujesz SQLAlchemy 2.0, albo wcisnął ciężki Celery zamiast lekkich kolejek.

Repozytorium FastAPI-template autorstwa developera s3rius rozwiązuje ten problem inaczej. To nie jest statyczny szablon, ale elastyczny interaktywny generator projektów.

Konstruktor zamiast sztywnego szablonu

Projekt działa jak interaktywny kreator w terminalu. Uruchamiasz narzędzie przez pip, uv lub Docker, odpowiadasz na kilkanaście pytań i otrzymujesz gotowy codebase dostosowany do twoich potrzeb.

Główną zaletą generatora jest zmienność. Większość szablonów narzuca konkretny stack, ale tutaj sam składasz potrzebny zestaw komponentów.

Bazy danych i ORM do wyboru

Zamiast być przywiązanym do jednej biblioteki, narzędzie obsługuje kilka popularnych opcji obsługi danych:

• SQLAlchemy 2.0 z silnikiem async
• TortoiseORM z generowaniem migracji przez Aerich
• Piccolo ORM
• Ormar
• Beanie dla MongoDB
• Surowy sterownik psycopg bez ORM

Jeśli nie potrzebujesz w ogóle bazy danych, możesz wybrać opcję bez przechowywania danych. W takim przypadku kod nie będzie zawierał niepotrzebnych zależności i śmieciowych plików konfiguracyjnych.

REST czy GraphQL

Domyślnie generator buduje klasyczne REST API z automatyczną dokumentacją Swagger. Ale jeśli twój frontend woli pracować przez GraphQL, generator skonfiguruje wrapper oparty na bibliotece Strawberry. Nie musisz ręcznie konfigurować schematu i typów, żeby zacząć.

Zadania w tle i kolejki

Zamiast ciężkiego Celery, autor szablonu dodał integrację z Taskiq — nowoczesnym menedżerem zadań async dla Pythona. Idealnie wpisuje się w ogólną architekturę async FastAPI. Jako broker wiadomości możesz wybrać Redis, RabbitMQ lub Kafka podczas generowania.

Monitoring i logowanie out of the box

Szablon ma już wbudowane gotowe integracje, które zwykle musisz konfigurować ręcznie z osobnych artykułów:

• Zbieranie metryk dla Prometheus
• Śledzenie przez OpenTelemetry
• Wysyłanie błędów do Sentry
• Strukturalne logowanie przez Loguru

Wszystkie te opcje są przełączane przez proste flagi lub wybór w menu interaktywnym.

Szybki start

Aby uruchomić narzędzie, potrzebujesz zainstalowanych na maszynie Git, Python i szybkiego menedżera pakietów uv.

Generator instaluje się przez pip:

python3 -m pip install fastapi_template
fastapi_template

Po uruchomieniu w konsoli pojawi się kreator krok po kroku. Wybierasz nazwę projektu, żądaną bazę danych, typ autoryzacji (JWT lub cookie przez fastapi-users), format CI/CD (GitHub Actions lub GitLab CI) oraz dodatkowe usługi.

Gdy generator zakończy pracę, przejdź do utworzonego folderu i uruchom środowisko:

cd my_awesome_project
docker-compose up --build

Jeśli nie chcesz instalować pakietu lokalnie, możesz uruchomić generator przez Docker jedną linijką:

docker run --rm -it -v "$(pwd):/projects" ghcr.io/s3rius/fastapi_template

Generowanie przez flagi CLI

Jeśli konfigurujesz automatyczne tworzenie mikroserwisów w swojej firmie, możesz wyłączyć tryb interaktywny. Narzędzie przyjmuje wszystkie parametry przez argumenty linii poleceń:

fastapi_template \
  --name billing_service \
  --api-type rest \
  --db postgresql \
  --orm sqlalchemy \
  --migrations \
  --redis \
  --taskiq \
  --prometheus \
  --ci github \
  --quiet

To wywołanie utworzy gotową usługę ze skonfigurowanym SQLAlchemy, migracjami Alembic, zadaniami w tle Taskiq, metrykami i pipeline'em GitHub bez ani jednego pytania w terminalu.

Co jest w środku wygenerowanego projektu

Wygenerowany kod przyjemnie zaskakuje swoją strukturą. Nie ma tutaj bałaganu z wszystkim wciśniętym w jeden plik main.py.

Architektura jest podzielona na logiczne warstwy:

• web/api: routery podzielone według prefiksów wersji i modułów
• db: połączenie z bazą danych, modele i konfiguracja migracji
• services: logika biznesowa i klienci zewnętrznych usług
• settings.py: typowane ustawienia oparte na pydantic-settings

Projekt od razu zawiera testy pytest z pokryciem około 90% dla struktury bazowej, skonfigurowany pre-commit z linterami i gotowy docker-compose.yml ze wszystkimi wybranymi usługami. Nie będziesz musiał osobno uruchamiać Redis czy PostgreSQL do lokalnego developmentu.

Komu przyda się ten projekt

Generator idealnie sprawdza się w dwóch scenariuszach.

Pierwszy przypadek to szybkie uruchamianie pet projects i MVP. Kiedy chcesz przetestować hipotezę w weekend, nie ma ochoty poświęcać pół dnia na boilerplate.

Drugi przypadek to standaryzacja mikroserwisów w zespole. Możesz wziąć ten szablon jako bazę lub użyć jego interfejsu CLI, żeby nowe usługi w firmie były tworzone według jednego standardu z już skonfigurowaną telemetrią i testami.

Jeśli piszesz w Pythonie i często uruchamiasz nowe backendy FastAPI, koniecznie dodaj to repozytorium do zakładek. Zaoszczędzi mnóstwo czasu i nerwów na starcie.