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:
| cerco | registro | restituisco | |
|---|---|---|---|
| la tabella e il modello | 1 | 2 | 3 |
| gli stampi | 4 | 5 | 6 |
| la rotta | 7 | 8 | 9 |
| il test | 10 | 11 | 12 |
A fette, una funzione alla volta:
| cerco | registro | restituisco | |
|---|---|---|---|
| la tabella e il modello | 1 | 5 | 9 |
| gli stampi | 2 | 6 | 10 |
| la rotta | 3 | 7 | 11 |
| il test | 4 | 8 | 12 |
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.
Per ogni passo c'è una prova: una cosa che puoi guardare, per sapere che è andato.
| Passo | Cosa fai | La prova |
|---|---|---|
| 1 · La riga | Scegli una riga della tabella delle rotte | La dici in una frase: «GET /oggetti: gli oggetti in deposito» |
| 2 · La tabella e il modello | Controlli che schema.sql abbia la tabella e che modelli.py la ricopi | psql -d ritrovato -c "SELECT count(*) FROM oggetti" risponde con un numero |
| 3 · Gli stampi | In schemi.py scrivi solo quelli che la rotta usa | python -c "from app.schemi import Oggetto" non dà errori |
| 4 · Il test | Scrivi 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 rotta | Il file in app/rotte/, il router in app/main.py | Il test diventa verde |
6 · /docs | Provi la rotta a mano, sul tuo database | La 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 commit | git 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| Azione | Richiesta | Mando → Ricevo | Codici | Login |
|---|---|---|---|---|
| Cerco gli oggetti | GET /oggetti?stazione_id=3&categoria=ombrelli | niente → gli oggetti in deposito | 200 | no |
| La scheda | GET /oggetti/{oggetto_id} | niente → l'oggetto, senza segno particolare | 200, 404 | no |
| Le stazioni, per il filtro | GET /stazioni | niente → le stazioni | 200 | no |
| Registro un oggetto | POST /oggetti | l'oggetto → l'oggetto con il suo id | 201, 422 | sì |
| Restituisco | POST /oggetti/{oggetto_id}/restituzioni | nome, ultime cifre → la restituzione | 201, 404, 409, 422 | sì |
| Login | POST /login | email, password → il biglietto | 200, 401 | no |
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:
- Leggere prima di scrivere. Una rotta che legge non rompe niente: se sbagli, sbagli una risposta. Una che scrive può sporcare il database.
- Una tabella prima di due. Meno cose si toccano, meno sospetti ci sono.
- 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 pezzo | Perché adesso |
|---|---|---|
| 0 | Lo scheletro del capitolo 4 | /salute verde, database collegato |
| 1 | GET /stazioni | La più piccola che c'è: una tabella, niente filtri, niente 404. Serve a provare il giro |
| 2 | GET /oggetti | È la funzione «cerco». Legge una tabella sola |
| 3 | GET /oggetti con i filtri | Gli stessi dati, ristretti: un where alla volta |
| 4 | GET /oggetti/{oggetto_id} | La scheda: l'id e il 404 |
| 5 | POST /oggetti | È la funzione «registro»: la prima che scrive, in una tabella sola |
| 6 | POST /oggetti/{oggetto_id}/restituzioni | È la funzione «restituisco»: scrive in due tabelle, e può dire 409. La più difficile |
| 7 | Il login e chi può fare cosa | Vedi sotto |
| 8 | Le 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:
| Condizione | Cosa dice |
|---|---|
| Il test è verde | Il codice fa quello che hai scritto nel test |
L'hai provato in /docs | Quello che hai scritto nel test è la cosa giusta |
| È nel commit | Puoi 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:
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 mainUn 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:
- ha un nome:
ADDETTO_FINTO, non un1sparso nel codice; - ha un commento
FINTO, che dice cosa verrà al suo posto; - sta in un posto solo, e tutte le rotte lo importano.
# 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.# 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 filtri | La rotta senza filtri. Poi un filtro. Poi il secondo |
Il POST | Una rotta che risponde 201 e restituisce il corpo, senza scrivere. Poi, la scrittura |
| Una rotta che dà 500 | Il test che la chiama, e il traceback letto dal basso (Leggere un traceback) |
| Un test che non so scrivere | Prima la prova a mano in /docs; poi la stessa richiesta, in un client.get(...) |
| Non so quale pezzo fare | Il primo della tabella dell'ordine dei lavori che non è ancora nel commit |
| Ho rotto quello che funzionava | git 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 soloLa 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 cosaOgni 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
FINTOe un posto solo. - Quando ti blocchi, fai il pezzo più piccolo.