Vai al contenuto
code-to-code

Apro l'indice…

↑ ↓ per scegliere, Invio per aprire, Esc per chiudere

Il progetto5. Un pezzo alla voltap. 144

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:

  1. Prima di aprire, prova tu: leggi la situazione e scrivi la tua risposta su un foglio. Poi apri la risposta.
  2. In italiano: cosa si fa, a parole.
  3. Passo per passo: nel dettaglio.
  4. 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'annuncio

Il 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.
  1. 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 con psql.
  2. Pubblico un annuncio (POST /annunci). È la prima che scrive, ma in una tabella sola. L'autore, per ora, è un valore finto.
  3. Il login. Serve prima del terzo pezzo, non dopo.
  4. 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.

PezzoLegge o scriveQuante tabelleServe il login?Quando
GET /annuncilegge1noper primo
POST /annunciscrive1l'autore sì, ma per ora è fintosecondo
il login—1 (gli utenti)—terzo
DELETE /annunci/{annuncio_id}scrive (cancella)1sì, per il controllo dell'autoreper ultimo

La tabella delle rotte della bacheca, che serve per scrivere il test di ogni pezzo:

AzioneRichiestaMando → RicevoCodiciLogin
Leggo gli annunciGET /annunciniente → gli annunci, dal più recente200no
PubblicoPOST /annuncititolo, testo → l'annuncio con il suo id201, 422sì
TolgoDELETE /annunci/{annuncio_id}niente → niente204, 403, 404sì

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 storico

Prima 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.
AzioneRichiestaMando → RicevoCodiciLogin
1. Le visite in scadenzaGET /visite?scadenza_entro=2026-12-31niente → le visite che scadono entro quel giorno200, 422sì
2. Lo storico di un dipendenteGET /dipendenti/{dipendente_id}/visiteniente → le sue visite200, 404sì
3. Registro l'esitoPOST /visitedipendente, data, esito, scadenza → la visita con il suo id201, 422sì
4. Annullo una visitaDELETE /visite/{visita_id}niente → niente204, 404sì
  • GET /visite/in-scadenza viola la regola 4: «in scadenza» restringe una lista, e il filtro sta nella query. In più, il percorso /visite/in-scadenza sembra l'indirizzo di una visita chiamata «in-scadenza».
  • POST /visite/{id}/annulla viola la regola 2: il verbo sta nel percorso. Annullare una visita la fa sparire: è un DELETE.

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.

AzioneIl verboIl percorsoPerchéI codici
1. Le visite in scadenzalegge → GET/visite + un filtro scadenza_entroLa lista delle visite, ristretta. Senza il filtro, tutte200; 422 se la data è scritta male
2. Lo storicolegge → GET/dipendenti/{dipendente_id}/visiteLe visite di un dipendente: se il dipendente non c'è, vuoi un 404. Quindi sotto-risorsa200; 404
3. Registro l'esitocrea → POST/visiteIl nome è al plurale, il verbo dice già «crea»201; 422 se manca un campo o l'esito non è fra quelli ammessi
4. Annullocancella → DELETE/visite/{visita_id}L'id nel percorso204; 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.

inizio GET /annunci la tabella annunci e il modello AnnuncioDB lo stampo Annuncio in schemi.py il test: rosso, 404 == 200 la rotta in app/rotte/annunci.py il router montato in app/main.py se il test è verde no: torna alla rotta e al router la prova in /docs il commit fine il pezzo è fattoGET /annuncila tabella annunci e ilmodello AnnuncioDBlo stampo Annuncio inschemi.pyil test: rosso, 404 == 200la rotta inapp/rotte/annunci.pyil router montato inapp/main.pyil test è verdetorna alla rotta e al routerla prova in /docsil commitil pezzo è fattonosì
Il primo pezzo della bacheca

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):

SQL
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
);
Python
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_DATE

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

Python
class Annuncio(BaseModel):
    model_config = ConfigDict(from_attributes=True)

    id: int
    titolo: str
    testo: str
    autore: str
    pubblicato_il: date

La prova: python -c "from app.schemi import Annuncio" non scrive niente (e non dà errori).

4 · Il test, rosso. In tests/test_annunci.py:

Python
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:

Python
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:

Python
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.18s

6 · 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.

Terminale
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:

Python
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
Python
@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 dati

Prima 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.17s

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

  1. La prova in /docs smaschera 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».
  2. Si corregge il test, non la rotta. Un test «fatto» deve guardare dove arriva la cosa: dentro il database. Si aggiunge:
Python
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.20s

Adesso il test vede il guaio: [], il database è vuoto.

  1. 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:
Python
@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.19s

Cosa 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.
OrdineRamoCommit
1storico-dipendenteGET /dipendenti/{dipendente_id}/visite: lo storico
2scadenzeGET /visite: tutte, in ordine di scadenza, poi GET /visite?scadenza_entro=: il filtro
3registro-visitaStampi di visita: VisitaNuova e Visita, poi POST /visite: registro l'esito
4annullo-visitaDELETE /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:

Terminale
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 collegato

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