uri

操纵请求的 URI。它可以从路径中去除前缀/后缀，或在整个 URI 上替换子字符串。

该指令与 rewrite 不同，uri 是以可区分的方式改变 URI，而不是像 rewrite 那样将其重置为完全不同的值。rewrite 被特殊处理为内部重定向，而 uri 只是另一个中间件。

语法

支持多种不同的操作：

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>]
	...
}

第一个（非 matcher）参数指定操作类型：

• 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

在任何请求 URI 中将 "/" 替换为 "/v1/docs/"：

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
}