Topcoat 路由层 `[layer]` 完全指南:路径匹配、嵌套顺序与路由上下文

原创2026-11-11 21:44:231,739 阅读
文章标签:后端Web框架前端

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。这条链路在源码中的走向是:

  1. 宏在无绝对路径时生成 impl ModuleLayer(crates/topcoat-router/grammar/src/layer.rs),其中 module_path() 返回 module_path!()。
  2. 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)。

由此得到四条必须记住的规则:

  1. 整段相等,不是字符串前缀。/admin 不会包裹 /administrator。构建期断言测试 layer_matching_part_of_a_segment_panics 正是这个例子(crates/topcoat-router/src/builder.rs)。
  2. 静态段不会匹配参数段或通配段。位于 /docs/admin 的层既不包裹 /docs/{something},也不包裹 /docs/{*path},尽管这两种路由实际服务的 URL 都落在 /docs/admin 之下。
  3. 参数段按名字匹配。/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)。
  4. 分组段计入路径。/(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 的路由上下文小节,完整的上下文叠加顺序是:

  1. 路由器构建器上的 with(...) 值;
  2. 包裹该路由的层,从最外层到最内层;
  3. 该路由的布局,同样从最外层到最内层;
  4. 路由/页面自身的 with(...);
  5. 请求处理过程中用 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):

  1. 生成一个与函数同名的单元结构体作为标记值,因此 timing 既可以直接写进 .layer(timing),也可以被 inventory 收集;
  2. 把原函数体改名为关联函数 handler,放进 impl <Marker>;同时补上 #[allow(clippy::unused_async)] 与未使用 cx 的豁免,这样即使层不需要上下文也不会报警告;
  3. 按路径形态生成 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 组合出更复杂的请求管线,都可以在这些规则内推导出可预测的行为。

登录后查看全文
topcoat