Python Academy · Урок

Параметры пути, параметры запроса и тела запросов

Определяйте типизированные параметры и схемы тел запросов с помощью Pydantic.

«Параметры пути, параметры запроса и тела запросов» — бесплатный урок Python Academy на CoddyKit. Это урок 2 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Python Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Python Academy содержит 4 уроков всего.

Проверка параметров пути

Добавляйте средства проверки к параметрам пути с помощью Path(): задавайте ограничения 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)

Проверка параметров запроса

Используйте Query(), чтобы добавить к параметрам запроса проверку, значения по умолчанию, псевдонимы и описания.

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}

Необязательные параметры запроса

Используйте | None = None (Python 3.10 и новее) или Optional[str] = None, чтобы сделать параметр запроса необязательным.

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

Несколько значений одного параметра запроса

Принимайте список значений для одного параметра запроса с помощью list[str] и 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

Вложенные тела запросов

Модели Pydantic можно вкладывать друг в друга. FastAPI автоматически обрабатывает вложенный JSON.

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()

Ограничения полей в Pydantic

Используйте Field() внутри модели, чтобы добавить ограничения, значения по умолчанию и описания отдельных полей.

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")

Тело запроса, путь и запрос вместе

Объединяйте все три типа параметров в одной конечной точке. FastAPI различает их по расположению: параметры пути находятся в URL, простые типы становятся параметрами запроса, а модели — телом запроса.

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}

Загрузка файлов

Используйте UploadFile и File(), чтобы принимать загружаемые файлы. Получайте доступ к содержимому с помощью 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)}

Данные формы

Используйте Form(), чтобы принимать данные HTML-формы (application/x-www-form-urlencoded или 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}

Итоги проверки запросов

FastAPI автоматически проверяет все типы параметров. Недопустимые входные данные возвращают HTTP 422 с подробным описанием ошибки ещё до вызова обработчика.

# 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= в Query() или Field(), чтобы принимать в запросе другое имя, а deprecated=True — чтобы пометить старые параметры.

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

Быстрая проверка

Как FastAPI различает параметр пути, параметр запроса и тело запроса?

Итоги

Используйте Path()/Query() для задания ограничений параметров. Вкладывайте модели Pydantic для описания сложных тел запросов. Свободно сочетайте параметры пути, запроса и тела. UploadFile обрабатывает файлы, а Form() — HTML-формы. FastAPI проверяет всё до запуска обработчика.

Часто задаваемые вопросы

Урок «Параметры пути, параметры запроса и тела запросов» бесплатный?

Да — полный текст урока «Параметры пути, параметры запроса и тела запросов» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Python Academy, подпишись на CoddyKit PRO. Курс Python Academy содержит 4 уроков всего.

Чему я научусь в уроке «Параметры пути, параметры запроса и тела запросов»?

Определяйте типизированные параметры и схемы тел запросов с помощью Pydantic. Ты практикуешь Python Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Python Academy?

Предыдущий опыт не требуется. Python Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 2 из 4.

Сколько времени занимает урок «Параметры пути, параметры запроса и тела запросов»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Python Academy?

Да. Каждый урок Python Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

Настройка проекта FastAPI и первая конечная точка
Параметры пути, параметры запроса и тела запросов
Внедрение зависимостей и аутентификация
Асинхронные конечные точки и интеграция с базой данных

← Назад к Python Academy