Возможность

Перезапись URL и путей

Измените путь, не трогая backend — клиент сохраняет свой URL, пока внутри работает новая архитектура.

TR7 Перезапись URL и путей — это не простая утилита для исправления URL. Это фундаментальный слой перезаписи для проектов модернизации приложений, версионирования API, совместимости с партнёрами B2B и прозрачной миграции сервисов. Клиент продолжает использовать известный ему внешний путь — например `/api/v1/...` — пока TR7 преобразует запрос к внутренней структуре путей, понятной backend. Слой перезаписи запросов TR7 изменяет путь с помощью действий set_path, set_pathq и normalize_uri, может сохранять строки запроса, приводить URI к канонической форме и применять шаблоны поиска и замены через STRREPLACE и STRREPLACEALL в языке выражений FX. Каждое правило ограничено условиями FX/ACL и срабатывает только при совпадении Host, метода, IP, cookie, заголовка или значений переменных. Наиболее мощный сценарий — двустороннее отображение, построенное совместно со слоем перезаписи ответов. Клиент видит `/api/v1/orders`, backend обслуживает `/internal/orders`, а внутренние ссылки и поля JSON в теле ответа записываются обратно во внешний формат пути. Клиент никогда не узнаёт реальную структуру путей backend. Результат: TR7 позволяет трансформировать архитектуру путей, не изменяя backend и клиент одновременно — инкрементальная миграция, совместимость URL для партнёров и шаблон прозрачного переназначения путей backend, всё в единой архитектуре правил.

Основных действия перезаписи: set_path, set_pathq, normalize_uri

Подопции normalize_uri: объединение слешей, удаление точечных сегментов и другие

Режима modifyResponse — replace, htmlTag, mask

Нельзя перестраивать структуру путей backend каждый раз, когда нужна модернизация приложения.

Современные архитектуры приложений находятся в постоянной эволюции. Эндпоинт, родившийся как API v1, достигает v3; структура путей за монолитом полностью меняется после разделения на микросервисы; партнёр B2B привык к другой схеме URL; или проект модернизации навязывает новый макет путей. Когда каждое изменение требует перенастройки клиента или backend с нуля, проект перестаёт быть технической задачей и превращается в длительное упражнение по координации.

Классический подход предлагает два плохих варианта. Первый — добавить поддержку нового пути в backend: поддержание старых эндпоинтов при одновременном написании новых удваивает сложность кода и тестовую нагрузку. Второй — принудить клиентов или партнёров мигрировать на новый путь: это социальное и операционное трение, часто требует пересмотра контрактов B2B, ожидания обновлений мобильных приложений и растягивает сроки перехода.

Правильная модель — ввести управляемый слой перезаписи в поток запрос-ответ. Этот слой преобразует путь клиента в путь, понятный backend, и при необходимости записывает внутренние пути в теле ответа обратно во внешние пути, ожидаемые клиентом. Backend модернизируется внутри; клиент или партнёр продолжает работать со знакомой схемой URL.

Для эффективности этого слоя необходимы три условия. Первое — гибкая логика поиска и замены: фиксированный путь, замена префикса, сохранение строки запроса и строковые преобразования на основе FX должны поддерживаться. Второе — условное применение: правило должно срабатывать только при совпадении правильного Host, метода, IP, cookie, заголовка или условия FX. Третье — двустороннее отображение с телом ответа: иначе внутренние ссылки, возвращаемые backend, превращаются в неработающие URL на стороне клиента.

TR7 Перезапись URL и путей реализует эту модель: действия set_path, set_pathq и normalize_uri; шаблоны FX STRREPLACE / STRREPLACEALL; условное применение FX/ACL; и двустороннее отображение путей через modifyResponse формируют основу прозрачной архитектуры переназначения путей backend.

Наш подход

Слой перезаписи URL TR7 строит управляемый мост между слоями архитектуры приложения — выходя далеко за рамки простой замены пути.

Перезапись пути преобразует внешний URL во внутренний путь

Входящий запрос на `/api/v1/users/123` может быть преобразован в путь `/internal/v3/users/123`, ожидаемый backend. set_path изменяет только путь; set_pathq перезаписывает путь и строку запроса вместе. Клиент продолжает отправлять свой существующий URL, пока backend работает с новой архитектурой.

Шаблоны поиска и замены FX обеспечивают динамическое преобразование

