Url Rewrite Filter 3.2.0中文手冊

原創 无意摘花 2020-05-10 20:28

注：本文檔基本3.2.0版本。原文請參閱：http://tuckey.org/urlrewrite/manual/3.2/index.html

手冊

    社區支持請訪問： urlrewrite谷歌小組 。

    閱讀 使用示例 和 ant任務 報告。如果你有任何找反饋，或者你想分享給大家的配置，可以 郵件我們 ，如果有任何建議和使用示例，請將它們提交到 urlrewrite谷歌小組論壇 。

安裝

  1. 下載zip（或tar.gz）並將解壓到你的上下文目錄中，比如把urlrewrite.xml放到WEB-INF目錄下。
  2. 把下面的代碼添加到WEB-INF/web.xml中（儘量放置到servlet配置的上方）（詳見過濾器參數部分） 
    <filter>
    <filter-name>UrlRewriteFilter</filter-name>
    <filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>UrlRewriteFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
    <dispatcher>FORWARD</dispatcher>
</filter-mapping>

     

  3. 把你的配置添加到WEB-INF/urlrewrite.xml中
  4. 重啓服務。

    你可以訪問    http://127.0.0.1:8080/rewrite-status  查看配置輸出。

過濾器參數（Filter Parameters） 

      下面列出了一些高級選項，如重新加載配置等。各個選項都有解釋。

<?xml version="1.0" encoding="UTF-8"?>

<filter>
    <filter-name>UrlRewriteFilter</filter-name>
    <filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter
</filter-class>
<!-- 設置配置文件重新加載的間隔時間，以秒計，必須是一個合法的整數（0表示每次修改都檢查，-1表示不做重新加載檢查，默認爲-1） -->
    <!-- 源碼中默認值爲0 -->
    <init-param>
        <param-name>confReloadCheckInterval</param-name>
        <param-value>60</param-value>
    </init-param>

    <!-- 如果需要求給配置文件的路徑，可以通過confPath參數，路徑相對於上下文跟目錄（默認爲/WEB-INF/urlrewrite.xml） -->
    <init-param>
        <param-name>confPath</param-name>
        <param-value>/WEB-INF/urlrewrite.xml</param-value>
    </init-param>

    <!-- 設置日誌級別，可選值爲 TRACE, DEBUG, INFO(默認), WARN, ERROR, FATAL； 日誌系統可選 log4j, 
        commons, slf4j； -->
    <init-param>
        <param-name>logLevel</param-name>
        <param-value>DEBUG</param-value>
    </init-param>

    <!-- 你可以修改urlrewrite狀態數據的目錄，以便它不與你已部署的應用相沖突（注：默認爲/rewrite-status） ，注：必須以/開頭 -->
    <init-param>
        <param-name>statusPath</param-name>
        <param-value>/status</param-value>
    </init-param>

    <!-- 可以禁用狀態頁面，可選值爲true/false，（默認爲true） -->
    <init-param>
        <param-name>statusEnabled</param-name>
        <param-value>true</param-value>
    </init-param>

    <!-- 你可能想允許其他的host也可以看到狀態頁，可以用statusEnabledOnHosts參數來配置，值爲,隔開的host列表，可使用*號通配符（默認爲"localhost, 
        local, 127.0.0.1"） -->
    <init-param>
        <param-name>statusEnabledOnHosts</param-name>
        <param-value>localhost, dev.*.myco.com, *.uat.mycom.com
        </param-value>
    </init-param>

    <!-- 默認false. 使用mod_rewrite風格的配置文件(若設置爲true，則confPath沒有被指定時會會設置爲/WEB-INF/.htaccess) -->
    <init-param>
        <param-name>modRewriteConf</param-name>
        <param-value>false</param-value>
    </init-param>

    <!-- 從參數modRewriteConfText中加載mod_rewrite風格的配置信息，注：如果調協這了個參數，其他的默認參數將被忽略 
    <init-param>
        <param-name>modRewriteConfText</param-name>
        <param-value>
            RewriteRule ^/~([^/]+)/?(.*) /u/$1/$2 [R] 
            RewriteRule ^/([uge])/([^/]+)$ /$1/$2/ [R]
        </param-value>
    </init-param>
    -->

    <!-- 默認爲false， 允許通過訪問下面的url設置使用哪個配置文件/rewrite-status/?conf=/WEB-INF/urlrewrite2.xml。僅爲測試方便而設計 
    <init-param>
        <param-name>allowConfSwapViaHttp</param-name>
        <param-value>false</param-value>
    </init-param>
    -->

