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: 同步 / 异步 / 两者

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: 推荐结构

• 将 routes 放在每个文件的顶部。

• 保持路径和方法名称在逻辑上对齐：

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

• 始终在目标中传递变量。
• 仅在端点故意需要同时为同步和异步时使用 both。
• 对于固定变体，使用值列表 :… 而不是单独的 if 分支。