Что такое query string в составе URL-запроса?

Что такое query string в составе URL-запроса?

Query string (строка запроса) — это часть URL, которая следует после символа ? и содержит параметры, передаваемые на сервер. Это один из основных способов передачи данных в HTTP GET запросах. Query string состоит из пар ключ-значение, разделённых символом &.

Структура query string

https://example.com/search?category=electronics&price=100&sort=ascending
                          ^      ^              ^     ^  ^    ^
                          |      |              |     |  |    |
                   начало query   ключ1       значение1  ключ2  значение2

Базовый синтаксис

?key1=value1&key2=value2&key3=value3

• ? — разделитель между путём и параметрами
• key=value — пара параметра (ключ и значение)
• & — разделитель между параметрами
• Символы кодируются по URL encoding (пробел = %20)

Примеры query string

Поиск на сайте

https://www.google.com/search?q=python+programming&hl=en

Фильтрация и сортировка

https://shop.example.com/products?category=clothes&size=M&color=red&sort=price_asc

Пагинация

https://api.example.com/users?page=2&limit=10&offset=20

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

https://example.com/filter?color=red&color=blue&color=green

Работа с query string в Python

С использованием urllib.parse

from urllib.parse import urlencode, parse_qs, urlparse

# Создание query string
params = {'name': 'John', 'age': 30, 'city': 'New York'}
query_string = urlencode(params)
print(query_string)
# name=John&age=30&city=New+York

# Полный URL
base_url = 'https://example.com/api/users'
full_url = f'{base_url}?{query_string}'
print(full_url)
# https://example.com/api/users?name=John&age=30&city=New+York

Парсинг query string

from urllib.parse import parse_qs, urlparse

url = 'https://example.com/search?q=python&lang=en&limit=10'

# Парсим URL
parsed = urlparse(url)
query_string = parsed.query
print(query_string)
# q=python&lang=en&limit=10

# Парсим параметры
params = parse_qs(query_string)
print(params)
# {'q': ['python'], 'lang': ['en'], 'limit': ['10']}

# Получаем отдельные значения
print(params['q'][0])  # 'python'
print(params['limit'][0])  # '10'

Работа с query string в FastAPI

from fastapi import FastAPI, Query

app = FastAPI()

@app.get('/search')
async def search(q: str = Query(...), limit: int = Query(10), offset: int = Query(0)):
    """
    GET /search?q=python&limit=20&offset=5
    """
    return {
        'query': q,
        'limit': limit,
        'offset': offset
    }

@app.get('/filter')
async def filter_items(
    category: str = Query(..., description='Category name'),
    tags: list[str] = Query(None, description='Filter by tags')
):
    """
    GET /filter?category=electronics&tags=smartphone&tags=cheap
    """
    return {'category': category, 'tags': tags}

URL кодирование (percent encoding)

Это обязательно при передаче специальных символов в query string:

from urllib.parse import quote, unquote

# Кодирование
text = 'Hello World!'
encoded = quote(text)
print(encoded)  # Hello%20World%21

# Декодирование
decoded = unquote(encoded)
print(decoded)  # Hello World!

# Таблица кодирования
# Пространство = %20
# ! = %21
# # = %23
# & = %26 (важно: разделитель параметров)
# = = %3D (важно: разделитель ключа и значения)
# ? = %3F

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

• Видимость — параметры видны в адресной строке
• Простота — легко создавать и парсить
• Кешируемость — GET запросы с query string кешируются
• Стандартность — поддерживается всеми браузерами и серверами
• Удаление закладок — можно сохранить URL с параметрами

Недостатки query string

• Ограничение размера — максимум 2048 символов (в зависимости от браузера)
• Видимость в истории — параметры видны в истории браузера
• Безопасность — не подходит для передачи чувствительных данных
• Сложность с большими данными — нельзя передать JSON напрямую

Когда использовать query string

• Фильтрация — выбор категорий, фильтров
• Сортировка — выбор порядка сортировки
• Пагинация — номер страницы, размер страницы
• Поиск — поисковые запросы
• Кеширование — параметры для кеша
• Отслеживание — UTM параметры для аналитики

Когда использовать request body вместо query string

• Большие данные — JSON, файлы
• Чувствительные данные — пароли, токены
• POST/PUT/DELETE — операции изменения данных

Пример с JavaScript (fetch API)

// Создание query string
const params = new URLSearchParams({
    q: 'javascript',
    limit: 10
});

// Отправка GET запроса
fetch(`https://api.example.com/search?${params}`)
    .then(response => response.json())
    .then(data => console.log(data));

Query string — это фундаментальная часть HTTP протокола, необходимая для передачи параметров в GET запросах и фильтрации данных на веб-сервисах.