罗罗编程学习记录
本页内容 展开查看

04.4.5.1 路由与请求守卫

所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.4 Rust / 04.4.5 Rocket

04.4.5.1-001 Rocket 0.5 的路由属性宏有哪些?

一句话结论

Rocket 提供按 HTTP 方法划分的路由宏 #[get]、#[post]、#[put]、#[patch]、#[delete]、#[head]、#[options],以及通用的 #[route],用于把普通函数声明为路由 handler。

概念解释

路由宏是 Rocket 把函数挂载到路由器的入口:宏参数给出 URI 模板,函数签名声明参数绑定、请求守卫与数据守卫。方法宏是 #[route(method = ...)] 的便捷形式,URI 写在宏参数里。Rocket 在启动期收集所有带路由宏的函数,注册到路由表;handler 的返回类型需要实现 Responder。

原理流程

  1. 在函数上标注方法宏与 URI 模板。
  2. 函数参数按路由声明、守卫、data 三类绑定。
  3. Rocket 启动时扫描路由,校验 URI 与参数类型。
  4. 请求匹配路由后执行对应 handler。
  5. 返回值经 Responder 转换为响应。

代码或图示

#[rocket::get("/users/<id>")]
fn get_user(id: u64) -> String {
    format!("user {id}")
}

#[rocket::post("/users", data = "<user>")]
fn create_user(user: rocket::serde::json::Json<User>) { /* ... */ }

常见误区

  • 以为路由注册需要手写路由表:Rocket 通过属性宏与 /routes![..] 宏收集,无需手工插入表项。
  • 混淆路由宏与 catcher 宏:#[catch(..)] 处理错误状态,不是正常路由。

追问

  • 通用 #[route] 什么时候用?答:方法动态化或需要同时指定 rank、format、data 等多项配置时使用;单一方法场景用方法宏更直观。
  • 路由宏支持哪些 HTTP 方法?答:get、post、put、patch、delete、head、options;其他自定义方法通过 #[route(method = ..)] 声明,具体取值以 Rocket 当前版本文档为准。

04.4.5.1-002 方法宏与 #[route] 是什么关系?

一句话结论

方法宏是 #[route] 的语法糖:#[get("/x")] 等价于 #[route(method = "GET", path = "/x")];#[route] 额外暴露 rank、format、data 等配置项。

概念解释

#[route] 是底层声明形式,参数覆盖方法、路径、排序优先级、媒体类型与数据参数。方法宏把常用方法固化为独立宏,减少重复书写。两者最终都生成路由注册所需的元数据;在需要手动调整优先级或约束 Content-Type 时,切换到 #[route] 即可,handler 函数本身不变。

原理流程

  1. 方法宏展开为带 method 的 route 声明。
  2. route 属性解析各配置项并写入路由元数据。
  3. 启动期校验配置组合是否合法。
  4. 路由表按 rank 与 URI 组织匹配顺序。
  5. 请求匹配时读取方法、路径、格式约束。

代码或图示

// 便捷形式
#[rocket::get("/items/<id>")]
fn one(id: u64) { /* ... */ }

// 通用形式(等价写法,额外配置以当前版本为准)
#[rocket::route(method = "GET", path = "/items/<id>", rank = 1)]
fn one_explicit(id: u64) { /* ... */ }

常见误区

  • 以为方法宏不能再配 rank:方法宏同样支持在参数中追加配置项,具体语法以版本文档为准。
  • 在 #[route] 里写错方法大小写导致不匹配:方法名按 HTTP 规范大写。

追问

  • format 配置项作用是什么?答:约束请求或响应的媒体类型(如 json),不匹配的请求不会路由到该 handler;详见 04.4.5.1-006。
  • 一个函数能否挂多个路由宏?答:通常每个 handler 一个路由声明;需要多路径时定义多个 handler 复用同一函数体,具体限制以版本文档为准。

04.4.5.1-003 路由 URI 中静态段与动态段如何区分?

一句话结论

URI 中普通字面段是静态段,尖括号 <name> 是动态段;动态段按位置映射到同名 handler 参数,解析由 FromParam 完成。

概念解释

路由模板由斜杠分隔的段组成:静态段必须与请求路径逐字符匹配,动态段匹配任意单段值并捕获为参数。动态段可标注类型 <id: u64>,未标注时按参数类型解析。多段捕获使用 <path..> 语法。静态段在匹配优先级上高于动态段,具体规则见 rank 与匹配顺序相关题目。

原理流程

  1. 启动期解析 URI 模板,拆分静态段与动态段。
  2. 请求路径逐段比对:静态段要求字面相等。
  3. 动态段捕获当前段字符串。
  4. 按参数类型通过 FromParam 解析,失败则不匹配。
  5. 解析成功后把值交给 handler 参数。

代码或图示

// /users/admin 命中静态段;/users/123 命中动态段
#[rocket::get("/users/<name>")]
fn by_name(name: &str) -> String { format!("{name}") }

#[rocket::get("/users/<id: u64>")]
fn by_id(id: u64) -> String { format!("{id}") }

常见误区

  • 动态段写成 :id 或 {id}:Rocket 0.5 使用尖括号 <id> 语法。
  • 一个动态段匹配斜杠:默认单段,含斜杠的剩余路径要用 <path..>。

追问

  • 段内可以混排静态与动态吗?答:段级别以静态或动态为主;段内拼接形式(如 file-<id>)的支持情况以当前版本文档为准,不确定时拆成独立段。
  • 捕获值是否自动解码?答:Rocket 0.5 对入参自动百分比解码,&str 参数拿到解码后的值。

04.4.5.1-004 #[route(...)] 支持哪些配置项?

一句话结论

常见配置项包括 method、path、rank、format、data;分别控制 HTTP 方法、URI 模板、匹配优先级、媒体类型约束与 body 参数名,具体可用项以 docs.rs 当前版本为准。

概念解释

路由元数据决定一条路由如何参与匹配。method 限定请求方法,path 给出模板,rank 调整匹配顺序,format 约束请求/响应媒体类型,data 声明 body 对应的 handler 参数名。配置项在启动期参与校验;组合冲突(如方法与路径无法匹配)会在启动日志或编译期暴露。

原理流程

  1. 解析 route 属性各字段。
  2. method 与 format 进入匹配条件。
  3. path 拆分为静态/动态段。
  4. rank 写入路由排序键。
  5. data 关联 handler 的 body 参数类型。

代码或图示

#[rocket::route(
    method = "POST",
    path = "/items",
    rank = 2,
    format = "json",
    data = "<item>"
)]
fn create(item: rocket::serde::json::Json<Item>) { /* ... */ }

常见误区

  • 把 data 写成路径的一部分:body 参数在属性 data 中声明,不出现在 URI 里。
  • 配置项取值凭记忆写死:媒体类型别名与字段名以当前版本文档为准。

追问

  • rank 不写时取值是什么?答:使用默认 rank,由 URI 模板自动计算;规则见 04.4.5.1-014。
  • format 同时约束请求与响应吗?答:取决于配置方向与类型实现;Json 守卫接收与响应都带 JSON 类型,具体语义以版本文档为准。

04.4.5.1-005 handler 参数如何与路由参数绑定?

一句话结论

handler 参数分三类:路由声明参数(路径/查询段同名绑定)、请求守卫(FromRequest,未在路由属性声明)、数据守卫(data 声明的 body 参数,实现 FromData)。

概念解释

Rocket 按参数类型与路由声明推断角色:在 URI 或 data 中声明的名字对应路由/数据参数;其余参数若实现 FromRequest 则作为守卫。参数名必须与模板占位符一致才能绑定。绑定失败时守卫走 Outcome 流程,data 解析失败走 FromData 流程;handler 只在全部参数成功构造后执行。

原理流程

  1. 启动期检查参数名与路由占位符是否对应。
  2. 请求到达后先构造请求守卫。
  3. 守卫通过后解析路径与查询参数。
  4. 最后读取并解析 body 数据守卫。
  5. 全部成功才调用 handler。

代码或图示

#[rocket::get("/users/<id>/posts?<page>")]
fn list(
    id: u64,                  // 路由路径参数
    page: u32,                // 路由查询参数
    auth: AuthGuard,           // 请求守卫
    rocket::State(state): rocket::State<AppState>, // 守卫式状态提取
) -> String { format!("{id} {page}") }

常见误区

  • 守卫参数名与占位符同名导致角色误判:命名上区分守卫类型与参数名。
  • body 参数在路径模板里找不到对应声明:必须用 data = "<name>"。

追问

  • 参数顺序有硬性要求吗?答:守卫在 body 参数之前参与构造;Rocket 对参数顺序与类型的校验规则以版本文档为准,data 参数通常位于参数列表后部。
  • 找不到同名占位符的普通参数怎么处理?答:若类型实现 FromRequest 作为守卫;既不是守卫也未声明的参数会在启动期报错。

04.4.5.1-006 format = "json" 起什么作用,与 Content-Type 有什么关系?

一句话结论

format 约束路由匹配的媒体类型:声明后只有请求 Content-Type(或按配置的响应类型)匹配该格式的请求才路由到 handler;json 是常用别名,对应 application/json。

概念解释

同一 URI 可能按不同媒体类型提供不同处理,format 在路由匹配层增加类型条件。Json<T> 守卫自身也会在接收时解析 JSON;显式 format = "json" 让不匹配类型的请求直接落到其他路由或 catcher。格式别名与完整 MIME 的映射以 Rocket 当前版本为准。响应侧 Json<T> 会自动设置 application/json。

原理流程

  1. 路由声明 format = "json"。
  2. 请求到达,读取 Content-Type 与路由格式约束比对。
  3. 匹配通过 → 进入该 handler。
  4. 不匹配 → 尝试其他路由或走 404。
  5. 响应由 Responder 写入对应媒体类型头。

代码或图示

#[rocket::post("/users", format = "json", data = "<user>")]
fn create(user: rocket::serde::json::Json<User>) { /* ... */ }

常见误区

  • 以为 format 只影响响应头:它首先是匹配条件,不满足的请求不会进入 handler。
  • 不声明格式又依赖 JSON 解析:Content-Type 不符时可能落到其他 handler 或解析失败。

追问

  • 不写 format 会怎样?答:路由不约束媒体类型,由数据守卫自身解析;Json 守卫解析失败会返回对应错误。
  • 支持哪些格式别名?答:常见有 json、msgpack 等;完整别名表以 Rocket 当前版本 feature 与文档为准。

04.4.5.1-007 同一 URI 不同方法如何注册?

一句话结论

为同一 URI 定义多个 handler,分别标注不同方法宏;Rocket 按方法分发到对应 handler,方法不匹配时进入 405 处理流程(具体响应行为以版本文档为准)。

概念解释

路由匹配同时考虑方法、路径、格式与 rank。同一资源的列表与创建通常是同一路径的 GET 与 POST。两个 handler 共用路径模板是正常做法;方法不同不会构成路由冲突。若路径与方法都相同,启动期会报告重复路由。

原理流程

  1. 为资源路径分别写 GET/POST 等 handler。
  2. 各 handler 标注对应方法宏与同一路径模板。
  3. 启动期校验无同方法同路径重复。
  4. 请求按方法分发到匹配 handler。
  5. 方法无对应路由时走错误处理。

代码或图示

#[rocket::get("/items")]
fn list() -> String { "list".into() }

#[rocket::post("/items", data = "<item>")]
fn create(item: rocket::serde::json::Json<Item>) { /* ... */ }

常见误区

  • 用一个 handler 内部判断 req.method() 分发:违背类型路由约定,守卫与解析也无法按方法复用。
  • 同方法同路径注册两次:启动期报重复路由错误。

追问

  • 方法不匹配返回什么状态码?答:HTTP 语义为 405;Rocket 对未匹配方法的默认响应与 catcher 关联方式以当前版本为准。
  • HEAD 请求如何处理?答:可单独注册 #[head] 路由;默认行为与 GET 的关系以版本文档为准。

04.4.5.1-008 路由返回类型与 Responder trait 是什么关系?

一句话结论

handler 返回值必须实现 rocket::response::Responder;标准库字符串、Json<T>、Form、状态元组等已有内置实现,自定义响应类型需手写 Responder。

概念解释

Responder 是 Rocket 的响应抽象边界,对应 axum 的 IntoResponse:把返回值转换为 Response,设置状态码、headers 与 body。内置实现覆盖常用类型;自定义响应(错误体、分页结构)实现该 trait 后即可直接作为 handler 返回。Rocket 0.5 的 responder 实现同样需要注意 async trait 标注。

原理流程

  1. handler 返回指定类型。
  2. Rocket 调用 Responder::respond_to 生成响应。
  3. 内置实现写入状态码、媒体类型与 body。
  4. 自定义类型在 trait 实现内组装响应。
  5. 响应进入发送流程。

代码或图示

#[rocket::get("/hello")]
fn hello() -> &'static str { "hello" }

// 自定义响应类型:impl Responder for MyResponse { ... }
// trait 方法签名与生命周期以 Rocket 当前版本文档为准

常见误区

  • 返回未实现 Responder 的裸结构体:编译期报 trait 未实现。
  • 在 responder 里做重 IO:响应层应保持轻量,重逻辑放在 handler 或 service 层。

追问

  • 如何返回自定义状态码?答:使用 (Status, T) 形式的组合 responder,T 实现 Responder;具体元组支持以版本文档为准。
  • Json<T> 响应有什么内置行为?答:自动序列化 T: Serialize 并设置 application/json,错误时由序列化失败处理。

04.4.5.1-009 Rocket 0.5 的异步 handler 怎么写?

一句话结论

Rocket 0.5 基于异步运行时,需要 await 的 handler 声明为 async fn;实现异步 trait(如 FromRequest、FromData)时必须加 #[rocket::async_trait]。

概念解释

0.4 时代 Rocket 以同步模型为主,0.5 切换到异步:handler 可以直接 .await 数据库查询、HTTP 调用等异步操作。异步 trait 方法因 Rust 原生 async trait 限制,需要通过 rocket::async_trait 宏标注。普通 async fn handler 不需要额外宏;派生 trait 实现时才需要 async_trait。

原理流程

  1. handler 声明为 async fn。
  2. 内部 .await 异步依赖。
  3. 实现 FromRequest/FromData 时在 impl 上加 #[rocket::async_trait]。
  4. Rocket 运行时调度 handler 任务。
  5. 返回值经 responder 转换。

代码或图示

#[rocket::get("/users/<id>")]
async fn profile(id: u64) -> String {
    let user = repo::find(id).await; // 异步查询
    format!("{user:?}")
}

常见误区

  • 异步 trait 实现漏加 async_trait:编译报错,签名与返回类型不匹配。
  • 在 async handler 里调用阻塞同步 IO:会占用运行时工作线程,应迁移到阻塞线程池或使用异步客户端。

追问

  • Rocket 0.5 底层用哪个运行时?答:Rocket 内置 Tokio 运行时;测试与自定义任务的运行时集成方式以当前版本文档为准。
  • 同步 handler 还支持吗?答:不需要 await 的普通函数 handler 仍可使用;是否为 async 取决于内部是否有异步操作。

04.4.5.1-010 路由宏在编译期与启动期分别校验什么?

一句话结论

编译期检查类型约束(参数/返回类型 trait 实现、async trait 标注);启动期校验路由 URI 与参数绑定、格式冲突、托管状态与 Sentinel 条件,不满足时中止启动。

概念解释

Rocket 把校验分两层:Rust 编译器负责类型安全(FromParam/FromRequest/FromData/Responder 约束);Rocket 启动期负责路由元数据一致性(占位符与参数名对应、重复路由、缺失托管状态)。Sentinel 机制让依赖特定状态或 catcher 的类型在条件不满足时中止启动,避免运行期才暴露错误。

原理流程

  1. 编译期:trait 约束、生命周期、async_trait 标注由编译器检查。
  2. 启动期:扫描 /routes![..] 收集路由元数据。
  3. 校验占位符与参数、格式与方法组合。
  4. Sentinel 检查托管状态、catcher 等前置条件。
  5. 校验失败打印诊断并中止,不进入服务监听。

代码或图示

let rocket = rocket::build()
    .mount("/", rocket::routes![get_user, create_user])
    .register("/", rocket::catchers![not_found]);

常见误区

  • 以为所有问题都在编译期发现:路由名绑定、状态缺失属于启动期校验。
  • 跳过启动日志直接上线:重复路由或缺失状态的诊断信息被忽略。

追问

  • 启动期校验失败进程会退出吗?答:Sentinel 与路由冲突检查不满足时中止 launch;具体退出行为以当前版本为准。
  • 编译期最常见的报错是什么?答:返回类型未实现 Responder,或守卫/数据类型未实现对应 trait。

04.4.5.1-011 #[catch(..)] 与路由宏有什么区别?

一句话结论

