Guida allo stack FARM: come creare app full-stack con FastAPI, React e MongoDB

Il generatore di applicazioni full-stack FastAPI, React, MongoDB (FARM) è uno strumento potente progettato per semplificare la creazione di applicazioni web pronte per la produzione. Integrando FastAPI per il back end, React per il front end e MongoDB come database NoSQL scalabile, il generatore FARM consente agli sviluppatori Python di impiantare rapidamente applicazioni robuste con un setup minimo. Questo strumento è ideale per chi vuole concentrarsi sulla costruzione delle funzionalità invece che sulla configurazione del boilerplate.

Questo articolo presenta il generatore di applicazioni FARM, ne spiega le funzionalità principali, fornisce istruzioni di setup passo passo e ne dimostra le capacità con un esempio reale: un'app di gestione delle attività. L'obiettivo è mostrare come il generatore semplifica lo sviluppo full-stack e aiuta gli sviluppatori Python a creare applicazioni scalabili e pronte per la produzione.

Se ti serve un ripasso su MongoDB, dai un'occhiata al corso di DataCamp Introduzione a MongoDB in Python. 

Che cos'è il FastAPI Application Generator?

Il generatore FARM automatizza la creazione di uno stack completo per applicazioni web con i seguenti componenti:

• Setup full-stack: Genera un back end FastAPI, un front end React e un database MongoDB, integrati senza soluzione di continuità per uno sviluppo rapido.
• Autenticazione preconfigurata: Include OAuth2 con JWT, autenticazione tramite magic link e gestione dei cookie per un accesso utente sicuro. OAuth2 con JWT è come un “pass VIP” sicuro (codice JWT) che ottieni dopo il login per accedere alle aree private.
• Integrazione con Docker Compose: Fornisce file Docker Compose preconfigurati per uno sviluppo e test locali semplici.
• Strumenti operativi: Integra Celery per l'elaborazione asincrona dei task, Traefik per il bilanciamento del carico e GitHub Actions per CI/CD, garantendo un ambiente pronto per la produzione.

L'elenco completo delle funzionalità è disponibile nel repo GitHub.

Vantaggi per gli sviluppatori

Il generatore FARM offre vantaggi significativi:

• Risparmio di tempo: Elimina compiti ripetitivi di setup, come configurare autenticazione o connessioni al database, permettendoti di iniziare subito a scrivere codice.
• Best practice: Garantisce una struttura di progetto scalabile, sicura e manutenibile, in linea con gli standard del settore.
• Flessibilità: Fornisce una base personalizzabile che puoi estendere in base alle esigenze specifiche del progetto.

Come eseguire il MongoDB FastAPI Application Generator

Per illustrare le capacità del generatore, vedremo come impostare un progetto di esempio. Le istruzioni seguenti presuppongono che tu abbia installato Python 3.8+, Node.js, Docker e Docker Compose.

Istruzioni di setup passo passo

Per dimostrare le capacità del generatore, creeremo un progetto di esempio chiamato task-manager. Assicurati di avere installati i seguenti prerequisiti:

• Python 3.11+: Preferibilmente 3.12, verificato con python3.12 --version.
• Node.js: Per il front end React.
• Docker Desktop: Per lo sviluppo containerizzato.
• MongoDB: Installazione locale (ad es. via Homebrew con brew install mongodb-community@7.0) o MongoDB Atlas (usa una URI di connessione come mongodb+srv://:@cluster0.mongodb.net/?retryWrites=true&w=majority).
• Cookiecutter: Per generare il template del progetto.
• Hatch: Per la gestione delle dipendenze.
• MongoDB Compass (opzionale): Per la visualizzazione del database.

Prima di continuare, crea un ambiente virtuale con /usr/local/bin/python3.12 -m venv task-manager-venv e attivalo con source task-manager-venv/bin/activate.

1. Installa la libreria cookiecutter: pip install cookiecutter
2. Genera il progetto: usa il generatore FARM per creare un progetto:

cookiecutter https://github.com/mongodb-labs/full-stack-fastapi-mongodb --no-input project_name="task-manager"
cd task-manager

3. Installa MongoDB in locale o usa MongoDB Atlas:

brew tap mongodb/brew
brew install mongodb-community@7.0
brew services start mongodb-community@7.0

Per Atlas, registrati, crea un cluster gratuito e ottieni una stringa di connessione (ad es. mongodb+srv://:@cluster0.mongodb.net/?retryWrites=true&w=majority) da usare nel tuo file .env.

4. Configura le variabili d'ambiente: 

Copia e modifica il file .env:

cp .env.example .env
nano .env

Aggiorna con la tua URI MongoDB, il nome del database e i secret:

MONGODB_URI=mongodb://localhost:27017
MONGO_DATABASE=task_manager
SECRET_KEY=your-secret-key
FIRST_SUPERUSER=admin@task-manager.com
FIRST_SUPERUSER_PASSWORD=changethis

5. Build ed esecuzione con Docker Compose:

Assicurati che Docker Desktop sia in esecuzione, poi:

docker compose build --no-cache

1. docker compose up -d
2. Accedi all'applicazione:
• Front end: http://localhost:3000
• Back end: http://localhost/api/v1
• Swagger UI: http://localhost/docs (documentazione API interattiva)
• ReDoc: http://localhost/redoc
• Flower: http://localhost:5555 (monitoraggio Celery)
• Traefik UI: http://localhost:8090 (dashboard di routing)
3. Effettua il login con admin@task-manager.com (password: changethis).
4. Testa l'autenticazione: usa Swagger UI (/docs) per provare gli endpoint /auth/login o /auth/magic-link.
5. Configura CI/CD: fai push su GitHub per attivare i workflow GitHub Actions inclusi.

Esplora la struttura del progetto full-stack generato

Quando usi il generatore FARM, crea un progetto task-manager ben organizzato. Pensalo come una casa prefabbricata in cui ogni stanza ha un compito:

• backend/: È la cucina dove lavora il back end FastAPI. Contiene cartelle come app/ (per il codice della tua API) e conf/ (per le impostazioni) per gestire task e dati.

• frontend/: È il soggiorno dove gli utenti vedono il tuo sito, basato su Next.js/React. La cartella app/ contiene le pagine (ad es. about, TaskList) con file come layout.tsx (la cornice della pagina) e page.tsx (il contenuto). La cartella public/ archivia elementi come l'icona del sito.

• Altri file: Troverai docker-compose.yml (per eseguire tutto con Docker), .env (le tue impostazioni segrete) e .github/workflows/ (per i test automatici quando condividi il codice).

Questo setup è pronto a crescere e il generatore aggiunge strumenti utili per rendere lo sviluppo più semplice!

Cosa puoi fare con le funzionalità del generatore

Il generatore FARM include strumenti integrati pensati per aiutarti a creare ogni tipo di progetto. Ecco una panoramica semplice di cosa fanno e come possono aiutarti:

Integrazione con Docker Compose: ottimizzata per lo sviluppo locale

• Cosa fa: Docker Compose è come un pulsante magico che configura ed esegue l'intero progetto (back end, front end, database) con un solo comando. Usa container per tenere tutto separato ed è facile da testare sul tuo computer.
• Come aiuta: Puoi avviare l'app task-manager digitando docker compose up -d e fermarla con docker compose down. È perfetto per sperimentare senza incasinare il computer. Controlla come sta andando con docker compose ps—se tutto è “Up”, sei a posto!

Esempio: Dopo aver configurato il progetto, esegui semplicemente:

cd task-manager
docker compose up -d

Apri http://localhost:3000 per vedere il front end: stai eseguendo tutto in locale!

Sistema di autenticazione integrato

• Cosa fa: Aggiunge un sistema di login con account utente, incluso un superuser predefinito (come admin@task-manager.com con password changethis). Usa OAuth2 con token JWT (codici di login sicuri) e magic link (link via email per accedere).
• Come aiuta: Puoi permettere agli utenti di registrarsi, accedere o usare un magic link per entrare nell'app. Provalo su http://localhost/docs in Swagger UI—cerca /api/v1/login/oauth per testare il login. È perfetto per app in cui solo alcune persone dovrebbero vedere certi contenuti, come una lista di task privata.

Esempio: Accedi con l'utente predefinito:

1. Vai su http://localhost/docs.
2. Trova /api/v1/login/oauth, inserisci admin@task-manager.com e la password indicata, quindi clicca “Execute”. Otterrai un token JWT da usare per le pagine private!

L'API del task manager

Demo per l'API Oauth

Risposta per l'API Oauth

Funzionalità del back end FastAPI

Vediamo più da vicino le funzionalità chiave del back end basato su FastAPI e come semplifica operazioni sul database, design delle API e scalabilità.

• MongoDB Motor: È il motore che comunica con il database MongoDB in modo super veloce, anche quando gestisce molte richieste contemporaneamente.
• MongoDB ODMantic: Pensalo come un aiutante che rende più semplice salvare e trovare dati in MongoDB, come organizzare i task in scatole ordinate.
• Supporto CRUD comune: CRUD sta per create, read, update, delete. Questa funzionalità offre strumenti pronti all'uso per aggiungere, visualizzare, modificare o rimuovere dati (come i task) senza partire da zero.
• Basato su standard: Segue regole come OpenAPI e JSON Schema, così la tua API è chiara e compatibile con altri strumenti o app.
• Come aiuta: Puoi costruire rapidamente un back end per archiviare i task. Il generatore lo imposta per te, così devi solo aggiungere le tue idee, come nuove funzionalità per i task, usando il codice fornito.

Esempio: Aggiungi un visualizzatore rapido di task in backend/app/api/tasks.py:

from fastapi import APIRouter, Depends
from odmantic import AIOEngine, Model
from motor.motor_asyncio import AsyncIOMotorClient
router = APIRouter(prefix="/tasks", tags=["tasks"])
class Task(Model):
    title: str
async def get_db():
    client = AsyncIOMotorClient("mongodb://localhost:27017")
    return AIOEngine(client, database="task_manager")
@router.get("/")  # View all tasks
async def get_tasks(db: AIOEngine = Depends(get_db)):
    return await db.find(Task)

Provalo su http://localhost/api/v1/tasks dopo aver ricostruito con docker compose up --build.

Front end Next.js/React

Il front end React è dove gli utenti interagiscono con la tua app. Vediamo com'è strutturato e quali strumenti include per aiutarti a creare pagine curate e responsive.

• Autorizzazione via middleware: Agisce come un guardiano, controllando se gli utenti hanno effettuato l'accesso prima di mostrare certe pagine (ad es. solo gli utenti loggati vedono /TaskList).
• Validazione dei form con React Hook Form: Garantisce che i form (come quello per aggiungere un task) contengano le informazioni corrette prima del salvataggio, così non passano task vuoti.
• Gestione dello stato con Redux: Tiene traccia di elementi come i task selezionati, rendendo l'app fluida e veloce anche con molti dati.
• CSS e template con TailwindCSS, HeroIcons e HeadlessUI: Sono strumenti di design preconfezionati. TailwindCSS stila le pagine, HeroIcons aggiunge icone accattivanti e HeadlessUI offre pulsanti e menu pronti all'uso.
• Come aiuta: Puoi costruire una bella pagina dei task con form semplici e accesso sicuro. Il generatore imposta il design, così puoi concentrarti sull'aggiunta di task o altre funzionalità.

Esempio: Aggiungi un semplice form per i task in frontend/app/TaskList/page.tsx:

import { useState } from 'react';
export default function TaskList() {
  const [task, setTask] = useState({ title: '' });
  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    fetch('http://localhost/api/v1/tasks', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(task),
    });
    setTask({ title: '' });
  };
  return (
    <div className="container mx-auto p-4">
      <h1 className="text-2xl font-bold">Add Task</h1>
      <form onSubmit={handleSubmit}>
        <input
          className="border p-2"
          value={task.title}
          onChange={e => setTask({ title: e.target.value })}
          placeholder="Task name"
        />
        <button className="bg-blue-500 text-white p-2" type="submit">Add</button>
      </form>
    </div>
  );
}