</filter>

<filter-mapping>
    <filter-name>UrlRewriteFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
    <dispatcher>FORWARD</dispatcher>
</filter-mapping>

    注：設置logLevel爲log4j或者commons將導致日誌構建時調用log4j或commons-loggin類庫。因此，需要把相關jar引入到classpath中。

配置文件 WEB-INF/urlrewrite.xml

    一個簡單的配置文件如下所示，把它放置到WEB-INF下面，並命名爲urlrewrite.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE urlrewrite PUBLIC "-//tuckey.org//DTD UrlRewrite 3.2//EN"
        "http://www.tuckey.org/res/dtds/urlrewrite3.2.dtd">

<urlrewrite>
    <rule>
        <from>^/some/olddir/(.*)$</from>
        <to type="redirect">/very/newdir/$1</to>
    </rule>
    <rule match-type="wildcard">
        <from>/blog/archive/**</from>
        <to type="redirect">/roller/history/$1</to>
    </rule>
</urlrewrite>

    urlrewrite.xml文件必須名爲"urlrewrite.xml"的根節點，並且必須有至少一個rule元素。

    rule節點必須包含一個from和一個to，可以有0或多個condition元素，並且可以有0或多個set元素。

    當一個rule處理進來的請求時，所有的condition都會被執行，然後from將嘗試與請求URL進行匹配，由to和from指定模式生成最終的URL，只要該rule匹配上了，set即會被執行。

    當執行rule時，過濾器將會對所有的rule進行一個非常簡單的循環，對每個rule執行如下僞代碼所未的動作

Pattern.compile(<from> element);
pattern.matcher(request url);
matcher.replaceAll(<to> element);
if ( <condition> elements match && matcher.find() ) {
    handle <set> elements (if any)
    execute <run> elements (if any)
    perform <to> element (if any)
}

3.1 <urlrewrite>元素

    頂級元素。

屬性 取值 解釋
default-match-type（可選） regex(默認) 所有的rule和condition都會使用Java正則表達式引擎（除非在某個rule上指定了match-type）
  wildcard 所有的rule和condition都會使用通配符表達式引擎（除非在某個rule上指定了match-type ） 
decode-using（可選） header,utf-8(默認) 如果URL解碼時將使用request.getCharacterEncoding()，如果返回值爲空，則使用UTF-8
  null 不解碼
  header 只使用request.getCharacterEncoding()解碼
  [encoding]

僅使用指定編碼去解碼，如ISO-8859-1。到 Java Charset Object  查看所有的編碼。
  header,[encoding] 當URL解碼時使用request.getCharacterEncoding() 解碼，如果爲空，使用指定的編碼去解碼。 
use-query-string（可選） false（默認） 查詢參數不使會加到from中的url上。
  true 查看參數添加到from的url上。
use-context（可選） false（默認） 上下文路徑不會被添加到from的url上。
  true 上面文件路徑會被添加到from的url上。

3.2 <rule>元素

    零個或多個，規則的基礎組件。

屬性 取值 解釋
enabled（可選） true（默認） 啓用該規則
  false 禁用該規則
match-type（可選） regex(默認) 該rule和condition都會使用Java正則表達式引擎
  wildcard 該rule和condition使用通配符表達式引擎

    下面的示例，請求/world/usa/nyc會被分發到/world.jsp上

<rule match-type="regex">
       <from>^/world/([a-z]+)/([a-z]+)$</from>
       <to>/world.jsp</to>
    </rule>
    <rule match-type="wildcard">
       <from>/world/*/*</from>
       <to>/world.jsp</to>
    </rule>