路由宏处理正常请求匹配;catcher 宏(#[catch(404)]、#[catch(default)])处理错误状态下的请求,如未匹配、守卫错误、解析失败,并通过 catchers![..] 注册。

概念解释

请求在路由匹配、守卫、数据解析任一阶段失败,都会脱离正常 handler 流程,进入对应状态码的 catcher。catcher 是特殊 responder:接收状态与请求上下文,返回错误响应。同一路由表可注册多个 catcher,按状态码匹配;未注册的状态走默认 catcher。

原理流程

  1. 请求处理某阶段产生错误状态(404/422/500 等)。
  2. Rocket 查找注册的对应 catcher。
  3. 命中则调用 catcher 函数生成响应。
  4. 未命中则使用默认 catcher。
  5. 错误响应发送给客户端。

代码或图示

#[rocket::catch(404)]
fn not_found(req: &rocket::Request<'_>) -> String {
    format!("未找到: {}", req.uri())
}

let _ = rocket::build().register("/", rocket::catchers![not_found]);

常见误区

  • 在路由 handler 里手写 404 分支替代 catcher:统一错误响应应走 catcher 机制。
  • 注册了路由却忘记注册 catcher:错误响应使用默认页面,结构不符合接口约定。

追问

  • catcher 能拿到 body 解析错误详情吗?答:可通过 catcher 参数与数据守卫的 Result 捕获;错误信息的可访问范围以版本文档为准。
  • 默认 catcher 作用是什么?答:为未显式注册的状态码提供兜底响应;#[catch(default)] 可自定义该兜底行为。

04.4.5.1-012 路由 URI 中的查询段如何声明?

一句话结论

查询参数写在 URI 模板的 ? 之后,形如 ?<page>、?<page>&<size>,按同名绑定到 handler 参数;结构体绑定查询参数通过表单/查询解析类型完成。

概念解释

Rocket 路由模板可包含查询部分,动态查询段用尖括号声明。查询参数解析由对应类型完成:标量类型直接解析,结构体实现表单绑定 trait 后整体接收。缺失或解析失败按守卫/数据错误流程处理。查询段与路径段共用占位符语法,但位置在 ? 之后。

原理流程

  1. 路由模板写出 ?<param> 声明查询参数。
  2. 请求查询串按名取值。
  3. 按参数类型解析(FromParam 或表单绑定)。
  4. 解析成功绑定到 handler 参数。
  5. 失败进入错误处理。

代码或图示

#[rocket::get("/posts?<page>&<size>")]
fn posts(page: u32, size: u32) -> String {
    format!("page {page} size {size}")
}

常见误区

  • 把查询参数写进路径段:路径与查询语法位置不同。
  • 查询参数类型不支持解析导致路由永不匹配:先确认类型实现了解析 trait。

追问

  • 可选查询参数怎么声明?答:参数类型用 Option<T>;默认值处理见 04.4.5.1-074。
  • 重复出现的查询参数如何绑定?答:集合类型(Vec 等)通过表单绑定接收,见 04.4.5.1-075。

04.4.5.1-013 rank 的优先级规则是什么?

一句话结论

rank 是路由排序键:数值越小优先级越高,匹配时优先尝试高优先级路由;默认 rank 按 URI 模板自动计算,手动 rank 用于覆盖默认顺序。

概念解释

当多个路由能匹配同一请求时,rank 决定尝试顺序。Rocket 内部结合 URI 静态段数量计算默认优先级;静态段越多、越具体的路由越优先。默认顺序不满足需求时(如兜底动态路由需要排在最后),手动设置 rank 调整。rank 只影响匹配顺序,不改变守卫与解析逻辑。

原理流程

  1. 启动期为每条路由计算或读取 rank。
  2. 路由表按 rank 升序排列。
  3. 请求到达,按顺序尝试匹配。
  4. 高优先级路由守卫/解析通过即采用。
  5. 失败则继续尝试下一优先级路由。

代码或图示

#[rocket::get("/users/<id>", rank = 1)]
fn by_id(id: u64) -> String { format!("{id}") }

#[rocket::get("/<path..>", rank = 10)]
fn fallback(path: &str) -> String { format!("fallback {path}") }

常见误区

  • 以为 rank 数值越大越优先:与常见直觉相反,小数值先匹配。
  • 不给兜底路由降优先级:兜底路由可能抢先匹配具体路径。

追问

  • 默认 rank 如何计算?答:Rocket 根据 URI 静态段与结构自动计算;具体公式以当前版本文档为准,不要凭记忆写死数值。
  • 两条路由 rank 相同如何排序?答:按路由注册顺序与内部规则处理;不确定时显式设置 rank 消除歧义。

04.4.5.1-014 默认 rank 如何按 URI 计算?

一句话结论

默认 rank 倾向于让更具体的模板优先:静态段越多、动态段越少的路由优先级越高;通配多段路由默认排在具体路由之后,具体计算公式以 Rocket 当前版本为准。

概念解释

默认排序解决“静态详情页与动态通配路由谁先匹配”的常见问题:Rocket 把模板结构折算为 rank,具体模板数值更小。理解默认行为可以减少手动 rank:只有当默认顺序不符合业务需要时才覆盖。启动日志会列出路由及其 rank,可用于核对实际顺序。

原理流程

  1. 解析模板,统计静态段、动态段与多段通配。
  2. 内部规则折算为默认 rank 值。
  3. 具体模板优先于通配模板。
  4. 启动日志展示各路由 rank。
  5. 必要时手动覆盖。

代码或图示

默认优先级倾向
├── /users/profile        静态段多,优先
├── /users/<id>           含动态段,次之
└── /<path..>             多段通配,兜底最后

常见误区

  • 依赖记忆中的默认数值:版本间计算规则可能调整,以启动日志与当前文档为准。
  • 所有路由都手动设 rank:增加维护成本,优先利用默认排序。

追问

  • 如何查看某条路由的默认 rank?答:Rocket 启动日志会打印已挂载路由及其排序信息;具体日志格式以版本为准。
  • 静态段与动态段冲突时谁优先?答:静态匹配优先于动态捕获,这也是默认 rank 规则的一部分。

04.4.5.1-015 动态段 <id> 与类型标注 <id: u64> 有什么区别?

一句话结论

<id> 只声明捕获段,类型由 handler 参数决定;<id: u64> 在模板上显式标注解析类型,解析失败则路由不匹配,类型标注与参数类型应保持一致。

概念解释

动态段的值是字符串,需要通过 FromParam 转成目标类型。模板标注类型是显式写法,便于阅读与校验;不标注时按 handler 参数类型解析。数字、布尔等标准类型内置 FromParam 实现;自定义类型实现该 trait 后也可标注。类型解析失败时该路由不参与匹配,继续尝试其他路由。

原理流程

  1. 请求路径段被捕获为字符串。
  2. 读取模板标注或参数类型。
  3. 调用 FromParam 解析。
  4. 成功 → 绑定参数;失败 → 跳过该路由。
  5. 全部路由失败进入 404。

代码或图示

#[rocket::get("/items/<id: u64>")]
fn item(id: u64) -> String { format!("{id}") }

// 自定义类型同样可标注,前提是实现 FromParam
#[rocket::get("/orders/<order: OrderId>")]
fn order(order: OrderId) -> String { format!("{order:?}") }

常见误区

  • 模板类型与参数类型不一致:以 Rocket 校验结果为准,可能启动报错或运行期解析失败。
  • 用 <id: String> 标注:String 参数通常直接用 &str,避免多余分配。

追问

  • FromParam 为哪些内置类型实现?答:常见整数、浮点、布尔、&str、String 等;完整列表以当前版本文档为准。
  • 解析失败返回 400 还是 404?答:路由不匹配时继续尝试其他路由;若无其他匹配走 404;参数级错误状态与 catcher 关联以版本实现为准。

04.4.5.1-016 多段路径 <path..> 如何捕获剩余路径?

一句话结论

<path..> 捕获 URI 中从该位置开始的全部剩余段(含斜杠),适合静态文件代理、兜底路由等场景;参数类型通常为 &str、String 或路径集合类型。

概念解释

普通动态段只匹配单段,多段通配捕获剩余整条路径。它必须位于模板末尾;捕获值保留段间斜杠。典型用途:把未匹配路径交给兜底 handler、代理静态资源路径。多段路由默认 rank 较低,避免抢先匹配具体路由。

原理流程

  1. 模板末尾声明 <path..>。
  2. 请求路径前面的段按规则匹配。
  3. 剩余全部段被通配段捕获。
  4. 按参数类型解析为路径字符串。
  5. handler 处理剩余路径。

代码或图示

#[rocket::get("/static/<path..>")]
fn asset(path: &str) -> String { format!("asset: {path}") }

#[rocket::get("/<path..>", rank = 10)]
fn fallback(path: &str) -> String { format!("404-ish: {path}") }

常见误区

  • 把 <path..> 放在模板中间:多段通配必须在末尾。
  • 以为捕获值去掉了前导斜杠:取值格式以当前版本实现为准,使用前核对。

追问

  • 多段捕获能限制段数吗?答:可使用带数量上限的通配语法;具体写法以版本文档为准。
  • 静态文件服务怎么用?答:Rocket 提供文件服务相关类型与 catcher 配合;本主题聚焦路由语法,文件 responder 细节见后续章节。

04.4.5.1-017 <path..N> 限定段数是什么含义?

一句话结论

带数量的多段通配限制捕获的段数上限,避免无限制匹配;具体语法(段数标注形式)与边界行为以 Rocket 当前版本文档为准,不确定处应在 docs.rs 核对。

概念解释

某些场景只希望通配固定数量的段(如两级资源路径),数量标注可以收紧匹配范围。超出段数的请求不匹配该路由。该语法属于 Rocket 路由模板细节,不同版本可能调整,面试中应说明“以当前版本文档为准”,并指出验证方式。

原理流程

  1. 模板声明带段数的通配段。
  2. 请求剩余路径按段拆分计数。
  3. 段数在允许范围内 → 匹配。
  4. 超出范围 → 跳过该路由。
  5. 继续尝试其他路由或走兜底。

代码或图示

// 语法形式待确认:以 docs.rs/rocket/latest 路由模板文档为准
// #[rocket::get("/files/<path..2>")]
// fn two_level(path: &str) { /* ... */ }

常见误区

  • 凭记忆写死段数语法:版本间语法可能不同,应核对当前文档。
  • 把段数限制写进 handler 二次判断:模板层能限制的优先在路由层完成。

追问

  • 段数不足时行为是什么?答:不匹配该路由,继续尝试其他匹配;具体空段处理以版本文档为准。
  • 如何验证某语法是否支持?答:查看 Rocket 源码或 docs.rs 路由章节,编译一个最小路由示例确认。

04.4.5.1-018 尾部斜杠在 Rocket 路由中如何处理?

一句话结论

路由模板与请求路径的尾斜杠按 Rocket 匹配规则对齐;静态段与动态段对尾斜杠的处理可能不同,具体归一化行为以当前版本为准,不确定时用最小示例验证。

概念解释

尾部斜杠是路由匹配常见争议点:/users/ 与 /users 是否视为同一资源取决于框架规则。Rocket 0.5 的匹配规则按段比较,尾斜杠不自动等同于空段。项目需要统一风格:路由模板不带尾斜杠,重定向或归一化在必要时显式处理。不同版本行为可能调整,面试中不写死结论。

原理流程

  1. 请求路径按斜杠拆分为段序列。
  2. 路由模板同样拆分段序列。
  3. 两段序列逐段比对。
  4. 尾斜杠是否产生空段按版本规则处理。
  5. 不匹配则尝试下一路由。

代码或图示

#[rocket::get("/users")]
fn users() -> &'static str { "users" }

// /users/ 是否命中上述路由:以 Rocket 当前版本匹配规则为准

常见误区

  • 假设框架自动 301 去尾斜杠:需要显式重定向时自行实现。
  • 模板与请求尾斜杠风格混用:测试中覆盖两种写法避免 404。

追问

  • 如何统一尾斜杠风格?答:路由模板保持一致,必要时加规范化重定向 catcher 或中间件;具体实现按项目约定。
  • 静态文件路径对尾斜杠敏感吗?答:文件系统路径语义不同,文件服务类型内部处理,以对应文档为准。

04.4.5.1-019 路径参数解析失败走哪个 catcher?

一句话结论

路径参数 FromParam 解析失败时该路由不匹配;若无其他路由命中,请求进入 404 流程;参数类型相关的错误状态映射以 Rocket 当前版本实现为准。

概念解释

与 body 解析不同,路径段解析发生在路由匹配阶段:类型不匹配的路由被跳过,而不是在已匹配 handler 内报错。因此非法 ID 通常表现为 404 而非 400。若需要区分“路由不存在”与“ID 格式非法”,可在 handler 内接收宽松类型(如 &str)再自行解析并返回业务错误。

原理流程

  1. 路由捕获段字符串,尝试 FromParam 解析。
  2. 失败 → 该路由不匹配。
  3. 遍历剩余路由,全部失败 → 404 catcher。
  4. 需要显式 400/422 时,handler 内宽松接收再校验。
  5. 校验失败返回业务错误响应。

代码或图示

#[rocket::get("/items/<id>")]
fn item(id: &str) -> Result<String, BadRequest> {
    let id: u64 = id.parse().map_err(|_| BadRequest("id 非法"))?;
    Ok(format!("{id}"))
}

常见误区

  • 期望数字解析失败返回 400:默认流程是跳过路由,不产生参数错误响应。
  • 在路径参数里塞复杂结构:应改用查询参数或 body。

追问

  • FromParam 错误能否被 catcher 捕获?答:路由匹配阶段的失败与守卫/body 错误流程不同;可捕获的错误类型以版本文档为准。
  • 如何对非法 ID 返回明确提示?答:路径参数用字符串宽松接收,handler 内解析失败返回自定义错误 responder。

04.4.5.1-020 FromParam trait 与自定义路径类型怎么实现?

一句话结论

FromParam 把路径段字符串转换为参数类型;自定义 ID/枚举类型实现该 trait 的解析方法,成功返回值,失败返回描述错误的类型,即可在路由模板中标注使用。

概念解释

路径参数解析是 trait 驱动的:标准类型内置实现,业务类型(如 OrderId、Slug)实现 FromParam 后获得路由绑定能力。trait 方法接收 &RawStr(0.5 中相关字符串类型以版本文档为准),返回 Result<Self, Self::Error>。错误类型可携带解析失败原因,供上层处理。

原理流程

  1. 定义新类型包装标量值(newtype 模式)。
  2. 实现 FromParam:段字符串解析为内部值。
  3. 解析失败返回 Err 与错误描述。
  4. 路由模板标注该类型。
  5. 请求匹配时自动调用解析。

代码或图示

struct OrderId(u64);

impl<'a> rocket::request::FromParam<'a> for OrderId {
    type Error = std::num::ParseIntError;
    fn from_param(param: &'a rocket::http::RawStr) -> Result<Self, Self::Error> {
        param.parse::<u64>().map(OrderId)
    }
}

#[rocket::get("/orders/<id>")]
fn order(id: OrderId) -> String { format!("{:?}", id.0) }

常见误区

  • 自定义类型没实现 FromParam 就写进模板:路由无法绑定。
  • 解析错误直接 panic:应返回 Err,走框架错误流程。

追问

  • RawStr 在 0.5 中有什么变化?答:0.5 入参自动解码,&str 实现了 FromParam;RawStr 相关 API 以升级指南与当前文档为准。
  • 复合路径值怎么解析?答:路径段只适合单值;多值结构放查询参数或 body。

04.4.5.1-021 静态段与动态段冲突时谁优先?

一句话结论

静态段字面匹配优先于动态段捕获:同一路由位置,固定字符串段先于 <param> 匹配,这一规则也体现在默认 rank 计算中。

概念解释

典型场景:/users/new(静态)与 /users/<id>(动态)并存。若动态路由抢先匹配,new 会被当成 ID 解析失败。Rocket 的匹配顺序保证静态具体路由优先,动态路由兜底。理解该规则可以避免把特例路径写成动态参数后再在 handler 内分支判断。

原理流程

  1. 启动期按 rank 组织路由顺序。
  2. 请求 /users/new:先尝试静态段路由。
  3. 静态段字面相等 → 匹配静态 handler。
  4. 静态不匹配才尝试动态捕获。
  5. 动态段解析失败则跳过。

代码或图示

#[rocket::get("/users/new")]
fn create_page() -> &'static str { "new" }

#[rocket::get("/users/<id>")]
fn profile(id: u64) -> String { format!("{id}") }

常见误区

  • 把特例路径合并进动态 handler 内部 match:丧失路由层的静态优先保护。
  • 动态段类型过宽(如 &str)后内部判断:仍可能拦截本应静态匹配的路径。

追问

  • 两个静态段冲突怎么办?答:同方法同路径重复注册属于路由冲突,启动期报错。
  • 静态优先规则与 rank 手动设置冲突吗?答:手动 rank 覆盖默认顺序;设错优先级可能反转静态/动态匹配,需核对启动日志。

04.4.5.1-022 通配段与固定段冲突时谁优先?

一句话结论

固定段路由优先于多段通配路由;通配 <path..> 作为兜底应排在具体路由之后,必要时通过手动 rank 保证顺序。

概念解释

多段通配能匹配任意剩余路径,若优先级高于具体路由,会把详情页、接口路径全部截走。默认 rank 已倾向具体路由优先;在自定义结构复杂时,仍需检查启动日志确认通配路由排在最后。兜底路由内部再做 404 或资源查找。

原理流程

  1. 具体路由(含静态/动态单段)按默认顺序在前。
  2. 多段通配路由 rank 靠后。
  3. 请求先匹配具体路由。
  4. 全部具体路由失败才进入通配兜底。
  5. 兜底 handler 返回资源或 404。

代码或图示

#[rocket::get("/api/items/<id: u64>")]
fn item(id: u64) -> String { format!("{id}") }

#[rocket::get("/<path..>", rank = 10)]
fn wildcard(path: &str) -> String { format!("wildcard: {path}") }

常见误区

  • 通配路由不设低优先级:抢先匹配具体 API 路径。
  • 兜底路由返回 200:未找到资源应走 404 状态与 catcher。

追问

  • 通配路由内如何区分静态资源与未知 API?答:按路径前缀分支处理;或拆分多个前缀路由,兜底只处理未匹配部分。
  • 多实例/多前缀挂载时 rank 还生效吗?答:rank 在挂载后的路由表内生效;前缀由 mount 拼接,具体规则以版本文档为准。

04.4.5.1-023 路由冲突在启动期如何暴露?

一句话结论

重复方法与路径、参数绑定不一致、Sentinel 条件缺失等冲突在 Rocket 启动校验阶段报告;诊断信息列出冲突路由与原因,未通过校验不会进入监听。

概念解释

启动期路由表构建是冲突检测的关卡:同方法同路径注册两次、占位符无对应参数、依赖的托管状态未注册,都会在此暴露。阅读启动日志是排查冲突的第一步;Sentinel 为自定义类型提供额外的条件检查钩子。开发环境应尽早跑启动流程,而不是等到集成测试。

原理流程

  1. mount/routes! 收集路由元数据。
  2. 校验方法、路径、参数绑定一致性。
  3. 检查 Sentinel 前置条件(托管状态、catcher 等)。
  4. 冲突项输出诊断信息。
  5. 校验失败中止启动,进程退出。

代码或图示

let rocket = rocket::build()
    .mount("/", rocket::routes![route_a, route_b])
    .register("/", rocket::catchers![not_found]);
// 启动日志中检查重复路由与绑定诊断

常见误区

  • 启动报错只看最后一行:冲突原因可能在前面的诊断段落。
  • 用忽略诊断的方式强行上线:运行期错误更难排查。

追问

  • 路由冲突与 rank 顺序是一回事吗?答:冲突指无法共存的重复/不一致注册;rank 是可共存路由之间的匹配顺序,两者不同。
  • 如何批量检查路由?答:routes![..] 宏集中收集;启动日志列出全部已挂载路由,便于核对。

04.4.5.1-024 rank 手动设置的典型场景有哪些?

一句话结论

典型场景:兜底通配路由需要排在最后、同一前缀下特例路径优先于动态路由、多版本路由并存需要显式排序;默认顺序不符合预期时才手动覆盖。

概念解释

手动 rank 是对默认排序的纠偏工具。最常见需求是给 <path..> 兜底路由设低优先级;其次是同一资源下特殊路径与动态 ID 的顺序确认。滥用手动 rank 会让匹配顺序难以理解,应优先依赖默认规则,启动日志核对后再调整。

原理流程

  1. 观察默认匹配是否符合预期。
  2. 识别需要前置/后置的路由。
  3. 在路由宏上设置 rank。
  4. 启动日志核对顺序。
  5. 回归测试覆盖冲突路径。

代码或图示

#[rocket::get("/docs/<page..>", rank = 1)]
fn docs(page: &str) -> String { format!("doc {page}") }

#[rocket::get("/<path..>", rank = 10)]
fn fallback(path: &str) -> String { format!("fallback {path}") }

常见误区

  • 给所有路由按注册顺序手动编号:默认规则被掩盖,后续新增路由容易排错。
  • rank 设置后不写测试:路径优先级回归问题难以发现。

追问

  • rank 可以设负数吗?答:取值范围与正负号规则以当前版本文档为准;需要最前置时核对允许范围。
  • 子挂载路由的 rank 如何计算?答:mount 拼接前缀后在同一表内排序;具体规则以版本文档为准。

04.4.5.1-025 URI 编码与 &str 参数自动解码是怎样的?

一句话结论

Rocket 0.5 自动对入参做百分比解码,&str 参数拿到解码后的字符串;解码规则覆盖查询参数与路径段,原始编码字符串的访问方式以版本文档为准。

概念解释

URL 中中文、空格、特殊符号以百分号编码传输。框架负责解码,handler 直接使用可读字符串。0.5 的升级指南明确:&str 实现了 FromParam 且完全解码,&RawStr 不再承担原始段角色。处理含斜杠或特殊字符的值时,注意解码后再做业务校验。

原理流程

  1. 原始请求 URI 进入框架。
  2. 路径段与查询值按规则百分比解码。
  3. 解码结果绑定到 &str/字符串参数。
  4. handler 使用解码后的值。
  5. 非法编码按框架错误流程处理。

代码或图示

#[rocket::get("/search/<keyword>")]
fn search(keyword: &str) -> String {
    // keyword 已是解码后的中文或空格形式
    format!("search: {keyword}")
}

常见误区

  • 业务代码再做一次解码:双重解码导致 % 字符处理错误。
  • 假设参数保留原始编码:0.5 行为是自动解码,旧版 RawStr 用法需迁移。

追问

  • 解码后含中文如何做匹配?答:按解码后字符串与数据库/字典比对;注意大小写与规范化形式。
  • 编码非法时返回什么?答:解码失败按框架错误流程处理;具体状态码以版本文档为准。

04.4.5.1-026 路径参数的多值或复合类型怎么绑定?

一句话结论

路径段只适合绑定单值标量;多值与复合结构应放到查询参数(结构体绑定)或请求 body;需要在路径表达层级关系时使用多段通配 <path..> 分段解析。

概念解释

FromParam 面向单个路径段,复合对象(地址、筛选条件、分页)不适合塞进路径。Rocket 的分工:路径表达资源层级与标识,查询表达可选过滤与分页,body 承载复杂提交数据。复合类型通过 FromForm 绑定查询或表单,路径只保留 ID、Slug 等单值。

原理流程

  1. 判断参数是标识还是复合数据。
  2. 标识 → 路径段,实现 FromParam。
  3. 过滤/分页 → 查询参数,结构体 FromForm 绑定。
  4. 提交数据 → body,FromData 守卫。
  5. 层级路径 → <path..> 捕获后在 handler 内拆分。

代码或图示

#[rocket::get("/users/<id>/orders?<status>&<page>")]
fn orders(id: u64, status: Option<String>, page: u32) -> String {
    format!("{id} {status:?} {page}")
}

常见误区

  • 路径段用分隔符拼多个值(如 /users/1,2,3):解析规则自定义,不如查询集合类型清晰。
  • 把提交表单塞进路径:违反 HTTP 语义,长度与编码都受限。

追问

  • 路径里放 Slug 怎么实现?答:newtype 包装字符串并实现 FromParam,校验字符集后绑定。
  • 复合查询结构体怎么写?答:派生 FromForm,字段名与查询参数同名;见 04.4.5.1-072。

04.4.5.1-027 路由中的重定向与内部跳转怎么实现?

一句话结论

重定向通过 responder 返回 (Status::Found, uri) 或框架提供的重定向类型实现;内部不做“转发到另一 handler”的调用,需要复用逻辑时抽取公共函数。

概念解释

HTTP 重定向是服务端返回 3xx 状态与 Location 头,浏览器/客户端重新请求。Rocket 提供组合 responder 或重定向类型表达该语义。与某些框架的内部 forward 不同,Rocket 路由匹配是一次性的;守卫 Forward 是把请求让给下一条路由,而不是 handler 内部跳转。复用业务逻辑应抽成普通函数在各 handler 调用。

原理流程

  1. handler 判断需要跳转。
  2. 返回 3xx 状态与目标 URI。
  3. 框架写入 Location 响应头。
  4. 客户端按状态码决定重新请求。
  5. 公共逻辑抽取为函数复用。

代码或图示

use rocket::http::Status;

#[rocket::get("/old/<id>")]
fn old(id: u64) -> (Status, rocket::http::uri::Origin<'static>) {
    // 具体重定向类型与构造方式以 Rocket 当前版本文档为准
    (Status::MovedPermanently, rocket::http::uri::Origin::parse(format!("/new/{id}")).unwrap().into_owned())
}

常见误区

  • 在 handler 内直接调用另一个 handler 函数:绕过路由守卫与 responder,状态上下文不一致。
  • 用 200 加页面跳转模拟重定向:丢失 3xx 语义,客户端无法跟随。

追问

  • 301 与 302 怎么选?答:永久迁移用 301,临时跳转用 302;307/308 保留请求方法,具体语义按 HTTP 规范。
  • 守卫 Forward 与重定向有何区别?答:Forward 是服务端把请求让给下一条匹配路由,不产生 3xx 响应;重定向是告诉客户端重新发起请求。

04.4.5.1-028 版本前缀路由如何组织(mount 与子路由)?

一句话结论

用 mount("/api/v1", routes![...]) 给一组路由统一加前缀;版本演进时按前缀分组挂载,路由模板内只写相对该前缀的路径。

概念解释

mount 在启动期把路由表挂载到前缀下,拼接 URI 模板。API 版本化、模块划分都通过挂载分组实现:同一模块的路由集中在 routes! 列表,挂载到对应前缀。前缀拼接发生在启动期,不影响 handler 内参数绑定。多版本并存时分别挂载 /v1、/v2,各自路由表独立。

原理流程

  1. 按模块/版本编写 handler 与路由模板。
  2. routes![..] 收集该组路由。
  3. mount(prefix, routes) 拼接前缀。
  4. 启动期校验拼接后的完整路径。
  5. 请求按完整路径匹配。

代码或图示

let rocket = rocket::build()
    .mount("/api/v1", rocket::routes![v1::list, v1::create])
    .mount("/api/v2", rocket::routes![v2::list, v2::create]);

常见误区

  • 路由模板里写全路径又重复 mount 前缀:路径拼接重复,导致匹配不到。
  • 跨版本复制 handler 不抽公共逻辑:版本分叉后维护成本高。

追问

  • mount 前缀可以是多级吗?答:可以,前缀按路径段拼接;具体归一化规则以版本文档为准。
  • 静态资源与 API 分开挂载怎么做?答:分别 mount 不同前缀,文件服务类型挂到静态前缀下。

04.4.5.1-029 什么是请求守卫(request guard)?

一句话结论

请求守卫是实现 FromRequest 的类型,在 handler 执行前校验请求元信息(认证、权限、头、Cookie 等);全部守卫通过才调用 handler,失败按 Outcome 流程处理。

概念解释

守卫把横切的校验策略收敛到类型上:handler 参数列表里出现守卫类型,Rocket 自动在分发前执行其 from_request。守卫不读取 body(body 由 data 守卫处理),可访问请求头、Cookie、URI、状态等。典型守卫:认证用户、管理员、API Key、语言偏好。守卫失败不抛异常,而是返回 Outcome 表达成功、错误或转发。

原理流程

  1. 请求匹配到路由。
  2. Rocket 按参数顺序构造守卫。
  3. 每个守卫调用 from_request 校验。
  4. 全部 Success → 执行 handler。
  5. Error/Forward → 进入对应错误或转发流程。

代码或图示

#[rocket::get("/admin")]
fn dashboard(admin: AdminUser) -> String {
    format!("welcome {}", admin.username)
}

常见误区

  • 把 body 解析逻辑写进请求守卫:body 只能由 data 守卫消费,守卫读取的是请求元信息。
  • 在守卫里写业务写入副作用:守卫职责是校验与提取,副作用应在 handler/service 层。

追问

  • 守卫与中间件有何异同?答:两者都做横切校验;守卫是类型化参数,结果直接进入 handler;中间件/ fairing 面向请求响应流程,不产生 handler 参数。
  • 一个 handler 可以有几个守卫?答:任意数量,按参数顺序依次构造;具体顺序规则见 04.4.5.1-037。

04.4.5.1-030 FromRequest trait 的方法与关联类型是什么?

一句话结论

FromRequest<'r> 定义关联类型 Error 与异步方法 from_request(req: &'r Request<'_>) -> Outcome<Self, Self::Error>;实现需加 #[rocket::async_trait],返回成功值、错误或转发。

概念解释

trait 签名体现守卫的输入输出:输入是借用的 Request,输出是三态 Outcome。Error 关联类型描述失败原因,可被 handler 用 Result 捕获。'r 生命周期绑定请求生命周期,允许守卫借用请求内数据。0.5 中方法为 async,必须通过 async_trait 宏标注,具体签名以 docs.rs 当前版本为准。

原理流程

  1. 定义守卫结构体与错误类型。
  2. 标注 impl<'r> FromRequest<'r> for Guard。
  3. 指定 type Error = GuardError。
  4. 实现 async from_request,读取请求并返回 Outcome。
  5. handler 参数使用该守卫类型。

代码或图示

use rocket::request::{FromRequest, Outcome, Request};

struct ApiKey(String);

#[rocket::async_trait]
impl<'r> FromRequest<'r> for ApiKey {
    type Error = ();

    async fn from_request(req: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        match req.headers().get_one("x-api-key") {
            Some(key) => Outcome::Success(ApiKey(key.to_string())),
            None => Outcome::Error((rocket::http::Status::Unauthorized, ())),
        }
    }
}

常见误区

  • 漏写 type Error:trait 关联类型未满足,编译报错。
  • 返回类型与 Outcome 泛型参数不匹配:错误类型必须与 Error 关联类型一致。

追问

  • Request 暴露哪些访问方法?答:头、Cookie、URI、方法、查询参数、托管状态等;完整方法列表以版本文档为准。
  • 守卫能持有请求借用的数据吗?答:可以,'r 生命周期允许引用请求内字符串等;拥有所有权的数据需克隆。

04.4.5.1-031 守卫与 data 参数在 handler 中的顺序规则是什么?

一句话结论

请求守卫在请求元信息阶段构造,data 守卫在 body 阶段解析;Rocket 按参数类型与路由声明推断角色,body 参数通常位于参数列表后部,具体顺序约束以版本文档为准。

概念解释

两类守卫构造阶段不同:FromRequest 读请求头与元信息,FromData 消费 body。body 只能被读取一次,因此 data 参数不能与其他 body 类型共存。handler 参数顺序影响构造短路:守卫失败就不会进入 body 解析。编写 handler 时把守卫放在前、data 参数放在后,符合框架预期。

原理流程

  1. Rocket 识别参数:路由声明参数、守卫、data 参数。
  2. 先执行所有 FromRequest 守卫。
  3. 守卫通过后读取并解析 body(FromData)。
  4. 全部构造成功调用 handler。
  5. 任一阶段失败走对应 Outcome 流程。

代码或图示

#[rocket::post("/items", data = "<item>")]
fn create(
    auth: AuthGuard,                 // 请求守卫
    item: rocket::serde::json::Json<Item>, // 数据守卫
) { /* ... */ }

常见误区

  • 放两个 body 守卫:body 第二次读取为空,解析失败。
  • 把 data 参数名写进 URI 占位符:data 参数由 data 属性声明,不在路径模板中。

追问

  • 守卫失败后 body 还会被读取吗?答:短路在守卫阶段,body 解析不执行;连接与 body 的后续处理按框架实现。
  • 参数顺序有编译检查吗?答:类型与声明一致性由启动期与编译期校验;具体报错形式以版本为准。

04.4.5.1-032 守卫参数如何与路由声明参数区分?

一句话结论

在 URI 模板或 data 属性中按名字声明的是路由/数据参数;未在路由属性声明、类型实现 FromRequest 的参数是请求守卫。

概念解释

Rocket 按声明来源判断参数角色:模板占位符对应路径/查询参数,data 对应 body 参数,其余参数走守卫解析。参数名与占位符同名是绑定条件;守卫类型即使名字相同,角色由类型实现的 trait 决定。理解这一区分有助于阅读 Rocket handler 签名。

原理流程

  1. 解析路由属性中的路径、查询、data 声明。
  2. 遍历 handler 参数,匹配已声明名字。
  3. 已声明 → 对应路由/数据参数。
  4. 未声明且实现 FromRequest → 请求守卫。
  5. 既未声明也非守卫 → 启动期报错。

代码或图示

#[rocket::get("/users/<id>?<tab>")]
fn profile(
    id: u64,            // 路径参数
    tab: String,        // 查询参数
    auth: AuthGuard,    // 请求守卫
) { /* ... */ }

常见误区

  • 守卫参数名与占位符同名导致混淆:命名上让守卫类型名体现角色(如 AuthUser)。
  • 忘记在 data 声明 body 参数:该参数被当作守卫类型检查,编译或启动报错。

追问

  • State<T> 属于哪类?答:State 是实现 FromRequest 的守卫式提取器,未在路由属性中声明。
  • 同一类型既是路径参数又是守卫可能吗?答:类型实现哪个 trait 就走哪条路径;一个类型不宜同时承担两种角色。

04.4.5.1-033 Outcome 三个变体 Success、Error、Forward 分别是什么含义?

一句话结论

Success(S) 表示守卫成功并给出值;Error(E) 表示校验失败,请求进入对应 catcher;Forward(F) 表示本守卫无法处理,请求转给下一条可匹配路由。

概念解释

Outcome 是 Rocket 核心三态返回类型,用于 FromRequest、FromData 与 responder。Success 提供 handler 所需值;Error 终止当前处理并按状态码找 catcher;Forward 让出当前路由,由其他路由尝试,全部失败再走 404。三态区分了“拒绝”与“不适用”:认证失败是 Error,当前类型无法判断场景是 Forward。

原理流程

  1. 守卫/数据解析返回 Outcome。
  2. Success → 解包值交给 handler。
  3. Error → 携带状态码与错误,进入 catcher。
  4. Forward → 跳过当前路由,尝试下一条。
  5. 无后续路由 → 404 兜底。

代码或图示

use rocket::outcome::Outcome;
use rocket::http::Status;

# fn demo() -> Outcome<u64, (), ()> {
Outcome::Success(1)            // 成功
// Outcome::Error((Status::Unauthorized, ()))  // 错误
// Outcome::Forward(Status::BadRequest)        // 转发
# }

常见误区

  • 把“未登录”写成 Forward:未登录是明确拒绝,应返回 Error 401;Forward 用于类型不适用当前场景。
  • 忽略 Forward 分支:请求被错误终止在当前路由。

追问

  • Error 携带哪些信息?答:通常包含状态码与错误类型值;具体元组结构以当前版本文档为准。
  • Forward 到下一路由后原守卫状态还保留吗?答:转发发生在路由匹配层,已构造的守卫值不跨路由传递;以版本文档行为为准。

04.4.5.1-034 Forward 转发到下一个匹配路由的机制是什么?

一句话结论

守卫返回 Forward 后,Rocket 放弃当前路由,按 rank 顺序尝试下一条匹配路由;若所有路由都转发或失败,请求由 404 catcher 处理。

概念解释

Forward 的典型用法是分层认证守卫:User 守卫在无凭证时转发,让 AdminUser 或公开路由接管;路由之间形成回退链。转发不产生 HTTP 响应,请求仍在服务端路由表内流动。设计 Forward 时要清楚回退顺序,避免请求在多条路由间空转后落到不符合预期的处理器。

原理流程

  1. 当前路由守卫返回 Forward。
  2. Rocket 标记当前路由不可用。
  3. 按 rank 顺序取下一条匹配路由。
  4. 新路由重新构造守卫与参数。
  5. 全部失败 → 404 catcher。

代码或图示

// User 守卫:无凭证时 Forward,交由后续路由判断
#[rocket::async_trait]
impl<'r> FromRequest<'r> for User {
    type Error = ();
    async fn from_request(req: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        match identify(req) {
            Some(user) => Outcome::Success(user),
            None => Outcome::Forward(rocket::http::Status::Unauthorized),
        }
    }
}

常见误区

  • Forward 与 Error 混用:Forward 是“交给别人”,Error 是“拒绝”,语义相反。
  • 转发链过长:排查请求落到哪条路由时困难,应控制守卫层级。

追问

  • 如何捕获 Forward 结果?答:handler 参数用 Option<S>,Forward 时为 None;详见 04.4.5.1-036。
  • 转发会重新匹配路径与方法吗?答:在已匹配候选路由间继续尝试;路径/方法条件不变,以版本文档为准。

04.4.5.1-035 守卫返回 Error 如何走到 catcher?

一句话结论

守卫 Error 携带状态码,Rocket 按该状态码查找注册的 catcher;catcher 生成错误响应,未注册则使用默认 catcher。

概念解释

Error 是明确拒绝:请求不再继续 handler,进入错误处理通道。状态码决定调用哪个 catcher(401、403、404 等)。错误类型值可通过 handler 的 Result 参数捕获查看,但请求已脱离正常 handler 流程。catcher 共享同一响应类型体系,可以返回 JSON 错误体。

原理流程

  1. 守卫返回 Error((status, error_value))。
  2. Rocket 按状态码检索 catcher 注册表。
  3. 命中 catcher → 调用 catcher 生成响应。
  4. 未命中 → 默认 catcher。
  5. 错误响应发送客户端。

代码或图示

#[rocket::catch(401)]
fn unauthorized<'r>(req: &'r Request<'_>) -> rocket::response::status::Unauthorized<&'r str> {
    rocket::response::status::Unauthorized(Some("需要登录"))
}

常见误区

  • 守卫 Error 后仍期待 handler 执行:Error 已终止正常流程。
  • 只注册 404 不注册 401/403:未认证响应使用默认页面,结构不符接口约定。

追问

  • catcher 如何拿到守卫错误值?答:部分错误值可通过请求本地存储或参数捕获;可访问范围以版本文档为准。
  • Error 状态码可以是 500 吗?答:协议上 5xx 表示服务端故障;守卫校验失败通常用 4xx,内部异常走错误处理流程。

04.4.5.1-036 如何用 Result<S, E> 或 Option<S> 捕获守卫结果?

一句话结论

handler 参数写成 Result<S, E> 可接收守卫的 Success/Error,写成 Option<S> 可接收 Success/Forward;这样 handler 内能区分通过、拒绝与转发,而不是直接落入 catcher。

概念解释

Rocket 允许在签名里请求守卫结果的包装类型:Result 对应 Error 分支,Option 对应 Forward 分支。包装后守卫失败不会直接走 catcher,而是把值交给 handler 判断。适合需要自定义错误响应、或在同一 handler 内处理匿名与登录两种状态的场景。包装类型与守卫类型的对应规则以版本文档为准。

原理流程

  1. 守卫正常返回 Outcome。
  2. 参数为 Result<S, E>:Success 解包为 Ok,Error 解包为 Err。
  3. 参数为 Option<S>:Success 为 Some,Forward 为 None。
  4. handler 内按分支处理。
  5. 需要错误响应时由 handler 返回 responder。

代码或图示

#[rocket::get("/profile")]
fn profile(user: Result<User, AuthError>) -> String {
    match user {
        Ok(u) => format!("hello {}", u.username),
        Err(_) => "anonymous".into(),
    }
}

常见误区

  • 包装类型与 Outcome 分支对应错误:Result 捕 Error,Option 捕 Forward,不要互换。
  • 捕获后完全忽略错误值:丢失拒绝原因,无法记录日志或返回提示。

追问

  • 一个参数能同时捕获 Error 与 Forward 吗?答:按 Rocket 提供的包装类型规则;如需完整三态,可结合请求上下文自行判断,具体支持以版本文档为准。
  • Result 的错误类型从哪来?答:守卫 FromRequest::Error 关联类型,两者必须一致。

04.4.5.1-037 多个守卫之间的执行顺序与短路规则是什么?

一句话结论

守卫按 handler 参数顺序依次构造;任一守卫返回 Error 即短路,不再构造后续守卫与 body;Forward 则跳到下一条路由,当前路由的后续守卫不再执行。

概念解释

多守卫场景需要明确执行语义:认证守卫通常在前,权限/资源守卫在后。短路保证前置校验失败时不浪费 body 解析与后续检查。顺序设计也影响错误类型:前置守卫失败返回前置错误,而不是被后置守卫覆盖。阅读 handler 签名时应按参数顺序理解校验链。

原理流程

  1. 按参数列表顺序取出守卫类型。
  2. 调用 from_request 构造当前守卫。
  3. Error → 短路,进入 catcher。
  4. Forward → 当前路由让给后续路由。
  5. 全部 Success → 进入 data 解析与 handler。

代码或图示

#[rocket::get("/admin/users")]
fn list(
    auth: AuthToken,     // 先认证
    admin: AdminUser,     // 再鉴权
) -> String { "ok".into() }

常见误区

  • 权限守卫放在认证守卫之前:未认证状态下鉴权逻辑无法取得用户身份。
  • 假设守卫并行执行:构造按顺序进行,前一个失败即短路。

追问

  • 守卫之间如何传递已认证用户?答:可在前置守卫内写入请求本地存储,后置守卫读取;或定义组合守卫类型一次性产出复合值。
  • 短路后 body 被读取了吗?答:未进入 data 阶段,body 未被守卫消费;具体连接行为以框架实现为准。

04.4.5.1-038 守卫中如何访问请求头、Cookie 与查询参数?

一句话结论

from_request 接收 &Request,通过其方法读取请求头(headers().get_one)、Cookie(cookies())与查询参数(URI/query 相关方法);具体访问器名称以版本文档为准。

概念解释

守卫的输入是 Request 引用,框架在其上提供各部分访问方法。头按名取值,Cookie 分普通与私有,查询参数从 URI 解析。守卫内读取后做校验,把需要的值包装进守卫结构体返回。跨守卫共享数据可通过请求本地存储;敏感值(令牌)只在校验过程中使用,不随意克隆留存。

原理流程

  1. 守卫实现内拿到 &Request。
  2. 调用头/Cookie/查询访问器取值。
  3. 校验或解析取值。
  4. 成功则把值封装为守卫结构体。
  5. 失败返回 Error 或 Forward。

代码或图示

#[rocket::async_trait]
impl<'r> FromRequest<'r> for Locale {
    type Error = ();
    async fn from_request(req: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        let lang = req.headers().get_one("accept-language")
            .unwrap_or("zh-CN").to_string();
        Outcome::Success(Locale(lang))
    }
}

常见误区

  • 守卫内直接消费 body:请求体不属于请求元信息,应由 data 守卫处理。
  • 多次克隆敏感凭证进守卫结构体:只保留校验后的身份标识。

追问

  • Cookie 读取有什么注意事项?答:私有 Cookie 需要解密密钥配置;Cookies API 的会话/私有区分以版本文档为准。
  • 查询参数在守卫里如何解析?答:通过 URI 查询串取值或借助表单绑定类型;复杂查询结构体优先作为独立参数绑定。

04.4.5.1-039 守卫中如何读取托管状态(State)?

一句话结论

Request 提供访问托管状态的方法,守卫内可取到注册的应用状态;State<T> 本身就是实现 FromRequest 的守卫式提取器,依赖特定状态的自定义守卫可复用同一访问路径。

概念解释

应用通过 manage() 托管共享状态,守卫与 handler 都能读取。状态访问在 Request 上完成,按类型查找。自定义守卫需要配置、数据库池、缓存句柄时,从请求状态中取出克隆句柄。状态类型缺失会被 Sentinel 在启动期检查出来,避免运行期空状态错误。

原理流程

  1. 应用启动时 manage(state) 注册托管状态。
  2. 守卫 from_request 内通过请求状态访问器取 T。
  3. 校验逻辑使用状态中的配置或连接句柄。
  4. 守卫结构体持有必要的值或句柄克隆。
  5. 状态缺失由 Sentinel/启动校验报错。

代码或图示

# struct AppState { limit: u32 }
#[rocket::async_trait]
impl<'r> FromRequest<'r> for RateLimitGuard {
    type Error = ();
    async fn from_request(req: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        let state = req.guard::<rocket::State<AppState>>().await;
        // 使用 state 中的配置完成校验;具体 State API 以版本文档为准
        Outcome::Success(RateLimitGuard)
    }
}

常见误区

  • 守卫内自己构造状态实例:共享状态必须来自托管注册,不能局部新建。
  • 状态类型未注册就访问:运行期取不到值;应靠启动期 Sentinel 检查暴露。

追问

  • State<T> 提取器返回什么?答:对托管状态的引用包装;句柄类型可克隆时克隆进守卫,具体 API 以版本文档为准。
  • 守卫能修改托管状态吗?答:可通过内部可变性(锁、原子类型)修改;共享可变状态的并发安全要求与普通 Rust 一致。

04.4.5.1-040 守卫的生命周期标注 'r 是什么含义?

一句话结论

FromRequest<'r> 的 'r 绑定请求生命周期,允许守卫类型借用请求内的字符串/数据;守卫值的有效范围不超过当前请求,跨请求保存必须克隆为拥有所有权的数据。

概念解释

trait 定义 impl<'r> FromRequest<'r>,'r 与 from_request 的 &'r Request 一致。守卫可以持有 &'r str 这类借用引用,省去克隆;但引用不能离开请求存活。需要存入会话、缓存或跨任务传递的值,必须转为 String 等自有类型。生命周期标注是编译期内存安全约束,与业务逻辑无关。

原理流程

  1. 实现声明 impl<'r> FromRequest<'r> for Guard。
  2. 方法签名使用 &'r Request<'_>。
  3. 守卫结构体可包含 &'r str 借用字段。
  4. 请求结束后守卫值失效,借用不可再用。
  5. 跨请求保存时克隆为自有类型。

代码或图示

struct CookieRef<'r> { value: &'r str }

