Creare un'Applicazioneper Svogliati
Sai scrivere uno script e vuoi fare il salto. Qui trovi come si ragiona prima di scrivere codice: frontend, backend, dati, quale linguaggio scegliere, i principi che evitano il disastro, la sicurezza e il ciclo di vita. Gli esempi sono in Python e seguono una sola app che cresce capitolo dopo capitolo.
"Lo sistemo dopo" — le ultime parole famose di ogni progetto che oggi nessuno ha il coraggio di toccare.
Prima del codice
La maggior parte delle applicazioni non muore per un bug. Muore perché nessuno sapeva bene cosa dovesse fare.
🛒 L'app che useremo in tutta la guida
Per non parlare nel vuoto, seguiamo un'app sola dall'inizio alla fine: ListaSpesa, una lista della spesa condivisa. Una persona crea una lista, invita i coinquilini, chiunque aggiunge "latte" e chi è al supermercato spunta le voci man mano.
È piccola, ma ha tutto quello che serve: utenti e login, dati condivisi tra più persone, permessi (chi può vedere quale lista), un frontend e un backend. Ogni concetto della guida lo vediamo applicato qui.
❓ Tre domande, scritte
- Che problema risolve? In una frase. "I coinquilini comprano il latte in tre e nessuno compra il detersivo."
- Chi la usa, e da dove? Dal telefono, al supermercato, con una mano sola e il carrello nell'altra.
- Come capisco che funziona? "Per un mese nessuno compra doppio" vale più di qualsiasi metrica.
Se non riesci a rispondere in tre righe, non è il momento di scegliere il framework.
✂️ L'MVP: taglia finché fa male
MVP (Minimum Viable Product) è la versione più piccola che qualcuno userebbe davvero. Per ListaSpesa:
- Dentro: login, una lista, aggiungi voce, spunta voce, condividi con un link
- Fuori (per ora): categorie, prezzi, foto, notifiche push, app nativa, modalità offline, tema scuro
Tutto quello che sta "fuori" va in un file IDEE.md. Non lo stai buttando, lo stai rimandando a quando avrai utenti che lo chiedono.
📝 Le storie utente, versione svogliata
Scrivi cosa fa l'utente, non come lo implementi. Il formato classico è "Come [chi], voglio [cosa], per [perché]":
- Come coinquilino, voglio aggiungere una voce in due tocchi, per non dimenticarmela mentre apro il frigo vuoto.
- Come chi fa la spesa, voglio spuntare le voci, così gli altri vedono cosa ho già preso.
- Come proprietario della lista, voglio invitare qualcuno con un link, senza che debba cercarmi per nome.
Ogni storia diventa poi una o più funzionalità, e ogni funzionalità uno o più test (cap. 9). Dieci storie bastano per un MVP. Cinquanta storie vogliono dire che l'MVP non l'hai tagliato.
Anatomia di un'applicazione
Quasi tutte le app moderne sono la stessa torta a strati. Cambiano gli ingredienti, non la ricetta.
Il frontend è la sala: tavoli, menu, camerieri gentili. L'API è il menu stesso, cioè cosa si può ordinare e in che formato. Il backend è la cucina: decide se l'ordine si può fare, prepara il piatto, rifiuta la carbonara con la panna. Il database è la dispensa. Il cliente non entra in cucina, e la cucina non si fida del cliente che dice "il cuoco ha detto che posso avere il dolce gratis".
🔄 Il viaggio di una richiesta
Renzo Panocia apre ListaSpesa al supermercato e spunta "latte". Ecco cosa succede, in ordine:
- Frontend: l'utente tocca la casella. Il JavaScript manda
PATCH /api/voci/42con{"presa": true}e il cookie di sessione. - Backend, autenticazione: "chi sei?" Il cookie corrisponde a una sessione valida di Renzo Panocia.
- Backend, autorizzazione: "puoi toccare la voce 42?" La voce sta nella lista 7, e Renzo Panocia è membro della lista 7. Sì.
- Backend, validazione:
presaè davvero un booleano? Sì. - Database:
UPDATE voci SET presa = 1 WHERE id = 42. - Risposta:
200 OKcon la voce aggiornata. Il frontend barra la riga.
I passi 2, 3 e 4 sono quelli che i principianti saltano. Il cap. 10 spiega perché è lì che nascono quasi tutti i buchi di sicurezza.
Monolite
Un solo programma backend fa tutto. È la scelta giusta per il 95% dei progetti nuovi, e ListaSpesa è uno di questi.
Microservizi
Tanti servizi piccoli che si parlano in rete. Risolvono problemi di organizzazione tra team grandi. Se sei da solo, risolvono problemi che non hai.
Serverless
Funzioni che girano solo quando servono, sulla piattaforma di qualcun altro. Comode per pezzi piccoli, scomode quando ti serve stato o debug serio.
Frontend
Tutto quello che l'utente vede e tocca. È anche la parte che gira su un computer che non controlli.
HTML
La struttura: titoli, liste, form, bottoni. Usa i tag giusti (<button>, non un <div> cliccabile) e accessibilità e SEO te le ritrovi quasi gratis.
CSS
L'aspetto: colori, spazi, layout. Flexbox e Grid risolvono il 90% dei layout. Pensa prima al telefono, poi al desktop.
JavaScript
Il comportamento: reagire ai click, chiamare l'API, aggiornare la pagina senza ricaricarla. È l'unico linguaggio che il browser esegue in modo nativo.
🛣️ Le due strade
| Voce | Rendering lato server (SSR) | Single Page App (SPA) |
|---|---|---|
| Come funziona | Il backend genera l'HTML già pronto, con un template (Jinja2). Il browser lo mostra e basta. | Il server manda una pagina vuota più un pacchetto JS. È il JS a costruire l'interfaccia e a chiedere i dati all'API. |
| Strumenti | Jinja2, Django templates, htmx per le parti dinamiche | React, Vue, Svelte, Angular |
| Pro | Semplice, veloce al primo caricamento, un solo progetto, un solo linguaggio | Interfacce molto interattive, l'API è riusabile per un'app mobile |
| Contro | Interazioni complesse (drag & drop, editor) diventano faticose | Due progetti, build step, gestione dello stato, pacchetti npm a centinaia |
| Per ListaSpesa | ✅ basta e avanza | solo se poi vuoi l'app nativa con la stessa API |
📡 Chiamare l'API senza farsi male
Se scegli il JavaScript "a mano", il pattern è sempre lo stesso: chiami l'API, controlli l'esito, aggiorni la pagina. Nota due cose: si gestisce l'errore e si inserisce il testo con textContent, mai con innerHTML. Il perché lo vediamo nel cap. 10.
async function aggiungiVoce(listaId, nome) {
const r = await fetch(`/api/liste/${listaId}/voci`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ nome }),
});
if (!r.ok) {
mostraErrore("Non sono riuscito ad aggiungere la voce, riprova.");
return;
}
const voce = await r.json();
const li = document.createElement("li");
li.textContent = voce.nome; // testo, non HTML: niente sorprese
document.querySelector("#voci").append(li);
}
Nel frontend sì
- Validare i campi per dare un feedback immediato all'utente
- Mostrare sempre uno stato: caricamento, errore, lista vuota
- Provare su un telefono vero, con la rete lenta
- Bottoni grandi, testo leggibile, contrasto decente
Nel frontend no
- Controlli di sicurezza "tanto il bottone è nascosto"
- Chiavi API, password, segreti di qualsiasi tipo
- Regole che contano (prezzi, permessi, limiti)
- Fidarsi del fatto che l'utente usi il tuo frontend
curl. La validazione nel frontend serve all'utente onesto. Quella nel backend serve contro tutti gli altri, e va fatta comunque.
Per i dettagli su contrasto, tipografia e form leggi UI/UX per Svogliati.
Backend
La cucina. Qui nessuno vede niente, ma è qui che si decide tutto.
Autenticazione
Chi sei?
Autorizzazione
Cosa puoi fare?
Validazione
Quello che mandi ha senso?
Logica
Applica le regole, salva, rispondi
🐍 Framework Python: quale?
| Framework | Filosofia | Quando |
|---|---|---|
| FastAPI | API moderne, validazione automatica con Pydantic, documentazione dell'API generata da sola | Backend che espone soprattutto JSON. È quello che usiamo qui. |
| Django | "Batterie incluse": ORM, login, pannello admin, migrazioni, form, tutto in scatola | App web classiche con molte pagine e un pannello di gestione. Meno decisioni da prendere. |
| Flask | Minimalista, scegli tu ogni pezzo | Progetti piccoli, o quando vuoi capire come funziona ogni componente. |
Sono tutte e tre scelte solide e mature. La differenza vera è quante decisioni vuoi prendere tu. Django le prende quasi tutte per te, Flask quasi nessuna, FastAPI sta a metà.
🔌 L'API REST in dieci righe di teoria
Un'API REST ragiona per risorse (liste, voci, utenti) indicate da URL, su cui fai azioni con i verbi HTTP. Le risposte usano i codici di stato standard, così il client sa cosa è successo senza leggere il testo.
| Richiesta | Significato | Risposta tipica |
|---|---|---|
GET /api/liste/7/voci | elenco delle voci della lista 7 | 200 + array JSON |
POST /api/liste/7/voci | crea una voce nella lista 7 | 201 Created |
PATCH /api/voci/42 | modifica parte della voce 42 | 200 |
DELETE /api/voci/42 | cancella la voce 42 | 204 No Content |
| Codice | Vuol dire |
|---|---|
400 / 422 | la richiesta è sbagliata o i dati non sono validi (colpa del client) |
401 | non so chi sei: fai il login |
403 | so chi sei, ma questa cosa non puoi farla |
404 | non esiste, oppure non te lo dico che esiste |
500 | il backend è esploso (colpa tua, non del client) |
🧑🍳 ListaSpesa: il primo endpoint
Il modello Pydantic descrive com'è fatta una voce valida. FastAPI lo usa per rifiutare da solo, con un 422, tutto quello che non rispetta le regole, prima ancora che il tuo codice parta.
from fastapi import APIRouter, Depends, HTTPException, status
from pydantic import BaseModel, Field
from . import servizi
from .auth import utente_corrente, Utente
router = APIRouter(prefix="/api")
class NuovaVoce(BaseModel):
nome: str = Field(min_length=1, max_length=100)
quantita: int = Field(default=1, ge=1, le=99)
@router.post("/liste/{lista_id}/voci", status_code=status.HTTP_201_CREATED)
def aggiungi_voce(
lista_id: int,
dati: NuovaVoce,
utente: Utente = Depends(utente_corrente), # 1. autenticazione
):
if not servizi.e_membro(utente.id, lista_id): # 2. autorizzazione
raise HTTPException(status.HTTP_404_NOT_FOUND)
return servizi.aggiungi_voce(lista_id, dati.nome, dati.quantita) # 3. logica
Nota che l'endpoint non contiene SQL. Si occupa solo di HTTP: riceve, controlla, delega. La logica sta in servizi.py e l'accesso ai dati in un modulo a parte. È la separazione delle responsabilità del cap. 8, applicata.
🍪 Sessioni o token?
Per un'app web con il frontend sullo stesso dominio, la scelta noiosa è quella giusta: sessione lato server con cookie HttpOnly, Secure e SameSite=Lax. Il JavaScript non vede il cookie e un attacco XSS non te lo ruba.
I JWT hanno senso quando più servizi devono verificare l'identità senza chiedere a un server centrale, oppure per le app mobili. Per un monolite web portano soprattutto un problema in più: revocare un token prima che scada.
🧠 Stateless
Il processo del backend non deve ricordarsi niente tra una richiesta e l'altra: le sessioni stanno nel database (o in Redis), i file caricati su disco o in un object storage, non in una variabile globale.
Il vantaggio: puoi riavviarlo, aggiornarlo o lanciarne tre copie dietro un load balancer senza che nessuno se ne accorga.
🚀 Dove gira
In sviluppo basta uv run fastapi dev. In produzione l'app gira con un server ASGI (uvicorn) dietro un reverse proxy (nginx, Caddy) che gestisce HTTPS, file statici e limiti. Come confezionarla e lanciarla in modo riproducibile lo spiegano Docker per Svogliati e, se proprio devi, K8s per Svogliati.
I dati
Il codice si riscrive. I dati sbagliati restano per anni. Progetta prima i dati, poi il resto.
🗺️ Modella prima di scegliere dove salvare
Prendi carta e penna e scrivi le entità (le "cose" della tua app) e le relazioni tra loro. Per ListaSpesa:
Se il disegno ti viene facile con tabelle e frecce, il tuo problema è relazionale: usa SQL. Capita quasi sempre.
⚖️ SQL o NoSQL?
| Tipo | Esempi | Buono per |
|---|---|---|
| Relazionale (SQL) | SQLite, PostgreSQL, MySQL/MariaDB | quasi tutto: dati strutturati, relazioni, transazioni, query flessibili. È la scelta di default. |
| Documentale | MongoDB | documenti dalla forma molto variabile. Spesso un campo JSONB di PostgreSQL fa lo stesso lavoro. |
| Chiave-valore | Redis, Valkey | cache, sessioni, code, contatori. Raramente è il database principale. |
| Altri | time-series, grafi, vettoriali | problemi specifici. Lo saprai quando ce l'hai. |
🪶 SQLite non è un giocattolo
È un file, non serve un server, ed è nella libreria standard di Python. Regge senza problemi app con poche scritture concorrenti, quindi molte più app di quanto pensi.
Passa a PostgreSQL quando hai più processi o server che scrivono insieme, quando servono utenti e permessi sul database, o quando vuoi le sue funzioni avanzate.
🧬 Le migrazioni
Lo schema cambierà: nuove colonne, nuove tabelle. Ogni modifica va scritta come migrazione, uno script versionato che porta il database dalla versione N alla N+1. In Python lo strumento standard è Alembic (con SQLAlchemy). Django ne ha uno integrato.
Mai modificare a mano lo schema di produzione "solo stavolta".
🗄️ Lo strato di accesso ai dati
Tutto l'SQL sta in un modulo solo. Le query usano sempre i parametri (?), mai stringhe costruite a mano: è la difesa contro la SQL injection (cap. 10).
import sqlite3
from .config import impostazioni
def esegui(sql: str, parametri: tuple = ()) -> list[sqlite3.Row]:
conn = sqlite3.connect(impostazioni.db_path)
conn.row_factory = sqlite3.Row
try:
with conn: # commit se va bene, rollback se esplode
return conn.execute(sql, parametri).fetchall()
finally:
conn.close()
def voci_della_lista(lista_id: int) -> list[sqlite3.Row]:
return esegui(
"SELECT id, nome, quantita, presa FROM voci WHERE lista_id = ? ORDER BY id",
(lista_id,),
)
Quando le query diventano tante, un ORM come SQLAlchemy ti evita molto SQL ripetitivo. Imparare prima l'SQL a mano però ti fa capire cosa fa l'ORM quando qualcosa va lento. Per approfondire leggi PostgreSQL, MySQL e SQL per Svogliati.
NOT NULL, UNIQUE sull'email, FOREIGN KEY tra voci e liste, CHECK (quantita > 0). Il codice ha bug, gli script di manutenzione saltano i controlli, e il database è l'ultima linea di difesa. Con SQLite ricordati PRAGMA foreign_keys = ON, perché per compatibilità è spento di default.
Scegliere il linguaggio
Non esiste il linguaggio migliore. Esiste quello adatto a cosa costruisci, a chi lo mantiene e a dove deve girare.
🧭 Dipende da cosa costruisci
| Cosa | Scelte sensate | Note |
|---|---|---|
| Backend web / API | Python, Go, TypeScript (Node), Java/Kotlin, C#, PHP | Tutti validi. Conta più l'ecosistema che conosci della velocità del linguaggio. |
| Frontend web | JavaScript / TypeScript | Non c'è scelta: è quello che gira nel browser. TypeScript aggiunge i tipi e ti salva da molti errori. |
| App mobile | Kotlin (Android), Swift (iOS), Flutter (Dart), React Native | Nativo per la massima integrazione. Flutter o React Native per un solo codice su due piattaforme. |
| App desktop | C#, Rust, Tauri, Electron, Qt | Electron è comodo ma pesa. Tauri e Rust sono più leggeri. |
| Script, CLI, automazione | Python, Go, Bash | Bash finché sta in una schermata, poi Python. Go se vuoi un binario unico da distribuire. |
| Dati, analisi, IA | Python | L'ecosistema (pandas, numpy, PyTorch) non ha rivali. |
| Sistemi, prestazioni, embedded | Rust, C, C++, Go | Quando i millisecondi e la memoria contano davvero. |
📦 L'ecosistema conta più della sintassi
La sintassi si impara in una settimana. Quello che fa la differenza:
- Librerie: esiste già un pacchetto maturo per login, PDF, email, pagamenti?
- Documentazione e community: quando ti blocchi, trovi la risposta?
- Deploy: quanto è facile metterlo su un server o in un container?
- Persone: chi lo manterrà tra due anni lo conosce?
🐍 Perché Python in questa guida
- Si legge quasi come pseudocodice, quindi gli esempi parlano da soli
- Probabilmente lo usi già per i tuoi script
- Backend web maturi (Django, FastAPI) e un ecosistema enorme
- I type hint, con un type checker, ti danno buona parte dei vantaggi di un linguaggio tipizzato
Se vuoi prima ripassare il linguaggio, c'è la guida Python per Svogliati.
Il limite onesto: non è il più veloce né il più leggero. Per una lista della spesa, e per la stragrande maggioranza delle app web, non te ne accorgerai mai: il collo di bottiglia sarà il database o la rete.
Buoni motivi per scegliere
- Lo conosci già e ti fa consegnare
- Ha le librerie che ti servono, mantenute
- È quello della piattaforma (Swift su iOS, JS nel browser)
- Il team lo sa mantenere
Cattivi motivi
- "È il più veloce" (per una CRUD con 10 utenti)
- "L'ho visto in un video ieri"
- "Scala meglio" (prima servono utenti da scalare)
- Imparare un linguaggio nuovo E consegnare un progetto nuovo, insieme
Impostare il progetto Python
Mezz'ora spesa bene il primo giorno ti risparmia mesi di "da me funziona".
⚡ uv: un comando per tutto
uv gestisce le versioni di Python, l'ambiente virtuale, le dipendenze e il file di lock. Prende il posto di pip, venv, pip-tools e pyenv, ed è molto più veloce.
uv init --package listaspesa # crea pyproject.toml e src/listaspesa/
cd listaspesa
uv add "fastapi[standard]" argon2-cffi # dipendenze dell'app
uv add --dev pytest ruff mypy pip-audit # strumenti di sviluppo
uv run fastapi dev src/listaspesa/main.py # server con ricarica automatica
uv run pytest # test
uv add aggiorna pyproject.toml e uv.lock. Il lock fissa la versione esatta di ogni pacchetto, comprese le dipendenze delle dipendenze. Va nel repository: è quello che garantisce che il server installi esattamente quello che hai provato tu.
📁 La struttura delle cartelle
listaspesa/
├── pyproject.toml # metadati, dipendenze, config di ruff/mypy/pytest
├── uv.lock # versioni esatte: nel repo, sempre
├── README.md # cos'è, come si avvia, come si testa
├── .env.example # variabili richieste, con valori finti
├── .gitignore # .env, .venv, *.db, __pycache__
├── src/listaspesa/
│ ├── main.py # crea l'app FastAPI e monta i router
│ ├── config.py # legge la configurazione dall'ambiente
│ ├── api.py # endpoint HTTP: ricevi, controlla, delega
│ ├── servizi.py # logica: le regole di ListaSpesa
│ ├── db.py # tutto l'SQL sta qui
│ ├── auth.py # login, sessioni, hash delle password
│ └── templates/ # HTML Jinja2
├── migrations/ # migrazioni dello schema
└── tests/
├── test_servizi.py
└── test_api.py
Il layout src/ ti obbliga a installare il pacchetto per poterlo importare. Così i test girano sul codice "installato", come in produzione, e non per caso sulla cartella corrente.
🧹 ruff: stile e bug banali
Linter e formattatore insieme. uv run ruff format sistema la formattazione, uv run ruff check trova import inutilizzati, variabili mai usate e pattern a rischio. Così nessuno discute più su spazi e virgole: decide ruff.
🔤 Type hint + mypy
Python non controlla i tipi quando il programma gira, ma mypy (o pyright) li controlla prima. def voci_della_lista(lista_id: int) -> list[Row] è documentazione che non diventa mai vecchia, e l'editor ti segnala gli errori mentre scrivi.
⚙️ Configurazione fuori dal codice
Percorso del database, chiave segreta, modalità debug: tutto quello che cambia tra il tuo portatile e il server si legge dall'ambiente, non sta scritto nel codice. Così lo stesso codice gira ovunque, e i segreti non finiscono su Git.
import os
from dataclasses import dataclass
@dataclass(frozen=True)
class Impostazioni:
db_path: str
chiave_segreta: str
debug: bool
def carica() -> Impostazioni:
return Impostazioni(
db_path=os.environ.get("LISTASPESA_DB", "listaspesa.db"),
chiave_segreta=os.environ["LISTASPESA_SECRET"], # niente default: se manca, meglio non partire
debug=os.environ.get("LISTASPESA_DEBUG") == "1",
)
impostazioni = carica()
Il default sul percorso del database va bene, quello sulla chiave segreta no: un'app che parte in produzione con "cambiami" come segreto è peggio di un'app che non parte.
Principi e buone pratiche
Il codice si scrive una volta e si legge cento. Scrivi per chi lo leggerà tra sei mesi, cioè per te stanco e senza memoria.
KISS
Keep It Simple, Stupid. La soluzione più semplice che funziona è quasi sempre quella giusta. L'eleganza arriva dopo, se arriva.
YAGNI
You Aren't Gonna Need It. Non scrivere codice per esigenze che "forse un giorno". Quel giorno, se arriva, avrai più informazioni di oggi.
DRY, con giudizio
Don't Repeat Yourself, ma aspetta la terza ripetizione prima di astrarre. Due pezzi simili per caso non sono ancora un concetto da unificare.
🧱 Separazione delle responsabilità
Ogni pezzo ha un solo lavoro. In ListaSpesa i livelli sono tre, e ognuno parla solo con quello sotto:
Il vantaggio concreto: se domani passi da SQLite a PostgreSQL cambi solo db.py. Se aggiungi un bot Telegram, riusi servizi.py senza toccarlo.
🏷️ I nomi sono metà della documentazione
def proc(d, f=False):
r = []
for x in d:
if not x[3] or f:
r.append(x)
return r
def voci_da_comprare(voci: list[Voce], includi_prese: bool = False) -> list[Voce]:
return [v for v in voci if includi_prese or not v.presa]
I commenti servono a spiegare il perché, quando non è ovvio: "ordiniamo per id e non per nome perché gli utenti vogliono vedere le voci nell'ordine in cui le hanno aggiunte". Il cosa deve dirlo già il codice.
💥 Gli errori non si nascondono
try:
salva_voce(voce)
except Exception:
pass
Cattura solo le eccezioni che sai gestire (sqlite3.IntegrityError per un duplicato), e lascia esplodere le altre. Un errore che esplode subito si trova in cinque minuti, uno inghiottito dopo tre settimane.
📜 Log, non print
import logging
log = logging.getLogger(__name__)
log.info("voce aggiunta lista=%s voce=%s", lista_id, voce_id)
Il modulo logging ha livelli (DEBUG, INFO, WARNING, ERROR), timestamp e destinazioni configurabili. In produzione li alzi o li abbassi senza toccare il codice. Mai loggare password, token o dati personali interi.
Abitudini che pagano
- Funzioni corte, che fanno una cosa e hanno un nome che la dice
- Commit piccoli e frequenti, con un messaggio che spiega il perché
- Rileggere il proprio diff prima di ogni commit
- Copiare la struttura del codice che c'è già, anche se faresti diversamente
- Cancellare il codice morto: Git se lo ricorda per te
Abitudini che costano
- Variabili globali modificate da più parti
- Copia-incolla di blocchi da venti righe
- "Lo rendo configurabile, non si sa mai"
- Codice commentato "per sicurezza"
- Riscrivere tutto da capo perché "questa volta lo faccio bene"
Test
Un test è un modo per dire una volta sola "questo deve funzionare così" e farlo controllare alla macchina per sempre.
Unit
Una funzione, isolata. Velocissimi, ne puoi avere centinaia. Ideali per servizi.py.
Integrazione
Più pezzi insieme: endpoint + servizi + database vero (un SQLite temporaneo). Trovano i bug "nelle giunture".
End-to-end
Un browser automatico (Playwright) clicca come un utente. Lenti e fragili: pochi, solo sui percorsi critici come login e aggiunta di una voce.
🧪 pytest su ListaSpesa
from fastapi.testclient import TestClient
from listaspesa.main import app
client = TestClient(app)
def test_quantita_negativa_rifiutata(sessione_di_renzo):
r = client.post(
"/api/liste/1/voci",
json={"nome": "latte", "quantita": -2},
cookies=sessione_di_renzo,
)
assert r.status_code == 422
def test_non_vedo_le_liste_degli_altri(sessione_di_renzo):
r = client.get("/api/liste/2/voci", cookies=sessione_di_renzo) # lista di un altro
assert r.status_code == 404
def test_senza_login_niente():
r = client.get("/api/liste/1/voci")
assert r.status_code == 401
sessione_di_renzo è una fixture: una funzione in tests/conftest.py che prepara un database temporaneo, crea Renzo Panocia con la sua lista e restituisce il cookie di sessione. pytest la passa da solo a ogni test che la chiede per nome.
🎯 Cosa testare
- I permessi. Il test "non vedo le liste degli altri" vale più di dieci test sulla formattazione.
- I casi limite: lista vuota, nome di 100 caratteri, quantità zero, utente cancellato.
- Ogni bug trovato: prima scrivi il test che lo riproduce e fallisce, poi correggi. Quel bug non tornerà più.
- Le regole di business, cioè quello che sta in
servizi.py.
🚫 Cosa non serve testare
- Che FastAPI sappia fare il routing, o che SQLite sappia salvare: lo testano già loro
- Getter e setter banali
- Il 100% di copertura come obiettivo in sé: diventa un gioco a gonfiare il numero
Una buona domanda da farsi: "se questo si rompe, me ne accorgo prima dell'utente?"
Sicurezza del codice
Non serve essere esperti di sicurezza per evitare i buchi più comuni. Serve conoscerli e non fare le cinque o sei cose che li aprono.
🧠 Il principio di fondo
Tutto quello che arriva da fuori è ostile finché non dimostri il contrario. Parametri dell'URL, corpo JSON, cookie, header, nomi di file caricati, persino i dati nel database se li ha scritti un utente. L'OWASP Top 10, la classifica di riferimento delle vulnerabilità web, è in gran parte una lista di modi diversi di dimenticarsene.
💉 SQL injection
Se costruisci la query incollando stringhe, l'utente può scrivere SQL al posto tuo.
email = richiesta["email"] # l'utente scrive: ' OR '1'='1
conn.execute(f"SELECT * FROM utenti WHERE email = '{email}'")
# diventa: SELECT * FROM utenti WHERE email = '' OR '1'='1' → tutti gli utenti
conn.execute("SELECT * FROM utenti WHERE email = ?", (email,))
# il driver passa email come DATO, mai come codice SQL
La regola non ha eccezioni: mai f-string, + o % per costruire SQL con dati esterni. Gli ORM parametrizzano da soli, finché non usi le loro funzioni per l'SQL "grezzo".
🦠 XSS: HTML iniettato nella pagina
Se Renzo Panocia chiama una voce <img src=x onerror="fetch('/api/liste/7',{method:'DELETE'})"> e la pagina la inserisce come HTML, quel codice gira nel browser di tutti gli altri membri della lista, con la loro sessione e i loro permessi.
li.innerHTML = voce.nome; // JS: interpreta come HTML
{{ voce.nome | safe }} {# Jinja2: "fidati, è sicuro" #}
li.textContent = voce.nome; // JS: è testo, punto
{{ voce.nome }} {# Jinja2 con autoescape: < diventa < #}
FastAPI e Django attivano l'autoescape nei template HTML. Il problema nasce quando lo spegni con | safe o Markup(). Come seconda difesa aggiungi un header Content-Security-Policy, che impedisce al browser di eseguire script non autorizzati.
🚪 Controllo degli accessi rotto: il numero uno
È la vulnerabilità più diffusa e la più banale: l'utente è autenticato, ma nessuno controlla che la risorsa sia sua.
@router.get("/liste/{lista_id}/voci")
def elenco(lista_id: int, utente: Utente = Depends(utente_corrente)):
return db.voci_della_lista(lista_id) # /liste/1, /liste/2, /liste/3...
@router.get("/liste/{lista_id}/voci")
def elenco(lista_id: int, utente: Utente = Depends(utente_corrente)):
if not servizi.e_membro(utente.id, lista_id):
raise HTTPException(404)
return db.voci_della_lista(lista_id)
Si chiama IDOR (Insecure Direct Object Reference). Si trova cambiando un numero nell'URL, quindi lo trova chiunque. Ogni endpoint che riceve un id deve chiedersi "di chi è questa cosa?". È anche il test più importante da scrivere (cap. 9).
🔑 Password: mai in chiaro, mai hash veloci
Non si salva la password, ma un suo hash calcolato con un algoritmo apposta lento e con salt: Argon2id (consigliato), scrypt o bcrypt. MD5 e SHA-256 "liscio" sono velocissimi, ed è proprio questo il problema: chi ruba il database prova miliardi di password al secondo.
from argon2 import PasswordHasher
from argon2.exceptions import VerifyMismatchError
ph = PasswordHasher() # Argon2id con parametri sensati di default
def hash_password(password: str) -> str:
return ph.hash(password) # il salt è incluso nella stringa risultante
def password_corretta(hash_salvato: str, tentativo: str) -> bool:
try:
return ph.verify(hash_salvato, tentativo)
except VerifyMismatchError:
return False
Ancora meglio: se puoi, non gestire tu le password. "Accedi con un link via email" o un provider OIDC tolgono di mezzo un'intera categoria di problemi. In ogni caso aggiungi un limite ai tentativi di login.
🤫 Segreti
- Mai nel codice, mai su Git, nemmeno in un repository privato
.envnel.gitignoredal primo commit,.env.examplecon valori finti- Se un segreto finisce in un commit, consideralo bruciato e cambialo: cancellare il commit non basta
- Per token e chiavi usa
secrets.token_urlsafe(32), mairandom, che è prevedibile
📦 Dipendenze (supply chain)
- Ogni pacchetto che aggiungi è codice di sconosciuti che gira con i tuoi permessi
- Controlla il nome prima di installare: esistono pacchetti finti con nomi quasi uguali (typosquatting)
uv run pip-auditcerca le vulnerabilità note nelle tue dipendenze- File di lock nel repo e aggiornamenti regolari, non uno all'anno con 80 pacchetti insieme
🐍 Le trappole tipiche di Python
| Pericoloso | Perché | Al suo posto |
|---|---|---|
subprocess.run(f"convert {nome}", shell=True) | con nome = "x; rm -rf ~" esegue comandi arbitrari | subprocess.run(["convert", nome]), lista di argomenti e niente shell |
pickle.loads(dati_utente) | deserializzare pickle può eseguire codice | JSON |
yaml.load(testo) | può costruire oggetti Python arbitrari | yaml.safe_load(testo) |
eval() / exec() su input | esegue qualsiasi cosa | quasi mai serve davvero. ast.literal_eval per i letterali |
open(CARTELLA / nome_file) | ../../etc/passwd (path traversal) | genera tu il nome del file e verifica che il percorso risolto resti dentro la cartella |
debug=True in produzione | stack trace e dettagli interni mostrati a chiunque | debug solo da variabile d'ambiente, spento di default |
🛡️ Difesa in profondità
Nessuna difesa è perfetta, quindi se ne mettono più d'una: validazione nel backend e vincoli nel database, escaping e CSP, autenticazione e controllo di appartenenza, firewall e servizi in ascolto solo su localhost. Così quando un livello cede, il successivo regge.
🔒 Minimo privilegio
L'app gira con un utente di sistema dedicato, non root. L'utente del database può leggere e scrivere le sue tabelle, non cancellare il database. Il container ha il filesystem in sola lettura. Ogni permesso in meno è un danno in meno quando qualcosa va storto. Per isolare il processo leggi AppArmor.
timestamp + id. Usa librerie mature (argon2-cffi, cryptography, il modulo secrets) e le funzioni di sicurezza già pronte del framework.
Il ciclo di sviluppo
Non si va dall'idea al rilascio in linea retta. Si gira in tondo, a cerchi piccoli e veloci.
Idea
Una storia utente presa dalla lista, la più piccola che porta valore
Branch
git switch -c voce-quantita, un ramo per una cosa
Codice + test
Piccoli passi, test che passano, commit frequenti
Review
Rileggi il diff. Meglio se lo legge anche un'altra persona.
CI
La macchina lancia lint, type check, test e audit a ogni push
Rilascio
Merge, tag di versione, deploy automatico o con un comando
Osserva
Log ed errori: funziona davvero? Lo usano? Si torna all'inizio.
🌿 Git: il minimo vitale
mainè sempre rilasciabile- Ogni modifica nasce su un branch corto, che vive giorni e non mesi
- Messaggi di commit che spiegano il perché: "Limita la quantità a 99, i numeri a tre cifre rompevano il layout"
- Si fa il merge solo con la CI verde
Tutto il resto lo trovi in Git per Svogliati.
🤖 Cosa fa la CI per te
uv sync --locked # installa esattamente il lock
uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest
uv run pip-audit
Se uno di questi fallisce, il merge non si fa. Come si costruisce la pipeline lo spiega CI/CD per Svogliati.
🔢 Versioni e ambienti
Versionamento semantico MAJOR.MINOR.PATCH: 1.4.2 → 1.4.3 per una correzione, → 1.5.0 per una funzione nuova compatibile, → 2.0.0 quando rompi qualcosa per chi usa la tua API. Accanto tieni un CHANGELOG.md scritto per esseri umani.
| Ambiente | A cosa serve | Dati |
|---|---|---|
| Sviluppo | il tuo portatile, si rompe di continuo ed è normale | finti, generati da uno script |
| Staging | copia fedele della produzione, per provare deploy e migrazioni | finti o anonimizzati |
| Produzione | gli utenti veri | veri: non si toccano a mano |
Per un progetto personale lo staging può essere una VM o un container sul tuo PC. Conta il principio: la prima volta che una migrazione gira non deve essere sui dati veri.
Il dopo: un'app non è mai finita
Il rilascio è l'inizio. Da lì in poi l'app va tenuta in vita, aggiornata e sorvegliata, possibilmente senza che ti rovini i weekend.
👀 Osservabilità
- Log su file o su journald, ruotati, leggibili. Meglio se strutturati (JSON) quando crescono.
- Errori raccolti in un posto solo (Sentry, GlitchTip self-hosted), con lo stack trace e senza dati sensibili
- Health check: un endpoint
/healthche controlla anche il database. Un monitor esterno lo chiama ogni minuto. - Metriche essenziali: richieste al secondo, latenza, errori 5xx
💾 Backup
- Automatici, giornalieri, con più copie storiche
- Almeno una copia fuori dal server
- Per SQLite si usa
sqlite3 listaspesa.db ".backup copia.db", noncpmentre l'app scrive - Prova il ripristino. Un backup mai ripristinato è solo una speranza.
🔄 Aggiornamenti
Python, il framework, le dipendenze e il sistema operativo ricevono patch di sicurezza in continuazione. Uno strumento come Dependabot o Renovate apre da solo le richieste di aggiornamento, la CI le verifica e tu le unisci. Pochi aggiornamenti spesso costano meno di un aggiornamento enorme ogni due anni.
💳 Il debito tecnico
Ogni scorciatoia è un prestito: ti fa consegnare oggi e la ripaghi con gli interessi più avanti. Prendere debito è lecito, a patto di saperlo (un TODO con il motivo, una nota nel tracker) e di ripagarlo un po' alla volta. Ogni tanto dedica un ciclo solo a quello.
📖 Documentazione che serve davvero
- README: cos'è, come si avvia in locale, come si lanciano i test, come si fa il deploy. Se serve chiedere a qualcuno, il README è incompleto.
- Le decisioni: "perché SQLite e non PostgreSQL" in mezza pagina, con la data. Tra un anno nessuno se lo ricorda, tu compreso.
- L'API: FastAPI la genera da sola su
/docs. Con Django usa DRF o drf-spectacular. - Il runbook: cosa fare quando il sito è giù alle 3 di notte, scritto quando sei sveglio e lucido.
Checklist dello svogliato
Da stampare e appendere sopra la scrivania, oppure da ignorare e rileggere dopo il primo incidente.
📋 Prima di scrivere codice
- Problema, utente e criterio di successo scritti in tre righe
- MVP tagliato, il resto finito in
IDEE.md - Entità e relazioni disegnate
- Linguaggio e framework scelti per motivi buoni, al massimo una novità
- Repository Git creato,
.gitignorecon.envdentro
🛠️ Mentre lo scrivi
- Struttura a livelli: api, servizi, db
- Configurazione e segreti dall'ambiente
- ruff, mypy e pytest che girano in locale
- Un test per ogni permesso e per ogni bug corretto
- Commit piccoli, su branch corti
🔐 Sicurezza
- Validazione nel backend su ogni input
- Solo query parametrizzate
- Controllo di appartenenza su ogni endpoint che riceve un id
- Escaping attivo, niente
| safenéinnerHTMLsu dati utente - Password con Argon2id e limite ai tentativi di login
- Cookie
HttpOnly,Secure,SameSite pip-auditpulito, debug spento in produzione
🚀 Prima e dopo il rilascio
- CI verde: lint, tipi, test, audit
- HTTPS, reverse proxy, processo con utente non root
- Backup automatico fuori dal server, ripristino provato
- Health check con monitor esterno
- Errori raccolti in un posto solo
- README che basta a un estraneo per avviare l'app
- Aggiornamenti delle dipendenze programmati
📚 Risorse
- docs.python.org: la documentazione ufficiale, sottovalutata
- fastapi.tiangolo.com: il tutorial di FastAPI, tra i migliori in circolazione
- docs.djangoproject.com: se scegli la strada "batterie incluse"
- owasp.org: Top 10 e Cheat Sheet Series, gratuiti e concreti
- 12factor.net: i principi delle app pensate per il cloud, in una pagina
🔗 Guide collegate
- Git: branch, commit e merge senza piangere
- CI/CD: la pipeline che lancia i controlli al posto tuo
- Docker: impacchettare l'app per farla girare ovunque
- PostgreSQL, MySQL e SQL: quando SQLite non basta più
- UI/UX: un frontend che la gente riesce a usare
- Redis: cache, sessioni e code
- DevOps: chi tiene in piedi tutto questo