3.3 <outbound-rule> 元素

   零或多個。相對於通用的規則來說，這個很簡單，只是它通過response.encodeURL()用來重寫url。

屬性 取值 解釋
enabled（可選） true（默認） 啓用該規則
  false 禁用該規則
encodefirst（可選） false (默認) 運行該規則後，執行encodeURL
  true  運行該規則之前，執行encodeURL

    可以包含 run、from、to 和 set元素，例如：

 <outbound-rule>
        <from>^/world.jsp?country=([a-z]+)&amp;city=([a-z]+)$</from>
        <to>/world/$1/$2</to>
    </outbound-rule>

    使用上面的示例，下面的jsp代碼：

<a href="<%= response.encodeURL("/world.jsp?country=usa&amp;city=nyc") %>">nyc</a>

    將會輸出爲：

<a href="/world/usa/nyc">nyc</a>

    或者使用JSTL標籤

<a href="<c:url value="/world.jsp?country=${country}&amp;city=${city}" />">nyc</a>

    將會輸出爲：

<a href="/world/usa/nyc">nyc</a>

    注：如果使用JSTL，也好使。

 

3.4 <name> 元素

    這也是一個可選元素，用於標識規則的名稱。可以用於rule和outbound-rule。

 <rule>
        <name>World Rule</name>
        <from>^/world/([a-z]+)/([a-z]+)$</from>
        <to>/world.jsp?country=$1&amp;city=$2</to>
    </rule>

3.5 <note>元素

    這個簡單的可選元素，用於描述某個規則。可用於rule和outbound-rule。

 <rule>
        <name>World Rule</name>
        <note>
            Cleanly redirect world requests to JSP,
            a country and city must be specified.
        </note>
        <from>^/world/([a-z]+)/([a-z]+)$</from>
        <to>/world.jsp</to>
    </rule>

3.6 <condition>元素

    提供給你爲某個規則選擇條件的元素。規則的所有條件必須都必須被滿足（除非or上顯示設置了next）。取值可以是正則表達式。

屬性 取值 解釋
類型（可選） header(默認) 如果選擇這個類型，頭名稱必須用name屬性來指定
  method 請求的方式，如GET、POST、HEAD等
  port 正在運行的web應用服務的端口
  time 服務端的當前 時間。（取值爲自1970-01-01 00:00:00開始的秒數，或者unix時間），即（new Date().getTime()）。這可能用於確定內容只在你設置的時間點生效。 
  year 服務器當前年份。即 (Calendar.getInstance()).get(Calendar.YEAR)
  month 服務器當前月份。一月是0。即(Calendar.getInstance()).get(Calendar.MONTH)
  dayofmonth

服務器一月中的第幾天。3月份第一天是1.即
(Calendar.getInstance()).get(Calendar.DAY_OF_MONTH) 
  dayofweek

服務器周的第幾天。週六是1，週日是7。即
(Calendar.getInstance()).get(Calendar.DAY_OF_WEEK) 
  ampm

服務器端上午還是下午，即
(Calendar.getInstance()).get(Calendar.AM_PM) 
  hourofday

服務器端一天中的第幾小時（24小時制），下午10點是22，即
(Calendar.getInstance()).get(Calendar.HOUR_OF_DAY) 
  minute

服務端當前時間的分鐘字段，即
(Calendar.getInstance()).get(Calendar.MINUTE) 
  second

服務端當前時間的秒鐘字段，即
(Calendar.getInstance()).get(Calendar.SECOND) 
  millisecond 服務端當前時間的毫秒字段，即
(Calendar.getInstance()).get(Calendar.MILLISECOND)
  attribute 將會檢查request中arttribute中的值，（不要與parameter混淆），當使用該類型時，name必須設置。
即request.getAttribute([name])
  auth-type 將檢查request的驗證類型，即：request.getAuthType()
  character-encoding 當前請求的字符編碼，即