#[rocket::async_trait]
impl<'r> FromRequest<'r> for CookieRef<'r> {
    type Error = ();
    async fn from_request(req: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        match req.cookies().get("session") {
            Some(c) => Outcome::Success(CookieRef { value: c.value() }),
            None => Outcome::Forward(rocket::http::Status::Unauthorized),
        }
    }
}

常见误区

  • 把守卫中的 &'r str 存入全局状态:引用超过请求生命周期,编译报错。
  • 守卫结构体忘记带生命周期参数:trait 实现不匹配。

追问

  • 什么时候该克隆?答:值需要跨请求、跨任务保存时克隆为 String/Vec;仅本次请求使用可借用。
  • 0.5 守卫返回值是 async 构造,生命周期与 Future 如何配合?答:async_trait 包装后由框架调度;具体约束以版本文档签名为准。

04.4.5.1-041 为什么实现异步 trait 必须加 #[rocket::async_trait]?

一句话结论

Rust 稳定版对 async trait 方法有限制,Rocket 0.5 通过 rocket::async_trait 宏把异步方法改造为返回 Pin<Box<dyn Future>> 的形式,FromRequest、FromData 等异步 trait 实现都需要标注。

概念解释

0.5 切换异步模型后,trait 方法是 async。受限于编译器原生 async trait 支持,Rocket 提供基于 async-trait 的宏标注,让 impl 签名与 trait 匹配。漏加宏会导致签名不匹配编译错误。该宏只作用于 trait 实现,普通 async fn handler 不需要。

