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

04.4.3.1 路由与提取器

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

04.4.3.1-001 Router、Route 与 MethodRouter 三者是什么关系?

一句话结论

Router 是路径表加状态/中间件容器,Route 是「一个具体路径」的注册项,MethodRouter 是同一路径下按 HTTP 方法分发的分发器;Router::route(path, get(h1).post(h2)) 实际是往路径表插入一个 MethodRouter。

概念解释

axum 的核心类型是 Router<S>,泛型 S 表示该路由还依赖哪种状态才能对外服务。route 接收路径字符串与 MethodRouter<S>,把二者登记到内部的路径匹配结构;nest 生成子路由并拼接前缀,merge 只做表合并、不拼前缀。同一路径重复注册会 panic,因此同一路径的多方法要用 get(..).post(..) 链式组合,而不是两次 route。

原理流程

  1. Router::new() 建立空路径表。
  2. route(path, method_router) 解析路径模板并写入内部匹配树。
  3. MethodRouter 按 Method 保存若干 endpoint,未命中方法时返回 405。
  4. 请求到达后先做路径匹配得到 MethodRouter,再按方法分发到对应 handler。
  5. with_state 补齐状态把 Router<S> 收窄为 Router<()>,into_make_service 交给 hyper 启动服务。

代码或图示

use axum::{routing::{get, post}, Router};

async fn list() -> &'static str { "list" }
async fn create() -> &'static str { "create" }

let app = Router::new()
    .route("/items", get(list).post(create))
    .nest("/api", Router::new().route("/health", get(|| async { "ok" })));

常见误区

  • 以为 merge 与 nest 等价:merge 不拼前缀,路径冲突时直接 panic。
  • 以为同一路径第二次 route 会覆盖前一次:axum 会 panic,只能合并到同一个 MethodRouter。

追问

  • Router<S> 的 S 有什么意义?答:声明该路由还缺哪种状态,未 with_state 时无法当作 MakeService 提供服务。
  • 404 与 405 分别由谁产生?答:路径没命中返回 404,路径命中但方法不支持由 MethodRouter 返回 405。

04.4.3.1-002 FromRequestParts 与 FromRequest 两个提取器 trait 有什么区别?

一句话结论

FromRequestParts 只读请求的「不需要消费 body」的部分(方法、uri、header、路径参数、状态),FromRequest 需要拿到并消费整个 Request(含 body);因此请求体只能被消费一次,FromRequest 只能出现在 handler 参数列表的最后一位。

概念解释

axum 限制 handler 参数最多 16 个,除最后一个外都必须实现 FromRequestParts,最后一个可以实现 FromRequest。原因是 Request 的 body 是流式的、只能被读一次:FromRequest::from_request(req, state) 直接拿走整个请求;而 FromRequestParts::from_request_parts(&mut Parts, state) 只借用请求头部分,不触碰 body,所以可排在前面。

原理流程

  1. axum 生成 handler 适配器时,按参数位置拆解类型约束。
  2. 前 N-1 个参数依次调用 from_request_parts(&mut parts, state)。
  3. 最后一个参数调用 from_request(req, state),获得完整请求。
  4. 每个提取器可自定义拒绝:返回 Result<Self, Self::Rejection>,拒绝类型需实现 IntoResponse。
  5. 任一提取器返回 Err 时立即短路,后续参数不再构造。

代码或图示

use axum::{extract::{Path, State}, Json};
use serde::Deserialize;

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

// Path 实现 FromRequestParts,可以排在前面;Json 实现 FromRequest,必须在最后
async fn create(Path(id): Path<u64>, Json(body): Json<CreateUser>) -> String {
    format!("{id}:{}", body.name)
}

常见误区

  • 把 Json 提取器写在参数中间位置:编译直接报 trait 不满足。
  • 同一 handler 里放两个 body 提取器(如 Json 加 Bytes):第二个永远拿不到内容。

追问

  • 自定义提取器要先实现哪个 trait?答:不碰 body 就实现 FromRequestParts,需要 body 才实现 FromRequest。
  • 提取器拒绝如何定制状态码?答:给 Rejection 实现 IntoResponse,返回想要的 StatusCode 与错误体。

04.4.3.1-003 路径参数为什么推荐 {id} 写法,Path<T> 对 T 有什么要求?

一句话结论

{id} 是 axum 0.8 起的路径参数语法(早期为 :id),这样路径模板可以直接被 OpenAPI 工具链识别;Path<T> 要求 T 实现 Deserialize,单参数用标量类型、多参数用元组或结构体,解析失败返回 400。

概念解释

axum 把路径模板解析成捕获组,命中后把各段字符串放进 Path 提取器的参数表。Path<T> 通过 serde 的 Deserialize 完成解析:Path<u64> 走单值反序列化,Path<(u64, String)> 按位置绑定,Path<Params>(结构体字段名与占位符同名)按名字绑定。同一个模板里出现通配 *rest 时只能放在末尾。

原理流程

  1. Router::route 编译模板,生成静态段与占位段的匹配结构。
  2. 请求命中后,按占位名收集字符串切片,构造 PathDeserializer。
  3. 反序列化为 T,失败则返回 PathRejection(通常 400)。
  4. 提取器把结果放进 handler 参数,进入业务逻辑。
  5. 未声明的多余路径段不会被捕获,Path 只拿到模板里声明的部分。

代码或图示

use axum::{extract::Path, routing::get, Router};
use serde::Deserialize;

#[derive(Deserialize)]
struct Params { org: String, repo: String }

async fn repo(Path(Params { org, repo }): Path<Params>) -> String {
    format!("{org}/{repo}")
}

let app = Router::new().route("/repos/{org}/{repo}", get(repo));

常见误区

  • 沿用 /:id 写法:在 axum 0.8 之后不再匹配,请求会 404。
  • 用 Path<String> 接多段路径:只会拿到第一段,多段应使用元组或结构体。

追问

  • 路径参数里带 %2F 之类编码会怎样?答:按段解码后再反序列化,含斜杠的内容通常需要改用通配段。
  • 通配段 *rest 如何取?答:Path<String> 拿到剩余路径字符串(不含前导斜杠,具体以 docs.rs 当前版本为准)。

04.4.3.1-004 nest 的前缀拼接规则是什么?

一句话结论

nest("/api", sub) 把每个子路由路径前面拼上 /api 对外匹配;子路由内部按相对路径书写,请求进入子树时前缀已被剥离,响应不再回拼。

概念解释

nest 用于按前缀做路由分组,挂载前缀与子路径都以 / 开头;拼接后的完整路径写入父路由的匹配结构。nest 生成一个挂载点,子 Router 与父 Router 的状态类型必须兼容,否则编译报错。它和 nest_service 的区别在于后者直接挂一个现成 Service,不再经过 axum 的路径表分发。

原理流程

  1. 父 Router 记录前缀 /api 与子 Router 的匹配结构。
  2. 请求到达后先剥离 /api 前缀,剩余部分交给子 Router。
  3. 子 Router 在剩余路径上命中模板,分发到对应 handler。
  4. 响应沿调用链原路返回,不会把前缀拼回 URI。

代码或图示

use axum::{routing::get, Router};

async fn health() -> &'static str { "ok" }

let api = Router::new().route("/health", get(health));
let app = Router::new().nest("/api", api);
// 对外可访问路径为 /api/health

常见误区

  • 在子路由里再写一遍完整前缀,实际路径变成 /api/api/health。
  • 把 nest 当成 merge 的语法糖:merge 不剥前缀,nest 会剥前缀。

追问

  • 前缀不以 / 开头会怎样?答:注册行为受限,推荐始终写成 /api 这种带前导斜杠的形式,具体校验规则以 docs.rs 当前版本为准。
  • nest 后未命中由谁返回 404?答:前缀命中但子树未命中时先走子 Router 的 fallback,子树未声明再回落到父 Router 的 fallback。

04.4.3.1-005 merge 与 nest 的本质区别是什么,路径冲突时如何处理?

一句话结论

merge 只把两张路径表平铺合并、不拼前缀;nest 按前缀挂载并剥前缀。两张表出现同路径同方法注册时,axum 直接 panic,而不是静默覆盖。

概念解释

merge 适合把多个同级模块的路由表拼到同一个根下,例如 Router::new().merge(users).merge(items);nest 适合层级化的 API 分组。两者都要求被合并路由的状态类型与当前路由一致。冲突判定发生在构建 Router 时:同一路径同一方法被注册两次属于重复挂载,启动即 panic;同路径不同方法应合并进同一个 MethodRouter。

原理流程

  1. 调用 merge(other) 时遍历 other 的路径表,逐条迁入当前表。
  2. 迁入时校验路径与方法是否已存在,存在则触发 panic。
  3. nest 则把前缀与子表作为一个节点挂入当前匹配树,不做平铺。
  4. 启动前完成静态校验,因此冲突在构建期暴露,而不是请求期。

代码或图示

use axum::{routing::get, Router};

async fn list_a() -> &'static str { "a" }
async fn list_b() -> &'static str { "b" }

let users = Router::new().route("/users", get(list_a));
let items = Router::new().route("/items", get(list_b));
// 平铺合并,路径保持原样
let app = Router::new().merge(users).merge(items);

常见误区

  • 以为第二次 route 同路径会覆盖第一次:实际 panic,需要合并到同一个 MethodRouter。
  • 用 merge 拼 /api 前缀:merge 不会加前缀,要加前缀必须用 nest。

追问

  • 合并两个 Router<S1> 与 Router<S2> 有什么要求?答:泛型状态必须相同,状态不同需要先分别 with_state 收窄到 () 再合并。
  • 冲突 panic 的信息包含什么?答:会指出重复的路径与方法,便于定位是哪两次注册造成的;具体 panic 文案以当前版本源码为准。

04.4.3.1-006 fallback 如何注册,未命中路径默认返回什么?

一句话结论

Router::fallback 接收一个 handler 或 Service,作为路径表全部未命中时的兜底;不注册时 axum 返回默认 404 响应,注册后所有未匹配请求都走兜底逻辑。

概念解释

fallback 与 405 是两个层级:路径没命中由 fallback 处理,路径命中但方法不匹配仍由 MethodRouter 返回 405。fallback 可以是普通 async fn,也可以是 fallback_service 挂任意 tower Service,例如静态文件服务或 SPA 前端入口。嵌套子树有自己的 fallback 时优先用子树的,没有再向外冒泡。

原理流程

  1. 请求先在匹配树中查找路径模板。
  2. 未找到任何模板时,调用当前 Router 的 fallback。
  3. fallback 若为 async fn,同样走 handler 适配器与提取器流程。
  4. fallback_service 则直接作为 Service 被调用,跳过路径分发。

代码或图示

use axum::{http::StatusCode, routing::get, Router};

async fn not_found() -> (StatusCode, &'static str) {
    (StatusCode::NOT_FOUND, "route not found")
}

let app = Router::new()
    .route("/health", get(|| async { "ok" }))
    .fallback(not_found);

常见误区

  • 以为 fallback 也会处理 405:方法不匹配不经过 fallback,仍返回 405。
  • 在嵌套子路由里设置了 fallback,却期望它拦截父路由的未命中路径。

追问

  • fallback handler 能否使用提取器?答:可以,参数约束与普通 handler 一致,body 提取器同样只能放最后一位。
  • 如何让 fallback 服务静态目录?答:用 fallback_service 挂 tower-http 的 ServeDir 或自己实现的静态服务 crate,依赖与配置以 docs.rs 当前版本为准。

04.4.3.1-007 Router::layer 与 Router::route_layer 的作用范围有什么区别?

一句话结论

layer 包裹整个 Router,包括 fallback 与所有路由;route_layer 只包裹已注册的具体路由,fallback 不经过它。层的执行与挂载方向相反,这一点在状态与中间件主题中展开。

概念解释

两者都是在路由表外层套 tower 中间件。layer 是全局层:进入 Router 即被包裹,兜底响应也会经过;route_layer 只挂在路由节点上,未命中走 fallback 时不执行。调试、跨切面日志、统一压缩等通常放 layer;只想对业务路由做鉴权、限流而不拦截健康检查时,用 route_layer 更合适。

原理流程

  1. 调用 layer(L) 时,axum 把 L 套在整个 Router Service 外。
  2. 调用 route_layer(L) 时,L 分别套在每个已注册路由节点外。
  3. 请求先经过全局层,再进入路由匹配,命中后再经过路由层。
  4. fallback 路径只经过全局层,绕过 route_layer。

代码或图示

use axum::{routing::get, Router};
use tower_http::trace::TraceLayer;

async fn health() -> &'static str { "ok" }
async fn admin() -> &'static str { "admin" }

let app = Router::new()
    .route("/health", get(health))
    .route("/admin", get(admin))
    .layer(TraceLayer::new_for_http())      // 全局,含 fallback
    .route_layer(TraceLayer::new_for_http()); // 仅业务路由

常见误区

  • 以为 route_layer 也会记录 fallback 请求:fallback 不经过路由层。
  • 在 route_layer 里做鉴权,期望它保护静态资源兜底路由:兜底路由需要改用全局层。

追问

  • 同一层先 layer 再 route_layer,执行顺序如何?答:后挂的层更靠近路由;全局层先于路由层接触请求,具体顺序见状态共享与中间件主题。
  • MethodRouter 上有对应方法吗?答:有,MethodRouter 同样提供 layer 与 route_layer,作用于该路径下的方法分发器。

04.4.3.1-008 静态段与占位段同时命中时,路由优先级如何确定?

一句话结论

匹配树优先匹配静态字面段,再匹配占位段,通配段优先级最低;即 /users/me 比 /users/{id} 更优先,不会被占位段抢走。

概念解释

axum 底层使用 matchit 风格的参数匹配结构,段按类型分层排序:纯文本段最先尝试,{id} 捕获段其次,*rest 通配段最后。注册顺序不决定优先级,模板结构才决定。同一层级出现两个结构等价的模板(例如两个同名 {id})才会在注册期报冲突。理解优先级能避免把固定路径写成占位路径后被错误捕获。

原理流程

  1. 路径按 / 切成段序列。
  2. 匹配树在每一层先找字面段,命中则下钻。
  3. 字面段未命中再找占位段,最后才尝试通配段。
  4. 多层都命中后按完整模板选中 MethodRouter。

代码或图示

use axum::{routing::get, Router};

async fn me() -> &'static str { "me" }
async fn user(axum::extract::Path(id): axum::extract::Path<String>) -> String { id }

let app = Router::new()
    .route("/users/me", get(me))
    .route("/users/{id}", get(user));
// GET /users/me 命中静态段 me,而不是被 {id} 捕获

常见误区

  • 按注册先后判断谁先命中:先注册的静态路径不会压过后注册的占位路径,反之亦然。
  • 以为通配段可以抢在占位段前面匹配:通配段只兜底剩余部分。

追问

  • 两个占位段同名不同类型会冲突吗?答:模板结构相同即视为冲突,注册期 panic;类型解析差异发生在提取器阶段。
  • 优先级规则在当前版本有无变化?答:以 docs.rs 当前版本与底层匹配库文档为准,版本敏感行为需实际跑用例验证。

04.4.3.1-009 嵌套子路由与父路由的状态类型必须一致吗?

一句话结论

在同一个未 with_state 的 Router<S> 树内,父与子的泛型 S 必须是同一个类型;子路由想换状态类型,需要先在子树上 with_state 收窄为 () 再合并或嵌套。

概念解释

Router<S> 的 S 表示还缺哪种状态。nest、merge 组装阶段,axum 要求参与组合的 Router 状态类型对齐,否则编译期就报类型不匹配。常见做法是先把子树 with_state(app_state.clone()) 变成 Router<()>,再挂到父树上;父树最后统一 with_state。把不同子系统封装成各自构造函数时,要注意返回的是 Router<()> 还是 Router<S>。

原理流程

  1. 构造子 Router<AppState>,内部 handler 用 State<AppState> 提取。
  2. 子树调用 with_state(state.clone()),类型变为 Router<()>。
  3. 父树 Router::new().nest("/sub", sub) 或 merge(sub)。
  4. 父树最后一次 with_state 仅补齐自身仍持有的状态。

代码或图示

use axum::{extract::State, routing::get, Router};

#[derive(Clone)]
struct AppState { port: u16 }

async fn handler(State(s): State<AppState>) -> String { s.port.to_string() }

fn sub() -> Router<AppState> {
    Router::new().route("/info", get(handler))
}

let app: Router<()> = Router::new()
    .nest("/api", sub())
    .with_state(AppState { port: 8080 });

常见误区

  • 父树 Router<()> 去 nest 一个 Router<Other>,编译报状态类型不匹配。
  • 在子树里重复 with_state 后又在父树再取原状态:收窄后子树已不再持有原状态。

追问

  • 状态类型为什么要求 Clone?答:每个请求进入时都要按提取器需要克隆一份句柄,State 内部通常是 Arc,克隆只增引用计数。
  • 一个应用能否同时存在两种 State?答:可以,但需要各自 with_state 收窄后再组合,不能在同一未收窄树里混用两种泛型。

04.4.3.1-010 nest 后子 handler 看到的 URI 与 MatchedPath 分别是什么?

一句话结论

进入子树时请求 URI 的前缀已被剥离供内部匹配,但 handler 里通过 OriginalUri/Uri 仍可取到原始完整路径;MatchedPath 反映实际命中的模板,嵌套拼接后的完整匹配路径以当前版本行为为准,需用用例验证。

概念解释

axum 在嵌套挂载点把路径分段:内部匹配用剩余路径,而原始请求 URI 保留在请求里。OriginalUri 提取器拿到进入中间件链前的原始 URI,Uri 取当前请求的 URI。MatchedPath 表示命中的路由模板字符串,常用于日志记录真实路由而不是原始路径。嵌套场景下 MatchedPath 是否包含父前缀属于版本敏感行为,验证点是 docs.rs/axum/latest 的 MatchedPath 文档。

原理流程

  1. 父挂载点剥离前缀,生成内部请求继续下钻。
  2. 子树在剩余路径上命中模板,记录匹配模板。
  3. 提取器分别从 Parts 读取原始 URI、当前 URI 与匹配模板。
  4. handler 按需要取用,三者语义不同不能混用。

代码或图示

use axum::{
    extract::{MatchedPath, OriginalUri, Uri},
    routing::get, Router,
};

async fn debug(
    MatchedPath(template): MatchedPath,
    OriginalUri(orig): OriginalUri,
    Uri(cur): Uri,
) -> String {
    format!("template={template} orig={orig} cur={cur}")
}

let app = Router::new().nest("/api", Router::new().route("/v1/info", get(debug)));

常见误区

  • 把 MatchedPath 当成原始请求路径打日志:它是模板,不含路径参数具体值。
  • 以为子 handler 拿不到完整路径:原始 URI 仍可通过 OriginalUri 取得。

追问

  • OriginalUri 与 Uri 何时不同?答:中间件或嵌套节点改写过 URI 时两者不同,未改写则一致。
  • 为什么日志用 MatchedPath 更好?答:路径参数会导致日志基数爆炸,模板路径能把同类请求归并统计。

04.4.3.1-011 多层 nest 的前缀如何逐级拼接?

一句话结论

多层嵌套时前缀沿挂载链逐级拼接,外层前缀在前、内层在后;每一层只负责剥自己那一段,内层看到的是剥掉外层后的剩余路径。

概念解释

nest("/a", Router::new().nest("/b", sub)) 对外等价于 /a/b/...。嵌套层级越深,内部 handler 看到的剩余路径越短。多级拆分常用于按模块组织代码:域名级分组在最外层,业务模块在中间层,具体资源在最内层。拼接过程在路由构建期完成,运行时只做前缀剥离与下钻,不做字符串反复拼接。

原理流程

  1. 最外层记录前缀 /a,挂载中间 Router。
  2. 中间 Router 记录前缀 /b,挂载最内层子树。
  3. 请求到达先剥 /a,再剥 /b,剩余路径进最内层匹配。
  4. 任一层未命中,按该层 fallback 规则向上冒泡。

代码或图示

use axum::{routing::get, Router};

async fn detail() -> &'static str { "detail" }

let inner = Router::new().route("/detail", get(detail));
let mid = Router::new().nest("/b", inner);
let app = Router::new().nest("/a", mid);
// 对外路径为 /a/b/detail

常见误区

  • 内层路由再带上外层前缀,拼出 /a/b/b/detail。
  • 以为多层嵌套会带来运行时递归拆字符串开销:前缀在构建期固化,运行时是匹配树下钻。

追问

  • 嵌套层级很深时调试 404 看哪里?答:从外到内逐层确认前缀与子路由路径,先用最内层单独挂载验证,再逐级挂回。
  • 多级嵌套能否用 merge 替代?答:不能,merge 平铺不产生层级前缀,路径语义完全不同。

04.4.3.1-012 route_service 与 route 的区别是什么,何时直接挂 Service?

一句话结论

route 接收 MethodRouter,走 axum handler 适配与提取器;route_service 接收实现了 Service 的现成服务,直接进入 tower 服务链,不经过 axum 的参数提取流程。

概念解释

当已有一个 tower/hyper 实现好的服务(静态文件服务、反向代理、WebSocket 升级服务、第三方组件)时,用 route_service 把它挂到路径上。路径参数仍可由匹配树匹配,但请求直接交给该 Service,handler 签名与提取器对它不生效。nest_service 则是把 Service 挂到前缀下,前缀下所有路径都进入该服务。

原理流程

  1. route(path, get(handler)) 把 handler 包装成 MethodRouter 注册。
  2. route_service(path, svc) 把 svc 作为该路径的处理 Service 注册。
  3. 命中路径后,分发器直接调用 svc 的 Service::call。
  4. 中间件层在 Service 外包裹,两种挂载方式都能被层覆盖。

代码或图示

use axum::{routing::get, Router};
use tower_http::services::ServeDir;

async fn api() -> &'static str { "api" }

let app = Router::new()
    .route("/api", get(api))
    .route_service("/assets/*rest", ServeDir::new("static"));

常见误区

  • 给 route_service 的服务再配提取器:提取器只对 axum handler 生效,Service 自己读请求。
  • 以为 route_service 只支持 GET:它挂的是整个 Service,方法行为由服务自身决定。

追问

  • ServeDir 来自哪个 crate?答:tower-http,需开启 serve-dir feature;具体 feature 名以 docs.rs 当前版本为准。
  • 挂 Service 后还能用 route_layer 加层吗?答:可以,层挂在路径节点外,对 Service 同样生效。