request.getCharacterEncoding()
  content-length 請求的內容長度（可以讓你拒絕大請求），即request.getContentLength()
  content-type 請求的內容類型（可能不是很有用），即：request.getContentType()
  context-path 請求的上下文路徑，即：request.getContextPath()
  cookie

cookie的值，注：用該類型時name必須指定。即
request.getCookies()

 
  parameter 一個檢查查詢參數的更條理的方式，這將檢查GET或POST請求的參數，注：name必須指定。即：request.getParameter([name])
  path-info 即：request.getPathInfo()
  path-translated 即：request.getPathTranslated()
  protocol 請求的協議，如HTTP/1.1。即：request.getProtocol()
  query-string 組成當前請求的查詢參數，如id=2345&name=bob，即：request.getQueryString()
  remote-addr 組成當前請求的客戶端IP地址，如123.123.123.123，即：getRemoteAddr()
  remote-host 組成當前請求的遠程主機名，如123qwdsl.att.com（注：這僅在你的應用服務器配置了獲取主機名時纔有效，多數沒有配置）。即：request.getRemoteHost()
  remote-user 如果用戶已通過驗證，該值表示請求的登錄用戶，即：request.getRemoteUser()
  requested-session-id 返回由客戶端指定的會話ID，如：2344asd234sada4 。即：request.getRequestedSessionId()
  requested-session-id-from-cookie sessionID是否來自於cookie，即：request.isRequestedSessionIdFromCookie()
  requested-session-id-from-url cookie是否來自來URL，即：isRequestedSessionIdFromURL()
  requested-session-id-valid cookie是否有效。即：request.isRequestedSessionIdValid()
  request-uri 返回請求url從協議名到查詢參數的一部分，HTTP請求的第一行。即：request.getRequestURI()
  request-url 重建客戶端請求的URL，返回的URL包含了協議、服務名、端口和路徑，但不包吃住查詢參數。即：request.getRequestURL()
  session-attribute （注：name必須設置），即：session.getAttribute([name])
  session-isnew 會話是否是新的。即：session.isNew()
  server-name 服務端的主機名，哪個請求被髮送（來自於主機header而不是機器名），即request.getServerName().
  scheme

請求使用的scheme，如http或https。

即：request.getScheme()

 
  user-in-role

該值不能是正則表達式。

即：request.isInRole([value])

 
name(可選)  可以任何值 如果type是header，則該項用給定了name的http請求頭與運行值比較。
next(可選)  and（默認） 下一個規則與該規則都匹配
  or 下一個規則或這個條件任一個匹配
operator(可選)  equal（默認） 相等，表示正則表達式匹配或值相等
  notequal 不等於，注：只有數值型都有效
  greater 大於，注：只有數值型都有效
  less 小於，注：只有數值型都有效
  greaterorequal 大於或等於，注：只有數值型纔有效
  lessorequal 小於或等於，注：只有數值型纔有效

示例：

    <condition name="user-agent" operator="notequal">Mozilla/[1-4]</condition>
    <condition type="user-in-role" operator="notequal">bigboss</condition>
    <condition name="host" operator="notequal">www.example.com</condition>
    <condition type="method" next="or">PROPFIND</condition>
    <condition type="method">PUT</condition>

3.7 <from>元素

    每個rule或outbound-rule都必須有from元素。取可以是個正則表達式，注：from的url是相對上下文路徑。

屬性 取值 解釋
casesensitive（可選） false（默認） 大小寫不敏感
  true 大小寫敏感

示例：

    <from>^/world/([a-z]+)$</from>

 

3.8 <to>元素

    值可以是正則替換表達式。

屬性 取值 解釋
type（可選） forward（默認）

如果請求匹配了rule上的conditions，則from上指定的url將內部跳轉至to元素指定的url上，注：to上的url的上下文必須與from的相同。與下面的代碼效果相同：

RequestDispatcher rq = request.getRequestDispatcher([to value]);
rq.forward(request, response);
  passthrough 與forward相同
  redirect

請求匹配上了condition，則from的url將重定向至to指定的url。與下面的代碼效果相同：