原理流程

  1. 编写 impl FromRequest,方法为 async。
  2. 在 impl 上标注 #[rocket::async_trait]。
  3. 宏改造方法返回类型为装箱 Future。
  4. 框架调用时调度该 Future。
  5. 编译期校验签名一致。

代码或图示

#[rocket::async_trait]
impl<'r> FromRequest<'r> for MyGuard {
    type Error = ();
    async fn from_request(req: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        Outcome::Success(MyGuard)
    }
}

常见误区

  • 在普通 async handler 上也加该宏:不需要,handler 是自由函数。
  • 用第三方 async_trait 替代:应使用 Rocket 重导出的宏,版本一致性以版本文档为准。

追问

  • FromData 实现也需要吗?答:需要,FromData 同样是异步 trait;标注规则与 FromRequest 一致。
  • 宏对性能有影响吗?答:装箱 Future 有少量开销;守卫路径通常不是热点,具体取舍按场景评估。

04.4.5.1-042 Fairing 与请求守卫有什么区别?

一句话结论

Fairing 是框架级钩子(监听请求/响应/启动/关机事件),面向流程横切;请求守卫是类型化参数,在 handler 前校验并产出进入 handler 的值。Fairing 不直接成为 handler 参数。

概念解释

两者都处理横切逻辑,但层级不同:Fairing 挂在 Rocket 应用上,对所有经过的请求/响应触发回调,适合日志、CORS、请求头注入;守卫按路由参数生效,结果绑定到 handler 变量。Rocket 0.5 的 Fairing trait 有 on_request、on_response 等钩子(具体名称以版本文档为准)。任务规范中提到的 Fairing 相关内容由 04.4.5.2 章节展开。

原理流程

  1. 应用注册 Fairing,框架在各生命周期触发回调。
  2. 请求到达 → Fairing on_request 钩子执行。
  3. 路由匹配 → 守卫依次构造。
  4. 响应返回 → Fairing on_response 钩子执行。
  5. Fairing 不产生 handler 参数,守卫产出参数值。

代码或图示

层级对比
├── Fairing:应用级钩子,请求/响应/启动/关机,无 handler 参数
├── 请求守卫:路由级类型参数,校验 + 产出值,进入 handler
├── 数据守卫:路由级 body 解析,FromData
└── 中间件:部分框架概念,Rocket 中由 Fairing 承担类似职责

常见误区

  • 用 Fairing 做需要把值传入 handler 的校验:Fairing 回调不产生参数,该需求应做守卫。
  • 在守卫里给所有响应统一加头:响应横切属于 Fairing 职责。

追问

  • Fairing 能短路请求吗?答:Fairing 钩子可修改请求/响应;是否支持直接拦截以版本文档为准,鉴权决策通常放守卫。
  • 两者如何配合?答:Fairing 做日志与通用头,守卫做认证授权并产出身份对象。

04.4.5.1-043 守卫中的异步操作(查库、验签)怎么写?

一句话结论

守卫方法本身是 async,可直接 .await 数据库查询、令牌验签等异步操作;通过 State 取得连接句柄,结果封装进守卫结构体,失败返回对应 Outcome。

概念解释

认证校验常依赖异步依赖:查用户表、校验 JWT 签名、查缓存会话。守卫 async 方法内可以正常 await,句柄从托管状态获取。注意守卫应保持轻量:复杂业务逻辑放 service 层,守卫只完成身份识别与授权判断。异步操作失败(库不可达)应区分内部错误与拒绝访问,避免把 5xx 误判成 401。

原理流程

  1. 守卫从请求提取凭证。
  2. 从 State 取数据库/缓存句柄。
  3. await 校验调用(查用户、验签)。
  4. 成功封装身份值;凭证无效返回 Error;依赖故障返回内部错误。
  5. 守卫值进入 handler。

代码或图示

#[rocket::async_trait]
impl<'r> FromRequest<'r> for AuthUser {
    type Error = AuthError;
    async fn from_request(req: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        let token = match bearer(req) {
            Some(t) => t,
            None => return Outcome::Error((Status::Unauthorized, AuthError::Missing)),
        };
        let state = req.guard::<State<AppState>>().await.ok();
        match verify(token, state.as_ref()).await {
            Ok(user) => Outcome::Success(user),
            Err(e) => Outcome::Error((Status::Unauthorized, AuthError::Invalid(e))),
        }
    }
}

常见误区

  • 守卫内做重业务计算:守卫路径被每个请求触发,重逻辑应下沉 service。
  • 依赖故障也返回 401:无法区分未认证与内部错误,监控失真。

追问

  • 守卫内 await 会阻塞其他请求吗?答:异步 await 让出工作线程,不会独占;阻塞同步调用才需要迁移阻塞线程池。
  • 验签失败与过期如何区分?答:错误枚举区分 Invalid、Expired,分别映射状态码与错误消息。

04.4.5.1-044 守卫失败的状态码如何自定义?

一句话结论

在 Outcome::Error 中携带自定义 Status(401/403/400 等),配合对应状态码 catcher 生成响应;错误类型值由 Error 关联类型定义,可携带失败原因。

概念解释

守卫失败的 HTTP 状态由 Error 携带的状态码决定。认证失败用 401,权限不足用 403,请求格式问题用 400/422。状态码选择遵循 HTTP 语义,错误枚举在守卫内区分场景。catcher 按状态码注册,保证响应体结构统一。需要 handler 自定义响应时,用 Result 包装守卫参数在内部处理。

原理流程

  1. 守卫识别失败场景(缺凭证/无效/无权限)。
  2. 映射为对应 Status 与错误值。
  3. 返回 Error((status, error_value))。
  4. Rocket 按状态码找 catcher。
  5. catcher 输出统一错误响应。

代码或图示

Outcome::Error((Status::Unauthorized, AuthError::MissingToken))
// 或
Outcome::Error((Status::Forbidden, AuthError::NotAdmin))

常见误区

  • 所有守卫失败都返回 401:权限不足应是 403,语义不同。
  • Error 不带错误类型值:catcher 与日志无法区分失败原因。

追问

  • 状态码可以用自定义数字吗?答:使用 Status 常量或合法 HTTP 状态码;非标准状态的兼容性按规范评估。
  • 如何返回 JSON 错误体?答:catcher 返回实现 Responder 的 JSON 类型;见 04.4.5.1-082。

04.4.5.1-045 守卫如何复用与组合(两个守卫类型合并)?

一句话结论

复用方式:基础守卫产出身份值,高级守卫在其基础上再校验;组合类型内部嵌套基础守卫,或在同一守卫内完成多步检查,避免重复解析凭证。

概念解释

认证与授权常分层:User 守卫识别登录身份,AdminUser 守卫在用户基础上检查角色。组合实现可以让高级守卫内部调用基础守卫逻辑,或把基础身份作为字段嵌入高级守卫。复用避免令牌解析、用户查询重复执行。守卫组合也是类型化策略集中管理的方式:权限规则随类型走。

原理流程

  1. 定义基础守卫(如 User)完成认证。
  2. 定义高级守卫(如 AdminUser),内嵌 User 或复用其校验逻辑。
  3. 高级守卫检查角色/权限。
  4. 成功返回高级守卫值,失败返回对应 Error。
  5. handler 参数使用高级守卫类型。

代码或图示

struct AdminUser { user: User }

#[rocket::async_trait]
impl<'r> FromRequest<'r> for AdminUser {
    type Error = AuthError;
    async fn from_request(req: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        let user = match User::from_request(req).await {
            Outcome::Success(u) => u,
            Outcome::Error((s, e)) => return Outcome::Error((s, e)),
            Outcome::Forward(f) => return Outcome::Forward(f),
        };
        if user.is_admin() {
            Outcome::Success(AdminUser { user })
        } else {
            Outcome::Error((Status::Forbidden, AuthError::NotAdmin))
        }
    }
}

常见误区

  • 高级守卫重复解析凭证:应复用基础守卫结果。
  • 组合守卫忘记处理 Forward 分支:转发语义被错误转为 Error。

追问

  • 多个独立守卫能合并成一个结构体吗?答:可以,定义复合守卫一次产出多个值;适合经常同时出现的校验组合。
  • 守卫复用需要继承机制吗?答:Rust 用结构体组合与 trait 复用,不依赖面向对象继承。

04.4.5.1-046 自定义 Token 守卫的完整实现步骤是什么?

一句话结论

步骤:定义守卫结构体与错误枚举 → 实现 FromRequest 提取 Bearer/查询令牌 → 验签并查用户 → 成功返回身份值,失败返回 401/403 Outcome → 在 handler 参数中使用。

概念解释

Token 守卫是最常见的自定义守卫。流程覆盖凭证提取、校验、身份封装三阶段。凭证来源可以是 Authorization: Bearer 头、Cookie 或查询参数(查询令牌应短期有效)。验签依赖状态中的密钥或缓存会话。守卫结构体持有用户 ID 与角色等身份信息,供 handler 使用。错误枚举区分缺失、无效、过期、无权限。

原理流程

  1. 定义 AuthUser 守卫与 AuthError 枚举。
  2. from_request 读取认证头提取令牌。
  3. 从 State 取密钥/缓存,await 验签与用户查询。
  4. 成功封装 AuthUser;失败按场景返回 Error 状态码。
  5. handler 参数使用 AuthUser。

代码或图示

struct AuthUser { id: u64, role: String }

#[rocket::async_trait]
impl<'r> FromRequest<'r> for AuthUser {
    type Error = AuthError;
    async fn from_request(req: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        let token = req.headers().get_one("authorization")
            .and_then(|h| h.strip_prefix("Bearer "))
            .ok_or(AuthError::Missing).ok()?;
        let claims = verify_jwt(token).await.map_err(|_| AuthError::Invalid)?;
        Outcome::Success(AuthUser { id: claims.sub, role: claims.role })
    }
}

#[rocket::get("/me")]
fn me(user: AuthUser) -> String { format!("{}:{}", user.id, user.role) }

常见误区

  • 守卫只校验令牌存在不验签:伪造令牌可通过。
  • 把原始令牌存进守卫结构体:只保留解析后的身份标识。

追问

  • 令牌放查询参数怎么处理?答:从 URI 查询提取,使用短期订阅令牌;安全约束见 04.4.3.3-033 同类讨论。
  • 守卫如何拿到数据库池?答:通过 State<AppState> 访问托管状态,池句柄克隆后使用。

04.4.5.1-047 权限守卫(AdminUser)如何基于用户守卫扩展?

一句话结论

AdminUser 内部复用 User 守卫完成认证,再检查角色/权限字段;通过校验返回嵌入用户身份的管理员值,无权限返回 403,未登录返回基础守卫的 401 流程。

概念解释

权限守卫建立在认证之上:先确认“是谁”,再判断“能不能”。复用 User 守卫避免重复查用户表。角色判断可以基于用户字段、权限集或服务层鉴权方法。返回的 AdminUser 可暴露用户信息与管理员操作所需上下文。Forward/Error 分支要透传基础守卫结果,不丢失原始状态码。

原理流程

  1. AdminUser::from_request 内部调用 User::from_request。
  2. 处理 Success/Error/Forward 三态。
  3. 检查用户角色是否满足管理员条件。
  4. 满足 → 封装 AdminUser;不满足 → 403 Error。
  5. handler 使用 AdminUser 作为参数。

代码或图示

struct AdminUser { user: User }

impl AdminUser {
    fn require_admin(user: User) -> Result<Self, AuthError> {
        if user.role == "admin" { Ok(AdminUser { user }) }
        else { Err(AuthError::NotAdmin) }
    }
}

常见误区

  • 权限守卫自己重新解析令牌:认证逻辑重复,易与基础守卫不一致。
  • 无权限返回 401:已认证但缺权限应为 403。

追问

  • 细粒度权限怎么做?答:守卫检查权限集(如 manage:users),或在 service 层按资源与动作鉴权;守卫适合粗粒度策略。
  • 管理员信息需要额外查询吗?答:可在基础用户值上扩展;需要补充资料时在守卫内 await 查询,结果缓存进状态。

04.4.5.1-048 Language / Accept-Language 守卫怎么写?

一句话结论

从 Accept-Language 头解析首选语言,封装为 Locale 守卫;无法识别时回退默认语言,语言列表从配置读取,handler 按守卫值选择文案与格式化。

概念解释

语言守卫是典型的非认证类守卫:读取请求头,解析出偏好语言,提供给 handler 做本地化。解析规则按语言标签(如 zh-CN、en)匹配支持列表,质量值(q)排序可选实现。守卫返回 Option<Locale> 或固定默认值,避免不支持的语言导致请求失败。语言偏好也可结合 Cookie 覆盖请求头。

原理流程

  1. 定义 Locale 守卫与支持语言列表(State 配置)。
  2. from_request 读取 Accept-Language 头。
  3. 解析语言标签,按支持列表匹配。
  4. 命中返回对应 Locale;未命中回退默认。
  5. handler 用守卫值选择响应文案。

代码或图示

struct Locale(String);

#[rocket::async_trait]
impl<'r> FromRequest<'r> for Locale {
    type Error = ();
    async fn from_request(req: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        let lang = req.headers().get_one("accept-language")
            .and_then(|h| h.split(',').next())
            .unwrap_or("zh-CN");
        let supported = ["zh-CN", "en"];
        let picked = supported.iter().find(|s| lang.starts_with(*s))
            .copied().unwrap_or("zh-CN");
        Outcome::Success(Locale(picked.to_string()))
    }
}

常见误区

  • 直接采用头里任意语言:未校验支持列表,可能产生未翻译文案。
  • 不支持的语言返回 Error:本地化偏好不应阻断请求,应回退默认。

追问

  • Cookie 语言偏好如何优先?答:先读 Cookie,缺失再读头;两者都无则默认。
  • 语言守卫需要异步操作吗?答:纯头解析可同步完成;异步 trait 方法内不 await 即可。

04.4.5.1-049 ApiKey 守卫(请求头校验)示例怎么写?

一句话结论

从自定义头(如 x-api-key)提取密钥,与配置或缓存中的有效密钥比对;匹配返回守卫值,缺失或不匹配返回 401,密钥不落日志。

概念解释

ApiKey 守卫用于服务间调用或开放接口认证。密钥通常在配置、数据库或缓存中校验,而非硬编码。守卫提取头值后做常量时间比较避免时序侧信道(具体比较工具按需引入)。失败区分缺失与无效两类错误。ApiKey 适合机器调用,用户会话仍走 Token/Cookie 体系。

原理流程

  1. 定义 ApiKey(String) 守卫与错误类型。
  2. 读取 x-api-key 头。
  3. 从 State 取有效密钥集合/缓存,await 校验。
  4. 匹配 → Success;不匹配 → 401 Error。
  5. handler 参数使用守卫类型。

代码或图示

struct ApiKey(String);

#[rocket::async_trait]
impl<'r> FromRequest<'r> for ApiKey {
    type Error = ApiKeyError;
    async fn from_request(req: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        let key = req.headers().get_one("x-api-key")
            .ok_or(ApiKeyError::Missing).ok()?;
        let state = req.guard::<State<AppState>>().await.ok()?;
        if state.valid_keys.contains(key) {
            Outcome::Success(ApiKey(key.to_string()))
        } else {
            Outcome::Error((Status::Unauthorized, ApiKeyError::Invalid))
        }
    }
}

常见误区

  • 密钥写死在守卫代码里:应来自配置或托管状态。
  • 日志打印完整密钥:记录前缀或哈希即可。

追问

  • 常量时间比较怎么做?答:使用专门的比较工具 crate 避免时序泄露;具体依赖按项目安全要求引入。
  • ApiKey 权限范围如何控制?答:密钥绑定权限集,守卫解析出 scope,handler 或 service 按 scope 鉴权。

一句话结论

从会话 Cookie 读取会话标识,查询服务端会话存储得到用户身份;Cookie 的 HttpOnly/Secure/SameSite 属性在配置侧保证,守卫校验会话有效性与过期时间。

概念解释

Cookie 会话守卫与 Token 守卫流程类似,凭证载体是 Cookie。要点:会话标识服务端可查(内存/Redis/DB),过期与续签在存储层判断;私有 Cookie 需要解密密钥配置。守卫不应信任 Cookie 中的用户字段,只认服务端会话记录。Cookie 安全属性由框架配置与响应写入逻辑保证,守卫聚焦身份校验。

