Svogliati
🏗️

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.

↓
01 / 13

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

  1. Che problema risolve? In una frase. "I coinquilini comprano il latte in tre e nessuno compra il detersivo."
  2. Chi la usa, e da dove? Dal telefono, al supermercato, con una mano sola e il carrello nell'altra.
  3. 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.

⚠️ Prima di costruire, cerca. Se esiste già un'app che fa il 90% di quello che ti serve, usala. Costruire ha senso quando vuoi imparare, quando il 10% che manca è proprio il punto, o quando i dati devono restare a casa tua. Sono motivi validi tutti e tre, basta dirselo onestamente.
02 / 13

Anatomia di un'applicazione

Quasi tutte le app moderne sono la stessa torta a strati. Cambiano gli ingredienti, non la ricetta.

CLIENTfrontend
browser, app mobile, app desktop
mostra i dati e raccoglie gli input. Non si fida di nessuno e nessuno si fida di lui.
↓↑ HTTPS
APIil contratto
GET /api/liste/7/voci → JSON
l'elenco delle domande che il client può fare e delle risposte che riceve
↓↑
BACKENDserver
Python + FastAPI, sul tuo server
valida, controlla i permessi, applica le regole. Qui stanno le decisioni.
↓↑ SQL
DATABASEpersistenza
SQLite all'inizio, PostgreSQL dopo
la memoria a lungo termine. Se perdi questo strato, hai perso l'app.
🍝 L'analogia del ristorante

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:

  1. Frontend: l'utente tocca la casella. Il JavaScript manda PATCH /api/voci/42 con {"presa": true} e il cookie di sessione.
  2. Backend, autenticazione: "chi sei?" Il cookie corrisponde a una sessione valida di Renzo Panocia.
  3. Backend, autorizzazione: "puoi toccare la voce 42?" La voce sta nella lista 7, e Renzo Panocia è membro della lista 7. Sì.
  4. Backend, validazione: presa è davvero un booleano? Sì.
  5. Database: UPDATE voci SET presa = 1 WHERE id = 42.
  6. Risposta: 200 OK con 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.

💡 Il monolite modulare. Un solo programma, ma diviso dentro in moduli con confini chiari (utenti, liste, voci). Se un giorno un pezzo dovrà diventare un servizio a parte, il confine c'è già. È il compromesso che ti permette di non decidere oggi quello che non sai ancora.
03 / 13

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

VoceRendering lato server (SSR)Single Page App (SPA)
Come funzionaIl 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.
StrumentiJinja2, Django templates, htmx per le parti dinamicheReact, Vue, Svelte, Angular
ProSemplice, veloce al primo caricamento, un solo progetto, un solo linguaggioInterfacce molto interattive, l'API è riusabile per un'app mobile
ControInterazioni complesse (drag & drop, editor) diventano faticoseDue progetti, build step, gestione dello stato, pacchetti npm a centinaia
Per ListaSpesa✅ basta e avanzasolo se poi vuoi l'app nativa con la stessa API
✅ La scelta dello svogliato. Parti con HTML generato dal server e un pizzico di JavaScript, oppure con htmx, che ti fa aggiornare pezzi di pagina con attributi HTML senza scrivere JS. Passa a un framework SPA quando senti il dolore, non prima. Ricordati che "tutti usano React" è un dato sul mercato del lavoro, non sul tuo progetto.

📡 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.

static/lista.js
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
🚨 Il frontend è pubblico. Chiunque può aprire gli strumenti per sviluppatori, leggere il tuo JS, modificarlo e mandare al backend le richieste che vuole con 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.

04 / 13

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?

FrameworkFilosofiaQuando
FastAPIAPI moderne, validazione automatica con Pydantic, documentazione dell'API generata da solaBackend che espone soprattutto JSON. È quello che usiamo qui.
Django"Batterie incluse": ORM, login, pannello admin, migrazioni, form, tutto in scatolaApp web classiche con molte pagine e un pannello di gestione. Meno decisioni da prendere.
FlaskMinimalista, scegli tu ogni pezzoProgetti 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.

