Что такое query params?

Query params (параметры запроса)

Query params (query parameters, параметры строки запроса) — это переменные, передаваемые в URL после символа ?. Они используются для передачи данных при выполнении GET-запросов и используются для фильтрации, сортировки, пагинации и другого управления поведением приложения.

Синтаксис URL с query params

Основная структура URL с параметрами:

https://example.com/api/users?id=42&sort=name&order=asc
                              └─ separator
                                └─ param=value pairs separated by &

Составляющие:

• Базовый URL — https://example.com/api/users
• Знак вопроса — ? (разделитель между URL и параметрами)
• Параметры — пары ключ=значение, разделённые &

Примеры URL

# Один параметр
/search?q=python

# Несколько параметров
/products?category=electronics&min_price=100&max_price=500

# Параметры с пробелами (URL-кодирование)
/search?q=hello%20world

# Массивы параметров
/filter?tags=python&tags=django&tags=fastapi

Работа с query params в Python

В Django:

# Получение параметров из request.GET
from django.shortcuts import render
from .models import Product

def product_list(request):
    # GET параметры доступны в request.GET
    category = request.GET.get('category')  # Один параметр
    min_price = request.GET.get('min_price', '0')  # С значением по умолчанию
    sort_by = request.GET.getlist('sort')  # Список значений
    
    queryset = Product.objects.all()
    
    if category:
        queryset = queryset.filter(category=category)
    
    if min_price:
        queryset = queryset.filter(price__gte=min_price)
    
    return render(request, 'products/list.html', {'products': queryset})

В FastAPI:

from fastapi import FastAPI, Query
from typing import Optional

app = FastAPI()

@app.get("/users")
async def get_users(
    skip: int = Query(0, ge=0),  # offset
    limit: int = Query(10, ge=1, le=100),  # limit
    search: Optional[str] = Query(None),  # опциональный параметр
    sort_by: str = Query("created_at", regex="^[a-z_]+$")  # с валидацией
):
    return {
        "skip": skip,
        "limit": limit,
        "search": search,
        "sort_by": sort_by
    }

# Запрос: GET /users?skip=20&limit=50&search=john&sort_by=name

В Flask:

from flask import Flask, request

app = Flask(__name__)

@app.route('/api/articles')
def get_articles():
    page = request.args.get('page', 1, type=int)
    per_page = request.args.get('per_page', 10, type=int)
    search = request.args.get('search', '')
    
    # Получение всех параметров
    all_params = request.args.to_dict()
    
    return {"page": page, "per_page": per_page, "search": search}

Типичные использования query params

Пагинация:

GET /api/users?page=2&limit=20

Сортировка:

GET /api/products?sort=price&order=asc
GET /api/products?sort_by=-created_at  # Минус для DESC

Фильтрация:

GET /api/items?category=electronics&min_price=100&max_price=1000&in_stock=true

Поиск:

GET /api/search?q=django&limit=50&offset=0

Множественные значения одного параметра:

GET /api/filter?tags=python&tags=web&tags=async

URL-кодирование

Специальные символы и пробелы должны быть URL-кодированы:

import urllib.parse

# Кодирование
query = "hello world & test"
encoded = urllib.parse.quote(query)
print(encoded)  # hello%20world%20%26%20test

# Декодирование
url_encoded = "hello%20world%20%26%20test"
decoded = urllib.parse.unquote(url_encoded)
print(decoded)  # hello world & test

Валидация и обработка ошибок

from fastapi import FastAPI, Query, HTTPException

app = FastAPI()

@app.get("/api/items")
async def get_items(
    skip: int = Query(0, ge=0, description="Number of items to skip"),
    limit: int = Query(10, ge=1, le=100, description="Max items to return"),
):
    if skip < 0:
        raise HTTPException(status_code=400, detail="skip должен быть неотрицательным")
    
    if limit > 100:
        raise HTTPException(status_code=400, detail="limit не может быть больше 100")
    
    return {"skip": skip, "limit": limit}

Query params vs Body (POST данные)

Query params:

• GET запросы
• Видны в URL
• Ограничение длины (зависит от браузера/сервера)
• Для фильтрации, сортировки, пагинации
• Кешируются браузером

Body (POST данные):

• POST, PUT, DELETE запросы
• Не видны в URL
• Нет ограничений по размеру
• Для создания/обновления/удаления
• Не кешируются

Best practices

• Используй стандартные названия — page, limit, skip, sort, search
• Валидируй параметры — проверяй типы и значения
• Документируй API — описывай параметры в OpenAPI/Swagger
• Используй значения по умолчанию — не требуй обязательного параметра, если это не критично
• Кодируй специальные символы — URL-кодирование для пробелов и спец.символов
• Ограничивай диапазоны — макс limit, макс offset для безопасности

Преимущества query params

• Простота — легко читать из URL
• Кеширование — браузер кеширует GET запросы
• История — видны в истории браузера
• Стандартизация — понятны разработчикам
• REST соответствие — правильное использование GET для получения данных