Vai al contenuto
code-to-code

Apro l'indice…

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

Il progetto5. Un pezzo alla voltap. 135

Un pezzo alla volta

Dal canvas alla prima rotta che funziona, e poi alla seconda

  • 15 minuti di lettura

Nives Corti ha il canvas di Ritrovato, le quattro tabelle in schema.sql e la cartella con lo scheletro: /salute risponde, il database è collegato. Di rotte vere non ce n'è nemmeno una. Da dove comincia?

Il modo che sembra ordinato: finire tutte le classi del database, poi tutti gli stampi, poi tutte le rotte, e solo alla fine provare. Il modo che funziona è un altro: una funzione sola, sottilissima, da capo a fondo, e poi la seguente.

Il motivo è semplice. Se scrivi dodici cose prima di provarne una, il primo test rosso ha dodici sospetti. Se ne scrivi una per volta, ne ha uno.

Lo scheletro che cammina

Il disegno del progetto si fa tutto insieme, prima del codice: il canvas, le entità, gli attributi, schema.sql (capitoli 1, 2 e 3). È su carta, e cambiarlo costa un minuto. Il disegno si fa tutto insieme, il codice una fetta alla volta.

Una fetta è un pezzo che attraversa tutti gli strati: il modello, lo stampo, la rotta, il test. Ecco le due strade, con tre funzioni di Ritrovato. Il numero dice in che ordine scrivi le cose.

A strati, uno strato dopo l'altro:

cercoregistrorestituisco
la tabella e il modello123
gli stampi456
la rotta789
il test101112

A fette, una funzione alla volta:

cercoregistrorestituisco
la tabella e il modello159
gli stampi2610
la rotta3711
il test4812

A strati, la prima cosa che vedi funzionare è al passo 10, e se è rossa il guaio può stare in nove punti. A fette, dopo il passo 4 hai una funzione che gira, e se il test è rosso il guaio sta nei quattro passi che hai appena fatto. Alla fine arrivi dove arriva l'altra strada, ma sei sempre stato su terreno che avevi provato.

C'è un secondo vantaggio: dopo la prima fetta hai già qualcosa da far vedere. Un progetto che gira a metà è meglio di uno completo che non parte.

Il giro di un pezzo

Ogni fetta ha gli stessi sette passi, nello stesso ordine.

inizio una riga della tabella delle rotte la tabella e il modello: ci sono, e si assomigliano? gli stampi: solo quelli di questa rotta il test: rosso, e per il motivo giusto la rotta, e il suo router montato in main.py se il test è verde no: torna alla rotta la prova in /docs, con i tuoi occhi se la risposta non è quella che volevi sì: torna al test il commit fine il pezzo è fattouna riga della tabella dellerottela tabella e il modello: cisono, e si assomigliano?gli stampi: solo quelli diquesta rottail test: rosso, e per ilmotivo giustola rotta, e il suo routermontato in main.pyil test è verdetorna alla rottala prova in /docs, con ituoi occhila risposta non èquella che volevitorna al testil commitil pezzo è fattonosìnosì
Il giro di un pezzo

Per ogni passo c'è una prova: una cosa che puoi guardare, per sapere che è andato.

PassoCosa faiLa prova
1 · La rigaScegli una riga della tabella delle rotteLa dici in una frase: «GET /oggetti: gli oggetti in deposito»
2 · La tabella e il modelloControlli che schema.sql abbia la tabella e che modelli.py la ricopipsql -d ritrovato -c "SELECT count(*) FROM oggetti" risponde con un numero
3 · Gli stampiIn schemi.py scrivi solo quelli che la rotta usapython -c "from app.schemi import Oggetto" non dà errori
4 · Il testScrivi il test prima della rottaÈ rosso, e dice assert 404 == 200: la rotta non c'è. Non un errore di import o di battitura
5 · La rottaIl file in app/rotte/, il router in app/main.pyIl test diventa verde
6 · /docsProvi la rotta a mano, sul tuo databaseLa risposta è quella che ti aspettavi. Il test dice che il codice fa quello che hai scritto; /docs dice che hai scritto la cosa giusta
7 · Il commitgit add ., git commit -m "…"git status dice nothing to commit, working tree clean

Il test viene prima della rotta per un motivo: se non l'hai mai visto rosso, non sai se può esserlo. Un test che nasce verde potrebbe non controllare niente.

Se hai cambiato schema.sql (la fetta ha bisogno di una colonna in più) l'ordine è uno solo: prima schema.sql, poi modelli.py. schema.sql è la fonte vera: la classe la ricopia, mai il contrario.

Dal riquadro 7 alla tabella delle rotte

Ogni fetta è una riga della tabella delle rotte. La tabella nasce dal canvas: il riquadro 7 («Le azioni»: cosa legge, cosa scrive ogni funzione) e il riquadro 8 («Chi può fare cosa»). Come si passa dall'uno all'altra l'hai già visto, e le cinque regole dei percorsi pure: sta tutto in Il contratto. Qui non lo ripeto, ti mostro solo il risultato per Ritrovato.

