Topcoat 路由层 `[layer]` 完全指南:路径匹配、嵌套顺序与路由上下文
Topcoat 路由层 #[layer] 完全指南:路径匹配、嵌套顺序与路由上下文
#<a href="https://link.gitcode.com/i/6ef9aa4d947cbb37d45c3017a88152b1" target="_blank">layer] 是 Topcoat 路由体系中最接近“中间件”的能力:它在请求真正进入处理函数之前包裹整条调用链,因此可以用来计时、记录日志、注入上下文、短路请求或改写响应。本文以 [docs/router/layer.md 为骨架,结合 crates/topcoat-router/src/layer.rs、crates/topcoat-router/grammar/src/layer.rs、crates/topcoat-router/src/builder.rs 等源码,把路径派生、构建期匹配、嵌套顺序和 with(...) 路由上下文四件事讲透,使你能写出可预测、可排错的路由层。
一、#[layer] 在 Topcoat 请求链路中的位置
在 Topcoat 中,三种“包裹”机制职责不同:
| 机制 | 包裹对象 | 典型用途 |
|---|---|---|
#[layout] |
只包裹页面(#[page]),负责视图外壳 |
HTML 骨架、导航、主题 |
#[layer] |
包裹匹配路径下的路由,包括 #[route] API 路由 |
计时、日志、上下文注入、鉴权短路 |
TowerLayer |
把 tower 生态中间件接入 Topcoat | 超时、限流等现成中间件 |
Layer trait 的定义非常克制,只有三个方法(crates/topcoat-router/src/layer.rs):
pub trait Layer: Send + Sync + 'static {
/// 该层包裹的 URL 路径前缀;返回 None 表示包裹每一个请求
fn path(&self) -> Option<&Path>;
/// 该层附加的路由上下文值,默认空
fn context(&self) -> ContextMap {
ContextMap::new()
}
/// 处理请求,调用 next 继续向下
fn handle<'a>(&'a self, cx: &'a Cx, body: Body, next: Next<'a>) -> LayerFuture<'a>;
}
从源码结构看,层链是一个“预计算的切片”:每个路由在构建期就确定了自己被哪些层包裹,请求期只需按顺序消费这个切片,不做任何路径匹配。这正是文档强调“前缀在构建期检查、请求 URL 不参与匹配”的底层原因。
二、三种路径写法与对应的注册方式
#[layer] 支持三种路径形态,它们决定生成哪一套 trait 实现。
2.1 无路径字符串:由模块路由派生
在 module_router!() 下使用不带参数的 #[layer],URL 前缀由所在模块决定。例如 src/app/api.rs 中的层包裹 /api 下的所有请求:
# use topcoat::{Result, context::Cx, router::{Body, Next, layer, response::Response}};
#[layer]
async fn api_log(cx: &Cx, body: Body, next: Next<'_>) -> Result<Response> {
let response = next.run(cx, body).await?;
println!("API response: {}", response.status());
Ok(response)
}
模块到 URL 的映射规则见 docs/router/module.md:app::api 对应 /api,模块名静态部分转 kebab-case。这条链路在源码中的走向是:
- 宏在无绝对路径时生成
impl ModuleLayer(crates/topcoat-router/grammar/src/layer.rs),其中module_path()返回module_path!()。 ModuleRouterBuilder::layer调用resolve_path把模块路径拼接成PathBuf,再用ResolvedLayer包装成普通Layer注册进内层构建器(crates/topcoat-router/src/module/router.rs、crates/topcoat-router/src/module/layer.rs)。
2.2 相对路径 ./:在模块路径下延伸
以 ./ 开头的字符串会拼接到模块路径之后。下面的层位于 src/app/api.rs,因此只包裹 /api/v1 之下:
# use topcoat::{Result, context::Cx, router::{Body, Next, layer, response::Response}};
#[layer("./v1")]
async fn v1_log(cx: &Cx, body: Body, next: Next<'_>) -> Result<Response> {
let response = next.run(cx, body).await?;
println!("v1 response: {}", response.status());
Ok(response)
}
解析逻辑在 crates/topcoat-router/grammar/src/common/handler_path.rs:以 ./ 判定为相对路径,去掉前导 . 后得到 /v1,交给模块路由器拼接。同一个文件里的测试明确了边界行为:裸 "." 会报错“a relative path must start with ./”,"../sibling" 会报错“cannot leave the module path”,即相对路径不能越出模块路径,需要跳出模块树时必须改用绝对路径。裸 ./ 则代表“模块路径加上尾部斜杠”的形式。
2.3 绝对路径:脱离模块树,必须单独注册
绝对路径(以 / 开头)与模块树解耦,但也因此不会被模块路由器自动收集,需要显式注册。文档示例:
use topcoat::{
Result,
context::Cx,
router::{Body, Next, layer, response::Response},
};
#[layer("/")]
async fn timing(cx: &Cx, body: Body, next: Next<'_>) -> Result<Response> {
let start = std::time::Instant::now();
let response = next.run(cx, body).await?;
println!("handled in {:?}", start.elapsed());
Ok(response)
}
在 module_router!() 场景下,注册形如 .layer(timing)(ModuleRouterBuilder::layer 也接受普通 Layer);文档 docs/router/module.md 建议用 discover() 一次性收集所有显式路径处理器,或像 #<a href="https://link.gitcode.com/i/e8e7d6ceb0f2629e6e8bb6ae816907fb" target="_blank">page("/legacy")] 那样按名字传入。宏在这种情形下生成的是 impl Layer,path() 直接返回 Path::new("/")([crates/topcoat-router/grammar/src/layer.rs)。
三种形态速查:
| 写法 | 生成实现 | URL 前缀来源 | 注册方式 |
|---|---|---|---|
#[layer] |
ModuleLayer |
所在模块路径 | module_router!() 自动收集 |
#[layer("./v1")] |
ModuleLayer |
模块路径 + /v1 |
module_router!() 自动收集 |
#[layer("/admin")] |
Layer |
字面量的绝对路径 | 显式 .layer(...) 或 .discover() |
三、匹配规则:比较注册路径,而不是请求 URL
这是 #[layer] 最容易踩坑的地方。文档给出的判定标准是:层是否包裹某个 handler,取决于该 handler 的注册路径;路由构建时把层的路径与 handler 的路径逐段比较,请求 URL 完全不参与。
源码实现是 Path::starts_with(crates/topcoat-router/src/path.rs):按 PathSegment 相等比较前 N 段,其中参数段必须同名,分组段参与比较。选择函数 layers_for_path 只对满足该前缀的层保留(crates/topcoat-router/src/layer.rs)。
由此得到四条必须记住的规则:
- 整段相等,不是字符串前缀。
/admin不会包裹/administrator。构建期断言测试layer_matching_part_of_a_segment_panics正是这个例子(crates/topcoat-router/src/builder.rs)。 - 静态段不会匹配参数段或通配段。位于
/docs/admin的层既不包裹/docs/{something},也不包裹/docs/{*path},尽管这两种路由实际服务的 URL 都落在/docs/admin之下。 - 参数段按名字匹配。
/users/{id}不会包裹/users/{user_id}/posts;测试for_path_distinguishes_param_names与layer_with_another_param_name_panics都验证了这一点(crates/topcoat-router/src/layer.rs、crates/topcoat-router/src/builder.rs)。 - 分组段计入路径。
/(auth)/dashboard的页面实际服务在/dashboard,但位于/dashboard的层不会包裹它;反过来/(auth)的层会包裹/(auth)/dashboard。分组段在 URL 中不占位,但在路由逻辑路径中是真实的一段(crates/topcoat-router/src/layer.rs)。
构建期的“误配即 panic”保护:如果某个带路径的层没有匹配到任何路由,build() 会 panic,错误信息是 layer with path \/admin` did not match any route, this is likely a mistake。唯一豁免是根路径 /`,因为它前缀匹配所有路由(crates/topcoat-router/src/builder.rs)。这条检查让“路径拼错”“漏了分组段”“参数名写错”三类问题在启动时立刻暴露,而不是在线上静默失效。
四、404 与 405:带路径的层不参与,无路径的层全量包裹
文档明确区分了两类层的行为:
#[layer]声明的层必有路径,因此 404(路径没匹配到任何 endpoint)与 405(路径匹配但方法不支持)不会触发它。path()返回None的层包裹每一个请求,包括未命中;未命中的错误会以next.run返回的Err形式传给它。
源码用 Terminal 枚举表达了链的终点(crates/topcoat-router/src/layer.rs):
pub(crate) enum Terminal<'a> {
Route(&'a dyn Route), // 命中的路由
MethodNotAllowed(&'a Endpoint), // 路径命中、方法不命中
NotFound, // 路径未命中
}
Next::run 在层消费完后落到这三种终点:命中路由则调用 route.handle;405 生成带 Allow 头的错误;404 生成未找到错误(crates/topcoat-router/src/layer.rs)。请求分发端在未命中路径时,使用 always_layers 构建 Terminal::NotFound(crates/topcoat-router/src/router.rs),always_layers 正是所有无路径层按“后注册先执行”整理出来的切片(crates/topcoat-router/src/builder.rs)。
要创建无路径层,有两种方式:
use std::borrow::Cow;
use topcoat::{
context::Cx,
router::{Body, Layer, LayerFuture, Next, Path},
};
struct Timing;
impl Layer for Timing {
fn path(&self) -> Option<&Path> {
None // 包裹所有请求,包括 404 / 405
}
fn handle<'a>(&'a self, cx: &'a Cx, body: Body, next: Next<'a>) -> LayerFuture<'a> {
Box::pin(async move {
let start = std::time::Instant::now();
let response = next.run(cx, body).await?;
println!("handled in {:?}", start.elapsed());
Ok(response)
})
}
}
或者更轻量地用 LayerFn::new(None::<&Path>, handler) 构造函数层,再通过 RouterBuilder::layer 注册(crates/topcoat-router/src/layer.rs)。注意 LayerFn::new 对路径字符串做了解析校验:传入非法路由路径会 panic,且在调用处报告位置(#[track_caller])。
五、嵌套顺序:从最不具体到最具体
当多个层命中同一个路由时,嵌套规则与布局一致:路径最不具体的在最外层(先执行),最具体的在最内层。补充规则有两条:
- 同一路径上的多个层按注册顺序决定:最后注册的在最外层。
- 通过
discover收集的层必须路径唯一,因为链接期收集顺序不稳定,无法定义同路径的嵌套顺序(crates/topcoat-router/src/builder.rs),冲突时 panic:multiple discovered layers registered for the same path ...。
实现细节解释了这两条规则如何同时成立(crates/topcoat-router/src/layer.rs):
let mut matching: Vec<_> = layers
.iter()
.filter(|(layer, _)| layer.path().is_none_or(|prefix| path.starts_with(prefix)))
.rev()
.collect();
matching.sort_by_key(|(layer, _)| layer.path().map_or(0, |path| path.len() + 1));
先 rev() 翻转注册顺序,再做稳定排序:因此路径更短(更不具体)的层排在前面;路径长度相同的层保留翻转后的顺序,即后注册者在前。+1 的偏移是给根路径的特殊处理:/ 的内部字符串长度为 0,加 1 之后才能让无路径层(键为 0)严格位于根层之外。文档中“无路径层在所有带路径层之外”的结论,就由这个偏移保证。
六、处理函数签名与返回值
#[layer] 修饰的函数必须满足:
- 是
async fn; - 第一个参数是
cx: &Cx,即使不用也必须写; - 第二、三个参数是
body: Body与next: Next<'_>; - 返回
Result<T>,其中T: AsyncIntoResponse;所有IntoResponse类型都满足该约束。
调用 next.run(cx, body) 继续执行剩余层和处理函数;直接返回即可短路,不调用 next 时后续层与 handler 都不会运行。宏在展开时会把返回值交给 AsyncIntoResponse::async_into_response,所以返回 Response、&'static str 或自定义 IntoResponse 都可以(crates/topcoat-router/grammar/src/layer.rs)。
短路写法在测试中有明确验证:short_circuit 层直接返回 "short",路由本应返回 "route",最终响应体是 short(crates/topcoat-router/src/layer.rs)。
给错误响应加响应头要特殊处理。错误响应是在错误离开层链之后才构建的,所以层里直接改 response.headers_mut() 不会影响 404/405 响应。此时应使用 response_headers(cx) 这个“待追加响应头”槽位(crates/topcoat-router/src/response/headers.rs);它会在最终响应生成后统一 apply(crates/topcoat-router/src/router.rs)。
七、路由上下文:用 with(...) 给整棵子树设默认值
这是 #[layer] 相对 #[layout] 的关键优势:布局只作用于页面,而层会包裹路由,因此“给某个路径下所有 handler 一组相同的值”应该用层。
语法上,with(...) 可以跟在路径后面,也可以单独使用;多个条目用逗号分隔:
#[layer(with(Section("api")))]
#[layer("/api", with(Section("api")))]
值的生命周期和作用范围由构建期决定:这些值在路由器构建时初始化一次,并加入该层包裹的每一个 handler 的上下文,且先于任何层、布局或处理函数运行。内层组件可以覆盖同名类型的值。
结合 docs/context.md 的路由上下文小节,完整的上下文叠加顺序是:
- 路由器构建器上的
with(...)值; - 包裹该路由的层,从最外层到最内层;
- 该路由的布局,同样从最外层到最内层;
- 路由/页面自身的
with(...); - 请求处理过程中用
cx.with(...)追加的值。
每一层都会遮蔽(shadow)前面同类型的值,而旧值仍可通过 iter_context 沿链回读。这也是“外层布局收集面包屑”这类模式能成立的原因。
两条限制必须记住:
- 无路径层只给命中的 handler 加值,不会加到 404/405 响应;而“未命中任何路由的请求没有任何路由上下文,即使在无路径层内部也是如此”。
- 路由上下文在构建期生成,依赖请求的值(例如当前登录用户名)应存成函数并通过
BoxCxFn在渲染时调用,或交给#[memoize]缓存,而不是塞进with(...)。
在上下文注入场景里,层通过给 next.run 传子上下文来生效。仓库示例 examples/context/src/main.rs 展示了最小完整用法:路由器注入 Greeting("Hi"),formal 模块的层把它换成 Greeting("Good day"):
#[layer]
async fn layer(cx: &Cx, body: Body, next: Next<'_>) -> Result<Response> {
let cx = cx.with(Greeting("Good day"));
next.run(&cx, body).await
}
demos/admin/src/app.rs 与 examples/l10n/src/app/locale.rs 是同一种模式的生产级变体:前者为每个请求(包括 shard 更新)确定语言,后者直接从路径参数读取 locale,并对没有消息资源的语言返回 404。
八、若干可直接复用的实战模式
计时 / 日志(包裹后观测):先 await 内层,再读取 response.status() 或耗时。文档中的 timing 与 api_log 都是这个形态。
注入共享请求头:仓库宏测试里 api_header 在内层响应上插入 x-api,version_header 通过 #<a href="https://link.gitcode.com/i/114d398abfb80d3bc8a1cb23cfa49836" target="_blank">layer("./v1")] 只在 /api/v1 下插入 x-api-version([crates/topcoat-router/macro/tests/module_router.rs)。这就是“同一路径前缀下分层加头”的标准写法。
鉴权短路:不调用 next.run,直接返回错误响应,后续层与 handler 全部跳过。
改写请求路径:如果需要在挂载点处剥掉前缀,用内置的 StripPrefixLayer,它本身就是带路径的层(crates/topcoat-router/src/layer/strip_prefix.rs)。StripPrefixLayer::new("/res") 让 /res/logo.svg?version=2 以 /logo.svg?version=2 到达 handler;at(...) 可以把“路由作用域”与“剥离模式”分开,例如 StripPrefixLayer::new("/res").at("/(assets)/res") 只对分组内的路由生效。需要强调的是:路由匹配发生在本层之前,所以只有内层与 handler 看到改写后的 URI,路径参数值、响应头和生成的 URL 均不变。
接入 tower 中间件:用 TowerLayer。它默认覆盖所有请求(包括未命中),用 .at("/api") 可收窄到匹配路径下的 handler(docs/router/tower.md)。
九、宏展开:为什么“路径错误能在编译期/构建期暴露”
理解展开结果有助于排错。#<a href="https://link.gitcode.com/i/4fe33faa13a034b2be4b6f4e639759a7" target="_blank">layer] 会把原函数改造成三部分([crates/topcoat-router/grammar/src/layer.rs):
- 生成一个与函数同名的单元结构体作为标记值,因此
timing既可以直接写进.layer(timing),也可以被inventory收集; - 把原函数体改名为关联函数
handler,放进impl <Marker>;同时补上#[allow(clippy::unused_async)]与未使用cx的豁免,这样即使层不需要上下文也不会报警告; - 按路径形态生成
impl Layer(绝对路径)或impl ModuleLayer(模块派生 / 相对路径),并在context()中逐条插入with(...)的值。
启用 discover feature 时,还会追加 inventory::submit! 把标记注册为 &'static dyn Layer 或 &'static dyn ModuleLayer。由于类型不同,显式路径层与模块派生层分别在 discover_layers 与模块路由器的收集流程中被拉取,这解释了三件事:为什么绝对路径层“需要单独注册”、为什么模块派生层“自动生效”、以及为什么两者重复路径都会在构建期 panic。
十、排错清单
| 现象 | 根因 | 处理 |
|---|---|---|
构建时 panic:layer with path ... did not match any route |
层路径与任何注册路径都不是整段前缀 | 检查是否漏了分组段、参数名是否一致;若确实无路由命中,改为无路径层 |
| 层对 404/405 不生效 | #[layer] 声明的层带路径,不参与未命中 |
改用 path() 返回 None 的 Layer / LayerFn |
层给 /[group] 下的页面注入值却没生效 |
分组段计入逻辑路径 | 层的路径也要写全分组段 |
| 参数路由下的层不生效 | 参数按名字匹配 | 层与 handler 使用同一参数名 |
| 同路径多层顺序不符预期 | 后注册者在最外层 | 调整 .layer(a).layer(b) 的书写顺序,或合并为一个层 |
| 发现式注册报重复路径 | 链接期顺序不稳定 | 同路径层改为显式注册 |
| 错误响应缺少自定义头 | 错误响应在层链之后构建 | 使用 response_headers(cx) |
小结
#[layer] 的设计把不确定性尽量前移:路径匹配在构建期完成,误配直接 panic,排序由“路径长度 + 稳定排序”确定,请求期只是一次切片遍历。掌握三条主线即可稳定使用它——路径按注册路径逐段比较且分组计入、参数同名才算匹配;带路径层不覆盖 404/405,无路径层全量包裹;上下文按最外层到最内层叠加并按类型遮蔽。在此基础上,无论是计时日志、请求上下文注入,还是用 StripPrefixLayer 与 TowerLayer 组合出更复杂的请求管线,都可以在这些规则内推导出可预测的行为。