5: 路由

在 Phlo 中，路由将 空格分隔的路径 + HTTP 方法 映射到目标（通常是一个方法）。来自所有 .phlo 文件的路由被收集；路由器通过 app::route() 激活。

5.1: 基本表单

route [async|both] [GET|POST|PUT|DELETE|PATCH|QUERY] pad [pad2 ...] => target

路径是用空格编写的（在路由定义中没有 /）。
目标：直接调用或语句块。

示例：

route GET home => $this->main
method main => view($this->home)

QUERY (RFC 10008) 是一种安全的、幂等的读取方式，携带请求体，用于查找其参数无法干净地放入 URL 的情况。%payload 以与解码 POST（JSON、表单编码、多部分）相同的方式解码 QUERY 主体，而 HTTP() 则接受一个匹配的 QUERY: 参数，用于调用另一个 QUERY 端点。

route QUERY search => $this->search
method search => dx(%payload->filters)

5.2: 同步 / 异步 / 两者

关键字	行为
(省略)	同步仅（常规 HTTP）
`async`	异步仅（来自 Phlo 前端的请求）
`both`	同步和异步均允许

route both GET data => $this->loadData
route async POST items save => $this->saveItems

5.3: 变量

Phlo 解析每个路径段。以 $ 开头的段是变量，具有额外的功能：

4.3.1 必需的（传递给目标）

route GET user $id => $this->showUser($id)
method showUser($id) => view($this->profile)

4.3.2 可选存在使用 `?` → 布尔值

route GET search $full? => $this->search($full)

匹配 /search 和 /search/full。
当请求段 full 存在时，$full 为 true，否则为 false。（实现实际上检查请求段是否等于不带 ? 的 name。）

4.3.3 Rest（可变长度）与 `=*`

route GET file $path=* => $this->serveFile($path)

将所有剩余的段匹配为 $path 中的一个字符串。

4.3.4 带 `=` 的默认值

route GET page $slug=home => $this->page($slug)

没有段落 → $slug = 'home'。
有段落 → $slug = '<value>'。

4.3.5 长度要求使用 `.N`

route GET code $pin.6 => $this->enter($pin)

仅当 $pin 的长度恰好为 6 时匹配。

4.3.6 带有 `:a,b,c` 的值列表

route GET report $range:daily,weekly,monthly => $this->report($range)

段必须是列出的值之一。
当段缺失（为空）并且设置了默认值时，将应用默认值。
否则匹配失败。

您可以组合这些形式。示例：

具有必需 id 的枚举：

route GET export $fmt:csv,json $id => $this->export($fmt, $id)

带默认值的枚举：

route GET theme $name:light,dark=light => $this->theme($name)

5.4: 使用 `@` 进行有效负载检查

您使用单个 @ 和 逗号分隔 的列表来指定确切的主体键。路由器将此与 %payload 中的键进行 一对一 比较（确切的集合；按引擎提供的顺序）。

route POST user @name,email => $this->createUser

method createUser => dx(%payload->name, %payload->email)

Body keys 不作为方法参数绑定；您可以通过 %payload 读取它们。

5.5: 目标

本地方法

route GET profile show => $this->show
method show => view($this->profile)

外部类方法 (静态)

route GET api version $major => api::getVersion($major)

静态调用：必须使用括号，即使没有参数。
显式传递路径变量。

路由可能返回的内容

调度程序检查返回值的唯一目的：false 意味着“不是我的路由”，匹配将继续进行下一个候选项。所有其他返回值都会被丢弃。

教训。 假设“路由返回其响应主体”会产生 route GET hello => 'Hello'：路由匹配并提供一个空页面的 200 响应。路由仅通过 view()、apply()、output()、location() 或 %res API 生成输出。

false 合同也是一个工具：一个捕获所有的 route GET guide $slug 对于未知的 slug 返回 false，允许后续文件中的字面路由 (GET guide index.json) 仍然匹配相同的 URL。

原则：无重定向响应。 请求和响应是解耦的，因此路由可以将工作转发到另一个例程并返回其输出，在一个请求中回答，而不是重定向。对于 async 请求，直接返回 apply()/view() 和 path:（SPA 在原地交换，无需第二个请求）；对于 sync POST 仅重新显示页面，转发到该页面的例程，而不是调用 location()。location() 仍然是处理必须 规范化 URL 的同步请求的正确工具（POST-重定向-GET，或硬导航），当同步 view() 接收到不同的字符串 path: 时，引擎本身会执行此操作。目标是避免 不必要 的往返，而不是禁止重定向。

5.6: 激活路由器

路由仅在之后匹配：

app::route()

在 app.phlo（或其他中央控制器）中放置此调用，位置应在应用初始化之后，并在处理 404 的回退之前。

5.7: Recommended structure

Put routes at the top of each file.

Keep path and method name logically aligned:

route GET users list  => $this->listUsers
route POST users add  => $this->addUser

Always pass variables in the target.
Use both only when an endpoint deliberately needs to be both sync and async.
Use value lists :… instead of separate if branches for fixed variants.

Reference. Routing and request resources are documented per node in the Manual, generated from the resource files so it never drifts from the code.

最近更新于 2026年8月23日