Riquadro 7 · le azioni
  registro:     scrivo un oggetto (in deposito)
  cerco:        leggo gli oggetti in deposito, con i filtri
  scheda:       leggo un oggetto, senza il segno particolare
  restituisco:  scrivo una restituzione, e lo stato dell'oggetto diventa «restituito»
  login:        leggo un addetto e controllo la password

Riquadro 8 · chi può fare cosa
  cercare e vedere la scheda: tutti, senza login
  registrare e restituire: solo gli addetti
AzioneRichiestaMando → RicevoCodiciLogin
Cerco gli oggettiGET /oggetti?stazione_id=3&categoria=ombrelliniente → gli oggetti in deposito200no
La schedaGET /oggetti/{oggetto_id}niente → l'oggetto, senza segno particolare200, 404no
Le stazioni, per il filtroGET /stazioniniente → le stazioni200no
Registro un oggettoPOST /oggettil'oggetto → l'oggetto con il suo id201, 422sì
RestituiscoPOST /oggetti/{oggetto_id}/restituzioninome, ultime cifre → la restituzione201, 404, 409, 422sì
LoginPOST /loginemail, password → il biglietto200, 401no

Due cose che il riquadro 7 da solo non ti dice.

Una riga viene dalle schermate. GET /stazioni non è un'azione del riquadro 7: nessuno «cerca le stazioni». Ma la schermata «gli oggetti trovati» ha un filtro per stazione, e il filtro ha bisogno dell'elenco delle stazioni. Quando riscrivi la tabella, rileggi anche il riquadro 5: per ogni schermata, tutto quello che le serve arriva da una rotta?

La restituzione sta sotto l'oggetto. Il percorso è /oggetti/{oggetto_id}/restituzioni, al plurale (regola 1, anche se ogni oggetto ne ha al massimo una) e con un livello solo (regola: un livello solo). È una sotto-risorsa perché l'oggetto deve esistere: se non c'è, vuoi un 404.

L'ordine dei lavori

Una fetta per volta, d'accordo. Ma quale per prima? Tre regole:

  1. Leggere prima di scrivere. Una rotta che legge non rompe niente: se sbagli, sbagli una risposta. Una che scrive può sporcare il database.
  2. Una tabella prima di due. Meno cose si toccano, meno sospetti ci sono.
  3. Senza permessi prima che con i permessi. Il login aggiunge una complicazione a ogni rotta: meglio che le rotte funzionino già.

Per Ritrovato, in ordine:

#Il pezzoPerché adesso
0Lo scheletro del capitolo 4/salute verde, database collegato
1GET /stazioniLa più piccola che c'è: una tabella, niente filtri, niente 404. Serve a provare il giro
2GET /oggettiÈ la funzione «cerco». Legge una tabella sola
3GET /oggetti con i filtriGli stessi dati, ristretti: un where alla volta
4GET /oggetti/{oggetto_id}La scheda: l'id e il 404
5POST /oggettiÈ la funzione «registro»: la prima che scrive, in una tabella sola
6POST /oggetti/{oggetto_id}/restituzioniÈ la funzione «restituisco»: scrive in due tabelle, e può dire 409. La più difficile
7Il login e chi può fare cosaVedi sotto
8Le funzioni «se avanza tempo»Solo quando il resto è verde e nel commit

Non è l'ordine del canvas: «registro» è la funzione 1, ma è il quinto pezzo. Si comincia dal pezzo più facile da provare, non da quello che viene prima nel racconto. Per leggere ti servono dei dati: li metti con psql, a mano, o con un file di prova.

Il login dopo le tre funzioni. Il login tocca ogni rotta che scrive e ogni rotta riservata. È più facile aggiungerlo a rotte che già funzionano, con i loro test verdi, che costruire tutto insieme. Come si fa lo trovi in Login e rotte protette; le password in Le password. Dopo il login, le rotte riservate diventano quelle che il riquadro 8 dice.

Le funzioni «se avanza tempo» per ultime, ognuna come una fetta nuova: stesso giro, stessi sette passi. Se per la scadenza non ci arrivi, il progetto è comunque finito: era scritto nel riquadro 4.

Quando un pezzo è fatto

«Quasi fatto» non esiste. Un pezzo è fatto quando succedono tutte e tre queste cose:

CondizioneCosa dice
Il test è verdeIl codice fa quello che hai scritto nel test
L'hai provato in /docsQuello che hai scritto nel test è la cosa giusta
È nel commitPuoi tornare indietro se il pezzo dopo va storto

Un pezzo è fatto quando il test è verde, l'hai provato in /docs ed è nel commit. Due su tre non vale: un test verde che non hai mai guardato in /docs può controllare la cosa sbagliata, e un pezzo che funziona ma non è nel commit sparisce al primo git restore fatto per sbaglio.

Il commit sta in un ramo per funzione, come in Branch e merge:

Terminale
git switch -c cerco-oggetti        # un ramo per funzione
# …i pezzi 2, 3 e 4, ognuno con il suo commit…
git switch main
git merge cerco-oggetti            # la funzione è finita: entra in main

