Метод HTTP QUERY для команд фронтэнду: безпечныя запыткі з тэламентам

Экраны для пошуку та фільтрацыі сталкваюцца з паўтараючымся проблемамі API. Якщо кожны фільтр кодуваць у рэчызе запиту GET, URL становіцца дужа дзьвягучым; якщо ж фільтры надсылаць у формате JSON праз метод POST, то вы викорыстоўваете метод, які сигналізуе пра змяну стану, хоча на самай адзе ўсё являе сабою працэс чытання. Метод HTTP QUERY створаны саме для выправлення гэтай праслінкі. У этой статыце поясняецца, што такое QUERY, як надсылаць його з дапамогай React-додатку за дапамою fetch, а таксама якія частыні вашай інфраструктуры, ад CORS да кэшаў, трэба прыглядаць перад тым, як паслужыцца ім.

Проблема, якую рашае QUERY

Спіс продуктав з калькама фільтраў быстра стварае запиты на кшталт гэтаго:

/products?category=laptop&brand=Apple&minPrice=50000&maxPrice=150000&rating=4

Гэта працюе, але кожны новы фільтр падвайнае дзьвягучасць рэчыза, а вкладаныя чы ўпоракаваныя значэння (калькі маркаў, дыапазон цены, спосаб сортавання, пагінацыя) вымагаюць спецыяльных правілаў кодування; кроме таго, дужа дзьвягучыя URL можу страждзець ад лімітавання дужоў на серверах, проксі та у логах.

Звычным спосабам выходу з дагэнай ситуацыі ёст транзакцыя POST з кантэнтам у формате JSON. Гэта прыемная форма для рэалізацыі на кліенте, але ўскладнюе формулюванне умоваў вяроўнавання. Метод POST ні ў чым не безпечны і ні ў чым не ідэмптантны, таму проміжніе элементы не можаць бяспечна павтараць такі запит, кэшы за замовчаннем не будуць зберагаць адпаведны адказ, і кожны, хто чытае API, павінен адзірвацца на дакументацыю, каб дазнацься, што гэты конкретны метод POST выкарыстоўваецца толькі для чытання дадзеных.

Што такое QUERY

QUERY — гэта метод HTTP, які выкарыстоўваецца для запрасу сервера аб выкананні запытку, описанай у кантэнце запиту. За данымі, якія ў наступны час былі публікуемы, IETF опублікаваў яго як стандарт у чэрвені 2026 года пад назвай RFC 10008; пераканаецца ў його текущым статусе ў індэксе RFC пры апілаванні да яго. Уместа таго, каб пакладаць параметры ў URL, кліент адправляе іх у кантэнце запыту:

QUERY /products HTTP/1.1
Content-Type: application/json

{
  "category": "laptop",
  "brands": ["Apple", "Dell"],
  "price": {
    "min": 50000,
    "max": 150000
  }
}

Сервер аналізуе запит і вяртае паспадныя рэзультаты. Тое, што адзінакоўвае QUERY з POST, — гэта яго семантыка: ён вважаецца безпечным, тое значыць, ён не мяніць цэльны ресурс, і ідемпатным, тое значыць, ўсуненне яго два разы дае той самы эфект, калі ўсунуць яго адна раз. Гэтыя два якості дазволяюць кліентам, проксі і кэшам атрымліваць данныя па прыему чытання. Ідемпатнасць, напрыклад, означае, што кліент або промежуцкі элемент можа автаматычна прабаваць зноў запускіць неудачны QUERY без рызыку падвойных паслядків, чаго ён не должен робіць для POST.

Выбор между GET, POST і QUERY

QUERY не заменяе іншыя методы. Кожны з яных все ўсё такі ж мае чыстаю ролю:

• GET застаецца стандартным для простага атрымлівання: ресурс па ID, короткі список з калькамі простых параметраў.

POST застаецца методам для аператыў, якія ствараюць або зменяюць стан сервера, або якія не ўпэўненыя для павтарэння.

QUERY падходзіць для чытання, дзе вхідныя даны настолькі складныя, што патрабуюць структураванага кантэнта, такога як вярстакаваныя фільтры, масівы значэнняў або выразы запитаў.

