ПРО АНАЛИТИКА | СИСТЕМНЫЙ АНАЛИТИК | АЛЕКСАНДР НЕЗДЕМИНА
Образование · 18 июня 2026 г.
КАК ПРАВИЛЬНО ПРОЕКТИРОВАТЬ QUERY-ПАРАМЕТРЫ: ФИЛЬТРЫ И СОРТИРОВКА — 18 июня 2026 г. в 06:44:35.102
КАК ПРАВИЛЬНО ПРОЕКТИРОВАТЬ QUERY-ПАРАМЕТРЫ: ФИЛЬТРЫ И СОРТИРОВКА Представьте, что вы проектируете админку, где по списку заказов надо поставить фильтры и сортировку. Отфильтровать по цене и статусу, ограничить период, да ещё и отсортировать. Кажется, легко на первый взгляд. Накидал параметров в URL и готово, но именно тут есть загвоздочка, что на скорую руку, может получится не очень гибкое решение. Например, такое: GET /orders?min_total_price=10000&status=обработка&sortByDate=desc&sortByPrice=asc Вроде все ок, на первый взгляд, правда? Но все же я бы докрутил. Как? Давайте разбираться. ➖➖➖ 1️⃣ ДИАПАЗОН значений Возьмем дату и цену. На первый взгляд, хочется запихнуть эти значения в один параметр, но на самом деле это всегда пара, а не одно поле. Возьмем пример. Мы хотим вернуть список заказов, которые были дешевле 10 000. Ну логично же, что min_total_price вообще огонь вариант? Нет, не огонь, потому что, во-первых, слово min само по себе говорит про нижнюю границу, но если нам понадобится фильтр по верхней границе, то с этим значением уже не сработает. во-вторых, заказчики люди переменчивые и там, где говорят, что хотят сейчас фильтровать только по минимальному значению, то завтра захотят не только по верхнему значению, но еще и в промежутке, например, "от 5 000 до 10 000", и хочешь-не хочешь, нам в любом случае придется вводить второй параметр. Поэтому лучше сразу выделить 2 параметра парой: ✖️ min_total_price=10000 ✔️ priceFrom=5000&priceTo=10000 В этом примере у нас и имя однозначное и гибкость и уберегли себя от уведомления старых потребителей о том, что что-то поменяли. Кто-то скажет: Ну это же почти то же самое! Не совсем, давайте накину деталей Пара закрывает все случаи: ✔️ нужна только верхняя граница - отправляем priceTo ✔️ нужна нижняя - отправляем priceFrom ✔️ нужен диапазон, оба сразу ➖➖➖ 2️⃣ ОДНО СОГЛАШЕНИЕ по именам на все параметры Когда у вас появляется большое количество параметров, то можно легко начать делать имена на параметры, которые уже есть. Например, в одном месте - min_price, в другом - priceTo, в одном месте - date_from, в другом - createdBefore. Каждый лепит свой нейминг. А потом у вас на проекте зоопарк похожих фильтров, а какой из них эталонный не понятно. Поэтому, если вам надо спроектировать стиль для ваших query параметров, то подсмотрите у коллег, как лучше. Можно на текущем проекте, если уже что-то есть, а можно подсмотреть у коллег во вне, через devtools, если проектируешь что-то с нуля. ➖➖➖ 3️⃣ СОРТИРОВКА - ЭТО ОДНИ ПАРАМЕТР, а не несколько Люди, которые проектируют редко это добро, часто хотят разбить сортировку на максимальное количество параметров. Есть у тебя табличка визуальная на 10 колонок. Вот втыкаем 10 разных, например, sortByDate, sortByPrice. И в целом, если у нас сортировок не сильно много, то так спроектировать ок, но если надо сортировать сразу по двум и более значениям, сразу, то тут надо продумывать, что главнее. Поэтому проще сортировку держать в одном параметре, где есть и поле, и направление: ✖️ sortByDate=desc&sortByPrice=asc ✔️ sort=createdAt,desc&sort=price,asc Выглядит вроде похоже, но в первом случае параметры независимы, а во втором - у нас порядок задает приоритеты. Сначала по дате, при равенстве по цене и при этом, так как параметр у нас один sort, то вы сможете докручивать логику и расширять сортировку новыми значениями, если потребуется. ➖➖➖ 4️⃣ ФИЛЬТРАЦИЯ ПО КОДАМ, а не по подписям Вернёмся к нашему параметру status=обработка. Иногда, люди любят воткнуть кирилицу и сортировать по ней, но это просто текст с экрана. Это ненадежно, так как описание сегодня одно, а завтра другое, поэтому для статусов надо задавать ENUM значения, которые будут всегда стандартные и не будут зависеть от локализации. Поэтому в значениях фильтра передаем