Visita http://localhost:3000/TaskList per aggiungere un task.

Far crescere il tuo task manager

Il generatore ti fornisce una base solida per un task manager. Ad esempio, puoi:

• Aggiungere un pulsante per contrassegnare i task come completati usando gli strumenti CRUD.
• Usare l'autenticazione per mantenere privata la tua lista di task.
• Stilizzarlo con TailwindCSS per un aspetto impeccabile.
• Configurare Celery per inviare promemoria dei task via email.

Altre idee da esplorare

Con queste funzionalità, puoi creare molto più di un semplice task manager:

• Blog o sito web: Archivia i post in MongoDB, usa FastAPI per mostrarli e progetta un sito accattivante con Next.js.
• Negozio online: Salva i prodotti in MongoDB, gestisci gli ordini con Celery e crea una pagina shop con Next.js.
• Aggiornamenti live: Mostra informazioni in tempo reale (come il punteggio di una partita) usando MongoDB, le funzionalità live di FastAPI e una dashboard Next.js.

Conclusione

Il generatore di applicazioni FARM semplifica lo sviluppo full-stack offrendo uno stack preconfigurato e pronto per la produzione che integra FastAPI, React e MongoDB. L'automazione dei compiti di setup, l'aderenza alle best practice e l'architettura flessibile lo rendono uno strumento prezioso per gli sviluppatori Python. Che tu stia costruendo un task manager o un'applicazione web complessa, il generatore FARM accelera lo sviluppo e garantisce scalabilità. Provalo oggi seguendo le istruzioni di setup ed esplora la documentazione completa sul repository GitHub per sbloccarne tutto il potenziale!

Se vuoi saperne di più, consulta queste risorse utili:

• Repository ufficiale: Esplora il codice sorgente, leggi la documentazione completa, controlla gli aggiornamenti o contribuisci.
• Documentazione di FastAPI: Approfondisci le funzionalità di FastAPI e come alimenta il back end.
• Corso Introduzione a FastAPI: Crea API robuste e pronte per la produzione con FastAPI, padroneggiando operazioni HTTP, validazione ed esecuzione asincrona per costruire pipeline di dati e ML efficienti.