Come Costruire uno Skeleton Backend FastAPI Funzionante in Pochi Minuti

Ogni volta che avvio un nuovo progetto FastAPI, mi ritrovo in un loop alla Groundhog Day. Devo configurare di nuovo la struttura delle directory, connettere il database, scrivere le migrazioni, collegare le variabili d'ambiente, costruire il Dockerfile e configurare i linter. È facile sprecare un'intera serata in questa routine prima ancora che appaia il primo endpoint vero.

Ovviamente, puoi copiare la struttura dal tuo repository precedente. Ma di solito contiene un sacco di workaround vecchi, dipendenze inutili e librerie obsolete. Anche i boilerplate già pronti trovati online raramente centrano l'obiettivo, perché l'autore ha scelto TortoiseORM ma tu hai bisogno di SQLAlchemy 2.0, oppure hanno inserito il pesante Celery al posto di code leggere.

Il repository FastAPI-template dello sviluppatore s3rius risolve questo problema in modo diverso. Non è un semplice template statico, ma un generatore di progetti interattivo e flessibile.

Un costruttore invece di un template rigido

Il progetto funziona come un questionario da terminale. Lanci l'utility tramite pip, uv o Docker, rispondi a una ventina di domande e ottieni una codebase pronta e personalizzata in base alle tue esigenze.

Il principale vantaggio del generatore è la variabilità. La maggior parte dei template impone uno stack specifico, ma qui assembli tu stesso l'insieme di componenti necessari.

Database e ORM a scelta

invece di essere legato a una singola libreria, l'utility supporta diverse opzioni popolari per la gestione dei dati:

• SQLAlchemy 2.0 con motore async
• TortoiseORM con generazione delle migrazioni tramite Aerich
• Piccolo ORM
• Ormar
• Beanie per MongoDB
• Driver psycopg raw senza ORM

Se non hai bisogno di un database, puoi scegliere l'opzione senza archiviazione dati. In questo caso, il codice non avrà dipendenze inutili e file di configurazione superflui.

REST o GraphQL

Di default, il generatore crea una classica API REST con documentazione Swagger automatica. Ma se il tuo frontend preferisce lavorare tramite GraphQL, il generatore configurerà il wrapper basato sulla libreria Strawberry. Non c'è bisogno di configurare manualmente schema e tipi per iniziare.

Task in background e code

invece del pesante Celery, l'autore del template ha aggiunto l'integrazione con Taskiq — un moderno task manager async per Python. Si integra perfettamente nell'architettura async complessiva di FastAPI. Come message broker, puoi scegliere Redis, RabbitMQ o Kafka durante la generazione.

Monitoraggio e logging out of the box

Il template include già integrazioni pronte che di solito devi configurare manualmente da articoli separati:

• Raccolta metriche per Prometheus
• Tracing tramite OpenTelemetry
• Invio errori a Sentry
• Logging strutturato tramite Loguru

Tutte queste opzioni sono attivabili tramite semplici flag o selezione nel menu interattivo.

Quick start

Per eseguire l'utility, devi avere installati Git, Python e il fast package manager uv sulla tua macchina.

Il generatore si installa tramite pip:

python3 -m pip install fastapi_template
fastapi_template

Dopo il lancio, apparirà un questionario passo-passo nella console. Selezioni il nome del progetto, il DBMS desiderato, il tipo di autenticazione (JWT o cookie tramite fastapi-users), il formato CI/CD (GitHub Actions o GitLab CI) e i servizi aggiuntivi.

Quando il generatore finisce, vai nella cartella creata e attiva l'ambiente:

cd my_awesome_project
docker-compose up --build

Se non vuoi installare il pacchetto localmente, puoi eseguire il generatore tramite Docker con una sola riga:

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

Generazione tramite flag CLI

Se stai configurando la creazione automatizzata di microservizi nella tua azienda, puoi disabilitare la modalità interattiva. L'utility accetta tutti i parametri tramite argomenti da riga di comando:

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

Questa chiamata creerà un servizio pronto con SQLAlchemy configurato, migrazioni Alembic, task in background con Taskiq, metriche e una pipeline GitHub senza una sola domanda nel terminale.

Cosa c'è dentro il progetto generato

Il codice generato stupisce piacevolmente per la sua struttura. Non c'è nessun disastro con tutto stipato in un unico file main.py.

L'architettura è divisa in layer logici:

• web/api: router suddivisi per prefissi di versione e moduli
• db: connessione al database, modelli e configurazione delle migrazioni
• services: logica di business e client per servizi esterni
• settings.py: impostazioni tipizzate basate su pydantic-settings

Il progetto include immediatamente test pytest con circa il 90% di copertura per la struttura base, pre-commit configurato con linter e un docker-compose.yml pronto con tutti i servizi selezionati. Non dovrai avviare separatamente Redis o PostgreSQL per lo sviluppo locale.

A chi tornerà utile questo progetto

Il generatore è perfetto per due scenari.

Il primo caso è il lancio rapido di pet project e MVP. Quando vuoi testare un'ipotesi nel fine settimana, non c'è voglia di passare mezza giornata sul boilerplate.

Il secondo caso è la standardizzazione dei microservizi in un team. Puoi usare questo template come base o utilizzare la sua interfaccia CLI in modo che i nuovi servizi in azienda vengano creati secondo uno standard unico con telemetria e test già configurati.

Se scrivi in Python e spesso avvii nuovi backend FastAPI, segna assolutamente questo repository. Farà risparmiare molto tempo e nervi all'inizio.