Hogyan adhat hozzá érvényesítési korlátozásokat a paraméterekhez?

Question

Accepted Answer

A típusellenőrzésen túl a FastAPI lehetővé teszi **korlátozások** hozzáadását az útvonal/lekérdezés paraméterekhez és modellmezőkhöz a `Query`, `Path` és `Field` használatával — olyan szabályok érvényesítésével, mint hossz, tartomány és minta, automatikus 422 hibákkal és dokumentációval a szabálysértés esetén. ## Query és Path korlátozások ```python from fastapi import Query, Path @app.get("/items") def search( q: str = Query(min_length=3, max_length=50), # string length bounds page: int = Query(default=1, ge=1), # >= 1 limit: int = Query(default=10, ge=1, le=100), # 1 <= limit <= 100 code: str = Query(pattern=r"^[A-Z]{3}$"), # regex pattern ): ... @app.get("/items/{item_id}") def get(item_id: int = Path(ge=1)): # path param must be >= 1 ... ``` A `Query()` és `Path()` korlátozásokat adnak a lekérdezés- és útvonal paraméterekhez. Gyakori: `min_length`/`max_length` (stringek), `ge`/`gt`/`le`/`lt` (számok), `pattern` (regex). A szabálysértések automatikusan egyértelmű 422 hibát hoznak létre. ## Field korlátozások Pydantic modelleken ```python from pydantic import BaseModel, Field, EmailStr class User(BaseModel): name: str = Field(min_length=1, max_length=100) age: int = Field(ge=0, le=120) email: EmailStr # format validation via a type bio: str = Field(default="", max_length=500, description="User bio") ``` Ugyanezek a korlátozások a modellmezőkre vonatkoznak a `Field()` -on keresztül, érvényesítve a kérés törzsét. Speciális típusok (`EmailStr`, `HttpUrl`, `UUID`) formátumokat érvényesítenek. ## A korlátozások a dokumentációt is gazdagítják ```python q: str = Query(min_length=3, description="Search query", example="phone") # the constraints + description + example appear in the auto-generated API docs ``` Minden deklarált korlátozás az OpenAPI dokumentációban is megjelenik, így a fogyasztók látják a szabályokat. ## Miért fontos Az érvényesítési korlátozások hozzáadása fontos a **biztonsággal/robusztussággal** és a jó API-tervezéssel egyaránt — a szabályok deklarálása (hosszkorlátozások, számtartományok, regex minták, formátumtípusok) biztosítja, hogy a helytelenül formázott vagy rosszindulatú bemenetet egyértelmű hibákkal elutasítják *mielőtt* elérné a logikáját, ami alapvetően fontos, mivel soha nem szabad megbíznia a nyers bemenetben. A FastAPI ezt deklaratívvá és erőfeszítés nélkülivé teszi: a `Query`/`Path`/`Field` korlátozásokat automatikusan érvényesítik (strukturált 422 hibákat hozva létre) és egyidejűleg dokumentálják az API dokumentációban, így a szabályok egy deklarációból kerülnek érvényesítésre és közlésre. A közös korlátozások és a speciális érvényesítési típusok ismerete napi tudás a biztonságos, jól meghatározott végpontok létrehozásához — így léphet túl az alapvető típusellenőrzésen a tényleges üzleti szabályok érvényesítésére, amelyeket az adatoknak meg kell felelniük.