Un pezzo alla volta, esercizi spiegati
Cinque esempi, dalla scelta del primo pezzo al piano dei commit
- 25 minuti di lettura
Cinque esempi, dal più semplice. I primi due si fanno con carta e penna: scegliere da dove cominciare e scrivere la tabella delle rotte. Gli ultimi tre sono un pezzo vero, da capo a fondo, con il codice e i comandi.
Ogni esempio ha lo stesso ritmo:
- Prima di aprire, prova tu: leggi la situazione e scrivi la tua risposta su un foglio. Poi apri la risposta.
- In italiano: cosa si fa, a parole.
- Passo per passo: nel dettaglio.
- Cosa portiamo a casa: la cosa da ricordare.
Non si parla di Ritrovato (la storia è la sua): gli esempi usano la bacheca degli annunci del personale della Linea Menta e il registro delle visite mediche. La palestra, poi, ha un terzo mondo: il campo da padel del dopolavoro.
A · Scegliere il primo pezzo
In sala ristoro, alla Linea Menta, c'è una bacheca di sughero: i turni da scambiare, gli ombrelli trovati, la cena di Natale. Rita, che lavora in biglietteria, vuole portarla online. Ha riempito il canvas. Ecco i riquadri che servono:
Riquadro 4 · le funzioni (indispensabili)
1. pubblico un annuncio (chi lavora sulla linea)
2. leggo gli annunci (tutto il personale)
3. tolgo un annuncio che non serve più (solo chi l'ha scritto)
Riquadro 7 · le azioni
pubblico: scrivo un annuncio
leggo: leggo gli annunci, dal più recente
tolgo: leggo un annuncio per vedere chi l'ha scritto e, se è suo, lo cancello
Riquadro 8 · chi può fare cosa
leggere: tutti
pubblicare: chi ha un account
togliere: solo l'autore dell'annuncioIl progetto ha tre pezzi, più il login. Prima di aprire, prova tu: scrivi i quattro in ordine, dal primo da fare all'ultimo, e per ognuno una riga di motivo. Usa le tre regole dell'ordine dei lavori: leggere prima di scrivere, una tabella prima di due, senza permessi prima che con i permessi.
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
- Leggo gli annunci (
GET /annunci). Legge una tabella sola, non serve nessun permesso, e se sbagli non sporchi niente. I dati per provarlo li metti a mano conpsql. - Pubblico un annuncio (
POST /annunci). È la prima che scrive, ma in una tabella sola. L'autore, per ora, è un valore finto. - Il login. Serve prima del terzo pezzo, non dopo.
- Tolgo un annuncio (
DELETE /annunci/{annuncio_id}). Il canvas dice «solo chi l'ha scritto»: per controllarlo, la rotta deve sapere chi sta chiedendo. Con un autore finto non c'è niente da controllare: il test sarebbe verde su una cosa falsa.
Il caso interessante è l'ultimo. «Tolgo» sembra facile (è una riga di DELETE), e in un ordine ingenuo verrebbe subito dopo «pubblico». Ma dipende dal login: va fatta dopo.
In italiano. Si parte da quello che si prova più facilmente: leggere. Poi si scrive. Poi, quando una funzione ha bisogno di sapere chi sei, si fa il login, e solo dopo si fa la funzione.
Passo per passo.
| Pezzo | Legge o scrive | Quante tabelle | Serve il login? | Quando |
|---|---|---|---|---|
GET /annunci | legge | 1 | no | per primo |
POST /annunci | scrive | 1 | l'autore sì, ma per ora è finto | secondo |
| il login | — | 1 (gli utenti) | — | terzo |
DELETE /annunci/{annuncio_id} | scrive (cancella) | 1 | sì, per il controllo dell'autore | per ultimo |
La tabella delle rotte della bacheca, che serve per scrivere il test di ogni pezzo:
| Azione | Richiesta | Mando → Ricevo | Codici | Login |
|---|---|---|---|---|
| Leggo gli annunci | GET /annunci | niente → gli annunci, dal più recente | 200 | no |
| Pubblico | POST /annunci | titolo, testo → l'annuncio con il suo id | 201, 422 | sì |
| Tolgo | DELETE /annunci/{annuncio_id} | niente → niente | 204, 403, 404 | sì |
Cosa portiamo a casa. L'ordine dei pezzi non è quello del canvas, e nemmeno quello dei verbi: un pezzo che ha bisogno di sapere chi sei viene dopo il login. Quando un pezzo ha una dipendenza, la dipendenza va prima.
B · Da un'azione a una riga della tabella
Il medico aziendale della Linea Menta tiene il registro delle visite mediche su un quaderno: per ogni dipendente, le visite fatte, l'esito, la scadenza della prossima. Quando una scadenza si avvicina, il medico lo ricorda a memoria. Vuole un'app.
Riquadro 6 · le cose
i dipendenti: il nome, il reparto
le visite: quale dipendente, la data, l'esito, la scadenza della prossima
Riquadro 7 · le azioni
1. vedo le visite che scadono entro una certa data
2. vedo lo storico di un dipendente
3. registro l'esito di una visita
4. annullo una visita registrata per errore
Riquadro 8 · chi può fare cosa
il medico fa tutto; il dipendente vede solo il proprio storicoPrima di aprire, prova tu: scrivi la tabella delle rotte (azione, richiesta, mando → ricevo, codici, login). Poi controlla ogni percorso con le cinque regole di Il contratto. Ti aiuto con le tentazioni: per l'azione 1 c'è chi scrive GET /visite/in-scadenza, per la 4 chi scrive POST /visite/{id}/annulla. Cosa non va?
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
| Azione | Richiesta | Mando → Ricevo | Codici | Login |
|---|---|---|---|---|
| 1. Le visite in scadenza | GET /visite?scadenza_entro=2026-12-31 | niente → le visite che scadono entro quel giorno | 200, 422 | sì |
| 2. Lo storico di un dipendente | GET /dipendenti/{dipendente_id}/visite | niente → le sue visite | 200, 404 | sì |
| 3. Registro l'esito | POST /visite | dipendente, data, esito, scadenza → la visita con il suo id | 201, 422 | sì |
| 4. Annullo una visita | DELETE /visite/{visita_id} | niente → niente | 204, 404 | sì |
GET /visite/in-scadenzaviola la regola 4: «in scadenza» restringe una lista, e il filtro sta nella query. In più, il percorso/visite/in-scadenzasembra l'indirizzo di una visita chiamata «in-scadenza».POST /visite/{id}/annullaviola la regola 2: il verbo sta nel percorso. Annullare una visita la fa sparire: è unDELETE.
In italiano. Per ogni azione del riquadro 7 si fa una domanda: legge, crea, cambia o cancella? Il verbo viene da lì. Poi si scrive il percorso con le cinque regole, si decide cosa entra e cosa esce, e si elencano i codici.
Passo per passo.
| Azione | Il verbo | Il percorso | Perché | I codici |
|---|---|---|---|---|
| 1. Le visite in scadenza | legge → GET | /visite + un filtro scadenza_entro | La lista delle visite, ristretta. Senza il filtro, tutte | 200; 422 se la data è scritta male |
| 2. Lo storico | legge → GET | /dipendenti/{dipendente_id}/visite | Le visite di un dipendente: se il dipendente non c'è, vuoi un 404. Quindi sotto-risorsa | 200; 404 |
| 3. Registro l'esito | crea → POST | /visite | Il nome è al plurale, il verbo dice già «crea» | 201; 422 se manca un campo o l'esito non è fra quelli ammessi |
| 4. Annullo | cancella → DELETE | /visite/{visita_id} | L'id nel percorso | 204; 404 se non c'è |
La colonna «Login» è «sì» per tutte, perché sono dati sanitari. Il riquadro 8 aggiunge una finezza: il dipendente può chiamare solo la 2, e solo per il proprio storico. Si scrive come nota sotto la tabella, ed è un lavoro per il login.
Cosa portiamo a casa. Il verbo lo decide l'azione, il percorso dice solo quale cosa. Il filtro sta nella query, la sotto-risorsa nel percorso solo quando la cosa di partenza deve esistere.
C · Un pezzo da capo a fondo
Torniamo alla bacheca: il primo pezzo, GET /annunci. Lo facciamo seguendo i sette passi.
Prima di aprire, prova tu: il primo test rosso dice assert 404 == 200. Poi scrivi la rotta in app/rotte/annunci.py. Rilanci il test: cosa si aspetta Rita? Verde?
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Ancora rosso, con lo stesso 404. La rotta è scritta, ma app/main.py non sa che esiste: manca app.include_router(annunci.router). Il router è un cassetto con le rotte dentro: finché non lo monti, FastAPI non lo apre.
In italiano. Dalla riga della tabella («Leggo gli annunci: GET /annunci») si arriva a una rotta che funziona, passando dalla tabella, dal modello, dallo stampo, dal test rosso, dalla rotta, dal router montato, da /docs e dal commit.
Passo per passo.
1 · La riga. «Leggo gli annunci: GET /annunci, niente → gli annunci dal più recente, 200, nessun login». Una frase.
2 · La tabella e il modello. schema.sql ha già annunci, e modelli.py la ricopia riga per riga (la riga SQL sta nel commento accanto):
CREATE TABLE annunci (
id SERIAL PRIMARY KEY,
titolo TEXT NOT NULL,
testo TEXT NOT NULL,
autore TEXT NOT NULL,
pubblicato_il DATE NOT NULL DEFAULT CURRENT_DATE
);class AnnuncioDB(Base):
__tablename__ = "annunci" # CREATE TABLE annunci
id: Mapped[int] = mapped_column(primary_key=True) # id SERIAL PRIMARY KEY
titolo: Mapped[str] # titolo TEXT NOT NULL
testo: Mapped[str] # testo TEXT NOT NULL
autore: Mapped[str] # autore TEXT NOT NULL
pubblicato_il: Mapped[date] = mapped_column(server_default=func.current_date()) # pubblicato_il DATE NOT NULL DEFAULT CURRENT_DATELa prova: la tabella esiste nel database, e ci sono due annunci di prova.
$ psql -d bacheca -c "SELECT count(*) FROM annunci"
count
-------
2
(1 row)3 · Lo stampo. In schemi.py, solo quello che la rotta usa: la risposta, con l'id e la data.
class Annuncio(BaseModel):
model_config = ConfigDict(from_attributes=True)
id: int
titolo: str
testo: str
autore: str
pubblicato_il: dateLa prova: python -c "from app.schemi import Annuncio" non scrive niente (e non dà errori).
4 · Il test, rosso. In tests/test_annunci.py:
def test_la_bacheca_mostra_gli_annunci(client):
risposta = client.get("/annunci")
assert risposta.status_code == 200
assert [annuncio["titolo"] for annuncio in risposta.json()] == ["Ombrello trovato", "Cambio turno"]I due annunci di prova (nel conftest.py) sono del 10 e del 12 novembre: il più recente, l'ombrello, deve venire prima.
$ pytest -q
F [100%]
=================================== FAILURES ===================================
______________________ test_la_bacheca_mostra_gli_annunci ______________________
client = <starlette.testclient.TestClient object at 0x10b73f050>
def test_la_bacheca_mostra_gli_annunci(client):
risposta = client.get("/annunci")
> assert risposta.status_code == 200
E assert 404 == 200
E + where 404 = <Response [404 Not Found]>.status_code
tests/test_annunci.py:3: AssertionError
=========================== short test summary info ============================
FAILED tests/test_annunci.py::test_la_bacheca_mostra_gli_annunci - assert 404...
1 failed in 0.06sÈ rosso per il motivo giusto: 404, la rotta non c'è. Non un ImportError, non un errore di battitura. Adesso si può scrivere la rotta.
5 · La rotta. Un file nuovo, app/rotte/annunci.py:
from fastapi import APIRouter, Depends
from sqlalchemy import select
from sqlalchemy.orm import Session
from app.database import get_db
from app.modelli import AnnuncioDB
from app.schemi import Annuncio
router = APIRouter(prefix="/annunci", tags=["annunci"])
@router.get("")
def leggi_annunci(db: Session = Depends(get_db)) -> list[Annuncio]:
domanda = select(AnnuncioDB).order_by(AnnuncioDB.pubblicato_il.desc(), AnnuncioDB.id.desc())
return db.scalars(domanda).all()Si rilancia il test: ancora rosso, 404 == 200. È la risposta della previsione. Il router esiste, ma nessuno l'ha collegato. In app/main.py:
from fastapi import FastAPI
from app.rotte import annunci
app = FastAPI(title="Bacheca")
@app.get("/salute")
def salute() -> dict[str, str]:
return {"stato": "ok"}
app.include_router(annunci.router)$ pytest -q
. [100%]
1 passed in 0.18s6 · La prova in /docs. Il test è verde, ma Rita vuole vederla con i suoi occhi, sul suo database bacheca. Si accende il server (fastapi dev app/main.py), si apre http://127.0.0.1:8000/docs, GET /annunci → Try it out → Execute. Lo stesso, da un secondo terminale:
$ curl -s http://127.0.0.1:8000/annunci
[{"id":2,"titolo":"Ombrello trovato","testo":"Chiedete in biglietteria","autore":"Ivo","pubblicato_il":"2026-11-12"},{"id":1,"titolo":"Cambio turno","testo":"Cerco chi mi copre sabato mattina","autore":"Marta","pubblicato_il":"2026-11-10"}]Due annunci, il più recente per primo.
7 · Il commit.
git add .
git commit -m "GET /annunci: la bacheca si legge"Fatto: test verde, provato, nel commit.
Cosa portiamo a casa. Un test rosso per il motivo giusto è il primo passo del pezzo, e ogni passo ha una prova. Una rotta scritta ma non montata dà ancora 404: se la rotta «non c'è», guarda main.py prima di guardare la rotta.
D · Il test che dice «fatto» (troppo presto)
Secondo pezzo della bacheca: POST /annunci. Rita scrive il test così, e poi la rotta:
NUOVO = {"titolo": "Scambio turno", "testo": "Offro il lunedì, cerco il venerdì", "autore": "Rita"}
def test_pubblico_un_annuncio(client):
risposta = client.post("/annunci", json=NUOVO)
assert risposta.status_code == 201@router.post("", status_code=status.HTTP_201_CREATED)
def pubblica_annuncio(dati: AnnuncioNuovo, db: Session = Depends(get_db)):
db.add(AnnuncioDB(**dati.model_dump()))
return datiPrima di aprire, prova tu: il test è verde? E la rotta, funziona?
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
$ pytest -q
. [100%]
1 passed in 0.17sIl test è verde, ma la rotta non funziona. Manca db.commit(): l'annuncio finisce nel carrello e non arriva mai al database. La rotta risponde 201 e restituisce il corpo che le è arrivato, quindi il test non se ne accorge. Rita lo scoprirebbe solo il giorno dopo, quando la bacheca è vuota.
In italiano. Il test dice «la rotta risponde 201». Non dice «l'annuncio è stato salvato». Un test controlla quello che scrivi nell'assert, e basta: se non ci scrivi la cosa importante, il test non la vede.
Passo per passo.
- La prova in
/docssmaschera il test. Si pubblica un annuncio da/docs, si fa GET /annunci: l'annuncio non c'è. Il test era verde, la rotta no. Per questo la regola dice «verde e provato». - Si corregge il test, non la rotta. Un test «fatto» deve guardare dove arriva la cosa: dentro il database. Si aggiunge:
def test_l_annuncio_pubblicato_e_nel_database(client, sql):
client.post("/annunci", json=NUOVO)
assert sql("SELECT titolo, autore FROM annunci WHERE id = %s", (3,)) == [
{"titolo": "Scambio turno", "autore": "Rita"}
]sql(...) guarda nel database senza passare dalla rotta. Il 3 è l'id: gli annunci di prova sono due, il nuovo sarà il terzo.
$ pytest -q
.F [100%]
=================================== FAILURES ===================================
__________________ test_l_annuncio_pubblicato_e_nel_database ___________________
client = <starlette.testclient.TestClient object at 0x10bdd2870>
sql = <function sql.<locals>.chiedi at 0x10bdcec00>
def test_l_annuncio_pubblicato_e_nel_database(client, sql):
client.post("/annunci", json=NUOVO)
> assert sql("SELECT titolo, autore FROM annunci WHERE id = %s", (3,)) == [
{"titolo": "Scambio turno", "autore": "Rita"}
]
E AssertionError: assert [] == [{'titolo': '...ore': 'Rita'}]
E
E Right contains one more item: {'titolo': 'Scambio turno', 'autore': 'Rita'}
E Use -v to get more diff
tests/test_annunci.py:11: AssertionError
=========================== short test summary info ============================
FAILED tests/test_annunci.py::test_l_annuncio_pubblicato_e_nel_database - Ass...
1 failed, 1 passed in 0.20sAdesso il test vede il guaio: [], il database è vuoto.
- Si corregge la rotta. Le quattro mosse di sempre: l'oggetto,
add,commit,refresh. E la risposta è l'annuncio salvato (con l'id), non il corpo arrivato:
@router.post("", status_code=status.HTTP_201_CREATED)
def pubblica_annuncio(dati: AnnuncioNuovo, db: Session = Depends(get_db)) -> Annuncio:
annuncio = AnnuncioDB(**dati.model_dump())
db.add(annuncio)
db.commit()
db.refresh(annuncio)
return annuncio$ pytest -q
.. [100%]
2 passed in 0.19sCosa portiamo a casa. Un test che passa non basta: guarda cosa controlla. Per ogni rotta che scrive, il test deve guardare dentro il database, non solo la risposta. E /docs serve proprio a questo: a smascherare un test che dice «fatto» troppo presto.
E · Il piano dei commit
Torniamo al registro delle visite mediche (esempio B): quattro rotte, e un'app che comincia dal suo scheletro. Il medico vuole che il lavoro sia ordinato: poterne vedere la storia, e poter tornare indietro se un pezzo va storto.
Prima di aprire, prova tu: scrivi il piano. L'ordine dei pezzi (usa le tre regole), il nome di un ramo per funzione, e un messaggio di commit per ogni pezzo. Attenzione: il login e il resto dopo i quattro non c'entrano ancora.
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
| Ordine | Ramo | Commit |
|---|---|---|
| 1 | storico-dipendente | GET /dipendenti/{dipendente_id}/visite: lo storico |
| 2 | scadenze | GET /visite: tutte, in ordine di scadenza, poi GET /visite?scadenza_entro=: il filtro |
| 3 | registro-visita | Stampi di visita: VisitaNuova e Visita, poi POST /visite: registro l'esito |
| 4 | annullo-visita | DELETE /visite/{visita_id}: annullo una visita |
Le due letture vengono per prime (regola 1). Tra le due, lo storico è più semplice: ha un id nel percorso, nessun filtro. Poi si scrive: prima la registrazione, poi la cancellazione (che ha bisogno di una visita da cancellare). In scadenze e in registro-visita i commit sono due: un pezzo grosso si spezza, come nell'esempio C. Un commit dice una cosa sola.
In italiano. Un ramo per ogni funzione, un commit per ogni pezzo (o due, se il pezzo ha un passo intermedio che funziona già). Quando la funzione è finita, il ramo entra in main con un merge.
Passo per passo. Per ogni ramo, gli stessi comandi:
git switch -c storico-dipendente
# …il giro di sette passi, fino al commit…
git switch main
git merge --no-ff storico-dipendente -m "Unisco storico-dipendente"(--no-ff serve solo a far vedere il ramo nel grafo: un merge normale, quando main non è andato avanti, si limita a spostare l'etichetta.) Dopo i quattro rami:
$ git log --oneline --graph
* 3e788d2 Unisco annullo-visita
|\
| * 3bded98 DELETE /visite/{visita_id}: annullo una visita
|/
* a573572 Unisco registro-visita
|\
| * 4cec121 POST /visite: registro l'esito
| * 8cc3ec6 Stampi di visita: VisitaNuova e Visita
|/
* 14ad8be Unisco scadenze
|\
| * e34d03b GET /visite?scadenza_entro=: il filtro
| * f203acb GET /visite: tutte, in ordine di scadenza
|/
* 36f851a Unisco storico-dipendente
|\
| * 0a0701e GET /dipendenti/{dipendente_id}/visite: lo storico
|/
* 456040a Scheletro: /salute e database collegatoSi legge dal basso come il piano: lo scheletro, poi i quattro pezzi nell'ordine deciso. Se oggi il pezzo registro-visita va storto, il ramo è lì, separato: main ha ancora lo storico e le scadenze, che funzionano.
I commit hanno nomi che dicono cosa fa l'app adesso, non cosa hai fatto tu: «GET /visite: tutte», non «ho scritto la rotta» né «modifiche». Fra un mese, rileggendo il log, capisci a che punto eri.
Cosa portiamo a casa. Un ramo per funzione, un commit per pezzo, e il nome del commit dice cosa fa l'app. Il log del progetto si legge come l'ordine dei lavori.