集册 Tomcat 8 权威指南 重写机制

重写机制

欢马劈雪     最近更新时间：2020-08-04 05:37:59

581

简介

重写 Valve（Rewrite Valve） 实现 URL 重写功能的方式非常类似于 Apache HTTP Server 的 mod_rewrite 模块。

配置

重写 Valve 是通过使用 org.apache.catalina.valves.rewrite.RewriteValve 类名来配置成 Valve 的。

经过配置，重写 Valve 可以做为一个 Valve 添加到 Host 中。参考虚拟服务器文档来了解配置详情。该 Valve 使用包含重写指令的 rewrite.config 文件，且必须放在 Host 配置文件夹中。

另外，重写 valve 也可以用在 Web 应用的 context.xml 中。该 Valve 使用包含重写指令的 rewrite.config 文件，且必须放在 Web 应用的 WEB-INF 文件夹中。

指令

rewrite.config 文件包含一系列指令，这些指令和 mod_rewrite 所用的指令很像，尤其是核心的 RewriteRule 与 RewriteCond 指令。

注意：该部分内容修改自 mod_rewrite 文档，后者版权归属于 Apache 软件基金会（1995-2006），遵循 Apache 许可发布。

1. RewriteCond

格式：RewriteCond TestString CondPattern

RewriteCond 指令定义了一个规则条件。一个或多个 RewriteCond 指令可以优先于 RewriteRule 指令执行。如果 URI 当前状态匹配它的模式，并且满足了这些条件，才会使用下列规则。

TestString 是一种字符串，除了简单的文本之外，它还可以含有下列扩展结构。

  • RewriteRule backreferences 对形式 $N（0 <= N <= 9）的反向引用。提供对模式成组部分的访问（括号中的），从属于 RewriteCond 条件当前状态的 RewriteRule。
  • RewriteCond backreferences
  • RewriteMap expansions

  • Server-Variables 这些是形式 %{ NAME_OF_VARIABLE } 中的变量。%{ NAME_OF_VARIABLE } 中的 NAME_OF_VARIABLE 是一种取自下面列表的字符串：

  • HTTP 报头：
HTTP\_USER\_AGENT  
HTTP\_REFERER  
HTTP\_COOKIE  
HTTP\_FORWARDED  
HTTP\_HOST  
HTTP\_PROXY\_CONNECTION  
HTTP\_ACCEPT
  • 连接与请求： 
REMOTE\_ADDR  
REMOTE\_HOST  
REMOTE\_PORT  
REMOTE\_USER  
REMOTE\_IDENT  
REQUEST\_METHOD  
SCRIPT\_FILENAME  
REQUEST\_PATH  
CONTEXT\_PATH  
SERVLET\_PATH  
PATH\_INFO  
QUERY\_STRING  
AUTH\_TYPE
  • 服务器内部：
DOCUMENT\_ROOT    
SERVER\_NAME  
SERVER\_ADDR  
SERVER\_PORT  
SERVER\_PROTOCOL  
SERVER\_SOFTWARE
  • 日期与时间： 
TIME\_YEAR  
TIME\_MON  
TIME\_DAY  
TIME\_HOUR  
TIME\_MIN  
TIME\_SEC  
TIME\_WDAY  
TIME
  • 特殊字符串： 
THE\_REQUEST  
REQUEST\_URI  
REQUEST\_FILENAME  
HTTPS

这些变量对应着相似名称的 HTTP MIME 报头和 Servlet API 方法。多数都记录在各种手册和 CGI 规范中。下面列出了重写 Valve 专有的那些变量：

  • REQUEST_PATH
    对应用于映射的完整路径。
  • CONTEXT_PATH
    对应映射的上下文的路径。
  • SERVLET_PATH
    对应 Servlet 路径。
  • THE_REQUEST
    由浏览器发送给服务器的完整 HTTP 请求代码行（比如，GET /index.html HTTP/1.1）。这并不包括任何由浏览器发送的额外报头。
  • REQUEST_URI
    HTTP 请求代码行中所请求的资源（在上例中，应为为 /index.html）。
  • REQUEST_FILENAME
    与请求相匹配的文件或脚本的完整本地文件系统路径。
  • HTTPS
    当连接使用 SSL/TLS 时，含有文本 "on"，否则含有 "off"。

另外还需要注意的是：

  1. SCRIPT_FILENAME 和 REQUEST_FILENAME 含有同样的值：Apache 服务器内部结构 request_rec 的 filename 字段值。第一个名称常被称为 CGI 变量值，第二个名称相当于 REQUEST_URI（包含 request_rec 的 uri 字段值）。
  2. %{ENV:variable}。其中的 variable 可以是任何 Java 系统属性。目前可以使用。
  3. %{SSL:variable}。其中的 variable 是 SSL 环境变量名。目前还未实现。范例： %{SSL:SSL_CIPHER_USEKEYSIZE} 可能扩展到 128。
  4. %{HTTP:header}。其中的 header 可以是任意的 HTTP MIME 报头名称。该变量常用来获取发送到 HTTP 请求的报头值。范例： %{HTTP:Proxy-Connection} 是 HTTP 报头 Proxy-Connection: 的值。

