> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arupa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 路由

> 了解 Arupa 的共享路径模式和路由选择规则。

Arupa 使用单一的路径模式实现来管理内核访问规则和插件资源注册。
这是一个小型路径模式语言。它不是通配符、glob 或正则表达式匹配器。

## 有效模式

模式必须：

* 非空；并且
* 以 `/` 开头。
  当您想要匹配路径子树时，请使用末尾的 `/`：

```text theme={null}
有效：/api/items
有效：/api/
无效：/api/*
无效：api/items
```

诸如 `*` 或 `?` 之类的字符不会产生通配符行为。
除非模式以 `/` 结尾，否则整个模式将被视为字面路径进行比较。

## 匹配规则

### 精确路径

不以 `/` 结尾的模式仅匹配相同的路径：

| 模式           | 匹配           | 不匹配                           |
| ------------ | ------------ | ----------------------------- |
| `/api/items` | `/api/items` | `/api/items/`, `/api/items/1` |
| `/health`    | `/health`    | `/healthz`                    |

末尾的斜杠很重要。 `/api/items` 和 `/api/items/` 是不同的确切路径。

### 子树

以 `/` 结尾的模式匹配以该模式开头的路径：

```text theme={null}
模式：/api/
匹配：/api/
/api/items
/api/items/1
不匹配：/api
```

不带尾部斜杠的父路径不属于子树。
如果您需要同时匹配 `/api` 及其子路径，请定义单独的模式。

### 根路径

`/` 的处理方式比较特殊，因为不同的资源类型对它的使用方式不同：

| 调用者           | 根路径行为        |
| ------------- | ------------ |
| `Route.Allow` | `/` 仅匹配 `/`  |
| 插件 HTTP 路由    | `/` 仅匹配 `/`  |
| 静态目录挂载        | `/` 匹配所有绝对路径 |

前两个调用者使用 `RootPathExact`。
静态挂载使用`RootPathSubtree`，
因此挂载在 `/` 的静态目录可以服务于根目录下的路径。
根目录下的所有路径。

## 选择匹配模式

当多个模式匹配一个路径时，Arupa 会选择最长的匹配模式。
它不会合并所有匹配模式的规则或组列表。

例如，给定以下主机访问规则：

```toml theme={null}
[Route.Allow]
"/api/" = ["staff"]
"/api/admin/" = ["root"]
```

`/api/admin/users` 匹配这两个模式，但 `/api/admin/` 胜出，因为它更长。
对于该请求，仅评估 `root` 组规则。
当插件路由器选择 HTTP 路由或静态挂载时，也会使用相同的最长模式规则。

## 主机访问规则

`Route.Allow` 在请求到达主机处理程序或插件处理程序之前，匹配请求的 URL 路径。
配置验证应用与上述相同的模式规则。请参阅[访问控制](./config-access)

了解如何根据已认证用户评估所选路由的组列表。

查询字符串不参与路径匹配。例如，对`/api/items?limit=10` 的请求将使用 `/api/items` 进行匹配。

## 插件 HTTP 路由

插件在注册 HTTP 路由时使用相同的路径模式。

路由器选择最长匹配路径模式后，会根据 HTTP 方法选择处理程序：

方法：

* 显式声明的方法（例如 `GET` 或 `POST`）在规范化后进行匹配，不区分大小写；
* 空方法可以处理任何方法；
* 对于所选路径，显式方法优先于空方法处理程序。

如果路径匹配但没有注册的方法匹配，Arupa 将返回 `405 Method Not Allowed`，
并在 `Allow` 响应头中包含可用方法。

路径相同但方法冲突的路由不能被不同的插件注册。

没有方法的路由会与同一路径下的所有方法冲突。

## 静态挂载

静态目录挂载使用子树匹配。内核会将目录挂载规范化为以 `/` 结尾的模式，因此配置在 `/assets` 的挂载点服务于 `/assets/` 子树。

静态文件挂载使用精确匹配，且不能以 `/` 结尾。因此，静态文件挂载在 `/favicon.ico` 仅服务于该路径。

插件路由器会同时考虑静态挂载和插件 HTTP 路由。

路由器会选择最长的匹配模式；当静态挂载和 HTTP 路由的匹配长度相同时，选择静态挂载。