Python Academy · Lezione

Parametri del percorso, parametri query e body delle richieste

Definisca parametri tipizzati e schemi per il body delle richieste con Pydantic.

Parametri del percorso, parametri query e body delle richieste è una lezione Python Academy gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Python Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Python Academy include 4 lezioni in totale.

Validazione dei parametri del percorso

Aggiunga validatori ai parametri del percorso utilizzando Path(): imposti i vincoli ge, le, gt, lt.

from fastapi import FastAPI, Path
app = FastAPI()

@app.get("/items/{item_id}")
def get_item(item_id: int = Path(ge=1, le=1000)):
    return {"item_id": item_id}

# GET /items/0  → 422 (must be >= 1)

Validazione dei parametri di query

Utilizzi Query() per aggiungere ai parametri di query validazione, valori predefiniti, alias e descrizioni.

from fastapi import FastAPI, Query
app = FastAPI()

@app.get("/search")
def search(
    q: str = Query(min_length=2, max_length=50),
    page: int = Query(default=1, ge=1),
):
    return {"q": q, "page": page}

Parametri di query facoltativi

Utilizzi | None = None (Python 3.10+) oppure Optional[str] = None per rendere facoltativo un parametro di query.

from fastapi import FastAPI
app = FastAPI()

@app.get("/users")
def list_users(
    dept: str | None = None,
    active: bool = True
):
    return {"dept": dept, "active": active}

# GET /users → dept=None, active=True
# GET /users?dept=HR&active=false

Più valori per un singolo parametro di query

Accetti un elenco di valori per un singolo parametro di query con list[str] e Query().

from fastapi import FastAPI, Query
from typing import Annotated
app = FastAPI()

@app.get("/filter")
def filter_items(tags: Annotated[list[str], Query()] = []):
    return {"tags": tags}

# GET /filter?tags=python&tags=web

Request body annidati

I modelli Pydantic possono essere annidati. FastAPI gestisce automaticamente i JSON annidati.

from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()

class Address(BaseModel):
    street: str
    city: str

class User(BaseModel):
    name: str
    address: Address

@app.post("/users")
def create_user(user: User):
    return user.model_dump()

Vincoli dei campi in Pydantic

Utilizzi Field() all'interno di un modello per aggiungere vincoli, valori predefiniti e descrizioni ai singoli campi.

from pydantic import BaseModel, Field

class Product(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    price: float = Field(gt=0)
    quantity: int = Field(ge=0, default=0, description="Items in stock")

Request body, percorso e query insieme

Combini tutti e tre i tipi di parametro in un unico endpoint. FastAPI li distingue in base alla posizione: il percorso nell'URL, i tipi semplici nella query e i modelli nel body.

from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()

class ItemUpdate(BaseModel):
    name: str
    price: float

@app.put("/shops/{shop_id}/items/{item_id}")
def update_item(
    shop_id: int,
    item_id: int,
    item: ItemUpdate,
    notify: bool = False,
):
    return {"shop": shop_id, "item": item_id,
            "data": item.model_dump(), "notify": notify}

Upload di file

Utilizzi UploadFile e File() per accettare l'upload di file. Acceda al contenuto con await file.read().

from fastapi import FastAPI, UploadFile, File
app = FastAPI()

@app.post("/upload")
async def upload(file: UploadFile = File(...)):
    content = await file.read()
    return {"filename": file.filename, "size": len(content)}

Dati dei form

Utilizzi Form() per accettare dati provenienti da form HTML (application/x-www-form-urlencoded o multipart/form-data).

# pip install python-multipart
from fastapi import FastAPI, Form
app = FastAPI()

@app.post("/login")
def login(username: str = Form(...), password: str = Form(...)):
    return {"username": username}

Riepilogo della validazione delle richieste

FastAPI convalida automaticamente tutti i tipi di parametro. Gli input non validi restituiscono HTTP 422 con un errore dettagliato prima che venga chiamato il gestore.

# Auto-validated:
# - Path params: type coercion, Path() constraints
# - Query params: Query() constraints, type coercion
# - Request body: Pydantic model validation
# - All errors → HTTP 422 Unprocessable Entity
# - No manual validation needed

Alias e deprecazione

Utilizzi alias= in Query() o Field() per accettare un nome diverso nella richiesta e deprecated=True per contrassegnare i vecchi parametri.

from fastapi import FastAPI, Query
app = FastAPI()

@app.get("/items")
def get_items(
    q: str | None = Query(default=None, alias="search-query"),
    old: str | None = Query(default=None, deprecated=True),
):
    return {"q": q, "old": old}

# GET /items?search-query=python

Verifica rapida

Come distingue FastAPI tra un parametro del percorso, un parametro di query e un request body?

Riepilogo

Utilizzi Path()/Query() per i vincoli dei parametri. Annidi i modelli Pydantic per i body complessi. Combini liberamente i parametri del percorso, di query e del body. UploadFile gestisce i file; Form() gestisce i form HTML. FastAPI convalida ogni elemento prima di eseguire il gestore.

Domande Frequenti

La lezione «Parametri del percorso, parametri query e body delle richieste» è gratuita?

Sì — il testo completo di «Parametri del percorso, parametri query e body delle richieste» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Python Academy, passa a CoddyKit PRO. Il corso Python Academy include 4 lezioni in totale.

Cosa imparerò in «Parametri del percorso, parametri query e body delle richieste»?

Definisca parametri tipizzati e schemi per il body delle richieste con Pydantic. Eserciti Python Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Python Academy?

Non è richiesta alcuna esperienza precedente. Python Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.

Quanto tempo richiede la lezione «Parametri del percorso, parametri query e body delle richieste»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Python Academy?

Sì. Ogni lezione Python Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

Configurazione di un progetto FastAPI e primo endpoint
Parametri del percorso, parametri query e body delle richieste
Dependency injection e autenticazione
Endpoint asincroni e integrazione con il database

← Torna a Python Academy