RichiestaSignificatoRisposta tipica
GET /api/liste/7/vocielenco delle voci della lista 7200 + array JSON
POST /api/liste/7/vocicrea una voce nella lista 7201 Created
PATCH /api/voci/42modifica parte della voce 42200
DELETE /api/voci/42cancella la voce 42204 No Content
CodiceVuol dire
400 / 422la richiesta è sbagliata o i dati non sono validi (colpa del client)
401non so chi sei: fai il login
403so chi sei, ma questa cosa non puoi farla
404non esiste, oppure non te lo dico che esiste
500il 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.

src/listaspesa/api.py
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.

💡 Perché 404 e non 403? Se rispondi "403, non puoi" a chi chiede la lista 8, gli hai appena confermato che la lista 8 esiste. Con un 404 non scopre nulla. È un dettaglio, ma l'enumerazione delle risorse comincia proprio così.

🍪 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.

05 / 13

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:

utenti
id, email, password_hash, creato_il
una persona che può fare login
↓ molti a molti, tramite membri
membri
utente_id, lista_id, ruolo
chi partecipa a quale lista, e con che ruolo (proprietario, membro)
↓
liste
id, nome, creata_il
"Casa", "Grigliata sabato"
↓ una lista ha molte voci
voci
id, lista_id, nome, quantita, presa
"latte, 2, non ancora presa"

Se il disegno ti viene facile con tabelle e frecce, il tuo problema è relazionale: usa SQL. Capita quasi sempre.

⚖️ SQL o NoSQL?

TipoEsempiBuono per
Relazionale (SQL)SQLite, PostgreSQL, MySQL/MariaDBquasi tutto: dati strutturati, relazioni, transazioni, query flessibili. È la scelta di default.
DocumentaleMongoDBdocumenti dalla forma molto variabile. Spesso un campo JSONB di PostgreSQL fa lo stesso lavoro.
Chiave-valoreRedis, Valkeycache, sessioni, code, contatori. Raramente è il database principale.
Altritime-series, grafi, vettorialiproblemi 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).

src/listaspesa/db.py
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.

⚠️ Vincoli nel database, non solo nel codice. 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.
06 / 13

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

CosaScelte sensateNote
Backend web / APIPython, Go, TypeScript (Node), Java/Kotlin, C#, PHPTutti validi. Conta più l'ecosistema che conosci della velocità del linguaggio.
Frontend webJavaScript / TypeScriptNon c'è scelta: è quello che gira nel browser. TypeScript aggiunge i tipi e ti salva da molti errori.
App mobileKotlin (Android), Swift (iOS), Flutter (Dart), React NativeNativo per la massima integrazione. Flutter o React Native per un solo codice su due piattaforme.
App desktopC#, Rust, Tauri, Electron, QtElectron è comodo ma pesa. Tauri e Rust sono più leggeri.
Script, CLI, automazionePython, Go, BashBash finché sta in una schermata, poi Python. Go se vuoi un binario unico da distribuire.
Dati, analisi, IAPythonL'ecosistema (pandas, numpy, PyTorch) non ha rivali.
Sistemi, prestazioni, embeddedRust, C, C++, GoQuando 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
💡 La regola del "una cosa nuova". In ogni progetto puoi permetterti una sola tecnologia sconosciuta. Se è tutto nuovo (linguaggio, framework, database e hosting) non sai più se un problema dipende da te, dal codice o dallo strumento. Per imparare, fai progetti piccoli in cui la novità è una sola.
07 / 13

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.

da zero a "gira"
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/
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.

src/listaspesa/config.py
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.

08 / 13

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:

api.py
HTTP: parametri, status code, JSON
non sa cos'è SQL
↓
servizi.py
le regole: "un membro può spuntare, solo il proprietario cancella la lista"
non sa cos'è HTTP: la puoi chiamare da una CLI o da un test
↓
db.py
query SQL parametrizzate
non sa niente delle regole

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