Un ramo, più commit: uno per pezzo. Così git log --oneline si legge come la tabella dell'ordine dei lavori. Mai due pezzi rossi in contemporanea: se il pezzo 3 non è verde, il pezzo 4 non si comincia.

I valori finti, dove arriverà il login

Finché il login non c'è, nessuna rotta sa chi sta scrivendo. Ma oggetti.registrato_da è NOT NULL: un valore ci deve andare. Per ora ci va 1, cioè Nives, che i dati di prova creano per prima.

È un valore finto, ed è permesso, a tre condizioni:

  1. ha un nome: ADDETTO_FINTO, non un 1 sparso nel codice;
  2. ha un commento FINTO, che dice cosa verrà al suo posto;
  3. sta in un posto solo, e tutte le rotte lo importano.
Python
# app/finti.py
"""I valori finti: quello che il login, un giorno, sostituirà. Si cercano con: grep -rn FINTO app/"""

ADDETTO_FINTO = 1  # FINTO: l'addetto che ha fatto il login. Per ora è sempre Nives, la numero 1.
Python
# in app/rotte/oggetti.py
from app.finti import ADDETTO_FINTO

oggetto = OggettoDB(**dati.model_dump(), registrato_da=ADDETTO_FINTO)

Quando arriva il login, un comando elenca tutti i posti da sistemare: grep -rn FINTO app/. Un valore finto ha un nome, un commento e un posto solo. Un 1 messo a caso in tre rotte non lo ritrova nessuno: resta lì, e il giorno dopo ogni oggetto è registrato da Nives.

Lo stesso vale per le rotte che un giorno saranno riservate: sopra il @router.post metti un commento # login: sì, come nella tabella. Poi il login lo cerchi con grep come i valori finti.

Quando ti blocchi

Succede. Una rotta non esce, un test resta rosso, non sai più da dove cominciare. La risposta è sempre la stessa: fai il pezzo più piccolo. Cioè: riduci quello che stai cercando di fare, finché una parte funziona.

Mi blocco su…Il pezzo più piccolo
La rotta con tre filtriLa rotta senza filtri. Poi un filtro. Poi il secondo
Il POSTUna rotta che risponde 201 e restituisce il corpo, senza scrivere. Poi, la scrittura
Una rotta che dà 500Il test che la chiama, e il traceback letto dal basso (Leggere un traceback)
Un test che non so scriverePrima la prova a mano in /docs; poi la stessa richiesta, in un client.get(...)
Non so quale pezzo fareIl primo della tabella dell'ordine dei lavori che non è ancora nel commit
Ho rotto quello che funzionavagit status, poi git restore e riparti dall'ultimo commit: ne avevi fatto uno

L'ultima riga è il motivo per cui si fanno commit piccoli: tornare indietro costa un comando.

Il README.md del progetto

L'ultimo file della cartella è il primo che un altro apre. Un README.md risponde a tre domande: cos'è, come si avvia, a che punto è. Le prime due le ha già quello del capitolo La cartella del progetto: cinque comandi, e chi apre la cartella tra un mese (o il compagno che deve spiegare la tua app) la fa partire senza chiederti niente.

# Ritrovato

Gli oggetti smarriti della Linea Menta: li registra l'ufficio di Porta Codice, li cerca chi ha perso qualcosa.

1. `python3 -m venv .venv`, poi `source .venv/bin/activate` e `pip install -r requirements.txt`
2. `cp .env.example .env`
3. `createdb ritrovato`, poi `psql -d ritrovato -f schema.sql`
4. `fastapi dev app/main.py`, poi nel browser `http://127.0.0.1:8000/docs`
5. `pytest`, dalla cartella `ritrovato/`: il database dei test se lo prepara da solo

La terza domanda la aggiungi tu, in fondo, ed è la tabella dell'ordine dei lavori in versione breve:

## A che punto siamo

- [x] lo scheletro: `/salute`, il database collegato
- [ ] `GET /stazioni`
- [ ] `GET /oggetti` (con i filtri) e `GET /oggetti/{oggetto_id}`
- [ ] `POST /oggetti`
- [ ] `POST /oggetti/{oggetto_id}/restituzioni`
- [ ] il login e chi può fare cosa

Ogni volta che un pezzo è fatto (test, /docs, commit), spunti la riga nello stesso commit: il README non resta mai indietro.

Nella storia di questo capitolo costruisci Ritrovato proprio così, un livello alla volta, sulla cartella del capitolo 4.

Ricorda

  • Il disegno si fa tutto insieme; il codice, una fetta alla volta.
  • Una fetta è un giro di sette passi: la riga, la tabella e il modello, gli stampi, il test rosso, la rotta, /docs, il commit.
  • L'ordine: leggere prima di scrivere, una tabella prima di due, il login dopo le tre funzioni, il «se avanza tempo» per ultimo.
  • Un pezzo è fatto con tre cose: test verde, provato in /docs, nel commit.
  • Un valore finto ha un nome, un commento FINTO e un posto solo.
  • Quando ti blocchi, fai il pezzo più piccolo.