uri

Изменяет URI запроса. Может удалять префикс/суффикс пути или заменять подстроки в полном URI.

Эта директива отличается от rewrite тем, что uri дифференцированно изменяет URI, а не устанавливает его в совершенно другое значение, как делает rewrite. В то время как rewrite обрабатывается как внутренний редирект, uri — это просто ещё один middleware.

Синтаксис

Поддерживается множество различных операций:

uri [<matcher>] strip_prefix <target>
uri [<matcher>] strip_suffix <target>
uri [<matcher>] replace      <target> <replacement> [<limit>]
uri [<matcher>] path_regexp  <target> <replacement>
uri [<matcher>] query        [-|+]<param> [<value>]
uri [<matcher>] query {
	<param> [<value>] [<replacement>]
	...
}

Первый (не-матчер) аргумент определяет операцию:

• strip_prefix удаляет префикс из пути.

• strip_suffix удаляет суффикс из пути.

• replace выполняет замену подстроки по всему URI.

  • <target> — это префикс, суффикс или поисковая строка/регулярное выражение. Если префикс, ведущий слеш можно опустить, так как пути всегда начинаются со слеша.

  • <replacement> — это строка замены. Поддерживает использование групп захвата с $name или ${name} синтаксисом, или с номером для индекса, например $1. Подробнее см. документацию Go. Если значение замены равно "", то соответствующий текст удаляется из значения.

  • <limit> — это необязательный лимит на максимальное количество замен.

• path_regexp выполняет замену по регулярному выражению в части пути URI.

  • <target> — это префикс, суффикс или поисковая строка/регулярное выражение. Если префикс, ведущий слеш можно опустить, так как пути всегда начинаются со слеша.

  • <replacement> — это строка замены. Поддерживает использование групп захвата с $name или ${name} синтаксисом, или с номером для индекса, например $1. Подробнее см. документацию Go. Если значение замены равно "", то соответствующий текст удаляется из значения.

• query выполняет манипуляции с запросом URI, причем режим зависит от префикса имени параметра или количества аргументов. Блок может быть использован для указания нескольких операций сразу, сгруппированных и выполняемых в следующем порядке: переименование 🡒 установка 🡒 добавление 🡒 замена 🡒 удаление.

  • Без префикса параметр устанавливается с заданным значением в запросе. Например, uri query foo bar установит значение параметра foo в bar.

  • Префикс с - удаляет параметр из запроса. Например, uri query -foo удалит параметр foo из запроса.

  • Префикс с + добавляет параметр в запрос со значением. Это не перезапишет существующий параметр с тем же именем (опустите + чтобы перезаписать).

    Например, uri query +foo bar добавит foo=bar в запрос.

  • Параметр с > в качестве инфикса переименует параметр на значение после >.

    Например, uri query foo>bar переименует параметр foo в bar.

  • С тремя аргументами выполняется замена значения параметра запроса по регулярному выражению, где первый аргумент — имя параметра запроса, второй — искомое значение, а третий — замена. Первый аргумент (имя параметра) может быть * для выполнения замены на всех параметрах запроса.

    Поддерживает использование групп захвата с $name или ${name} синтаксисом, или с номером для индекса, например $1. Подробнее см. документацию Go. Если значение замены равно "", то соответствующий текст удаляется из значения.

    Например, uri query foo ^(ba)r $1z заменит значение параметра foo, где значение начиналось с bar, в результате чего значение станет baz.

Изменения URI происходят в нормализованной или неэкранированной форме URI. Однако, последовательности экранирования могут использоваться в шаблонах префикса или суффикса для сопоставления только этих буквальных экранирований в этих позициях в пути запроса. Например, uri strip_prefix /a/b перепишет как /a/b/c, так и /a%2Fb/c в /c; а uri strip_prefix /a%2Fb перепишет /a%2Fb/c в /c, но не сопоставит /a/b/c.

Путь URI очищается от точек перехода каталогов перед модификациями. Кроме того, несколько слешей (например, //) объединяются, если <target> не содержит нескольких слешей.

Похожие директивы

Некоторые другие директивы также могут изменять URI запроса.

• rewrite изменяет весь путь и запрос на новое значение вместо частичного изменения значения.

• handle_path делает то же самое, что и handle, но удаляет префикс из запроса перед запуском обработчиков. Может быть использовано вместо uri strip_prefix, чтобы устранить одну лишнюю строку конфигурации во многих случаях.

Примеры

Удалить /api из начала всех путей запросов:

uri strip_prefix /api

Удалить .php из конца всех путей запросов:

uri strip_suffix .php

Заменить "/docs/" на "/v1/docs/" в любом URI запроса:

uri replace /docs/ /v1/docs/

Объединить все повторяющиеся слеши в пути запроса (но не в запросе) в один слеш:

uri path_regexp /{2,} /

Установить значение параметра запроса foo в bar:

uri query foo bar

Удалить параметр foo из запроса:

uri query -foo

Переименовать параметр запроса foo в bar:

uri query foo>bar

Добавить параметр bar в запрос:

uri query +foo bar

Заменить значение параметра запроса foo, где значение начинается с bar, на baz:

uri query foo ^(ba)r $1z

Выполнить несколько операций запроса одновременно:

uri query {
	+foo bar
	-baz
	qux test
	renamethis>renamed
}