Когда фиксированной замены пути недостаточно, в дело вступает язык выражений FX. STRREPLACE и STRREPLACEALL преобразуют определённые сегменты — префикс, суффикс или середину пути. Операторы могут компоновать переменные, поля поиска-замены и условия в рамках одной модели правил.

Условное применение предотвращает воздействие на каждый запрос

Каждое правило перезаписи может быть ограничено условием FX/ACL. Правило срабатывает только при совпадении Host, метода, исходного IP, cookie, значения заголовка или переменной FX. Различные преобразования путей с разными условиями могут работать параллельно в рамках одного vService.

Перезапись ответа завершает двустороннее отображение путей

Изменения только пути запроса зачастую недостаточно — backend может возвращать внутренние пути в теле ответа. С modifyResponse HTML-ссылки, поля href в JSON или любой текст, содержащий внутренние пути, записываются обратно во внешний формат. Результат — полностью прозрачная архитектура переназначения путей backend с точки зрения клиента.

Возможности

Перезапись URL-путей — это не единственное действие, а фундаментальный строительный блок для шаблонов миграции, совместимости и двустороннего скрытия путей.

set_path преобразует входящий путь запроса в фиксированное или динамическое значение

set_path заменяет часть пути входящего запроса новым значением пути. Новое значение может быть написано статически или сделано динамическим с помощью смарт-переменных контента, таких как `%HOST`, `%PATH`, `%METHOD` или `%SRCIP`. Строка запроса не сохраняется при использовании set_path; если данные запроса должны быть сохранены, предпочтителен set_pathq. Это действие используется для сопоставления старой внешней структуры URL с новым внутренним макетом сервиса.

set_pathq перезаписывает путь и строку запроса вместе

set_pathq управляет путём и строкой запроса в едином действии перезаписи. Операторы могут включать существующее значение `%QUERY` в новый путь, чтобы сохранить параметры, отправленные клиентом. Новые параметры также могут добавляться — например, запрос `/api/v1/users?id=42` может быть преобразован в `/internal/v3/users?id=42&version=v3-from-v1`. Это практичный механизм перехода для версионирования API и совместимости с партнёрами.

normalize_uri приводит путь к канонической безопасной форме

normalize_uri нормализует путь и компоненты URI к стандартной форме. Опции включают объединение множественных слешей, удаление точечных сегментов, разрешение обходов `../`, декодирование безопасных символов по RFC 3986, приведение процентно-кодированных последовательностей к верхнему регистру, обработку фрагментов и сортировку параметров запроса по алфавиту. Эта нормализация важна для согласованности ключей кэша, читаемости аудита и устойчивости к попыткам обхода системы безопасности. Она также помогает WAAP и другим средствам безопасности принимать решения на основе одного канонического пути.

FX STRREPLACE и STRREPLACEALL применяют точный поиск и замену внутри пути

STRREPLACE заменяет первое совпадение; STRREPLACEALL заменяет каждое совпадение. Операторы могут писать выражения вида `%PATH.STRREPLACE("/old/", "/new/")` для преобразования определённых сегментов внутри пути. Этот подход обрабатывает замену префикса, замену сегментов в середине пути и перенос устаревших сегментов URL в новый макет сервиса. Вспомогательные поля UI делают ввод значений поиска и замены более управляемым.

Условия FX/ACL ограничивают перезапись с точностью

Каждое правило перезаписи пути может выполняться условно. Условием может быть совпадение Host-заголовка, ограничение по методу HTTP, проверка диапазона исходного IP, сравнение значения cookie или заголовка, или любое выражение true/false, создаваемое движком FX. В рамках одного vService специфичные для партнёра, тенанта или метода преобразования путей могут сосуществовать с разными условиями. Запросы, не совпадающие с условием, продолжают работать в обычном потоке без изменений.

modifyResponse завершает прозрачное переназначение путей backend двусторонне

Когда set_path или set_pathq преобразует путь запроса во внутренний путь, backend может возвращать внутренние пути в теле ответа. Режим replace в modifyResponse записывает эти внутренние пути обратно во внешний формат. Например: клиент запрашивает `/api/v1/orders`, backend работает с `/internal/orders`, а `"href":"/internal/users/42"` в JSON ответа возвращается как `"href":"/api/v1/users/42"`. Клиент работает, никогда не видя реальной структуры URL backend.

