FastAPI е модерна, бърза (високопроизводителна) уеб рамка за изграждане на API с Python 3.6+ на базата на стандартните Python типови подсказки. Тя е проектирана да бъде лесна за използване, бърза за писане на код и подходяща за производствени среди. Една от ключовите характеристики на FastAPI е способността й да борави с параметри ефективно. В тази статия ще разгледаме различни начини за предаване на параметри във FastAPI и ще предоставим подробни обяснения и примери, за да ви помогнем да ги разберете и приложите ефективно.

Примери за параметри във FastAPI
Path параметри
Path параметрите се използват за улавяне на стойности от самия URL път. Те обикновено се използват за предаване на уникални идентификатори или имена на ресурси. Във FastAPI можете да дефинирате path параметри, използвайки къдрави скоби {}
в декларацията на пътя.
Дефиниране на Path параметри
За да дефинирате path параметър, просто го включете в къдрави скоби в декларацията на пътя. Например:
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: int):
return {"item_id": item_id}
В този пример item_id
е дефиниран като path параметър. FastAPI автоматично извлича стойността от URL пътя и я предава на функцията read_item
.
Типове Path параметри
FastAPI поддържа различни типове за path параметри. По подразбиране path параметрите се третират като низове. Въпреки това, можете да посочите типа на параметъра, използвайки Python типови подсказки. FastAPI автоматично ще конвертира path параметъра в посочения тип. Някои често използвани типове включват:
int
: Целочислени стойностиfloat
: Стойности с плаваща запетаяstr
: Низови стойности (по подразбиране)bool
: Булеви стойностиUUID
: Universally Unique Identifier (UUID) стойности
Например:
@app.get("/items/{item_id}")
async def read_item(item_id: int):
return {"item_id": item_id}
В този случай FastAPI ще конвертира параметъра item_id
в цяло число, преди да го предаде на функцията read_item
.
Path параметри с предварително дефинирани стойности
Можете да дефинирате path параметри с предварително дефинирани стойности, използвайки Enum класове. Това ви позволява да ограничите възможните стойности за path параметър. Ето един пример:
from enum import Enum
from fastapi import FastAPI
class ItemType(str, Enum):
ELECTRONICS = "electronics"
CLOTHING = "clothing"
BOOKS = "books"
app = FastAPI()
@app.get("/items/{item_type}")
async def read_item(item_type: ItemType):
return {"item_type": item_type}
В този пример path параметърът item_type
е ограничен до стойностите, дефинирани в enum класа ItemType
. FastAPI автоматично ще валидира входните данни и ще върне грешка, ако е предоставена невалидна стойност.
Query параметри
Query параметрите се използват за предаване на допълнителни данни към API крайна точка. Те се добавят към URL след въпросителен знак ?
и обикновено се използват за филтриране, сортиране или разделяне на страници. Във FastAPI можете да дефинирате query параметри като параметри на функцията с подразбиращи се стойности.
Дефиниране на Query параметри
За да дефинирате query параметър, просто го включете като параметър на функцията с подразбираща се стойност. Например:
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/")
async def read_items(skip: int = 0, limit: int = 10):
return {"skip": skip, "limit": limit}
В този пример skip
и limit
са дефинирани като query параметри със стойности по подразбиране съответно 0
и 10
. FastAPI автоматично ще извлече стойностите от низа на заявката на URL и ще ги предаде на функцията read_items
.
Незадължителни Query параметри
По подразбиране query параметрите се считат за незадължителни. Ако query параметър не е предоставен в URL, FastAPI ще използва стойността по подразбиране, посочена в параметъра на функцията. Можете също така да направите query параметрите задължителни, като не предоставяте стойност по подразбиране. Например:
@app.get("/items/")
async def read_items(required_param: str):
return {"required_param": required_param}
В този случай query параметърът required_param
е задължителен и FastAPI ще върне грешка, ако не е предоставен в URL.
Типове Query параметри
Подобно на path параметрите, можете да посочите типа на query параметрите, използвайки Python типови подсказки. FastAPI автоматично ще конвертира стойностите на query параметрите в посочения тип. Някои често използвани типове включват:
int
: Целочислени стойностиfloat
: Стойности с плаваща запетаяstr
: Низови стойности (по подразбиране)bool
: Булеви стойностиlist
: Списък от стойности
Например:
@app.get("/items/")
async def read_items(q: str = None, page: int = 1, size: int = 10):
return {"q": q, "page": page, "size": size}
В този пример q
е низов query параметър със стойност по подразбиране None
, докато page
и size
са целочислени query параметри със стойности по подразбиране съответно 1
и 10
.
Множество стойности за Query параметри
FastAPI поддържа предаването на множество стойности за един query параметър. Можете да дефинирате query параметър като списъчен тип, за да приемете множество стойности. Например:
from typing import List
@app.get("/items/")
async def read_items(q: List[str] = None):
return {"q": q}
В този случай query параметърът q
може да приеме множество стойности. FastAPI ще анализира стойностите като списък от низове.
Request Body
В допълнение към path и query параметрите, можете също така да предавате данни в тялото на заявката (request body). Това обикновено се използва за създаване или актуализиране на ресурси. FastAPI използва Pydantic модели за дефиниране на структурата на тялото на заявката.
Дефиниране на Request body
За да дефинирате request body, създайте клас на Pydantic модел, който представлява очакваната структура на данните. Например:
from pydantic import BaseModel
class Item(BaseModel):
name: str
description: str = None
price: float
tax: float = None
@app.post("/items/")
async def create_item(item: Item):
return item
В този пример моделът Item
дефинира структурата на request body. FastAPI автоматично ще анализира JSON request body и ще го валидира спрямо модела.
Вложени модели
Можете също така да дефинирате вложени модели, за да представите сложни структури от данни. Например:
from pydantic import BaseModel
class ItemDetails(BaseModel):
description: str
price: float
tax: float = None
class Item(BaseModel):
name: str
details: ItemDetails
@app.post("/items/")
async def create_item(item: Item):
return item
В този случай моделът Item
съдържа вложен модел ItemDetails
. FastAPI автоматично ще анализира вложената структура и ще я валидира съответно.
Файлове в заявката
FastAPI също така поддържа обработка при качване на файлове, използвайки класовете File
и UploadFile
от модула fastapi
.
Качване на единичен файл
За да обработите качването на единичен файл, използвайте класа File
като параметър на функцията. Например:
from fastapi import File
@app.post("/upload/")
async def upload_file(file: bytes = File(...)):
return {"file_size": len(file)}
В този пример параметърът file
е дефиниран като тип bytes
с клас File
като стойност по подразбиране. ...
(многоточието) означава, че файлът е задължителен. FastAPI ще прочете качения файл и ще предаде съдържанието му като байтове на функцията upload_file
.
Качване на множество файлове
За да обработите качването на множество файлове, използвайте типа List
с класа File
. Например:
from fastapi import File
from typing import List
@app.post("/upload-multiple/")
async def upload_multiple_files(files: List[bytes] = File(...)):
return {"file_sizes": [len(file) for file in files]}
В този случай параметърът files
е дефиниран като списък от bytes
с класа File
. FastAPI ще приеме множество файлове и ще ги предаде като списък от байтове на функцията upload_multiple_files
.
Разширена обработка на файлове
За по-разширено обработване на файлове, като например извличане на метаданни за файлове или използване на обекти от тип файл, можете да използвате класа UploadFile
вместо File
. Класът UploadFile
предоставя допълнителни функционалности, като достъп до името на файла, типа на съдържанието и обект от тип файл за четене на съдържанието на файла.
from fastapi import UploadFile
@app.post("/upload/")
async def upload_file(file: UploadFile = File(...)):
return {"filename": file.filename, "content_type": file.content_type}
В този пример параметърът file
е дефиниран като инстанция на UploadFile
. FastAPI ще предостави допълнителни метаданни за файла, като името на файла и типа на съдържанието, чрез инстанцията на UploadFile
.
Данни от формуляр
FastAPI поддържа обработка на данни от формуляр, използвайки класа Form
от модула fastapi
. Това е полезно, когато трябва да получите данни, изпратени чрез HTML формуляри.
Дефиниране на параметри на формуляр
За да дефинирате параметри на формуляр, използвайте класа Form
като параметър на функцията. Например:
from fastapi import Form
@app.post("/login/")
async def login(username: str = Form(...), password: str = Form(...)):
return {"username": username}
В този пример параметрите username
и password
са дефинирани като параметри на формуляр, използвайки класа Form
. FastAPI ще извлече стойностите от изпратените данни от формуляра и ще ги предаде на функцията login
.
Комбиниране на данни от формуляр и файлове
Можете да комбинирате данни от формуляр и качване на файлове в една заявка, използвайки класовете File
и Form
заедно. Например:
from fastapi import File, Form
@app.post("/submit/")
async def submit_form(
name: str = Form(...),
email: str = Form(...),
file: UploadFile = File(...)
):
return {"name": name, "email": email, "file": file.filename}
В този случай параметрите name
и email
са дефинирани като параметри на формуляр, докато параметърът file
е дефиниран като качване на файл. FastAPI ще обработи както данните от формуляра, така и качването на файлове в една заявка.
Заключение
FastAPI предоставя мощен и гъвкав начин за обработка на параметри във вашите API крайни точки. Независимо дали трябва да улавяте стойности от URL пътя, да извличате query параметри, да получавате request body, да обработвате качени файлове или данни от формуляри, FastAPI поддържа всичко необходимо.
Като се възползвате от интуитивния синтаксис на FastAPI и моделите на Pydantic, можете лесно да дефинирате и валидирате параметри. Автоматичното конвертиране на типове и валидирането на FastAPI гарантира, че получавате очакваните типове данни и улавяте всички невалидни входни данни в ранен етап от процеса на обработка на заявките.
С познанията, придобити от тази статия, вече трябва да се чувствате уверени в дефинирането и обработването на различни типове параметри във вашите FastAPI приложения. Не забравяйте да изберете подходящия тип параметър въз основа на вашите конкретни изисквания и случаи на употреба.