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

第一个（非匹配器）参数指定操作：

• 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中将 "/docs/" 替换为 "/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
}