Для фронтэнду прыемлівасць заключаецца у тым, што складныя карты стану фільтраў адразу пераходзяць у тэле запита, а контракт API чыста зазначае, што нічога не зменяецца.

Адправка запита QUERY з React

Уявіце компонент React, які зберагае своія ныяньшыя фільтры продуктав у об’екте:

const filters = {
  category: "laptop",
  brands: ["Apple", "Dell"],
  price: {
    min: 50000,
    max: 150000
  },
  rating: 4
};

За дапамогай QUERY гэты об’ект можна серыялізаваць і адправіць такім, які ён. Наступны хелпер выкарыстоўвае fetch з адзінаменным іменем методу і тэлам у формате JSON:

const searchProducts = async (filters) => {
  const response = await fetch("/api/products", {
    method: "QUERY",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify(filters)
  });

Другая частка таго жа функцыі пераканальвае статус адпаведзі і парсуе рэзультат:

  if (!response.ok) {
    throw new Error("Failed to fetch products");
  }  return response.json();
};

За выключэнням атрыбута методу, гэта ідентычна вызову POST. Змена ў сэмантыцы, а не у сінтаксі: запит тепер прызнаецца кэйсам. Зверніце увагу на два практычныя моменты. Стандарт Fetch перакладае на верхнія літеры толькі калькі вядомых імен методаў, таму завжды пішыце "QUERY" з верхнімі літерамі. І на вядзімую ад GET і HEAD, якія fetch не дозволяе адправляць з тэлам, для QUERY дазволена наявнасць такога тэлу.

Аднам з компромісаў, спецыфічных для інтэрфейсаў корыстувача, ёсць тое, што фільтры, закодаваныя ў URL, можна зберагчыць у закладках і перадаваць іншым, а таксама яны застаюцца пасля перзагрузкі стораны. Тэла кэйса QUERY такога не робяць. Якщо важлівы перадавальныя лінкі, можа знадобіцца відбіць стан фільтраў у URL стораны на кліянце, а ў той жа час адправіць структураваны запит да API.

Пераканайцеся, што падтрымка дзейнаўцае на всій дылінгу запита

Стандартызаваны метод не значыць, што кожны элемент, який працуе з вашым трафікам, розумее яго. Запрос браузера праходзіць через калькі слоёў, перш чым дасягнуць аплікацыі, і кожны з іх можа адмовіць у обробке або спакаванні незнаёмага методу. Перш чым выкористоўваць QUERY, пераканайцеся:

• Працэсах браузера і функцыях fetch() у тых браузерах, якія вы падтрымляеце.
• Канфігурацыі CORS у API.
• API-шлюзах і зворачных проксі.
• CDN-ах і кэшах на краю сеті.
• Мідлвэрах для аутентыкацыі і автарызацыі.
• Інструментах для манітарынгу, логавання і трэйсінгу.
• Механізмах маршрутызацыі і парсавання тэлу ў фреймворку бэкенду.

Дзеяныя слоі можа дазволіць толькі фіксаваны список методаў, а іншыя могу адхіліць тэлу запита, якія ў іх не впішываюцца. Тэставайце ўсё на адной лініі ў средовышчы, якое адпавядае рэальнай супрацоўке, а не толькі на локальным серверы.

CORS завжды выклікае прадзейнавальную перапаковку

QUERY не ў складзе спісу методаў, дазволеных для CORS (GET, HEAD і POST). Адносна гэтага, запыт QUERY з іншага канстанту ў браузеры завжды запускае прадзейнаванне: перш чым будзе адправлены рэальны запыт, браузер надае запыт OPTIONS, ў яком пытаецца, чыраўся QUERY.

Якщо ваша аплікацыя на React і API знаходзяцца на разных канстантах, сервер павінен адпаведаць на гэтае прадзейнаванне загаловкам Access-Control-Allow-Methods, у якім павінен быць указаны QUERY, а таксама ўсе іншы загаловкі, якія викорыстоўваецца ў вашым запыті, напрыклад Content-Type. Тэла запыту у формате JSON таксама вымагае прадзейнавання для методу POST, таму дадатковыя зусилля часта не ўскладнююць ситуацыю, але метод павінен быць явна указаны.

Гэта легка працягнуць пад час розрабоцы. Толькі такія інструменты, як Postman і curl, не прыменяюць правіла CORS, таму канчатак можа чынна працаваць там, але не функцыонаваць у браузеры.