HttpServletResponse.sendRedirect([to value]))
  permanent-redirect

與下面代碼相同：

response.setStatus(HttpServletResponse.SC_MOVED_PERMANENTLY); 
response.setHeader("Location", [to value]); 

(注：SC_MOVED_PERMANENTLY是HTTP狀態碼，值爲301)
  temporay-redirect

與下面代碼相同：

response.setStatus(HttpServletResponse.SC_MOVED_TEMPORARILY);
response.setHeader("Location", [to value]); 

(注： SC_MOVED_TEMPORARILY是HTTP狀態碼，值爲302)
  pre-include  
  post-include  
  proxy 請求將被代理到指定的完整url上，當使用該特性時，必須把common-http和commons-codec放到類路徑當中。
last（可選） false（默認） 如果這個rule成功，則剩餘的rule也會被處理。
  true 如果這個rule匹配上，則剩餘的rule不再處理了。
encode（可選） false（在rule中爲默認） response.encodeURL([to])不會被執行
  true（在outbound-rule中爲默認） 在to元素指定的url進行重定向之前，執行response.encodeURL([to])
context（可選）  

如果應用服務端配置了允許“cross context”通訊，則該屬性可以用於forward（僅僅是forward，而不是重定向或其的to類型）請求到一個指定名稱的servlet上下文。

在Tomcat中，對一個實例，應用上下文在服務項配置（server.xml或context.xml）需要一個可選項crossContext="true"。對實例，前面提到的兩個應用要定義成下面的樣式：

<Context docBase="app" path="/app" reloadable="true" crossContext="true"/> 

<Context docBase="forum" path="/forum" reloadable="true" crossContext="true"/>

    注："to"元素的值可以爲null，例如<to>null</to>，意思是如果該rule匹配後，請求不會繼續往後走了，即該fileter將不調用chain.doFilter。

    如果"to"元素被設置爲-，則沒有適當的url被替換，請求還會像原生一樣，就像沒發生任何事一樣。即該filter將調用chain.doFilter

 

發表評論
所有評論
還沒有人評論，想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章

簡單瞭解 java urlrewrite

無脸男 2020-02-20 20:08:33

MIME類型完整列表

无意摘花 2020-05-10 20:28:41

配置文件WEB-INF/urlrewrite.xml

1. DTD約束 <!DOCTYPE urlrewrite         PUBLIC "-//tuckey.org//DTD UrlRewrite 3.0//EN"         "http://tuckey.org/res/d

szymark 2020-07-05 22:32:10

普通web項目和springboot項目的URLrewrite講解

知兮寒兮 2020-05-06 16:48:18

URLRewrite

chenzhao12 2020-02-25 07:52:56

UrlRewriteFilter 學習筆記

hybaym 2020-02-21 07:17:31

C語言 - 學習

ning先森 2020-04-16 08:24:14

PostgreSQL11.2-CN-v0.1中文手冊.chm

PostgreSQL_HighGoDB 2020-03-02 12:27:17

MIME類型完整列表

无意摘花 2020-05-10 20:28:41

Nginx rewrite模塊

Nginx rewrite模塊 1.詳細文檔 淘寶團隊翻譯的詳細文檔 http://tengine.taobao.org/nginx_docs/cn/docs/http/ngx_http_rewrite_module.html 2.

camelNiu 2020-07-07 21:56:56

配置文件WEB-INF/urlrewrite.xml

1. DTD約束 <!DOCTYPE urlrewrite         PUBLIC "-//tuckey.org//DTD UrlRewrite 3.0//EN"         "http://tuckey.org/res/d

szymark 2020-07-05 22:32:10

普通web項目和springboot項目的URLrewrite講解

知兮寒兮 2020-05-06 16:48:18

URLRewrite

chenzhao12 2020-02-25 07:52:56

C語言 - 學習

ning先森 2020-04-16 08:24:14

PostgreSQL11.2-CN-v0.1中文手冊.chm

PostgreSQL_HighGoDB 2020-03-02 12:27:17