CondPattern 即条件模式，是一种应用于 TestString 当前实例的正则表达式。TestString 在匹配 CondPattern 之前，会首先求值。

谨记：CondPattern 是一种兼容 perl 并带有一些扩展的正则表达式。

  1. 可以在模式字符串前加上 ! 字符作为前缀，来指定非匹配模式。
  2. CondPattern 有一些特殊变体。除了真正的正则表达式字符串外，还可以使用下列组合形式之一：
    • <CondPattern (字母顺序高于)
      将 CondPattern 当成一种纯粹字符串，按照字母顺序将其与 TestString 进行对比。如果在字母顺序上，TestString 高于 CondPattern ，则为 true。
    • >CondPattern（字母顺序低于） 将 CondPattern 当成一种纯粹字符串，按照字母顺序将其与 TestString 进行对比。如果在字母顺序上，TestString 低于 CondPattern ，则为 true。
    • =CondPattern' (字母顺序等于)
      将 CondPattern 当成一种纯粹字符串，按照字母顺序将其与 TestString 进行对比。如果在字母顺序上，TestString 等于 CondPattern ，则为 true。
    • -d（目录）
      将 TestString 当成一种路径名，测试它是否存在并且是一个目录。
    • -f（常规文件） 将 TestString 当成一种路径名，测试它是否存在并且是一个常规文件。
    • -s（常规文件，带有文件尺寸）
      将 TestString 当成一种路径名，测试它是否存在并且是一个文件大小大于 0 的普通文件。

注意：所有这些测试都可以加上前缀 ! 来使它们的含义反向。

  1. 可以将 [flag] 做为 RewriteCond 指令的第三个参数，为 CondPattern 设定标记。这里的 flag 是一个包含下列任一标记，且标记间由逗号分隔的列表：
    • nocase|NC（不区分大小写） 无论是扩展的 TestString 还是在 CondPattern 中，都不区分大小写（A-Z 和 a-z 是等同的）。该标记只有在比较 TestString 和 CondPattern 时才是有效的。对于文件系统和子请求（HTTP 请求）是无效的。
    • ornext|OR（或者下一个条件） 利用本地 OR（而不是隐式的 AND）来组合规则条件。典型范例为：
RewriteCond %{REMOTE_HOST}  ^host1.*  [OR]  
RewriteCond %{REMOTE_HOST}  ^host2.*  [OR]  
RewriteCond %{REMOTE_HOST}  ^host3.*  
RewriteRule ...some special stuff for any of these hosts...

没有该标记，你必须写三遍条件/规则对。

范例：

假如想根据请求头的 User-Agent: 对网站主页进行重写，可以使用下列代码： 

RewriteCond  %{HTTP_USER_AGENT}  ^Mozilla.*
RewriteRule  ^/$                 /homepage.max.html  [L]

RewriteCond  %{HTTP_USER_AGENT}  ^Lynx.*
RewriteRule  ^/$                 /homepage.min.html  [L]

RewriteRule  ^/$                 /homepage.std.html  [L]

说明：如果使用的浏览器将它自身标识为 'Mozilla'（包括 Netscape Navigator、Mozilla，等等），那么这就是内容最大化主页（max homepage。它可以包含框架或其他特性）；如果使用的是 Lynx 浏览器（基于终端的），那么获得的就是内容最小化的主页（min homepage）——专为便于浏览文本而设计的版本；如果这些条件都不适用（你使用的是其他浏览器，或者你的浏览器将其自身标识为非标准内容），那么得到的就是标准主页（std homepage）。

2. RewriteMap

格式：RewriteMap name rewriteMapClassName optionalParameters。

通过用户必须实现的一个接口来实现映射。类名为 org.apache.catalina.valves.rewrite.RewriteMap，代码为： 

package org.apache.catalina.valves.rewrite;

public interface RewriteMap {
public String setParameters(String params);
public String lookup(String key);
}

3. RewriteRule

格式：RewriteRule Pattern Substitution

RewriteRule 指令是重写机制的核心。此指令可以多次使用，每个实例都定义一个单独的重写规则。这些规则的定义顺序尤为重要，因为这是在运行时应用它们的顺序。

模式是一个作用于当前 URL 的兼容 perl 的正则表达式，这里的“当前”是指该规则生效时的 URL，它可能与被请求的 URL 不同，因为其他规则可能在此之前已经发生匹配并对它做了改动。

下面是关于正则表达式格式的一些提示：