✗ indovina cosa fa
def proc(d, f=False):
    r = []
    for x in d:
        if not x[3] or f:
            r.append(x)
    return r
✓ non serve il commento
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

✗ il bug diventa invisibile
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

✓ logging
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"
09 / 13

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

tests/test_api.py
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?"

✅ I test sono la tua rete di sicurezza per cambiare. Senza test, ogni modifica fa paura e il codice si irrigidisce. Con i test puoi rifattorizzare, aggiornare le dipendenze e cambiare database con la ragionevole certezza di non aver rotto nulla. Fanno lavorare più veloce, non più lento.
10 / 13

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.

✗ vulnerabile
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
✓ query parametrizzata
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.

✗ vulnerabile
li.innerHTML = voce.nome;              // JS: interpreta come HTML
{{ voce.nome | safe }}                 {# Jinja2: "fidati, è sicuro" #}
✓ escaping
li.textContent = voce.nome;            // JS: è testo, punto
{{ voce.nome }}                        {# Jinja2 con autoescape: < diventa &lt; #}

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.

✗ chiunque sia loggato legge qualsiasi lista
@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...
✓ controllo di appartenenza
@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.

src/listaspesa/auth.py
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
  • .env nel .gitignore dal primo commit, .env.example con 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), mai random, 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-audit cerca 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

PericolosoPerchéAl suo posto
subprocess.run(f"convert {nome}", shell=True)con nome = "x; rm -rf ~" esegue comandi arbitrarisubprocess.run(["convert", nome]), lista di argomenti e niente shell
pickle.loads(dati_utente)deserializzare pickle può eseguire codiceJSON
yaml.load(testo)può costruire oggetti Python arbitrariyaml.safe_load(testo)
eval() / exec() su inputesegue qualsiasi cosaquasi 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 produzionestack trace e dettagli interni mostrati a chiunquedebug 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.

🚨 Mai inventare la crittografia. Niente cifratura fatta in casa, niente "offusco la password con base64", niente token costruiti con timestamp + id. Usa librerie mature (argon2-cffi, cryptography, il modulo secrets) e le funzioni di sicurezza già pronte del framework.
11 / 13

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

quello che la pipeline lancia a ogni push
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.

AmbienteA cosa serveDati
Sviluppoil tuo portatile, si rompe di continuo ed è normalefinti, generati da uno script
Stagingcopia fedele della produzione, per provare deploy e migrazionifinti o anonimizzati
Produzionegli utenti veriveri: 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.

🤖 E l'IA che scrive codice? È un acceleratore notevole, ma il codice resta tuo: lo rileggi, lo capisci e lo testi come se l'avesse scritto un collega junior molto veloce e molto sicuro di sé. Attenzione in particolare a dipendenze inventate o con nomi sbagliati e a controlli di sicurezza "dimenticati". Come usarla bene lo trovi in Claude Code per Svogliati.
12 / 13

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 /health che 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", non cp mentre 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.
💡 Quando fermarsi. Anche spegnere un'app è una scelta legittima. Se nessuno la usa, ogni mese che resta online è manutenzione, superficie d'attacco e costi. Esporta i dati per chi li vuole, annuncia la data, spegni. Il codice resta su Git.
13 / 13

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, .gitignore con .env dentro

🛠️ 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 | safe né innerHTML su dati utente
  • Password con Argon2id e limite ai tentativi di login
  • Cookie HttpOnly, Secure, SameSite
  • pip-audit pulito, 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
🏗️
Regola finale dello svogliato: un'app piccola, noiosa, finita e online batte sempre un'architettura bellissima rimasta in una cartella. Parti semplice, proteggi gli input, scrivi i test per le cose che fanno paura, fai i backup. Tutto il resto, microservizi, Kubernetes e il framework del mese, lo aggiungi solo quando un problema vero te lo chiede.