5: 路由

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

5.1: 基本表单

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

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

示例：

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

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。 （实现实际上检查请求段是否等于 名称，不包括 ?。）

4.3.3 可变长度 使用 =*

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 中的键进行 1对1 比较（确切的集合；按引擎提供的顺序）。

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

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

主体键 不 作为方法参数绑定；您通过 %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。

5.6: 激活路由器

路由仅在之后匹配：

app::route()

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

5.7: 推荐结构

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

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

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

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