GoAhead3 - 路由处理

一. 前言

        GoAhead包含一个强大的请求路由引擎，管理客户端HTTP请求的处理方式。路由是由一个名为route.txt的配置文件中的一组路由配置而成。这个文件在GoAhead启动时被加载。当收到一个请求时，路由引擎会测试各个路由，并选择最佳路由来处理该请求。在这个过程中，路由可以根据需要重定向或重写请求。

        一个GoAhead配置通常会有很多条路由，通过将路由URI模式与请求的URL相匹配，对配置的路由依次进行测试。一个路由可能需要满足更多的前提条件才适合处理请求。如果所需条件没有得到满足，配置文件的下一条路由将被测试。总是有一个"万能的路由"，如果所有先前的路由都不符合条件，它将处理该请求。

二. 路由配置

1. 路由配置文件

        路由规则由route.txt配置文件定义。配置文件中有一系列的路由执行规则。路由配置样式如下

route uri=/cgi-bin dir=cgi-bin handler=cgi
route uri=/action handler=action
route uri=/ extensions=jst,asp handler=jst
route uri=/ methods=OPTIONS|TRACE handler=options

         文件的每行定义一条新的路由规则，虽然路由规则有很多可选的参数，但是每条路由规则都必须要有一个uri关键字，它定义了一个URI前缀 (合格的请求都需要有)。如果客户端请求的URI不符合路由URI的前缀，那么该条路由规则将被跳过，继续匹配下一条。

2. 路由配置顺序

        当配置文件中有多条路由规则，路由匹配的顺序是按照路由规则在配置文件中定义的先后决定的，因此顺序非常的重要。对于具有相似前导字符的路由，具有更长URI的路由应该定义在更前面。

三. 路由配置关键字

        路由规则是由一系列键值对( keyword=value )组成，所有路由规则都必须要有uri关键字，其他的关键字是可选的，下面是所有支持的路由关键字，如下：

1. abilities

        abilities关键字指定了当访问该路由所描述的资源时，用户所需要的能力，能力不满足，则不能访问该路由指定的资源。多个abilities以逗号分隔。当多个abilities被指定时，指定的所有abilities都需要满足。例如：

route uri=/auth/basic/ auth=basic abilities=create,edit,view

        激活用户的abilities，是通过auth.txt文件的关键字指定使能认证和授权。举例如下：

role name=manager abilities=view,edit,delete
user name=joshua password=2fd6e47ff9bb70c0465fd2f5c8e5305e roles=manager

2. auth

        auth关键字指定了要使用的认证方案。认证是一个要求用户提供用户名和密码的过程，然后验证凭证的有效性，最后确定应该授权该用户哪些abilities。支持的认证方案有：basic（Basic authentication），digest（Digest authentication），form（web-form based authentication）。

        如果用户的凭证不能被认证，用户将被重定向一个新的由redirect关键字指定的URI，当认证失败时，GoAhead回复一个HTTP 401状态码，意味着不能被授权访问，举例如下：

route uri=/ auth=form handler=continue redirect=401@/pub/login.html

3. dir

        dir关键字定义了这个路由的包含文档的文件系统目录，这会覆盖默认的文档路径。如果客户端请求一个具体的文档时，请求的URI的路径会被附加到这个目录中用来定位要提供的文件。

4. extensions

        extensions关键字指定了由该路由提供的文档的扩展名，例如：

route uri=/ extension=cgi|fcgi|mycgi handler=cgi

5. handler

        handler关键字指定了负责生成响应的GoAhead处理程序。如果没有指定，默认为文件处理程序。有效的handler包括：action，cgi，file，jst，options，redirect和upload。

6. methods

        一条路由规则可以定义一组可接受的HTTP方法，多个方法应该通过"|"符号分隔开，例如：

route uri=/put/ methods=PUT|DELETE

        标准的HTTP方法有：DELETE，GET，OPTIONS，POST，PUT和TRACE。

7. protocol

        一条路由可以通过protocol关键字，将协议限制在一个指定的协议，例如HTTP或HTTPS。案例如下：

route uri=/ protocol=https

8. redirect

        redirect关键字指定目标URI，客户端将根据响应的HTTP的状态码被重定向到这些URI。

格式为：

        redirect=STATUS@URI

STATUS是HTTP状态码，并且URI需要是一个有效的目标URI，例如：

route uri=/old-content/ redirect=404@/upgrade-message.html

        不像其他关键字，一条路由规则中只能有一个，redirect关键字可以有多个。

9. uri

        uri关键字是所有路由的必选项，它定义了匹配请求的URI资源。所有以指定uri值开始的请求URI都将会被匹配。一个好的做法是在最后加上一个/来匹配目录。

10. 关键字分隔符

        有些关键字可以包含多个值（abilities，extensions，methods），在这些情况下，值是通过使用"|"或","符号分隔开。当所有的值都需要满足的情况，使用","，当只需要指定的值的一个满足就可以时，使用"|"。具体来说，abilities应该使用","分隔，extensions和methods应该用"|"分隔。

四. 路由处理

        为了处理一个请求，GoAhead路由引擎检查每一个配置的路由，以确定请求的最佳的匹配路由。它通过按照配置文件中定义的顺序检查每条路由来做到这一点。每条路由都需要经过一系列步骤的测试。如果一个路由在某个步骤中不能匹配，该路由将被丢弃，并继续匹配下一条路由。     

路由匹配顺序：

1. Protocol

2. Method

3. Extension

4. URI

五. 总结

        本文主要介绍GoAhead的路由的工作机制，介绍了路由规则的配置文件的格式以及GoAhead路由引擎如何利用该文件，还介绍了一系列的路由规则的关键字及作用。最后介绍了路由匹配关键字的顺序。

实际使用中的案例：

1.  重定向请求

route uri=/oldfile.html redirect=/newfile.html

2. 重定向HTTP到HTTPS

route uri=/ protocol=http redirect=https

3. 通过摘要认证方式访问

route uri=/ auth=digest

4. 使能TRACE和OPTIONS方法

route uri=/partition/ methods=OPTIONS|TRACE handler=options

5. 定义新的文件扩展名和handler关键字

route uri=/ extensions=jst,asp handler=jst

6. 万能路由规则

route uri=/