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。
原理流程
Router::new()建立空路径表。route(path, method_router)解析路径模板并写入内部匹配树。MethodRouter按Method保存若干 endpoint,未命中方法时返回 405。- 请求到达后先做路径匹配得到
MethodRouter,再按方法分发到对应 handler。 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,所以可排在前面。
原理流程
- axum 生成 handler 适配器时,按参数位置拆解类型约束。
- 前 N-1 个参数依次调用
from_request_parts(&mut parts, state)。 - 最后一个参数调用
from_request(req, state),获得完整请求。 - 每个提取器可自定义拒绝:返回
Result<Self, Self::Rejection>,拒绝类型需实现IntoResponse。 - 任一提取器返回
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 时只能放在末尾。
原理流程
Router::route编译模板,生成静态段与占位段的匹配结构。- 请求命中后,按占位名收集字符串切片,构造
PathDeserializer。 - 反序列化为
T,失败则返回PathRejection(通常 400)。 - 提取器把结果放进 handler 参数,进入业务逻辑。
- 未声明的多余路径段不会被捕获,
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 的路径表分发。
原理流程
- 父 Router 记录前缀
/api与子 Router 的匹配结构。 - 请求到达后先剥离
/api前缀,剩余部分交给子 Router。 - 子 Router 在剩余路径上命中模板,分发到对应 handler。
- 响应沿调用链原路返回,不会把前缀拼回 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。
原理流程
- 调用
merge(other)时遍历 other 的路径表,逐条迁入当前表。 - 迁入时校验路径与方法是否已存在,存在则触发 panic。
nest则把前缀与子表作为一个节点挂入当前匹配树,不做平铺。- 启动前完成静态校验,因此冲突在构建期暴露,而不是请求期。
代码或图示
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 时优先用子树的,没有再向外冒泡。
原理流程
- 请求先在匹配树中查找路径模板。
- 未找到任何模板时,调用当前 Router 的 fallback。
- fallback 若为 async fn,同样走 handler 适配器与提取器流程。
- 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 更合适。
原理流程
- 调用
layer(L)时,axum 把 L 套在整个 Router Service 外。 - 调用
route_layer(L)时,L 分别套在每个已注册路由节点外。 - 请求先经过全局层,再进入路由匹配,命中后再经过路由层。
- 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})才会在注册期报冲突。理解优先级能避免把固定路径写成占位路径后被错误捕获。
原理流程
- 路径按
/切成段序列。 - 匹配树在每一层先找字面段,命中则下钻。
- 字面段未命中再找占位段,最后才尝试通配段。
- 多层都命中后按完整模板选中
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>。
原理流程
- 构造子
Router<AppState>,内部 handler 用State<AppState>提取。 - 子树调用
with_state(state.clone()),类型变为Router<()>。 - 父树
Router::new().nest("/sub", sub)或merge(sub)。 - 父树最后一次
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 文档。
原理流程
- 父挂载点剥离前缀,生成内部请求继续下钻。
- 子树在剩余路径上命中模板,记录匹配模板。
- 提取器分别从
Parts读取原始 URI、当前 URI 与匹配模板。 - 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 看到的剩余路径越短。多级拆分常用于按模块组织代码:域名级分组在最外层,业务模块在中间层,具体资源在最内层。拼接过程在路由构建期完成,运行时只做前缀剥离与下钻,不做字符串反复拼接。
原理流程
- 最外层记录前缀
/a,挂载中间 Router。 - 中间 Router 记录前缀
/b,挂载最内层子树。 - 请求到达先剥
/a,再剥/b,剩余路径进最内层匹配。 - 任一层未命中,按该层 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 挂到前缀下,前缀下所有路径都进入该服务。
原理流程
route(path, get(handler))把 handler 包装成MethodRouter注册。route_service(path, svc)把 svc 作为该路径的处理 Service 注册。- 命中路径后,分发器直接调用 svc 的
Service::call。 - 中间件层在 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-dirfeature;具体 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。
原理流程
- 构建
Router<AppState>,handler 通过State<AppState>取用状态。 - 调用
with_state(app_state),状态被分发给各路由节点。 - 泛型参数变为
Router<()>,不再声明外部依赖。 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 提取器无法使用。
原理流程
Router<()>调用对应方法生成MakeService。- hyper 接受连接时调用工厂构造请求处理 Service。
- 带 connect_info 的工厂把对端地址随请求一起放入扩展。
- 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。
原理流程
get(h1)生成只挂 GET 的MethodRouter。.post(h2)在其上追加 POST 分支。route(path, mr)把该分发器登记到路径表。- 请求命中路径后按方法选择分支,未登记方法返回 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 本身不参与。
原理流程
- 路径匹配成功,取出对应
MethodRouter。 - 按请求
Method查找已注册分支。 - 未找到则构造 405 响应,附带
Allow头。 - 已找到则分发到对应 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 定位成模板冲突,而不是运行时偶发问题。
原理流程
route/nest解析路径字符串,切分出各类段。- 段序列写入匹配树对应节点,冲突检查在此时进行。
- 构建完成后树结构冻结,请求期仅做段匹配与下钻。
- 非法模板或重复模板在启动构建阶段 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,静态站点子树返回前端入口,互不干扰。设计时要明确每一层兜底的响应语义。
原理流程
- 请求进入父 Router,按前缀定位子树挂载点。
- 子树内路径未命中,检查子 Router 的 fallback。
- 子树有 fallback 则由它响应;没有则冒泡给父 Router。
- 父 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 冒泡。
原理流程
nest_service("/static", svc)在前缀节点登记外部 Service。- 请求命中前缀后剥离前缀,剩余路径透传给 svc。
- svc 自己完成路径匹配、方法处理与响应构造。
- 父层中间件仍在 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,会造成每个处理单元重复持有重资源。
原理流程
- 构建期组装
Router<AppState>,登记状态需求。 with_state把一份 AppState 分发给节点引用。- 运行期工厂克隆 Router,生成连接级 Service。
- 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<()>。拆分后模块可独立写测试,单独挂载验证路由与提取器。
原理流程
- 模块内定义 handler 与子
Router<AppState>。 - 导出
pub fn router() -> Router<AppState>。 - 根模块
Router::new().nest("/users", users::router())。 - 根层统一
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/ 下任意层级路径。它必须位于模板末尾,后面不能再接静态段或占位段。命中后通配内容作为一段字符串放入路径参数表;是否保留前导斜杠属于版本敏感行为,取值后打印核对。通配段与占位段可以在同一模板中并存,但占位段在前、通配段在末。
原理流程
- 模板解析时记录
*rest为末尾通配捕获。 - 请求路径前缀与模板前段匹配后,剩余全部路径归入通配段。
- 路径参数表生成时,占位段与通配段按名/位置填入。
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 标识符,避免与查询参数、结构体字段名混淆。非法命名或段结构会在模板解析阶段暴露,启动期即可发现。
原理流程
- 模板字符串按
/切分。 - 每段判定为静态、占位或通配。
- 校验通配段数量与位置、占位段命名。
- 合法段序列写入匹配树。
代码或图示
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 中间件,在状态与中间件主题中展开。
原理流程
- 请求 URI 路径被切分成段序列。
- 匹配树按段字面比较,大小写逐字符敏感。
- 未挂归一化层时,尾斜杠产生空段参与匹配判断。
- 挂归一化层后,请求进入 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。在嵌套路由中,模板拼接范围、前缀保留方式可能随版本调整,文档未明确时应写「待确认」并抓实际响应核对。
原理流程
- 匹配树命中节点后,把节点保存的模板字符串写入请求扩展。
MatchedPath提取器从扩展中取出模板。- handler 或日志层用模板归类请求。
- 未命中路由时扩展中无模板,提取结果按拒绝处理。
代码或图示
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 的区别是后者拿到原始字符串,不做反序列化。
原理流程
- 从请求 URI 取出原始查询串。
- 按
&与=解析为键值对序列。 - 经
serde_urlencoded反序列化为 T。 - 失败构造
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 时保持扁平,避免在查询串里塞深层嵌套。数字、布尔等标量由反序列化器做字符串到类型的转换。
原理流程
- 解析查询串得到键值序列。
- Option 字段缺失填入 None,存在则解析内层类型。
- Vec 字段收集同名键的全部值。
- 标量字段从字符串反序列化为目标类型,失败拒绝。
代码或图示
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。
原理流程
- 读取请求 Content-Type,校验是否为 urlencoded。
- 消费 body 字节,按表单编码解析键值对。
- serde 反序列化为 T,失败返回
FormRejection。 - 成功后把结构体作为最后一个参数传入 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 大小限制,超限按拒绝或限制层处理。
原理流程
- 校验
Content-Type: application/json(具体可接受的子类型以当前版本为准)。 - 读取 body 全部字节,先过大小限制。
- serde_json 反序列化为 T。
- 任一步失败返回
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。
原理流程
- 提取器先查 Content-Type,不符返回 415。
- 读取 body 时检查大小,超限返回 413。
- 字节交给 serde_json 解析与映射,结构失败返回 422。
- 全部通过才进入 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 只能被消费一次。
原理流程
- 提取器从请求中取出 body 流。
- 按限制读取全部字节到缓冲。
Bytes直接封装返回;String校验 UTF-8 后转字符串。- 失败返回对应 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 编码,再判断是客户端错发还是提取器选型错误。
原理流程
- 读取 body 全部字节。
- 调用
String::from_utf8做 UTF-8 校验。 - 校验通过构造
String;失败返回转换错误对应的拒绝。 - 拒绝经
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 内部按规范化键存储;多个同名头以迭代方式取值。
原理流程
- 提取器从请求 Parts 克隆或借用 HeaderMap。
- handler 按头名查询值。
- 必要时把
HeaderValue转&str或字节。 - 业务逻辑按头值判断行为。
代码或图示
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。
原理流程
- 泛型 T 指定目标头类型。
- 提取器按 T 声明的头名从 HeaderMap 取值。
- 调用类型的解析逻辑反序列化头值。
- 成功传入 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 当前版本为准
常见误区
- 把
headerscrate 的类型与手写字符串头混用后忘记引入依赖:Cargo.toml 需要声明headers。 - 期望
TypedHeader解析自定义业务头:预定义类型不含业务头,自定义需实现Headertrait。
追问
TypedHeaderRejection何时触发?答:头缺失、值无法按类型解析等,具体变体以 docs.rs/axum 当前版本为准。- 可选标准头怎么写?答:参数用
Option<TypedHeader<H>>,缺失时为 None,存在时再解析内层。
04.4.3.1-035 CookieJar 提取器如何读取与写入 Cookie?
一句话结论
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 头。
原理流程
- 从请求
Cookie头解析各 Cookie,装入 jar。 - handler 通过
jar.get(name)读取值。 - 修改集合:
jar.add(Cookie::new(...))或移除条目。 - 响应构造阶段把变更序列化为
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)。提取器只负责取值,可信度判断要结合部署拓扑。
原理流程
- 提取器从请求 URI 或 Host 头定位 authority。
- 解析出主机部分(端口处理按当前版本实现)。
- 成功作为参数传入;缺失或非法则拒绝。
- 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 内区分方法,或中间件记录操作类型。选型原则:要结构化数据用对应强类型提取器,要原始值调试或兼容特殊格式时用部件提取器。
原理流程
- 请求进入适配器,Parts 已包含方法、URI、查询串等部件。
- 各提取器从 Parts 读取对应字段,不触碰 body。
- 中间件改写 URI 后,
Uri与OriginalUri出现差异。 - 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 必须与启动时声明的泛型一致,类型不匹配时提取器拒绝。
原理流程
- 启动时用带 connect_info 的工厂生成 MakeService。
- 新连接建立时,工厂把对端地址写入请求扩展。
- 提取器按类型从扩展读出
ConnectInfo<T>。 - 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 签名实现,具体语法以工具链版本为准。
原理流程
- 定义提取器结构体,字段装解析结果。
impl FromRequestParts<S> for MyExtractor。- 在方法中读 Parts 的头、URI、路径或扩展,结合 State 校验。
- 成功返回 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。
原理流程
- 定义自定义 body 类型。
impl FromRequest<S> for MyBody。- 方法内检查头、读取 body 字节、做协议解析。
- 成功返回类型,失败返回 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 生成响应。不要在拒绝里泄露内部错误细节。
原理流程
- 定义错误枚举,各变体对应一类拒绝。
- 为枚举实现
IntoResponse,映射状态码与 JSON body。 - 提取器失败时返回对应变体。
- 框架把拒绝转成响应写回客户端。
代码或图示
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<..>>,锁的类型选择要符合异步规则,避免在异步上下文持有阻塞锁。
原理流程
- 定义 AppState 并在路由上
with_state。 - 提取器实现 trait,方法签名接收
&S。 - 从状态取需要的字段,完成校验或预取。
- 构造提取器值传入 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 消费顺序不能颠倒。
原理流程
- 在实现方法中调用基础提取器的构造函数。
- 拿到基础值后做二次校验或转换。
- 内部错误映射为自定义 Rejection。
- 返回包装后的业务类型。
代码或图示
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。
原理流程
get(closure)把闭包包装成 Handler 实现。- 闭包捕获环境按
move语义进入节点。 - 类型检查捕获变量
Send + 'static。 - 请求到达时闭包被调用,参数仍由提取器注入。
代码或图示
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,因此超长列表在编译期被拦截。工程上参数过多通常说明职责膨胀,应把相关请求部件聚合成一个自定义提取器结构体,而不是继续堆参数。
原理流程
- handler 函数被包装进
Handler适配器。 - 编译器检查参数元组是否实现对应提取器 trait。
- arity 在 16 以内通过;超出则找不到 trait 实现。
- 报错指向参数元组不满足约束,需聚合参数。
代码或图示
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> 是最底层形态,可直接构造。
原理流程
- handler 执行完成,得到返回值。
- 适配器调用
IntoResponse::into_response。 - 转换过程写入状态码、响应头与 body。
- 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 结构。
原理流程
- handler 被包装成返回 Future 的服务节点。
- 类型系统检查 Future 及其捕获变量
Send + 'static。 - 状态在多线程间共享,检查
Send + Sync + 'static。 - 约束满足后才允许注册到 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,不是就不能直接挂路由。
原理流程
get(handler)要求 handler 实现Handlertrait。- 编译器检查返回类型是否为可 await 的 Future。
- 同步函数不满足,编译报错。
- 阻塞业务放入
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 类型,本身就不合法。
原理流程
- 编译报错指向 handler 参数元组的 trait bound。
- 逐个参数判断实现的是哪个提取器 trait。
- 把
FromRequest类型移到最后一位。 - 确认没有第二个 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,避免散落的元组写法。
原理流程
- handler 返回元组。
IntoResponse实现按位置取出状态码、头、body。- body 元素再转成响应体。
- 组合成最终
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 挂在层上,对经过该层的请求统一限流。提取器内建限制与层限制关注点不同:前者按提取器消费行为控制,后者在进入路由前统一拦截。上传接口需要放大阈值时要同时确认两处,避免一处仍按小阈值拒绝。
原理流程
- 请求进入层链,
RequestBodyLimitLayer先按全局阈值拦截超限 body。 - 进入路由后,提取器读取 body 时再过
DefaultBodyLimit。 - 超限返回 413 类响应。
- 未超限 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 会被拒绝。
原理流程
- 校验 Content-Type 为 multipart 并解析 boundary。
- 提取器持有 body 流,生成字段迭代句柄。
- handler 循环
next_field()取下一块。 - 每块读取文件名、字段名与字节内容。
代码或图示
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,业务上要区分普通字段与文件字段。
原理流程
next_field()返回当前分块的Field。- 读取分块头得到字段名、文件名、内容类型。
- 按字段类型选择读全量字节或流式处理。
- 处理完进入下一分块。
代码或图示
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 读取两处控制。落盘用异步文件操作,避免阻塞运行时。
原理流程
- 读取字段字节或流式内容。
- 清洗文件名:去掉分隔符、
..、控制字符。 - 生成服务端安全文件名,拼接到固定根目录并校验规范化后仍在目录内。
- 写入文件并记录元数据。
代码或图示
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() 适合小附件,大文件必须走流。还要限制字段数量与请求并发,避免多字段耗尽资源。
原理流程
- 层限制先拦截超限总 body。
- 遍历字段时累计每个字段字节数,超限提前中止。
- 大字段按 chunk 写入文件,小字段读入内存。
- 处理结束返回结果或拒绝。
代码或图示
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 编码。
原理流程
- 读取请求 Content-Type。
- 按编码类别选择对应提取器。
- 提取器校验类型并解析 body。
- 解析结果进入 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 任意改写成危险方法。
原理流程
- 请求进入自定义层。
- 检查覆盖头或表单字段是否存在合法方法。
- 合法则改写请求
Method。 - 内层 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 接口走路由分发,预检请求由层短路处理。
原理流程
- 浏览器判断跨域,先发送 OPTIONS 预检。
CorsLayer检查Origin、方法、头,生成预检响应。- 预检通过后浏览器再发实际请求。
- 未挂层时 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 语义,需谨慎。测试时应同时覆盖已注册方法与未注册方法两种响应。
原理流程
- 路径命中,方法未注册,分发器生成 405 响应。
- 响应沿层链回传,外层层识别 405。
- 层把 body 替换为统一错误 JSON,保留或补充
Allow。 - 客户端收到规范错误体。
代码或图示
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 抽象上。
原理流程
- 组装
Router<S>并with_state收窄为Router<()>。 Router<()>实现Service<Request<Body>>。into_make_service生成克隆 Router 的 MakeService。- 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 使用:泛型状态未收窄,类型不满足。
追问
Servicetrait 的核心方法是什么?答: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<()>,状态句柄在克隆间共享。
原理流程
Router<()>调用into_service得到 Service。- 或调用
into_make_service得到工厂。 - 测试用
ServiceExt::oneshot直接对 Service 发一次请求。 - 生产由 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。
原理流程
- hyper 监听到新连接。
- 调用 MakeService 生成该连接的 Service。
- 连接内多个请求由同一 Service 处理。
- 连接关闭后实例销毁,共享资源由 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 中间件或第三方服务多数已满足约束,直接挂载即可。
原理流程
- 定义结构体实现
Service<Request<Body>>。 poll_ready报告是否可接收请求。call处理请求,返回响应 Future。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。
原理流程
- 调用方先轮询
poll_ready,未就绪则挂起等待通知。 - 就绪后调用
call(req)取得响应 Future。 - Future 被调度执行,最终产出响应。
- 中间件在外层包装这两个方法,加入日志、超时、鉴权等逻辑。
代码或图示
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。
原理流程
- 调用
layer(L),把 L 加入 Router 的层序列。 - 转换 Service 时按序列逐层包裹:外层先入。
- 请求沿外层到内层穿过各层。
- 响应沿内层到外层回传,各层可改写响应。
代码或图示
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 官方推荐的测试形态之一。
原理流程
- 构造 Router 与所需 State。
into_service得到测试 Service。Request::builder组装请求,oneshot发送。- 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。
原理流程
- oneshot 得到
Response<Body>。 - 断言
resp.status()与期望状态码。 - 查询响应头断言关键头存在或取值。
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,测试替身也要满足。
原理流程
- 定义测试用 AppState(可含内存替身)。
- 调用路由构造函数得到
Router<AppState>。 with_state(test_state)收窄为Router<()>。- 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 映射是否正确。不要在测试里直接调用提取器内部方法,保持黑盒请求视角。
原理流程
- 按失败场景构造请求(错误路径、错误头、错误 body)。
- oneshot 发送到测试 Service。
- 断言状态码为拒绝对应的状态。
- 解析 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 失败形式出现,需一并核对。
原理流程
- 定位报错参数位置与类型。
- 判断该类型实现
FromRequestParts还是FromRequest。 - 调整参数顺序或补 trait 实现。
- 核对 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,提取器不会执行。
原理流程
- 记录请求方法与完整路径。
- 对照父前缀、子路径拼接出的完整模板。
- 检查占位段语法、段数、通配段位置。
- 最小挂载复现,逐步加回嵌套与层。
代码或图示
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、字符串接收后转换)。
原理流程
- 按状态码与拒绝来源确定提取器类别。
- 打印路径、查询串、原始 body。
- 对照 DTO 字段名、类型与必填约束。
- 修正输入或调整反序列化定义后复测。
代码或图示
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。
原理流程
- 读取请求
Content-Type头。 - 提取器比对期望媒体类型。
- 不匹配直接拒绝 415。
- 匹配通过后才解析 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 确认命中段。
原理流程
- 确认请求完整路径与父层前缀。
- 剥去父前缀得到子树应看到的剩余路径。
- 对照子路由注册路径是否为相对写法。
- 逐层挂载验证,定位未命中的层级。
代码或图示
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 在解码前后段划分可能不同,具体行为以匹配库实现为准。点号、连字符属于静态段字符,模板与请求字面一致。排查时打印解码后的路径分段,对照模板段结构;通配段必须位于末尾,中间带通配是非法模板。
原理流程
- 取出解码后的请求路径,按
/分段。 - 对照模板:静态段、占位段、通配段的位置与数量。
- 跨段路径改用通配段模板。
- 复测并核对解码行为。
代码或图示
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 时,服务还没开始监听,因此不会造成线上请求期崩溃。
原理流程
- 第二次注册进入同一路径节点。
- 冲突检查发现方法分发器已存在。
- 构建期触发 panic,附重复路径信息。
- 修复方式:合并到同一
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} 段类型不同,注册不冲突,请求期静态段优先。理解注册冲突与请求优先级的区别:前者是构建期校验,后者是运行期匹配规则。模板语法非法(通配段位置错)也在解析阶段报错。
原理流程
- 新模板切分为段序列。
- 沿匹配树查找同层级节点。
- 节点结构等价且方法分发器已存在则冲突 panic。
- 段类型不同则共存,运行期按优先级选择。
代码或图示
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 行为随之变化。
原理流程
any/on生成带方法集合的MethodRouter。- 链式调用向分发器追加方法分支。
route登记到路径节点。- 请求按方法选择分支。
代码或图示
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 冒泡规则对两者同样适用。
原理流程
- 路径表未命中。
- 查当前 Router 的兜底节点。
fallback走 handler 适配器;fallback_service直接调用外部 Service。- 兜底响应沿层链回传。
代码或图示
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、层与测试构造请求时使用正确类型。
原理流程
- 请求行解析出方法字节序列。
- http crate 构造
Method值。 - 提取器把
Method注入 handler 参数。 - 业务按常量比较分支。
代码或图示
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 或在收窄前注入。测试中替换状态时,要确认替换发生在哪一层收窄之前。
原理流程
- 子树作为
Router<S>挂入父树。 - 父树
with_state把状态分发到包含子树在内的节点。 - 子树 handler 用
State<S>取出共享句柄。 - 子树已收窄为
()时,原状态不再可取。
代码或图示
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 完成,位置错位或字段缺失都返回路径相关拒绝。重构模板调整参数顺序时,元组绑定要同步调整,结构体则不受顺序影响。
原理流程
- 命中模板后按顺序收集各占位段字符串。
- 元组反序列化按位置填入。
- 结构体反序列化按字段名匹配。
- 类型转换失败返回
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 或拒绝处理。
原理流程
- 请求 URI 拆成路径与查询串两部分。
Path提取路径段并反序列化。Query解析查询串并反序列化。- 两类值一起进入 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 限制约束。
原理流程
- handler 返回
Json(value)。 IntoResponse调用 serde 序列化 T。- 写入 JSON Content-Type 与 body。
- 响应沿层链回传。
代码或图示
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,统一错误与包装类型单独实现。
原理流程
- handler 产出返回值。
- 按类型找到对应
IntoResponse实现。 - 实现写入状态码、头与 body。
- 生成标准
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。
原理流程
- 请求进入提取器阶段,失败返回 Rejection 响应。
- 提取成功进入 handler 执行业务。
- handler panic 由 panic 层或运行时捕获。
- 两类错误分别映射状态码与日志。
代码或图示
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 跨请求共享;取舍在状态共享与中间件主题展开。
原理流程
- 外层层把值写入请求扩展。
- 请求进入路由,扩展随 Parts 向下传递。
Extension<T>按类型取出值。- 缺失或类型不符返回拒绝。
代码或图示
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。绕过提取器意味着拒绝处理、类型校验都要自己实现。常规业务接口仍推荐组合提取器,保持代码可读。
原理流程
- handler 最后一个参数声明
Request<Body>。 - 适配器把完整请求传给 handler。
- 业务代码拆分 Parts 与 Body。
- 自行构造响应返回。
代码或图示
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 是内层业务节点,中间件在其外层。层挂载范围(全局/路由级)决定中间件覆盖哪些端点;具体层顺序与状态访问在状态共享与中间件主题展开。
原理流程
- 层函数接收
Request与Next。 - 前置逻辑读请求、做鉴权或日志。
- 调用
next.run(req)进入内层链,最终到达 handler。 - 后置逻辑加工响应后返回。
代码或图示
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,请求级上下文进扩展。
原理流程
- 启动期确定应用级资源,构造 AppState。
- 请求到达,层从认证结果生成请求上下文写入扩展。
- handler 分别通过
State与Extension取用。 - 请求结束扩展释放,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 结构。
原理流程
- 构造未注册路径请求,oneshot 发送。
- 断言 404 状态与兜底 body。
- 对已注册路径换未注册方法发请求。
- 断言 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 极少,通常依赖自动实现。
原理流程
- 函数签名被解析为参数类型序列与返回类型。
- 编译器推断提取器元组
T与状态S。 - 检查参数提取约束、返回
IntoResponse、FutureSend + 'static。 - 满足后
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。
原理流程
- handler 被调用,构造返回 Future。
- 类型检查 Future 及其捕获值
Send + 'static。 - 不满足则在注册或调用期编译报错。
- 修复方式: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。理解元组粒度后能明白:聚合多个相关参数为自定义结构体,本质是减少元组元素数量并把解析逻辑内聚。提取器失败短路:任一前置提取器失败,后续不再构造。
原理流程
- 参数列表被视为元组类型。
- 编译器选择对应 arity 的 trait 实现。
- 依次调用各元素提取器,部件先于 body。
- 失败短路,成功则组装参数调用 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、配置项、状态码映射标注验证点。
原理流程
- 识别版本敏感点:拒绝类型、默认值、嵌套行为、feature 名。
- 打开 docs.rs/axum/latest 对应条目核对签名与文档。
- 写最小用例实际运行,打印行为结果。
- 无法确认的内容标注待确认与验证步骤。
代码或图示
待确认示例:
- 验证对象: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> 直接拿到解码文本,数值类型再做解析。中文作为文件名或标识时,注意服务端文件系统编码与日志显示。编码斜杠是否跨段行为版本敏感,需用例验证。不要在路径参数里传递未编码的原始特殊字符。
原理流程
- 客户端对路径段做百分号编码。
- 匹配树在解码后的段上比对。
Path<T>取出解码字符串并反序列化。- 业务使用解码后的值,落盘或入库前再做校验。
代码或图示
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 配置。
原理流程
- API 路由表先注册业务接口。
nest_service挂静态前缀或fallback_service挂文件服务。- 请求先匹配 API,未命中进入文件服务。
- 文件服务按剩余路径查找磁盘文件并响应。
代码或图示
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-dirfeature,具体名称以 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,再决定查层还是查路由。
原理流程
- 请求方法为 HEAD/OPTIONS 进入分发器。
- 预检 OPTIONS 先被 CORS 层识别并响应。
- 非预检请求查方法表,命中则调用 handler。
- 未命中返回 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,再判断位置或类型问题。
原理流程
- 列出 handler 所需数据来源。
- 按来源匹配对应提取器。
- 部件提取器排前,body 提取器置末。
- 无现成提取器时自定义实现对应 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。线上问题先还原请求样例,再在测试里复现,避免凭感觉改代码。
原理流程
- 抓请求方法、完整路径、头、body 编码。
- 核对 Router 模板、嵌套前缀与方法注册。
- 命中后逐个提取器归类,确认位置与拒绝类型。
- 检查 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。