Работа с Query Parameters для передачи данных

Сегодня мы идём дальше и говорим о Query Parameters — одном из самых важных инструментов для передачи данных в веб-запросах. С их помощью можно добавлять гибкость взаимодействия с API без необходимости изменять маршруты или тело запросов.

Представьте, что вы заходите в интернет-магазин и ищете ноутбук с определённой ценой и маркой. Вы вводите параметры поиска, а сервер возвращает результат, соответствующий вашим запросам. Эти параметры поиска, которые передаются через URL, и называются Query Parameters.

В HTTP-запросах Query Parameters добавляются после знака ? в URL. Пример:

GET /products?category=laptop&brand=apple&price=1500

Здесь:

• category — это имя параметра,
• laptop — значение параметра,
• Параметры отделяются друг от друга символом & (brand=apple&price=1500).

---

Пример использования Query Parameters

Давайте создадим API, которое возвращает список товаров. Мы будем использовать Query Parameters для фильтрации товаров по категории и цене.

from fastapi import FastAPI, Query
from typing import Optional

app = FastAPI()

# Список "товаров" для демонстрации
products = [
    {"id": 1, "name": "Laptop", "category": "electronics", "price": 1500},
    {"id": 2, "name": "Phone", "category": "electronics", "price": 800},
    {"id": 3, "name": "T-Shirt", "category": "clothing", "price": 20},
    {"id": 4, "name": "Jeans", "category": "clothing", "price": 50},
]

@app.get("/products")
async def get_products(
    category: Optional[str] = Query(None),  # Допустимая категория
    max_price: Optional[float] = Query(None)  # Максимальная цена
):
    filtered_products = products

    if category:
        filtered_products = [p for p in filtered_products if p["category"] == category]
    
    if max_price:
        filtered_products = [p for p in filtered_products if p["price"] <= max_price]
    
    return {"products": filtered_products}

Объяснение кода

• Query(None): Мы используем функцию Query из FastAPI, чтобы указать, что параметр может быть передан через Query Parameters. Значение None делает параметр необязательным.
• category и max_price адаптируют результат в зависимости от входных данных. Если параметры не переданы, возвращаются все записи.

---

Проверка работы

Попробуем несколько запросов:

1. Получить все товары:

   GET /products

   Ответ:

   {
     "products": [
       {"id": 1, "name": "Laptop", "category": "electronics", "price": 1500},
       {"id": 2, "name": "Phone", "category": "electronics", "price": 800},
       {"id": 3, "name": "T-Shirt", "category": "clothing", "price": 20},
       {"id": 4, "name": "Jeans", "category": "clothing", "price": 50}
     ]
   }

2. Получить товары только из категории clothing:

   GET /products?category=clothing

   Ответ:

   {
     "products": [
       {"id": 3, "name": "T-Shirt", "category": "clothing", "price": 20},
       {"id": 4, "name": "Jeans", "category": "clothing", "price": 50}
     ]
   }

3. Получить товары дешевле $1000:

   GET /products?max_price=1000

   Ответ:

   {
     "products": [
       {"id": 2, "name": "Phone", "category": "electronics", "price": 800},
       {"id": 3, "name": "T-Shirt", "category": "clothing", "price": 20},
       {"id": 4, "name": "Jeans", "category": "clothing", "price": 50}
     ]
   }

---

Опциональные параметры и значения по умолчанию

Query Parameters в FastAPI можно сделать необязательными, задав значение по умолчанию. Например:

async def get_products(
    category: str = Query(None),
    max_price: float = Query(1000)  # Значение по умолчанию: 1000
):
    pass

Если пользователь не передаст max_price, он автоматически примет значение 1000.

---

Валидация Query Parameters

FastAPI + Pydantic = ❤️. Благодаря встроенной поддержке Pydantic, вы можете добавить правила для валидации Query Parameters.

Пример с добавлением ограничений:

@app.get("/products")
async def get_products(
    category: Optional[str] = Query(None, max_length=50),  # Максимальная длина строки
    max_price: Optional[float] = Query(None, gt=0)  # Цена должна быть больше 0
):
    filtered_products = products
    
    if category:
        filtered_products = [p for p in filtered_products if p["category"] == category]
    
    if max_price:
        filtered_products = [p for p in filtered_products if p["price"] <= max_price]
    
    return {"products": filtered_products}

Теперь FastAPI будет возвращать 400 Bad Request, если:

1. category длиннее 50 символов.
2. max_price меньше или равно 0.

---

Обработка списка значений в Query Parameters

Иногда нужно передать несколько значений для одного параметра. Например, чтобы выбрать товары из нескольких категорий.

FastAPI поддерживает этот сценарий "из коробки":

@app.get("/products")
async def get_products(
    categories: Optional[list[str]] = Query(None)  # Категории в виде списка
):
    filtered_products = products
    
    if categories:
        filtered_products = [p for p in filtered_products if p["category"] in categories]
    
    return {"products": filtered_products}

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

GET /products?categories=electronics&categories=clothing

Ответ:

{
  "products": [
    {"id": 1, "name": "Laptop", "category": "electronics", "price": 1500},
    {"id": 2, "name": "Phone", "category": "electronics", "price": 800},
    {"id": 3, "name": "T-Shirt", "category": "clothing", "price": 20},
    {"id": 4, "name": "Jeans", "category": "clothing", "price": 50}
  ]
}

---

Частые ошибки при работе с Query Parameters

Часто встречающиеся проблемы:

1. Отсутствие валидации. Если вы не ограничиваете вводимые данные (например, используете max_length), пользователи могут ненароком (или специально) отправить гигантскую строку или некорректные значения.
2. Неправильно обработанные значения по умолчанию. Если вы задаёте значение по умолчанию, убедитесь, что оно соответствует логике вашего приложения. Например, если max_price по умолчанию равен 1000, это может ограничить возвращаемые результаты.
3. Путаница между Query Parameters и Path Parameters. Запомните: Query Parameters — это параметры в URL после ?. Path Parameters являются частью самого маршрута.

---

Преимущества Query Parameters в реальных проектах

1. Фильтрация данных. Например, в интернет-магазине можно использовать Query Parameters для поиска товаров по категориям, ценам и другим признакам.
2. Наименование параметров. В отличие от структуры тела запроса, Query Parameters более "читаемы" прямо из URL.
3. Интеграция с фронтендом. Большинство фронтенд-фреймворков, таких как React и Angular, легко работают с Query Parameters для построения динамических запросов к серверу.

---

FastAPI делает работу с Query Parameters простой и гибкой благодаря богатому инструментарию Pydantic для валидации и обработки данных. Теперь вы готовы применять эти знания для создания более сложных и динамичных API.