04.4.3.1-013 with_state 做了什么类型收窄,不调用能否启动服务?

一句话结论

with_state 把 Router<S> 持有的状态注入进去,类型收窄为 Router<()>;只有 Router<()> 才能调用 into_make_service 转成 MakeService,未收窄的路由不能直接启动。

概念解释

Router<S> 的泛型 S 是编译期状态依赖标记。handler 里用 State<S> 提取器时,Router 必须持有同类型状态。with_state(state) 在构建期把状态克隆进每个需要它的节点,返回 Router<()>。这一步把运行期才缺的状态在启动前补齐,类型系统阻止你把缺状态的路由直接交给 hyper。状态类型需要 Clone + Send + Sync + 'static。

原理流程

  1. 构建 Router<AppState>,handler 通过 State<AppState> 取用状态。
  2. 调用 with_state(app_state),状态被分发给各路由节点。
  3. 泛型参数变为 Router<()>,不再声明外部依赖。
  4. into_make_service 把 Router<()> 转为 hyper 可挂载的 MakeService。

代码或图示

use axum::{extract::State, routing::get, Router};

#[derive(Clone)]
struct AppState { db_url: String }

async fn ping(State(s): State<AppState>) -> String { s.db_url }

let app: Router<()> = Router::new()
    .route("/ping", get(ping))
    .with_state(AppState { db_url: "sqlite://db.sqlite".into() });

常见误区

  • 忘记 with_state 就调 into_make_service:编译报错,提示状态类型未对齐。
  • 把状态写进全局 static 而不用 State:失去依赖注入与测试替换能力。

追问

  • 为什么状态要求 Clone 而不是只共享一份?答:axum 在构建路由与克隆服务实例时会复制句柄,内部通常用 Arc,克隆成本极低。
  • with_state 可以调用多次吗?答:可以多次收窄不同子树,但外层最终只需补自身剩余状态;重复传入的状态类型要兼容。

04.4.3.1-014 into_make_service 与 into_make_service_with_connect_info 有什么区别?

一句话结论

前者把 Router<()> 转为普通 MakeService;后者额外携带连接信息(如对端 SocketAddr),配合 ConnectInfo<T> 提取器在 handler 中读取客户端地址。

概念解释

hyper 启动服务需要一个 MakeService,即每次新连接构造一个 Service 的工厂。into_make_service 是标准转换;into_make_service_with_connect_info::<T>() 要求监听时传入的 listener 提供连接信息类型 T,通常是 SocketAddr。这样 handler 才能通过 ConnectInfo<SocketAddr> 拿到客户端 IP 与端口,用于限流、审计日志等场景。不声明连接信息类型时,ConnectInfo 提取器无法使用。

原理流程

  1. Router<()> 调用对应方法生成 MakeService。
  2. hyper 接受连接时调用工厂构造请求处理 Service。
  3. 带 connect_info 的工厂把对端地址随请求一起放入扩展。
  4. handler 用 ConnectInfo<T> 从扩展中读取该地址。

代码或图示

use axum::{extract::ConnectInfo, routing::get, Router};
use std::net::SocketAddr;

async fn who(ConnectInfo(addr): ConnectInfo<SocketAddr>) -> String {
    addr.to_string()
}

let app = Router::new().route("/who", get(who));
// 启动时使用 into_make_service_with_connect_info::<SocketAddr>()
// let svc = app.into_make_service_with_connect_info::<SocketAddr>();

常见误区

  • 用普通 into_make_service 却在 handler 里取 ConnectInfo:提取器拿不到值,运行期拒绝。
  • 泛型 T 与 listener 实际提供的连接信息类型不一致:提取器类型不匹配。

追问

  • 反向代理后 ConnectInfo 拿到的是代理 IP 还是真实客户端 IP?答:默认拿到直连对端地址,真实客户端 IP 需要从 X-Forwarded-For 等头解析,不能直接信任。
  • 不带连接信息能否取客户端地址?答:只能从请求头推断,且要在可信代理链路上解析。

04.4.3.1-015 同一路径的多个 HTTP 方法如何组合到一个 MethodRouter?

一句话结论

用 get(h1).post(h2).put(h3) 在同一个 MethodRouter 上链式挂载各方法,再由一次 route(path, method_router) 注册;不要对同一路径多次调用 route。

概念解释

MethodRouter 内部按 Method 保存 handler。get、post、put、delete、patch、head、options、trace 等构造函数各挂一个方法,链式调用累加。any 把 handler 挂到全部方法,on 接受方法数组批量挂载。同一路径第二次 route 会与已有表冲突 panic;不同方法的 handler 必须合并进同一个 MethodRouter。

原理流程

  1. get(h1) 生成只挂 GET 的 MethodRouter。
  2. .post(h2) 在其上追加 POST 分支。
  3. route(path, mr) 把该分发器登记到路径表。
  4. 请求命中路径后按方法选择分支,未登记方法返回 405。

代码或图示

use axum::{routing::{get, post}, Router};

async fn list() -> &'static str { "list" }
async fn create() -> &'static str { "create" }

let app = Router::new()
    .route("/items", get(list).post(create));

常见误区

  • 两次 route("/items", get(list)) 与 route("/items", post(create)):构建期 panic。
  • 用 any 挂全部方法后又单独挂 GET:行为以链式覆盖关系为准,需确认最终分发表。

追问

  • on 方法如何批量挂载?答:routing::on([Method::GET, Method::POST], handler) 把同一 handler 挂到列出的方法,具体签名以 docs.rs 当前版本为准。
  • 多个方法共享同一 handler 时返回类型要注意什么?答:返回值对所有方法都要实现 IntoResponse,错误分支按统一错误类型处理。

04.4.3.1-016 路径命中但方法不匹配时,405 与 Allow 头如何产生?

一句话结论

路径命中后 MethodRouter 未找到对应方法,返回 405 状态码,并通过 Allow 响应头列出该路径已注册的方法;这一分发由 MethodRouter 完成,不走 fallback。

概念解释

405 与 404 分层明确:404 是路径没匹配上,405 是路径匹配但方法未注册。MethodRouter 知道自己挂了哪些方法,拒绝时构造带 Allow 头的响应,告诉客户端允许的方法集合。Allow 头值是逗号分隔的方法名。若需要自定义 405 响应体,可在层或错误处理层统一改写,handler 本身不参与。

原理流程

  1. 路径匹配成功,取出对应 MethodRouter。
  2. 按请求 Method 查找已注册分支。
  3. 未找到则构造 405 响应,附带 Allow 头。
  4. 已找到则分发到对应 handler 执行。

代码或图示

use axum::{http::Method, routing::{get, post}, Router};

async fn list() -> &'static str { "list" }
async fn create() -> &'static str { "create" }

let app = Router::new().route("/items", get(list).post(create));
// 对 /items 发 DELETE:返回 405,Allow: GET, POST

常见误区

  • 把 405 当成 404 处理:两者产生层级不同,排错时先看状态码再看路径。
  • 以为自定义 fallback 能改写 405:fallback 只接路径未命中,405 仍由分发器产生。

追问

  • Allow 头是否包含 HEAD 等自动方法?答:以当前版本分发器实现为准,必要时抓响应头核对。
  • 如何让 405 返回统一 JSON 错误体?答:在全局层拦截 405 响应或在错误处理入口映射,业务 handler 不直接生成 405。

04.4.3.1-017 路由匹配底层用什么结构,模板在注册期做哪些校验?

一句话结论

axum 内部基于参数化路径匹配树(matchit 风格)组织模板;注册期解析占位段与通配段,发现结构等价的重复模板直接 panic,而不是等到请求期才报错。

概念解释

路径模板在构建 Router 时被解析成段序列:静态段、{id} 占位段、*rest 通配段。匹配树把同层级的段组织成可下钻结构。注册期校验包括:通配段必须在末尾、占位段命名合法、同层级不出现冲突模板。请求期只做下钻匹配,不重复解析字符串模板。理解这一点有助于把启动 panic 定位成模板冲突,而不是运行时偶发问题。

原理流程

  1. route/nest 解析路径字符串,切分出各类段。
  2. 段序列写入匹配树对应节点,冲突检查在此时进行。
  3. 构建完成后树结构冻结,请求期仅做段匹配与下钻。
  4. 非法模板或重复模板在启动构建阶段 panic。

代码或图示

use axum::{routing::get, Router};

let app = Router::new()
    .route("/users/{id}", get(|| async { "a" }))
    .route("/users/{id}/posts", get(|| async { "b" }));
// 启动期完成模板解析与冲突校验

常见误区

  • 以为模板错误会在第一次请求时暴露:多数模板冲突在构建 Router 时就 panic。
  • 在运行时动态增删路由表:axum Router 构建后是静态表,动态路由需要自己在 Service 层实现。

追问

  • 通配段不在末尾会怎样?答:模板解析不通过,属于非法模板;具体报错形式以当前版本为准。
  • 匹配库版本是否随 axum 升级变化?答:底层匹配实现属于依赖细节,版本敏感行为以 docs.rs 与 Cargo.lock 中实际依赖为准。

04.4.3.1-018 子路由的 fallback 能否覆盖父路由,嵌套内部未命中如何冒泡?

一句话结论

子路由声明的 fallback 只兜底自己子树内的未命中;子树未声明时,未命中请求向上冒泡到父路由 fallback。子路由 fallback 不会拦截父路由其他分支的请求。

概念解释

fallback 是挂载在路由节点上的兜底节点。nest 进入子树后,先在子树匹配路径,未命中先查子树 fallback;子树没设再把未命中状态返回父层,由父层 fallback 处理。这一机制让 API 子树返回 JSON 404,静态站点子树返回前端入口,互不干扰。设计时要明确每一层兜底的响应语义。

原理流程

  1. 请求进入父 Router,按前缀定位子树挂载点。
  2. 子树内路径未命中,检查子 Router 的 fallback。
  3. 子树有 fallback 则由它响应;没有则冒泡给父 Router。
  4. 父 Router 用自己的 fallback 兜底最终未命中请求。

代码或图示

use axum::{http::StatusCode, routing::get, Router};

async fn api_404() -> (StatusCode, &'static str) {
    (StatusCode::NOT_FOUND, "api not found")
}

let api = Router::new()
    .route("/health", get(|| async { "ok" }))
    .fallback(api_404);

let app = Router::new().nest("/api", api);

常见误区

  • 给子树设了 fallback,以为父路由的未命中也会走它:只在该前缀内生效。
  • 父层与子层 fallback 都返回 404 但格式不同,前端无法统一解析。

追问

  • fallback_service 参与同样的冒泡规则吗?答:参与,服务挂在兜底节点上,未命中按层级查找。
  • 想让全局未命中都返回 JSON,应把 fallback 设在哪一层?答:设在最外层根 Router,子树不再单独声明覆盖。

04.4.3.1-019 nest_service 与 nest 的区别是什么?

一句话结论

nest 挂一个子 Router,内部继续走 axum 路径表与提取器;nest_service 直接挂一个 tower Service,前缀下所有路径整体交给该服务处理,不再在 axum 内部分发。

概念解释

nest_service 适合桥接非 axum 生态的服务:静态目录服务、文件下载服务、遗留的 hyper/tower 服务。挂载后前缀被剥离,剩余路径随请求进入外部 Service。它不支持 axum 的路径提取器在挂载侧解析模板,路径规则由外部 Service 自己处理。两者都参与父层的层包裹与 fallback 冒泡。

原理流程

  1. nest_service("/static", svc) 在前缀节点登记外部 Service。
  2. 请求命中前缀后剥离前缀,剩余路径透传给 svc。
  3. svc 自己完成路径匹配、方法处理与响应构造。
  4. 父层中间件仍在 Service 外层生效。

代码或图示

use axum::Router;
use tower_http::services::ServeDir;

let app = Router::new().nest_service("/static", ServeDir::new("assets"));

常见误区

  • 给 nest_service 的服务配 axum 提取器:提取器只作用于 axum handler,外部 Service 自己读请求。
  • 以为外部 Service 未命中会自动走 axum fallback:兜底行为由该 Service 自身决定。

追问

  • ServeDir 如何处理目录索引?答:由 tower-http ServeDir 自身策略决定,可配置索引文件与缓存头,具体选项以 docs.rs 当前版本为准。
  • 能否在 nest_service 上再 route_layer?答:可以,路由层包裹挂载节点,对外部 Service 的请求同样经过。

04.4.3.1-020 子路由在什么时机绑定父状态,状态克隆发生在哪一步?

一句话结论

状态在 with_state 调用时注入到路由节点;运行期每个新连接/请求需要时由 axum 克隆状态句柄,业务代码拿到的是句柄克隆,不是整份状态深拷贝。

概念解释

Router<S> 先以缺状态形态组装,with_state 把状态分发到各节点,完成类型收窄。运行期服务工厂克隆 Router 构造连接级 Service,handler 经 State<S> 提取时再克隆状态。状态内部重资源(连接池、HTTP 客户端、配置)都应是 Arc 句柄,克隆只复制指针与引用计数。把大对象直接放进状态且不包 Arc,会造成每个处理单元重复持有重资源。

原理流程

  1. 构建期组装 Router<AppState>,登记状态需求。
  2. with_state 把一份 AppState 分发给节点引用。
  3. 运行期工厂克隆 Router,生成连接级 Service。
  4. handler 提取 State 时克隆句柄,内部 Arc 指向同一份共享资源。

代码或图示

use axum::{extract::State, routing::get, Router};
use std::sync::Arc;

#[derive(Clone)]
struct AppState {
    pool: Arc<PoolLike>,
    config: Arc<ConfigLike>,
}

struct PoolLike;
struct ConfigLike;

async fn handler(State(s): State<AppState>) -> String {
    format!("pool={}", Arc::strong_count(&s.pool))
}

let app = Router::new().route("/", get(handler));

常见误区

  • 状态里直接放大数组或无 Arc 的重对象,克隆成本随并发连接数放大。
  • 把需要随请求变化的数据塞进 State:State 是跨请求共享的,请求级数据应走 Extension 或提取器。

追问

  • 状态为什么必须 'static?答:服务生命周期长于单次请求,句柄不能借用栈上临时数据,这也是 handler 与状态约束 'static 的原因。
  • 测试时如何替换状态?答:构造不同的 AppState 实例分别 with_state,再用 oneshot 发请求断言,无需改业务代码。

04.4.3.1-021 如何把一个大 Router 拆成多个函数或模块复用?

一句话结论

按模块导出返回 Router<S> 或 Router<()> 的构造函数,在根路由 nest/merge 组合;状态类型在各模块内保持一致,最终在根层统一 with_state。

概念解释

工程上通常按业务域拆分:users::router()、orders::router() 各自返回子路由,根模块负责拼装。子函数内部定义自己的 handler 与路由表,对外只暴露 Router。返回 Router<S> 时由外层注入状态;已在模块内完成 with_state 的返回 Router<()>。拆分后模块可独立写测试,单独挂载验证路由与提取器。

原理流程

  1. 模块内定义 handler 与子 Router<AppState>。
  2. 导出 pub fn router() -> Router<AppState>。
  3. 根模块 Router::new().nest("/users", users::router())。
  4. 根层统一 with_state 并 into_make_service。

代码或图示

// src/users.rs
use axum::{extract::State, routing::get, Router};

use crate::AppState;

async fn list(State(_): State<AppState>) -> &'static str { "users" }

pub fn router() -> Router<AppState> {
    Router::new().route("/users", get(list))
}

// src/main.rs
// let app = Router::new().nest("/api", users::router()).with_state(state);

常见误区

  • 子模块返回 Router<()> 却又在 handler 里取 State<AppState>:类型对不上,编译报错。
  • 在子模块内提前 with_state 后,外层无法再按子系统替换状态做测试。

追问

  • 不同模块需要不同子状态怎么拆?答:定义统一 AppState 后各模块取自己需要的字段,或把子状态先 with_state 收窄再合并。
  • 拆分后路由前缀在哪一层决定?答:由挂载点的 nest 前缀决定,子模块路径写相对自身的部分。

04.4.3.1-022 通配段 *rest 的语法、位置约束与取值方式是什么?

一句话结论

*rest 匹配模板末尾剩余的一段或多段路径,只能放在模板最后;取值用 Path<String> 或 Path<(String, ...)> 按声明的捕获段读取,其余部分不被捕获。

概念解释