Магчыма кэшаванне, але гэта ўскладненая задача

Адказы на запыткі можна зберагаць у кэшы, і гэта ўсё ж адна з галоўных пераваг гэтага методу па апэраванню да POST. Складнасць заключаецца у тым, што адказ залежыць не толькі ад URL, але і ад тэла запыткі. Разглянем два тэлы запытак, якія надсылаюцца да таго ж канцэнтраба:

{
  "brand": "Apple"
}

{
  "brand": "Dell"
}

Яны павінны вяртаць разныя рэзультаты. Таму кэш павінен уключаць контэнт запыткі, а таксама яго тип медыя, у ключ кэшу пад час адлікавання, чы можна пераўтарыта выкарыстоўваць зберажаны адказ. Кэшы таксама можу нормалізаваць контэнт (напрыклад, ігнораваць незначныя прабелы ў JSON), каб эквівалентныя запыткі дзеліліся адной ступенёй кэшування.

Для разработчыкаў React і Next.js урок заключаецца ў тым, што не трэба спрыяглядаць на QUERY як на „GET з тэлам“ пад час кэшування. Кэшы браузера, CDN-ы і кэшы фреймворка на роўні fetch можа ўсё ж не выкорыстоваць тэлу запыткі як ключ, таму трэба пераканацца, як кожны слой паводзіцца, а не прыпускаць, што будзе успех кэшування.

Як QUERY адаптуюцца да GraphQL

GraphQL часта паводзіцца ў тых сабе размовах, але гэтыя два прыемы функцыонуюць на разных рэвэлях. GraphQL дае вам мову для апісання дадзэных, якія вы хочаце, і модель для ўсунення прычын якіх-лібо проблем з імі. QUERY — гэта толькі верб на рэвэле транспорту: ён вказывае, як HTTP павінен адмаўляць запит з кантэнтам QUERY. Сёгодні кліенты GraphQL часта адправляюць операцыі за дапамою методу POST; сервер GraphQL у прынцыпе могаў бы приймать операцыі чытання через QUERY, але QUERY не заменяе GraphQL, і гэтыя два можу сусістаць адпаведна да дизайну API.

Чы трэба мігруаваць існуючыя API?

Зазвычай ні, прынеймна не толькі таму, што існуе QUERY. Якщо канцэнтр пашуку вже добра працюе за дапамою методаў GET або POST, яго змена прыносіць додатковую работу па міграцыі і сумаспадобнасці з мінімальнымы рэзультатам. QUERY стае наіболей прыемным выборам пад час проектавання новага канцэнтра, якіх запыты ўсе ў той жа час:

• Якія є толькі для чытання.

Можаць быць сложным.

Болей прыроднае выражэнне як структураваны контент, чым як параметры URL.

Ўможліва парадка ад безпечных, ідэмпотентных семантык, такіх як павторныя запускі і кэшаванне.

Гэта дае командам прынцыпавую альтернатыву выкарыстоўванню метода POST, калі запит GET стае некерованым.

Ключавыя выводы

• Выкарыстоўваюце GET для простага атрымання дадзеных і залучайце простыя запыты да застаўкі простымі.
• Разглядзіце варыянт QUERY для сложных, толькі-чытаючых запытоў, якія патрабуюць структураванага тэлу.
• Не чакайце прышвартавання скорасці: QUERY зменяе спосаб представлення запыту, а не швальнасць бэкенду чы сеті.
• Пераканайцеся, што браузеры, проксі, гейтвэйы, CDN і ваша бэкенд-фрэймворк падтрымаюць гэты метод, прычым перш чым выкарыстоўваць у працэсе.
• Настроюйце CORS, каб явна разрэшыць даны метод, і працавайце з рэальным браузерам.
• Пераканаўцеся, што всі ключы роўня кэша ў тэле запиту перакананы, прычаму пасля чаго толькі спакойвацеся на кэшаваных адпаведзях QUERY.
• Следзіце за адымленнем у экасистеме: сторанкі пошуку, панелі керавання і дапыткі з великай колькасцю дадзэнняў — гэта тыя месца, дзе QUERY, верагодна, даўае першыя рэзультаты.