Перезапись ответа охватывает режимы replace, htmlTag и mask

modifyResponse не ограничивается переназначением путей — он поддерживает различные преобразования тела ответа. Режим replace сопоставляет шаблоны регулярных выражений или простого текста и заменяет их, делая его основным инструментом переназначения путей. Режим htmlTag внедряет управляемый контент в HTML-теги. Режим mask скрывает конфиденциальные данные. В контексте перезаписи URL и путей эта возможность позиционируется специально для двустороннего отображения путей.

Перезапись выполняется до инспекции WAAP, передавая корректные пути далее

Перезапись пути применяется в фазе запроса до того, как нижестоящие средства безопасности оценивают запрос. Это означает, что Virtual Patching, сопоставление сигнатур WAAP, ключи ограничения скорости и правила трафика — все работают на перезаписанном пути. Нормализованный или переупорядоченный путь становится общим вводом для каждого последующего уровня принятия решений. Разрыв между внешним URL и внутренним путём сервиса больше не создаёт несоответствий в политике.

Журнал аудита делает исходный и перезаписанный путь видимыми

Преобразование путей должно быть операционно наблюдаемым. TR7 может включать исходный путь запроса и значение перезаписанного пути в поток аудита и логов. На стороне SIEM вопрос «какой путь запросил клиент, какой путь система отправила в backend?» становится отвечаемым. Эта видимость критична во время проектов миграции и проверок безопасности.

Цепочки правил разбивают сложные преобразования на составные шаги

Несколько правил путей могут выполняться последовательно в рамках одного vService. Первое правило нормализует URI, второе выполняет замену префикса, а третье обогащает строку запроса или добавляет суффикс при определённом условии. Каждое правило работает с выводом предыдущего. Эта модель позволяет создавать читаемую, тестируемую и инкрементальную цепочку преобразований вместо одного большого и рискованного правила.

Операционная глубина

Перезапись URL-путей работает совместно со смарт-переменными контента, интеграцией FX, языком условий, характеристиками производительности, поведением при ошибках и шаблоном перезаписи ответов.

Смарт-переменные контента

В определении нового пути могут использоваться `%PATH`, `%QUERY`, `%HOST`, `%METHOD`, `%SRCIP`, `%PORT` и пользовательские переменные. Эти переменные компонуются в поле значения действий set_path и set_pathq для создания динамического пути. К любой из этих переменных могут применяться функции FX.

Интеграция движка FX

Перезапись URL-путей — один из потребителей движка выражений FX в TR7. Операторам не нужно изучать отдельный язык для преобразования путей — они используют STRREPLACE, STRREPLACEALL и другие функции FX в рамках той же логики выражений. Эта общая модель обеспечивает согласованный подход к управлению правилами трафика, шаблонами логов и определениями условий.

Язык условных выражений

Условия FX/ACL сужают область перезаписи. Допустимы выражения вида `%HOST == "partner.example.com"`, `%METHOD in ["POST","PUT"]`, `%SRCIP in MAP_IP("partner_ips")` или `%HEADER("X-Tenant") == "tenant-a"`. Несколько условий могут комбинироваться с логикой AND / OR.

Производительность и стоимость ресурсов

Перезапись пути добавляет низкие накладные расходы на запрос; строковые преобразования не требуют дополнительных операций с сокетами или файлами. STRREPLACE и STRREPLACEALL работают в памяти. Перезапись тела ответа обходится дороже, так как может потребовать буферизации тела и обработки регулярных выражений, поэтому её следует использовать только там, где сценарии переназначения путей действительно требуют этого.

Поведение при ошибках и резервный вариант

Если во время перезаписи возникает ошибка разбора FX, отсутствующая переменная или несоответствие регулярному выражению, запрос может продолжить работу в обычном потоке через безопасный резервный вариант — он не отбрасывается. Ошибка записывается в журнал аудита, чтобы оператор мог впоследствии изучить проблему конфигурации. Это поведение защищает производственный доступ от прерывания из-за неправильно настроенного правила.

Прозрачное переназначение путей backend

Рекомендуемый шаблон для прозрачного переназначения путей состоит из двух частей: на стороне запроса внешний путь преобразуется во внутренний; на стороне ответа внутренние пути в теле ответа записываются обратно во внешние. Эти два правила работают как согласованная пара в рамках одного vService. Этот шаблон становится стандартной структурой для сценариев API gateway, интеграции партнёров B2B и проектов миграции от монолита к микросервисам.