通配段用于代理前端静态资源、文件路径转发等场景:/assets/*rest 匹配 /assets/ 下任意层级路径。它必须位于模板末尾,后面不能再接静态段或占位段。命中后通配内容作为一段字符串放入路径参数表;是否保留前导斜杠属于版本敏感行为,取值后打印核对。通配段与占位段可以在同一模板中并存,但占位段在前、通配段在末。

原理流程

  1. 模板解析时记录 *rest 为末尾通配捕获。
  2. 请求路径前缀与模板前段匹配后,剩余全部路径归入通配段。
  3. 路径参数表生成时,占位段与通配段按名/位置填入。
  4. Path<T> 反序列化取对应字段。

代码或图示

use axum::{extract::Path, routing::get, Router};

async fn asset(Path(rest): Path<String>) -> String {
    rest
}

let app = Router::new().route("/assets/*rest", get(asset));
// GET /assets/css/app.css 时 rest 为剩余路径,具体前导斜杠以当前版本为准

常见误区

  • 把 *rest 写在模板中间:非法模板,注册或匹配阶段报错。
  • 用 Path<Vec<String>> 直接拿分段:axum 的 Path 反序列化目标由 T 决定,分段拆分需自己处理字符串。

追问

  • 通配段里出现编码斜杠会怎样?答:按剩余路径整体捕获,解码行为与段拆分规则以匹配库当前实现为准。
  • 通配路由与具体静态路由谁优先?答:静态与占位段优先,通配段兜底,与优先级规则一致。

04.4.3.1-023 一条模板里能否出现多个通配段,占位段有哪些字符限制?

一句话结论

一条模板只允许一个通配段且在末尾;占位段名是合法标识符形式,段内不能包含斜杠,模板段之间以 / 分隔。

概念解释

路径模板按 / 切段,占位段 {id} 对应一段路径,不能跨斜杠。多个占位段可以并列出现,如 /orgs/{org}/repos/{repo}。通配段数量限制为一个,放在最后。占位名建议使用 snake_case 标识符,避免与查询参数、结构体字段名混淆。非法命名或段结构会在模板解析阶段暴露,启动期即可发现。

原理流程

  1. 模板字符串按 / 切分。
  2. 每段判定为静态、占位或通配。
  3. 校验通配段数量与位置、占位段命名。
  4. 合法段序列写入匹配树。

代码或图示

use axum::{routing::get, Router};

let app = Router::new()
    .route("/orgs/{org}/repos/{repo}", get(|| async { "ok" }))
    .route("/files/*rest", get(|| async { "file" }));

常见误区

  • 写 /{a}/*rest/{b} 这类中间通配:结构非法。
  • 指望 {id} 匹配含 / 的值:占位段只到下一个斜杠为止。

追问

  • 占位段名与结构体字段名如何对应?答:结构体反序列化按字段名匹配占位名;元组按位置顺序绑定。
  • 模板里出现点号或连字符会被当成什么?答:属于静态段字符,原样参与字面匹配,具体允许字符集以当前版本文档为准。

04.4.3.1-024 结尾斜杠与字面斜杠如何匹配,路径大小写敏感吗?

一句话结论

axum 路径按字面段匹配,大小写敏感;结尾斜杠是否视为不同路径由匹配规则与是否挂载 NormalizePathLayer 决定,不能想当然地认为 /foo 与 /foo/ 等价。

概念解释

默认情况下路径段按字符串精确匹配,/Users 与 /users 是两个不同模板。尾斜杠行为需要区分:单纯注册 /foo 时请求 /foo/ 不一定命中,挂归一化层后可统一去掉或补上尾斜杠。生产服务常配合 NormalizePathLayer 处理尾斜杠与多余斜杠,该层属于 tower-http 中间件,在状态与中间件主题中展开。

原理流程

  1. 请求 URI 路径被切分成段序列。
  2. 匹配树按段字面比较,大小写逐字符敏感。
  3. 未挂归一化层时,尾斜杠产生空段参与匹配判断。
  4. 挂归一化层后,请求进入 Router 前路径被规范化。

代码或图示

use axum::{routing::get, Router};
use tower_http::normalize_path::NormalizePathLayer;

let app = Router::new()
    .route("/foo", get(|| async { "foo" }))
    .layer(NormalizePathLayer::trim_trailing_slash());

常见误区

  • 认为框架自动忽略尾斜杠:未挂归一化层时行为以匹配树为准。
  • 依赖大小写不敏感匹配:axum 不做大小写折叠,需要自行在层或模板层处理。

追问

  • NormalizePathLayer 有哪些归一化策略?答:可去尾斜杠或补尾斜杠等模式,具体枚举与方法名以 docs.rs/tower-http 当前版本为准。
  • 归一化层放在全局层还是路由层?答:应在路径匹配前生效,通常挂全局层最外层。

04.4.3.1-025 MatchedPath 提取器拿到的是完整模板还是裁剪后的模板?

一句话结论

MatchedPath 提取器给出本次命中的路由模板字符串(含占位符写法),用于日志与指标归类;嵌套场景下是否拼接父前缀属于版本敏感行为,需在目标版本上用用例核对。

概念解释

原始请求路径含参数具体值,直接打日志会造成高基数;MatchedPath 提供模板形式(如 /users/{id}),适合按路由聚合 tracing 事件与指标。它实现 FromRequestParts,可放在 handler 前几个参数,不消费 body。在嵌套路由中,模板拼接范围、前缀保留方式可能随版本调整,文档未明确时应写「待确认」并抓实际响应核对。

原理流程

  1. 匹配树命中节点后,把节点保存的模板字符串写入请求扩展。
  2. MatchedPath 提取器从扩展中取出模板。
  3. handler 或日志层用模板归类请求。
  4. 未命中路由时扩展中无模板,提取结果按拒绝处理。

代码或图示

use axum::{extract::MatchedPath, routing::get, Router};

async fn show(MatchedPath(template): MatchedPath) -> String {
    template
}

let app = Router::new().route("/users/{id}", get(show));
// GET /users/42 返回模板 /users/{id},而不是 /users/42

常见误区

  • 用 MatchedPath 取路径参数值:参数值要走 Path 提取器,模板里只有占位符。
  • 把嵌套场景下的模板行为当成固定结论:先写用例打印,再决定日志格式。

追问

  • MatchedPath 能否在中间件里读取?答:匹配完成后模板已写入扩展,下游中间件可从请求扩展读取;挂载在匹配前的外层中间件读不到。
  • 待确认点是什么?答:嵌套 Router 中 MatchedPath 是否包含父级前缀,验证方式为在 docs.rs/axum/latest 查 MatchedPath 文档并跑嵌套路由用例打印实际值。

04.4.3.1-026 Query<T> 提取器如何解析查询串,解析失败返回什么?

一句话结论

Query<T> 从 URL 的 ? 后查询串按 serde_urlencoded 反序列化为 T,要求 T 实现 Deserialize;解析失败返回 QueryRejection,通常映射为 400。

概念解释

查询串是 key=value&key2=value2 形式的键值对,Query<T> 把它交给 serde 的 urlencoded 反序列化器。结构体字段名对应参数名,Option<T> 字段允许缺参,Vec<T> 接收重复键。提取器只读请求部件,实现 FromRequestParts,可以排在 handler 参数前面。与 RawQuery 的区别是后者拿到原始字符串,不做反序列化。

原理流程

  1. 从请求 URI 取出原始查询串。
  2. 按 & 与 = 解析为键值对序列。
  3. 经 serde_urlencoded 反序列化为 T。
  4. 失败构造 QueryRejection,成功则作为参数传入 handler。

代码或图示

use axum::{extract::Query, routing::get, Router};
use serde::Deserialize;

#[derive(Deserialize)]
struct Page { page: Option<u32>, size: Option<u32> }

async fn list(Query(q): Query<Page>) -> String {
    format!("page={:?} size={:?}", q.page, q.size)
}

let app = Router::new().route("/items", get(list));

常见误区

  • 把必填字段声明成非 Option,缺参直接拒绝;可选参数要用 Option<T>。
  • 以为查询串是 JSON:Query 只解 urlencoded,JSON 查询体应走 body 提取器。

追问

  • 重复同名参数如何接收?答:字段声明为 Vec<T>,反序列化器把多个值收进数组;具体行为以 serde_urlencoded 当前版本为准。
  • QueryRejection 包含哪些变体?答:通常覆盖缺少参数与反序列化失败两类,变体名以 docs.rs/axum 当前版本为准。

04.4.3.1-027 Query 如何接收多值参数与可选参数,类型怎么声明?

一句话结论

可选参数用 Option<T>,多值用 Vec<T>,嵌套对象用支持 urlencoded 风格字段名的结构体;类型不匹配时反序列化拒绝。

概念解释

urlencoded 表单语义与 JSON 不同:重复键形成多值,缺失键对 Option 是 None。结构体字段直接对应顶层参数;复杂嵌套对象的字段命名约定取决于反序列化器支持,超出能力范围时应改为 body 传 JSON。设计查询 DTO 时保持扁平,避免在查询串里塞深层嵌套。数字、布尔等标量由反序列化器做字符串到类型的转换。

原理流程

  1. 解析查询串得到键值序列。
  2. Option 字段缺失填入 None,存在则解析内层类型。
  3. Vec 字段收集同名键的全部值。
  4. 标量字段从字符串反序列化为目标类型,失败拒绝。

代码或图示

use axum::{extract::Query, routing::get, Router};
use serde::Deserialize;

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

async fn search(Query(f): Query<Filter>) -> String {
    format!("tags={:?} kw={:?}", f.tag, f.keyword)
}

let app = Router::new().route("/search", get(search));

常见误区

  • 用 String 接重复键:只会拿到其中一个值,多值必须用 Vec。
  • 在查询 DTO 里放嵌套结构体并期望方括号语法:支持程度以 serde_urlencoded 实现为准,不确定就扁平展开。

追问

  • 枚举字段在查询串里怎么传?答:传枚举的 serde 表示形式(默认序列化名),传错值会反序列化失败。
  • 想校验范围与非空怎么做?答:反序列化后在 handler 或服务层做业务校验,查询提取器本身只做类型解析。

04.4.3.1-028 Form<T> 提取器要求什么 Content-Type,与 Multipart 如何分工?

一句话结论

Form<T> 处理 application/x-www-form-urlencoded 表单,反序列化为 T;文件上传类的 multipart/form-data 必须用 Multipart 提取器,两者不能互换。

概念解释

Form 与 Query 走相似的 urlencoded 反序列化,区别是数据在请求 body 里而不是查询串,因此 Form 实现 FromRequest,只能放 handler 最后一位。Content-Type 不匹配会被拒绝(通常 415)。Multipart 按分块边界解析文件与字段,适合上传二进制;普通登录表单、编辑表单用 Form,附件上传用 Multipart。

原理流程

  1. 读取请求 Content-Type,校验是否为 urlencoded。
  2. 消费 body 字节,按表单编码解析键值对。
  3. serde 反序列化为 T,失败返回 FormRejection。
  4. 成功后把结构体作为最后一个参数传入 handler。

代码或图示

use axum::{extract::Form, routing::post, Router};
use serde::Deserialize;

#[derive(Deserialize)]
struct Login { username: String, password: String }

async fn login(Form(f): Form<Login>) -> String {
    format!("hello {}", f.username)
}

let app = Router::new().route("/login", post(login));

常见误区

  • 用 Form 接 multipart/form-data:Content-Type 不匹配,直接拒绝。
  • 把 Form 放在参数中间:它消费 body,必须在最后一位。

追问

  • FormRejection 可能包含哪些失败?答:Content-Type 不符、body 读取失败、反序列化失败等,变体以当前版本文档为准。
  • 表单里同时上传文件怎么写?答:改用 Multipart,普通字段与文件分块依次遍历读取。

04.4.3.1-029 Json<T> 提取器如何工作,反序列化失败如何拒绝?

一句话结论

Json<T> 读取并解析整个请求 body 为 JSON,通过 serde 反序列化为 T;Content-Type 不符、JSON 非法或字段不匹配都会返回 JsonRejection,状态码按拒绝类型映射。

概念解释

Json 是最常用的 body 提取器,实现 FromRequest,只能放在参数最后一位。它先检查 Content-Type 是否为 JSON,再消费 body 字节交给 serde_json。T 需要 Deserialize。拒绝分几类:缺少 JSON Content-Type、body 不是合法 JSON、JSON 结构反序列化失败等。默认还有 body 大小限制,超限按拒绝或限制层处理。

原理流程

  1. 校验 Content-Type: application/json(具体可接受的子类型以当前版本为准)。
  2. 读取 body 全部字节,先过大小限制。
  3. serde_json 反序列化为 T。
  4. 任一步失败返回 JsonRejection,成功则传入 handler。

代码或图示

use axum::{extract::Json, routing::post, Router};
use serde::Deserialize;

#[derive(Deserialize)]
struct CreateItem { title: String }

async fn create(Json(body): Json<CreateItem>) -> String {
    body.title
}

let app = Router::new().route("/items", post(create));

常见误区

  • 请求没带 application/json 头也期望解析:Content-Type 校验先于 JSON 解析。
  • 一个 handler 里再放 Bytes:body 已被 Json 消费,第二个 body 提取器拿不到数据。

追问

  • Json<T> 是否要求 T 实现 Serialize?答:入参只要求 Deserialize;响应里的 Json<T> 才要求 Serialize。
  • 反序列化失败返回什么状态码?答:通常映射为 422 或 400,具体变体与状态码映射以 docs.rs 当前版本为准。

04.4.3.1-030 Json 相关的 415、422、413 分别在什么情况下出现?

一句话结论

415 是 Content-Type 不支持,422 是 JSON 语义/结构反序列化失败,413 是 body 超过大小限制;三者来源不同,排错时先对状态码定位层级。

概念解释

415 发生在媒体类型检查阶段,请求头就不对;422 发生在 JSON 解析后映射到 T 失败,例如缺字段、类型不符;413 由 body 大小限制触发,可能来自提取器默认限制或 RequestBodyLimitLayer/DefaultBodyLimit。区分状态码能快速判断是客户端头问题、载荷结构问题还是体积问题。响应体中的拒绝信息可通过自定义 Rejection 的 IntoResponse 统一成 JSON。

原理流程

  1. 提取器先查 Content-Type,不符返回 415。
  2. 读取 body 时检查大小,超限返回 413。
  3. 字节交给 serde_json 解析与映射,结构失败返回 422。
  4. 全部通过才进入 handler。

代码或图示

use axum::{extract::DefaultBodyLimit, routing::post, Router, Json};
use serde::Deserialize;

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

async fn accept(Json(p): Json<Payload>) -> String { p.name }

let app = Router::new()
    .route("/upload", post(accept))
    .layer(DefaultBodyLimit::max(1_000_000));

常见误区

  • 把 422 当 400 笼统返回:前端需要区分「格式不对」与「字段语义错误」时应保留细分状态码。
  • 只在提取器层限大小,忽略层级限制:两处限制叠加,实际阈值取更严格者。

追问

  • DefaultBodyLimit 来自哪里?答:axum 的 extract::DefaultBodyLimit,用于调整默认 body 上限;tower-http 另有 RequestBodyLimitLayer,二者行为差异以当前版本文档为准。
  • 想让大文件接口绕过默认限制怎么做?答:对该路由单独放宽或关闭默认限制,同时用 Multipart 流式处理,避免一次性读全量 body。

04.4.3.1-031 Bytes 提取器如何读取 body,与 String 提取器有何分工?

一句话结论

Bytes 把整个 body 读成 axum::body::Bytes(字节缓冲),不做编码校验;String 读取 body 后额外校验 UTF-8,非合法 UTF-8 拒绝。两者都是 body 提取器,只能放最后一位。

概念解释

需要处理原始二进制(图片、protobuf、加密载荷)时用 Bytes;只接收纯文本且要求 UTF-8 时用 String。Bytes 实现 FromRequest,读取全量 body 后缓冲在内存,超大 body 必须先限长或改用流式。String 在字节基础上做 str 转换校验,失败返回字符串相关拒绝。两者与 Json 互斥:body 只能被消费一次。

原理流程

  1. 提取器从请求中取出 body 流。
  2. 按限制读取全部字节到缓冲。
  3. Bytes 直接封装返回;String 校验 UTF-8 后转字符串。
  4. 失败返回对应 Rejection,成功传入 handler。

代码或图示

use axum::{extract::{Bytes, String as ExtractString}, routing::post, Router};

async fn raw(Bytes(b): Bytes) -> Vec<u8> { b.to_vec() }
async fn text(ExtractString(s): ExtractString) -> String { s }

let app = Router::new()
    .route("/raw", post(raw))
    .route("/text", post(text));

常见误区

  • 用 String 接二进制:UTF-8 校验失败被拒,应改用 Bytes。
  • 无限制读取大 body:内存随请求体膨胀,必须配合大小限制或流式读取。

追问

  • Bytes 与 hyper/bytes crate 的关系?答:axum 复用 bytes::Bytes 类型,零拷贝切片语义来自该 crate;类型别名以 docs.rs 当前版本为准。
  • 如何流式处理大 body 而不读全量?答:直接拿 Request<Body> 或自己实现 FromRequest,逐 chunk 处理,不要用全量缓冲提取器。

04.4.3.1-032 String 提取器的 UTF-8 校验失败返回什么,常见触发场景?

一句话结论

String 提取器在字节转字符串时校验 UTF-8,非法字节序列返回 StringRejection(通常 400);常见于客户端上传二进制却走错文本接口,或编码被中间环节破坏。

概念解释

Rust 字符串保证合法 UTF-8,因此 String 提取器不能像 Bytes 那样直接持有任意字节。校验发生在 body 读取之后、构造参数之前。若接口设计上只接收文本,校验失败是合理拒绝;若需要接收任意字节,应换成 Bytes。排错时先看请求实际 Content-Type 与 body 编码,再判断是客户端错发还是提取器选型错误。

原理流程

  1. 读取 body 全部字节。
  2. 调用 String::from_utf8 做 UTF-8 校验。
  3. 校验通过构造 String;失败返回转换错误对应的拒绝。
  4. 拒绝经 IntoResponse 映射为 HTTP 响应。

代码或图示

use axum::{extract::String as ExtractString, routing::post, Router};

async fn echo(ExtractString(body): ExtractString) -> String {
    body
}

let app = Router::new().route("/echo", post(echo));

常见误区

  • 误以为 String 提取器只做类型别名不校验:它确实做 UTF-8 校验。
  • 中文乱码归因为框架:先确认发送端编码与 Content-Type,多数乱码是客户端编码问题。

追问

  • 想接收 lossy 字符串怎么做?答:用 Bytes 取字节后自己 String::from_utf8_lossy,不要直接用 String 提取器。
  • StringRejection 变体有哪些?答:围绕 body 读取失败与 UTF-8 校验失败两类,具体变体名以当前版本文档为准。

04.4.3.1-033 HeaderMap 提取器如何读取请求头,常用头怎么取?

一句话结论

HeaderMap 提取器直接给出 http::HeaderMap,可按名读取全部请求头;常用标准头也有专门类型化提取器,避免手写字符串解析。

概念解释

HeaderMap 是 http crate 的头部集合,实现 FromRequestParts,不消费 body。手动按 headers.get("x-request-id") 取值返回 Option<&HeaderValue>,需要转字符串时再 to_str()。类型化提取器(如 TypedHeader)把常见头解析成强类型并处理拒绝。读取头时注意大小写不敏感,但 HeaderMap 内部按规范化键存储;多个同名头以迭代方式取值。

原理流程

  1. 提取器从请求 Parts 克隆或借用 HeaderMap。
  2. handler 按头名查询值。
  3. 必要时把 HeaderValue 转 &str 或字节。
  4. 业务逻辑按头值判断行为。

代码或图示

use axum::{http::HeaderMap, routing::get, Router};

async fn agent(headers: HeaderMap) -> String {
    headers.get("user-agent")
        .and_then(|v| v.to_str().ok())
        .unwrap_or("unknown")
        .to_string()
}

let app = Router::new().route("/ua", get(agent));

常见误区

  • 直接把 HeaderValue 当字符串比较:需先 to_str(),非法 UTF-8 值要按字节处理。
  • 以为头名大小写敏感:HTTP 头名大小写不敏感,取值由 HeaderMap 规范化处理。

追问

  • 如何取同名多值头?答:用 HeaderMap::get_all 返回该键的值迭代器,常见于 Set-Cookie、Accept 类头。
  • 响应头在哪里设置?答:在 handler 返回类型或响应层中写入,请求头读取不直接等于响应头设置。

04.4.3.1-034 TypedHeader 提取器如何把标准头解析成强类型?

一句话结论

TypedHeader<T> 基于 headers crate 的强类型头模型,把请求头解析为对应结构体;解析失败或缺失时返回 TypedHeaderRejection,类型由泛型 T 指定。

概念解释

手写 HeaderMap 取值需要自己处理编码、多值与格式校验;TypedHeader 复用 headers crate 预定义类型,例如 Authorization、ContentType、UserAgent 等。T 必须实现 headers::Header。它实现 FromRequestParts,可排在参数前。自定义强类型头需要为类型实现 Header trait,成本较高,内部服务常用直接读 HeaderMap。

原理流程

  1. 泛型 T 指定目标头类型。
  2. 提取器按 T 声明的头名从 HeaderMap 取值。
  3. 调用类型的解析逻辑反序列化头值。
  4. 成功传入 handler,失败返回 TypedHeaderRejection。

代码或图示

use axum::{extract::TypedHeader, routing::get, Router};
use headers::UserAgent;

async fn ua(TypedHeader(agent): TypedHeader<UserAgent>) -> String {
    agent.to_string()
}

let app = Router::new().route("/ua", get(ua));
// 依赖:headers crate,类型以 docs.rs 当前版本为准

常见误区

  • 把 headers crate 的类型与手写字符串头混用后忘记引入依赖:Cargo.toml 需要声明 headers。
  • 期望 TypedHeader 解析自定义业务头:预定义类型不含业务头,自定义需实现 Header trait。

追问

  • TypedHeaderRejection 何时触发?答:头缺失、值无法按类型解析等,具体变体以 docs.rs/axum 当前版本为准。
  • 可选标准头怎么写?答:参数用 Option<TypedHeader<H>>,缺失时为 None,存在时再解析内层。

一句话结论

CookieJar 提取器读取请求中的 Cookie 集合,handler 或响应层通过 add/remove 修改后由响应写回;它基于 cookie crate 的类型模型,请求与响应 Cookie 分开处理。

概念解释

Cookie 存储在请求头 Cookie 中,响应通过 Set-Cookie 下发。CookieJar 把请求侧 Cookie 收集成可操作集合,提取器实现 FromRequestParts。写入新 Cookie 需要把修改后的 jar 放进响应(或在支持的集成方式下由框架同步)。签名 Cookie、过期时间、路径域属性属于 cookie crate 的 Cookie 类型能力。注意不要在普通 JSON 接口里滥用 Cookie,无状态 API 常用 Bearer 头。

原理流程

  1. 从请求 Cookie 头解析各 Cookie,装入 jar。
  2. handler 通过 jar.get(name) 读取值。
  3. 修改集合:jar.add(Cookie::new(...)) 或移除条目。
  4. 响应构造阶段把变更序列化为 Set-Cookie 头。

代码或图示

use axum::{extract::CookieJar, routing::get, Router};
use cookie::Cookie;

async fn visit(jar: CookieJar) -> String {
    match jar.get("session") {
        Some(c) => c.value().to_string(),
        None => "no session".to_string(),
    }
}

let app = Router::new().route("/visit", get(visit));

常见误区

  • 以为在 jar 里 add 后自动写回:需要把 jar 纳入响应构造,具体同步方式以当前版本集成文档为准。
  • 把敏感信息明文放进 Cookie:应签名或加密,并设置 HttpOnly、Secure 等属性。

追问

  • CookieJar 与会话中间件是什么关系?答:会话中间件(如 tower-sessions)在 Cookie 之上管理服务端会话状态,CookieJar 只操作原始 Cookie。
  • 依赖里 cookie crate 需要单独声明吗?答:axum 对 cookie 类型有重导出,直接使用类型时按 docs.rs 当前版本确认是否需显式依赖 cookie。

04.4.3.1-036 Host 提取器如何获取主机名,与 Host 头有什么关系?

一句话结论

Host 提取器从请求的 authority(Host 头或 URI 权威段)取出主机部分,实现 FromRequestParts;取到的值是主机字符串,端口是否剥离取决于提取器实现,需以当前版本为准。

概念解释

Host 用于按域名分流、构造回调地址、做租户判断。直接读 Host 头需要自己拆主机与端口,Host 提取器给出解析后的值。反向代理场景下请求 Host 可能是内网地址,真实对外域名要看代理转发的头(如 X-Forwarded-Host)。提取器只负责取值,可信度判断要结合部署拓扑。

原理流程

  1. 提取器从请求 URI 或 Host 头定位 authority。
  2. 解析出主机部分(端口处理按当前版本实现)。
  3. 成功作为参数传入;缺失或非法则拒绝。
  4. handler 用主机值做分流或拼接外链。

代码或图示

use axum::{extract::Host, routing::get, Router};

async fn where_(Host(host): Host) -> String { host }

let app = Router::new().route("/where", get(where_));

常见误区

  • 直接信任 Host 头做安全决策:Host 可被客户端伪造,安全边界要基于可信代理与白名单。
  • 以为 Host 提取器带端口:端口剥离行为版本敏感,使用前打印实际值核对。

追问

  • 待确认点是什么?答:Host 提取器返回值是否包含端口,验证方式为 docs.rs/axum/latest 查 Host 提取器文档并带端口发请求断言。
  • 多域名服务如何路由?答:在中间件或 handler 按 Host 值分流,或按域名拆多个服务实例。

04.4.3.1-037 RawQuery、Uri、OriginalUri、Method 这些部件提取器各取什么?

一句话结论

RawQuery 取未解析的原始查询串,Uri 取当前请求 URI,OriginalUri 取进入链路前的原始 URI,Method 取 HTTP 方法;它们都实现 FromRequestParts,不消费 body。

概念解释

这些提取器暴露请求部件的不同侧面:需要原始串自己解析时用 RawQuery;当前链路内可能被中间件改写,Uri 反映改写后状态,OriginalUri 保留最初值。Method 常用于在同一个 handler 内区分方法,或中间件记录操作类型。选型原则:要结构化数据用对应强类型提取器,要原始值调试或兼容特殊格式时用部件提取器。

原理流程

  1. 请求进入适配器,Parts 已包含方法、URI、查询串等部件。
  2. 各提取器从 Parts 读取对应字段,不触碰 body。
  3. 中间件改写 URI 后,Uri 与 OriginalUri 出现差异。
  4. handler 按需要取用不同部件。

代码或图示

use axum::{
    extract::{OriginalUri, RawQuery, Uri},
    http::Method, routing::get, Router,
};

async fn inspect(
    Method(m): Method,
    Uri(u): Uri,
    OriginalUri(o): OriginalUri,
    RawQuery(q): RawQuery,
) -> String {
    format!("{m} {u} orig={o} q={:?}", q.0)
}

let app = Router::new().route("/inspect", get(inspect));

常见误区

  • 用 Uri 做日志原始路径:链路改写后可能不是客户端原始请求,审计日志应用 OriginalUri。
  • 把 RawQuery 当结构化参数:它是字符串,解析仍要自己做或用 Query<T>。

追问

  • RawQuery 的内部类型是什么?答:通常包装 Option<String>,空查询串为 None,具体结构以当前版本文档为准。
  • 这些提取器能放在 body 提取器后面吗?答:可以,FromRequestParts 不依赖 body 位置,但规范写法是部件参数在前、body 参数在最后。

04.4.3.1-038 ConnectInfo 提取器在 handler 与中间件中如何取用客户端连接信息?

一句话结论

ConnectInfo<T> 从请求扩展中读取连接级信息,通常是 SocketAddr;前提是启动服务时用 into_make_service_with_connect_info::<T>() 注册了对应类型,否则提取器拿不到值。

概念解释

连接信息在服务工厂构造请求 Service 时放入请求扩展,生命周期跟随一次连接。handler 用 ConnectInfo<SocketAddr> 取对端地址做限流、审计;中间件在读取扩展时同样可以取得。反向代理后面对端是代理地址,真实 IP 要解析转发链头。类型 T 必须与启动时声明的泛型一致,类型不匹配时提取器拒绝。

原理流程

  1. 启动时用带 connect_info 的工厂生成 MakeService。
  2. 新连接建立时,工厂把对端地址写入请求扩展。
  3. 提取器按类型从扩展读出 ConnectInfo<T>。
  4. handler/中间件用于日志、限流与鉴权判断。

代码或图示

use axum::{extract::ConnectInfo, routing::get, Router};
use std::net::SocketAddr;

async fn addr(ConnectInfo(peer): ConnectInfo<SocketAddr>) -> String {
    peer.to_string()
}

let app = Router::new().route("/addr", get(addr));
// 启动:app.into_make_service_with_connect_info::<SocketAddr>()

常见误区

  • 普通 into_make_service 启动却提取 ConnectInfo:扩展中无对应类型,运行期拒绝。
  • 直接把对端地址当真实客户端 IP 做风控:代理链路下需要校验转发头。

追问

  • 中间件里如何取 ConnectInfo?答:从请求扩展按类型读取,与提取器读扩展路径一致;类型不匹配时取不到。
  • 除 SocketAddr 外还能放什么连接信息?答:工厂可携带自定义连接元数据,类型 T 相应定义,以启动方式支持为准。

04.4.3.1-039 如何为只读请求部件实现自定义 FromRequestParts 提取器?

一句话结论

实现 FromRequestParts<S> trait,在 from_request_parts 中从 &mut Parts 取值并通过 State 拿状态;不需要碰 body 时优先用这个 trait,错误用关联 Rejection 类型返回。

概念解释

自定义提取器用于把重复的请求解析逻辑收敛成类型:从头解析租户、从 Cookie 解会话、组合多个头形成上下文。FromRequestParts 只借 Parts,可排在 handler 前任意位置。trait 关联类型 Rejection 需要能转成响应;最简单做法是复用 axum 现有拒绝类型或自己定义错误枚举并实现 IntoResponse。异步方法在当前 Rust 版本通过 trait 的 async 签名实现,具体语法以工具链版本为准。

原理流程

  1. 定义提取器结构体,字段装解析结果。
  2. impl FromRequestParts<S> for MyExtractor。
  3. 在方法中读 Parts 的头、URI、路径或扩展,结合 State 校验。
  4. 成功返回 Ok,失败返回 Err(Rejection)。

代码或图示

use axum::{
    extract::FromRequestParts, http::request::Parts,
    response::IntoResponse, http::StatusCode,
};

struct Tenant(String);

impl<S> FromRequestParts<S> for Tenant
where S: Send + Sync,
{
    type Rejection = (StatusCode, &'static str);

    async fn from_request_parts(
        parts: &mut Parts, _state: &S,
    ) -> Result<Self, Self::Rejection> {
        match parts.headers.get("x-tenant") {
            Some(v) => v.to_str()
                .map(|s| Tenant(s.to_string()))
                .map_err(|_| (StatusCode::BAD_REQUEST, "bad tenant")),
            None => Err((StatusCode::UNAUTHORIZED, "missing tenant")),
        }
    }
}

常见误区

  • 需要 body 却实现 FromRequestParts:拿不到 body,应改实现 FromRequest。
  • Rejection 类型没实现 IntoResponse:编译或运行期无法转成 HTTP 响应。

追问

  • 自定义提取器如何访问 State?答:trait 方法签名带 &S,按需取 State 子字段;S 约束 Send + Sync。
  • 能否复用现有提取器再包装?答:可以在自己的实现里先调用 Other::from_request_parts,再派生自定义类型。

04.4.3.1-040 如何为消费 body 的场景实现自定义 FromRequest 提取器?

一句话结论

需要读取整个请求体时实现 FromRequest<S>,在 from_request 中拿到完整 Request,消费 body 后构造类型;该提取器在 handler 参数列表中只能位于最后一位。

概念解释

FromRequest 接收 Request<Body> 所有权,可以读头也可以消费 body;典型场景是自定义二进制协议、加解密 body、压缩体解压后再解析。与 FromRequestParts 二选一:不碰 body 不要升级到 FromRequest。body 只能被读一次,自定义实现内部要先限长再缓冲,避免大 body 打满内存。拒绝类型同样需要 IntoResponse。

原理流程

  1. 定义自定义 body 类型。
  2. impl FromRequest<S> for MyBody。
  3. 方法内检查头、读取 body 字节、做协议解析。
  4. 成功返回类型,失败返回 Rejection;请求所有权被本提取器消费。

代码或图示

use axum::{
    async_trait,
    extract::FromRequest,
    http::Request,
    response::IntoResponse,
    body::Bytes,
    http::StatusCode,
};

struct Plain(Bytes);

#[async_trait]
impl<S> FromRequest<S> for Plain
where S: Send + Sync,
{
    type Rejection = (StatusCode, &'static str);

    async fn from_request(req: Request<axum::body::Body>, _: &S)
        -> Result<Self, Self::Rejection>
    {
        let bytes = axum::body::to_bytes(req.into_body(), 1_000_000)
            .await
            .map_err(|_| (StatusCode::PAYLOAD_TOO_LARGE, "body too large"))?;
        Ok(Plain(bytes))
    }
}

常见误区

  • 把 FromRequest 提取器放在参数中间:body 所有权已被取走,后续部件提取器行为异常,编译约束会拦截。
  • 不限长直接 to_bytes:恶意大 body 可耗尽内存。

追问

  • async_trait 是否仍需要?答:取决于 axum 版本对 async trait 原生支持情况,当前若签名要求则保留,以 docs.rs/axum/latest 编译示例为准。
  • 流式自定义解析怎么做?答:在实现里逐 chunk 处理 Body 的数据流,不要先 to_bytes 全量缓冲。

04.4.3.1-041 提取器的 Rejection 类型如何定制成统一错误响应?

一句话结论

为自定义 Rejection 实现 IntoResponse,在其中选择状态码与响应体;也可以把多个提取器拒绝合并成统一错误枚举,避免直接把内部类型暴露给客户端。

概念解释

Rejection 是提取器构造失败的产物,默认拒绝类型已有 IntoResponse 实现,但响应体与状态码可能不符合业务 API 规范。自定义场景常见做法:定义枚举区分缺失头、解析失败、未认证等变体,统一序列化为 JSON 错误体。提取器返回 Err(MyRejection::Xxx),框架调用其 IntoResponse 生成响应。不要在拒绝里泄露内部错误细节。

原理流程

  1. 定义错误枚举,各变体对应一类拒绝。
  2. 为枚举实现 IntoResponse,映射状态码与 JSON body。
  3. 提取器失败时返回对应变体。
  4. 框架把拒绝转成响应写回客户端。

代码或图示

use axum::{http::StatusCode, response::{IntoResponse, Response}, Json};
use serde_json::json;

enum ApiRejection {
    MissingHeader,
    BadFormat,
}

impl IntoResponse for ApiRejection {
    fn into_response(self) -> Response {
        let (status, msg) = match self {
            ApiRejection::MissingHeader => (StatusCode::UNAUTHORIZED, "missing header"),
            ApiRejection::BadFormat => (StatusCode::BAD_REQUEST, "bad format"),
        };
        (status, Json(json!({ "error": msg }))).into_response()
    }
}

常见误区

  • 直接把 Rejection 的内部 Debug 文本返回给前端:可能暴露实现细节。
  • 拒绝类型没区分场景,全部 400:前端无法按错误类型做差异化处理。

追问

  • 现有内建提取器拒绝也能改写响应吗?答:可以在全局错误映射层或 handler 入口统一处理,自定义提取器则直接实现 IntoResponse。
  • Rejection 与 handler 返回错误是什么关系?答:Rejection 发生在进入 handler 之前,handler 内部业务错误走 IntoResponse 错误类型,两段链路分开。

04.4.3.1-042 自定义提取器如何读取应用 State?

一句话结论

FromRequestParts/FromRequest 的 trait 方法都带 &S 状态参数,自定义提取器可从中取共享句柄;S 需满足 Send + Sync,访问内部可变数据要走锁或原子类型。

概念解释

提取器不止解析请求部件,还可能需要查状态里的配置、缓存或数据库句柄做校验。trait 方法第二参数就是 &S,与 handler 的 State<S> 同源。注意在提取器里不要做长时间阻塞 IO;需要异步查询时在实现内 .await。状态字段若是 Arc<Mutex<..>>,锁的类型选择要符合异步规则,避免在异步上下文持有阻塞锁。

原理流程

  1. 定义 AppState 并在路由上 with_state。
  2. 提取器实现 trait,方法签名接收 &S。
  3. 从状态取需要的字段,完成校验或预取。
  4. 构造提取器值传入 handler。

代码或图示

use axum::{
    extract::FromRequestParts, http::request::Parts,
    http::StatusCode, State,
};

#[derive(Clone)]
struct AppState { realm: String }

struct CurrentRealm(String);

impl FromRequestParts<AppState> for CurrentRealm {
    type Rejection = StatusCode;

    async fn from_request_parts(
        _parts: &mut Parts, state: &AppState,
    ) -> Result<Self, Self::Rejection> {
        Ok(CurrentRealm(state.realm.clone()))
    }
}

async fn handler(State(s): State<AppState>, realm: CurrentRealm) -> String {
    format!("{} / {}", s.realm, realm.0)
}

常见误区

  • 提取器实现写成泛型 S 却访问具体字段:类型不匹配,应直接约束 AppState 或 trait 方法化。
  • 在提取器里同步阻塞查库:阻塞异步运行时,应使用异步驱动或 spawn_blocking。

追问

  • 提取器里拿到的 State 是克隆吗?答:trait 方法给的是 &S 借用,需要持有值时再克隆句柄。
  • 提取器失败时状态资源会泄漏吗?答:状态句柄由路由与 Arc 管理,提取器短路不影响共享资源生命周期。

04.4.3.1-043 如何从已有提取器派生新提取器,而不重复解析逻辑?

一句话结论

在自定义提取器的 trait 实现内部调用现有提取器的 from_request_parts/from_request,把结果再加工成自己的类型;这样复用解析、校验与拒绝处理,只补充业务语义。

概念解释

例如业务上下文需要先取 Path 再查状态得到资源对象,或把 Json 包一层做统一字段校验。派生方式是把现有提取器作为内部步骤,成功后转换;失败时把内部 Rejection 映射成自己的拒绝类型。需要注意现有提取器若是 body 提取器,派生类型同样只能放最后一位,body 消费顺序不能颠倒。

原理流程

  1. 在实现方法中调用基础提取器的构造函数。
  2. 拿到基础值后做二次校验或转换。
  3. 内部错误映射为自定义 Rejection。
  4. 返回包装后的业务类型。

代码或图示

use axum::{
    extract::{FromRequestParts, Path},
    http::request::Parts, http::StatusCode,
    serde::Deserialize,
};

#[derive(Deserialize)]
struct Id { id: u64 }

struct ResourceId(u64);

impl FromRequestParts<()> for ResourceId {
    type Rejection = StatusCode;

    async fn from_request_parts(
        parts: &mut Parts, state: &(),
    ) -> Result<Self, Self::Rejection> {
        let Path(Id { id }) = Path::<Id>::from_request_parts(parts, state)
            .await
            .map_err(|_| StatusCode::BAD_REQUEST)?;
        if id == 0 { return Err(StatusCode::UNPROCESSABLE_ENTITY); }
        Ok(ResourceId(id))
    }
}

常见误区

  • 派生 body 提取器后又在参数里并列基础提取器:body 被消费两次,第二个拿不到。
  • 直接把内部 Rejection 透传而不映射:外部响应语义与业务错误表不一致。

追问

  • 组合多个部件提取器时顺序有约束吗?答:都实现 FromRequestParts 可按任意借用顺序调用,注意共享可变 Parts 的借用规则。
  • 派生类型能复用基础提取器的日志或拒绝信息吗?答:可以在映射时保留内部错误上下文,但对外响应需脱敏。

04.4.3.1-044 普通函数与闭包都能作为 endpoint,二者有什么区别?

一句话结论

get(..) 接受实现 Handler 的类型;具名 async fn 与捕获环境的闭包都可以,区别在于闭包通过 move 捕获外部变量并要求捕获值满足 Send + 'static,函数则从参数与 State 获取依赖。

概念解释

具名 handler 便于复用、测试与拆分,依赖通过提取器参数进入;闭包适合短生命周期的内联端点,直接捕获上下文。闭包捕获的变量会被移入服务节点,因此必须满足服务的 Send + 'static 约束。工程上业务 handler 优先用具名函数,临时探针、健康检查可用闭包。闭包不要捕获需要随请求变化的值,跨请求共享数据应放 State。

原理流程

  1. get(closure) 把闭包包装成 Handler 实现。
  2. 闭包捕获环境按 move 语义进入节点。
  3. 类型检查捕获变量 Send + 'static。
  4. 请求到达时闭包被调用,参数仍由提取器注入。

代码或图示

use axum::{routing::get, Router};

async fn named() -> &'static str { "named" }

let prefix = String::from("inline");
let app = Router::new()
    .route("/named", get(named))
    .route("/inline", get(move || async move { prefix.clone() }));

常见误区

  • 闭包借用外部局部变量而不 move:'static 检查失败。
  • 用闭包捕获可变计数器直接共享:多个请求竞争同一捕获值,需改 State 加锁。

追问

  • 闭包返回的 Future 有什么约束?答:与具名 handler 一样要求 Send + 'static,捕获值不满足会编译报错。
  • 具名函数能被多个路由复用吗?答:可以,同一 handler 可挂到多条路由;需要区分场景时用提取器读取路径或头。

04.4.3.1-045 handler 参数最多 16 个是怎么约束的,超出会怎样?

一句话结论

axum 为元组提取器实现 trait,参数个数上限为 16;超过 16 个参数的 handler 无法满足 handler 约束,编译期报错,需要把多个参数聚合成结构体提取器。

概念解释

trait 实现按元组 arity 展开:1 到 16 个参数的元组各有一份 FromRequestParts/FromRequest 实现,超过 16 没有实现。handler 适配器要求参数列表满足这些 trait bound,因此超长列表在编译期被拦截。工程上参数过多通常说明职责膨胀,应把相关请求部件聚合成一个自定义提取器结构体,而不是继续堆参数。

原理流程

  1. handler 函数被包装进 Handler 适配器。
  2. 编译器检查参数元组是否实现对应提取器 trait。
  3. arity 在 16 以内通过;超出则找不到 trait 实现。
  4. 报错指向参数元组不满足约束,需聚合参数。

代码或图示

use axum::{extract::{Path, Query, State}, Json};
use serde::Deserialize;

#[derive(Deserialize)]
struct Req { title: String }

// 参数过多时聚合为自定义提取器,避免突破 16 个参数上限
async fn handler(
    State(_): State<()>,
    Path(_): Path<u64>,
    Query(_): Query<Req>,
    Json(_): Json<Req>,
) -> &'static str { "ok" }

常见误区

  • 运行期才发现参数超限:实际是编译期 trait bound 不满足。
  • 用嵌套元组绕过限制:元组本身不被展开成多个提取器,聚合才有意义。

追问

  • 16 这个数字会随版本变化吗?答:属于 trait 元组实现数量,以 docs.rs/axum 当前版本的提取器文档为准。
  • 聚合后如何保留各字段校验?答:自定义提取器内部分步调用基础提取器,失败映射统一拒绝。

04.4.3.1-046 handler 返回值需要满足什么约束?

一句话结论

handler 返回值必须实现 IntoResponse:axum 把它转成 Response<Body>;常用标量、元组组合、Json、Response 都已有实现,自定义类型需手动实现 IntoResponse。

概念解释

handler 是异步函数,返回 impl IntoResponse。标准实现覆盖 ()、字符串、StatusCode、Json<T>、(StatusCode, T)、(StatusCode, HeaderMap, T) 等组合。自定义业务响应类型(统一错误体、分页包装)通常自己实现 IntoResponse,把内部字段序列化并设置状态码与头。返回 Response<Body> 是最底层形态,可直接构造。

原理流程

  1. handler 执行完成,得到返回值。
  2. 适配器调用 IntoResponse::into_response。
  3. 转换过程写入状态码、响应头与 body。
  4. hyper 把响应写回客户端。

代码或图示

use axum::{response::IntoResponse, http::StatusCode, Json};
use serde_json::json;

struct ApiOk<T> { data: T }

impl<T: serde::Serialize> IntoResponse for ApiOk<T> {
    fn into_response(self) -> axum::response::Response {
        (StatusCode::OK, Json(json!({ "data": self.data }))).into_response()
    }
}

async fn handler() -> ApiOk<u32> { ApiOk { data: 42 } }

常见误区

  • 自定义结构体直接当返回值却没实现 IntoResponse:编译报 trait 未实现。
  • 在返回类型里保留内部错误细节:统一响应实现时要脱敏并固定错误结构。

追问

  • Json<T> 要求 T 实现什么?答:响应侧要求 Serialize,入参 Json<T> 才要求 Deserialize。
  • 元组组合最长支持几层?答:状态码、头、body 的常见组合都有实现,具体组合形式以 docs.rs 当前版本为准。

04.4.3.1-047 为什么 handler 与状态都要求 Send + 'static?

一句话结论

hyper/tower 并发调度请求,handler 闭包与返回的 Future 必须跨线程移动(Send),且不能借用栈上临时数据('static);状态句柄同样要 Send + Sync + 'static 才能被多请求共享。

概念解释

Web 服务是多线程并发模型:任务被 spawn 到运行时工作线程,Future 可能在线程间迁移,因此必须 Send。'static 表示不持有短生命周期借用,服务存活期长于单次请求。Sync 保证状态句柄可被多线程共享访问。违反这些约束时编译器在 handler 注册或 with_state 阶段报错。业务里跨线程共享可变数据用 Arc<Mutex/RwLock> 这类 Send + Sync 结构。

原理流程

  1. handler 被包装成返回 Future 的服务节点。
  2. 类型系统检查 Future 及其捕获变量 Send + 'static。
  3. 状态在多线程间共享,检查 Send + Sync + 'static。
  4. 约束满足后才允许注册到 Router。

代码或图示

use axum::{extract::State, routing::get, Router};
use std::sync::Arc;

#[derive(Clone)]
struct AppState { counter: Arc<std::sync::atomic::AtomicU64> }

async fn tick(State(s): State<AppState>) -> String {
    s.counter.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
    "ok".into()
}

let app = Router::new().route("/tick", get(tick));

常见误区

  • handler 捕获了栈上引用:'static 检查不通过,应把持有数据 move 进闭包或放入 State。
  • 状态里放非 Sync 类型(如 Rc):多线程共享检查失败。

追问

  • 'static 不等于数据存活永久吗?答:只表示类型不含非静态生命周期借用,Arc 持有的数据仍可在引用计数归零时释放。
  • 异步锁与同步锁在 handler 里怎么选?答:异步等待用 tokio::sync 锁,短临界区避免阻塞运行时;同步锁只能保护极短非阻塞临界区。

04.4.3.1-048 同步阻塞函数能否直接作为 axum handler?

一句话结论

handler 期望返回 Future 的异步函数;普通同步函数不会被自动 .await,直接传给 get(..) 不满足 handler 约束。需要在异步 handler 内部用 spawn_blocking 包裹阻塞工作。

概念解释

axum handler 是 async fn 或返回实现 Future 的闭包。同步 CPU 密集或阻塞 IO 代码若直接写进 async handler,会卡住当前工作线程;正确做法是把阻塞操作丢到阻塞线程池(tokio::task::spawn_blocking),await 其 JoinHandle。注册阶段的 trait 检查会拒绝非异步返回的普通函数。判断标准:函数是否返回 impl Future,不是就不能直接挂路由。

原理流程

  1. get(handler) 要求 handler 实现 Handler trait。
  2. 编译器检查返回类型是否为可 await 的 Future。
  3. 同步函数不满足,编译报错。
  4. 阻塞业务放入 spawn_blocking,异步 handler await 结果。

代码或图示

use axum::{routing::get, Router};

async fn handler() -> String {
    let result = tokio::task::spawn_blocking(|| {
        // 阻塞计算或阻塞 IO 放在这里
        1 + 1
    })
    .await
    .expect("blocking task panicked");
    result.to_string()
}

let app = Router::new().route("/compute", get(handler));

常见误区

  • 在 async handler 里直接调用同步文件读写或锁阻塞等待:阻塞运行时工作线程。
  • 把 CPU 密集循环写进 async fn 却不切让出:长时间占用线程影响并发。

追问

  • spawn_blocking 返回的 JoinHandle 出错怎么处理?答:await 得到 Result,线程 panic 时为 Err,需要映射成业务错误响应。
  • 数据库驱动用同步实现行不行?答:Web 服务优先选异步驱动;被迫使用同步客户端时同样放阻塞线程池并控制并发。

04.4.3.1-049 提取器参数顺序错误的编译报错如何排查?

一句话结论

body 提取器必须在最后一位,部件提取器在前;顺序错误时编译器报 trait bound 不满足,定位方式是看参数元组缺少哪个 FromRequest/FromRequestParts 实现,再把消费 body 的类型移到末尾。

概念解释

报错信息通常围绕「the trait FromRequestParts<_> is not implemented for Json<..>」或反向约束。原因是 axum 对前 N-1 个参数要求 FromRequestParts,最后一个才允许 FromRequest。排查步骤:先找出参数列表中哪些类型消费 body(Json、Form、Bytes、String、Multipart、自定义 FromRequest),把它们移到最后;其余部件提取器顺序不强制。若同 handler 有两个 body 类型,本身就不合法。

原理流程

  1. 编译报错指向 handler 参数元组的 trait bound。
  2. 逐个参数判断实现的是哪个提取器 trait。
  3. 把 FromRequest 类型移到最后一位。
  4. 确认没有第二个 body 提取器后重新编译。

代码或图示

// 错误示范:Json 在前,Path 在后
// async fn bad(Json(b): Json<Req>, Path(id): Path<u64>) -> String { todo!() }

// 正确:Path 在前,Json 在最后
use axum::{extract::{Path, Json}, routing::post, Router};
use serde::Deserialize;

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

async fn good(Path(id): Path<u64>, Json(b): Json<Req>) -> String {
    format!("{id}:{}", b.name)
}

let app = Router::new().route("/{id}", post(good));

常见误区

  • 看到 trait 报错就去给类型手动 impl:根因是参数位置,不是缺实现。
  • 把 Form/Multipart 当成部件提取器放在前面。

追问

  • 两个提取器都需要 body 有没有合法写法?答:没有,body 只能消费一次;需要多个视图就先取 Bytes/Request 自行解析。
  • 报错里的泛型 S 对不上怎么查?答:检查 State 类型与 with_state 传入类型是否一致,状态不匹配也会表现为提取器 bound 失败。

04.4.3.1-050 handler 返回的元组组合如何映射状态码、头与 body?

一句话结论

axum 为常见元组实现 IntoResponse:(StatusCode, Body)、(StatusCode, Headers, Body)、(StatusCode, Json<T>) 等按位置解析,前位是状态码或头,末位是 body 转换目标。

概念解释

元组返回值是便捷写法:只改状态码就在前面加 StatusCode;需要带头用 HeaderMap 或元组第二位置放入类型化头。末位 body 走其自身 IntoResponse。错误返回常用 (StatusCode, Json(ErrBody))。元组层数与位置有固定约定,不要随意调换顺序。复杂响应建议封装成自定义类型实现 IntoResponse,避免散落的元组写法。

原理流程

  1. handler 返回元组。
  2. IntoResponse 实现按位置取出状态码、头、body。
  3. body 元素再转成响应体。
  4. 组合成最终 Response<Body>。

代码或图示

use axum::{http::{StatusCode, HeaderMap, HeaderName}, response::IntoResponse, Json};
use serde_json::json;

async fn created() -> impl IntoResponse {
    let mut headers = HeaderMap::new();
    headers.insert(HeaderName::from_static("x-trace"), "1".parse().unwrap());
    (StatusCode::CREATED, headers, Json(json!({ "id": 1 })))
}

let app = axum::Router::new().route("/", axum::routing::post(created));

常见误区

  • 元组位置放错:把头放状态码位置,编译类型不匹配。
  • 直接返回裸状态码却又想带 JSON body:需要用元组把两者组合。

追问

  • 如何返回纯文本带状态码?答:(StatusCode::BAD_REQUEST, "text"),字符串实现了 IntoResponse。
  • 元组组合支持哪些头类型?答:HeaderMap、类型化头迭代等形式,具体实现组合以 docs.rs 当前版本为准。

04.4.3.1-051 axum 的 body 大小限制有哪两层,如何调整默认上限?

一句话结论

axum 提取器自带默认 body 上限(DefaultBodyLimit),tower-http 的 RequestBodyLimitLayer 提供层级式请求体限制;两者叠加时实际阈值取更严格者,超大 body 触发 413 类拒绝。

概念解释

默认限制防止无界 body 打满内存:DefaultBodyLimit::max(bytes) 调整默认阈值,disable() 关闭;RequestBodyLimitLayer 挂在层上,对经过该层的请求统一限流。提取器内建限制与层限制关注点不同:前者按提取器消费行为控制,后者在进入路由前统一拦截。上传接口需要放大阈值时要同时确认两处,避免一处仍按小阈值拒绝。

原理流程

  1. 请求进入层链,RequestBodyLimitLayer 先按全局阈值拦截超限 body。
  2. 进入路由后,提取器读取 body 时再过 DefaultBodyLimit。
  3. 超限返回 413 类响应。
  4. 未超限 body 被正常解析。

代码或图示

use axum::{extract::DefaultBodyLimit, routing::post, Router};
use tower_http::limit::RequestBodyLimitLayer;

async fn accept() -> &'static str { "ok" }

let app = Router::new()
    .route("/upload", post(accept))
    .layer(DefaultBodyLimit::max(5_000_000))
    .layer(RequestBodyLimitLayer::new(5_000_000));

常见误区

  • 只调大提取器默认限制,忘记层限制:层先拦截,接口仍 413。
  • 对大文件接口关闭全部限制:缺少防护时大 body 可耗尽内存,应配合 Multipart 流式落盘。

追问

  • 两层限制阈值不一致时哪个先生效?答:层限制在进入路由前先执行,提取器限制在消费 body 时执行,整体不超过两者中更小的阈值。
  • 待确认点是什么?答:当前版本 DefaultBodyLimit 的默认字节数与拒绝状态码映射,验证方式为 docs.rs/axum/latest 查 DefaultBodyLimit。

04.4.3.1-052 Multipart 提取器如何解析 multipart/form-data 请求?

一句话结论

Multipart 提取器读取带边界(boundary)的 multipart body,按分块拆出字段与文件;它实现 FromRequest,只能放 handler 最后一位,字段需要在 handler 内逐个遍历读取。

概念解释

文件上传表单的 Content-Type 是 multipart/form-data; boundary=...,body 由多个分隔块组成,每块带头(字段名、文件名、内容类型)与内容。Multipart 提供字段流,依次取出 Field 再读字节或落盘。与 Form 的 urlencoded 不同,multipart 适合二进制与多文件。解析依赖请求头里的 boundary,Content-Type 不符或缺失 boundary 会被拒绝。

原理流程

  1. 校验 Content-Type 为 multipart 并解析 boundary。
  2. 提取器持有 body 流,生成字段迭代句柄。
  3. handler 循环 next_field() 取下一块。
  4. 每块读取文件名、字段名与字节内容。

代码或图示

use axum::{extract::Multipart, routing::post, Router};

async fn upload(mut multipart: Multipart) -> String {
    let mut count = 0;
    while let Some(field) = multipart.next_field().await.unwrap() {
        let _name = field.name().map(|s| s.to_string());
        let _file = field.file_name().map(|s| s.to_string());
        let _bytes = field.bytes().await.unwrap_or_default();
        count += 1;
    }
    format!("fields={count}")
}

let app = Router::new().route("/upload", post(upload));

常见误区

  • 用 Form 接 multipart:Content-Type 不匹配被拒。
  • 不遍历字段就直接读文件:Multipart 是流模型,必须逐个字段消费。

追问

  • next_field 返回什么错误?答:解析流异常时返回错误,具体错误类型以 docs.rs/axum 当前版本为准,需在代码中处理。
  • 一个请求能传多个文件吗?答:可以,多个文件作为同名字段或不同字段的多个分块出现,遍历全部字段即可。

04.4.3.1-053 Multipart 的 Field 提供哪些元数据与读取方法?

一句话结论

Field 暴露字段名、文件名、内容类型等元数据,以及读取字节流的方法;文件名字符串可能含客户端构造值,落盘前必须做安全校验。

概念解释

每个分块对应一个 Field:name() 取表单字段名,file_name() 取客户端声称的文件名,content_type() 取 MIME 类型,bytes() 读取剩余字节,stream 方式可逐块读取。文件名来自客户端,不能直接拼进磁盘路径,否则存在路径穿越风险。元数据缺失时返回 None,业务上要区分普通字段与文件字段。

原理流程

  1. next_field() 返回当前分块的 Field。
  2. 读取分块头得到字段名、文件名、内容类型。
  3. 按字段类型选择读全量字节或流式处理。
  4. 处理完进入下一分块。

代码或图示

use axum::extract::Multipart;

async fn inspect(mut mp: Multipart) -> String {
    let mut out = String::new();
    while let Some(f) = mp.next_field().await.unwrap() {
        out.push_str(&format!(
            "field={:?} file={:?} type={:?}\n",
            f.name(), f.file_name(), f.content_type()
        ));
    }
    out
}

常见误区

  • 直接用 file_name() 拼保存路径:未过滤 .. 与分隔符可写出上传目录。
  • 把 file_name() 当可信身份信息:客户端可任意构造,仅作展示或二次校验。

追问

  • 如何只处理文件字段、跳过普通字段?答:判断 file_name() 是否为 Some,普通文本字段继续读取其字节后跳过。
  • 大文件如何避免一次性 bytes() 入内存?答:按 chunk 流式写入目标文件,Field 的流式读取能力以当前版本文档为准。

04.4.3.1-054 文件上传落盘如何避免路径穿越与覆盖风险?

一句话结论

落盘路径必须基于服务端固定目录拼接,文件名只取安全部分(去除目录分隔符与 ..),必要时用服务端生成的文件名;同时限制大小、类型与并发写入。

概念解释

客户端文件名可能含 ../、绝对路径或特殊字符,直接拼接会写到上传目录之外。安全做法:定义上传根目录,剥离文件名中的路径成分,生成随机文件名或 UUID 保存,原始名仅存数据库记录。类型校验看内容而非仅扩展名,大小限制在层与 Multipart 读取两处控制。落盘用异步文件操作,避免阻塞运行时。

原理流程

  1. 读取字段字节或流式内容。
  2. 清洗文件名:去掉分隔符、..、控制字符。
  3. 生成服务端安全文件名,拼接到固定根目录并校验规范化后仍在目录内。
  4. 写入文件并记录元数据。

代码或图示

use axum::extract::Multipart;
use std::path::Path;

fn safe_name(raw: &str) -> String {
    raw.split('/').next_back().unwrap_or("file")
        .replace("..", "")
}

async fn save(mut mp: Multipart) -> String {
    let root = Path::new("uploads");
    while let Some(f) = mp.next_field().await.unwrap() {
        let name = safe_name(f.file_name().unwrap_or("file"));
        let dest = root.join(&name);
        let bytes = f.bytes().await.unwrap_or_default();
        tokio::fs::write(&dest, bytes).await.ok();
    }
    "saved".into()
}

常见误区

  • 直接 root.join(client_filename) 不做规范化校验:穿越风险。
  • 信任扩展名判断文件类型:应嗅探内容或限制允许的 MIME 白名单。

追问

  • 如何校验最终路径仍在根目录内?答:对拼接结果做 canonicalize 或路径前缀比较,确认未逃逸到上级目录。
  • 同名文件如何处理?答:用随机 UUID 或时间戳重命名,避免覆盖已有文件;覆盖策略按业务设计。

04.4.3.1-055 Multipart 上传如何做大小限制与流式处理?

一句话结论

全局用 RequestBodyLimitLayer 或 DefaultBodyLimit 控制总 body 上限,字段级在读取时逐块检查累计字节;超大文件应流式落盘,不要把整个分块读进内存。

概念解释

上传接口最容易被大 body 打垮:总限制在层与提取器默认限制处设置,单字段大小在遍历 Field 时累计判断。流式处理把分块内容边读边写目标文件,内存占用稳定;全量 bytes() 适合小附件,大文件必须走流。还要限制字段数量与请求并发,避免多字段耗尽资源。

原理流程

  1. 层限制先拦截超限总 body。
  2. 遍历字段时累计每个字段字节数,超限提前中止。
  3. 大字段按 chunk 写入文件,小字段读入内存。
  4. 处理结束返回结果或拒绝。

代码或图示

use axum::{extract::Multipart, routing::post, Router};
use tower_http::limit::RequestBodyLimitLayer;

const MAX: usize = 5_000_000;

async fn upload(mut mp: Multipart) -> &'static str {
    while let Some(f) = mp.next_field().await.unwrap() {
        let data = f.bytes().await.unwrap_or_default();
        if data.len() > MAX {
            return "too large";
        }
        // 写入逻辑略
    }
    "ok"
}

let app = Router::new()
    .route("/upload", post(upload))
    .layer(RequestBodyLimitLayer::new(MAX));

常见误区

  • 只设总限制不查单字段:单个超大字段仍可占满内存。
  • 所有字段都 bytes() 全量读取:大文件场景内存随文件大小膨胀。

追问

  • 流式写文件用什么异步 API?答:tokio::fs::File 与 tokio::io::AsyncWriteExt,按 chunk 写入;依赖以当前工程为准。
  • 限制超限后已上传的部分如何处理?答:中止遍历并返回错误,临时文件按需清理,避免残留半截文件。

04.4.3.1-056 普通表单、JSON 表单与文件上传的提取器如何选择?

一句话结论

application/x-www-form-urlencoded 用 Form<T>,application/json 用 Json<T>,multipart/form-data 用 Multipart;按 Content-Type 选提取器,选错会被 415 拒绝。

概念解释

三种 body 编码对应三种提取器:urlencoded 是键值对文本,JSON 是结构化对象,multipart 是带边界的分块流。浏览器原生表单可提交前两种编码之一,文件控件必须 multipart。API 服务间调用通常 JSON,后台管理页面表单可能 urlencoded。提取器选型先看请求实际 Content-Type,再看是否需要二进制。一个 handler 只消费一种 body 编码。

原理流程

  1. 读取请求 Content-Type。
  2. 按编码类别选择对应提取器。
  3. 提取器校验类型并解析 body。
  4. 解析结果进入 handler。

代码或图示

use axum::{extract::{Form, Json, Multipart}, routing::post, Router};
use serde::Deserialize;

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

async fn json(Json(_): Json<Req>) -> &'static str { "json" }
async fn form(Form(_): Form<Req>) -> &'static str { "form" }
async fn multi(_: Multipart) -> &'static str { "multi" }

let app = Router::new()
    .route("/json", post(json))
    .route("/form", post(form))
    .route("/multi", post(multi));

常见误区

  • 前端表单 enctype 与后端提取器不一致:415 拒绝。
  • 想在一个接口同时收 JSON 与文件:应拆成两个接口或用 Multipart 内嵌 JSON 字段。

追问

  • 同一资源按 Content-Type 分流到不同 handler 怎么做?答:注册同路径不同方法分发器无法按媒体类型分流,可在 handler 内读 Content-Type 后分别解析,或拆路径。
  • 表单字段值类型如何转换?答:urlencoded 与 JSON 都经 serde 反序列化,数字、布尔按目标类型解析。

04.4.3.1-057 axum 是否内置「方法覆盖」(method override)支持?

一句话结论

axum 路由按请求行的 Method 分发,不内置从表单字段或头改写方法的机制;需要 method override 时要在自定义层里改写请求方法,再进入路由匹配。

概念解释

部分旧浏览器或表单只支持 GET/POST,框架常通过 _method 字段或 X-HTTP-Method-Override 头把 POST 改写成 PUT/DELETE。axum 本身不提供该中间件,路由表看到的是原始方法。实现方式:在全局层读取覆盖头/字段,修改 Request 的方法后继续调用内层服务。注意只允许覆盖到安全方法集合,避免把 POST 任意改写成危险方法。

原理流程

  1. 请求进入自定义层。
  2. 检查覆盖头或表单字段是否存在合法方法。
  3. 合法则改写请求 Method。
  4. 内层 Router 按改写后的方法分发。

代码或图示

use axum::{http::Request, routing::get, Router};
use tower::ServiceExt;

// 示意:层内读取 x-http-method-override 并改写方法
async fn override_method<B>(req: Request<B>, next: axum::middleware::Next<B>)
    -> axum::response::Response
{
    if let Some(m) = req.headers().get("x-http-method-override") {
        if let Ok(method) = m.to_str().and_then(|s| s.parse()) {
            let mut parts = req.into_parts();
            parts.method = method;
            let req = Request::from_parts(parts, req.into_body());
            return next.run(req).await;
        }
    }
    next.run(req).await
}

let app = Router::new().route("/item", get(|| async { "ok" }));

常见误区

  • 以为 axum 自动识别 _method 表单字段:没有内建行为,需自行实现。
  • 允许覆盖到任意方法:应限制白名单,避免方法语义被滥用。

追问

  • 改写方法后 405 由谁产生?答:内层 MethodRouter 按改写后的方法分发,未注册仍返回 405。
  • 待确认点是什么?答:当前 axum 版本是否提供官方 method override 组件,验证方式为 docs.rs/axum/latest 查中间件与提取器列表。

04.4.3.1-058 OPTIONS 请求与 CORS 预检在路由层是什么关系?

一句话结论

OPTIONS 只是一个普通 HTTP 方法,路由表可单独注册 handler;跨域预检(preflight)由浏览器自动发起,通常由 CorsLayer 直接响应,不一定要业务路由注册 OPTIONS。

概念解释

跨域场景下浏览器先发 OPTIONS 预检,询问服务端允许的方法、头与来源。CorsLayer 在层链中识别预检请求并直接返回带 CORS 头的响应,业务路由无需为每个接口写 OPTIONS handler。若未挂 CORS 层,OPTIONS 命中路径但未注册该方法会返回 405。区分两种 OPTIONS:业务自定义的 OPTIONS 接口走路由分发,预检请求由层短路处理。

原理流程

  1. 浏览器判断跨域,先发送 OPTIONS 预检。
  2. CorsLayer 检查Origin、方法、头,生成预检响应。
  3. 预检通过后浏览器再发实际请求。
  4. 未挂层时 OPTIONS 按普通方法进入 MethodRouter 分发。

代码或图示

use axum::{routing::get, Router};
use tower_http::cors::{CorsLayer, Any};

let app = Router::new()
    .route("/items", get(|| async { "items" }))
    .layer(CorsLayer::new()
        .allow_origin(Any)
        .allow_methods(Any)
        .allow_headers(Any));

常见误区

  • 为每个接口手写 OPTIONS handler 处理预检:CORS 层已覆盖,重复处理易冲突。
  • 预检通过后实际请求仍被跨域拦:实际响应缺少 CORS 头,层配置要覆盖真实响应。

追问

  • CorsLayer 的 credentials 与 origin 通配能同时用吗?答:浏览器规范限制携带凭证时不能用通配来源,配置需按规范收敛;具体以 tower-http 当前版本与浏览器行为为准。
  • 预检缓存如何配置?答:通过 CORS 层的 max-age 选项控制预检结果缓存时长,配置项名以 docs.rs/tower-http 当前版本为准。

04.4.3.1-059 未注册方法的请求除了 405 还能怎样处理,如何统一改写?

一句话结论

默认由 MethodRouter 返回 405 并带 Allow 头;需要统一 JSON 错误体时,在全局层拦截 405 响应改写,或在错误处理入口映射,业务 handler 不直接生成 405。

概念解释

405 是分发器产物,handler 感知不到未注册方法。统一 API 风格要求所有错误返回 JSON 结构时,405 响应也要被改写。层可以在响应返回后检查状态码与 Allow 头,替换 body。另一种方式是挂兜底方法处理器,但会改变 405 语义,需谨慎。测试时应同时覆盖已注册方法与未注册方法两种响应。

原理流程

  1. 路径命中,方法未注册,分发器生成 405 响应。
  2. 响应沿层链回传,外层层识别 405。
  3. 层把 body 替换为统一错误 JSON,保留或补充 Allow。
  4. 客户端收到规范错误体。

代码或图示

use axum::{http::StatusCode, response::Response, routing::get, Router};

async fn rewrite(mut resp: Response) -> Response {
    if resp.status() == StatusCode::METHOD_NOT_ALLOWED {
        *resp.body_mut() = axum::body::Body::from(r#"{"error":"method not allowed"}"#);
    }
    resp
}

let app = Router::new().route("/items", get(|| async { "items" }));
// rewrite 经 map_response 或自定义层挂到全局,层写法见中间件主题

常见误区

  • 在 fallback 里改 405:fallback 接不住 405,位置不对。
  • 改写时丢掉 Allow 头:客户端无法知道支持哪些方法,应保留。

追问

  • 405 与 404 在层里如何区分?答:按响应状态码判断,405 路径已命中、404 未命中,处理策略可不同。
  • 能否让未注册方法也走统一错误类型?答:可以,层映射与错误类型约定保持一致即可。

04.4.3.1-060 Router 本身是不是 Service,它如何进入 tower 服务链?

一句话结论

Router<()> 实现了 tower Service,可以被层包裹;启动时 into_make_service 把它转成 MakeService,由 hyper 每连接构造一个服务实例。

概念解释

axum 建立在 tower 抽象之上:Service 是「接受请求、返回响应 Future」的核心 trait,Layer 负责包裹服务。Router 内部聚合路径表与各节点服务,对外呈现为一个 Service。Router<S> 未收窄状态时不能直接作为对外服务;with_state 后得到 Router<()>,再转换。理解这层关系后,层挂载、自定义服务、测试 oneshot 都落在 tower 抽象上。

原理流程

  1. 组装 Router<S> 并 with_state 收窄为 Router<()>。
  2. Router<()> 实现 Service<Request<Body>>。
  3. into_make_service 生成克隆 Router 的 MakeService。
  4. hyper 接受连接后调用工厂生成请求处理 Service。

代码或图示

use axum::{routing::get, Router};

let app = Router::new().route("/", get(|| async { "ok" }));
// Router<()> 可被 tower Layer 包裹
let make_svc = app.into_make_service();
// hyper::Server::bind(&addr).serve(make_svc)

常见误区

  • 以为 Router 直接监听端口:它只是服务抽象,监听由 hyper Server 完成。
  • 未 with_state 就尝试当 Service 使用:泛型状态未收窄,类型不满足。

追问

  • Service trait 的核心方法是什么?答:poll_ready 与 call,tower 服务先确认就绪再处理请求,模型在 hyper/tower 主题展开。
  • Router 克隆后各实例共享状态吗?答:克隆的是句柄,内部 Arc 指向共享资源,业务数据不复制。

04.4.3.1-061 into_service 与 into_make_service 的转换路径有什么区别?

一句话结论

into_service 把 Router 直接转成单个 Service;into_make_service 转成 MakeService 工厂,由 hyper 为每个连接克隆出 Service。测试里 oneshot 通常直接用 Service,生产监听用 MakeService。

概念解释

MakeService 是服务工厂:新连接到来时 make_service 被调用,克隆 Router 生成独立 Service。直接 into_service 得到的单个 Service 适合一次性请求测试或嵌入其它服务。生产 Server::serve 要求 MakeService 类型。两者来源都是 Router<()>,状态句柄在克隆间共享。

原理流程

  1. Router<()> 调用 into_service 得到 Service。
  2. 或调用 into_make_service 得到工厂。
  3. 测试用 ServiceExt::oneshot 直接对 Service 发一次请求。
  4. 生产由 hyper 反复调用工厂生成连接级 Service。

代码或图示

use axum::{routing::get, Router};
use tower::ServiceExt;

let app = Router::new().route("/", get(|| async { "ok" }));

// 测试:直接转 Service 发一次请求
let svc = app.into_service();
let resp = svc.oneshot(axum::http::Request::new("".into())).await.unwrap();

常见误区

  • 测试里走 MakeService 再手动调工厂:多此一举,oneshot 直接用 Service 即可。
  • 把单例 Service 用于多连接:连接级状态隔离由工厂克隆保证。

追问

  • into_make_service_with_connect_info 与普通工厂差在哪?答:额外携带连接信息类型,供 ConnectInfo 提取器读取。
  • Service 是否需要手动克隆?答:MakeService 内部处理克隆,业务代码不直接操作。

04.4.3.1-062 MakeService 在 Web 服务模型中承担什么角色?

一句话结论

MakeService 是「为每个新连接构造一个 Service」的工厂 trait;hyper 接受 TCP 连接后调用它生成请求处理器,Router 通过 into_make_service 实现该抽象。

概念解释

tower 把「服务工厂」与「服务实例」分开:Service 处理一次或多次请求,MakeService 负责按需生产 Service。axum Router 内部可克隆,工厂克隆 Router 即可得到新实例。连接级的临时状态放在由工厂产出的 Service 上,跨连接共享数据仍走 State。理解工厂模型有助于解释为什么状态句柄要 Clone,以及测试为何能绕过工厂直接 oneshot。

原理流程

  1. hyper 监听到新连接。
  2. 调用 MakeService 生成该连接的 Service。
  3. 连接内多个请求由同一 Service 处理。
  4. 连接关闭后实例销毁,共享资源由 State 句柄回收。

代码或图示

use axum::{routing::get, Router};

let app = Router::new().route("/", get(|| async { "ok" }));
let make_svc = app.into_make_service();
// Server::bind(&addr).serve(make_svc) 为每个连接调用工厂

常见误区

  • 把 MakeService 当成处理请求的 Service:它只负责生产实例。
  • 在工厂产出前假设已有请求上下文:连接信息在工厂生成 Service 时注入。

追问

  • MakeService 的 trait 方法是什么?答:make_service 返回产出 Service 的 Future,具体签名以 tower crate 当前版本为准。
  • 连接级状态放哪里?答:可在自定义服务或层里按连接持有,Router State 是跨连接共享的。

04.4.3.1-063 把自定义 Service 挂到路由上需要满足哪些 trait 约束?

一句话结论

route_service/nest_service 接收实现 tower Service<Request<Body>> 的类型,响应体需可转成 axum 响应;通常还要满足 Clone + Send + 'static 以接入并发服务链。

概念解释

自定义 Service 封装了请求处理逻辑:实现 Service trait 的 poll_ready 与 call,返回响应 Future。挂到 axum 路由后,层链与工厂克隆机制同样适用。Service 的错误类型一般要能转成响应,避免向 hyper 抛出未处理错误。已有 tower 中间件或第三方服务多数已满足约束,直接挂载即可。

原理流程

  1. 定义结构体实现 Service<Request<Body>>。
  2. poll_ready 报告是否可接收请求。
  3. call 处理请求,返回响应 Future。
  4. route_service 把该 Service 登记到路径节点。

代码或图示

use axum::{Router, body::Body, http::Request, response::Response};
use std::future::Future;

struct EchoService;

impl tower::Service<Request<Body>> for EchoService {
    type Response = Response<Body>;
    type Error = std::convert::Infallible;
    type Future = std::pin::Pin<Box<dyn Future<Output = Result<Response<Body>, Self::Error>> + Send>>;

    fn poll_ready(&mut self, _cx: &mut std::task::Context<'_>) -> std::task::Poll<Result<(), Self::Error>> {
        std::task::Poll::Ready(Ok(()))
    }

    fn call(&mut self, _req: Request<Body>) -> Self::Future {
        Box::pin(async { Ok(Response::new(Body::from("echo"))) })
    }
}

let app = Router::new().route_service("/echo", EchoService);

常见误区

  • Service 的 Future 不 Send:无法跨线程调度,编译报错。
  • 错误类型未处理:运行期错误直接冒泡到 hyper,响应不可控。

追问

  • 自定义 Service 如何读取 State?答:Service 在构造时由外层传入状态句柄,或从请求扩展读取;Router 提取器机制对裸 Service 不生效。
  • 已有 tower 服务能否直接挂?答:满足 Service 约束即可,例如 ServeDir,通常无需自己实现 trait。

04.4.3.1-064 tower Service 的 poll_ready 与 call 模型是什么?

一句话结论

tower::Service 先由 poll_ready 报告是否可接收请求,就绪后 call 取出请求并返回响应 Future;这是 tower 中间件与 axum 路由共用的调度模型。

概念解释

poll_ready 让服务在背压场景下声明暂不可用,调用方先等待就绪;call 消费请求所有权,返回一个 Future。中间件包裹外层 Service 时,两个方法都透传或增强。axum Router 本身也是该模型的一个 Service。理解 poll_ready 有助于看懂限流、并发限制等层的工作方式,而不必把所有逻辑都塞进 handler。

原理流程

  1. 调用方先轮询 poll_ready,未就绪则挂起等待通知。
  2. 就绪后调用 call(req) 取得响应 Future。
  3. Future 被调度执行,最终产出响应。
  4. 中间件在外层包装这两个方法,加入日志、超时、鉴权等逻辑。

代码或图示

use tower::Service;
use std::{future::Future, pin::Pin, task::{Context, Poll}};

# struct Svc;
# impl Service<axum::http::Request<axum::body::Body>> for Svc {
#     type Response = axum::response::Response;
#     type Error = std::convert::Infallible;
#     type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>> + Send>>;
#     fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { Poll::Ready(Ok(())) }
#     fn call(&mut self, req: axum::http::Request<axum::body::Body>) -> Self::Future { todo!() }
# }

常见误区

  • 把 call 当成同步函数:它返回 Future,响应要 await 才产出。
  • 忽略 poll_ready 直接并发 call:背压层依赖就绪信号控制并发。

追问

  • poll_ready 未就绪时调用方怎么等?答:通过 waker 注册等待,就绪后被唤醒再重试,具体由 tower 调度机制处理。
  • 该模型与 axum handler 的关系?答:handler 适配器最终被包装成实现 Service 的节点,路由匹配后调用其 call。

04.4.3.1-065 Router::layer 是如何把服务包成层链的?

一句话结论

layer(L) 调用 Layer::layer 把当前 Router Service 包在 L 内,返回新的 Router;多个层链式调用时,后挂的层更靠近内层服务,请求穿过层链到达路由。

概念解释

层是对 Service 的装饰:每层接收请求、做处理、调用内层 call、再加工响应。Router 记录待挂载的层序列,在转成 MakeService/Service 时逐层包裹。层顺序决定谁先接触请求,这是中间件主题的核心。route_layer 只包裹路由节点,layer 包裹整体。层本身需要实现 tower::Layer。

原理流程

  1. 调用 layer(L),把 L 加入 Router 的层序列。
  2. 转换 Service 时按序列逐层包裹:外层先入。
  3. 请求沿外层到内层穿过各层。
  4. 响应沿内层到外层回传,各层可改写响应。

代码或图示

use axum::{routing::get, Router};
use tower_http::trace::TraceLayer;

let app = Router::new()
    .route("/", get(|| async { "ok" }))
    .layer(TraceLayer::new_for_http());

常见误区

  • 认为层按挂载先后从内到外执行请求:实际外层先接触请求,顺序需按包裹方向判断。
  • 把状态相关层挂在未收窄 Router 上导致类型不匹配:先确认状态类型兼容。

追问

  • 层序列在嵌套子路由中如何继承?答:子路由可自带层,父层在外层包裹,具体叠加行为在中间件主题展开。
  • 自定义层实现哪个 trait?答:tower::Layer<Svc>,layer 方法返回包裹后的服务类型。

04.4.3.1-066 路由单元测试的最小写法是什么,如何用 oneshot 发请求?

一句话结论

把 Router 转成 Service,用 tower::ServiceExt::oneshot 发一个构造好的 Request,await 得到响应;无需启动监听端口,即可验证路由与提取器行为。

概念解释

集成测试不必绑定真实端口:Router<()>::into_service 得到 Service,oneshot 消费一次请求返回响应。请求用 Request::builder 构造方法、路径、头与 body。断言状态码与 body 内容即可覆盖命中、拒绝、404 等路径。带状态的路由先构造 State 再 with_state。这是 axum 官方推荐的测试形态之一。

原理流程

  1. 构造 Router 与所需 State。
  2. into_service 得到测试 Service。
  3. Request::builder 组装请求,oneshot 发送。
  4. await 响应并断言状态码、头、body。

代码或图示

use axum::{body::Body, http::Request, routing::get, Router};
use tower::ServiceExt;

async fn hello() -> &'static str { "hi" }

#[tokio::test]
async fn route_works() {
    let app = Router::new().route("/", get(hello));
    let resp = app
        .into_service()
        .oneshot(Request::builder().uri("/").body(Body::empty()).unwrap())
        .await
        .unwrap();
    assert_eq!(resp.status(), axum::http::StatusCode::OK);
}

常见误区

  • 测试里真正 Server::bind 占端口:增加不确定性,oneshot 足够覆盖路由逻辑。
  • 忘记 into_service 直接对 Router 调 oneshot:类型不对,需先转换。

追问

  • 依赖 tower 的哪个 trait 方法?答:ServiceExt::oneshot,需要在 Cargo.toml 引入 tower 并启用相应 feature。
  • 多个测试复用同一 Router 吗?答:每个测试可独立构造,State 句柄按需克隆,避免测试间共享可变状态。

04.4.3.1-067 测试中如何断言响应状态码、头与 body 内容?

一句话结论

从响应取 status() 断言状态码,headers() 断言头,body 用 axum::body::to_bytes 读取后转字符串或 JSON 再比较。

概念解释

Response<Body> 分离状态、头与 body:状态码直接可读,头按名查询;body 是流,必须异步聚合为字节缓冲后断言。JSON 响应可把字节反序列化为结构体比较,文本响应直接转字符串。断言失败时打印实际状态与 body,便于定位。测试要覆盖成功与拒绝两类路径,不能只测 happy path。

原理流程

  1. oneshot 得到 Response<Body>。
  2. 断言 resp.status() 与期望状态码。
  3. 查询响应头断言关键头存在或取值。
  4. to_bytes 聚合 body,反序列化后断言字段。

代码或图示

use axum::{body::Body, http::Request, routing::get, Router, http::StatusCode};
use tower::ServiceExt;

#[tokio::test]
async fn body_check() {
    let app = Router::new().route("/", get(|| async { "hi" }));
    let resp = app.into_service()
        .oneshot(Request::builder().uri("/").body(Body::empty()).unwrap())
        .await.unwrap();
    assert_eq!(resp.status(), StatusCode::OK);
    let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX).await.unwrap();
    assert_eq!(bytes, "hi");
}

常见误区

  • 直接把 Body 当字符串比较:Body 是流,必须先聚合。
  • 只断言状态码不断言 body:可能状态对而响应体错误。

追问

  • JSON 响应怎么结构化断言?答:to_bytes 后 serde_json::from_slice 解析为 DTO,再比较字段。
  • body 聚合有大小限制吗?答:测试传入的限额按调用处设置,避免测试用例无限读 body。

04.4.3.1-068 带 State 的路由在测试中如何构造与替换?

一句话结论

测试里构造所需 AppState 实例,Router 经 with_state(state) 收窄后转 Service;不同用例可传入不同状态(含测试替身),业务代码无需改动。

概念解释

State 注入正是为了可测试:生产注入真实连接池与配置,测试注入内存替身或最小配置。构造 Router 的函数接收 State 或返回 Router<S>,测试组装时传入测试实例。若状态持有 trait 对象或异步客户端,可在测试中替换为假实现。注意状态类型仍需 Clone + Send + Sync + 'static,测试替身也要满足。

原理流程

  1. 定义测试用 AppState(可含内存替身)。
  2. 调用路由构造函数得到 Router<AppState>。
  3. with_state(test_state) 收窄为 Router<()>。
  4. oneshot 发请求断言行为。

代码或图示

use axum::{extract::State, routing::get, Router, body::Body, http::Request};
use tower::ServiceExt;

#[derive(Clone)]
struct AppState { greeting: String }

async fn hi(State(s): State<AppState>) -> String { s.greeting }

#[tokio::test]
async fn state_injected() {
    let app = Router::new()
        .route("/", get(hi))
        .with_state(AppState { greeting: "test".into() });
    let resp = app.into_service()
        .oneshot(Request::builder().uri("/").body(Body::empty()).unwrap())
        .await.unwrap();
    let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX).await.unwrap();
    assert_eq!(bytes, "test");
}

常见误区

  • 测试里用全局单例状态:无法按用例替换,耦合生产实现。
  • 状态替身没实现 Clone/Send:with_state 编译不过。

追问

  • 数据库替身怎么做?答:State 中放 trait 连接或仓库 trait,测试注入内存实现;具体抽象在数据访问主题展开。
  • 多个用例共享一份状态要注意什么?答:含可变计数器时用线程安全结构并在用例间重置,避免相互污染。

04.4.3.1-069 提取器失败路径如何写测试覆盖?

一句话结论

构造触发拒绝的请求(缺参数、类型错误、Content-Type 不符),oneshot 后断言拒绝状态码与错误体;失败路径与成功路径分开用例覆盖。

概念解释

提取器拒绝发生在进入 handler 前,测试直接从外部请求视角触发:缺路径参数、查询串类型不符、JSON 结构错误、Content-Type 错误等。断言状态码符合预期,必要时解析错误体核对错误码。覆盖失败路径能验证自定义 Rejection 的 IntoResponse 映射是否正确。不要在测试里直接调用提取器内部方法,保持黑盒请求视角。

原理流程

  1. 按失败场景构造请求(错误路径、错误头、错误 body)。
  2. oneshot 发送到测试 Service。
  3. 断言状态码为拒绝对应的状态。
  4. 解析 body 校验错误结构。

代码或图示

use axum::{body::Body, http::{Request, StatusCode}, routing::get, Router};
use tower::ServiceExt;

#[tokio::test]
async fn bad_path_rejected() {
    let app = Router::new().route(
        "/{id}",
        get(|axum::extract::Path(id): axum::extract::Path<u64>| async move { id.to_string() }),
    );
    let resp = app.into_service()
        .oneshot(Request::builder().uri("/not-a-number").body(Body::empty()).unwrap())
        .await.unwrap();
    assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
}

常见误区

  • 只测合法请求,忽略 400/415/422 分支:拒绝映射问题上线后才暴露。
  • 断言错误体时硬编码内部 Debug 文本:版本升级易失效,应断言稳定错误字段。

追问

  • 如何测试自定义提取器的拒绝?答:构造触发失败的请求,验证其 IntoResponse 输出;也可单测 trait 实现返回的 Rejection 变体。
  • 拒绝状态码映射在哪一层确认?答:内建提取器映射以当前版本为准,自定义枚举在自己的 IntoResponse 里固定。

04.4.3.1-070 编译报「missing FromRequestParts implementation」时如何定位?

一句话结论

报错指向某个参数类型未实现部件提取器 trait,先确认类型是否为 axum 已知提取器,再检查它是否消费 body 而被放在前 N-1 位;自定义类型则补实现或换用已有提取器。

概念解释

编译器把参数元组的 trait bound 展开,某个类型不满足 FromRequestParts 时给出该错误。常见来源:body 提取器位置靠前、自定义结构体没实现提取器、类型名写错引入了无关类型。排查顺序:列出参数类型与各自实现的 trait,把 body 类型移到最后;自定义类型要么实现 trait,要么包一层已有提取器。State 类型不匹配也会以 bound 失败形式出现,需一并核对。

原理流程

  1. 定位报错参数位置与类型。
  2. 判断该类型实现 FromRequestParts 还是 FromRequest。
  3. 调整参数顺序或补 trait 实现。
  4. 核对 State 泛型与 with_state 类型后重新编译。

代码或图示

// 报错:Json 实现 FromRequest,却被放在部件参数位置
// async fn bad(Json(b): Json<Req>, Path(id): Path<u64>) -> String { todo!() }

// 修复:Path 在前,Json 在末位
use axum::{extract::{Path, Json}, routing::post, Router};
use serde::Deserialize;

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

async fn fixed(Path(id): Path<u64>, Json(b): Json<Req>) -> String {
    format!("{id}:{}", b.name)
}

let app = Router::new().route("/{id}", post(fixed));

常见误区

  • 看到报错就给无关类型强行 impl:根因可能是位置或 State 类型。
  • 忽略报错中的泛型 S:状态类型不一致同样表现为提取器 bound 失败。

追问

  • 如何快速判断类型是哪种提取器?答:查 docs.rs/axum/latest 对应类型文档,标注 FromRequestParts 或 FromRequest。
  • 自定义结构体想直接当参数怎么办?答:实现对应提取器 trait,或先用 Json/Path 接收再转换。

04.4.3.1-071 接口返回 404 时如何排查路径前缀与模板问题?

一句话结论

404 说明路径未命中匹配树:先核对完整 URL 前缀、nest 拼接结果、模板占位写法与尾斜杠,再用最小路由复现确认是前缀问题还是模板问题。

概念解释

404 常见原因:nest 前缀与子路由路径拼接后多写或少写一段;模板仍用旧版 :id 语法;请求路径与注册模板段数不一致;通配段位置不对。排查顺序:打印实际请求路径,对照 Router 注册的完整模板,单独把目标路由挂到根路径验证。注意 404 不经过业务 handler,提取器不会执行。

原理流程

  1. 记录请求方法与完整路径。
  2. 对照父前缀、子路径拼接出的完整模板。
  3. 检查占位段语法、段数、通配段位置。
  4. 最小挂载复现,逐步加回嵌套与层。

代码或图示

use axum::{routing::get, Router};

// 实际对外路径 /api/v1/items
let v1 = Router::new().route("/items", get(|| async { "ok" }));
let app = Router::new().nest("/api", Router::new().nest("/v1", v1));

常见误区

  • 在子路由里重复写父前缀:拼成 /api/api/v1/items。
  • 把 404 当成提取器错误:未命中路径时提取器根本不运行。

追问

  • 如何列出当前 Router 的所有模板?答:调试期可逐处检查 route/nest 调用,当前版本没有内置转储全部路由的稳定 API,待确认点以 docs.rs 为准。
  • 尾斜杠导致 404 怎么处理?答:挂 NormalizePathLayer 归一化,或让注册模板与请求路径保持一致。

04.4.3.1-072 返回 400/422 时如何排查提取器解析问题?

一句话结论

400/422 说明路径已命中、提取器构造失败:区分是路径参数、查询串还是 body 解析失败,对照实际输入与 DTO 字段类型定位序列化错误。

概念解释

400 多来自部件解析失败(Path、Query、头格式),422 多来自 body 语义反序列化失败。排查时先看拒绝类型属于哪个提取器,再打印原始输入:路径参数是否为数字、查询键名是否匹配字段、JSON 是否缺字段或类型不符。serde 错误信息指出字段名与类型不匹配处。修复方向是调整客户端输入或放宽 DTO(Option、字符串接收后转换)。

原理流程

  1. 按状态码与拒绝来源确定提取器类别。
  2. 打印路径、查询串、原始 body。
  3. 对照 DTO 字段名、类型与必填约束。
  4. 修正输入或调整反序列化定义后复测。

代码或图示

use axum::{extract::{Path, Query, Json}, routing::post, Router};
use serde::Deserialize;

#[derive(Deserialize)]
struct Req { count: u32 }

async fn create(Path(id): Path<u64>, Query(q: Query<Req>), Json(b): Json<Req>) -> String {
    format!("{id} {} {}", q.count, b.count)
}

let app = Router::new().route("/{id}", post(create));

常见误区

  • 把所有 400 都当成参数缺失:类型转换失败同样返回 400。
  • DTO 字段名与 JSON 键不一致又不加 serde 别名:反序列化找不到字段。

追问

  • 如何在测试里复现解析失败?答:构造类型错误的路径/查询/body 请求,断言拒绝状态码与错误字段。
  • 想把 serde 错误透传给前端吗?答:对外应转成稳定错误结构,原始解析细节按需保留在服务端日志。

04.4.3.1-073 接口返回 415 如何排查 Content-Type 问题?

一句话结论

415 表示请求媒体类型不被提取器接受:核对 Content-Type 头与提取器期望(JSON、urlencoded、multipart),确认客户端发送的编码与后端选型一致。

概念解释

Json 期望 JSON 媒体类型,Form 期望 urlencoded,Multipart 期望 multipart;头缺失或编码写错都会先被媒体类型校验拦截。浏览器表单默认 urlencoded,文件控件切换 multipart;API 客户端默认可能不带 Content-Type。排查先抓请求头确认实际值,再对照提取器要求。415 发生在 body 解析前,body 内容问题不会触发 415。

原理流程

  1. 读取请求 Content-Type 头。
  2. 提取器比对期望媒体类型。
  3. 不匹配直接拒绝 415。
  4. 匹配通过后才解析 body。

代码或图示

use axum::{extract::Json, routing::post, Router};
use serde::Deserialize;

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

async fn create(Json(_): Json<Req>) -> &'static str { "ok" }

let app = Router::new().route("/items", post(create));
// 客户端必须带 Content-Type: application/json

常见误区

  • body 是 JSON 文本却没带头:先被 415 拒绝,而非解析失败。
  • 用 Form 接口接收 JSON 客户端:编码不匹配。

追问

  • 415 与 422 怎么区分?答:415 是媒体类型校验失败,422 是类型已接受但结构反序列化失败。
  • 待确认点是什么?答:当前版本 Json 接受的 Content-Type 子类型范围(如是否接受 application/*+json),验证方式为 docs.rs/axum/latest 查 Json 文档。

04.4.3.1-074 嵌套路由后出现 404,常见原因有哪些?

一句话结论

嵌套 404 多为前缀拼接错误、子路由路径写成绝对全路径、子树 fallback 缺失,或状态类型未收窄导致挂载异常;逐层剥离前缀可定位是哪一层未命中。

概念解释

nest 会剥前缀,子路由必须写相对路径。常见错误:子路由又写全前缀造成双前缀;父前缀与请求路径不一致;多层嵌套中某层段数对不上;子树未设 fallback 时未命中直接冒泡表现为 404。排查方法:把目标路由先挂到根 Router 验证模板本身,再逐层加 nest,每层用 curl 或 oneshot 确认命中段。

原理流程

  1. 确认请求完整路径与父层前缀。
  2. 剥去父前缀得到子树应看到的剩余路径。
  3. 对照子路由注册路径是否为相对写法。
  4. 逐层挂载验证,定位未命中的层级。

代码或图示

use axum::{routing::get, Router};

// 正确:子路由写相对路径
let sub = Router::new().route("/items", get(|| async { "ok" }));
let app = Router::new().nest("/api", sub);
// 请求 /api/items 命中;请求 /api/api/items 404

常见误区

  • 子路由路径以 /api/... 开头:拼接后双前缀。
  • 只在最外层看模板,忽略中间层剥前缀后的剩余路径。

追问

  • 嵌套后 MatchedPath 与原始路径对不上怎么查?答:分别打印 Uri、OriginalUri、MatchedPath,确认前缀剥离发生在哪一层。
  • 子树自己的 fallback 会拦截父层未命中吗?答:不会,只在该前缀子树内生效。

04.4.3.1-075 通配段与路径编码导致的 404 如何排查?

一句话结论

含 %2F、点号或多级子路径的请求未命中时,先确认模板是否声明了末尾通配段、占位段是否只匹配单段,再核对编码解码后的实际分段。

概念解释

占位段 {id} 只匹配到下一个斜杠,跨目录路径必须用 *rest。编码斜杠 %2F 在解码前后段划分可能不同,具体行为以匹配库实现为准。点号、连字符属于静态段字符,模板与请求字面一致。排查时打印解码后的路径分段,对照模板段结构;通配段必须位于末尾,中间带通配是非法模板。

原理流程

  1. 取出解码后的请求路径,按 / 分段。
  2. 对照模板:静态段、占位段、通配段的位置与数量。
  3. 跨段路径改用通配段模板。
  4. 复测并核对解码行为。

代码或图示

use axum::{routing::get, Router};

// 匹配 files 下任意层级
let app = Router::new()
    .route("/files/*rest", get(|axum::extract::Path(p): axum::extract::Path<String>| async move { p }));
// /files/a/b/c 命中;占位段模板 /files/{id} 只匹配单段

常见误区

  • 用 {id} 接收多级路径:第二段起不匹配。
  • 在通配段后再拼静态段:模板非法。

追问

  • %2F 解码后会被当成分隔符吗?答:行为版本敏感,验证方式为发编码斜杠用例观察匹配结果,以当前匹配库实现为准。
  • 通配段取值含前导斜杠吗?答:取值形式以 docs.rs 当前版本为准,打印实际字符串核对。

04.4.3.1-076 同路径重复注册在什么情况下 panic,报错包含什么信息?

一句话结论

同一模板路径下注册了已存在的方法分发器,Router 构建期直接 panic;报错指向重复的路径与方法,定位方式是检查两次 route/merge/nest 挂载。

概念解释

axum 不做静默覆盖:路径表是静态构建的,冲突在启动阶段暴露。触发场景包括两次 route 同路径同方法、merge 两张含同路径的表、子路由与父路由路径重叠。合法的多方法写法是合并到同一个 MethodRouter。panic 发生在构建 Router 时,服务还没开始监听,因此不会造成线上请求期崩溃。

原理流程

  1. 第二次注册进入同一路径节点。
  2. 冲突检查发现方法分发器已存在。
  3. 构建期触发 panic,附重复路径信息。
  4. 修复方式:合并到同一 MethodRouter 或调整路径。

代码或图示

use axum::{routing::get, Router};

// panic:同路径同方法注册两次
// let app = Router::new()
//     .route("/items", get(list))
//     .route("/items", get(other));

// 合法:不同方法合并进同一分发器
let app = Router::new()
    .route("/items", get(|| async { "a" }).post(|| async { "b" }));

常见误区

  • 以为后注册覆盖先注册:实际 panic,需要重构注册方式。
  • 把冲突留到运行期观察:构建期就会中断启动。

追问

  • 不同方法同路径算冲突吗?答:不算,应合并到同一个 MethodRouter 的链式调用中。
  • merge 时冲突如何发现?答:合并遍历逐条校验,发现重复路径同样 panic。

04.4.3.1-077 注册期如何判定两个模板结构冲突?

一句话结论

同层级段结构等价(同名占位段或相同静态段)且会竞争同一匹配节点时判定冲突;静态段与占位段优先级不同不构成注册冲突,请求期按优先级匹配。

概念解释

匹配树把段分层组织:同一层级出现两个会落到同一节点的模板才冲突。例如两条 /users/{id} 是结构等价冲突;/users/me 与 /users/{id} 段类型不同,注册不冲突,请求期静态段优先。理解注册冲突与请求优先级的区别:前者是构建期校验,后者是运行期匹配规则。模板语法非法(通配段位置错)也在解析阶段报错。

原理流程

  1. 新模板切分为段序列。
  2. 沿匹配树查找同层级节点。
  3. 节点结构等价且方法分发器已存在则冲突 panic。
  4. 段类型不同则共存,运行期按优先级选择。

代码或图示

use axum::{routing::get, Router};

// 共存:静态优先
let app = Router::new()
    .route("/users/me", get(|| async { "me" }))
    .route("/users/{id}", get(|| async { "id" }));

// 冲突示例:两条结构等价模板
// .route("/users/{id}", get(a))
// .route("/users/{id}", get(b))

常见误区

  • 把优先级共存的模板当成注册冲突:静态与占位可以同时注册。
  • 忽略方法维度:同路径不同方法不冲突,同路径同方法才冲突。

追问

  • 待确认点是什么?答:当前版本底层匹配库对冲突模板的判定边界,验证方式为 docs.rs/axum/latest 路由文档与实际 panic 用例。
  • 冲突 panic 能否在运行期降级为 404?答:不能,构建期校验先于服务启动,需在代码里消除重复注册。

04.4.3.1-078 any 与 on 如何批量挂载方法,与逐个链式调用有何区别?

一句话结论

any 把同一 handler 挂到全部方法,on 挂到指定方法集合;逐个 get/post 链式挂载则各方法可用不同 handler,三者都写入同一个 MethodRouter。

概念解释

routing::any(handler) 简化全方法端点,例如健康检查或代理转发;routing::on([Method::GET, Method::HEAD], handler) 批量列出方法。逐个链式调用适合各方法行为不同(GET 列表、POST 创建)。选择依据是方法间是否共享逻辑:共享用 any/on,分离用链式。注意 any 覆盖未区分方法的语义,405 行为随之变化。

原理流程

  1. any/on 生成带方法集合的 MethodRouter。
  2. 链式调用向分发器追加方法分支。
  3. route 登记到路径节点。
  4. 请求按方法选择分支。

代码或图示

use axum::{http::Method, routing::{any, get, on, post}, Router};

let app = Router::new()
    .route("/all", any(|| async { "any" }))
    .route("/some", on([Method::GET, Method::HEAD], || async { "some" }))
    .route("/items", get(|| async { "list" }).post(|| async { "create" }));

常见误区

  • 用 any 挂写操作却不区分方法:安全语义模糊,应显式列出允许方法。
  • on 传入方法数组后又链式追加:最终分发器取并集,注意覆盖关系。

追问

  • any 包含哪些方法?答:覆盖分发器支持的方法集合,具体以当前版本 any 文档为准。
  • HEAD 请求由 GET 派生吗?答:HTTP 语义上 HEAD 不取 body,框架是否自动派生 HEAD 行为以当前版本实现为准。

04.4.3.1-079 fallback_service 如何挂外部服务兜底,与 fallback handler 有何区别?

一句话结论

fallback 挂 axum async handler,走提取器与适配器;fallback_service 挂现成 tower Service,未命中路径整体交给外部服务,例如静态目录或 SPA 入口。

概念解释

两者都是未命中兜底,区别在处理器形态:handler 受 axum 参数约束,Service 自己读请求。SPA 部署常把前端静态文件服务作为 fallback_service,未命中 API 时回落到前端路由。静态资源走 ServeDir,历史遗留服务可桥接已有 Service。父层与子层 fallback 冒泡规则对两者同样适用。

原理流程

  1. 路径表未命中。
  2. 查当前 Router 的兜底节点。
  3. fallback 走 handler 适配器;fallback_service 直接调用外部 Service。
  4. 兜底响应沿层链回传。

代码或图示

use axum::Router;
use tower_http::services::ServeDir;

let app = Router::new()
    .route("/api/health", axum::routing::get(|| async { "ok" }))
    .fallback_service(ServeDir::new("dist"));

常见误区

  • 给 fallback_service 配 axum 提取器:外部 Service 不经过提取器流程。
  • 静态兜底与 API 路由前缀未隔离:静态服务可能吞掉本应 404 的 API 路径。

追问

  • fallback_service 还能被全局层包裹吗?答:可以,全局层在外层对兜底响应同样生效,route_layer 不包裹兜底。
  • ServeDir 的目录不存在会怎样?答:由该服务自身返回对应错误,具体行为以 tower-http 文档为准。

04.4.3.1-080 提取器中的 Method 类型来自哪里,常用方法常量有哪些?

一句话结论

Method 来自 axum::http::Method(重导出 http crate 类型),GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS 等为预定义常量;可从字符串解析,非法方法解析失败。

概念解释

方法是请求行的一部分,Method 提取器把它作为部件注入 handler,实现 FromRequestParts。方法常量在 http crate 预定义,比较时直接用常量而非字符串大写转换。自定义方法(罕见)可 Method::from_bytes 构造。中间件按方法做分支判断时同样读取该类型。理解方法类型来源有助于在 on、层与测试构造请求时使用正确类型。

原理流程

  1. 请求行解析出方法字节序列。
  2. http crate 构造 Method 值。
  3. 提取器把 Method 注入 handler 参数。
  4. 业务按常量比较分支。

代码或图示

use axum::{http::{Method, StatusCode}, routing::get, Router};

async fn check(m: Method) -> StatusCode {
    if m == Method::GET { StatusCode::OK } else { StatusCode::METHOD_NOT_ALLOWED }
}

let app = Router::new().route("/", get(check));

常见误区

  • 把方法转字符串再 eq_ignore_ascii_case 比较:直接用 Method 常量比较更稳妥。
  • 手写非法方法名直接构造:应走 from_bytes 并处理解析错误。

追问

  • Method 是否区分大小写?答:HTTP 方法名按规范大写,类型内部表示与比较规则以 http crate 为准。
  • 测试构造请求如何指定方法?答:Request::builder().method(Method::POST),方法作为 builder 参数传入。

04.4.3.1-081 嵌套子路由中的 handler 能否读取父路由 State?

一句话结论

可以:只要父子树属于同一未收窄的 Router<S>,State 类型一致,子树 handler 的 State<S> 提取器读到的就是同一份共享句柄;子树提前 with_state 收窄后则只能读收窄时注入的状态。

概念解释

状态在 with_state 时分发到各节点,嵌套不改变状态共享关系。父树持有的 AppState 对子树可见,子树字段按需取用。若子树先 with_state 变成 Router<()>,它就不再持有父状态;需要额外共享数据应通过 Extension 或在收窄前注入。测试中替换状态时,要确认替换发生在哪一层收窄之前。

原理流程

  1. 子树作为 Router<S> 挂入父树。
  2. 父树 with_state 把状态分发到包含子树在内的节点。
  3. 子树 handler 用 State<S> 取出共享句柄。
  4. 子树已收窄为 () 时,原状态不再可取。

代码或图示

use axum::{extract::State, routing::get, Router};

#[derive(Clone)]
struct AppState { label: String }

async fn child(State(s): State<AppState>) -> String { s.label }

fn sub() -> Router<AppState> {
    Router::new().route("/child", get(child))
}

let app = Router::new()
    .nest("/api", sub())
    .with_state(AppState { label: "shared".into() });

常见误区

  • 子树内提前 with_state 后又在 handler 取父状态:类型已收窄,取不到。
  • 以为嵌套会复制一份状态:克隆的是句柄,内部资源共享。

追问

  • 子树需要独立子状态怎么做?答:在子树构造时用自己的状态类型 with_state 收窄,再挂到父树;跨树共享数据另走 Extension。
  • 状态字段在子树间隔离吗?答:同一 AppState 实例共享,需要隔离就拆分状态实例或子系统。

04.4.3.1-082 Path 多参数用元组绑定时,顺序如何对应模板占位?

一句话结论

Path<(A, B)> 按模板中占位段出现的先后位置依次绑定;结构体按字段名绑定,与书写顺序无关。位置对不上会反序列化失败。

概念解释

多路径参数有两种接法:元组按位置,结构体按名字。元组适合参数少、顺序直观的场景;结构体可读性更好,字段名必须与占位名一致。反序列化由 PathDeserializer 完成,位置错位或字段缺失都返回路径相关拒绝。重构模板调整参数顺序时,元组绑定要同步调整,结构体则不受顺序影响。

原理流程

  1. 命中模板后按顺序收集各占位段字符串。
  2. 元组反序列化按位置填入。
  3. 结构体反序列化按字段名匹配。
  4. 类型转换失败返回 PathRejection。

代码或图示

use axum::{extract::Path, routing::get, Router};
use serde::Deserialize;

async fn tuple(Path((org, repo)): Path<(String, String)>) -> String {
    format!("{org}/{repo}")
}

#[derive(Deserialize)]
struct Params { org: String, repo: String }
async fn named(Path(Params { org, repo }): Path<Params>) -> String {
    format!("{org}/{repo}")
}

let app = Router::new()
    .route("/{org}/{repo}", get(tuple))
    .route("/s/{org}/{repo}", get(named));

常见误区

  • 元组顺序与模板占位顺序错位:值绑定到错误字段。
  • 结构体字段名与占位名不一致又不加 serde 别名:反序列化失败。

追问

  • 元组最多支持几个参数?答:受提取器元组 arity 上限约束,超出应改用结构体;具体上限以当前版本为准。
  • 路径参数缺一段会怎样?答:段数与模板不符直接未命中或解析拒绝,按匹配阶段区分。

04.4.3.1-083 同时使用 Path 与 Query 时,两类参数如何区分来源?

一句话结论

Path 取自路径段,Query 取自 ? 后查询串;两者实现不同提取器,可在同一 handler 并存,路径参数在前、查询参数也属部件提取器,body 提取器仍在最后。

概念解释

路径段标识资源定位,查询串控制过滤、分页与排序。Path<(..)> 从 URI 路径取段,Query<T> 解析查询串键值对,互不干扰。设计 DTO 时把路径资源标识放 Path,可选过滤条件放 Query。两者都实现 FromRequestParts,排列顺序自由。请求缺失路径段属于路由未命中或缺参,缺失查询参数按 Option 或拒绝处理。

原理流程

  1. 请求 URI 拆成路径与查询串两部分。
  2. Path 提取路径段并反序列化。
  3. Query 解析查询串并反序列化。
  4. 两类值一起进入 handler。

代码或图示

use axum::{extract::{Path, Query}, routing::get, Router};
use serde::Deserialize;

#[derive(Deserialize)]
struct Page { size: Option<u32> }

async fn item(Path(id): Path<u64>, Query(p): Query<Page>) -> String {
    format!("item={id} size={:?}", p.size)
}

let app = Router::new().route("/items/{id}", get(item));

常见误区

  • 把分页参数放进 Path:路径段语义是资源标识,查询条件应走 Query。
  • 查询必填字段不包 Option:缺参直接拒绝。

追问

  • Path 与 Query 字段同名会冲突吗?答:来源独立,分别反序列化,DTO 字段可同名但语义要分清。
  • 两者解析失败状态码一致吗?答:都常映射 400,但拒绝类型不同,可在错误映射中区分。

04.4.3.1-084 响应侧 Json<T> 对 T 有什么序列化约束?

一句话结论

作为响应返回的 Json<T> 要求 T 实现 Serialize;它把结构序列化为 JSON body 并设置 JSON Content-Type,与入参 Json<T> 要求 Deserialize 方向相反。

概念解释

同一个结构体常同时用于入参与出参,需要同时派生 Deserialize 与 Serialize。响应 Json 在 handler 返回时序列化失败一般发生在自定义序列化逻辑中,标准派生很少失败。Json 包装类型实现 IntoResponse,可直接作为返回值或元组末位。响应大小不受入参 body 限制约束。

原理流程

  1. handler 返回 Json(value)。
  2. IntoResponse 调用 serde 序列化 T。
  3. 写入 JSON Content-Type 与 body。
  4. 响应沿层链回传。

代码或图示

use axum::{extract::State, Json};
use serde::Serialize;

#[derive(Serialize)]
struct User { id: u64, name: String }

async fn profile() -> Json<User> {
    Json(User { id: 1, name: "ann".into() })
}

常见误区

  • 出参只派生 Deserialize:序列化编译报错,需补 Serialize。
  • 把响应 Json 当 body 提取器放在参数里:方向混淆,入参与出参类型用途不同。

追问

  • 序列化失败如何处理?答:标准结构体派生基本不失败;自定义 Serialize 报错需在实现内转成可控错误,具体错误链路以 serde 行为为准。
  • 响应 JSON 字段重命名怎么做?答:用 serde #[serde(rename = "...")] 属性,与入参共用同一结构体时注意双向命名。

04.4.3.1-085 除了 Json,还有哪些常用类型实现了 IntoResponse?

一句话结论

字符串、StatusCode、HeaderMap、Bytes、Vec<u8>、Response<Body>、元组组合以及自定义类型都可实现 IntoResponse;选择取决于响应体格式与需要的状态码、头。

概念解释

IntoResponse 是返回值统一抽象:纯文本用 &str/String,二进制用 Bytes/Vec<u8>,结构化数据用 Json,底层拼装直接返回 Response。状态码与头通过元组组合附加。自定义响应包装类型实现该 trait 后可在全工程复用。选型原则:能复用既有实现就不自建 Response,统一错误与包装类型单独实现。

原理流程

  1. handler 产出返回值。
  2. 按类型找到对应 IntoResponse 实现。
  3. 实现写入状态码、头与 body。
  4. 生成标准 Response<Body>。

代码或图示

use axum::{http::StatusCode, response::{IntoResponse, Response}, Json};
use serde_json::json;

async fn text() -> &'static str { "plain" }
async fn status() -> StatusCode { StatusCode::NO_CONTENT }
async fn json() -> Json<serde_json::Value> { Json(json!({ "ok": true })) }
async fn custom() -> Response {
    (StatusCode::CREATED, Json(json!({ "id": 1 }))).into_response()
}

常见误区

  • 裸返回业务结构体却没实现 IntoResponse:编译报 trait 未实现。
  • 不同 handler 响应格式不统一:应抽出包装类型集中实现。

追问

  • 如何返回流式响应?答:body 用流式 Body 构造 Response,SSE/WebSocket 场景在错误处理与实时通信主题展开。
  • Bytes 响应需要设 Content-Type 吗?答:默认不自动推断媒体类型,需要时在元组中补响应头。

04.4.3.1-086 提取器拒绝与 handler 内 panic 的边界是什么?

一句话结论

提取器构造失败走 Rejection 响应链路;进入 handler 后发生的 panic 不属于提取器拒绝,需要 panic 捕获层兜底,二者错误链路分开处理。

概念解释

Rejection 发生在参数构造阶段,返回可控错误响应;handler 执行期间 panic 会中断 Future,默认由运行时与 panic 层处理。CatchPanicLayer 可捕获 panic 并转成 500 响应,但不能替代提取器拒绝。区分两类问题:400/415/422 来自提取器,500 与线程异常来自运行期 panic。业务预期失败应返回错误值而不是 panic。

原理流程

  1. 请求进入提取器阶段,失败返回 Rejection 响应。
  2. 提取成功进入 handler 执行业务。
  3. handler panic 由 panic 层或运行时捕获。
  4. 两类错误分别映射状态码与日志。

代码或图示

use axum::{http::StatusCode, response::IntoResponse, Json};
use serde_json::json;

enum BizError { NotFound }

impl IntoResponse for BizError {
    fn into_response(self) -> axum::response::Response {
        (StatusCode::NOT_FOUND, Json(json!({ "error": "not found" }))).into_response()
    }
}

async fn handler() -> Result<&'static str, BizError> {
    Ok("ok") // 预期失败返回 Err,不 panic
}

常见误区

  • 用 panic 表达业务未找到:应返回错误类型,panic 只用于不可恢复的内部状态。
  • 以为提取器拒绝能捕获 handler panic:阶段不同,需要 panic 层。

追问

  • CatchPanicLayer 来自哪里?答:tower-http,开启对应 feature;它把 panic 转成错误响应,配置在中间件主题展开。
  • panic 后状态一致性如何保证?答:panic 前持有的锁与资源按 Drop 规则释放,跨事务操作需在业务层补偿。

04.4.3.1-087 handler 中如何读取链路插入的请求扩展值?

一句话结论

请求扩展(extensions)中的类型值用 Extension<T> 提取器读取;插入动作由层或其它节点完成,读取侧不负责写入,类型不匹配时提取器拒绝。

概念解释

扩展是挂在请求上的类型键值存储,层常把请求 ID、认证上下文、租户信息写入扩展,handler 用 Extension<T> 取出。Extension<T> 实现 FromRequestParts,不消费 body。类型即键:不同类型互不冲突,同类型重复插入后者覆盖。与 State 的区别在于扩展跟随单次请求,State 跨请求共享;取舍在状态共享与中间件主题展开。

原理流程

  1. 外层层把值写入请求扩展。
  2. 请求进入路由,扩展随 Parts 向下传递。
  3. Extension<T> 按类型取出值。
  4. 缺失或类型不符返回拒绝。

代码或图示

use axum::extract::Extension;

#[derive(Clone)]
struct TraceId(String);

async fn handler(Extension(trace): Extension<TraceId>) -> String {
    trace.0
}

常见误区

  • 在 handler 内才插入扩展再取:读取侧只取已有值,写入要在前置层完成。
  • 把请求级数据放 State:State 跨请求共享,请求级数据应走扩展。

追问

  • Extension 值需要 Clone 吗?答:提取器按扩展值类型要求处理,常见做法是存 Arc 或可克隆小类型,具体约束以当前版本文档为准。
  • 扩展里能放 body 吗?答:扩展存部件级值,body 属于请求流,不能作为扩展直接持有。

04.4.3.1-088 handler 能否直接接收原始 Request 类型,绕过提取器?

一句话结论

可以:handler 参数直接声明 Request<Body> 即拿到完整请求,属于 body 消费方式之一,只能放在最后一位;此时头、URI、body 都由业务代码自行读取。

概念解释

提取器是约定式解析,直接拿 Request 是底层形态:需要自定义协议、同时访问头与 body、或做桥接转发时使用。拿到请求后可拆 Parts 读头,或直接消费 Body。绕过提取器意味着拒绝处理、类型校验都要自己实现。常规业务接口仍推荐组合提取器,保持代码可读。

原理流程

  1. handler 最后一个参数声明 Request<Body>。
  2. 适配器把完整请求传给 handler。
  3. 业务代码拆分 Parts 与 Body。
  4. 自行构造响应返回。

代码或图示

use axum::{http::Request, body::Body, routing::post, Router};

async fn raw(req: Request<Body>) -> String {
    let method = req.method().clone();
    let uri = req.uri().clone();
    format!("{method} {uri}")
}

let app = Router::new().route("/raw", post(raw));

常见误区

  • 同时声明 Request 与 Json:body 被双方争抢,不合法。
  • 拿到请求后不消费 body 就返回:连接与 body 释放按框架规则处理,注意不要泄漏流。

追问

  • 直接拿 Request 还能用 State 吗?答:可以,State<S> 作为部件参数在前,Request 在最后一位。
  • 自定义 body 协议怎么解析?答:在 handler 内读取 Body 流并按协议解码,必要时自己实现 FromRequest 复用逻辑。

04.4.3.1-089 路由层 from_fn 中间件与 handler 适配器的边界是什么?

一句话结论

handler 负责单个端点的业务处理,中间件 from_fn 包裹服务链做跨切面逻辑;中间件拿到的是 Next 与请求,可在调用内层前后加工,不直接绑定某条路由模板。

概念解释

axum 提供 middleware::from_fn 把普通函数挂成层,函数接收请求与 Next,显式调用 next.run(req) 进入内层。中间件可短路返回响应,也可读写请求/响应。handler 是内层业务节点,中间件在其外层。层挂载范围(全局/路由级)决定中间件覆盖哪些端点;具体层顺序与状态访问在状态共享与中间件主题展开。

原理流程

  1. 层函数接收 Request 与 Next。
  2. 前置逻辑读请求、做鉴权或日志。
  3. 调用 next.run(req) 进入内层链,最终到达 handler。
  4. 后置逻辑加工响应后返回。

代码或图示

use axum::{http::Request, middleware::{self, Next}, response::Response, routing::get, Router};

async fn log<B>(req: Request<B>, next: Next<B>) -> Response {
    let method = req.method().clone();
    let resp = next.run(req).await;
    println!("{method} {}", resp.status());
    resp
}

let app = Router::new()
    .route("/", get(|| async { "ok" }))
    .route_layer(middleware::from_fn(log));

常见误区

  • 中间件里忘了调用 next.run:内层永远不执行,请求被短路。
  • 把业务端点逻辑写进全局中间件:职责混淆,应下沉到 handler。

追问

  • Next 持有什么?答:内层服务句柄,run 方法传入请求并返回响应 Future;类型签名以当前版本为准。
  • 中间件能使用提取器参数吗?答:from_fn_with_state 与相关形式支持提取器与状态,具体见中间件主题。

04.4.3.1-090 请求扩展与 State 各存什么数据,职责如何划分?

一句话结论

State 存跨请求共享的资源(连接池、客户端、配置),请求扩展存单次请求链路产生的上下文(请求 ID、认证主体、租户);生命周期与可见范围不同。

概念解释

State 在 with_state 时注入,跨所有请求复用,内部用 Arc 共享;扩展在请求进入链路后由层写入,跟随本次请求,响应结束即释放。放错位置的典型问题:请求级用户身份塞进 State 会被多请求共享污染;重连接池塞进扩展会重复构造。划分标准是数据生命周期:应用级共享进 State,请求级上下文进扩展。

原理流程

  1. 启动期确定应用级资源,构造 AppState。
  2. 请求到达,层从认证结果生成请求上下文写入扩展。
  3. handler 分别通过 State 与 Extension 取用。
  4. 请求结束扩展释放,State 继续存活。

代码或图示

use axum::{extract::{Extension, State}, routing::get, Router};
use std::sync::Arc;

#[derive(Clone)]
struct AppState { pool: Arc<Pool> }
struct Pool;

#[derive(Clone)]
struct AuthUser { id: u64 }

async fn handler(State(s): State<AppState>, Extension(user): Extension<AuthUser>) -> String {
    format!("user={} pool={}", user.id, Arc::strong_count(&s.pool))
}

常见误区

  • 把当前登录用户放进 State:多请求串号。
  • 把数据库池放进扩展:每个请求重复创建连接池。

追问

  • 扩展值在嵌套服务间会丢失吗?答:随请求向下传递,链路中被降级或重建服务时可能不带扩展,需按挂载结构确认。
  • State 与扩展都要求 Send 吗?答:跨线程共享与传递都要求 Send,扩展值通常还需 Clone 以便提取,具体以当前版本为准。

04.4.3.1-091 测试中如何覆盖 404 与 405 响应?

一句话结论

404 用未注册路径发请求断言状态码;405 用已注册路径但未注册的方法发请求断言 405 与 Allow 头;两类都走 oneshot 黑盒测试。

概念解释

路由测试不只覆盖命中路径:未注册路径验证 fallback 行为,已注册路径的错误方法验证 405 分发。405 响应带 Allow 头,断言头值可确认方法表完整。测试用例按成功、404、405 分组,避免回归时误改路由表。fallback 返回自定义内容时,同时断言 body 结构。

原理流程

  1. 构造未注册路径请求,oneshot 发送。
  2. 断言 404 状态与兜底 body。
  3. 对已注册路径换未注册方法发请求。
  4. 断言 405 状态与 Allow 头包含已注册方法。

代码或图示

use axum::{body::Body, http::{Request, StatusCode}, routing::get, Router};
use tower::ServiceExt;

#[tokio::test]
async fn not_found_and_method() {
    let app = Router::new().route("/items", get(|| async { "ok" }));

    let r404 = app.clone().into_service()
        .oneshot(Request::builder().uri("/nope").body(Body::empty()).unwrap())
        .await.unwrap();
    assert_eq!(r404.status(), StatusCode::NOT_FOUND);

    let r405 = app.into_service()
        .oneshot(Request::builder().method("DELETE").uri("/items").body(Body::empty()).unwrap())
        .await.unwrap();
    assert_eq!(r405.status(), StatusCode::METHOD_NOT_ALLOWED);
}

常见误区

  • 只测 GET 命中,忽略 405:方法表变更后客户端收到错误状态码无感知。
  • 断言 Allow 头时不核对方法集合:头存在但方法列表不全会被漏掉。

追问

  • 自定义 fallback 的 404 body 怎么断言?答:聚合 body 后解析 JSON 错误字段,与 405 错误结构分开断言。
  • 测试中 Router 需要克隆吗?答:into_service 消费 Router,多个用例或多次请求前按需 clone,Clone 成本在句柄层。

04.4.3.1-092 Handler trait 的类型参数如何对应函数签名与状态?

一句话结论

Handler<In, S, T> 把函数参数类型、状态类型与提取器元组编码进 trait 参数;axum 为满足约束的函数自动实现该 trait,注册路由时编译器推断这些参数。

概念解释

Handler 是 endpoint 的抽象:输入 In 描述参数列表,S 是状态类型,T 是提取器元组标识。普通 async fn 满足「参数可被提取器构造、返回值实现 IntoResponse、Future Send + 'static」即自动实现 Handler。理解这一抽象能看懂编译报错里的泛型参数来自哪里,也能判断闭包与函数为何可互换。自定义实现 Handler 极少,通常依赖自动实现。

原理流程

  1. 函数签名被解析为参数类型序列与返回类型。
  2. 编译器推断提取器元组 T 与状态 S。
  3. 检查参数提取约束、返回 IntoResponse、Future Send + 'static。
  4. 满足后 get(handler) 接收该 Handler。

代码或图示

use axum::{extract::State, routing::get, Router};

#[derive(Clone)]
struct AppState { port: u16 }

async fn handler(State(s): State<AppState>) -> String { s.port.to_string() }

// get(handler) 由编译器推断 Handler<In, AppState, T>
let app = Router::new().route("/", get(handler));

常见误区

  • 以为需要手写 impl Handler:普通函数满足约束即自动实现。
  • 报错里出现未解析的 Handler 参数:先核对参数提取器与 State 类型,再看返回值约束。

追问

  • Handler 的 S 与 Router 的 S 必须一致吗?答:必须一致,否则 with_state 与路由注册阶段类型不匹配。
  • 闭包也满足 Handler 自动实现吗?答:满足,捕获变量约束 Send + 'static 后闭包同样被接受。

04.4.3.1-093 handler 返回的 Future 对生命周期与捕获有什么要求?

一句话结论

handler 返回的 Future 必须 Send + 'static,因此闭包捕获的数据不能借用栈上临时值,跨任务持有数据要 move 进闭包或放入 State。

概念解释

异步函数返回的 Future 在被 poll 期间可能跨线程迁移,捕获变量随 Future 一起移动。'static 排除短生命周期借用,Send 允许跨线程。async fn 引用函数参数是允许的,因为参数随调用帧存活;闭包引用外部局部变量则违反约束。需要在多个请求间复用的数据放入 State,单次请求内构造的数据 move 进 Future。

原理流程

  1. handler 被调用,构造返回 Future。
  2. 类型检查 Future 及其捕获值 Send + 'static。
  3. 不满足则在注册或调用期编译报错。
  4. 修复方式:move 捕获、放入 State 或改成参数传入。

代码或图示

use axum::{routing::get, Router};

// 合法:值 move 进闭包
let token = String::from("abc");
let app = Router::new().route(
    "/",
    get(move || async move { token.clone() }),
);

常见误区

  • 闭包 & 捕获外部局部变量:'static 检查失败。
  • 在 Future 中持有跨线程不 Send 的类型:编译报错,需换线程安全结构。

追问

  • async fn 的参数引用算不算借用外部数据?答:参数属于本次调用帧,Future 存活期内有效,不构成 'static 违规。
  • Future 不 Send 通常由什么类型引起?答:持有 Rc、非 Send 同步锁守卫等,换成 Arc 与异步锁。

04.4.3.1-094 提取器元组的实现粒度如何决定参数分组?

一句话结论

axum 为 1 到 16 个参数的元组分别实现提取器 trait;元组内每个位置独立调用对应提取器,参数即元组元素,分组只是编译期展开,运行期按顺序构造。

概念解释

handler 参数列表在类型层面就是一个元组,trait 实现按 arity 展开。前 N-1 位走 FromRequestParts,末位走 FromRequest。理解元组粒度后能明白:聚合多个相关参数为自定义结构体,本质是减少元组元素数量并把解析逻辑内聚。提取器失败短路:任一前置提取器失败,后续不再构造。

原理流程

  1. 参数列表被视为元组类型。
  2. 编译器选择对应 arity 的 trait 实现。
  3. 依次调用各元素提取器,部件先于 body。
  4. 失败短路,成功则组装参数调用 handler。

代码或图示

use axum::{extract::{Path, Query, State, Json}, routing::post, Router};
use serde::Deserialize;

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

async fn handler(
    State(_): State<()>,
    Path(_): Path<u64>,
    Query(_): Query<Req>,
    Json(_): Json<Req>,
) -> &'static str { "ok" }

let app = Router::new().route("/{id}", post(handler));

常见误区

  • 以为元组提取器会批量解析 body:只有末位元素消费 body,其余读部件。
  • 超过 16 元素仍期待自动实现:没有对应 arity 的 trait 实现。

追问

  • 提取器失败顺序与参数位置一致吗?答:部件提取器按位置依次执行,body 提取器最后;任一失败即短路。
  • 元组元素能否是另一个元组?答:嵌套元组不会被递归展开成多个提取器,应使用结构体聚合。

04.4.3.1-095 遇到版本敏感的 axum API,如何确认当前行为而不编造?

一句话结论

以 docs.rs/axum 当前版本文档与编译示例为准;行为不确定处标注「待确认」并写明验证点(文档地址、测试用例步骤),不在题目或代码里写死未核实的变体名与状态码。

概念解释

axum 迭代较快,提取器拒绝变体、默认阈值、嵌套模板行为等可能跨版本变化。工程实践中先查 docs.rs 对应类型页面,再用最小用例打印实际响应或类型输出验证。文档未覆盖的边界行为,写代码时保留显式判断,不依赖猜测。本项目题库同样要求:不确定的 API、配置项、状态码映射标注验证点。

原理流程

  1. 识别版本敏感点:拒绝类型、默认值、嵌套行为、feature 名。
  2. 打开 docs.rs/axum/latest 对应条目核对签名与文档。
  3. 写最小用例实际运行,打印行为结果。
  4. 无法确认的内容标注待确认与验证步骤。

代码或图示

待确认示例:
- 验证对象:JsonRejection 各变体对应的 HTTP 状态码
- 验证方式:docs.rs/axum/latest 查 JsonRejection,构造缺失头、非法 JSON、缺字段三类请求断言
- 版本表述:以 docs.rs 当前版本为准,不写死次版本号

常见误区

  • 凭记忆写拒绝变体名或默认字节数:版本升级后与实际不符。
  • 把待确认内容写成确定结论进入面试答案。

追问

  • Cargo 依赖版本怎么写才稳妥?答:在 Cargo.toml 写宽松 semver 范围(如 "0.8" 级别),具体兼容版本以当前 workspace 锁定为准。
  • 如何确认 feature 开关真实存在?答:查 crate 文档的 feature 列表与 Cargo.toml [features],不臆造开关名。

04.4.3.1-096 路径参数中的中文与特殊字符如何编码处理?

一句话结论

路径段按 URI 编码传输,Path 提取器在解码后反序列化;中文与特殊字符需先 URL 编码,占位段仍以斜杠为界,含斜杠的内容改用通配段。

概念解释

URI 中非 ASCII 与保留字符以百分号编码表示,匹配与提取器在解码后的字符串上工作。Path<String> 直接拿到解码文本,数值类型再做解析。中文作为文件名或标识时,注意服务端文件系统编码与日志显示。编码斜杠是否跨段行为版本敏感,需用例验证。不要在路径参数里传递未编码的原始特殊字符。

原理流程

  1. 客户端对路径段做百分号编码。
  2. 匹配树在解码后的段上比对。
  3. Path<T> 取出解码字符串并反序列化。
  4. 业务使用解码后的值,落盘或入库前再做校验。

代码或图示

use axum::{extract::Path, routing::get, Router};

async fn name(Path(n): Path<String>) -> String { n }

let app = Router::new().route("/greet/{name}", get(name));
// 请求 /greet/%E5%AE%89%E5%A6%86 解码后参数为中文文本

常见误区

  • 未编码中文直接拼进路径:不同客户端与代理行为不一致。
  • 把含 / 的标识塞进占位段:被拆成多段,应编码或用通配段。

追问

  • 解码后出现非法 UTF-8 怎么办?答:路径解析与类型转换按提取器拒绝处理,具体错误类型以当前版本为准。
  • 查询串中的中文与路径编码规则一样吗?答:同为百分号编码,Query 反序列化器按 urlencoded 规则解码。

04.4.3.1-097 静态文件服务如何与路由前缀、兜底路由配合?

一句话结论

静态资源用 ServeDir 挂到前缀(nest_service)或作为 fallback_service;API 路由在前匹配,未命中的静态路径交给文件服务,前缀剥离由挂载方式决定。

概念解释

前后端分离部署常见两类:静态资源集中在 /assets/* 前缀下用 nest_service 挂载;前端 SPA 路由交给 fallback,未命中 API 时由 ServeDir 返回入口文件。文件服务自己处理磁盘路径与缓存头,axum 只做挂载。注意 API 前缀与静态前缀不要重叠,避免静态服务吞掉 JSON 接口。目录位置、索引文件与压缩选项由 tower-http 配置。

原理流程

  1. API 路由表先注册业务接口。
  2. nest_service 挂静态前缀或 fallback_service 挂文件服务。
  3. 请求先匹配 API,未命中进入文件服务。
  4. 文件服务按剩余路径查找磁盘文件并响应。

代码或图示

use axum::{routing::get, Router};
use tower_http::services::ServeDir;

let app = Router::new()
    .route("/api/health", get(|| async { "ok" }))
    .nest_service("/assets", ServeDir::new("dist/assets"))
    .fallback_service(ServeDir::new("dist"));

常见误区

  • 静态兜底吞掉未知 API 路径:应按 /api 前缀区分,API 未命中返回 JSON 404。
  • 直接把磁盘根目录挂出去:目录穿越与信息泄露风险。

追问

  • ServeDir 需要哪个 feature?答:tower-http 的 serve-dir feature,具体名称以 docs.rs/tower-http 当前版本为准。
  • SPA 刷新子路由 404 怎么处理?答:文件服务配置回退到入口 HTML,具体选项由 ServeDir 或自定义服务提供。

04.4.3.1-098 HEAD 与 OPTIONS 请求在 axum 路由中的默认行为是什么?

一句话结论

HEAD 与 OPTIONS 都是普通方法,按 MethodRouter 方法表分发;未注册时返回 405。是否由 GET 自动派生 HEAD、预检是否由 CORS 层短路,属于框架与层的组合行为,需按当前版本确认。

概念解释

HTTP 方法语义上 HEAD 只取响应头不取 body,OPTIONS 用于描述接口能力。axum 路由表按方法显式分发,框架不保证自动为 GET 派生 HEAD 处理器。CORS 预检 OPTIONS 由 CorsLayer 在层链短路,不进入业务方法表。排错时先判断请求是预检还是业务 OPTIONS,再决定查层还是查路由。

原理流程

  1. 请求方法为 HEAD/OPTIONS 进入分发器。
  2. 预检 OPTIONS 先被 CORS 层识别并响应。
  3. 非预检请求查方法表,命中则调用 handler。
  4. 未命中返回 405 与 Allow 头。

代码或图示

use axum::{routing::{get, options}, Router};

async fn info() -> &'static str { "info" }

let app = Router::new()
    .route("/items", get(info).options(|| async { "options" }));

常见误区

  • 以为注册 GET 就自动支持 HEAD:派生行为以当前版本实现为准,不确定就显式验证。
  • 把预检 OPTIONS 405 当成业务路由缺陷:预检应由 CORS 层处理。

追问

  • 待确认点是什么?答:当前 axum 版本是否为 GET 自动派生 HEAD 响应,验证方式为 docs.rs/axum/latest 路由文档与 HEAD 请求用例。
  • 如何统一声明允许的方法?答:在 MethodRouter 上链式注册,Allow 头由分发器根据已注册方法生成。

04.4.3.1-099 常用提取器按「读取部件 / 消费 body」如何速查分类?

一句话结论

部件提取器(FromRequestParts)包括 Path、Query、HeaderMap、TypedHeader、CookieJar、Host、MatchedPath、State、Extension、ConnectInfo、Method、Uri、OriginalUri、RawQuery;body 提取器(FromRequest)包括 Json、Form、Bytes、String、Multipart、Request,只能放最后一位。

概念解释

分类决定参数位置与复用方式:部件提取器只读请求头部分,可并列在前;body 提取器持有请求所有权,全表唯一。选型速查先看数据来源:路径段、查询串、头、Cookie、状态、扩展各有对应提取器;body 编码再选 Json/Form/Multipart/原始字节。需要复合语义时自定义提取器派生组合。排错时先归类提取器 trait,再判断位置或类型问题。

原理流程

  1. 列出 handler 所需数据来源。
  2. 按来源匹配对应提取器。
  3. 部件提取器排前,body 提取器置末。
  4. 无现成提取器时自定义实现对应 trait。

代码或图示

部件提取器(FromRequestParts):
  Path / Query / HeaderMap / TypedHeader / CookieJar / Host
  MatchedPath / State / Extension / ConnectInfo / Method
  Uri / OriginalUri / RawQuery

body 提取器(FromRequest,末位):
  Json / Form / Bytes / String / Multipart / Request<Body>

常见误区

  • 把 body 提取器归入部件类放在中间:编译报错。
  • 一个 handler 声明两个 body 提取器:body 只能消费一次。

追问

  • 自定义提取器如何归类?答:不碰 body 实现 FromRequestParts,需要 body 实现 FromRequest。
  • 待确认点是什么?答:当前版本提取器完整清单以 docs.rs/axum/latest 的 extract 模块文档为准。

04.4.3.1-100 路由与提取器问题的综合排查清单是什么?

一句话结论

按「方法与路径 → 匹配层级 → 提取器类型与位置 → body 编码与限制 → 响应转换」顺序逐层定位:先确认请求是否命中路由,再查参数构造,最后查响应生成。

概念解释

综合排错把前面各题串成一条链:404 查路由模板与前缀,405 查方法表,400/422/415 查提取器与 Content-Type,413 查大小限制,500 查 handler panic 与错误转换。每一层都有对应的最小复现手段:oneshot 构造请求、打印模板与原始输入、断言状态码与 body。线上问题先还原请求样例,再在测试里复现,避免凭感觉改代码。

原理流程

  1. 抓请求方法、完整路径、头、body 编码。
  2. 核对 Router 模板、嵌套前缀与方法注册。
  3. 命中后逐个提取器归类,确认位置与拒绝类型。
  4. 检查 body 限制与响应 IntoResponse 转换,复现并修复。

代码或图示

排查顺序:
1. 状态码 404 → 模板 / 前缀 / 尾斜杠 / 通配段
2. 状态码 405 → 方法表与 Allow 头
3. 400 / 422 → Path / Query / Json 反序列化与 DTO 字段
4. 415 → Content-Type 与提取器选型
5. 413 → DefaultBodyLimit 与 RequestBodyLimitLayer
6. 500 → handler panic、错误类型 IntoResponse 映射

常见误区

  • 跳过路由匹配直接怀疑提取器:未命中路径时提取器不执行。
  • 线上凭日志猜结论:先在测试用例复现同一样请求,再定位具体层。

追问

  • 如何建立可复用的最小复现?答:把路由构造抽成函数,测试传入 State 后 oneshot 发送问题请求,逐步剥离层与嵌套。
  • 与状态、中间件相关的问题在哪继续展开?答:State 共享、层顺序、鉴权限流见 04.4.3.2 状态共享与中间件;错误统一与流式通信见 04.4.3.3。