Skip to main content
Arupa 使用同一套路径模式实现来处理内核访问规则和服务路由注册。这是一种小型的路径模式语言,并不是通配符、glob 或正则表达式匹配器。

有效模式

模式必须:
  • 非空;并且
  • / 开头。
当您想匹配某个路径子树时,请使用末尾的 /
诸如 *? 之类的字符不会产生通配符行为。除非模式以 / 结尾,否则整个模式都会被当作字面路径进行比较。

匹配规则

精确路径

不以 / 结尾的模式只匹配同一个路径: 末尾的斜杠是有意义的。/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 方法选择处理程序:
  • 显式声明的方法(例如 GETPOST)会在规范化之后按不区分大小写的方式进行匹配;
  • 空方法表示可处理任意方法;以及
  • 对于同一路径,显式方法优先于空方法处理程序。
如果路径匹配但没有注册的方法与之匹配,Arupa 会返回 405 Method Not Allowed,并在 Allow 响应头中包含可用的方法。 路径相同且方法冲突的路由不能被不同的服务注册。一个没有方法限制的路由,会与同一路径下的所有方法发生冲突。 本节介绍的是路由存在之后如何进行路径匹配。关于路由是如何被声明并绑定到某个传输上的——包括那种无需运行服务代码即可提供打包文件的静态传输——请参阅路由与传输

保留路径

在任何服务注册路由之前,内核会为自己保留一组固定的 HTTP 路径——登录相关的路径,以及整个管理 API
不带末尾斜杠的路径只保留这个精确路径本身,对应每个能力的集合级接口(GET /api/userGET /api/service 等)。以 / 结尾的路径则把这个模式作为子树保留,覆盖其下按资源划分的嵌套接口(/api/user/{name}/api/service/config/{name} 等)——这个模式的具体含义请参阅子树。这些保留使用的是与服务相同的路由器,因此服务无法注册一个与这些模式完全相同的 HTTP 路由;这种尝试的失败方式,与注册一个已被其他服务占用的路径完全一样。只有由内核直接实现的路径才会以这种方式被保留——其他一切,包括像登录这样的核心服务所提供的页面,都和其他任何服务路由一样,需要争夺路径的所有权。 一个能力被保留与它是否被启用没有关系。内核会在启动时无条件地占用这些路径,与 [API] 表无关,因此即使某个能力当前被关闭,服务也永远不可能注册到会与它的接口冲突的路由;启用/禁用状态本身是如何被强制执行的,请参阅管理 API

静态路由

绑定到静态传输的路由使用与其他 HTTP 路由相同的路径模式规则,只多一条:它究竟按精确路径匹配还是按子树匹配,取决于其来源(source)是单个文件还是一个目录。
  • 由目录来源支撑的路由使用子树匹配。内核会将其规范化为以 / 结尾的模式,因此配置在 /assets 的路由会服务 /assets/ 子树。
  • 由单文件来源支撑的路由使用精确匹配,且不得以 / 结尾。因此,位于 /favicon.ico 的路由只会服务该路径本身。
静态路由和被动态处理的路由会被同一个服务路由器一并考虑,并争夺同一片路径空间。路由器会选择最长的匹配模式;当静态路由和被动态处理的路由匹配长度相同时,静态路由胜出。完整的冲突规则,包括一批路由注册是如何被应用的,请参阅路由与传输