ASP.NET Core в .NET 11 Preview 4 обучает OpenAPI методу HTTP QUERY

.NET 11 Preview 4, выпущенный 2026-05-12, включил небольшое, но дальновидное изменение в ASP.NET Core: генерация документов OpenAPI теперь распознаёт QUERY как известный тип HTTP-операции. Если вы никогда не слышали о методе QUERY, в этом и состоит суть этой статьи. Это предлагаемый стандартный метод, который снимает реальное противоречие, годами досаждавшее endpoint поиска.

Зачем новый глагол для поиска

Запрос поиска хочет двух вещей, которые существующие глаголы не могут дать вместе. Он хочет быть безопасным и идемпотентным, как GET, чтобы кеши и прокси обрабатывали его разумно, а повторная попытка ничего не меняла. И он хочет нести структурированное тело запроса, как POST, потому что серьёзный фильтр (вложенные булевы условия, географические границы, вектор плюс предикаты по метаданным) не помещается аккуратно в строку запроса и упирается в ограничения длины URL.

Команды затыкали эту дыру десятилетие, отправляя POST /search с телом JSON и молча делая вид, что он идемпотентен. Это работает, но обманывает каждый кеш и каждого посредника на пути. Метод QUERY от IETF — это честная версия: семантика GET (безопасный, идемпотентный, кешируемый) плюс тело запроса. Preview 4 не изобретает метод, он обучает конвейер OpenAPI правильно его описывать.

Сопоставление endpoint QUERY

Маршрутизация уже поддерживала произвольные глаголы, поэтому учить новый атрибут не нужно. Вы сопоставляете endpoint QUERY с помощью существующей перегрузки MapMethods:

app.MapMethods("/search", ["QUERY"], (SearchRequest request) =>
    SearchService.Run(request));

Новое здесь — то, что выдаёт генератор документов OpenAPI. QUERY стал полноценной концепцией только в OpenAPI 3.2, поэтому вам нужно явно выбрать эту версию спецификации:

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_2;
});

С выбранным 3.2 указанный выше endpoint выдаётся как корректная операция query в path item. Если вы всё ещё привязаны к OpenAPI 3.0 или 3.1, которые появились раньше метода, генератор не отбрасывает endpoint молча. Он прибегает к расширению x-oai-additionalOperations, чтобы инструменты, понимающие это расширение, всё равно видели операцию, а те, что не понимают, по крайней мере не споткнулись.

Что стоит знать перед выпуском

QUERY всё ещё остаётся предлагаемым методом, поэтому поддержка в браузерах, HTTP-клиентах, CDN и корпоративных прокси неоднородна. Это изменение про точное документирование endpoint, а не обещание, что каждый посредник его маршрутизирует. Для внутренних API поиска между сервисами, где вы контролируете оба конца, оно отлично подходит уже сегодня. Для публичных API относитесь к нему как к заделу на будущее и сохраняйте путь POST, пока экосистема не догонит.

Работа вошла в dotnet/aspnetcore #65714. Это тихая строка в тихом preview, но именно такая сантехника решает, действительно ли QUERY приживётся или навсегда останется черновиком.