有效模式
模式必须:- 非空;并且
- 以
/开头。
/:
* 或 ? 之类的字符不会产生通配符行为。除非模式以 / 结尾,否则整个模式都会被当作字面路径进行比较。
匹配规则
精确路径
不以/ 结尾的模式只匹配同一个路径:
末尾的斜杠是有意义的。
/api/items 和 /api/items/ 是两个不同的精确路径。
子树
以/ 结尾的模式会匹配所有以该模式开头的路径:
/api 及其子路径,请分别定义各自的模式。
根路径
/ 的处理方式比较特殊,因为不同类型的资源对它的使用方式各不相同:
大多数调用者使用
RootPathExact。由目录支撑的静态路由和代理路由都使用 RootPathSubtree,因此挂载在 / 上的静态目录或代理都可以服务或转发根路径之下的所有路径——这在代理需要接管整个应用、或某个静态目录需要提供通用内容时很有用。
在多个匹配模式之间进行选择
当多个模式匹配同一个路径时,Arupa 会选择最长的匹配模式,而不会合并所有匹配模式的规则或组列表。 例如,给定以下主机访问规则:/api/admin/users 同时匹配这两个模式,但 /api/admin/ 更长,因此胜出。对于该请求,只会评估 root 组规则。
当服务路由器为某个 HTTP 路由做选择时,无论该路由是通过静态传输提供打包文件,还是被动态处理,都会使用相同的最长匹配规则。
主机访问规则
Route.Allow 会在请求到达主机处理程序或服务处理程序之前,对请求的 URL 路径进行匹配。配置校验会应用与上述相同的模式规则。关于如何根据已认证用户来评估所选路由的组列表,请参阅访问控制。
查询字符串不参与路径匹配。例如,对 /api/items?limit=10 的请求会使用 /api/items 进行匹配。
服务的 HTTP 路由
服务在注册 HTTP 路由时使用相同的路径模式。路由器选出最长匹配的路径模式后,会再根据 HTTP 方法选择处理程序:- 显式声明的方法(例如
GET或POST)会在规范化之后按不区分大小写的方式进行匹配; - 空方法表示可处理任意方法;以及
- 对于同一路径,显式方法优先于空方法处理程序。
405 Method Not Allowed,并在 Allow 响应头中包含可用的方法。
路径相同且方法冲突的路由不能被不同的服务注册。一个没有方法限制的路由,会与同一路径下的所有方法发生冲突。
本节介绍的是路由存在之后如何进行路径匹配。关于路由是如何被声明并绑定到某个传输上的——包括那种无需运行服务代码即可提供打包文件的静态传输——请参阅路由与传输。
保留路径
在任何服务注册路由之前,内核会为自己保留一组固定的 HTTP 路径——登录相关的路径,以及整个管理 API:GET /api/user、GET /api/service 等)。以 / 结尾的路径则把这个模式作为子树保留,覆盖其下按资源划分的嵌套接口(/api/user/{name}、/api/service/config/{name} 等)——这个模式的具体含义请参阅子树。这些保留使用的是与服务相同的路由器,因此服务无法注册一个与这些模式完全相同的 HTTP 路由;这种尝试的失败方式,与注册一个已被其他服务占用的路径完全一样。只有由内核直接实现的路径才会以这种方式被保留——其他一切,包括像登录这样的核心服务所提供的页面,都和其他任何服务路由一样,需要争夺路径的所有权。
一个能力被保留与它是否被启用没有关系。内核会在启动时无条件地占用这些路径,与 [API] 表无关,因此即使某个能力当前被关闭,服务也永远不可能注册到会与它的接口冲突的路由;启用/禁用状态本身是如何被强制执行的,请参阅管理 API。
静态路由
绑定到静态传输的路由使用与其他 HTTP 路由相同的路径模式规则,只多一条:它究竟按精确路径匹配还是按子树匹配,取决于其来源(source)是单个文件还是一个目录。- 由目录来源支撑的路由使用子树匹配。内核会将其规范化为以
/结尾的模式,因此配置在/assets的路由会服务/assets/子树。 - 由单文件来源支撑的路由使用精确匹配,且不得以
/结尾。因此,位于/favicon.ico的路由只会服务该路径本身。