Depends, da zero
Un controllo scritto una volta, e una riga per rotta
- 15 minuti di lettura
Nel capitolo 2 hai scritto il controllore della chiave, e l'hai attaccato a una rotta con una riga che sembrava magica: fornitore: str = Depends(controlla_chiave). La stessa riga tornerà in tutti i capitoli dopo questo, con utente_corrente al posto di controlla_chiave. Se ti è rimasta addosso la domanda «ma chi chiama chi?», è normale: è il punto dove quasi tutti si bloccano.
Qui la prendiamo da zero, lentamente, con un solo esempio piccolo: il magazzino ricambi del deposito, e la sua chiave.
Il problema: lo stesso controllo, due volte
Il magazzino ha due rotte: le scorte (/magazzino) e gli ordini in arrivo (/ordini). Tutte e due devono rispondere solo a chi manda la chiave giusta. Senza Depends, il controllo lo scrivi dentro ognuna:
from fastapi import FastAPI, Header, HTTPException
app = FastAPI(title="Il magazzino ricambi")
CHIAVE_MAGAZZINO = "6085ac6ded1fa2505cd0b84cdfac423a" # di prova: quella vera sta nel .env
SCORTE = {"guarnizione-P12": 140, "fusibile-F5": 62, "faro-led-M": 9}
ORDINI = [{"ricambio": "faro-led-M", "quantita": 50}, {"ricambio": "fusibile-F5", "quantita": 100}]
@app.get("/magazzino")
def leggi_magazzino(chiave: str | None = Header(default=None, alias="X-API-Key")) -> dict:
if chiave is None:
raise HTTPException(status_code=401, detail="Manca la chiave")
if chiave != CHIAVE_MAGAZZINO:
raise HTTPException(status_code=401, detail="Chiave sbagliata")
return {"scorte": SCORTE}
@app.get("/ordini")
def leggi_ordini(chiave: str | None = Header(default=None, alias="X-API-Key")) -> dict:
if chiave is None:
raise HTTPException(status_code=401, detail="Manca la chiave")
if chiave != CHIAVE_MAGAZZINO:
raise HTTPException(status_code=401, detail="Chiave sbagliata")
return {"ordini": ORDINI}Funziona. Guarda però le righe in mezzo: i due if sono identici, copiati. Con due rotte è fastidioso. Con dieci è un problema vero, per due motivi.
Il primo. Il giorno che devi cambiare il controllo, lo cambi dappertutto. Ernesto Pozzi, il capo deposito, preferisce il messaggio «Chiave non valida». Lo cambi in /magazzino e ti dimentichi di /ordini:
curl -s http://127.0.0.1:8000/magazzino -H "X-API-Key: abc123"
curl -s http://127.0.0.1:8000/ordini -H "X-API-Key: abc123"{"detail":"Chiave non valida"}
{"detail":"Chiave sbagliata"}Stessa chiave sbagliata, due messaggi diversi. Nessun errore, nessun test rosso: il programma funziona, solo che dice cose diverse a seconda della porta.
Il secondo è peggio. Scrivi una terza rotta e ti dimentichi di copiare il controllo: quella porta resta aperta a tutti, senza nessun errore che te lo dica. Un controllo di sicurezza scritto a mano in ogni rotta è un controllo che prima o poi manca.
Una funzione sola, una riga per rotta
La cura è scrivere il controllo una volta, in una funzione, e dire a ogni rotta: «prima di partire, chiama quella».
from fastapi import Depends, FastAPI, Header, HTTPException
app = FastAPI(title="Il magazzino ricambi")
CHIAVE_MAGAZZINO = "6085ac6ded1fa2505cd0b84cdfac423a" # di prova: quella vera sta nel .env
FORNITORE = "Valdora Ricambi"
SCORTE = {"guarnizione-P12": 140, "fusibile-F5": 62, "faro-led-M": 9}
ORDINI = [{"ricambio": "faro-led-M", "quantita": 50}, {"ricambio": "fusibile-F5", "quantita": 100}]
def controlla_chiave(chiave: str | None = Header(default=None, alias="X-API-Key")) -> str:
if chiave is None:
raise HTTPException(status_code=401, detail="Manca la chiave")
if chiave != CHIAVE_MAGAZZINO:
raise HTTPException(status_code=401, detail="Chiave sbagliata")
return FORNITORE
@app.get("/magazzino")
def leggi_magazzino(fornitore: str = Depends(controlla_chiave)) -> dict:
return {"fornitore": fornitore, "scorte": SCORTE}
@app.get("/ordini")
def leggi_ordini(fornitore: str = Depends(controlla_chiave)) -> dict:
return {"fornitore": fornitore, "ordini": ORDINI}Le richieste sono quelle del capitolo 2: senza chiave, con una chiave sbagliata, con quella giusta. In più, la stessa chiave sull'altra rotta.
curl -s http://127.0.0.1:8000/magazzino
curl -s http://127.0.0.1:8000/magazzino -H "X-API-Key: abc123"
curl -s http://127.0.0.1:8000/magazzino -H "X-API-Key: 6085ac6ded1fa2505cd0b84cdfac423a"
curl -s http://127.0.0.1:8000/ordini -H "X-API-Key: 6085ac6ded1fa2505cd0b84cdfac423a"{"detail":"Manca la chiave"}
{"detail":"Chiave sbagliata"}
{"fornitore":"Valdora Ricambi","scorte":{"guarnizione-P12":140,"fusibile-F5":62,"faro-led-M":9}}
{"fornitore":"Valdora Ricambi","ordini":[{"ricambio":"faro-led-M","quantita":50},{"ricambio":"fusibile-F5","quantita":100}]}I messaggi ora sono scritti in un posto solo. Cambiarli è una modifica. Una terza rotta si protegge con una riga.
Depends vuol dire «dipende da»: questa rotta dipende da quella funzione. Prima parte la funzione, poi la rotta.
Cosa fa FastAPI, passo per passo
Tu non chiami mai controlla_chiave. La chiama FastAPI, a ogni richiesta, prima della rotta. Ecco cosa succede quando arriva GET /magazzino:
I passi, a parole:
- FastAPI legge il
defdella rotta. Vede il parametrofornitore: str = Depends(controlla_chiave): per riempirlo, prima deve chiamare quella funzione. - Chiama
controlla_chiave. Anche i parametri del controllore li riempie lui, come per una rotta:chiaveè unHeader, quindi va a leggere l'headerX-API-Keydella richiesta. - Se il controllore fa
raise, finisce tutto lì. La risposta è il 401, e la rotta non parte nemmeno: il suo codice non viene eseguito. Lo vedi con i tuoi occhi nell'esempio A degli esercizi spiegati. - Se il controllore fa
return, si va avanti. Il valore restituito ("Valdora Ricambi") finisce nel parametrofornitore. Poi parte la rotta, che trova il parametro già pieno.
Quindi la risposta a «chi passa chiave al controllore?» è: nessuno di voi due. Lo passa FastAPI, leggendo la richiesta.
Anche il controllore ha parametri come una rotta
I parametri di controlla_chiave vengono riempiti come quelli di una rotta: stessa tabella che hai visto nel capitolo 2. Una dipendenza può avere un parametro dal percorso, dalla query, dal corpo, dagli header. E può averne uno che è a sua volta un Depends. Per questo il controllore delle chiavi riceve un header, e quello dei biglietti ne riceverà un altro.
Tre funzioni, una sola idea
Una dipendenza prepara qualcosa per la rotta, oppure la ferma prima che parta. A volte tutte e due. Ne hai già incontrate due, e una la incontrerai:
Nel def della rotta | Cosa fa, prima della rotta | Cosa riceve la rotta | Può fermarla? |
|---|---|---|---|
db: Session = Depends(get_db) | apre una sessione con il database | la sessione, per lavorare | no |
fornitore: str = Depends(controlla_chiave) | controlla la chiave nell'header | il nome del fornitore | sì: 401 |
utente: UtenteSalvato = Depends(utente_corrente) | controlla il biglietto, cerca l'utente | l'utente, tutta la riga | sì: 401 |
La prima la conosci dal capitolo sulla sessione. La seconda l'hai appena scritta. La terza la scrivi nel capitolo 6: qui ti basta vedere che ha la stessa forma delle altre due.
Le tre regole
1. Si scrive nel def, come un parametro. Un nome, un tipo, = Depends(funzione):
fornitore: str = Depends(controlla_chiave)2. Senza parentesi. Dai a FastAPI la funzione, e la chiama lui, al momento giusto:
Depends(controlla_chiave) # giusto: la funzione
Depends(controlla_chiave()) # sbagliato: la chiami tu, subito3. Il parametro vale il return. Dentro la rotta, fornitore è quello che controlla_chiave ha restituito:
@app.get("/magazzino")
def leggi_magazzino(fornitore: str = Depends(controlla_chiave)) -> dict:
return {"fornitore": fornitore, "scorte": SCORTE}Se il controllore finisce senza return, Python restituisce None e il parametro vale None: la rotta risponde 200 con "fornitore": null, e nessun errore ti avvisa. Lo vedi nell'esempio B.
In più, una cosa da non dimenticare: la funzione con Depends non ha @app. Non è una rotta: nessuno la chiama con un indirizzo.
Una dipendenza dentro l'altra
Una dipendenza può dipendere da un'altra. Il controllore dei biglietti, che scrivi nel capitolo 6, lo fa:
def utente_corrente(header: HTTPAuthorizationCredentials | None = Depends(controllore)) -> UtenteSalvato:Dentro le parentesi c'è Depends(controllore): controllore è la funzione che legge l'header Authorization e lo spezza in due. utente_corrente la usa, e si trova l'header già pronto. (Con il database ce n'è anche una seconda, Depends(get_db): una funzione può dipendere da quante ne servono.)
Così la richiesta passa per tre mani, una dopo l'altra:
la richiesta
│
▼
controllore legge l'header Authorization
│ l'header
▼
utente_corrente guarda il biglietto, cerca l'utente
│ l'utente
▼
la rotta riceve l'utente nel parametroTu non coordini niente. FastAPI risolve la catena da solo, dal basso verso l'alto: prima quello da cui dipendono tutti, poi quello che ne dipende, poi la rotta. Se un anello fa raise, la catena si ferma lì e gli anelli dopo non partono. Lo vedi girare, con tre scritte che escono nell'ordine, nell'esempio D.
Depends non è solo sicurezza
Finora Depends ha controllato qualcosa. Ma può anche solo preparare qualcosa che serve a molte rotte. Un caso comune: gli elenchi lunghi si chiedono a pagine, con due parametri della query, limite e salta. Scritti in ogni rotta sarebbero la stessa copia di prima. Scritti una volta:
from fastapi import Depends, FastAPI
app = FastAPI(title="L'archivio della Linea Menta")
TRENI = ["M12", "M14", "M16", "M18", "M20", "M22", "M24"]
STAZIONI = ["Porta Codice", "Vecchia Fiera", "Ponte Vecchio", "Largo Variabili", "Via dei Tipi"]
def paginazione(limite: int = 3, salta: int = 0) -> dict[str, int]:
return {"limite": limite, "salta": salta}
@app.get("/treni")
def leggi_treni(pagina: dict[str, int] = Depends(paginazione)) -> list[str]:
return TRENI[pagina["salta"] : pagina["salta"] + pagina["limite"]]
@app.get("/stazioni")
def leggi_stazioni(pagina: dict[str, int] = Depends(paginazione)) -> list[str]:
return STAZIONI[pagina["salta"] : pagina["salta"] + pagina["limite"]]paginazione non ferma niente e non fa raise: restituisce un piccolo dizionario. I suoi parametri sono della query, e FastAPI li riempie leggendo l'indirizzo.
curl -s http://127.0.0.1:8000/treni
curl -s "http://127.0.0.1:8000/treni?limite=2&salta=4"
curl -s "http://127.0.0.1:8000/stazioni?salta=3"["M12","M14","M16"]
["M20","M22"]
["Largo Variabili","Via dei Tipi"]Le due rotte usano la stessa funzione, e la stessa regola per le pagine vale per tutte: se un giorno il limite predefinito diventa 20, lo cambi in un punto. È nella palestra, con tre elenchi.
Quando il valore non serve
A volte la rotta vuole solo che il controllo avvenga, e il nome di chi bussa non le serve. Tenere un parametro fornitore che nessuno legge è rumore. Si può dire a FastAPI di chiamare la dipendenza senza darne il valore, con dependencies=[…] nel decoratore:
@app.post("/sirena", dependencies=[Depends(controlla_chiave)])
def suona_la_sirena() -> dict:
return {"sirena": "suonata"}Il controllo parte prima della rotta, come sempre, e se fa raise la rotta non parte. Ma nel def non c'è nessun parametro.
E se le rotte da proteggere sono tante, la stessa riga sta sul router: un gruppo di rotte con lo stesso prefisso (APIRouter è spiegato in La cartella del progetto).
router = APIRouter(prefix="/detersivi", dependencies=[Depends(controlla_chiave)])Ogni rotta di quel router è protetta, anche quelle che aggiungerai tra un mese. Quelle fuori dal router restano come sono. Lo provi nell'esempio E.
yield: quello che c'è dopo la rotta
Hai già visto get_db, che usa yield al posto di return. Nel capitolo sulla sessione c'è la spiegazione intera. Qui ti serve una cosa sola: quello che scrivi dopo il yield parte quando la rotta ha finito. Serve a chiudere quello che la dipendenza ha aperto: la sessione, un file, una connessione.
from fastapi import Depends, FastAPI
def apri_registro():
print(" apro il registro")
yield "registro aperto"
print(" chiudo il registro")
app = FastAPI(title="Il registro")
@app.get("/turni")
def leggi_turni(registro: str = Depends(apri_registro)) -> dict:
print(f" la rotta lavora: {registro}")
return {"turni": 12}Con una richiesta a GET /turni, nel terminale del server:
apro il registro
la rotta lavora: registro aperto
INFO: 127.0.0.1:63300 - "GET /turni HTTP/1.1" 200 OK
chiudo il registroPrima la parte prima del yield, poi la rotta con il valore del yield nel parametro, e per ultima la parte dopo. Una dipendenza con yield non è un controllore: non decide niente, apre e chiude.
In /docs
Apri http://127.0.0.1:8000/docs, sulla rotta GET /magazzino del capitolo. Tra i parametri compare un campo X-API-Key, di tipo header: l'ha messo FastAPI, perché il controllore ha un parametro Header. È per questo che su /docs la chiave si scrive in quel campo, come hai visto nel capitolo 2. Una dipendenza con parametri compare in /docs come se i parametri fossero della rotta.
Con HTTPBearer, il lettore dei biglietti, è diverso: /docs mostra in alto il lucchetto Authorize, e ogni rotta protetta ne ha uno accanto. Lo incontri nel capitolo 6. La cosa da portare via: se una dipendenza ha un parametro, /docs lo sa.
Le domande che fanno sempre
«Chi passa chiave al controllore?» FastAPI. Quando chiama controlla_chiave guarda i suoi parametri come farebbe con una rotta: Header(alias="X-API-Key") vuol dire «leggi quell'header della richiesta». Né tu né la rotta passate niente.
«Perché scrivo fornitore se poi non lo uso?» Perché Depends sta in un parametro, e un parametro ha un nome. Se la rotta non usa il valore, hai due strade pulite: usarlo (scrivilo nella risposta, come negli esempi) oppure togliere il parametro e mettere dependencies=[Depends(controlla_chiave)] nel decoratore.
«E se due rotte vogliono la chiave?» Scrivono tutte e due Depends(controlla_chiave). La funzione è una sola, le righe nelle rotte sono due. È proprio il senso di tutto il capitolo.
«Perché non Depends(controlla_chiave())?» Perché con le parentesi la chiami tu, subito, senza richiesta, e il programma si ferma prima ancora di partire. Senza parentesi la chiama FastAPI, a ogni richiesta, con la richiesta giusta in mano.
Ricorda
- Un controllo copiato in ogni rotta si cambia dappertutto, e prima o poi manca da qualche parte. Scritto una volta in una funzione, si dimentica meno.
Dependsvuol dire «dipende da»: prima parte la funzione, poi la rotta.- FastAPI chiama la dipendenza e ne riempie i parametri come per una rotta. Un
raiseferma tutto (e la rotta non parte); unreturnfinisce nel parametro. - Tre regole: nel
defcome un parametro; senza parentesi; il parametro vale ilreturn. E la funzione non ha@app. - Una dipendenza può dipendere da un'altra: FastAPI risolve la catena dal basso verso l'alto.
Dependsnon serve solo alla sicurezza: anche a preparare cose (le pagine, la sessione).- Se il valore non serve,
dependencies=[Depends(…)]nel decoratore, o in unAPIRouterper tutte le sue rotte. - Dopo il
yieldparte quello che chiude, a rotta finita. - Il controllore dei biglietti (capitolo 6) è lo stesso schema di
controlla_chiave, con quattro cambi.