Vai al contenuto
code-to-code

Apro l'indice…

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

Login e sicurezza3. Depends, da zerop. 58

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:

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

Terminale
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».

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

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

inizio arriva GET /magazzino FastAPI legge il def della rotta trova Depends(controlla_chiave) chiama controlla_chiave, e riempie i suoi parametri: legge l'header X-API-Key se controlla_chiave fa un raise sì: errore 401 e la rotta non parte il return finisce nel parametro fornitore parte la rotta leggi_magazzino restituisci 200 e la rispostaarriva GET /magazzinoFastAPI legge il def dellarottatrovaDepends(controlla_chiave)chiama controlla_chiave, eriempie i suoi parametri:legge l'header X-API-Keycontrolla_chiave faun raise401 e la rotta non parteil return finisce nelparametro fornitoreparte la rottaleggi_magazzinorestituisci 200 e larispostanosì
Cosa fa FastAPI con Depends

I passi, a parole:

  1. FastAPI legge il def della rotta. Vede il parametro fornitore: str = Depends(controlla_chiave): per riempirlo, prima deve chiamare quella funzione.
  2. Chiama controlla_chiave. Anche i parametri del controllore li riempie lui, come per una rotta: chiave è un Header, quindi va a leggere l'header X-API-Key della richiesta.
  3. 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.
  4. Se il controllore fa return, si va avanti. Il valore restituito ("Valdora Ricambi") finisce nel parametro fornitore. 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 rottaCosa fa, prima della rottaCosa riceve la rottaPuò fermarla?
db: Session = Depends(get_db)apre una sessione con il databasela sessione, per lavorareno
fornitore: str = Depends(controlla_chiave)controlla la chiave nell'headeril nome del fornitoresì: 401
utente: UtenteSalvato = Depends(utente_corrente)controlla il biglietto, cerca l'utentel'utente, tutta la rigasì: 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):

Python
fornitore: str = Depends(controlla_chiave)

2. Senza parentesi. Dai a FastAPI la funzione, e la chiama lui, al momento giusto:

Python
Depends(controlla_chiave)       # giusto: la funzione
Depends(controlla_chiave())     # sbagliato: la chiami tu, subito

3. Il parametro vale il return. Dentro la rotta, fornitore è quello che controlla_chiave ha restituito:

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

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

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

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

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

Python
@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).

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

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

Prima 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.
  • Depends vuol dire «dipende da»: prima parte la funzione, poi la rotta.
  • FastAPI chiama la dipendenza e ne riempie i parametri come per una rotta. Un raise ferma tutto (e la rotta non parte); un return finisce nel parametro.
  • Tre regole: nel def come un parametro; senza parentesi; il parametro vale il return. E la funzione non ha @app.
  • Una dipendenza può dipendere da un'altra: FastAPI risolve la catena dal basso verso l'alto.
  • Depends non serve solo alla sicurezza: anche a preparare cose (le pagine, la sessione).
  • Se il valore non serve, dependencies=[Depends(…)] nel decoratore, o in un APIRouter per tutte le sue rotte.
  • Dopo il yield parte quello che chiude, a rotta finita.
  • Il controllore dei biglietti (capitolo 6) è lo stesso schema di controlla_chiave, con quattro cambi.