原理流程

  1. 读取会话 Cookie 值。
  2. 从 State 取会话存储句柄。
  3. await 查询会话,校验存在且未过期。
  4. 成功返回身份守卫;不存在/过期返回 401。
  5. handler 使用身份值。

代码或图示

#[rocket::async_trait]
impl<'r> FromRequest<'r> for SessionUser {
    type Error = AuthError;
    async fn from_request(req: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        let cookie = req.cookies().get("session")
            .ok_or(AuthError::Missing).ok()?;
        let state = req.guard::<State<AppState>>().await.ok()?;
        match state.sessions.find(cookie.value()).await {
            Some(user) => Outcome::Success(SessionUser { user }),
            None => Outcome::Error((Status::Unauthorized, AuthError::Expired)),
        }
    }
}

常见误区

  • 信任 Cookie 里存的角色字段:身份以服务端会话记录为准。
  • 会话不过期:登录态长期有效,泄露风险高。

追问

  • 私有 Cookie 怎么读取?答:通过配置密钥解密;Cookies API 的私有/普通区分以版本文档为准。
  • 会话续签在哪里做?答:会话临近过期时在响应侧续签 Cookie;守卫只负责校验当前有效性。

04.4.5.1-051 守卫内如何校验 Bearer 令牌签名?

一句话结论

从 Authorization: Bearer <token> 提取令牌,使用状态中的密钥或 JWKS 验签并解析 claims,校验过期时间与签发方;验签通过才封装身份,签名无效或过期返回 401。

概念解释

Bearer 令牌校验分三步:提取、验签、 claims 校验。验签依赖算法与密钥(对称 HMAC 或非对称公钥),密钥从托管状态读取,不硬编码。claims 校验包括 exp 过期、iss 签发方、必要受众。具体 JWT 库与 API 以项目依赖版本为准;守卫内只做校验与身份提取,不解析业务权限细节。

原理流程

  1. 读取认证头,剥离 Bearer 前缀。
  2. 从 State 取验签密钥/公钥集。
  3. await 验签并解码 claims。
  4. 校验过期、签发方等声明。
  5. 成功返回身份守卫;失败按原因返回 401。

代码或图示

# async fn verify(token: &str) -> Result<Claims, AuthError> { Ok(Claims { sub: 1, role: "user".into() }) }

#[rocket::async_trait]
impl<'r> FromRequest<'r> for AuthUser {
    type Error = AuthError;
    async fn from_request(req: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        let token = req.headers().get_one("authorization")
            .and_then(|h| h.strip_prefix("Bearer "))
            .ok_or(AuthError::Missing).ok()?;
        match verify(token).await {
            Ok(claims) => Outcome::Success(AuthUser { id: claims.sub, role: claims.role }),
            Err(e) => Outcome::Error((Status::Unauthorized, e)),
        }
    }
}

常见误区

  • 只解码不验签:JWT 可被伪造,解码不等于校验。
  • 把密钥写进守卫源码:密钥来自配置或托管状态。

追问

  • 过期令牌与无效签名如何区分?答:错误枚举区分 Expired 与 Invalid,响应消息与日志分别记录。
  • 非对称验签公钥从哪来?答:配置本地公钥或通过 JWKS 端点获取并缓存;刷新机制按安全策略设计。

04.4.5.1-052 守卫返回 401 与 403 如何分工?

一句话结论

401 用于未认证(缺凭证、凭证无效或过期),403 用于已认证但权限不足;守卫先认证再鉴权,两个状态码对应不同校验阶段与错误枚举。

概念解释

状态码语义与 axum 章节一致:身份不明走 401,身份明确但无权走 403。守卫实现上,认证守卫失败返回 401,权限守卫在认证通过后失败返回 403。前端拦截器通常只在 401 时跳转登录,403 提示无权限;混用会导致错误的客户端行为。错误消息也应区分:未登录 vs 无权限。

原理流程

  1. 认证守卫校验凭证有效性。
  2. 失败 → 401 Error(缺失/无效/过期)。
  3. 认证通过后,权限守卫检查角色或资源权限。
  4. 不足 → 403 Error。
  5. 对应 catcher 返回区分文案的错误体。

代码或图示

// 认证阶段
Outcome::Error((Status::Unauthorized, AuthError::Invalid))
// 授权阶段
Outcome::Error((Status::Forbidden, AuthError::NotAdmin))

常见误区

  • 已登录用户访问受限资源返回 401:应是 403。
  • 匿名访问返回 403:应先 401 完成认证。

追问

  • 401 需要带 WWW-Authenticate 头吗?答:按认证方案可选;Rocket 响应头写入方式以版本文档为准。
  • 接口同时需要登录与角色,守卫顺序怎么排?答:认证守卫在前,权限守卫在后,保证 401 先于 403 触发。

04.4.5.1-053 守卫如何做基础版频率限制?

一句话结论

守卫内按用户/IP 维护滑动窗口或计数器,超限返回 429;计数器放在托管状态中,配合锁或原子类型保证并发安全,阈值与窗口从配置读取。

概念解释

频率限制是守卫可承担的横切策略:识别调用方(用户 ID 或 IP),在状态存储中记录窗口内请求次数,超限拒绝。基础实现用内存计数器,分布式场景需 Redis 等共享存储。守卫内只做计数与判断,不记录业务日志细节。429 响应可带 Retry-After 提示;具体响应头支持以版本文档为准。

原理流程

  1. 从守卫身份或请求 IP 取调用方标识。
  2. 从 State 取限计数器存储。
  3. 滑动窗口计数,判断是否超限。
  4. 未超限放行;超限返回 429 Error。
  5. 计数数据随状态生命周期管理。

代码或图示

# struct RateState { hits: std::collections::HashMap<String, Vec<std::time::Instant>> }
#[rocket::async_trait]
impl<'r> FromRequest<'r> for RateLimited {
    type Error = ();
    async fn from_request(req: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        let state = req.guard::<State<AppState>>().await.ok()?;
        let key = client_key(req);
        if state.rate_exceeded(&key) {
            Outcome::Error((Status::TooManyRequests, ()))
        } else {
            Outcome::Success(RateLimited)
        }
    }
}

常见误区

  • 计数器用无锁 HashMap 直接并发写:数据竞争,需要锁或并发结构。
  • 内存计数在多实例下不准:分布式限流需共享存储。

追问

  • 滑动窗口怎么实现?答:记录时间戳列表,清理窗口外记录后计数;固定窗口实现更简单但边界粗糙。
  • 限流失败算守卫 Error 还是 Forward?答:明确拒绝,返回 Error 429。

04.4.5.1-054 多租户上下文守卫如何按子域或请求头提取?

一句话结论

守卫从子域、自定义头或路径段解析租户标识,校验租户存在与状态,封装为 TenantContext 供 handler/service 使用;租户句柄从状态获取,无效租户返回 404/403。

概念解释

多租户系统需要在请求早期确定租户上下文。来源可以是子域(acme.app.com)、X-Tenant 头或路径前缀。守卫解析后校验租户是否存在、是否启用,把租户 ID 与配置放入上下文。后续数据库查询、缓存键都基于该上下文隔离。租户解析失败要区分“租户不存在”与“无权访问”。

原理流程

  1. 定义 TenantContext { id, config } 守卫。
  2. 从请求子域/头/路径提取租户标识。
  3. 从 State 取租户存储,await 校验存在与状态。
  4. 成功封装上下文;不存在返回对应错误。
  5. handler 与 service 使用上下文隔离数据。

代码或图示

struct TenantContext { tenant_id: String }

#[rocket::async_trait]
impl<'r> FromRequest<'r> for TenantContext {
    type Error = TenantError;
    async fn from_request(req: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        let host = req.host().unwrap_or("");
        let sub = host.split('.').next().unwrap_or("");
        let state = req.guard::<State<AppState>>().await.ok()?;
        match state.tenants.find(sub).await {
            Some(t) => Outcome::Success(TenantContext { tenant_id: t.id }),
            None => Outcome::Error((Status::NotFound, TenantError::Unknown)),
        }
    }
}

常见误区

  • 租户标识只在 handler 内解析:各接口重复逻辑,易遗漏隔离。
  • 信任客户端传入的租户 ID 不校验:越权访问其他租户数据。

追问

  • 子域解析在本地开发怎么办?答:开发环境可用头或固定子域映射;配置按环境区分。
  • 租户上下文如何传到数据库层?答:作为参数或请求上下文传递,查询与缓存键带上租户 ID。

04.4.5.1-055 守卫错误类型如何设计?

一句话结论

错误枚举覆盖守卫可预期的失败场景(缺失、无效、过期、无权限、限流),每个变体携带必要上下文;实现 Display 与必要的错误链,状态码在 Outcome 映射处集中选择。

概念解释

守卫错误类型与业务错误分层一致:枚举表达场景,thiserror 派生标准 Error 实现,消息面向日志与响应。错误值可被 handler 的 Result 捕获,也供 catcher 生成提示。设计时区分客户端错误(4xx)与内部错误(5xx),避免把依赖故障包装成认证失败。错误变体稳定后不要随意改名,便于日志聚合。

原理流程

  1. 列出守卫失败场景,定义枚举变体。
  2. 用 #[error("...")] 派生 Display 与 source。
  3. 守卫内按场景构造错误值。
  4. Outcome 映射状态码。
  5. catcher/handler 按错误类型生成响应。

代码或图示

#[derive(Debug, thiserror::Error)]
pub enum AuthError {
    #[error("缺少认证凭证")]
    Missing,
    #[error("凭证无效")]
    Invalid,
    #[error("凭证已过期")]
    Expired,
    #[error("权限不足")]
    NotAdmin,
}

常见误区

  • 错误枚举只放状态码:丢失失败原因,日志与提示无法区分。
  • 把内部依赖错误直接作为守卫错误:应先分类映射。

追问

  • 错误类型需要实现 Responder 吗?答:不强制;状态码在 Outcome 选择,响应体由 catcher 或 handler 生成。需要直接返回错误时再实现 Responder。
  • 多守卫共享错误类型还是各自定义?答:同一认证域共享枚举;跨域守卫可独立定义,避免变体膨胀。

04.4.5.1-056 守卫与 Sentinel 机制是什么关系?

一句话结论

Sentinel 是 Rocket 0.5 的启动期自检机制:依赖特定托管状态、catcher 等前置条件的类型实现 Sentinel,条件不满足时中止启动;守卫可以借助 Sentinel 把运行期前置条件检查提前到启动期。

概念解释

普通守卫在请求到达时才发现状态缺失;Sentinel 在应用启动阶段就检查类型依赖的条件。例如 State<T> 守卫是 Sentinel,T 未托管时启动即报错。自定义守卫若依赖必须存在的配置或 catcher,可实现 Sentinel 做启动校验。这样把配置错误从运行期故障提前到部署期暴露。

原理流程

  1. 类型实现 Sentinel,声明检查条件。
  2. Rocket 启动期遍历路由中的类型,调用检查。
  3. 条件缺失 → 中止启动并输出诊断。
  4. 条件满足 → 正常进入服务监听。
  5. 请求期守卫按正常流程构造。

代码或图示

// Sentinel trait 方法与检查方式以 Rocket 当前版本文档为准
// 依赖托管状态的守卫可借助 State<T> 内置的 Sentinel 检查

常见误区

  • 以为守卫错误只会在请求时暴露:关键前置条件应通过 Sentinel 提前检查。
  • 自定义守卫依赖必选状态却不做启动校验:线上首个请求才报错。

追问

  • Sentinel 检查哪些典型条件?答:托管状态类型、已注册 catcher、必要配置等;完整列表以版本文档为准。
  • Sentinel 与启动期路由校验是同一阶段吗?答:都在 launch 阶段执行,Sentinel 补充类型级条件检查。

04.4.5.1-057 守卫如何在测试中构造?

一句话结论

测试通过本地客户端发请求,在请求头/Cookie/查询中带上测试凭证;守卫逻辑可单独调用 from_request 或通过集成测试覆盖通过与拒绝两条路径。

概念解释

守卫测试分两层:单元层直接构造 Request 或调用守卫实现,校验 Outcome 分支;集成层用 Rocket 测试客户端发真实请求,断言状态码与响应体。测试状态(用户表、密钥、缓存)注入托管状态。凭证按守卫约定放入对应位置(头、Cookie、查询)。拒绝路径要覆盖缺失、无效、无权限等变体。

原理流程

  1. 构造测试 Rocket 实例,注入测试状态。
  2. 测试客户端发起带凭证的请求。
  3. 断言通过路径的响应与守卫值效果。
  4. 分别构造缺失/无效/越权请求,断言错误状态码。
  5. 必要时直接调用 from_request 覆盖边界分支。

代码或图示

# #[rocket::async_test]
# async fn auth_test() {
# let rocket = rocket::build().manage(test_state());
# let client = rocket::local::asynchronous::Client::tracked(rocket).await.unwrap();
// 带 Authorization 头请求 /me,断言 200;无凭证请求断言 401
# }

常见误区

  • 只测通过路径:拒绝分支未覆盖,回归风险高。
  • 测试用生产密钥或真实用户:应使用隔离的测试状态与凭证。

追问

  • 如何直接测试 Outcome 三态?答:构造 Request 引用调用 from_request,匹配 Success/Error/Forward;Request 构造方式以版本文档为准。
  • 守卫依赖数据库怎么测?答:注入内存替身或测试库,避免依赖外部服务。

04.4.5.1-058 守卫中执行业务副作用有哪些常见误用?

一句话结论

守卫职责是校验与提取,不应执行业务写入、消息发送、计量扣费等副作用;副作用应放在 handler 或 service 层,避免守卫被转发/重试时重复执行。

概念解释

守卫可能在路由匹配链中被多次构造(Forward 场景),且每个请求触发一次。把写操作放守卫会导致重复执行、事务边界不清、错误处理困难。正确分层:守卫识别身份与权限,handler 调用 service 完成业务动作,副作用在 service 事务内管理。读操作(查用户、查配置)在守卫内是可接受的校验支撑。

原理流程

  1. 区分守卫内允许的读校验与禁止的写副作用。
  2. 认证/授权判断留在守卫。
  3. 业务写入、发消息、计费移入 service。
  4. handler 编排调用 service。
  5. 重试/转发场景下副作用不重复触发。

代码或图示

守卫内可以
├── 读取凭证与请求元信息
├── 查询用户/配置做校验
└── 封装身份上下文

守卫内避免
├── 写数据库/发消息/扣费
├── 启动后台任务
└── 修改全局业务状态

常见误区

  • 在守卫里记录访问日志:日志横切更适合 Fairing。
  • 守卫内累加业务计数:计数属于业务副作用,应在 service 层。

追问

  • 守卫内查用户表算副作用吗?答:只读查询属于校验支撑,可接受;查询结果应缓存或按需优化。
  • 必须在鉴权阶段做的动作怎么办?答:只读校验可以;需要落库的决策记录放到 handler 事务内。

04.4.5.1-059 什么是 data guard(数据守卫)?

一句话结论

数据守卫是实现 FromData<'r> 的类型,负责从请求 body 解析出 handler 参数;通过路由属性 data = "<param>" 声明,Rocket 在守卫通过后读取并解析 body。

概念解释

与请求守卫对应,data guard 面向请求体:Json<T>、Form<T>、TempFile、ByteStream 都是内置数据守卫。FromData 接收请求与 Data<'r>(body 句柄),返回 Outcome<Self>。body 只能被消费一次,因此一条路由只有一个 data 参数。自定义 body 类型可实现 FromData。

原理流程

  1. 路由属性声明 data = "<name>"。
  2. 请求守卫通过后,框架读取 body。
  3. 调用数据守卫的 from_data 解析。
  4. Success 解包值交给 handler;Error 进入错误流程;Forward 转下一路由。
  5. body 解析失败可用 Result 参数捕获。

代码或图示

#[rocket::post("/items", data = "<item>")]
fn create(item: rocket::serde::json::Json<Item>) { /* ... */ }

常见误区

  • data 参数不在 data 属性声明:被当作请求守卫检查,类型不匹配报错。
  • 注册两个 body 参数:body 只能消费一次。

追问

  • FromData 是异步 trait 吗?答:是,0.5 中实现需标注 #[rocket::async_trait];签名以版本文档为准。
  • 数据守卫与表单守卫什么关系?答:Form<T> 既是 data guard 也可作为表单字段守卫;FromForm 是表单解析 trait。

04.4.5.1-060 data = "<param>" 如何声明 body 参数?

一句话结论

在路由宏参数中写 data = "<参数名>",handler 内同名参数类型实现 FromData;参数名与属性声明一致,框架据此把 body 解析结果绑定到该参数。

概念解释

data 是路由元数据的一部分,与路径、查询声明并列。它告诉 Rocket 哪个 handler 参数消费 body。未声明 data 的 body 类型参数不会被识别为数据守卫。data 值是参数名字符串,不是类型名;类型由 Rust 类型系统检查。

原理流程

  1. 路由宏添加 data = "<param>"。
  2. 启动期校验同名参数存在且实现 FromData。
  3. 请求读取 body,调用 from_data。
  4. 解析成功绑定参数。
  5. 解析失败走 Outcome 错误流程。

代码或图示

#[rocket::put("/items/<id>", data = "<payload>")]
fn update(id: u64, payload: rocket::serde::json::Json<UpdateItem>) { /* ... */ }

常见误区

  • data 里写类型名:应写 handler 参数名。
  • 省略 data 导致 body 未被读取:请求体被忽略,handler 拿到守卫类型检查结果。

追问

  • 一条路由可以声明多个 data 吗?答:body 只能消费一次,一个路由一个 data 参数;多部分结构在单个表单/JSON 内组织。
  • data 参数可以是可选的吗?答:用 Option<T> 或 Result<T, E> 包装处理缺失与失败;具体支持以版本文档为准。

04.4.5.1-061 Json<T> 数据守卫的 feature、解析与响应行为是什么?

一句话结论

Json<T> 位于 rocket::serde::json,需要 json feature;接收时反序列化 T: Deserialize,响应时序列化 T: Serialize 并自动设置 application/json。

概念解释

Json 是双向类型:作为 data guard 解析请求 JSON,作为 responder 输出 JSON。接收时 body 解析为 T,失败返回 JSON 解析错误;format = "json" 可额外约束 Content-Type。Rocket 重导出 serde trait 与 derive,结构体可标注 #[serde(crate = "rocket::serde")],或直接依赖 serde crate。

原理流程

  1. 启用 json feature,导入 rocket::serde::json::Json。
  2. 请求 body 按 JSON 解析为 T。
  3. 解析失败 → data Outcome Error,可被 Result 捕获。
  4. handler 返回 Json<T>,序列化并设置媒体类型。
  5. 响应发送客户端。

代码或图示

use rocket::serde::json::Json;
use serde::Deserialize;

#[derive(Deserialize)]
struct Item { name: String }

#[rocket::post("/items", data = "<item>")]
fn create(item: Json<Item>) -> Json<serde_json::Value> {
    Json(serde_json::json!({"ok": true, "name": item.name}))
}

常见误区

  • 未启用 json feature 就导入 Json:类型不可用,编译报错。
  • 结构体 derive 未标注 crate 重导出:0.5 中需要 #[serde(crate = "rocket::serde")] 或直接依赖 serde。

追问

  • JSON 解析失败返回什么状态码?答:由 Json 守卫的 FromData 实现决定,通常为 422/400 类错误;具体状态码以当前版本文档为准。
  • Json<T> 能作为表单字段守卫吗?答:可以,0.5 中 Json 同时实现表单字段守卫,用于嵌套 JSON 表单字段。

04.4.5.1-062 Form<T> 与 FromForm derive 怎么用?

一句话结论

Form<T> 是表单数据守卫,T 派生 FromForm;支持 urlencoded 表单与 multipart,字段名与表单键对应,解析与校验错误由 Errors 收集。

概念解释

Rocket 0.5 表单体系基于 FromForm derive:结构体字段自动映射表单键,支持嵌套、集合、可选字段与校验属性。Form<T> 作为 data guard 接收整体表单;表单字段级类型可实现 FromFormField。解析错误聚合为 Errors,可用 Result<Form<T>, Errors> 捕获后重渲染或返回错误。

原理流程

  1. 结构体派生 FromForm,字段对应表单键。
  2. 路由声明 data = "<form>",参数类型 Form<T>。
  3. 框架解析 urlencoded/multipart body。
  4. 字段绑定与校验,错误收集到 Errors。
  5. 成功绑定 handler;失败走错误或 Result 分支。