文本：

  • .——匹配任何单个字符
  • [chars]——匹配当前字符
  • [^chars]——不匹配当前字符
  • text1|text2——匹配 text1 或 text2

量词:

  • ?——零个或者 1 个 ? 号前的字符
  • *——零个或者 N 个 * 号前的字符（N > 0）
  • +——零个或 N 个 + 号前的字符（N > 1）

分组： (text)——文本分组（设定第 N 组可以被引用为 RewriteRule）

行锚

^——匹配一行起始处的空字符串。
$——匹配一行结束处的空字符串。

转义

\char ——将指定字符转义（比如将.、[]、() 等字符转义）

要想了解更多关于正则表达式的信息，请参见 perl 正则表达式在线联机手册（perldoc perlre）。关于正则表达式及其变体（POSIX 正则表达式）的详情，可看看这本书： 

*Mastering Regular Expressions, 2nd Edition* （目前该书为第 3 版）
Jeffrey E.F. Friedl 
O'Reilly & Associates, Inc. 2002
ISBN 978-0-596-00289-3

在规则中，NOT 字符（!）可作为模式的前缀，实现逆向模式。比如“如果当前 URL 并不匹配该模式”。这可以用在易于匹配的是逆向模式这种异常情况下，或者也可以作为最后一个默认规则来使用。

注意：在使用 NOT 字符反转模式时，不能在模式中包含分组的通配成分。这是因为，如果模式不匹配（比如反匹配），分组内将没有内容。如果使用了逆向模式，就不能在替代字符串中使用 $N。

重写规则中的替代字符串（substitution string）是一种用来取代模式匹配的原始 URL 的字符串。除了纯文本之外，它还包括：

  1. 反向引用（$N）RewriteRule 模式。
  2. 反向引用（%N）最后匹配的 RewriteCond 模式。
  3. 规则条件测试字符串中（%{VARNAME}）的服务器变量。
  4. 映射函数调用（${mapname:key|default}）。

反向引用表示的是形式 $N（N 的范围为 0-9），它是指用模式所匹配的第 N 组的内容去替换 URL。服务器变量 RewriteCond 指令的 TestString 所用的相同。映射函数来自 RewriteMap 指令。这 3 类变量都按照上述顺序展开。

如前所述，所有的重写规则都应用于替代字符串（按照配置文件中所定义的顺序）。URL 完全由替代字符串所替换，直到所有规则都应用完毕，重写过程才结束（或利用 L 标记来终止）。

还有一个特殊的替代字符串：-，意思是不替代，当需要让重写规则只匹配 URL 而不替换时，就用得上它了。这一字符串通常与 C（chain）标记配合使用，为的是在替换发生前应用多个模式。

另外，还可以将 [flags] 做为 RewriteRule 的第三个参数，从而为替代字符串设置特殊标记。flags是一个包含下列标记且标记间以逗号分隔的列表：

  • chain|C （与下一个规则相链接）

此标记使当前规则与下一个规则（它又可以与其后规则相链接，如此反复）相链接。 它产生如下效果：如果某个规则被匹配，通常会继续处理其后继规则，这个标记就不起作用；如果某规则不被匹配，则其后继链接规将会被忽略。比如，在执行一个外部重定向时， 对一个目录级规则集，你可能需要删除 .www（因为此处不应该出现 .www）。

  • cookie|CO = NAME:VAL:domain[:lifetime[:path]] （设置 cookie）

在客户端浏览器上设置一个 cookie。cookie 的名称是 NAME，其值是 VAL。 domain 字段是该 cookie 的域，比如 .apache.org，可选的lifetime 是 cookie 生命周期（以分钟计），可选的 path 是 cookie 的路径。

  • env|E = VAR:VAL （设置环境变量）

强制一个名为 VAR 的请求变量值为 VAL，VAL可以包含可扩展的反向引用的正则表达式 $N 和 %N。可以多次使用该标记，以便设置多个变量。

  • forbidden|F（强制禁止访问该 URL ）

强制禁止访问当前的 URL——立即反馈一个 HTTP 响应代码 403。使用这个标记，可以链接若干 RewriteConds 以阻断某些 URL。

  • gone|G（强制 URL 为已失效）

强制当前 URL 为已失效——立即反馈一个 HTTP 响应代码 410（请求资源已被删除）。使用这个标记，可以标明页面已被删除而不存在.

  • host|H=Host（重写虚拟主机）
    重写虚拟主机，而不是重写 URL。

  • last|L（最后一个规则）

立即停止重写操作，并不再应用其他重写规则。它对应于 Perl 中的 last 命令或 C 语言中的 break 命令。使用该标记可以防止当前已被重写的 URL 被后续规则所继续重写。比如，用它可以将根路径的 URL（/）重写为实际存在的 URL，比如：/e/www/。

展开阅读全文