Параметры запросов: работа с Query Parameters

Сегодня мы копнём чуть глубже и проберёмся в мир Query Parameters (параметров запроса). Это мощный инструмент, который позволяет превращать ваш API в швейцарский нож. Усаживайтесь поудобнее, приготовьтесь к практике, и давайте разбираться.

Query Parameters — это параметры, которые передаются в URL в рамках HTTP-запросов. Вы наверняка видели их в браузере, например:

https://example.com/search?query=fastapi&page=2

Здесь:

• query=fastapi — передаёт строку для поиска.
• page=2 — указывает, что пользователь запрашивает вторую страницу результата.

Параметры запроса начинаются после вопросительного знака ? и идут в формате ключ=значение. Несколько параметров разделяются амперсандом &.

В FastAPI работать с ними — одно удовольствие. Да-да, серьёзно!

---

Как извлекать Query Parameters в FastAPI

Для работы с параметрами запроса в FastAPI используется объект Query из библиотеки fastapi. Давайте рассмотрим базовый пример.

Шаг 1: импортируем Query и создаём эндпоинт

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/search")
async def search(query: str = Query(...)):
    return {"query": query}

• Query(...): Указывает, что этот параметр обязателен (... — это не трёхточие уныния, а требование обязательности).
• Мы возвращаем введённый параметр в ответе, чтобы проверить работоспособность.

Шаг 2: запускаем сервер и тестируем

Запускаем приложение:

uvicorn main:app --reload

Откройте в браузере http://127.0.0.1:8000/docs. Там будет наш эндпоинт /search, где можно ввести значение параметра query.

Пример запроса:

http://127.0.0.1:8000/search?query=fastapi

Ответ:

{
    "query": "fastapi"
}

Момент истины!

Если параметр query не передан, вы получите ошибку валидации:

{
    "detail": [
        {
            "loc": ["query", "query"],
            "msg": "field required",
            "type": "value_error.missing"
        }
    ]
}

FastAPI заботится о нас и автоматически добавляет валидацию. Намного меньше багов — намного больше веселья.

---

Опциональные параметры

Пользователи ленивы, и это факт. Мы не можем ожидать, что они всегда отправят все параметры. Давайте сделаем параметр необязательным.

@app.get("/search")
async def search(query: str = Query(None)):
    if query:
        return {"query": query}
    return {"message": "No query provided"}

Здесь:

• Query(None) указывает, что значение по умолчанию — None.
• Мы проверяем наличие параметра и возвращаем сообщение, если его нет.

Тестируем:

http://127.0.0.1:8000/search

Ответ:

{
    "message": "No query provided"
}

---

Значения по умолчанию

Допустим, мы хотим, чтобы, если значение не указано, поисковый запрос был "python":

@app.get("/search")
async def search(query: str = Query("python")):
    return {"query": query}

Теперь запрос без параметра вернёт:

{
    "query": "python"
}

---

Валидация параметров

Работа с параметрами запроса — это не только извлечение данных, но и их валидация. Никто не хочет принимать запросы вроде ?page=лодка.

Давайте добавим валидацию для параметра page:

@app.get("/items")
async def get_items(page: int = Query(1, ge=1, le=100)):
    return {"page": page}

• ge=1: Значение должно быть больше или равно 1.
• le=100: Значение должно быть меньше или равно 100.

Тестируем:

Указываем page=101 — получаем ошибку:

{
    "detail": [
        {
            "loc": ["query", "page"],
            "msg": "ensure this value is less than or equal to 100",
            "type": "value_error.number.not_le",
            "ctx": {
                "limit_value": 100
            }
        }
    ]
}

FastAPI позаботился обо всём за вас. Реально удобно, правда?

---

Дополнительные возможности Query

Для встроенной документации полезно давать описание параметров. Это делается с помощью аргумента description:

@app.get("/search")
async def search(
    query: str = Query("python", description="Search term to look for")
):
    return {"query": query}

Теперь в Swagger UI вы увидите описание возле параметра.

Регулярные выражения

Если вам нужно строго ограничить вводимые данные, используйте параметр regex:

@app.get("/validate")
async def validate(
    code: str = Query(..., regex="^[A-Za-z0-9]{6}$")
):
    return {"code": code}

Этот код принимает только строки длиной 6 символов, содержащие буквы и цифры.

Пример запроса:

http://127.0.0.1:8000/validate?code=abc123

Ответ:

{
    "code": "abc123"
}

Если код не подходит, будет ошибка:

{
    "detail": [
        {
            "loc": ["query", "code"],
            "msg": "string does not match regex \"^[A-Za-z0-9]{6}$\"",
            "type": "value_error.str.regex",
            "ctx": {
                "pattern": "^[A-Za-z0-9]{6}$"
            }
        }
    ]
}

---

Несколько параметров

FastAPI позволяет обрабатывать несколько параметров одновременно. Давайте добавим сортировку и фильтрацию:

@app.get("/products")
async def get_products(
    category: str = Query(None),
    sort: str = Query("asc", regex="^(asc|desc)$")
):
    return {"category": category, "sort": sort}

Пример запросов:

http://127.0.0.1:8000/products?category=books&sort=desc

Ответ:

{
    "category": "books",
    "sort": "desc"
}

---

Углубляемся: Списки в Query Parameters

Иногда нам нужно передать несколько значений для одного параметра. Это легко решается:

@app.get("/tags")
async def get_tags(tags: list[str] = Query(None)):
    return {"tags": tags}

Запрос:

http://127.0.0.1:8000/tags?tags=python&tags=fastapi

Ответ:

{
    "tags": ["python", "fastapi"]
}

И всё — никаких дополнительных библиотек.

---

Типичные ошибки и нюансы

Если вы забыли указать значение по умолчанию или не использовали обязательность параметра, FastAPI выбросит ошибку. Ещё одна ловушка — неправильная работа с типами данных. Например, если вы ждёте int, а пользователь передаёт строку, FastAPI вернёт 422 HTTP-ошибку.

---

Практическое применение

• Фильтрация данных: создание API для фильтрации товаров по категориям или параметрам.
• Сортировка: удобная передача параметров asc/desc для управления сортировкой.
• Пагинация: простое указание страницы и лимита результатов.

Теперь вы знаете, как использовать Query Parameters для создания гибких и удобных API. Переходите к следующей теме, и FastAPI продолжит вас радовать. 😉