Когда применять

Прозрачная миграция с API v1 на v3

Существующие клиенты продолжают использовать эндпоинты `/api/v1/...`, пока TR7 внутренне преобразует запрос к структуре `/api/v3/...`. Ссылки v3 в теле ответа записываются обратно в формат v1 через modifyResponse. Современный backend активируется без каких-либо изменений в коде клиента.

Сохранение совместимости URL для партнёров B2B

Партнёр может годами использовать схему URL `/services/payments/...`, пока внутренняя команда перешла на `/v2/payment-api/...`. Правило set_path, специфичное для партнёра и ограниченное его Host-заголовком, обрабатывает преобразование. Партнёр работает со старым URL; новая архитектура сервиса работает внутри.

Инкрементальная миграция от монолита к микросервисам

Устаревший монолит обслуживает пути `/app/orders`, `/app/users` и `/app/inventory`, каждый из которых переносится в отдельный backend-сервис. TR7 применяет маршрутизацию на основе префиксов и переназначение путей, не раскрывая разделение клиентам. Пользователи сохраняют ту же схему URL, пока сервисы разделяются в фоновом режиме.

Снижение попыток обхода системы безопасности через нормализацию URL

Злоумышленник может пробовать процентно-кодированные пути, обходы через точечные сегменты или путаницу со слешами, чтобы обойти сопоставление сигнатур WAAP. normalize_uri приводит путь к канонической форме, и последующие средства WAAP работают с этим очищенным значением. Варианты URL, написанные по-разному, но нацеленные на один ресурс, оцениваются более последовательно.

Часто задаваемые вопросы

В чём разница между set_path и set_pathq?

set_path заменяет только часть пути запроса; строка запроса не сохраняется и отбрасывается. set_pathq перезаписывает путь и строку запроса вместе в едином действии. Когда существующие параметры запроса должны быть сохранены в новом пути, используется set_pathq и переменная `%QUERY` включается в новое значение пути.

Какие проблемы с URI решает normalize_uri?

normalize_uri предоставляет девять подопций: объединение множественных слешей, удаление точечных сегментов, разрешение обходов `../`, декодирование безопасных символов по RFC 3986, приведение процентно-кодированных последовательностей к верхнему регистру, удаление или кодирование фрагментов и сортировка параметров запроса по алфавиту. Эти опции используются для согласованности ключей кэша, читаемости аудита и устойчивости к попыткам обхода системы безопасности.

Как преобразуются внутренние ссылки в теле ответа?

Режим replace действия modifyResponse может сопоставлять шаблон регулярного выражения или простого текста в теле ответа и заменять его. После того как set_path преобразует внешний путь во внутренний на стороне запроса, modifyResponse записывает внутренние пути, которые backend возвращает в своём ответе, обратно во внешний формат. Клиент никогда не видит реальной структуры URL backend.

Может ли правило перезаписи применяться только к определённым партнёрам или тенантам?

Да. Каждое правило может быть ограничено условием FX/ACL. Условие Host-заголовка вида `%HOST == "partner-bank.example.com"` или совпадение значения заголовка вида `%HEADER("X-Tenant") == "tenant-a"` могут использоваться. Когда условие не выполняется, правило не срабатывает и запрос продолжает работать в обычном потоке.

Как перезапись пути соотносится с WAAP?

Перезапись пути применяется в фазе запроса до инспекции WAAP. Это означает, что сопоставление сигнатур WAAP, Virtual Patching и ограничение скорости — все работают на перезаписанном и нормализованном пути. Разрыв между внешним URL и внутренним путём сервиса не создаёт несоответствий в политике безопасности.

Если правило перезаписи сталкивается с ошибкой, запрос отбрасывается?

Нет. Если возникает ошибка разбора FX, отсутствующая переменная или несоответствие регулярному выражению, запрос продолжает работу в обычном потоке через безопасный резервный вариант — он не прерывается. Ошибка записывается в журнал аудита, чтобы оператор мог впоследствии изучить проблему конфигурации. Это поведение защищает производственный доступ.

Трансформируйте архитектуру путей без изменения backend

Версионирование API, совместимость URL для партнёров B2B и прозрачное переназначение путей backend — давайте разберём живую настройку на ваших собственных сервисах.