代码或图示

use rocket::form::{Form, FromForm};

#[derive(FromForm)]
struct Login<'r> {
    username: &'r str,
    password: String,
}

#[rocket::post("/login", data = "<form>")]
fn login(form: Form<Login<'_>>) -> String {
    format!("hello {}", form.username)
}

常见误区

  • 用 Json 守卫接收表单 body:Content-Type 与解析格式不匹配。
  • 表单字段名与结构体字段不一致:绑定失败,检查重命名属性。

追问

  • 表单校验怎么写?答:#[field(validate = ...)] 属性配合校验函数;内置校验规则以版本文档为准。
  • multipart 表单怎么接收文件?答:表单字段类型用 TempFile,见 04.4.5.1-064。

04.4.5.1-063 表单嵌套、集合与 multipart 上传如何组织?

一句话结论

FromForm 支持嵌套结构体、Vec/HashMap 等集合与 multipart 文件字段;嵌套类型同样派生 FromForm,集合按重复键或索引键绑定,文件字段用 TempFile。

概念解释

复杂表单在 0.5 中由 derive 自动处理:嵌套字段用点号或嵌套结构表达,集合接收重复键与索引键,multipart 每个部分映射为字段。表单上下文 Context 与 Errors 保留字段级错误,便于回显。设计表单结构时与前端字段命名约定对齐,避免索引键解析问题。

原理流程

  1. 定义外层表单结构,嵌套子结构与集合字段。
  2. 子结构派生 FromForm,集合字段标注类型。
  3. multipart 部分按字段名绑定,文件部分进 TempFile。
  4. 解析收集字段错误。
  5. handler 使用绑定后的结构。

代码或图示

#[derive(FromForm)]
struct Profile<'r> {
    nickname: &'r str,
    tags: Vec<String>,
    avatar: Option<TempFile<'r>>,
}

#[rocket::post("/profile", data = "<p>")]
fn update(p: Form<Profile<'_>>) { /* ... */ }

常见误区

  • 集合字段接收重复键却声明标量类型:绑定失败。
  • multipart 字段名与结构体字段不一致:文件/字段丢失。

追问

  • 嵌套表单键怎么命名?答:按 Rocket 表单命名规则(点号/索引);具体格式以版本文档为准。
  • 表单错误如何回显?答:Errors 携带字段路径与消息,handler 可重渲染表单或返回结构化错误。

04.4.5.1-064 TempFile 上传流程与 persist_to/copy_to 怎么用?

一句话结论

TempFile 把上传流直接写入临时文件;persist_to 持久化移动到正式路径,copy_to 复制一份保留临时文件;句柄 drop 时未持久化的临时文件自动删除。

概念解释

TempFile 是数据与表单字段守卫,流式落盘避免内存缓冲。上传过程中数据写入系统临时目录,大小受 limits.file 限制。业务校验通过后调用 persist_to 移动到永久位置;需要保留临时副本时用 copy_to。未持久化的文件在 TempFile 句柄 drop 时清理。路径与目录权限在部署环境保证。

原理流程

  1. 路由 data 参数或表单字段类型为 TempFile。
  2. body 流式写入临时文件,累计大小受限制。
  3. handler 校验文件类型、大小、内容。
  4. 调用 persist_to 移动到正式路径,或 copy_to 复制。
  5. 句柄结束时未持久化文件自动删除。

代码或图示

use rocket::fs::TempFile;

#[rocket::post("/upload", data = "<file>")]
async fn upload(mut file: TempFile<'_>) -> std::io::Result<()> {
    file.persist_to("/var/www/uploads/avatar.png").await?;
    Ok(())
}

常见误区

  • 上传后忘记 persist:临时文件随 drop 删除,正式位置无文件。
  • 临时目录与正式目录跨文件系统:persist_to 移动行为可能退化为复制;具体实现以版本文档为准。

追问

  • persist_to 与 copy_to 区别?答:前者移动并清理临时文件,后者复制且临时文件仍由句柄管理。
  • 如何获取文件名与大小?答:TempFile 提供文件名、长度等访问方法;具体 API 以当前版本文档为准。

04.4.5.1-065 TempFile 的大小限制 limits.file 如何配置?

一句话结论

文件大小限制通过 Rocket 配置 limits.file(可按扩展名 limits.file/$ext 细分),默认值约 1MiB;超限在流式写入阶段中止并返回错误,配置在 Rocket 配置文件或启动参数中设置。

概念解释

限制体系按类别配置 body 与文件上限,文件类别支持按扩展名覆盖。超限后 TempFile 守卫返回错误,handler 可用 Result 捕获。上传接口需要放大文件限制时,按扩展名分别配置,避免整体上限过松。配置值单位与写法以当前版本文档为准;默认值随版本可能调整。

原理流程

  1. 在 Rocket 配置中设置 limits.file 基础上限。
  2. 按扩展名配置 limits.file/$ext 覆盖值。
  3. 上传流式写入时累计字节数。
  4. 超限 → 中止写入,数据守卫返回 Error。
  5. 错误经 catcher 或 Result 分支响应。

代码或图示

# Rocket 配置示例;键名与单位写法以当前版本文档为准
[default.limits]
file = "10MiB"
file.png = "5MiB"
file.pdf = "20MiB"

常见误区

  • 只在 handler 里检查文件大小:超限数据已流入临时文件,限制应在守卫层生效。
  • 忘记按扩展名细分:大图被通用上限拒绝,或文档上限过松。

追问

  • 非文件 body 的限制在哪里配?答:同样在 limits 配置体系,按类别(表单、JSON 等)设置;类别名以版本文档为准。
  • 超限返回什么状态码?答:由数据守卫错误实现映射;具体状态码以版本文档为准,可在 catcher 定制。

04.4.5.1-066 ByteStream 如何流式接收 body?

一句话结论

ByteStream 是原始字节流数据守卫,把请求 body 暴露为字节流供逐块消费;适合自定义解析、代理转发或大文件流式处理,具体类型路径与方法以版本文档为准。

概念解释

与 TempFile 落盘、Json 结构化解析不同,ByteStream 保留原始字节流。handler 逐块读取并处理:计算哈希、转发到下游、边解析边落盘。流消费方式遵循异步迭代;body 大小仍受配置限制。Rocket 0.5 中 Data<'r> 是更原始的 body 句柄,ByteStream 是其流式封装之一。

原理流程

  1. 路由声明 data 参数类型 ByteStream。
  2. 框架把 body 句柄包装为流。
  3. handler 异步迭代字节块。
  4. 逐块处理(校验、转发、落盘)。
  5. 流结束完成请求。

代码或图示

#[rocket::post("/raw", data = "<stream>")]
async fn ingest(mut stream: rocket::data::ByteStream<'_>) -> std::io::Result<()> {
    use futures::stream::StreamExt;
    while let Some(chunk) = stream.next().await {
        let chunk = chunk?;
        // 逐块处理 chunk
        let _ = &chunk;
    }
    Ok(())
}

常见误区

  • 用 ByteStream 接收结构化 JSON:应直接用 Json 守卫,解析与错误处理更完整。
  • 流内做阻塞读取:占用工作线程,应使用异步流 API。

追问

  • ByteStream 与 Data<'r> 关系?答:Data 是原始 body 句柄,可转换为流或限制读取;ByteStream 提供流视图,具体转换 API 以版本文档为准。
  • 如何限制流读取量?答:配置 limits 与流内累计计数配合,超限中止处理。

04.4.5.1-067 Data<'r> 原始 body 类型什么时候使用?

一句话结论

需要直接控制 body 读取(自定义 FromData、流式代理、手动限制读取量)时使用 Data<'r>;常规场景优先用 Json/Form/TempFile 等高层守卫。

概念解释

Data<'r> 是 Rocket 暴露给数据守卫的原始 body 句柄,提供读取、流式化与长度限制方法。实现自定义 FromData 时接收它;高层守卫内部也基于它。handler 直接拿 Data 属于底层用法,需要自行处理读取、限制与错误。理解 Data 有助于阅读守卫源码与实现自定义 body 类型。

原理流程

  1. 自定义 FromData 接收 Data<'r>。
  2. 通过句柄读取或转换 body 流。
  3. 按类型规则解析/落盘。
  4. 返回 Outcome。
  5. 常规 handler 不直接操作 Data。

代码或图示

use rocket::data::{Data, FromData, Outcome};
use rocket::request::Request;

// 自定义 FromData 示例;方法签名以当前版本文档为准
#[rocket::async_trait]
impl<'r> FromData<'r> for MyBody {
    type Error = std::io::Error;
    async fn from_data(req: &'r Request<'_>, data: Data<'r>) -> Outcome<'r, Self, Self::Error> {
        // 在 data 上读取/流式化并解析
        Outcome::Success(MyBody)
    }
}

常见误区

  • 业务 handler 直接操作 Data:重复造轮子,容易遗漏限制与错误处理。
  • 忽略 body 长度限制:原始读取需要主动配合 limits 配置。

追问

  • Data 提供哪些读取方式?答:转字节流、读取限定长度、转文件等;完整方法列表以版本文档为准。
  • 自定义 FromData 如何返回错误?答:Outcome::Error((status, error)),状态码与错误类型自行定义。

04.4.5.1-068 除 JSON/Form 外还有哪些内置 FromData 类型?

一句话结论

内置数据守卫还包括 MsgPack(需要对应 feature)、Data、ByteStream、TempFile 以及字符串/字节相关类型;完整列表与 feature 名以 Rocket 当前版本文档为准。

概念解释

Rocket 的 data guard 体系按媒体类型组织:JSON、MsgPack、表单、文件、原始流。不同类型对应不同 feature 开关,未启用时类型不可用。选择依据:提交格式与处理方式。自定义协议可实现 FromData 包装 Data。面试中列举已知类型,不确定的 feature 与类型标注待确认并给出验证点。

原理流程

  1. 按请求格式选择内置守卫类型。
  2. 确认对应 feature 已启用。
  3. 类型实现 FromData,路由 data 参数绑定。
  4. 解析失败走 Outcome 错误流程。
  5. 无匹配类型时自定义 FromData。

代码或图示

内置数据守卫(以版本文档为准)
├── Json<T>:application/json,feature json
├── Form<T>:urlencoded / multipart 表单
├── TempFile:流式落盘文件
├── ByteStream:原始字节流
├── Data<'r>:原始 body 句柄
└── MsgPack:MessagePack,对应 feature

常见误区

  • 凭记忆列举类型与 feature:版本间可能增减,应核对 docs.rs。
  • 把 responder 类型与 data guard 混淆:同一类型常双向实现,需分开说明。

追问

  • MsgPack 如何接收?答:启用对应 feature,参数类型 MsgPack<T>,T 实现对应反序列化 trait;具体名称以版本文档为准。
  • 能否同时支持 JSON 与表单?答:不同路由或按 format 区分;单 data 参数按其类型解析。

04.4.5.1-069 body 解析失败如何用 Result 捕获字段级错误?

一句话结论

data 参数写成 Result<T, T::Error>,守卫的 Success 解包为 Ok,Error 解包为 Err;handler 内读取错误聚合(如表单 Errors、JSON 解析错误),生成字段级错误响应。

概念解释

与请求守卫的 Result 捕获类似,数据守卫失败可被 handler 捕获而不直接走 catcher。表单错误是字段级集合,可映射为 422 响应的字段列表;JSON 错误携带解析位置与原因。捕获后 handler 决定响应结构:重渲染表单、返回 JSON 错误体或记录日志。错误类型由守卫 FromData::Error 关联类型决定。

原理流程

  1. handler 参数声明 Result<Json<T>, JsonError> 或 Result<Form<T>, Errors>。
  2. 数据守卫返回 Success/Error。
  3. 包装类型解包为 Ok/Err。
  4. handler 遍历错误字段,构造错误响应。
  5. 成功分支继续业务逻辑。

代码或图示

use rocket::form::{Form, Errors};

#[rocket::post("/login", data = "<form>")]
fn login(form: Result<Form<Login<'_>>, Errors<'_>>) -> String {
    match form {
        Ok(f) => format!("hello {}", f.username),
        Err(e) => format!("表单错误: {e}"),
    }
}

常见误区

  • 捕获错误后丢弃错误详情:无法定位字段问题。
  • 用 Result 捕 JSON 错误却期望字段级路径:JSON 解析错误位置与表单字段错误结构不同,分别处理。

追问

  • 表单 Errors 如何遍历字段?答:按错误项的字段路径与消息访问;API 结构以版本文档为准。
  • 捕获后还能走 catcher 吗?答:需要统一错误响应时可在 handler 返回对应状态 responder,或重新转为错误流程。

04.4.5.1-070 自定义 FromData 实现有哪些要点?

一句话结论

实现 FromData<'r>:定义错误类型、async from_data 读取 Data、解析成功返回 Success、失败返回 Error 或 Forward;配合 feature 与 Sentinel 检查,body 读取遵守大小限制。

概念解释

自定义 body 类型用于私有协议或组合解析。要点:trait 关联 Error 类型;方法接收请求与 Data;读取流并构造自身类型;三态 Outcome 正确映射。实现内要处理超限、解析失败与空 body。若依赖托管状态或 catcher,考虑实现 Sentinel。返回值生命周期与 'r 一致,跨请求数据需克隆。

原理流程

  1. 定义 body 结构体与错误类型。
  2. 标注 #[rocket::async_trait] 实现 FromData。
  3. 在 from_data 中读取 Data 流。
  4. 解析成功 Success;不可处理 Forward;失败 Error。
  5. 路由 data 参数使用自定义类型。

代码或图示

#[rocket::async_trait]
impl<'r> FromData<'r> for MyBody {
    type Error = BodyError;
    async fn from_data(req: &'r Request<'_>, data: Data<'r>) -> Outcome<'r, Self, Self::Error> {
        match read_and_parse(data).await {
            Ok(body) => Outcome::Success(body),
            Err(e) => Outcome::Error((Status::UnprocessableEntity, e)),
        }
    }
}

常见误区

  • 读取 body 不做大小限制:超大请求撑爆内存。
  • 忘记 async_trait 标注:签名不匹配编译失败。

追问

  • 自定义守卫如何校验 Content-Type?答:在 from_data 内读取请求头比对;format 路由属性也可做前置约束。
  • 解析后的值需要跨任务保存吗?答:按生命周期规则克隆为自有类型,避免借用超出请求。

04.4.5.1-071 查询参数如何在路由 URI 中声明?

一句话结论

查询参数写在模板 ? 后,形如 ?<page>、?<page>&<size>,按同名绑定 handler 参数;可选参数用 Option<T>,结构体绑定通过表单类型整体接收。

概念解释

Rocket 路由模板包含路径与查询两部分。查询段声明后,框架从请求查询串取值并按类型解析。标量参数直接绑定;多字段查询用 Form/查询结构体。缺失参数按类型处理:标量缺失走解析失败,Option 为 None。查询声明与路径声明共用尖括号语法。

原理流程

  1. 模板写出 ?<param> 查询占位符。
  2. 请求查询串按名取值。
  3. 按参数类型解析。
  4. 成功绑定 handler 参数。
  5. 失败进入错误流程。

代码或图示

#[rocket::get("/items?<page>&<size>")]
fn list(page: u32, size: u32) -> String {
    format!("{page}/{size}")
}

常见误区

  • 查询参数写进路径段:位置与语法错误。
  • 必选参数缺失仍期待默认值:需用 Option 或在解析后提供默认。

追问

  • 查询参数类型解析用哪个 trait?答:标量按 FromParam 规则;结构体走表单绑定;具体 trait 对应以版本文档为准。
  • 查询串重复键怎么接收?答:集合类型(Vec)通过表单绑定,见 04.4.5.1-075。

04.4.5.1-072 结构体如何绑定查询参数?

一句话结论

定义派生 FromForm 的结构体,字段名与查询参数同名;handler 参数用表单/查询绑定类型接收,框架把查询串解析为结构体,缺失与类型错误由表单 Errors 收集。

概念解释

多字段查询(过滤、排序、分页)适合结构体绑定。FromForm 既解析 urlencoded body 也解析查询串;字段类型支持标量、可选、集合。结构体绑定避免 handler 参数列表过长,校验规则集中在类型上。查询结构体与表单结构体可复用同一 FromForm 定义。

原理流程

  1. 定义结构体派生 FromForm,字段对应查询键。
  2. handler 参数使用表单绑定类型。
  3. 框架解析查询串到字段。
  4. 错误收集到 Errors,可用 Result 捕获。
  5. handler 使用结构体字段。

代码或图示

use rocket::form::{Form, FromForm};

#[derive(FromForm)]
struct PageQuery {
    page: Option<u32>,
    size: Option<u32>,
    keyword: Option<String>,
}

#[rocket::get("/search")]
fn search(query: Form<PageQuery>) -> String {
    format!("{:?}", query)
}

常见误区

  • 结构体字段名与查询键不一致:绑定失败,用重命名属性校正。
  • 必选数值字段不包 Option:缺失即解析错误。

追问

  • 查询结构体需要 data 声明吗?答:查询参数来自 URI,不走 body data;绑定类型按 Rocket 规则解析,具体以版本文档为准。
  • 校验规则写在哪?答:#[field(validate = ...)] 属性或 handler/service 层补充校验。

04.4.5.1-073 查询参数的类型解析与缺失处理是怎样的?

一句话结论

标量按 FromParam 解析为目标类型;缺失参数对必选类型触发解析失败,对 Option<T> 为 None;解析错误可被 Result/Option 包装捕获后自定义响应。

概念解释

查询参数处理分缺失与类型错误两类。Rocket 按参数类型决定行为:普通类型缺失或无法解析走错误流程,Option 缺失为 None,带默认值需在 handler 内补充。数值、布尔等标准类型内置解析;自定义类型实现解析 trait。复杂错误展示通过表单 Errors 或 Result 捕获。

原理流程

  1. 从查询串取参数值。
  2. 缺失:Option 绑定 None;其他类型进入错误分支。
  3. 存在:按目标类型解析。
  4. 解析失败:错误 Outcome 或 Result::Err。
  5. handler 提供默认值与错误响应。

代码或图示

#[rocket::get("/items")]
fn list(page: Option<u32>, size: Option<u32>) -> String {
    let page = page.unwrap_or(1);
    let size = size.unwrap_or(20);
    format!("{page}/{size}")
}

常见误区

  • 数值参数缺失返回 500:应区分缺失默认与非法格式。
  • 在模板里声明必选参数却不传:路由不匹配或错误响应,按框架行为验证。

追问

  • 非法数字格式返回什么状态码?答:由解析错误映射决定;以版本文档为准,可在 handler 捕获后返回 400/422。
  • 字符串参数需要解码吗?答:0.5 自动百分比解码,直接使用 &str。

04.4.5.1-074 可选查询参数与默认值怎么声明?

一句话结论

参数类型用 Option<T> 表达可选;默认值在 handler 内 unwrap_or 提供,或通过表单字段默认值机制;模板声明不区分可选必选,可选性由 Rust 类型决定。

概念解释

可选性体现在参数类型而非路由模板。Option<T> 缺失为 None,handler 再给业务默认值(如页码 1、每页 20)。表单字段可定义默认值行为,具体机制以 FromForm 文档为准。默认值集中在一处定义,避免各 handler 散落字面量。布尔/枚举可选参数同样用 Option 包装。

原理流程

  1. 参数声明为 Option<T>。
  2. 缺失时绑定 None。
  3. handler 用 unwrap_or(default) 提供默认。
  4. 显式传入的值覆盖默认。
  5. 默认值常量集中管理。

代码或图示

const DEFAULT_PAGE: u32 = 1;
const DEFAULT_SIZE: u32 = 20;

#[rocket::get("/posts")]
fn posts(page: Option<u32>, size: Option<u32>) -> String {
    let page = page.unwrap_or(DEFAULT_PAGE);
    let size = size.unwrap_or(DEFAULT_SIZE);
    format!("{page}/{size}")
}

常见误区

  • 模板里写“可选语法”:Rocket 可选性由类型表达,模板占位符不区分。
  • 默认值散落在各 handler:分页/筛选口径不一致。

追问

  • 表单结构体字段默认值怎么设?答:FromForm 支持字段默认值机制;具体属性名以版本文档为准。
  • 可选枚举参数怎么解析?答:实现对应解析 trait 或在 handler 内字符串匹配后转换。

04.4.5.1-075 数组/重复查询参数如何绑定?

一句话结论

重复出现的查询参数绑定到集合类型(如 Vec<T>),通过表单绑定机制按重复键收集;集合元素按标量规则解析,空集合与缺失区分处理。

概念解释

?tag=rust&tag=rocket 这类重复键需要集合接收。Rocket 表单体系支持 Vec 等集合字段,查询串重复值按名收集。元素类型解析失败会进入表单错误。集合为空与参数缺失在业务上可区分:Option<Vec<T>> 表达“未传”与“传了空”。

原理流程

  1. 结构体集合字段声明 Vec<T>。
  2. 框架按重复查询键收集值。
  3. 元素逐个解析为 T。
  4. 解析错误聚合到 Errors。
  5. handler 使用集合。

代码或图示

#[derive(FromForm)]
struct Filter {
    tag: Vec<String>,
}

#[rocket::get("/items")]
fn items(filter: Form<Filter>) -> String {
    format!("{:?}", filter.tag)
}

常见误区

  • 重复键绑定到标量类型:只取到一个值或绑定失败。
  • 集合元素未校验类型:非法值进入业务逻辑。

追问

  • 索引键形式(tag[0]=a)怎么解析?答:表单集合支持索引键命名;具体格式以版本文档为准。
  • 集合大小有限制吗?答:表单/limits 配置与字段校验可约束元素数量;防止超大查询串。

04.4.5.1-076 查询参数与表单绑定如何共用 FromForm?

一句话结论

FromForm 结构体既解析 urlencoded/multipart body,也可用于查询参数绑定;同一结构体可同时服务于 GET 查询与 POST 表单,字段命名与校验规则复用。

概念解释

表单绑定 trait 的输入来源不限于 body:查询串同样是键值对集合。把筛选条件结构体派生 FromForm,GET 路由用它接收查询,POST 路由用它接收表单,减少重复类型定义。两者错误结构一致,校验规则可复用。注意 body 表单受 data 声明约束,查询绑定来自 URI,参数声明方式不同。

原理流程

  1. 定义筛选/提交结构体派生 FromForm。
  2. GET 路由:结构体接收查询参数。
  3. POST 路由:Form<T> 接收 body。
  4. 字段校验与错误处理复用同一套逻辑。
  5. handler 按场景使用绑定值。

代码或图示

#[derive(FromForm)]
struct Search<'r> {
    keyword: Option<&'r str>,
    tag: Vec<String>,
}

#[rocket::get("/search")]
fn get_search(q: Form<Search<'_>>) -> String { format!("{q:?}") }

#[rocket::post("/search", data = "<q>")]
fn post_search(q: Form<Search<'_>>) -> String { format!("{q:?}") }

常见误区

  • 查询绑定也写 data 属性:data 只用于 body,查询参数不声明。
  • 结构体同时包含 body 专属文件字段:查询场景无法提供 TempFile,应拆分类型。

追问

  • 复用结构体有什么风险?答:body 与查询的字段约束可能不同,差异大时拆分更清晰。
  • FromForm 与 FromFormField 区别?答:前者描述整体表单,后者描述单个字段类型;嵌套字段实现后者。

04.4.5.1-077 catcher 是什么,与路由 handler 有什么区别?

一句话结论

catcher 是处理错误状态请求的特殊 handler,由状态码触发;普通路由处理匹配成功的请求,catcher 处理未匹配、守卫错误、解析失败等脱离正常流程的请求。

概念解释

请求处理分正常与错误两条通道。路由 handler 在匹配与守卫全部通过后执行;catcher 在错误状态产生后按状态码被调用。catcher 可以访问请求与状态,返回错误响应。两者返回类型都需要实现 Responder。未注册的状态码由默认 catcher 兜底。

原理流程

  1. 请求在路由/守卫/数据阶段产生错误状态。
  2. Rocket 按状态码查找注册 catcher。
  3. 命中 → 调用 catcher 生成响应。
  4. 未命中 → 默认 catcher。
  5. 错误响应发送客户端。

代码或图示

#[rocket::catch(404)]
fn not_found(req: &rocket::Request<'_>) -> String {
    format!("路径不存在: {}", req.uri())
}

常见误区

  • 把 404 逻辑写进路由兜底 handler 而不用 catcher:错误响应结构无法统一复用。
  • catcher 内执行业务查询:catcher 应保持轻量,只生成错误响应。

追问

  • catcher 能返回 JSON 吗?答:能,返回 Json<T> 或其他实现 Responder 的错误类型。
  • 一条状态码能注册多个 catcher 吗?答:按注册规则匹配;具体覆盖方式以版本文档为准。

04.4.5.1-078 如何注册 404、422、500 定制 catcher?

一句话结论

用 #[catch(状态码)] 定义 catcher 函数,在 register("/", catchers![..]) 中注册;为需要定制的状态码分别编写,未覆盖的状态走默认 catcher。

概念解释

注册流程与路由对称:catchers![..] 宏收集 catcher 函数,register 挂载到前缀。常见定制状态:404 未找到、422 校验失败、500 内部错误。401/403 等认证错误也可注册对应 catcher。catcher 函数签名接收请求(与可选错误数据),返回 responder。注册后启动日志可核对 catcher 列表。

原理流程

  1. 为目标状态码编写 #[catch(404)] 等函数。
  2. 函数返回统一错误响应类型。
  3. register("/", catchers![not_found, unprocessable, internal])。
  4. 错误状态产生时按码匹配。
  5. 未注册状态走默认 catcher。

代码或图示

#[rocket::catch(422)]
fn unprocessable(req: &rocket::Request<'_>) -> String {
    format!("请求校验失败: {}", req.uri())
}

let rocket = rocket::build()
    .register("/", rocket::catchers![not_found, unprocessable]);

常见误区

  • 只定义 catcher 函数忘记注册:默认页面仍生效。
  • catcher 状态码与实际错误不匹配:422 响应挂到 404 catcher 下。

追问

  • 500 catcher 能拿到 panic 信息吗?答:取决于错误传递方式;panic 捕获与错误信息可访问范围以版本文档为准。
  • catcher 可以按前缀分别注册吗?答:register 支持前缀挂载;具体匹配规则以版本文档为准。

04.4.5.1-079 #[catch(default)] 默认 catcher 的作用是什么?

一句话结论

默认 catcher 为所有未显式注册的状态码提供兜底响应;自定义默认 catcher 可统一错误页面/错误体格式,避免不同状态返回框架默认样式不一致。

概念解释

每个状态码都需要响应:未单独注册的状态落到默认 catcher。#[catch(default)] 覆盖这些兜底场景,项目可在此统一错误体结构、日志记录与页面模板。显式注册的 catcher 优先于默认 catcher。默认 catcher 不应假设请求一定匹配了某条路由。

原理流程

  1. 定义 #[catch(default)] 函数。
  2. 错误状态产生,先查找显式 catcher。
  3. 未命中 → 调用默认 catcher。
  4. 默认 catcher 生成统一错误响应。
  5. 响应发送客户端。

代码或图示

#[rocket::catch(default)]
fn default_catcher(status: rocket::http::Status, req: &rocket::Request<'_>) -> String {
    format!("错误 {}: {}", status.code, req.uri())
}

常见误区

  • 只配默认 catcher 不配 404:404 文案与结构无法针对未找到资源定制。
  • 默认 catcher 内部假设请求已认证:错误请求可能未经过守卫。

追问

  • 默认 catcher 接收哪些参数?答:常见为 Status 与 Request;参数形式以版本文档为准。
  • 能否为不同状态在默认 catcher 内分支?答:可以按 status.code 区分响应,但显式 catcher 更清晰。

04.4.5.1-080 catcher 接收哪些参数(Status、Request、数据)?

一句话结论

catcher 函数可接收 Status(状态码)、&Request(请求上下文)以及对应错误类型的数据;参数按 catcher 签名规则注入,具体可访问的错误数据以版本文档为准。

概念解释

catcher 参数与路由参数不同:没有路由占位符绑定,主要接收状态与请求引用。部分错误类型允许把错误值传给 catcher(如表单错误、数据守卫错误)。参数类型决定可访问的信息范围;需要托管状态时通过请求访问器读取。编写 catcher 前应核对当前版本支持的参数形式。

原理流程

  1. 定义 catcher 函数,声明需要的参数。
  2. Rocket 按签名注入状态、请求或错误数据。
  3. catcher 读取上下文构造响应。
  4. 返回 responder。
  5. 未提供的参数不强制要求。

代码或图示

#[rocket::catch(404)]
fn not_found(status: rocket::http::Status, req: &rocket::Request<'_>) -> String {
    format!("{} {}", status.code, req.uri())
}

常见误区

  • 期待 catcher 自动收到 body 解析错误详情:错误数据可访问性受 trait 实现限制,不确定时核对文档。
  • catcher 参数声明过多未注入类型:编译/启动报错。

追问

  • catcher 能读取请求头与 Cookie 吗?答:通过 &Request 访问器读取,与守卫一致。
  • 错误数据如何传递给 catcher?答:由对应守卫/数据守卫的 Outcome 与 Rocket 错误通道决定;具体机制以版本文档为准。

04.4.5.1-081 422 表单/JSON 校验错误如何展示?

一句话结论

422 响应应包含字段级错误列表(字段路径 + 消息);表单 Errors 与 JSON 解析错误分别映射为结构化错误体,前端据此定位输入项并提示。

概念解释

422 表示报文合法但语义/校验不通过。表单错误天然带字段路径,可直接映射字段列表;JSON 解析错误携带位置与原因,结构化后返回。错误体建议区分字段错误与全局错误。展示策略:Web 表单回显错误,API 返回 JSON 字段错误数组。校验规则在 FromForm 属性或 service 层,错误收集在 data 守卫阶段。

原理流程

  1. 数据守卫解析失败,错误聚合为 Errors 或解析错误。
  2. handler 用 Result 捕获或 catcher 接收。
  3. 遍历错误,提取字段路径与消息。
  4. 构造 422 错误体(字段列表 + 全局消息)。
  5. 响应发送,前端按字段定位。

代码或图示

use rocket::form::{Form, Errors};

#[rocket::post("/login", data = "<form>")]
fn login(form: Result<Form<Login<'_>>, Errors<'_>>) -> rocket::serde::json::Json<serde_json::Value> {
    match form {
        Ok(f) => rocket::serde::json::Json(serde_json::json!({"ok": true})),
        Err(e) => rocket::serde::json::Json(serde_json::json!({
            "code": "VALIDATION",
            "errors": e.iter().map(|err| err.to_string()).collect::<Vec<_>>()
        })),
    }
}

常见误区

  • 422 只返回笼统消息:前端无法定位字段。
  • 把 JSON 语法错误与业务校验失败混为一类:错误类型应区分。

追问

  • Errors 如何取字段路径?答:错误项携带字段上下文;访问 API 以版本文档为准。
  • 字段校验规则写在哪?答:#[field(validate = ...)] 派生属性,或 service 层规则校验后抛业务错误。

04.4.5.1-082 catcher 如何返回 JSON 错误体?

一句话结论

catcher 返回 Json<T>(或自定义实现 Responder 的错误结构体),序列化为 JSON 并设置 application/json;错误体结构与成功响应风格保持一致。

概念解释

catcher 与路由 handler 共用 responder 体系。返回 Json<ErrorBody> 即可输出 JSON 错误;需要复用统一错误类型时为其实现 Responder。错误体包含错误码、消息、字段错误与请求标识。catcher 内不要泄露内部堆栈与依赖细节。JSON feature 需在依赖中启用。

原理流程

  1. 定义统一错误体结构体并派生 Serialize。
  2. catcher 按状态码与上下文填充字段。
  3. 返回 Json(error_body)。
  4. 框架序列化并设置媒体类型。
  5. 客户端解析错误分支。

代码或图示

use rocket::serde::json::Json;
use serde::Serialize;

#[derive(Serialize)]
struct ErrorBody { code: String, message: String }

#[rocket::catch(404)]
fn not_found(_req: &rocket::Request<'_>) -> Json<ErrorBody> {
    Json(ErrorBody { code: "NOT_FOUND".into(), message: "资源不存在".into() })
}

常见误区

  • catcher 返回纯文本但前端按 JSON 解析:响应格式与接口约定不一致。
  • 错误体结构各 catcher 重复定义:应复用统一类型。

追问

  • 自定义错误结构体如何实现 Responder?答:实现 Responder trait,组装状态码、头与 body;签名以版本文档为准。
  • 错误码与状态码关系?答:HTTP 状态码表达协议语义,错误码表达业务场景,两者并存于错误体。

04.4.5.1-083 catcher 与守卫 Error 的流转关系是什么?

一句话结论

守卫/数据守卫返回 Error 后,Rocket 按携带状态码把请求交给对应 catcher;catcher 是错误响应的统一出口,Error 提供状态码与错误值。

概念解释

流转链路:守卫校验失败 → Outcome::Error((status, value)) → 框架按 status 查找 catcher → catcher 生成响应。Forward 不进入 catcher,而是转下一路由。理解这条链路有助于定位“为什么返回了某个错误页面”:先看守卫 Error 状态码,再看对应 catcher 实现。错误值能否被 catcher 读取取决于传递机制。

原理流程

  1. 守卫返回 Error 携带状态码。
  2. Rocket 脱离正常 handler 流程。
  3. 按状态码检索 catcher 注册表。
  4. 调用 catcher 生成错误响应。
  5. 未注册状态走默认 catcher。

代码或图示

守卫/数据守卫
├── Success → handler
├── Forward → 下一条路由
└── Error((status, value)) → 对应状态码 catcher → 错误响应

常见误区

  • 以为守卫 Error 会被 handler 的 Result 捕获:未用 Result 包装参数时直接进 catcher;包装后在 handler 内处理。
  • catcher 找不到时返回框架默认响应:需检查注册列表。

追问

  • 数据守卫 Error 走同一通道吗?答:是,FromData 的 Error 同样按状态码进入 catcher。
  • 如何在 catcher 记录错误日志?答:catcher 内可通过日志记录状态与请求路径;错误链详情的可访问性以版本文档为准。

04.4.5.1-084 catcher 中如何访问请求与托管状态?

一句话结论

catcher 通过注入的 &Request 访问头、Cookie、URI 等;托管状态通过请求状态访问器读取,方式与守卫一致;需要身份信息时注意错误请求可能未经过认证守卫。

概念解释

catcher 处于错误通道,仍持有请求上下文。请求方法、URI、头、Cookie 可直接读取;托管状态从请求状态入口获取。与守卫不同,catcher 执行时认证守卫可能未通过,不要假设身份已存在。日志记录在 catcher 内补充请求路径与状态码。

原理流程

  1. catcher 签名声明 &Request 参数。
  2. 通过请求访问器读取上下文。
  3. 托管状态经请求状态入口获取。
  4. 构造错误响应,必要时记录日志。
  5. 返回 responder。

代码或图示

#[rocket::catch(500)]
fn internal(req: &rocket::Request<'_>) -> String {
    tracing::error!(uri = %req.uri(), "internal error");
    format!("服务暂不可用: {}", req.uri())
}

常见误区

  • 在 catcher 内读取守卫产出的身份值:身份未注入请求上下文,不可直接获取。
  • catcher 内做重业务查询:错误通道应保持轻量。

追问

  • catcher 能访问请求本地存储吗?答:若守卫在请求本地写入,catcher 可按访问器读取;写入内容需在错误路径仍保留。
  • 托管状态类型未注册会怎样?答:访问取不到值;启动期 Sentinel 可提前发现缺失状态。

04.4.5.1-085 Rocket 的编译期与启动期校验覆盖哪些问题?

一句话结论

编译期检查 trait 实现、生命周期与 async_trait 标注;启动期检查路由绑定、重复路由、格式冲突、Sentinel 前置条件(托管状态、catcher);两类校验共同保证类型安全与配置完整。

概念解释

Rocket 的安全模型分层:Rust 编译器保证类型与内存安全,Rocket 启动校验保证路由元数据与运行前置条件。编译期报错多为 trait 未实现;启动期诊断多为参数不匹配、重复注册、状态缺失。理解分层后,报错时先判断属于哪一层,按对应信息排查。

原理流程

  1. 编译期:trait bound、生命周期、async_trait 签名检查。
  2. 启动期:扫描路由元数据,校验占位符与参数对应。
  3. 检查重复方法路径与格式冲突。
  4. Sentinel 检查托管状态、catcher 等条件。
  5. 校验通过才进入监听。

代码或图示

校验分层
├── 编译期:Responder/FromRequest/FromData/FromParam 实现、生命周期
├── 启动期:参数绑定、重复路由、format 冲突
└── Sentinel:托管状态存在、必需 catcher 已注册

常见误区

  • 把启动期问题当编译错误排查:两类诊断信息位置不同。
  • 跳过启动流程直接上线:配置错误延迟到请求时暴露。

追问

  • 路由参数名不匹配何时报错?答:启动期路由元数据校验阶段;编译期只检查类型约束。
  • 如何快速跑启动校验?答:测试或启动命令中构建 Rocket 实例,观察启动日志诊断。

04.4.5.1-086 路由冲突如何检测与解决?

一句话结论

同方法同路径的重复注册在启动期被检测为冲突;解决方式是合并为单一路由、区分方法/前缀,或用 rank 与 Forward 组织回退链,而不是让两条竞争路由共存。

概念解释

冲突指无法共存的路由注册:方法、路径都相同。Rocket 启动期报告冲突并中止。解决思路:重复 handler 合并;按方法区分 GET/POST;按前缀拆分模块;需要回退语义时用动态路由 + Forward/rank 排序。冲突与“可共存但顺序需调整”的 rank 问题不同。

原理流程

  1. 启动期比对路由方法与路径模板。
  2. 发现完全重复 → 报告冲突。
  3. 评估重复来源:复制粘贴、模块重复挂载。
  4. 合并或拆分路由。
  5. 重新启动校验通过。

代码或图示

冲突处理
├── 重复注册:删除多余路由
├── 同路径不同方法:保留各方法 handler
├── 同方法路径近似:调整前缀/参数
└── 回退需求:动态段 + rank + Forward

常见误区

  • 试图用 rank 解决重复注册:rank 只排顺序,不消除冲突。
  • 重复挂载同一模块:mount 多次导致路由叠加,检查挂载列表。

追问

  • 静态与动态段同位置算冲突吗?答:不算冲突,按默认 rank 静态优先;具体匹配顺序见 04.4.5.1-021。
  • 如何查看全部已注册路由?答:启动日志列出路由表;routes! 宏列表是源代码侧入口。

04.4.5.1-087 Sentinel 在哪些场景下会中止启动?

一句话结论

Sentinel 检查类型依赖的前置条件:托管状态类型缺失、必需 catcher 未注册、配置不满足等;条件不满足时 Rocket 中止 launch 并输出诊断,避免运行期错误。

概念解释

典型场景:State<T> 守卫发现 T 未通过 manage 注册;自定义 responder/守卫依赖某个 catcher 或配置。Sentinel 把“请求时才暴露”的问题提前到部署阶段。实现 Sentinel 可为自定义类型补充检查。启动诊断应明确指出缺失的类型与条件。

原理流程

  1. Rocket 启动期遍历路由与 catcher 中的类型。
  2. 调用各类型的 Sentinel 检查。
  3. 条件缺失 → 收集诊断并中止。
  4. 诊断说明缺失状态/ catcher/配置。
  5. 修复后重新启动。

代码或图示

// 示例:State<AppState> 是内置 Sentinel
// 若未 rocket::build().manage(AppState { .. }),启动期报错

常见误区

  • 忽略启动期 Sentinel 报错强行放行:运行期首个相关请求才失败。
  • 自定义守卫依赖必选状态却不实现 Sentinel:缺失问题延后暴露。

追问

  • 如何为自定义类型实现 Sentinel?答:实现 Sentinel trait 的检查方法;具体签名以版本文档为准。
  • Sentinel 检查在路由校验之前还是之后?答:同属 launch 阶段;执行顺序以框架实现为准。

04.4.5.1-088 未注册托管状态会导致什么启动失败?

一句话结论

路由或 catcher 中使用 State<T> 但未 manage(T) 时,Sentinel 在启动期中止;表现为诊断提示状态类型缺失,注册状态后恢复。

概念解释

托管状态通过 rocket::build().manage(value) 注册,State<T> 守卫按类型查找。缺失时运行期无法构造守卫;Sentinel 提前拦截。常见遗漏:新增状态类型后只改了守卫,忘记 manage;或测试实例未注入状态。排查时先看启动诊断指出的类型,再检查 manage 调用与测试状态注入。

原理流程

  1. 路由参数使用 State<AppState>。
  2. 启动期 Sentinel 检查 AppState 是否托管。
  3. 未注册 → 诊断中止。
  4. 在构建实例时 manage(AppState { .. })。
  5. 重新启动校验通过。

代码或图示

let rocket = rocket::build()
    .manage(AppState { /* 配置与连接句柄 */ })
    .mount("/", rocket::routes![handler]);

常见误区

  • 在 handler 内局部新建状态实例:不是托管状态,State 守卫仍取不到。
  • 测试实例忘记 manage:集成测试报 Sentinel 错误。

追问

  • 状态类型需要 Send + Sync + 'static 吗?答:托管状态跨请求共享,通常要求线程安全;具体约束以版本文档为准。
  • 多个同类型状态如何区分?答:按类型注册,不同数据用不同包装类型;同类型多实例需自定义键机制。

04.4.5.1-089 responder 与守卫类型检查在什么时候发生?

一句话结论

trait 实现检查在编译期完成;类型在路由中的出现与前置条件检查在启动期(含 Sentinel);请求运行时才执行守卫与解析逻辑。

概念解释

三层时机:编译器检查“类型是否实现对应 trait”;启动期检查“路由元数据与状态条件是否完整”;运行时执行“校验、解析、响应转换”。排查报错先定位时机:编译错误看 trait bound,启动诊断看路由/状态,运行错误看守卫与解析分支。

原理流程

  1. 编译期:返回类型 Responder、参数类型 FromRequest/FromData/FromParam 检查。
  2. 启动期:参数绑定、重复路由、Sentinel 条件。
  3. 运行时:守卫 from_request、数据 from_data、responder 转换。
  4. 各层失败进入对应错误通道。
  5. 日志记录运行期错误。

代码或图示

时机对照
├── 编译期:trait 未实现、签名不匹配
├── 启动期:绑定/冲突/状态缺失
└── 运行时:凭证无效、解析失败、响应序列化错误

常见误区

  • 把运行期解析失败归因于编译检查:两者排查路径不同。
  • 守卫逻辑错误在编译期寻找原因:逻辑分支只能在运行测试覆盖。

追问

  • FromParam 检查在哪一层?答:编译期检查 trait 实现;路由占位符与参数对应在启动期校验。
  • responder 序列化错误何时暴露?答:运行期返回响应时;序列化失败的处理以 Responder 实现为准。

04.4.5.1-090 启动日志中的路由与 catcher 列表如何阅读?

一句话结论

启动日志按挂载前缀列出每条路由的方法、路径、rank 与参数,以及已注册 catcher;核对日志可确认路由是否注册、优先级顺序与错误出口是否完整。

概念解释

Rocket 启动时打印路由表与 catcher 表,是核对配置的第一手资料。阅读要点:方法与路径是否符合预期;动态段与参数类型;rank 顺序;catcher 状态码覆盖。日志格式随版本调整,不确定处以当前版本实际输出为准。新增路由后应检查日志确认出现,而不是只看源代码。

原理流程

  1. 启动 Rocket 实例,观察输出日志。
  2. 在路由列表中查找目标方法与路径。
  3. 核对动态段、参数类型与 rank。
  4. 在 catcher 列表核对 404/422/500 等覆盖。
  5. 缺失项回到注册代码补齐。

代码或图示

日志核对项
├── 方法:GET/POST/PUT/DELETE
├── 路径:静态段、动态段、多段通配
├── rank:匹配优先级
├── 参数:守卫、数据守卫类型
└── catcher:状态码与默认 catcher

常见误区

  • 新增路由后不看日志:路径拼写或挂载前缀错误未被发现。
  • 只看源代码不核对 catcher 注册:错误响应仍走默认页面。

追问

  • 日志中某路由缺失说明什么?答:未挂载到当前 Rocket 实例,检查 routes! 列表与 mount 前缀。
  • 如何在测试中查看路由表?答:测试实例同样输出启动日志;也可通过实例 API 检查路由列表,具体接口以版本文档为准。

04.4.5.1-091 Rocket 测试用 local client 如何搭建?

一句话结论

构造测试 Rocket 实例(注入测试状态),用 rocket::local 客户端包裹实例,发起请求并断言响应;阻塞客户端用于同步测试,异步客户端配合 async 测试运行时。

概念解释

Rocket 提供本地测试客户端,无需真实端口即可驱动路由。搭建步骤:rocket::build() 注册路由、catcher 与测试状态;创建 Client;用客户端方法发 GET/POST 等请求;读取状态码与 body。测试状态使用内存替身或测试数据库,与生产配置隔离。客户端类型分阻塞与异步两种。

原理流程

  1. 构建测试 Rocket 实例,挂载路由与 catcher。
  2. 注入测试托管状态。
  3. 创建 local client(阻塞或异步)。
  4. 发送请求,得到响应。
  5. 断言状态码、响应体与副作用。

代码或图示

# #[rocket::async_test]
# async fn hello() {
let rocket = rocket::build()
    .manage(test_state())
    .mount("/", rocket::routes![index]);
let client = rocket::local::asynchronous::Client::tracked(rocket).await.unwrap();
let resp = client.get("/").dispatch().await;
assert_eq!(resp.status(), rocket::http::Status::Ok);
# }

常见误区

  • 测试实例漏挂路由或 catcher:断言落到默认响应。
  • 测试依赖外部真实服务:隔离性差,结果不稳定。

追问

  • tracked 方法做什么?答:启用请求跟踪以便测试检查;具体行为以版本文档为准。
  • 客户端可以发带 body 的请求吗?答:可以,按客户端 API 传递 JSON/表单数据;方法形式以版本文档为准。

04.4.5.1-092 阻塞客户端与异步客户端如何选择?

一句话结论

同步测试函数用 blocking::Client,async 测试用 asynchronous::Client;选择与测试运行时匹配,阻塞客户端内部桥接运行时,异步客户端直接在 async 上下文使用。

概念解释

Rocket 0.5 提供两种本地客户端:阻塞版面向同步测试,异步版面向 async_test/Tokio 上下文。混用会导致运行时桥接问题。测试函数标注决定客户端选择:#[test] 配阻塞客户端,#[rocket::async_test] 配异步客户端。两种客户端请求与断言 API 基本对应。

原理流程

  1. 确定测试函数是同步还是 async。
  2. 同步 → rocket::local::blocking::Client。
  3. async → rocket::local::asynchronous::Client。
  4. 发送请求并读取响应。
  5. 断言状态码与 body。

代码或图示

// 异步测试客户端
# #[rocket::async_test]
# async fn async_case() {
let client = rocket::local::asynchronous::Client::tracked(rocket).await.unwrap();
let resp = client.get("/").dispatch().await;
# }

// 阻塞测试客户端(同步测试函数内使用)
// let client = rocket::local::blocking::Client::tracked(rocket);
// let resp = client.get("/").dispatch();

常见误区

  • async 测试里用阻塞客户端:运行时上下文不匹配。
  • 阻塞客户端在多线程测试下共享:客户端实例按测试隔离创建。

追问

  • 两种客户端断言能力一致吗?答:状态码、body 读取等核心能力对应;细节 API 以版本文档为准。
  • 测试用哪个运行时?答:Rocket 提供 #[rocket::async_test] 宏;也可按项目约定使用 Tokio 测试宏,具体支持以版本文档为准。

04.4.5.1-093 测试中如何断言状态码与响应体?

一句话结论

响应对象提供状态码访问器与 body 读取方法;断言 status() 等于预期,读取 body 字符串/字节后解析比对 JSON 或字段。

概念解释

测试断言分两步:先断言状态码(200/401/404/422),再断言 body。body 可读取为字符串或字节,JSON 响应反序列化为结构体比较。错误响应断言错误码与字段列表,不只看状态码。断言应具体到业务值,避免只断言 body 非空。

原理流程

  1. 客户端发起请求得到响应。
  2. assert_eq!(resp.status(), expected)。
  3. 读取 body 为字符串/字节。
  4. JSON 反序列化后断言字段。
  5. 必要时断言响应头。

代码或图示

# let resp = client.get("/users/1").dispatch().await;
assert_eq!(resp.status(), rocket::http::Status::Ok);
let body = resp.into_string().await.unwrap();
let json: serde_json::Value = serde_json::from_str(&body).unwrap();
assert_eq!(json["name"], "ann");

常见误区

  • 只断言状态码:错误结构漂移无法发现。
  • body 读取后未处理错误:读取失败被忽略,断言假阳性。

追问

  • 如何断言 JSON 字段缺失?答:反序列化为 Value 检查键存在与类型;或用结构体 Option 字段断言。
  • 响应头如何断言?答:通过响应头访问器读取 content-type 等;API 形式以版本文档为准。

04.4.5.1-094 如何测试守卫的通过与拒绝路径?

一句话结论

通过路径带有效凭证请求,断言 200 与业务响应;拒绝路径分别构造缺失、无效、过期、越权请求,断言对应 401/403/429 状态码与错误体。

概念解释

守卫测试必须覆盖成功与各类失败分支。测试状态中准备测试用户、有效与无效令牌、不同角色。每个拒绝变体对应一种请求构造:无头、伪造令牌、过期令牌、普通用户访问管理员路由。断言状态码与错误码,验证 Forward 行为时检查请求是否落到后续路由。

原理流程

  1. 测试实例注入用户表、密钥与权限数据。
  2. 有效凭证请求 → 断言通过响应。
  3. 缺失凭证 → 断言 401。
  4. 无效/过期凭证 → 断言对应错误。
  5. 越权角色 → 断言 403。

代码或图示

# async fn guard_tests() {
// 通过
let resp = client.get("/admin").header(Authorization("Bearer valid")).dispatch().await;
assert_eq!(resp.status(), Status::Ok);
// 拒绝:无凭证
let resp = client.get("/admin").dispatch().await;
assert_eq!(resp.status(), Status::Unauthorized);
// 拒绝:普通用户
let resp = client.get("/admin").header(Authorization("Bearer user")).dispatch().await;
assert_eq!(resp.status(), Status::Forbidden);
# }

常见误区

  • 只测通过路径:拒绝分支回归无保护。
  • 拒绝断言不区分错误码:401 与 403 混用无法发现。

追问

  • 如何测试 Forward 分支?答:请求同时匹配当前路由与回退路由,断言最终落到预期 handler;响应与日志辅助判断。
  • 守卫依赖异步查询怎么测?答:注入内存替身仓库,预置用户与令牌数据。

04.4.5.1-095 如何测试表单与 JSON body 提交?

一句话结论

客户端 POST 请求带上 JSON/表单 body 与对应 Content-Type;断言解析成功响应或 422 字段错误;非法报文单独构造用例验证错误分支。

概念解释

body 提交测试覆盖三类:合法 JSON/表单成功绑定;字段缺失或类型错误返回 422;Content-Type 不匹配路由约束时落到其他路由或错误。测试构造请求体按守卫格式序列化,表单按 urlencoded 或 multipart 编码。断言绑定后的业务结果与错误字段列表。

原理流程

  1. 构造合法 body 并设置 Content-Type。
  2. POST 到目标路由,断言成功响应。
  3. 构造缺字段/类型错误 body,断言 422 与错误字段。
  4. 构造格式不匹配请求,验证路由约束行为。
  5. 校验持久化结果(测试库/内存替身)。

代码或图示

# let client = /* */;
let resp = client.post("/login")
    .header(ContentType::FormUrlEncoded)
    .body("username=ann&password=secret")
    .dispatch().await;
assert_eq!(resp.status(), Status::Ok);

let bad = client.post("/login")
    .header(ContentType::FormUrlEncoded)
    .body("username=")
    .dispatch().await;
assert_eq!(bad.status(), Status::UnprocessableEntity);

常见误区

  • 不设置 Content-Type:守卫按类型解析可能失败或路由不匹配。
  • 只测合法提交:校验错误分支未覆盖。

追问

  • multipart 文件上传怎么测?答:构造 multipart 编码 body;TempFile 测试构造方式见 04.4.5.1-097。
  • JSON body 用什么客户端方法?答:按客户端 API 设置 body 与 application/json 头;具体方法名以版本文档为准。

04.4.5.1-096 测试中如何注入托管状态?

一句话结论

测试 Rocket 实例在 build() 后调用 manage() 注入内存替身、测试配置或测试库连接;每个测试实例独立注入,避免共享可变状态污染。

概念解释

生产状态来自配置与真实依赖,测试替换为替身:内存仓库、假密钥、测试数据库连接。manage 注册的类型与守卫 State<T> 一致。测试之间状态隔离:每个测试构建自己的实例与状态,或在 setup 中重置共享替身。异步共享状态注意并发安全。

原理流程

  1. 定义测试用状态结构与替身实现。
  2. 测试内 rocket::build().manage(test_state)。
  3. 挂载路由与 catcher。
  4. 创建客户端发请求。
  5. 断言后实例与状态丢弃。

代码或图示

fn test_rocket() -> rocket::Rocket<rocket::Build> {
    let state = AppState {
        users: MemoryUserRepo::new(),
        secret: "test-secret".into(),
    };
    rocket::build().manage(state).mount("/", rocket::routes![handler])
}

常见误区

  • 测试实例复用生产配置读取:环境依赖导致测试不稳定。
  • 共享可变替身未重置:用例间数据串扰。

追问

  • 数据库池怎么注入测试?答:连接测试库或内存数据库池;事务回滚/重建策略按测试方案设计。
  • 状态类型不匹配会怎样?答:Sentinel 启动期报错;核对 manage 类型与 State<T> 泛型一致。

04.4.5.1-097 测试上传文件(TempFile)如何构造请求?

一句话结论

按 multipart 表单格式构造请求 body,包含文件字段与文件名/类型;客户端提交后断言 TempFile 接收、持久化结果与临时文件清理行为;测试临时目录按环境隔离。

概念解释

TempFile 从 multipart 部分落盘,测试需要模拟 multipart 编码:边界、字段头、文件内容。断言点:文件被接收、persist_to 后正式路径存在、未持久化文件被清理。测试环境临时目录与正式上传目录分离,避免污染。大文件测试用小字节内容验证流程即可。

原理流程

  1. 构造 multipart body(边界、文件字段名、文件名、内容)。
  2. POST 到上传路由,Content-Type 为 multipart。
  3. 断言响应状态与业务结果。
  4. 检查正式文件路径(若 persist)。
  5. 清理测试产生的临时与正式文件。

代码或图示

# let client = /* */;
let boundary = "----testboundary";
let body = format!(
    "--{boundary}\r\nContent-Disposition: form-data; name=\"file\"; filename=\"a.txt\"\r\n\r\nhello\r\n--{boundary}--\r\n"
);
let resp = client.post("/upload")
    .header(ContentType::new("multipart", "form-data").with_boundary(boundary))
    .body(body)
    .dispatch().await;
assert_eq!(resp.status(), Status::Ok);

常见误区

  • body 缺少边界声明或字段头:TempFile 解析不到文件部分。
  • 测试后不清理上传目录:用例间文件残留。

追问

  • 测试中限制大小如何验证?答:构造超过 limits.file 的内容,断言超限错误状态。
  • 如何验证临时文件删除?答:监控临时目录在测试结束后无残留;具体临时目录路径以配置为准。

04.4.5.1-098 catcher 在测试中如何验证?

一句话结论

触发对应错误状态(未匹配路径、守卫拒绝、解析失败),请求响应应落到目标 catcher;断言 catcher 产出的状态码与错误体结构,而不是框架默认页面。

概念解释

catcher 测试验证错误出口完整:404 走自定义 404 catcher,422 走校验 catcher。测试构造触发条件:访问不存在路径、带无效凭证、提交非法 body。断言响应体包含 catcher 生成的错误码与消息。默认 catcher 覆盖项也应验证未注册状态的兜底格式。

原理流程

  1. 测试实例注册目标 catcher。
  2. 触发对应错误状态请求。
  3. 断言响应状态码匹配 catcher。
  4. 读取 body 断言自定义错误结构。
  5. 验证默认 catcher 兜底行为。

代码或图示

# let client = /* */;
let resp = client.get("/no-such-path").dispatch().await;
assert_eq!(resp.status(), Status::NotFound);
let body = resp.into_string().await.unwrap();
assert!(body.contains("NOT_FOUND"));

常见误区

  • 只检查状态码不检查 body:catcher 未生效时默认页面也可能带同状态码。
  • 触发条件构造错误:请求实际落到路由而非 catcher。

追问

  • 如何确认响应来自自定义 catcher?答:断言错误体中自定义的错误码/文案;默认页面不含这些内容。
  • catcher 内日志如何在测试中断言?答:可捕获日志输出或检查副作用;具体方式按项目日志测试方案。

04.4.5.1-099 异步测试与测试运行时怎么组织?

一句话结论

async handler 与异步守卫的测试使用 Rocket 提供的 async 测试宏或 Tokio 测试宏,在运行时内创建异步客户端;同步客户端用于纯同步断言场景,避免在 async 上下文混用阻塞桥接。

概念解释

Rocket 0.5 基于异步运行时,测试需要在运行时内执行。#[rocket::async_test] 提供测试运行时包装;也可使用项目约定的 Tokio 测试宏。异步客户端在 async 测试函数内 .await 请求。共享测试状态跨任务时满足 Send + Sync。测试结束运行时退出,清理临时资源。

原理流程

  1. 标注测试为 async(#[rocket::async_test] 或 Tokio 宏)。
  2. 构建测试 Rocket 实例与状态。
  3. 创建异步 local client。
  4. await 请求与响应断言。
  5. 资源随测试结束释放。

代码或图示

# #[rocket::async_test]
# async fn example() {
let rocket = test_rocket();
let client = rocket::local::asynchronous::Client::tracked(rocket).await.unwrap();
let resp = client.get("/").dispatch().await;
assert_eq!(resp.status(), Status::Ok);
# }

常见误区

  • async 测试中调用阻塞客户端:运行时桥接可能报错或阻塞工作线程。
  • 测试状态跨任务共享未加同步保护:并发测试下数据竞争。

追问

  • #[rocket::async_test] 与 #[tokio::test] 区别?答:前者由 Rocket 提供并适配其运行时集成;后者是 Tokio 通用宏,可用性以版本文档为准。
  • 同步 handler 需要 async 测试吗?答:无 await 的 handler 可用阻塞客户端同步测试;路由中含异步守卫时按异步组织。

04.4.5.1-100 面试中如何讲清 Rocket 路由与守卫的设计落地?

一句话结论

按“路由模型 → 参数绑定 → 守卫分层 → 数据解析 → 错误出口 → 测试验证”的顺序讲述,每个环节落到 Rocket 具体类型与 trait,结合认证、鉴权、上传等真实场景说明取舍。

概念解释

完整回答体现从框架机制到工程落地的闭环:路由宏与 rank 决定匹配;FromParam/FromRequest/FromData 三类 trait 分别处理路径、守卫、body;错误经 Outcome 进入 catcher;测试用 local client 覆盖通过与拒绝路径。讲述时对比其他框架(如 axum 提取器)说明 Rocket 的类型化守卫特色,并指出版本敏感行为以 docs.rs 当前版本为准。

原理流程

  1. 场景:接口列表、创建、认证与文件上传需求。
  2. 路由:方法宏、URI 模板、rank 与前缀挂载。
  3. 绑定:路径参数、查询结构体、data 守卫。
  4. 守卫:认证 → 权限分层,Outcome 三态处理。
  5. 错误:catcher 统一错误体,404/422/500 定制。
  6. 测试:local client 覆盖成功、拒绝、解析失败与上传。

代码或图示

讲述闭环
路由宏与 rank → 参数三类绑定 → 守卫认证鉴权
  → FromData 解析 body → Outcome 错误流转 catcher
  → local client 测试覆盖 → 启动期校验与 Sentinel 兜底

常见误区

  • 只背 trait 名称:缺少场景落地与故障处理说明。
  • 忽略错误出口与测试:设计闭环不完整。

追问

  • 被追问守卫与中间件区别?答:守卫是类型化参数、产出 handler 值;Fairing/中间件是流程钩子,不产生参数;见 04.4.5.1-042。
  • 被追问版本不确定的 API 怎么办?答:明确标注“以 docs.rs 当前版本为准”,给出验证方式,不编造方法名与默认值。