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

04.4.3.2 状态共享与中间件

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

04.4.3.2-001 State<S> 提取器如何取出应用共享状态?

一句话结论

State<S> 从路由注入的状态句柄中取出类型为 S 的共享值;状态在 with_state 时分发到各节点,handler 通过该提取器按类型取用,跨请求共享同一份内部资源。

概念解释

State 是 axum 的依赖注入入口:应用级资源(连接池、HTTP 客户端、配置)在启动期构造一次,放入 AppState,随路由树分发。State<S> 实现 FromRequestParts,可排在 handler 参数前面。提取器拿到的是句柄克隆,内部通常是 Arc,多个请求共享底层数据。与全局变量相比,State 可在测试中替换,也在类型上明确声明依赖。

原理流程

  1. 构造 AppState 实例,持有共享资源句柄。
  2. Router 调用 with_state(state) 把状态分发给路由节点。
  3. 请求到达 handler,State<S> 提取器取出状态克隆。
  4. 业务通过句柄访问共享资源。

代码或图示

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

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

async fn ping(State(s): State<AppState>) -> String {
    format!("port={}", s.port)
}

let app = Router::new()
    .route("/ping", get(ping))
    .with_state(AppState { port: 8080 });

常见误区

  • 把请求级数据放进 State:跨请求共享会串号。
  • 状态类型与 with_state 传入类型不一致:编译期提取器 bound 失败。

追问

  • State 提取器要求 S 满足什么约束?答:Clone + Send + Sync + 'static,以 docs.rs/axum 当前版本为准。
  • 多个不同类型的状态能同时提取吗?答:Router 只持有一个状态类型,子状态字段在该类型内聚合;多类型需分别收窄后组合。

04.4.3.2-002 with_state 在路由组装的哪个环节调用,做了哪些事?

一句话结论

with_state 在 Router 组装末尾调用,把状态注入节点并把 Router<S> 收窄为 Router<()>;只有收窄后的路由才能转成 MakeService 对外服务。

概念解释

Router<S> 的 S 是编译期状态依赖标记。组装阶段可以先合并子路由,最后统一 with_state。该方法遍历路由节点,把状态句柄存入需要 State<S> 的位置,并完成类型收窄。子路由也可提前 with_state 收窄为 Router<()>,再与父树组合。状态注入发生在构建期,运行期不再传入新状态。

原理流程

  1. 组装 Router<AppState>,登记各节点的状态需求。
  2. 调用 with_state(app_state),句柄分发到节点。
  3. 类型参数变为 Router<()>。
  4. into_make_service 转成服务工厂。

代码或图示

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

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

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

let app: Router<()> = Router::new()
    .route("/env", get(env))
    .with_state(AppState { env: "prod".into() });

常见误区

  • 未 with_state 就 into_make_service:类型未收窄,编译报错。
  • 运行期想再更换 State:状态在构建期固化,更换需重建路由。

追问

  • 一个路由树可以调用多次 with_state 吗?答:可以对子树分别收窄,外层最终只补自身剩余状态;类型必须兼容。
  • with_state 会克隆整份状态吗?答:传入一份句柄,节点持有的是克隆句柄,内部 Arc 不复制底层资源。

04.4.3.2-003 AppState 类型为什么必须满足 Clone + Send + Sync + 'static?

一句话结论

服务在多线程下被克隆与并发访问,状态句柄需要可克隆、可跨线程传递与共享、不持有短生命周期借用;这些约束由 Clone + Send + Sync + 'static 表达。

概念解释

MakeService 为每个连接克隆 Router,状态句柄随之复制,因此需要 Clone。多个请求在不同工作线程并发访问状态,内部数据必须线程安全,即 Send + Sync。服务存活期长于单次请求,句柄不能借用栈上临时数据,因此要求 'static。重资源用 Arc 共享,可变部分用 tokio::sync 锁或原子类型。不满足约束会在 with_state 或路由注册阶段编译报错。

原理流程

  1. 定义 AppState 字段,逐字段检查线程安全与生命周期。
  2. 派生或实现 Clone,内部共享资源用 Arc。
  3. 路由注册与 with_state 阶段校验 Send + Sync + 'static。
  4. 运行期多线程共享访问。

代码或图示

use std::sync::Arc;
use std::sync::atomic::AtomicU64;

#[derive(Clone)]
struct AppState {
    pool: Arc<Pool>,
    counter: Arc<AtomicU64>,
}

struct Pool;

常见误区

  • 状态字段放 Rc 或 RefCell:不满足 Send + Sync。
  • 状态持有借用字符串或引用:'static 检查失败,应持有 String 或 Arc<str>。

追问

  • 字段是 Arc<Mutex<T>> 时 AppState 自动 Send/Sync 吗?答:Arc 内部 T 满足 Send + Sync 时整体满足,锁类型选择见并发主题。
  • 如何快速验证状态约束?答:with_state 编译报错会指出不满足的 trait 与字段类型。

04.4.3.2-004 State 内部需要可变共享数据时,锁结构如何选择?

一句话结论

AppState 内部可变数据按临界区时长选择:短临界区用 std::sync::Mutex/RwLock,异步等待或长临界区用 tokio::sync 锁;跨线程共享外层包 Arc。

概念解释

State 句柄跨线程共享,内部可变量必须线程安全。同步锁持有期间不能 await,适合纯内存短操作;异步锁允许在持有期间等待,但开销更高。计数器类无冲突场景用原子类型,避免整把锁。读多写少可用 RwLock。选择原则:不在异步上下文持有阻塞锁,临界区不做 IO。锁中毒与死锁问题在并发主题展开,这里只绑定 axum State 的放置方式。

原理流程

  1. 识别状态字段的读写并发模式。
  2. 计数类选原子类型,短临界区选同步锁,异步场景选异步锁。
  3. 外层 Arc 共享,AppState 派生 Clone。
  4. handler 内取锁、改值、尽快释放。

代码或图示

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

#[derive(Clone)]
struct AppState { kv: Arc<RwLock<Vec<String>>> }

async fn add(State(s): State<AppState>) -> String {
    s.kv.write().unwrap().push("item".into());
    s.kv.read().unwrap().len().to_string()
}

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

常见误区

  • 在 async handler 里长期持有 std::sync::MutexGuard:阻塞运行时线程。
  • 用 RwLock 却存在大量写竞争:读多写少才划算。

追问

  • tokio::sync::Mutex 与 std::sync::Mutex 怎么选?答:需要在持有锁期间 await 用前者,纯内存短临界区用后者,避免不必要的异步锁开销。
  • 状态里放全局缓存要注意什么?答:缓存淘汰与容量上限在状态内维护,不能无界增长。

04.4.3.2-005 父路由与子路由状态类型不同时如何组合?

一句话结论

同一未收窄树内状态类型必须一致;子系统状态不同时,先在子树 with_state 收窄为 Router<()>,再 nest/merge 到父树,跨树共享数据另走 Extension。

概念解释

Router<S1> 与 Router<S2> 不能直接合并,泛型必须对齐。常见工程形态:核心子系统共享主 AppState,个别子模块自带配置,先在模块内用自己的状态类型收窄。收窄后子树不再持有主状态,需要主资源就在收窄前把所需句柄放进子状态。父树最终 with_state 只处理自身剩余状态。

原理流程

  1. 子模块定义自己的子状态类型并构造路由。
  2. 子模块 with_state 收窄为 Router<()>。
  3. 父树挂载收窄后的子路由。
  4. 父树统一注入主状态。

代码或图示

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

#[derive(Clone)]
struct MainState { label: String }
#[derive(Clone)]
struct SubState { limit: u32 }

async fn sub_handler(State(s): State<SubState>) -> String { s.limit.to_string() }

fn sub_router() -> Router<()> {
    Router::new().route("/sub", get(sub_handler))
        .with_state(SubState { limit: 10 })
}

let app = Router::new()
    .nest("/api", sub_router())
    .with_state(MainState { label: "main".into() });

常见误区

  • 父树 Router<MainState> 直接合并 Router<SubState>:编译报类型不匹配。
  • 子树收窄后又在 handler 取主状态:类型已不可用。

追问

  • 子树需要主状态中的连接池怎么办?答:收窄前把池句柄克隆进子状态字段,或通过 Extension 向下传递。
  • 收窄时机放模块内还是根路由?答:模块内收窄便于独立测试,根路由统一收窄便于集中注入,按工程约定选择。

04.4.3.2-006 状态在嵌套子路由中的可见范围与注入时机是什么?

一句话结论

未收窄的子树随父树一起在父层 with_state 时注入状态,子树 handler 可读同一句柄;提前收窄的子树只保留注入时的状态,两者可见范围不同。

概念解释

嵌套本身不复制状态,只是路径挂载。状态注入沿构建期路由树分发:父树 with_state 覆盖所有未收窄子节点。子树内部提前 with_state 后类型变为 (),与父状态脱钩。排错时若子 handler 取不到期望状态,先检查子树是否被提前收窄。状态句柄在克隆间共享,字段修改对子树同样可见。

原理流程

  1. 父树组装未收窄子路由。
  2. 父层 with_state 遍历节点注入状态。
  3. 子树 handler 按类型提取状态。
  4. 提前收窄的子树使用自身注入值。

代码或图示

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

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

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

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

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

常见误区

  • 以为嵌套会给子树复制独立状态:句柄克隆,内部资源共享。
  • 子树收窄后再期待父状态向下传递:已脱钩。

追问

  • 状态字段修改对子树立即可见吗?答:共享内部资源的修改通过句柄可见,可见性语义由锁或原子类型保证。
  • 测试父状态替换会影响子树吗?答:未收窄子树随父状态一起替换,收窄子树需单独构造测试状态。

04.4.3.2-007 自定义提取器或中间件如何访问 State?

一句话结论

FromRequestParts/FromRequest 实现与 from_fn_with_state 中间件都带状态参数,可按类型取用 State;普通 from_fn 中间件不直接拿 State,需要时用带状态形式或从扩展读取。

概念解释

提取器 trait 方法第二参数是 &S,可直接读共享状态。中间件分两种:from_fn 只接收请求与 Next,状态不直接传入;from_fn_with_state 额外注入 State<S> 参数。需要在鉴权、限流中间件里读配置或缓存时,选用带状态形式。状态在中间件阶段与 handler 同源,都是启动期注入的句柄。

原理流程

  1. 提取器实现方法签名接收 &S。
  2. 带状态中间件形式增加 State<S> 参数。
  3. 按字段读取配置、缓存或句柄。
  4. 校验结果写入扩展或直接短路响应。

代码或图示

use axum::{
    extract::State, http::Request, middleware::{self, Next}, response::Response, Router,
};

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

async fn guard<B>(
    State(s): State<AppState>,
    req: Request<B>,
    next: Next<B>,
) -> Response {
    if s.secret.is_empty() {
        return Response::new(axum::body::Body::from("no secret"));
    }
    next.run(req).await
}

let app = Router::new().route_layer(middleware::from_fn_with_state(
    AppState { secret: "x".into() },
    guard,
));

常见误区

  • 普通 from_fn 闭包内去拿 State:没有状态参数,拿不到。
  • 中间件里做阻塞查询拖慢链路:状态访问应保持轻量,重逻辑下沉服务层。

追问

  • from_fn_with_state 的状态与路由 with_state 是同一份吗?答:注入值按调用处传入,保持一致即可;二者类型需兼容。
  • 中间件读取状态后能修改吗?答:可以访问内部可变字段,线程安全约束与 handler 一致。

04.4.3.2-008 数据库连接池放入 AppState 的理由与典型形态是什么?

一句话结论

连接池是重资源,应用内只构造一次并由 Arc 共享,放进 State 供各 handler 取用;每个请求从池中借连接,用完归还,避免每请求新建连接。

概念解释

数据库连接建立成本高,连接池统一管理连接数量与复用。典型形态:State 持有 Arc<Pool>(如 sqlx 的 Pool<Postgres>,连接池类型本身可克隆内部共享)。handler 提取 State 后调用池方法获取连接执行查询。池的大小、超时、回收策略在启动期配置。把池放 State 而非全局变量,便于测试替换为内存替身或测试库。

原理流程

  1. 启动期读取配置,构造数据库连接池。
  2. 池句柄放入 AppState 并 with_state。
  3. handler 提取 State,从池内借连接执行查询。
  4. 请求结束连接归还池中,不销毁。

代码或图示

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

// 示例类型,实际池类型以所选数据库驱动为准
struct DbPool;

#[derive(Clone)]
struct AppState { db: Arc<DbPool> }

async fn count(State(s): State<AppState>) -> String {
    // 实际调用池获取连接并查询
    format!("pool ready")
}

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

常见误区

  • 每个请求新建连接:握手与认证开销随请求数放大。
  • 把单个数据库连接放进 State:连接不具备并发共享能力。

追问

  • 连接池类型需要再包 Arc 吗?答:多数驱动池内部已共享、可直接克隆放入 State;是否外包 Arc 按具体池类型的 Clone 语义确认,以驱动文档为准。
  • 事务边界放在哪里?答:在 handler 或服务层从池取连接开启事务,池本身不持有跨请求事务。

04.4.3.2-009 HTTP 客户端放入 State 为什么能复用连接池?

一句话结论

reqwest::Client 内部维护连接池与线程配置,构造成本高;放入 State 全局共享一个 Client,各请求复用底层连接与 DNS 缓存,避免每请求重建客户端。

概念解释

外部 API 调用的 HTTP 客户端应单例化:Client 内部管理 keep-alive 连接、连接池、中间件配置。AppState 持有 Client 克隆句柄(Client 本身可廉价克隆)。handler 通过 State 取出发起出站请求。超时、重试、连接数上限在 Client 构造期配置。测试时可替换为假客户端 trait 实现,避免真实出站调用。

原理流程

  1. 启动期构造 reqwest::Client,配置超时与连接池。
  2. Client 句柄放入 AppState。
  3. handler 提取 State,复用 Client 发起请求。
  4. 底层 keep-alive 连接在多次出站调用间复用。

代码或图示

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

#[derive(Clone)]
struct AppState { http: reqwest::Client }

async fn fetch(State(s): State<AppState>) -> String {
    match s.http.get("https://example.com").send().await {
        Ok(_) => "ok".into(),
        Err(_) => "err".into(),
    }
}

let client = reqwest::Client::new();
let app = Router::new().route("/fetch", get(fetch))
    .with_state(AppState { http: client });

常见误区

  • handler 内 reqwest::Client::new():每请求新建客户端,连接池无法复用。
  • 客户端不设超时:下游慢响应会拖垮本服务并发。

追问

  • reqwest::Client 克隆昂贵吗?答:克隆为句柄复制,底层连接池共享,具体以 reqwest 文档为准。
  • 出站调用需要按租户配置不同客户端怎么做?答:State 持有客户端注册表或 trait 工厂,按上下文取对应实例。

04.4.3.2-010 配置信息如何放进 AppState,为什么不读全局环境变量?

一句话结论

启动期把配置解析成强类型结构体放入 State,handler 通过句柄读取;集中注入便于测试替换、类型校验与多环境切换,避免业务代码散落读取环境变量。

概念解释

配置在启动阶段从环境变量或配置文件加载,校验后构造 Config 结构体,包进 AppState。业务 handler 只依赖类型化配置,不直接 std::env::var。这样配置解析错误在启动期暴露,测试可传入自定义配置。敏感配置不进日志与错误响应。配置变更是否热更新取决于状态内部结构,普通只读配置启动后固定。

原理流程

  1. 启动期加载环境变量/配置文件。
  2. 反序列化为强类型 Config 并校验。
  3. Config 句柄放入 AppState 注入路由。
  4. handler 读取配置字段完成业务。

代码或图示

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

#[derive(Clone)]
struct Config { max_items: u32 }

#[derive(Clone)]
struct AppState { config: Arc<Config> }

async fn limit(State(s): State<AppState>) -> String {
    s.config.max_items.to_string()
}

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

常见误区

  • handler 内直接读 env::var:配置散落、测试难以替换、解析错误延迟到请求期。
  • 配置结构体不可克隆:放入 State 需要 Clone,内部用 Arc 共享大配置。

追问

  • 配置含密钥能直接放 State 打印吗?答:不能,日志与错误响应必须脱敏;State 只在代码内使用。
  • 多环境配置如何区分?答:启动期按环境选择配置源,注入不同 Config 实例,路由代码不变。

04.4.3.2-011 State 克隆开销来自哪里,为什么内部资源要用 Arc?

一句话结论

AppState 每连接/每提取一次都会克隆句柄,克隆成本应是指针级;重资源放进 Arc,克隆只增加引用计数,避免复制连接池、客户端、大配置。

概念解释

Router 克隆、Service 工厂产出、提取器取状态都会复制 AppState。若字段直接持有大对象,每次克隆都深拷贝,并发越高开销越大。Arc 把重资源放到堆上,结构体只复制指针与计数。小字段(数值、短字符串)可直接放结构体。判断标准:字段构造成本与体积,重资源一律 Arc 句柄化。

原理流程

  1. 识别状态字段中的重资源。
  2. 重资源包 Arc,小值直接存放。
  3. AppState 派生 Clone,克隆复制句柄。
  4. 运行期句柄复制低成本,底层资源共享。

代码或图示

use std::sync::Arc;

#[derive(Clone)]
struct AppState {
    pool: Arc<Pool>,
    http: Arc<reqwest::Client>,
    max_items: u32,
}

struct Pool;

常见误区

  • 状态字段直接放大数组或无 Arc 的池:克隆成本随并发放大。
  • 为了省 Arc 把全局单例塞进去:失去 State 注入与测试替换能力。

追问

  • Arc::strong_count 能用来排查句柄泄漏吗?答:可辅助观察引用计数变化,但业务判断不能依赖计数,资源回收由 Arc 规则保证。
  • 配置字符串每次克隆有多大影响?答:短字符串克隆成本低,超长配置仍建议 Arc<str> 或 Arc<String>。

04.4.3.2-012 测试中如何构造并替换 State 验证不同行为?

一句话结论

测试内构造目标 AppState(含内存替身或最小配置),路由 with_state 后 oneshot 发请求断言;不同用例注入不同状态实例,业务代码不改动。

概念解释

State 注入的核心收益是可测试性:生产用真实池与客户端,测试用内存实现或假响应。路由构造函数接收状态类型,测试组装时传入替身。需要替换外部依赖时,State 内放 trait 对象或仓库 trait,测试注入假实现。状态替身仍需满足 Clone + Send + Sync + 'static。请求级差异(用户身份)走扩展,不放 State。

原理流程

  1. 定义测试用 AppState 或替身实现。
  2. 调用路由构造函数得到 Router<AppState>。
  3. with_state(test_state) 收窄后转 Service。
  4. oneshot 断言行为,按用例更换状态实例。

代码或图示

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

#[derive(Clone)]
struct AppState { flag: bool }

async fn handler(State(s): State<AppState>) -> String {
    if s.flag { "on" } else { "off" }.into()
}

#[tokio::test]
async fn toggle() {
    let app = Router::new().route("/", get(handler))
        .with_state(AppState { flag: true });
    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, "on");
}

常见误区

  • 测试依赖全局真实资源:用例隔离差,外部不可用时失败。
  • 替身类型不满足 Clone/Send:with_state 编译不过。

追问

  • 数据库替身怎么做?答:State 持有仓库 trait,测试注入内存实现;具体抽象在数据访问主题展开。
  • 多用例共享可变状态如何隔离?答:每用例新建状态实例,含计数器时重置后再跑。

04.4.3.2-013 AppState 字段应聚合分组还是扁平罗列,工程上怎么组织?

一句话结论

按子系统聚合字段(数据库、HTTP、配置、缓存),对外暴露分组后的句柄;字段过多时拆成子结构体,避免一个巨型状态对象遍布所有 handler。

概念解释

小型服务扁平罗列字段即可;增长后按职责分组:db、http、config、cache 各为子结构体或句柄。handler 只取自己需要的分组,降低耦合。分组后子系统可独立测试与替换。状态命名保持稳定,字段变更同步更新各 handler 提取处。不要把无关请求级 DTO 塞进状态结构。

原理流程

  1. 梳理应用级资源清单。
  2. 按子系统分组为字段或子结构体。
  3. AppState 聚合各组并派生 Clone。
  4. handler 按需要提取对应分组字段。

代码或图示

use std::sync::Arc;

#[derive(Clone)]
struct Db { pool: Arc<DbPool> }
#[derive(Clone)]
struct Http { client: Arc<reqwest::Client> }
#[derive(Clone)]
struct Cfg { max_items: u32 }

#[derive(Clone)]
struct AppState {
    db: Db,
    http: Http,
    config: Cfg,
}

struct DbPool;

常见误区

  • 所有字段平铺在一个结构体,handler 被迫感知无关子系统。
  • 分组过碎导致嵌套取值层级过深,按团队约定平衡。

追问

  • 分组子结构体需要 Arc 吗?答:组内重资源 Arc,组结构体本身可克隆;避免整组深拷贝。
  • 状态分组后中间件如何取配置?答:带状态中间件提取 AppState 后读对应分组字段。

04.4.3.2-014 状态中的重资源能否惰性初始化,而不在启动期全部构造?

一句话结论

可以用 OnceLock/OnceCell 或 OnceCell 句柄在首次访问时初始化;需要跨线程共享时选线程安全的 OnceLock,异步初始化要处理并发等待与失败重试。

概念解释

部分资源不一定每个环境都需要,启动期全构造浪费成本。状态内放 Arc<OnceLock<T>>,首次访问初始化后复用。注意异步初始化不能在 OnceLock 初始化闭包内 await;需要异步懒加载时用专门的懒加载结构或启动期预热。初始化失败要能返回明确错误,不能 panic 在请求路径上。惰性初始化增加复杂度,启动期可构造的资源优先启动期构造。

原理流程

  1. 状态字段放 OnceLock 或等价惰性句柄。
  2. 首次访问检查是否已初始化。
  3. 未初始化则构造资源并写入锁。
  4. 后续访问直接取用已初始化值。

代码或图示

use std::sync::{Arc, OnceLock};

#[derive(Clone)]
struct AppState {
    lazy: Arc<OnceLock<Heavy>>,
}

struct Heavy;

impl AppState {
    fn get(&self) -> &Heavy {
        self.lazy.get_or_init(|| Heavy)
    }
}

常见误区

  • 在 OnceLock 闭包里做异步初始化:阻塞初始化器且无法 await。
  • 初始化失败仍继续放行:应在首次访问返回错误响应或启动期提前校验。

追问

  • 异步懒加载用什么结构?答:可在启动期预热,或用支持异步初始化的并发原语;具体选型以工程依赖为准,待确认点对照 docs.rs 当前版本。
  • 惰性初始化会影响首次请求延迟吗?答:首次访问承担初始化成本,对延迟敏感的接口应启动期预热。

04.4.3.2-015 Extension<T> 提取器如何读取请求扩展中的值?

一句话结论

Extension<T> 按类型 T 从请求扩展中取出值;值由前置层或节点写入,缺失或类型不符时提取器拒绝,它实现 FromRequestParts,不消费 body。

概念解释

扩展是请求上的类型键值存储,适合放置请求级上下文:认证主体、请求 ID、解析后的租户。Extension<T> 提取器在 handler 参数中声明类型即可取出。类型即键,不同类型互不覆盖。与 State 的生命周期区别是扩展跟随单次请求。读取侧不负责写入,写入必须在前置层完成。

原理流程

  1. 前置层把类型化值写入请求扩展。
  2. 请求进入路由,扩展随 Parts 向下传递。
  3. Extension<T> 按类型查找取值。
  4. 成功传入 handler,失败返回拒绝。

代码或图示

use axum::Extension;

#[derive(Clone)]
struct CurrentUser { id: u64 }

async fn me(Extension(user): Extension<CurrentUser>) -> String {
    user.id.to_string()
}

常见误区

  • 期望在 handler 内首次读取就有值:写入动作必须发生在前置层。
  • 两个不同类型使用相同语义键:类型隔离不会冲突,但要避免类型命名混淆。

追问

  • 扩展值为什么常要求 Clone?答:提取器按值取出,可克隆类型便于复用;具体约束以当前版本文档为准。
  • 扩展里能放错误类型吗?答:可以放任意满足约束的类型,但错误响应仍应走返回值或拒绝链路。

04.4.3.2-016 如何把值插入请求扩展,Extension 层怎么挂?

一句话结论

把 Extension(value) 作为层挂到 Router 或路由上,值在请求处理前插入扩展;后续 handler 与下游层用 Extension<T> 读取,值按类型存储。

概念解释

axum 提供 Extension 类型既可作提取器也可作层:Router::layer(Extension(value)) 在服务链外层插入值。插入的值随每个请求向下传递。需要多个值就挂多个 Extension 层或聚合为一个上下文结构体。值要满足跨请求传递约束。层挂载范围决定扩展对哪些路由可见。

原理流程

  1. 构造需要共享的上下文值。
  2. layer(Extension(value)) 挂到目标 Router/路由。
  3. 请求到达时层把值写入扩展。
  4. 下游提取器按类型读取。

代码或图示

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

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

async fn show(Extension(t): Extension<TraceId>) -> String { t.0 }

let app = Router::new()
    .route("/", get(show))
    .layer(Extension(TraceId("trace-1".into())));

常见误区

  • 把 Extension 层挂在路由内层导致前置中间件读不到:层顺序决定可见时机。
  • 插入不可克隆或不 Send 的值:层与服务链约束不满足。

追问

  • 每次请求插入的是同一个值吗?答:层持有的是构造时的值句柄,请求间共享;请求内变化应在自定义层里按请求写入。
  • 扩展与 State 插入方式有何不同?答:State 经 with_state 构建期注入,Extension 经层在请求链路注入。

04.4.3.2-017 State 与 Extension 如何取舍,判断标准是什么?

一句话结论

跨请求共享的应用资源进 State,单次请求产生的上下文进 Extension;判断依据是数据生命周期、构造成本与可见范围,二者不可互相替代。

概念解释

State 在启动期构造、全应用共享,适合连接池、客户端、配置;Extension 跟随一次请求,适合认证主体、请求 ID、租户标识。放错方向的典型症状:请求级身份放 State 导致多请求串号,重连接池放 Extension 导致每请求重建。中间件生成的上下文天然进扩展,handler 再读取。设计时先问数据属于应用级还是请求级。

原理流程

  1. 判断数据生命周期:应用级还是请求级。
  2. 应用级资源构造句柄放入 State。
  3. 请求级上下文由层写入 Extension。
  4. handler 分别用 State 与 Extension 取用。

代码或图示

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

#[derive(Clone)]
struct AppState { pool: String }
#[derive(Clone)]
struct AuthUser { id: u64 }

async fn handler(
    State(s): State<AppState>,
    Extension(u): Extension<AuthUser>,
) -> String {
    format!("{}:{}", s.pool, u.id)
}

常见误区

  • 当前登录用户存入 State:被后续请求覆盖,造成越权风险。
  • 连接池存入 Extension:每个请求重复构造,资源浪费。

追问

  • 配置值在请求中被临时覆盖放哪里?答:临时覆盖属于请求级上下文,放 Extension;持久配置仍在 State。
  • 两者都要求线程安全吗?答:跨线程传递与共享都要求 Send,Extension 值通常还需可克隆。

04.4.3.2-018 Extension 的类型键如何避免冲突,同类型重复插入会怎样?

一句话结论

扩展按类型作为键存储,不同类型天然隔离;同一类型重复插入会覆盖已有值,因此同类型上下文要聚合到结构体中,避免隐式覆盖。

概念解释

扩展内部是类型索引的映射,TypeId 区分条目。插入同类型新值覆盖旧值,调试时不易发现。工程做法:把一次请求的多个上下文字段聚合成一个结构体(如 RequestContext { user, tenant, trace_id }),作为单一类型插入。类型命名清晰,避免把语义不同的值用同类型包装。读取时类型不匹配视为缺失。

原理流程

  1. 层插入值时按类型索引写入扩展。
  2. 同类型已存在则被新值覆盖。
  3. 下游按类型读取,拿到当前值。
  4. 多字段上下文聚合为结构体避免多键管理。

代码或图示

use axum::Extension;

#[derive(Clone)]
struct RequestContext {
    user_id: u64,
    tenant: String,
    trace_id: String,
}

async fn handler(Extension(ctx): Extension<RequestContext>) -> String {
    format!("{} {} {}", ctx.user_id, ctx.tenant, ctx.trace_id)
}

常见误区

  • 同一类型在多层分别插入不同含义的值:后者覆盖前者。
  • 用裸 String/u64 做扩展值:类型粒度过粗,极易冲突。

追问

  • 扩展能存多个同类型值吗?答:标准按类型单值存放,多值用 Vec<T> 或聚合结构体;具体存储行为以当前版本为准。
  • 覆盖问题如何在测试中发现?答:构造多层插入同类型值的用例,断言最终读取值。

04.4.3.2-019 Extension 值的生命周期与请求边界是什么?

一句话结论

扩展值跟随请求 Parts 向下传递,响应结束即释放;不跨请求存活,也不会进入 State 的共享生命周期。

概念解释

每次请求构造独立 Parts,扩展条目挂在请求上。层写入、handler 读取都在同一请求链路内。请求结束响应返回,扩展随 Parts 销毁。需要跨请求保留的数据(会话记录、缓存)应存 State 或外部存储。理解生命周期可避免把扩展当全局缓存使用。嵌套服务若重建请求,扩展可能不被带入。

原理流程

  1. 请求进入链路,Parts 携带空扩展表。
  2. 各层按需写入类型化值。
  3. handler 与下游层读取扩展。
  4. 响应结束,扩展随请求释放。

代码或图示

use axum::Extension;

#[derive(Clone)]
struct ReqMeta { path: String }

async fn handler(Extension(m): Extension<ReqMeta>) -> String { m.path }
// ReqMeta 仅在本次请求内有效,下一个请求重新构造

常见误区

  • 把扩展当请求间缓存:下次请求读不到上次的值。
  • 在扩展里持有大 body 缓冲:body 是流,不应作为扩展长期持有。

追问

  • 会话数据为什么不放 Extension?答:会话需要跨请求持久化,由会话中间件存后端存储,扩展只带本次会话句柄。
  • 嵌套 Service 会保留扩展吗?答:随请求传递则保留,服务重建请求则不保证;挂载结构需实测确认。

04.4.3.2-020 哪些场景下 Extension 会丢失,如何排查?

一句话结论

扩展在请求被重建、服务降级到独立 Service、或层挂载位置错误时可能丢失;排查方式是沿链路打印扩展类型是否存在,确认写入层在读取层上游。

概念解释

扩展依赖请求对象沿层链传递。常见丢失场景:写入层挂在路由内层,读取层在外层;外部 Service 重建请求不带扩展;错误处理路径绕过主链路。排查时从写入点到读取点逐层确认请求对象未被替换。中间件短路响应不影响已写入扩展,但下游不再读取。类型不匹配也表现为取不到值,需核对类型定义。

原理流程

  1. 确认写入层的挂载位置在读取方上游。
  2. 沿链路检查请求是否被重建或外包独立服务。
  3. 核对读取类型与插入类型完全一致。
  4. 在中间件打印扩展存在性定位丢失层级。

代码或图示

use axum::{Extension, http::Request, middleware::{self, Next}, response::Response, Router};

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

async fn check<B>(req: Request<B>, next: Next<B>) -> Response {
    let has = req.extensions().get::<Ctx>().is_some();
    println!("extension present: {has}");
    next.run(req).await
}

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .layer(Extension(Ctx("x".into())))
    .route_layer(middleware::from_fn(check));

常见误区

  • 读取层挂在写入层外层:请求还没经过写入层。
  • 类型定义重复(两个同名结构体):TypeId 不同,读取视为缺失。

追问

  • 如何在中间件直接检查扩展?答:req.extensions().get::<T>() 按类型查询,返回 Option<&T>。
  • 外部 Service 拿不到扩展怎么办?答:在调用外部服务前把需要的值写入请求头或显式传入,不要依赖扩展透传。

04.4.3.2-021 共享可变计数器在 AppState 中如何实现,并发安全如何保证?

一句话结论

计数器用 Arc<AtomicU64> 放入 State,自增用原子操作;无锁、跨线程安全,读多写少的统计类字段优先选原子类型而非互斥锁。

概念解释

请求计数、在线数、指标累加属于典型共享可变状态。原子类型提供无锁的整数操作,内存序选择 Relaxed 即可满足计数场景。Arc 让句柄跨线程共享,AppState 克隆时只复制指针。需要复杂集合或复合状态时再用锁。原子操作不会持锁阻塞,适合在 handler 高频调用。

原理流程

  1. 状态字段定义 Arc<AtomicU64>。
  2. 启动期初始化为 0。
  3. handler 提取 State,调用 fetch_add/load。
  4. 各线程原子更新,无需互斥临界区。

代码或图示

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

#[derive(Clone)]
struct AppState { hits: Arc<AtomicU64> }

async fn ping(State(s): State<AppState>) -> String {
    let n = s.hits.fetch_add(1, Ordering::Relaxed) + 1;
    n.to_string()
}

let app = Router::new().route("/ping", get(ping))
    .with_state(AppState { hits: Arc::new(AtomicU64::new(0)) });

常见误区

  • 用普通 u64 放 State:多线程数据竞争,编译与运行都不安全。
  • 计数场景上重锁:原子类型足够,锁增加争用成本。

追问

  • 内存序怎么选?答:单纯计数用 Relaxed,需要顺序约束再提升到 Acquire/Release;内存序细节见并发主题。
  • 计数器需要持久化吗?答:内存原子计数重启即清零,持久指标另接监控或存储。

04.4.3.2-022 状态中的异步锁与同步锁在 axum handler 里如何选择?

一句话结论

临界区内不 await 用 std::sync::Mutex/RwLock;持有锁期间需要 await 或可能长等待,用 tokio::sync::Mutex/RwLock;两者都不能在异步运行时造成长时间阻塞。

概念解释

同步锁守卫不能跨 await 持有,否则编译或运行出问题;异步锁内部用等待机制,守卫可跨 await 但开销更高。State 中的共享集合按操作形态选择:纯内存计算用同步锁,等待数据库/外部资源的复合操作放异步锁或先取数据再释放锁。锁粒度尽量小,避免在锁内做 IO。锁中毒与死锁规则在并发主题展开。

原理流程

  1. 分析临界区是否包含 await。
  2. 无 await 选同步锁,有 await 选异步锁。
  3. handler 提取 State,取锁完成短操作后释放。
  4. 复合操作先在锁内取数据,解锁后再异步等待。

代码或图示

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

#[derive(Clone)]
struct AppState { cache: Arc<RwLock<Vec<String>>> }

async fn list(State(s): State<AppState>) -> String {
    let snapshot = s.cache.read().unwrap().clone();
    // 解锁后再做后续异步处理
    format!("len={}", snapshot.len())
}

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

常见误区

  • 持同步锁守卫穿越 .await:守卫不 Send,编译报错。
  • 锁内调用远程接口:阻塞其它请求,临界区应只做内存操作。

追问

  • tokio::sync::RwLock 写饥饿如何?答:其等待策略以 tokio 文档为准;高争用场景评估拆分锁或无锁结构。
  • 状态里的锁需要包 Arc 吗?答:需要跨线程共享时外包 Arc,AppState 克隆句柄。

04.4.3.2-023 本地缓存放入 State 时要考虑哪些容量与失效问题?

一句话结论

本地缓存以 Arc<Mutex/RwLock<HashMap>> 或专门缓存结构放 State,必须设容量上限、过期策略与淘汰规则;无界缓存会随请求增长耗尽内存。

概念解释

进程内缓存减少重复计算或外部查询,但需要治理:键空间控制、条目过期、最大容量、淘汰策略。缓存命中一致性按业务容忍度设计。多实例部署时本地缓存不共享,跨实例一致需求要走 Redis 等集中存储。缓存键避免放入用户敏感数据。缓存更新与失效时机在写入路径同步处理。

原理流程

  1. 状态内定义缓存结构与容量上限。
  2. 读取先查缓存,未命中回源并写入。
  3. 写入路径更新或失效缓存条目。
  4. 按过期/容量策略淘汰旧条目。

代码或图示

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

#[derive(Clone)]
struct AppState {
    cache: Arc<RwLock<HashMap<String, String>>>,
}

async fn get(State(s): State<AppState>, axum::extract::Path(key): axum::extract::Path<String>) -> String {
    let guard = s.cache.read().unwrap();
    guard.get(&key).cloned().unwrap_or_else(|| "miss".into())
}

let app = Router::new().route("/cache/{key}", get(get));

常见误区

  • 只写不淘汰:内存随键数持续增长。
  • 多实例假设本地缓存全局一致:各进程缓存独立。

追问

  • 缓存击穿与穿透怎么处理?答:热点键加锁重建,空结果短缓存;具体策略在缓存主题展开。
  • 缓存值需要跨线程可变吗?答:值类型线程安全或整体加锁,避免内部竞争。

04.4.3.2-024 如何在 State 中做依赖注入与仓库抽象,便于替换实现?

一句话结论

State 持有仓库 trait 对象或泛型 trait 句柄,业务 handler 依赖 trait 接口;生产绑定真实实现,测试注入内存替身,实现依赖反转。

概念解释

直接在 handler 调用具体数据库类型会绑死实现。抽象出仓库 trait(如 UserRepo),State 持有 Arc<dyn UserRepo> 或泛型参数。handler 只面向 trait 方法编程。测试时构造假实现注入 State。trait 方法返回异步 Future 时注意 Send 约束。抽象层级按业务复杂度控制,避免过度设计。

原理流程

  1. 定义业务仓库 trait 与方法签名。
  2. 生产实现对接真实数据源。
  3. State 持有 trait 对象句柄。
  4. handler 调用 trait 方法,测试替换替身实现。

代码或图示

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

trait UserRepo: Send + Sync {
    fn name(&self, id: u64) -> String;
}

struct RealRepo;
impl UserRepo for RealRepo {
    fn name(&self, _id: u64) -> String { "real".into() }
}

#[derive(Clone)]
struct AppState { repo: Arc<dyn UserRepo> }

async fn profile(State(s): State<AppState>) -> String {
    s.repo.name(1)
}

let app = Router::new().route("/profile", get(profile))
    .with_state(AppState { repo: Arc::new(RealRepo) });

常见误区

  • trait 方法返回的 Future 不 Send:无法跨线程调度,需用 async trait 约束处理。
  • 抽象过细导致接口碎片化:先按业务边界抽仓库,再细化。

追问

  • trait 对象与泛型依赖怎么选?答:需要运行期替换用 dyn,编译期单态化用泛型;测试替换场景常用 trait 对象。
  • State 持有 Arc<dyn Trait> 需要 trait 标记什么?答:通常要求 Send + Sync,以实际编译约束为准。

04.4.3.2-025 配置热更新在 State 层面能做到什么程度,边界在哪里?

一句话结论

只读配置启动期固化在 State;需要热更新时把可变配置放进 Arc<RwLock/Atomic> 结构,后台任务更新句柄内值,handler 读取最新值;连接池、客户端等重资源一般不做无热重启的在线替换。

概念解释

普通配置字段不可变,启动后固定。热更新场景把配置包成线程安全可更新结构,配置后台任务重新加载后写入;handler 读取时取当前快照。不是所有资源都适合热替换:连接池大小、HTTP 客户端连接策略重建成本高,通常重启生效。热更新要考虑部分更新失败、版本一致性与审计记录。配置变更不应破坏进行中的请求。

原理流程

  1. 可变配置字段用 Arc<RwLock<Config>> 或原子包装。
  2. 后台监听配置变更,校验后写入新值。
  3. handler 读取时取快照使用。
  4. 不可热替换资源标注为重启生效。

代码或图示

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

#[derive(Clone)]
struct Config { max_items: u32 }

#[derive(Clone)]
struct AppState { config: Arc<RwLock<Config>> }

async fn limit(State(s): State<AppState>) -> String {
    s.config.read().unwrap().max_items.to_string()
}

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

常见误区

  • 期望所有资源免重启刷新:连接池、TLS 配置等重建成本高,需明确边界。
  • 配置更新不加校验:非法值进入运行期导致请求错误。

追问

  • 热更新期间进行中的请求用旧值还是新值?答:请求开始时取快照,本次请求沿用快照,新请求再取新值,避免中途切换。
  • 配置变更如何审计?答:后台更新路径记录版本与变更来源,敏感配置变更走审批与日志。

04.4.3.2-026 tower 与 tower-http 分别承担什么角色?

一句话结论

tower 提供 Service、Layer、ServiceBuilder 等通用异步服务抽象;tower-http 在其上实现 HTTP 场景的现成层(日志、CORS、压缩、超时、限流、静态服务等),axum 路由直接挂载这些层。

概念解释

tower 是与协议无关的中间件抽象:Service 处理请求返回响应,Layer 装饰 Service。tower-http 把 HTTP 领域能力做成可复用层,axum 基于 hyper 与 tower 构建,因此 Router 可直接挂 tower-http 层。工程上业务横切逻辑优先选现成 tower-http 层,特殊需求再自定义 Layer。依赖引入时按需开启 feature,避免编译无关组件。

原理流程

  1. 引入 tower 获取 Service/Layer 抽象与 ServiceExt。
  2. 引入 tower-http 并开启所需层的 feature。
  3. 层挂到 Router,包裹内层 Service。
  4. 请求穿过层链到达路由 handler。

代码或图示

[dependencies]
axum = "0.8"
tower = { version = "0.5", features = ["util"] }
tower-http = { version = "0.6", features = ["trace", "cors", "compression", "timeout"] }

常见误区

  • 把 tower-http 当成 axum 内置模块:层来自独立 crate,需在 Cargo.toml 声明。
  • 一次性开启全部 feature:编译体积增大,按实际使用选择。

追问

  • 版本号为什么不写死?答:依赖兼容范围以 workspace 锁定为准,版本表述以 docs.rs 当前版本为准。
  • tower 与 hyper 是什么关系?答:hyper 是 HTTP 服务实现,tower 是服务中间件抽象,axum 把二者粘合;协议层细节在 04.4.7 主题展开。

04.4.3.2-027 Layer trait 与 Service trait 是什么关系?

一句话结论

Service 是「处理请求返回响应」的服务单元,Layer 是「包裹 Service 生成新 Service」的装饰器;层不直接处理业务,只在前后增强内层服务。

概念解释

Service 核心是 poll_ready 与 call;Layer 的 layer(inner) 接收内层 Service,返回包裹后的新 Service。多个层按序包裹形成链:外层层先看到请求,逐层进入内层。axum 的 Router::layer 接受实现 Layer 的类型。理解这层关系后,自定义层就是实现包裹逻辑,而不是重写路由分发。

原理流程

  1. 内层 Service 实现请求处理。
  2. 外层 Layer 调用 layer(inner) 持有内层句柄。
  3. 包裹后的 Service 在 call 中先做前置处理,再调用内层 call。
  4. 响应沿链回传,外层可后置加工。

代码或图示

use tower::Layer;

# struct MyLayer;
# impl<S> Layer<S> for MyLayer {
#     type Service = MyService<S>;
#     fn layer(&self, inner: S) -> Self::Service { MyService { inner } }
# }
# struct MyService<S> { inner: S }

常见误区

  • 把 Layer 当成 handler:层不绑定路由模板,包裹的是服务链。
  • 自定义层忘记保留内层调用:链路被截断,下游不执行。

追问

  • Service 的错误类型有什么要求?答:接入 axum 链通常要求错误可转响应或为 Infallible,具体以挂载点约束为准。
  • 层能改变请求类型吗?答:可以在包裹层内转换请求/响应类型,只要内外层类型契约一致。

04.4.3.2-028 ServiceBuilder 如何链式组装多个层?

一句话结论

ServiceBuilder 按调用顺序把多个层组装成一条链,layer 方法依次包裹内层;链式写法比逐个 Router::layer 更适合集中配置横切层。

概念解释

ServiceBuilder 来自 tower,提供 layer、layer_fn 等方法组织层序列。builder 构造出的整体层可一次挂到 Router。顺序规则与直接链式一致:先加入的层更靠外。集中放置日志、追踪、CORS、压缩等基础层时,builder 可读性更好。业务路由专属层仍可用 route_layer 单独挂载。

原理流程

  1. ServiceBuilder::new() 起建链。
  2. 依次调用 layer(..) 加入各层。
  3. builder 生成组合 Layer。
  4. Router 调用 layer(builder) 整体包裹。

代码或图示

use axum::{routing::get, Router};
use tower::ServiceBuilder;
use tower_http::{trace::TraceLayer, cors::CorsLayer, compression::CompressionLayer};

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

常见误区

  • 把 builder 顺序与执行顺序对应反:先加入的层在外层,先接触请求。
  • 在 builder 中混入需要路由状态的层:状态兼容问题需单独处理。

追问

  • ServiceBuilder 与多次 Router::layer 等价吗?答:层组装结果等价,builder 只是集中写法;顺序规则相同。
  • builder 支持条件加层吗?答:可按条件在构造期选择是否加入层,运行期条件判断需自定义层。

04.4.3.2-029 TraceLayer 如何记录请求生命周期日志与追踪事件?

一句话结论

TraceLayer 在请求进入、响应返回、失败等阶段生成 tracing 事件,记录方法、路径、状态码、耗时等字段;接入 tracing 订阅后输出结构化日志。

概念解释

TraceLayer 是 tower-http 提供的观测层,基于 tracing crate。它可配置事件级别、响应头记录、延迟统计等。请求进入时建立 span,响应结束记录状态码与耗时。与业务 handler 内 tracing::info! 配合,形成从接入到业务的完整链路。配置项随版本变化,具体方法名以 docs.rs/tower-http 当前版本为准。

原理流程

  1. 层包裹内层服务,请求进入时创建 tracing span。
  2. 前置记录方法、路径等字段。
  3. 调用内层处理,等待响应或错误。
  4. 后置记录状态码、耗时,关闭 span。

代码或图示

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

let app = Router::new()
    .route("/", get(|| async { "ok" }))
    .layer(TraceLayer::new_for_http()
        .make_span_with(|req: &axum::http::Request<axum::body::Body>| {
            tracing::span!(Level::INFO, "request", method = ?req.method(), uri = ?req.uri())
        }));

常见误区

  • 只挂层不配置 tracing 订阅:事件产生但没有输出。
  • 在日志里记录完整请求头:敏感信息泄露风险,按需选择记录字段。

追问

  • TraceLayer 记录响应 body 吗?答:默认不记录 body 内容,记录元数据与状态;body 采样需自定义策略,以当前版本为准。
  • 追踪 ID 如何进入 span?答:由 SetRequestIdLayer 生成并写入扩展/头,TraceLayer 读取后挂到 span 字段。

04.4.3.2-030 CorsLayer 如何配置允许来源、方法、头与凭证?

一句话结论

CorsLayer 通过 allow_origin、allow_methods、allow_headers、allow_credentials 等方法配置跨域策略;携带凭证时不能使用通配来源,需按规范收敛。

概念解释

跨域请求分简单请求与预检请求:层校验 Origin 与请求方法/头,在响应中写入 CORS 头。来源可配置精确域名或匹配规则,方法与头列出允许集合。Any 表示放开,仅适合内部工具或演示。凭证(Cookie、Authorization)场景下浏览器规范禁止通配来源与通配头,配置需显式列出。预检由层直接响应,不进入业务 handler。

原理流程

  1. 请求带 Origin 到达 CORS 层。
  2. 层校验来源、方法、头是否在允许集合。
  3. 预检请求直接返回带 CORS 头的响应。
  4. 实际请求响应附加允许跨域的 CORS 头。

代码或图示

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

let app = Router::new()
    .route("/api", axum::routing::get(|| async { "ok" }))
    .layer(CorsLayer::new()
        .allow_origin(Origin::exact("https://example.com".parse().unwrap()))
        .allow_methods(Any)
        .allow_headers(Any)
        .allow_credentials(true));

常见误区

  • allow_credentials(true) 同时用 Any 来源:浏览器规范不允许,预检或实际请求被拦。
  • 只配实际响应头忽略预检:OPTIONS 预检未通过,实际请求不会发出。

追问

  • 多来源白名单怎么配?答:allow_origin 传入来源集合或匹配器,具体形式以 tower-http 当前版本 API 为准。
  • CORS 层应放在外层还是内层?答:预检需要在业务路由前被处理,通常挂全局外层。

04.4.3.2-031 CompressionLayer 如何根据 Accept-Encoding 压缩响应?

一句话结论

CompressionLayer 检查请求 Accept-Encoding,按支持的编码(gzip、br、deflate 等)压缩响应 body;压缩策略与编码集合通过层配置选择。

概念解释

响应压缩减少传输体积,但增加 CPU 开销。层根据客户端声明的编码与层启用的编码协商,对可压缩 body 压缩并设置 Content-Encoding。已压缩内容(图片、压缩包)不应重复压缩。流式响应与压缩可能冲突,需要单独评估。feature 按需开启,不同编码对应不同依赖。

原理流程

  1. 读取请求 Accept-Encoding。
  2. 与层启用的编码集合协商出目标编码。
  3. 调用内层得到响应 body。
  4. 按编码压缩 body 并写入 Content-Encoding 头。

代码或图示

use axum::{routing::get, Router};
use tower_http::compression::CompressionLayer;

let app = Router::new()
    .route("/", get(|| async { "plain text" }))
    .layer(CompressionLayer::new());

常见误区

  • 对所有响应无条件压缩:二进制已压缩格式浪费 CPU。
  • 压缩与 SSE 流式响应叠加:缓冲行为可能破坏流式推送,需按场景关闭。

追问

  • 支持哪些压缩编码?答:gzip、deflate、br 等,具体可用编码与 feature 名以 docs.rs/tower-http 当前版本为准。
  • 压缩级别可配吗?答:层提供策略配置项,级别与默认值以当前版本文档为准。

04.4.3.2-032 TimeoutLayer 如何给请求处理加超时?

一句话结论

TimeoutLayer 给内层服务的响应 Future 加超时限制,超时后返回超时错误响应;它保护慢请求不长期占用 worker,但与流式响应需要配合评估。

概念解释

超时层在调用内层后等待响应 Future,超过设定时长未完成则取消等待并返回超时响应。它覆盖 handler 执行与下游调用等待。超时不终止正在运行的内部任务,只放弃等待;需要真正取消任务要在业务层处理。全局超时与接口级超时可分别挂载。超时值按接口 SLA 设置,避免过短误杀慢接口。

原理流程

  1. 请求进入超时层,记录起始时间。
  2. 调用内层 call 取得响应 Future。
  3. 并发等待 Future 与超时计时器。
  4. 超时先完成则返回超时响应,否则返回内层响应。

代码或图示

use axum::{routing::get, Router};
use tower_http::timeout::TimeoutLayer;
use std::time::Duration;

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

常见误区

  • 以为超时会中断内部数据库查询:层只放弃等待,任务是否取消取决于内部实现。
  • 流式长连接接口套全局超时:连接被提前切断,需对该路由放宽或关闭。

追问

  • 超时返回什么状态码?答:默认错误响应类型可配置映射,具体状态码以当前版本与自定义错误处理为准。
  • 接口级超时怎么配?答:用 route_layer 只挂目标路由,全局超时挂 layer。

04.4.3.2-033 RequestBodyLimitLayer 如何限制请求体大小?

一句话结论

RequestBodyLimitLayer 在进入路由前限制请求 body 字节数,超限拒绝;与 axum 提取器的默认 body 限制叠加,实际阈值取更严格者。

概念解释

body 限制防止无界上传打满内存。层限制在请求进入服务链时生效,提取器限制在消费 body 时生效。两层阈值不一致时,先到的限制先生效。上传大文件接口需要单独放宽层限制,并配合 Multipart 流式处理。限制超限返回 413 类响应,具体映射以当前版本为准。

原理流程

  1. 请求进入 body 限制层。
  2. 读取/统计 body 字节,超过阈值拒绝。
  3. 未超限 body 透传给内层路由。
  4. 提取器消费时再过默认限制。

代码或图示

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

let app = Router::new()
    .route("/upload", post(|| async { "ok" }))
    .layer(RequestBodyLimitLayer::new(5_000_000));

常见误区

  • 只在提取器放宽限制,层仍按小阈值拦截:上传接口 413。
  • 大文件接口完全去掉限制:缺少防护,应流式处理并控制单字段大小。

追问

  • 该层与 DefaultBodyLimit 区别?答:层是链路级统一拦截,提取器限制是消费侧默认值;两者分工见路由与提取器主题。
  • 限制超限状态码是多少?答:通常 413 Payload Too Large,具体映射以 docs.rs/tower-http 当前版本为准。

04.4.3.2-034 SetRequestIdLayer 如何为每个请求生成并透传请求 ID?

一句话结论

SetRequestIdLayer 为每个请求生成唯一 ID,写入响应头与请求扩展;下游日志、错误排查按 ID 串联一次请求的全部记录。

概念解释

请求 ID 用于跨层、跨服务追踪。层生成 ID(可配置生成策略),写入请求扩展供业务读取,同时写入响应头返回客户端。TraceLayer 可把 ID 挂到 span 字段。ID 生成避免使用可预测序列,防日志伪造。响应头名称按团队约定配置。注意不要把内部请求 ID 暴露给不可信客户端而不加校验。

原理流程

  1. 请求进入层,按策略生成请求 ID。
  2. ID 写入请求扩展与响应头。
  3. 下游中间件与 handler 从扩展读取 ID。
  4. 日志与错误响应携带同一 ID。

代码或图示

use axum::{routing::get, Router};
use tower_http::request_id::{SetRequestIdLayer, MakeRequestId, PropagateRequestIdLayer};
use http::HeaderName;

#[derive(Clone)]
struct UuidId;
// MakeRequestId 实现按 tower-http 当前版本 trait 约定编写,示例略

let app = Router::new()
    .route("/", get(|| async { "ok" }))
    .layer(SetRequestIdLayer::new(HeaderName::from_static("x-request-id")));

常见误区

  • 只写响应头不写入扩展:下游业务取不到 ID。
  • 请求 ID 用自增整数:可预测且多实例不一致,应用随机或 UUID 方案。

追问

  • 如何保留客户端传入的 ID?答:配合传播层读取已有头,无值时再生成;具体层组合以 tower-http 文档为准。
  • ID 如何进入 tracing span?答:TraceLayer 配置从扩展或头读取 ID 字段,挂到当前 span。

04.4.3.2-035 NormalizePathLayer 如何归一化路径?

一句话结论

NormalizePathLayer 在路由匹配前规整路径,例如去除或补全尾斜杠、合并多余斜杠;避免 /foo 与 /foo/ 被当成两条路径。

概念解释

路径尾斜杠与重复斜杠常导致意外 404。归一化层在请求进入匹配树前改写路径。策略分去尾斜杠与补尾斜杠等模式,按路由注册风格选择。层应挂在全局外层,确保匹配前完成归一化。注意归一化会改变 Uri 内容,原始路径读取需用 OriginalUri。

原理流程

  1. 请求进入归一化层。
  2. 按策略规范化路径段。
  3. 改写请求 URI 后调用内层。
  4. 匹配树在规整路径上查找模板。

代码或图示

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());

常见误区

  • 归一化层挂在路由内层:匹配已发生,尾斜杠问题未解决。
  • 依赖 Uri 取原始路径:归一化后 Uri 被改写,原始值用 OriginalUri。

追问

  • 归一化策略有哪些模式?答:去尾斜杠、补尾斜杠等,具体枚举与方法名以 docs.rs/tower-http 当前版本为准。
  • 多余斜杠会被合并吗?答:归一化行为覆盖范围以当前版本实现为准,建议用用例验证。

04.4.3.2-036 CatchPanicLayer 如何把 panic 转成错误响应?

一句话结论

CatchPanicLayer 捕获内层服务执行中发生的 panic,转换为 500 类错误响应,避免 panic 直接中断连接或 Worker;它不能替代业务错误处理。

概念解释

handler 或下层出现 panic 时,默认行为可能导致任务失败。panic 捕获层在服务链包裹内层,catch 住 panic 后生成错误响应。它是最后一道防线:预期业务失败应返回错误类型,不该靠 panic 表达。捕获层无法恢复被破坏的内部状态,panic 后的资源一致性仍需业务保证。层配置可自定义错误响应内容。

原理流程

  1. 层包裹内层 Service。
  2. 内层执行中发生 panic。
  3. 层捕获 panic,按配置生成错误响应。
  4. 响应回传,连接不被 panic 直接打断。

代码或图示

use axum::{routing::get, Router};
use tower_http::catch_panic::CatchPanicLayer;

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

常见误区

  • 用 panic 处理可预期业务错误:应返回 Result 与错误类型,panic 层只兜底不可恢复异常。
  • 以为捕获 panic 后内部状态完好:panic 中途可能破坏不变量,需按场景评估。

追问

  • CatchPanicLayer 需要哪个 feature?答:tower-http 的 catch-panic 相关 feature,具体名称以当前版本文档为准。
  • panic 信息会返回给客户端吗?答:默认不应暴露内部信息,错误响应需脱敏,具体配置以层实现为准。

04.4.3.2-037 layer 与 route_layer 分别包裹哪些节点,作用范围如何区分?

一句话结论

layer 包裹整个 Router(含 fallback),route_layer 只包裹已注册路由节点,fallback 不经过路由层;子路由可再挂自己的层,形成嵌套作用域。

概念解释

全局层对所有请求生效,包括兜底响应;路由层只作用于命中具体模板的请求。健康检查、静态兜底若不想被鉴权层拦截,应把鉴权放 route_layer。子路由内部 layer 只影响该子树。排查「某层没生效」先确认挂载层级:全局、路由级还是子树级。

原理流程

  1. layer(L) 把 L 套在 Router 整体外。
  2. route_layer(L) 把 L 套在每个路由节点外。
  3. 请求先过全局层,匹配后再过路由层。
  4. fallback 路径只经过全局层。

代码或图示

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

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

常见误区

  • 把鉴权放全局层:fallback 与健康检查也被拦截。
  • 以为 route_layer 覆盖兜底服务:兜底节点不经过路由层。

追问

  • MethodRouter 上也有这两个方法吗?答:有,作用于该路径的方法分发器,具体以当前版本 API 为准。
  • 子路由 route_layer 会继承父层吗?答:父全局层仍在外层包裹,子路由层在内部叠加。

04.4.3.2-038 多个层的执行顺序如何确定,为什么说外层先入后出?

一句话结论

先挂载的层更靠外:请求先穿过外层再到内层,响应沿内层向外层回传;后挂的层更靠近 handler。顺序错误会导致鉴权、压缩、日志等行为不符合预期。

概念解释

层链类似洋葱模型:请求从外层向内层逐层进入,响应从内层向外层逐层返回。Router::layer(a).layer(b) 中 a 更外、b 更内,请求先经 a 再经 b。配置原则:日志/追踪在最外层观察完整链路,CORS 靠前处理预检,鉴权在业务前,压缩靠近响应侧。顺序问题是中间件排错高频点,画图理清包裹方向。

原理流程

  1. 按挂载顺序形成外层到内层的层序列。
  2. 请求依次经过外层到内层的前置逻辑。
  3. handler 产出响应。
  4. 响应依次经过内层到外层的后置逻辑。

代码或图示

请求 → Layer A(外) → Layer B → handler → Layer B(后) → Layer A(后) → 响应

常见误区

  • 把挂载先后当成内层到外层:方向反了会误判谁先读到请求。
  • 压缩层放在鉴权之前:未鉴权响应也被压缩,虽不致命但语义混乱。

追问

  • 如何用代码验证顺序?答:在各层打印进入与返回日志,观察请求/响应两侧的先后次序。
  • ServiceBuilder 顺序规则相同吗?答:相同,先加入 builder 的层更靠外。

04.4.3.2-039 全局层、路由层、子路由层的可见范围如何叠加?

一句话结论

全局层覆盖根 Router 全部请求;路由层只覆盖指定路由;子路由层只覆盖子树;叠加时外层先于内层,子树请求经过父全局层、父路由层、子树层。

概念解释

层作用域分三层:根全局、单路由、子路由。鉴权按模块隔离时挂子路由层;跨切面观测挂全局;个别接口特殊处理挂路由层。叠加顺序为外层到内层:根全局 → 父路由层 → 子树层 → handler。子树可自带层,父层不被子层替换。设计中间件覆盖范围时,先列每个关注点的作用域,再选挂载点。

原理流程

  1. 根 Router 挂全局层。
  2. 指定路由挂路由层。
  3. 子 Router 挂子树层。
  4. 命中子树路由的请求依次穿过各层到达 handler。

代码或图示

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

let sub = Router::new()
    .route("/inner", get(|| async { "inner" }))
    .route_layer(axum::middleware::from_fn(|req, next| async { next.run(req).await }));

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

常见误区

  • 子树层以为能覆盖父路由:作用域仅限子树前缀内。
  • 全局层与子树层重复实现同一逻辑:重复计数或重复改写响应。

追问

  • 子树层能访问父层写入的扩展吗?答:扩展随请求向下传递,父层写入的可见;子层写入的外层读不到。
  • 想让某层只排除个别路由怎么做?答:用路由层挂到需要的路由,而不是全局层再排除。

04.4.3.2-040 全局层会包裹 fallback 与 nest_service 的外部服务吗?

一句话结论

全局 layer 包裹整个 Router 服务,fallback 与挂载的外部服务都经过它;route_layer 不包裹兜底与外部挂载节点。

概念解释

全局层在服务链最外层,无论请求命中路由、兜底还是外部服务节点,都先经过全局层。路由层只挂在 axum 识别的路由节点上。静态文件服务作为 fallback_service 或 nest_service 挂载时,全局层仍在外层生效。需要对兜底响应做日志或压缩时,挂全局层;只想保护业务路由时用路由层。

原理流程

  1. 全局层包裹 Router 整体 Service。
  2. 请求无论命中哪类节点,先过全局层。
  3. 路由节点额外经过路由层。
  4. 兜底与外部服务不经过路由层。

代码或图示

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

let app = Router::new()
    .route("/api", axum::routing::get(|| async { "ok" }))
    .fallback_service(ServeDir::new("dist"))
    .layer(TraceLayer::new_for_http()); // 含兜底静态服务

常见误区

  • 以为外部服务完全绕过所有层:它绕过路由层,但仍在全局层包裹内。
  • 在路由层里记录兜底请求:记录不到,需改全局层。

追问

  • 外部服务内部还能再套层吗?答:可以在构造外部服务时自行包裹层,与 axum 全局层叠加。
  • 全局层改写响应会影响静态资源吗?答:会,全局后置逻辑对兜底响应同样生效。

04.4.3.2-041 如何实现自定义 Layer,最小步骤是什么?

一句话结论

定义层结构体实现 tower::Layer<S>,layer 方法构造持有内层的服务结构体;服务结构体实现 Service,在 call 中前置处理、调用内层、后置加工响应。

概念解释

现成层不满足需求时自定义 Layer:层本身无状态或持有配置,服务实例在 layer 时绑定内层。服务结构体实现 poll_ready 透传内层,call 包裹请求处理。自定义层需满足服务链的 Clone + Send + 'static 约束。简单前后置逻辑也可用 middleware::from_fn,不必从零实现 Layer trait。

原理流程

  1. 定义层配置结构体。
  2. 实现 Layer<S>,产出包裹服务类型。
  3. 包裹服务实现 Service,保存内层句柄。
  4. call 中处理请求、调用内层、加工响应。

代码或图示

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

#[derive(Clone)]
struct LogLayer;

impl<S> Layer<S> for LogLayer {
    type Service = LogService<S>;
    fn layer(&self, inner: S) -> Self::Service {
        LogService { inner }
    }
}

#[derive(Clone)]
struct LogService<S> { inner: S }

impl<S> Service<Request<Body>> for LogService<S>
where
    S: Service<Request<Body>, Response = Response<Body>> + Send + Clone + 'static,
    S::Future: Send,
{
    type Response = S::Response;
    type Error = S::Error;
    type Future = std::pin::Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>> + Send>>;

    fn poll_ready(&mut self, cx: &mut std::task::Context<'_>) -> std::task::Poll<Result<(), Self::Error>> {
        self.inner.poll_ready(cx)
    }

    fn call(&mut self, req: Request<Body>) -> Self::Future {
        let mut inner = self.inner.clone();
        Box::pin(async move { inner.call(req).await })
    }
}

常见误区

  • 层结构体与服务结构体混淆:Layer 负责构造,Service 负责处理。
  • 包裹服务不 Clone:MakeService 克隆服务时约束不满足。

追问

  • 什么时候该用 from_fn 而不是自定义 Layer?答:只做请求/响应前后置逻辑用 from_fn 更轻量;需要控制 Service 生命周期或复杂就绪逻辑再实现 Layer。
  • 自定义层如何读 State?答:通过 from_fn_with_state 形式或在层构造时注入句柄。

04.4.3.2-042 如何写一个自定义 Service 包裹请求与响应做加工?

一句话结论

自定义服务结构体持有内层 Service,call 中读取/改写请求后调用内层,再对响应做后置处理;poll_ready 通常透传内层就绪状态。

概念解释

Service 包裹是层的内层形态:前置可校验请求、写扩展、改头;后置可改状态码、补头、包装 body。服务需可克隆,Future 需 Send。直接操作 Request/Response 类型,比 from_fn 更底层。多数业务中间件用 from_fn 即可,自定义 Service 用于需要独立服务类型或集成第三方服务的场景。

原理流程

  1. 服务结构体保存内层 Service 句柄。
  2. poll_ready 转发内层就绪状态。
  3. call 前置加工请求,调用内层 call。
  4. await 响应后后置加工并返回。

代码或图示

use tower::Service;
use axum::{http::Request, response::Response, body::Body, http::HeaderMap};

#[derive(Clone)]
struct HeaderService<S> { inner: S, headers: HeaderMap }

impl<S> Service<Request<Body>> for HeaderService<S>
where S: Service<Request<Body>, Response = Response<Body>> + Send + Clone + 'static,
      S::Future: Send,
{
    type Response = S::Response;
    type Error = S::Error;
    type Future = std::pin::Pin<Box<dyn std::future::Future<Output = Result<Self::Response, Self::Error>> + Send>>;

    fn poll_ready(&mut self, cx: &mut std::task::Context<'_>) -> std::task::Poll<Result<(), Self::Error>> {
        self.inner.poll_ready(cx)
    }

    fn call(&mut self, mut req: Request<Body>) -> Self::Future {
        let mut inner = self.inner.clone();
        let headers = self.headers.clone();
        Box::pin(async move {
            let mut resp = inner.call(req).await?;
            *resp.headers_mut() = headers;
            Ok(resp)
        })
    }
}

常见误区

  • 服务 Future 不 Send:无法跨线程调度。
  • 忘记调用内层:下游路由与 handler 不执行。

追问

  • 自定义 Service 如何读 State?答:构造服务时由层注入状态句柄,Service 结构体持有克隆值。
  • 服务克隆成本如何控制?答:内层句柄与状态用 Arc/可廉价克隆类型,避免深拷贝。

04.4.3.2-043 中间件中读取应用 State 用哪种写法?

一句话结论

需要在中间件访问 State 时用 middleware::from_fn_with_state,把 State<S> 作为首个参数;普通 from_fn 不注入状态,只能读请求与扩展。

概念解释

鉴权、限流中间件常需要读配置、缓存或用户存储。from_fn_with_state 与 handler 一样支持 State<S> 提取,参数顺序为 State、请求、Next。注入的状态与路由 with_state 保持同类型。若状态已由前置层写入扩展,普通 from_fn 也能从扩展读取,但应用级资源仍走 State。中间件取状态应保持轻量,重业务下沉服务层。

原理流程

  1. 中间件函数首参声明 State<S>。
  2. from_fn_with_state(state, func) 挂载层并传入状态。
  3. 前置逻辑读 State 字段做校验或配置判断。
  4. 调用 next.run(req) 进入内层。

代码或图示

use axum::{
    extract::State, http::Request, middleware::{self, Next}, response::Response, Router,
};

#[derive(Clone)]
struct AppState { limit: u32 }

async fn quota<B>(
    State(s): State<AppState>,
    req: Request<B>,
    next: Next<B>,
) -> Response {
    if s.limit == 0 {
        return (axum::http::StatusCode::TOO_MANY_REQUESTS, "limit 0").into_response();
    }
    next.run(req).await
}

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .route_layer(middleware::from_fn_with_state(AppState { limit: 10 }, quota));

常见误区

  • 用 from_fn 闭包捕获 State 变量:生命周期与克隆约束不满足,应使用带状态形式。
  • 中间件内做重数据库查询:拖慢全部请求,应只做轻量判断。

追问

  • from_fn_with_state 的状态必须 Clone 吗?答:与路由 State 约束一致,需满足克隆与线程安全要求。
  • 中间件能修改 State 字段吗?答:可访问内部可变字段,线程安全规则与 handler 相同。

04.4.3.2-044 中间件如何把派生上下文插入请求扩展供 handler 读取?

一句话结论

中间件解析请求后构造类型化上下文,写入 req.extensions_mut(),下游 handler 用 Extension<T> 读取;写入必须在调用 next.run 之前完成。

概念解释

认证中间件解析令牌得到用户主体,租户中间件解析头得到租户,这些请求级结果写入扩展供下游复用,避免每个 handler 重复解析。上下文聚合为结构体类型,按类型存入扩展。写入后请求继续向下传递;后置响应阶段扩展仍可读,但不再需要向下游传递。短路响应时上下文无需写入。

原理流程

  1. 中间件解析请求头、Cookie 或令牌。
  2. 构造上下文结构体写入请求扩展。
  3. 调用 next.run(req) 进入内层。
  4. handler 用 Extension<T> 取出上下文。

代码或图示

use axum::{
    Extension, http::Request, middleware::{self, Next}, response::Response, Router,
};

#[derive(Clone)]
struct CurrentUser { id: u64 }

async fn auth<B>(mut req: Request<B>, next: Next<B>) -> Response {
    let user = CurrentUser { id: 1 };
    req.extensions_mut().insert(user);
    next.run(req).await
}

async fn me(Extension(u): Extension<CurrentUser>) -> String { u.id.to_string() }

let app = Router::new()
    .route("/me", axum::routing::get(me))
    .route_layer(middleware::from_fn(auth));

常见误区

  • 在 next.run 返回后才写扩展:下游已经执行,读不到。
  • 上下文用裸字符串/数字类型:易与其它扩展冲突,应定义结构体。

追问

  • 扩展值需要 Clone 吗?答:提取器按值取出,定义为可克隆类型最稳妥;具体约束以当前版本为准。
  • 认证失败如何短路?答:不写扩展,直接返回 401 响应,不调用 next.run。

04.4.3.2-045 鉴权中间件的最小骨架如何实现,校验失败如何响应?

一句话结论

鉴权中间件读取凭证(头或 Cookie),校验通过则把主体写入扩展并调用 next,失败直接返回 401 响应,不进入内层路由。

概念解释

鉴权属于跨切面关注点,放中间件统一处理:解析 Authorization 头或会话 Cookie,校验签名/会话有效性,得到用户主体。通过后上下文进扩展,handler 不再重复解析;失败返回 401,缺失权限按场景返回 403。中间件只做认证与粗粒度授权,细粒度资源授权可在 handler/服务层完成。凭证校验细节(JWT、会话)在认证授权主题展开。

原理流程

  1. 中间件读取认证头或 Cookie。
  2. 校验凭证有效性与主体。
  3. 通过:主体写入扩展,调用 next.run。
  4. 失败:构造 401/403 响应直接返回。

代码或图示

use axum::{
    Extension, http::{Request, StatusCode}, middleware::{self, Next}, response::{IntoResponse, Response}, Router,
};

#[derive(Clone)]
struct AuthUser { id: u64 }

async fn auth<B>(req: Request<B>, next: Next<B>) -> Response {
    let token = req.headers()
        .get("authorization")
        .and_then(|v| v.to_str().ok())
        .map(|s| s.to_string());

    match token {
        Some(t) if t.starts_with("Bearer ") => {
            let mut req = req;
            req.extensions_mut().insert(AuthUser { id: 1 });
            next.run(req).await
        }
        _ => (StatusCode::UNAUTHORIZED, "missing token").into_response(),
    }
}

let app = Router::new()
    .route("/me", axum::routing::get(|Extension(u): Extension<AuthUser>| async move { u.id.to_string() }))
    .route_layer(middleware::from_fn(auth));

常见误区

  • 鉴权层挂在路由内层:未受保护的公开路由先经过,作用域错误。
  • 校验通过后仍在 handler 重复解析令牌:主体应从扩展读取。

追问

  • 401 与 403 怎么区分?答:未认证(无凭证/失效)返回 401,已认证但权限不足返回 403。
  • 会话凭证放哪里读取?答:会话中间件解析后把主体放扩展,鉴权层读取主体做授权判断。

04.4.3.2-046 限流中间件如何接入,按什么维度统计请求?

一句话结论

限流可用 tower-governor 等中间件 crate 或自定义层,按客户端 IP、用户 ID 或租户维度统计窗口请求数,超限返回 429;维度键从 ConnectInfo、扩展或头提取。

概念解释

限流保护服务不被突发流量打垮。常见算法有固定窗口、滑动窗口、令牌桶、漏桶;中间件在调用内层前检查配额,剩余额度放行,超限短路 429。维度选择:匿名按 IP,登录用户按用户 ID,多租户按租户。限流状态存内存或共享存储,多实例部署需集中计数。具体 crate 的 API 与配置以 docs.rs 当前版本为准,本层只绑定接入形态。

原理流程

  1. 中间件提取限流键(IP/用户/租户)。
  2. 查询/更新该键的计数与窗口状态。
  3. 未超限调用 next.run;超限返回 429。
  4. 响应头可携带剩余额度与重试时间。

代码或图示

use axum::{
    extract::ConnectInfo, http::Request, middleware::{self, Next},
    response::{IntoResponse, Response}, Router,
};
use std::net::SocketAddr;

async fn rate_limit<B>(
    ConnectInfo(addr): ConnectInfo<SocketAddr>,
    req: Request<B>,
    next: Next<B>,
) -> Response {
    // 实际计数由限流器维护,此处示意按地址取键
    let _key = addr.ip();
    next.run(req).await
}

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .route_layer(middleware::from_fn(rate_limit));

常见误区

  • 多实例用内存计数:各节点独立计数,总配额失控,需集中存储。
  • 限流键取不可信头未校验代理链:可被伪造绕过。

追问

  • tower-governor 提供什么能力?答:基于 governor 的令牌桶限流中间件,配置配额与等键方式;具体类型与 feature 以 docs.rs/tower-governor 当前版本为准。
  • 429 响应应带哪些头?答:可带 Retry-After 与剩余额度头,头名按团队约定。

04.4.3.2-047 会话中间件(tower-sessions)如何管理服务端会话?

一句话结论

会话中间件在 Cookie 中保存会话 ID,服务端存储对应会话数据;Session 提取器读写会话内容,存储后端可换内存、Redis 等,适合需要跨请求保持登录态的场景。

概念解释

无状态 JWT 与有状态会话是两条路线:会话中间件把服务端数据存后端,Cookie 只存 ID。SessionLayer 配置存储后端与 Cookie 选项,handler 用 Session 提取器读写键值。内存存储仅适合开发,生产用持久化后端。会话过期、轮换 ID、注销语义由中间件与存储实现。认证框架(如 axum-login 类 crate)可在会话之上封装登录主体管理。

原理流程

  1. 配置会话存储后端与 Cookie 选项,挂载 SessionLayer。
  2. 请求携带会话 ID,中间件加载对应会话数据。
  3. handler 通过 Session 读写会话字段。
  4. 响应前回写会话状态并刷新 Cookie。

代码或图示

// 依赖:tower-sessions,存储后端按选型引入
use axum::{extract::Session, routing::get, Router};

async fn whoami(session: Session) -> String {
    session.get::<u64>("user_id")
        .map(|id| id.to_string())
        .unwrap_or_else(|| "anon".into())
}

let app = Router::new().route("/me", get(whoami));
// SessionLayer 与 MemoryStore 的挂载写法以 tower-sessions 当前版本文档为准

常见误区

  • 生产用内存存储:重启会话全部丢失,多实例不共享。
  • 把敏感数据明文存会话:按后端加密与脱敏要求处理。

追问

  • 会话存储后端有哪些选择?答:内存用于开发,Redis 等持久化后端用于生产,可用后端列表以 tower-sessions 文档为准。
  • 会话与 JWT 怎么选?答:需要服务端主动注销与服务端状态选会话,纯无状态令牌选 JWT;对比在认证授权主题展开。

04.4.3.2-048 中间件如何统一返回 401/403 拒绝响应?

一句话结论

鉴权/授权失败时中间件直接构造 (StatusCode, Json(错误体)) 响应返回,不调用 next.run;响应结构与业务错误类型保持一致,避免客户端收到裸状态码。

概念解释

中间件短路响应与 handler 返回错误走同一套 IntoResponse 约定。未认证返回 401,缺权限返回 403,错误体包含稳定错误码与提示。响应头按需带 WWW-Authenticate。中间件不要泄露内部错误细节。统一错误类型可在中间件与 handler 间复用,保证前端解析一致。

原理流程

  1. 中间件完成凭证/权限判断。
  2. 失败分支构造状态码与错误体。
  3. into_response 转为标准响应直接返回。
  4. 成功分支才调用 next.run。

代码或图示

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

fn unauthorized() -> Response {
    (StatusCode::UNAUTHORIZED, Json(json!({ "error": "unauthenticated" }))).into_response()
}

fn forbidden() -> Response {
    (StatusCode::FORBIDDEN, Json(json!({ "error": "forbidden" }))).into_response()
}

常见误区

  • 失败时仍调用 next.run:未认证请求进入业务 handler。
  • 错误体返回内部 panic 信息:对外响应必须脱敏。

追问

  • 401 响应需要 WWW-Authenticate 头吗?答:按认证方案选择,Bearer 场景可携带该头,具体规范按方案文档。
  • 中间件错误能复用 handler 错误枚举吗?答:可以,统一错误类型实现 IntoResponse 后两处共用。

04.4.3.2-049 中间件如何读取与改写请求头、响应头?

一句话结论

前置阶段从 req.headers() 读取请求头并可 headers_mut() 改写;后置阶段在响应返回后操作 resp.headers_mut();注意头名规范化与多值头读取。

概念解释

中间件是跨切面改头的位置:读取 X-Forwarded-For、X-Request-Id,补充响应安全头、自定义标识头。请求头修改影响下游看到的值;响应头修改不影响上游请求。多值头用 get_all 迭代。头值非法 UTF-8 时按字节处理。不要在中间件反复解析业务头,解析结果写入扩展复用。

原理流程

  1. 前置:读取/修改请求头,必要时解析结果写扩展。
  2. 调用 next.run(req) 取得响应。
  3. 后置:读取/修改响应头。
  4. 返回加工后的响应。

代码或图示

use axum::{http::Request, middleware::{self, Next}, response::Response, Router};

async fn headers<B>(mut req: Request<B>, next: Next<B>) -> Response {
    let _agent = req.headers().get("user-agent").cloned();
    req.headers_mut().insert("x-processed", "1".parse().unwrap());
    let mut resp = next.run(req).await;
    resp.headers_mut().insert("x-server", "axum".parse().unwrap());
    resp
}

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .layer(middleware::from_fn(headers));

常见误区

  • 直接把 HeaderValue 当字符串比较:先 to_str() 校验。
  • 后置阶段改请求头:请求已进入内层,改响应才有效。

追问

  • 如何读取同名多值头?答:headers().get_all(name) 返回迭代器,常见于 Set-Cookie、Accept。
  • 安全响应头统一在哪里加?答:全局后置层集中补充,避免各 handler 重复设置。

04.4.3.2-050 中间件如何记录请求耗时与基本指标?

一句话结论

中间件在调用内层前记录起始时间,响应返回后计算耗时,配合状态码记录指标或日志;耗时统计放在外层中间件,覆盖完整链路。

概念解释

耗时是核心观测指标:从请求进入到响应产出的 wall-clock 时间。中间件记录开始 Instant,await 响应后计算差值,结合方法、路由模板、状态码输出日志或上报指标。路由模板需从扩展读取 MatchedPath,避免原始路径高基数。耗时统计层应尽量靠外,保证覆盖 fallback 与错误路径。注意不要在层内做重格式化阻塞链路。

原理流程

  1. 请求进入层,记录起始 Instant。
  2. 调用 next.run(req) 等待响应。
  3. 响应返回后计算耗时并读取状态码。
  4. 输出日志/指标后回传响应。

代码或图示

use axum::{http::Request, middleware::{self, Next}, response::Response, Router};
use std::time::Instant;

async fn timing<B>(req: Request<B>, next: Next<B>) -> Response {
    let start = Instant::now();
    let resp = next.run(req).await;
    let elapsed = start.elapsed();
    println!("status={} elapsed={:?}", resp.status(), elapsed);
    resp
}

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .layer(middleware::from_fn(timing));

常见误区

  • 耗时层挂在内层:未覆盖外层处理与短路响应。
  • 日志记录原始路径:参数值导致高基数,应取 MatchedPath 模板。

追问

  • 耗时指标按什么维度聚合?答:方法、路由模板、状态码为常用维度;用户与租户维度按需要再加。
  • 慢请求如何标记?答:超过阈值在日志或指标中打慢请求标记,具体阈值按 SLA 设置。

04.4.3.2-051 同一层被重复挂载会出现什么问题?

一句话结论

同一层在全局与路由级、父子路由间重复挂载,会导致日志重复、计数翻倍、响应头重复追加;排查「一次请求两条日志/两次计数」先检查层是否被叠加挂载。

概念解释

层叠加不是幂等的:日志层记录两次进入与返回,计数层自增两次,追加响应头的层写入重复头。常见来源:父 Router 挂了全局层,子 Router 又挂同名层;merge 两张各自带层的路由表。修复方式是明确每层唯一作用域,全局观测层只挂根,业务层挂对应路由。排查时在层内打印挂载标识,确认请求穿过几次。

原理流程

  1. 检查根 Router、子 Router、路由节点的层挂载清单。
  2. 识别同一类型层出现多次的位置。
  3. 按作用域保留一处,移除重复挂载。
  4. 用测试请求验证日志与计数只出现一次。

代码或图示

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

// 避免:根层与子树层重复挂 TraceLayer
let sub = Router::new().route("/inner", get(|| async { "i" }));
let app = Router::new()
    .route("/outer", get(|| async { "o" }))
    .nest("/sub", sub)
    .layer(TraceLayer::new_for_http());

常见误区

  • 以为层重复挂载只是冗余无副作用:计数、日志、头都会重复。
  • 子树需要独立配置时复制整层:应通过层参数区分,而不是重复同一实例。

追问

  • 如何确认层执行了几次?答:在层前置逻辑打印固定标识,一次请求观察出现次数。
  • 重复追加的响应头有什么影响?答:同名多值头可能被客户端按多值解析,语义与预期不符。

04.4.3.2-052 超时层为什么会与 SSE、长轮询等流式响应冲突?

一句话结论

TimeoutLayer 等待整个响应 Future 完成,流式连接持续输出数据不结束,超时会在限定时间后切断连接;长连接接口需要单独放宽或关闭超时层。

概念解释

普通请求在有限时间内返回完整响应,超时层按整体完成时间计时。SSE、WebSocket、长轮询的响应是持续流,连接存活时间远大于普通接口。全局超时套到流式路由上会提前断开推送。处理方式:流式路由不挂全局超时,或挂更长的独立超时;超时层只控制等待响应完成,不管理连接保活。WebSocket 升级流程在实时通信主题展开。

原理流程

  1. 超时层等待内层响应 Future。
  2. 流式响应 Future 长期不完成。
  3. 计时器先到期,层放弃等待并返回超时响应。
  4. 推送连接被切断,后续事件无法下发。

代码或图示

use axum::{routing::get, Router};
use tower_http::timeout::TimeoutLayer;
use std::time::Duration;

// 普通接口全局超时
let api = Router::new()
    .route("/api", get(|| async { "ok" }))
    .layer(TimeoutLayer::new(Duration::from_secs(10)));

// 流式接口单独挂载,不套同一超时层
let app = Router::new().merge(api);

常见误区

  • 给所有路由统一套超时:流式接口被误杀。
  • 以为超时层只限制 handler 首字节:它等待整个响应完成。

追问

  • 流式接口需要什么保护?答:空闲超时、心跳与连接数限制单独设计,不能复用整体响应超时。
  • 超时后内部流任务会被取消吗?答:层放弃等待,底层任务是否取消取决于流实现,需实测确认。

04.4.3.2-053 body 限制层与提取器默认限制在链路上的位置关系是什么?

一句话结论

RequestBodyLimitLayer 在进入路由前拦截,DefaultBodyLimit 在提取器消费 body 时校验;两层叠加时先过层限制,再过提取器限制,阈值取更严格者。

概念解释

body 限制分两道:链路层在请求早期统计/拦截,提取器在读取字节时再次检查。上传接口放宽时必须两处同时调整,否则仍被较早的限制拦截。层限制适合全局统一阈值,提取器限制按路由/提取器类型微调。排查 413 时先确认是哪一层拒绝,再调整对应阈值。

原理流程

  1. 请求进入 RequestBodyLimitLayer,按全局阈值检查。
  2. 未超限进入路由,提取器读取 body 时过 DefaultBodyLimit。
  3. 任一环节超限返回 413 类响应。
  4. 全部通过才解析 body。

代码或图示

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

let app = Router::new()
    .route("/upload", post(|| async { "ok" }))
    .layer(RequestBodyLimitLayer::new(5_000_000))
    .layer(DefaultBodyLimit::max(5_000_000));

常见误区

  • 只调大 DefaultBodyLimit:层限制先生效,接口仍 413。
  • 两层阈值不一致却不记录来源:排错无法定位是哪道限制。

追问

  • 某条路由想放宽限制怎么做?答:路由级覆盖默认限制,层限制按挂载范围调整;流式上传另做单字段控制。
  • 待确认点是什么?答:当前版本两层默认字节数与拒绝状态码映射,验证方式为 docs.rs 对应类型文档与超限用例。

04.4.3.2-054 压缩层与流式响应、已压缩二进制为什么会冲突?

一句话结论

压缩层缓冲并压缩响应 body,与需要即时推送的流不兼容;对已是压缩格式的二进制重复压缩只增加 CPU 不减少体积。

概念解释

普通一次性响应适合压缩;SSE 等流式响应要求数据即时下发,压缩缓冲会延迟事件。图片、视频、压缩包本身已压缩,再压缩收益极小甚至变大。工程上对流式路由关闭压缩,按 Content-Type 跳过二进制类型。压缩层配置可跳过指定媒体类型。响应编码协商失败时 body 不压缩直接返回。

原理流程

  1. 压缩层读取 Accept-Encoding 协商编码。
  2. 判断响应类型是否可压缩。
  3. 可压缩则缓冲压缩;流式/二进制跳过。
  4. 写入 Content-Encoding 头返回。

代码或图示

use axum::{routing::get, Router};
use tower_http::compression::CompressionLayer;

let app = Router::new()
    .route("/text", get(|| async { "plain" }))
    .layer(CompressionLayer::new());
// SSE 流式路由建议单独挂载,不叠加该压缩层

常见误区

  • 全局压缩覆盖流式路由:事件被缓冲,推送延迟。
  • 压缩图片/视频:CPU 浪费,体积基本不变。

追问

  • 如何按媒体类型跳过压缩?答:CompressionLayer 提供谓词/策略配置,具体方法名以 docs.rs/tower-http 当前版本为准。
  • 压缩层会修改 Content-Length 吗?答:压缩后体积变化,长度头按压缩后 body 重新计算,具体行为以层实现为准。

04.4.3.2-055 CORS 预检为什么要求 CORS 层位于业务路由之前?

一句话结论

预检 OPTIONS 需要在进入业务路由前被层识别并直接响应;CORS 层挂在内层或路由级时,预检请求可能先落到路由分发器返回 405。

概念解释

浏览器预检是跨域流程的第一步,业务 handler 不应该处理 OPTIONS。CORS 层在全局外层拦截预检并返回允许头。若 CORS 层挂在路由内层,请求先经过路由匹配,未注册 OPTIONS 分支就返回 405,预检失败。实际请求的 CORS 响应头也由该层在后置阶段补充。层顺序问题表现为预检 405 或跨域头缺失。

原理流程

  1. 浏览器发送 OPTIONS 预检。
  2. 全局 CORS 层识别预检并校验来源/方法/头。
  3. 通过则直接返回带 CORS 头的预检响应。
  4. 实际请求再进入业务路由,响应由层补充跨域头。

代码或图示

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

let app = Router::new()
    .route("/items", get(|| async { "items" }))
    .layer(CorsLayer::permissive()); // 外层处理预检

常见误区

  • CORS 层挂 route_layer:预检请求未命中业务分支时绕过层。
  • 只在 handler 里加 CORS 头:预检 OPTIONS 没有对应 handler。

追问

  • 预检通过后实际请求仍被跨域拦为什么?答:实际响应缺少 CORS 头,层配置未覆盖真实响应,检查 allow_origin 等配置。
  • CorsLayer::permissive() 适合生产吗?答:放开全部限制,仅适合内部演示,生产应收敛来源与方法。

04.4.3.2-056 生产环境推荐的层组合顺序大致是什么?

一句话结论

从外到内常见顺序:追踪/请求 ID → CORS → panic 捕获 → 超时 → 限流/鉴权 → 压缩 → 业务路由;观测类在外层覆盖全链路,安全类在业务前,压缩靠近响应侧。

概念解释

层顺序按职责排:最外层观测完整链路(Trace、RequestId),CORS 先处理预检,panic 兜底包住内层,超时与限流保护资源,鉴权放行后才进业务,压缩在响应侧减少传输。子路由可叠加自己的业务层。具体顺序还要结合层实现:需要读取完整响应的层不应被内层短路绕过。顺序确定后用请求样例验证各层前后置行为。

原理流程

  1. 外层:请求 ID、追踪日志,记录完整生命周期。
  2. 中间:CORS、panic、超时、限流、鉴权。
  3. 内层:压缩等响应加工层与业务路由。
  4. 响应沿链回传,各层后置加工。

代码或图示

请求 → RequestId → Trace → CORS → CatchPanic → Timeout → RateLimit → Auth → Compression → handler
响应 ←─────────────────────────────────────────────────────────────────────── ←

常见误区

  • 压缩放在鉴权外层:未鉴权响应也被压缩,语义混乱。
  • 观测层挂在内层:短路响应与 panic 路径记录不到。

追问

  • 鉴权与限流谁先谁后?答:通常限流先于鉴权保护资源,鉴权再校验身份;按防护目标调整。
  • 层顺序有官方固定模板吗?答:tower-http 文档给推荐组合,具体业务可调整,以实际行为验证为准。

04.4.3.2-057 全局层包裹 fallback 会带来哪些需要注意的场景?

一句话结论

全局层对兜底响应同样生效:日志、压缩、安全头、超时都会作用于 404 与静态兜底;设计兜底响应时要确认这些后置逻辑符合预期,避免兜底被鉴权层拦截。

概念解释

fallback 是 Router 服务的一部分,全局层在外层包裹它。观测层记录 404 请求属于正常需求;鉴权层若挂全局会连兜底一起保护,静态资源需要匿名访问时应把鉴权放路由层。压缩与安全头对兜底响应同样生效。排查「静态资源 404/被拦截」时确认全局层行为。

原理流程

  1. 请求未命中业务路由,进入兜底节点。
  2. 兜底响应仍穿过全局层链。
  3. 各全局层后置逻辑加工兜底响应。
  4. 客户端收到处理后的兜底响应。

代码或图示

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

let app = Router::new()
    .route("/api", get(|| async { "ok" }))
    .fallback_service(ServeDir::new("dist"))
    .layer(axum::middleware::from_fn(|req, next| async { next.run(req).await }));

常见误区

  • 以为兜底绕过全局层:全局层包裹整体服务,兜底同样经过。
  • 鉴权放全局层导致静态资源不可匿名访问:应改用路由层。

追问

  • 兜底响应需要单独加安全头怎么做?答:全局后置层按响应路径或状态码判断后补头,或在兜底服务内自行设置。
  • 404 日志高基数怎么处理?答:记录模板化路径与状态,不记录完整参数值。

04.4.3.2-058 中间件里做阻塞调用会有什么风险?

一句话结论

中间件运行在异步任务上下文,同步阻塞 IO 或长 CPU 计算会卡住当前 worker 线程,降低整体并发;阻塞工作应放 spawn_blocking,中间件本身保持轻量。

概念解释

从 fn 中间件的 next.run 是异步调用,层逻辑与 handler 同处于运行时 worker。在中间件里同步读文件、调用阻塞锁、跑密集计算会阻塞线程调度。鉴权查缓存应使用异步客户端;必须用阻塞库时丢阻塞线程池。中间件职责是跨切面轻量判断,重业务下沉服务层。这条规则与 async handler 中的阻塞风险一致,只是发生位置在层链。

原理流程

  1. 中间件前置逻辑执行。
  2. 出现阻塞调用时 worker 线程被占住。
  3. 同线程其它任务等待调度。
  4. 阻塞结束后才继续 next.run。

代码或图示

use axum::{http::Request, middleware::{self, Next}, response::Response, Router};

async fn mw<B>(req: Request<B>, next: Next<B>) -> Response {
    // 阻塞计算应放入 spawn_blocking,不在中间件内同步执行
    next.run(req).await
}

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .layer(middleware::from_fn(mw));

常见误区

  • 中间件内同步查询本地文件做校验:阻塞 worker。
  • 持同步锁跨越 next.run:守卫不 Send,编译或运行出问题。

追问

  • 如何在中间件调用阻塞库?答:tokio::task::spawn_blocking 包装后 await JoinHandle,与 handler 中的处理方式一致。
  • 中间件能发起异步远程调用吗?答:可以,但应设超时并控制并发,避免层链被下游拖慢。

04.4.3.2-059 Service 克隆机制与 State 共享是什么关系?

一句话结论

MakeService 为每个连接克隆 Router/Service,克隆复制的是句柄;State 内部 Arc 资源在克隆间共享,层持有的配置值也随克隆复制。

概念解释

服务工厂产出连接级 Service 时克隆整体服务结构。可克隆性是 Service 约束之一。State 句柄克隆不复制底层资源,连接池与客户端在克隆间复用。层若持有配置,克隆时复制配置值;持有可变状态的层要确保线程安全。理解克隆机制后能判断:为什么状态要 Clone,为什么重资源要 Arc。

原理流程

  1. MakeService 收到新连接。
  2. 克隆 Router/Service 结构生成连接实例。
  3. State 句柄与层配置随克隆复制。
  4. 内部 Arc 资源指向同一份共享数据。

代码或图示

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

#[derive(Clone)]
struct AppState { pool: Arc<DbPool> }
struct DbPool;

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

let app = Router::new().route("/", get(handler))
    .with_state(AppState { pool: Arc::new(DbPool) });
// into_make_service 后按连接克隆句柄

常见误区

  • 以为克隆会复制整个连接池:复制的是 Arc 句柄,池内部共享。
  • 层持有非 Clone 可变状态:服务克隆约束不满足。

追问

  • 连接级状态放哪里?答:由工厂产出的 Service 实例持有,State 是跨连接共享;连接级缓存按服务实例设计。
  • 如何观察克隆次数?答:可在状态句柄上辅助打印 Arc 计数,但业务逻辑不依赖计数。

04.4.3.2-060 中间件与自定义服务需要满足哪些 Send + Sync + 'static 约束?

一句话结论

中间件闭包、自定义 Service 及其返回 Future 必须 Send + 'static,层与服务持有的共享状态需 Sync;约束不满足会在挂载或编译期报错。

概念解释

请求在多线程运行时调度,服务与 Future 可跨线程移动,因此要求 Send;层/服务被多个连接共享访问,内部状态需 Sync。'static 排除短生命周期借用。常见违规:闭包捕获 Rc、持有非 Send 守卫、Future 捕获跨线程不 Send 类型。排查报错时先定位闭包捕获值与内部字段的线程安全性质。

原理流程

  1. 中间件/服务被挂载到 Router。
  2. 编译器检查闭包、服务结构、Future 的 Send + 'static。
  3. 共享状态检查 Sync。
  4. 不满足则在编译期指出违规类型。

代码或图示

use axum::{http::Request, middleware::{self, Next}, response::Response, Router};
use std::sync::Arc;

#[derive(Clone)]
struct Cfg { enabled: Arc<std::sync::atomic::AtomicBool> }

async fn mw<B>(req: Request<B>, next: Next<B>) -> Response {
    next.run(req).await
}

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .layer(middleware::from_fn(mw));

常见误区

  • 中间件闭包捕获 Rc:不 Send,应换 Arc。
  • 自定义服务 Future 持有非 Send 局部值:跨线程调度失败。

追问

  • Sync 约束在哪个环节检查?答:服务被多连接共享时,内部可变字段需线程安全;报错类型指向具体字段。
  • 异步中间件 Future 不 Send 怎么修?答:找出 Future 捕获的非 Send 类型,换成线程安全结构或避免跨 await 持有。

04.4.3.2-061 子路由独立加层与父层如何叠加,层会被子树替换吗?

一句话结论

子路由层在父层内部叠加,父全局层仍然包裹子树;子树层只影响自己的路由节点,不会替换父层,两层按外层到内层顺序执行。

概念解释

父 Router 挂全局层后,子 Router 再挂自己的层:请求先过父层,再进子树层,最后到 handler。子树层可做模块专属鉴权、日志格式;父层保留通用观测。merge 进来的子路由自带层同样叠加。排查子树「没经过某层」时,区分是父层未覆盖还是子树层未挂载。

原理流程

  1. 父 Router 挂载全局层。
  2. 子 Router 挂载子树层。
  3. 命中子树请求:父层前置 → 子树层前置 → handler。
  4. 响应按子树层后置 → 父层后置回传。

代码或图示

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

let sub = Router::new()
    .route("/inner", get(|| async { "i" }))
    .route_layer(axum::middleware::from_fn(|req, next| async { next.run(req).await }));

let app = Router::new()
    .nest("/sub", sub)
    .layer(axum::middleware::from_fn(|req, next| async { next.run(req).await }));

常见误区

  • 以为子树层会覆盖父层:父层仍在外层生效。
  • 子树重复挂父层已有逻辑:重复执行,见重复加层问题。

追问

  • 子树层能访问父层写入的扩展吗?答:扩展随请求向下传递,可以读取;反之不行。
  • 子树收窄 State 后层还能访问父状态吗?答:收窄后按子状态类型访问,父状态不再可取。

04.4.3.2-062 tower-http 的 feature 应如何按需开启?

一句话结论

按实际使用的层与服务在 Cargo.toml 开启对应 feature(trace、cors、compression、timeout、limit、set-request-id、normalize-path、catch-panic、serve-dir 等),未使用的不开,避免无关依赖进入编译。

概念解释

tower-http 按能力拆分 feature,每个层/服务可能绑定对应编码或依赖。引入 crate 时只声明用到的 feature,编译体积与依赖图更干净。feature 名称随版本可能调整,新增层时查 docs.rs 确认 feature 名。axum 自身 re-export 部分类型,但层实现仍来自 tower-http。版本范围写宽松 semver,锁定以 Cargo.lock 为准。

原理流程

  1. 列出工程使用的 tower-http 组件。
  2. 对照文档为每个组件找到对应 feature。
  3. 在依赖声明中开启 feature 集合。
  4. 编译确认无缺失依赖告警。

代码或图示

[dependencies]
tower-http = { version = "0.6", features = [
    "trace", "cors", "compression-gzip", "timeout",
    "request-body-limit", "set-request-id", "normalize-path",
    "catch-panic", "serve-dir",
] }

常见误区

  • 照搬示例开启全部 feature:编译慢、引入不必要编码依赖。
  • 层类型找不到却没开对应 feature:编译报未导出类型。

追问

  • 压缩编码 feature 与普通压缩层区别?答:不同编码(gzip、br、deflate)可能对应独立 feature,按需开启,以当前版本清单为准。
  • 如何查看已引入的 tower-http 依赖?答:cargo tree -p tower-http 查看特性与传递依赖。

04.4.3.2-063 压缩编码选择与压缩级别如何配置?

一句话结论

压缩层按客户端 Accept-Encoding 与启用编码协商;压缩级别、是否压缩流式/二进制由层策略控制,配置项名称与默认级别以 tower-http 当前版本为准。

概念解释

常见编码 gzip 兼容性好,br 压缩率更高但需服务端与客户端支持。级别越高压缩率越好但 CPU 开销越大。文本类响应收益明显,二进制媒体跳过。配置时先按响应类型评估收益,再选级别。待确认的具体方法名与默认级别应查 docs.rs,不在代码里写死未核实项。

原理流程

  1. 层启用指定编码集。
  2. 读取客户端 Accept-Encoding 协商。
  3. 按策略判断响应是否可压缩。
  4. 按级别压缩并写编码头。

代码或图示

use axum::Router;
use tower_http::compression::CompressionLayer;

let app = Router::new()
    .route("/", axum::routing::get(|| async { "text" }))
    .layer(CompressionLayer::new());
// 编码与级别配置项以 docs.rs/tower-http 当前版本为准

常见误区

  • 盲目用最高压缩级别:CPU 成本上升,高并发下吞吐下降。
  • 不检查响应类型:二进制被重复压缩。

追问

  • br 编码需要额外依赖吗?答:通常对应独立 feature 与压缩库,以当前版本 feature 清单为准。
  • 如何对大响应禁用压缩?答:按响应大小或媒体类型配置跳过策略,具体谓词 API 查文档。

04.4.3.2-064 应用请求超时与 TCP 连接超时有什么区别?

一句话结论

TimeoutLayer 限制请求处理时长,属于应用层;TCP 连接超时由监听 Server 与操作系统控制,限制建立连接阶段,两者作用阶段不同,不能互相替代。

概念解释

请求超时覆盖从进入服务到响应产出的时间,保护慢 handler 与慢下游;连接超时控制 accept 阶段握手与建立连接的等待,属于 hyper/Server 配置。空闲连接保活由 keep-alive 设置管理。部署中三类超时分别配置:连接建立、请求处理、空闲保活。超时层取消的是等待,不一定终止内部任务。

原理流程

  1. TCP 握手阶段受连接超时约束。
  2. 连接建立后请求进入应用层。
  3. TimeoutLayer 按处理时长计时。
  4. 空闲连接由 keep-alive 策略回收。

代码或图示

use axum::Router;
use tower_http::timeout::TimeoutLayer;
use std::time::Duration;

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .layer(TimeoutLayer::new(Duration::from_secs(10)));
// 连接超时与 keep-alive 在 Server 绑定配置中设置

常见误区

  • 用请求超时限制连接建立:阶段不匹配。
  • 把超时层当成连接数限制:并发控制需限流器或信号量。

追问

  • Server 连接超时在哪里配?答:hyper Server 的绑定与服务配置,具体 API 以 hyper/axum 当前版本为准。
  • 超时响应与 504 是什么关系?答:网关超时 504 与应用超时映射按工程错误约定,层默认错误类型需自定义映射。

04.4.3.2-065 请求 ID 如何进入 tracing span 并跨服务透传?

一句话结论

SetRequestIdLayer 生成 ID 写入扩展与响应头;TraceLayer 从扩展读取 ID 挂到 span 字段;出站调用时把 ID 放入请求头,下游服务继续透传形成链路。

概念解释

单服务内请求 ID 串联日志;跨服务调用需要把 ID 带入出站请求头,下游解析后继续传播。ID 写入扩展供业务与层读取,响应头返回客户端便于排障。Trace 上下文中的 span 字段携带 ID,日志按 ID 聚合。注意入站 ID 要校验格式,避免伪造日志。跨服务传播格式按团队约定。

原理流程

  1. 入站层生成或传播请求 ID。
  2. ID 写入扩展,TraceLayer 挂到 span。
  3. 出站客户端请求带上 ID 头。
  4. 下游读取 ID 继续链路记录。

代码或图示

use axum::{routing::get, Router};
use tower_http::request_id::SetRequestIdLayer;
use http::HeaderName;

let app = Router::new()
    .route("/", get(|| async { "ok" }))
    .layer(SetRequestIdLayer::new(HeaderName::from_static("x-request-id")));

常见误区

  • 只生成 ID 不写入扩展:Trace 与业务日志取不到。
  • 出站调用不带 ID:跨服务链路断裂。

追问

  • 如何保留客户端传入的 ID?答:使用传播相关层读取已有头,缺失再生成;组合方式以 tower-http 文档为准。
  • ID 与 OpenTelemetry TraceId 是什么关系?答:可相互映射,具体集成在可观测性主题展开。

04.4.3.2-066 尾斜杠归一化的两种模式如何选择?

一句话结论

去尾斜杠模式把 /foo/ 规整为 /foo,补尾斜杠模式把 /foo 规整为 /foo/;按路由注册风格统一选择一种,避免混用导致重复 404。

概念解释

路由模板注册风格决定归一化方向:资源路由多不带尾斜杠,选 trim 模式;目录风格路由带尾斜杠,选补全模式。混用两种模式会在边界产生重定向或 404。归一化层在匹配前改写路径,原始路径用 OriginalUri 读取。具体模式枚举名以 tower-http 当前版本为准。

原理流程

  1. 按团队路由风格选择归一化模式。
  2. 层在匹配前规整请求路径。
  3. 匹配树在规整路径上查找。
  4. 响应不自动 301 跳转,行为以层实现为准。

代码或图示

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());

常见误区

  • 路由模板带尾斜杠却用去尾模式:规整后模板不匹配。
  • 两个服务实例配置不同模式:同一路径行为不一致。

追问

  • 归一化会产生重定向响应吗?答:层默认改写内部路径,是否对外 301 以当前版本实现为准,需用例验证。
  • 多余连续斜杠如何处理?答:归一化覆盖范围以当前版本文档为准,不确定就用用例确认。

04.4.3.2-067 CatchPanicLayer 与 Rust 全局 panic hook 如何分工?

一句话结论

CatchPanicLayer 在服务链内把 panic 转成错误响应;全局 panic hook 是进程级 panic 钩子,记录与上报崩溃,二者层级不同,不能互相替代。

概念解释

panic hook 在 panic 展开时执行,做日志、上报、清理;CatchPanicLayer 在服务层捕获本次请求的 panic 并返回响应,避免连接直接失败。业务可预期错误走 Result,panic 只兜底不可恢复异常。层捕获后内部状态一致性仍需评估,hook 不能恢复被中断的数据结构。两者配合:hook 负责崩溃记录,层负责请求级兜底响应。

原理流程

  1. 内层任务触发 panic。
  2. CatchPanicLayer 捕获并转换为错误响应。
  3. 若未被层捕获,panic 展开经过全局 hook。
  4. hook 记录后按 panic 策略终止或继续。

代码或图示

use axum::{routing::get, Router};
use tower_http::catch_panic::CatchPanicLayer;

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

常见误区

  • 以为挂了 panic 层就不需要 panic 日志:层转换响应,崩溃细节仍需 hook/日志记录。
  • 用 panic 做流程控制:应返回错误值。

追问

  • panic 后 Worker 线程会退出吗?答:取决于运行时与 panic 策略,层捕获的是请求级 panic,具体行为以 tokio/hyper 当前版本为准。
  • 层如何自定义 panic 响应?答:通过层配置提供错误响应构造,具体 API 查 docs.rs/tower-http。

04.4.3.2-068 自定义层或服务访问 State 时类型标注怎么写?

一句话结论

带状态中间件用 State<S> 参数并由 from_fn_with_state 注入;自定义 Layer 在构造时接收状态句柄存入服务结构体,类型标注为具体 AppState 或泛型 S 并约束线程安全。

概念解释

axum 中间件形式支持直接声明 State<S>;裸 Layer/Service 不经过 axum 提取器,状态需在层构造时由调用方传入句柄。类型标注选择:固定应用用具体 AppState,通用层用泛型 S 加 trait 约束。状态字段访问方式与 handler 一致,线程安全约束相同。构造层时传入的状态要与路由 with_state 类型兼容。

原理流程

  1. 方案一:from_fn_with_state 函数首参 State<S>。
  2. 方案二:Layer 结构体保存状态句柄,layer 时传入服务。
  3. 服务实现内通过句柄读状态字段。
  4. 类型约束 Clone + Send + Sync + 'static。

代码或图示

use axum::{extract::State, http::Request, middleware::{self, Next}, response::Response, Router};

#[derive(Clone)]
struct AppState { debug: bool }

async fn mw<B>(State(s): State<AppState>, req: Request<B>, next: Next<B>) -> Response {
    let _ = s.debug;
    next.run(req).await
}

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .route_layer(middleware::from_fn_with_state(AppState { debug: false }, mw));

常见误区

  • 裸 Layer 里期待自动注入 State:Layer 不经 axum 提取器,需显式传句柄。
  • 状态类型在层与路由间不一致:编译报类型不匹配。

追问

  • 通用层如何不绑定具体 AppState?答:层定义泛型 S 并要求所需 trait,构造时传入句柄;具体约束按访问字段推导。
  • 层状态与路由状态是同一份吗?答:注入同一实例句柄即为共享;分别传入会得到两份独立句柄。

04.4.3.2-069 中间件产生的错误如何映射为统一响应?

一句话结论

中间件失败分支构造状态码与错误体,经 IntoResponse 转标准响应;与 handler 共用统一错误枚举,保证对外结构一致,内部细节不暴露。

概念解释

鉴权失败、限流超限、上游校验拒绝都在中间件短路。错误响应结构应与业务错误一致:错误码、提示、请求 ID。中间件可从扩展取请求 ID 写入错误体。错误类型实现 IntoResponse 后,中间件与 handler 复用。映射原则:对外状态码稳定,内部原因只进日志。

原理流程

  1. 中间件判断失败类别。
  2. 选择对应状态码与错误枚举变体。
  3. 调用 into_response 生成响应。
  4. 不调用 next.run,直接回传错误响应。

代码或图示

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

enum MiddlewareError {
    Unauthorized,
    TooManyRequests,
}

impl IntoResponse for MiddlewareError {
    fn into_response(self) -> Response {
        let (status, msg) = match self {
            MiddlewareError::Unauthorized => (StatusCode::UNAUTHORIZED, "unauthorized"),
            MiddlewareError::TooManyRequests => (StatusCode::TOO_MANY_REQUESTS, "rate limited"),
        };
        (status, Json(json!({ "error": msg }))).into_response()
    }
}

常见误区

  • 中间件返回裸状态码:前端缺少错误结构无法解析。
  • 错误体包含内部异常文本:对外响应需脱敏。

追问

  • 限流 429 需要带 Retry-After 吗?答:建议携带,值为建议重试秒数,头名按 HTTP 规范。
  • 中间件错误能被全局错误层再次加工吗?答:响应沿链回传,外层后置层可统一补头与包装。

04.4.3.2-070 map_request 与 map_response 便捷层适合做什么?

一句话结论

map_request 在调用内层前同步/异步改写请求,map_response 在内层返回后加工响应;适合简单的请求改写或响应补头,复杂逻辑再用 from_fn 或自定义 Layer。

概念解释

axum middleware 模块提供便捷组合器:map_request 闭包接收请求返回新请求,map_response 闭包接收响应返回新响应。它们省去手写 Service 包装,适合补请求头、改响应状态、加安全头。需要条件分支短路、读写扩展或访问 State 时,用 from_fn/from_fn_with_state。便捷层同样按挂载顺序形成链。

原理流程

  1. map_request 闭包前置改写请求。
  2. 内层处理请求。
  3. map_response 闭包后置加工响应。
  4. 加工后的响应回传。

代码或图示

use axum::{http::Request, middleware::{self, map_request, map_response}, response::Response, Router};

fn add_header<B>(req: Request<B>) -> Request<B> { req }

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .route_layer(middleware::map_request(add_header))
    .route_layer(middleware::map_response(|resp: Response| resp));

常见误区

  • 在 map_request 里做短路响应:便捷组合器只改请求,短路需 from_fn。
  • 用便捷层访问 State:不带状态参数,需要时换带状态形式。

追问

  • map 闭包能是 async 吗?答:按当前版本 middleware 组合器签名支持情况为准,复杂异步逻辑用 from_fn。
  • 便捷层与手写 Layer 性能差异大吗?答:抽象成本相近,选型以可读性与功能需求为准。

04.4.3.2-071 from_fn 中间件函数签名与 Next 参数如何使用?

一句话结论

from_fn 中间件签名为 async fn(Request<B>, Next<B>) -> Response;Next 持有内层服务,调用 next.run(req) 进入下游并返回响应 Future。

概念解释

Next<B> 是内层服务的句柄,泛型 B 为 body 类型。函数先做前置处理,显式调用 next.run 把请求传入内层,await 响应后可后置加工。不调用 next.run 即短路。body 类型 B 通常保持泛型,层不消费 body。from_fn 不注入 State,需要状态用 from_fn_with_state。

原理流程

  1. 中间件函数接收请求与 Next。
  2. 前置逻辑读取请求、写扩展。
  3. next.run(req).await 调用内层。
  4. 后置逻辑加工响应后返回。

代码或图示

use axum::{http::Request, middleware::{self, Next}, response::Response, Router};

async fn my_mw<B>(req: Request<B>, next: Next<B>) -> Response {
    // 前置逻辑
    let resp = next.run(req).await;
    // 后置逻辑
    resp
}

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .layer(middleware::from_fn(my_mw));

常见误区

  • 忘记 await next.run:响应 Future 未完成,返回类型不符。
  • 把 Next 当成 handler 参数:它是内层服务句柄,不是提取器。

追问

  • Next 能被多次调用吗?答:一次请求只应调用一次内层,重复调用语义不成立;具体约束以当前版本为准。
  • body 类型 B 可以写死吗?答:保持泛型 B 兼容性最好,写死具体 Body 类型会限制内层组合。

04.4.3.2-072 from_fn 中间件支持哪些提取器参数?

一句话结论

from_fn_with_state 形式可在请求与 Next 前声明部件提取器(如 State、Extension、Path、HeaderMap);普通 from_fn 只接收原始请求与 Next,提取器由函数内手动读取。

概念解释

带状态中间件支持与 handler 类似的提取器参数,部件提取器排在请求前,body 提取器不用于中间件。提取器失败时中间件同样短路拒绝。中间件提取器适合复用已有解析逻辑,例如从扩展取主体、从头取 ID。参数顺序与约束规则和 handler 一致,body 不能被中间件消费后再传下游。

原理流程

  1. 中间件函数声明提取器参数、请求、Next。
  2. 适配器先构造提取器值。
  3. 成功后执行中间件逻辑并调用 next.run。
  4. 提取失败返回拒绝响应。

代码或图示

use axum::{
    extract::{Extension, State}, http::Request, middleware::{self, Next},
    response::Response, Router,
};

#[derive(Clone)]
struct AppState { mode: String }
#[derive(Clone)]
struct Ctx(String);

async fn mw<B>(
    State(s): State<AppState>,
    Extension(c): Extension<Ctx>,
    req: Request<B>,
    next: Next<B>,
) -> Response {
    let _ = (&s.mode, &c.0);
    next.run(req).await
}

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .route_layer(middleware::from_fn_with_state(AppState { mode: "x".into() }, mw));

常见误区

  • 普通 from_fn 里声明提取器参数:形式不支持,需换 from_fn_with_state。
  • 中间件用 body 提取器消费 body:下游拿不到 body。

追问

  • 中间件提取器失败返回什么状态码?答:走对应提取器的拒绝映射,与 handler 中行为一致。
  • 中间件能取 Path 吗?答:部件提取器可取,但路径匹配在层链中的时机需确认,外层中间件可能尚未完成匹配。

04.4.3.2-073 中间件能否读取并转发请求 body?

一句话结论

中间件默认持有请求句柄并向下传递,不消费 body;需要读取 body 时必须先取出字节,再用新 body 重建请求传给 next.run,否则下游拿不到 body。

概念解释

body 是流,中间件一旦读取消费,原请求不再带 body。需要在层内校验 body(签名、大小、哈希)时,先聚合字节,再 Request::from_parts 重建带 Body::from(bytes) 的请求。读取全量 body 有内存成本,大 body 场景应谨慎。中间件通常只读写头与扩展,body 解析留给提取器。

原理流程

  1. 拆分请求 Parts 与 Body。
  2. 聚合 body 字节供中间件校验。
  3. 用字节重建 Body 与请求。
  4. 把新请求传给 next.run。

代码或图示

use axum::{http::Request, body::Body, middleware::{self, Next}, response::Response, Router};

async fn inspect(req: Request<Body>, next: Next<Body>) -> Response {
    let (parts, body) = req.into_parts();
    let bytes = axum::body::to_bytes(body, usize::MAX).await.unwrap_or_default();
    // 此处校验 bytes,再重建请求
    let rebuilt = Request::from_parts(parts, Body::from(bytes));
    next.run(rebuilt).await
}

let app = Router::new()
    .route("/", axum::routing::post(|| async { "ok" }))
    .layer(middleware::from_fn(inspect));

常见误区

  • 中间件读了 body 却传原请求:下游 body 为空。
  • 无限制聚合大 body:内存风险,需先过大小限制。

追问

  • 中间件能只读 body 一部分再透传吗?答:流被部分消费后需重组剩余字节,实现复杂;通常全量聚合或不在层内读 body。
  • 响应 body 能在中间件读取吗?答:可以包装响应 body 流,但缓冲响应同样有成本,按需使用。

04.4.3.2-074 中间件短路响应的条件是什么,需要注意什么?

一句话结论

鉴权失败、限流超限、请求不合法等场景可在中间件直接返回响应,不调用 next.run;短路时要写清状态码与错误体,并确保不遗漏必要响应头。

概念解释

短路是中间件的核心能力:前置校验不通过就不进入业务链。短路响应同样沿外层链回传,外层后置层仍可加工。常见短路:401、403、429、400。短路前已写入的扩展不影响响应,但下游不会读取。注意短路路径也要记录日志与指标,避免失败请求无观测。

原理流程

  1. 中间件前置校验请求。
  2. 不通过则构造错误响应。
  3. 不调用 next.run,直接返回响应。
  4. 响应沿外层链回传并记录观测。

代码或图示

use axum::{http::{Request, StatusCode}, middleware::{self, Next}, response::{IntoResponse, Response}, Router};

async fn guard<B>(req: Request<B>, next: Next<B>) -> Response {
    if req.headers().contains_key("x-token") {
        next.run(req).await
    } else {
        (StatusCode::UNAUTHORIZED, "no token").into_response()
    }
}

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .layer(middleware::from_fn(guard));

常见误区

  • 短路后忘记记录日志:失败请求在观测中消失。
  • 短路响应缺 CORS 头:跨域预检与错误响应都需补 CORS 头。

追问

  • 短路响应会经过路由匹配吗?答:不会进入业务 handler,但仍在层链中,外层层可见。
  • 如何统一短路错误格式?答:复用统一错误枚举的 IntoResponse,所有中间件失败分支共用。

04.4.3.2-075 限流键从客户端 IP 提取有什么前提与风险?

一句话结论

按 IP 限流需要服务以 into_make_service_with_connect_info::<SocketAddr>() 启动,ConnectInfo<SocketAddr> 才能取到对端地址;反向代理后真实 IP 需校验转发头,不能直接信任。

概念解释

匿名请求按 IP 计数最常见。前提是启动方式注入连接信息,否则 ConnectInfo 提取不到值。直连场景对端地址可信;反向代理后对端是代理 IP,真实客户端 IP 从 X-Forwarded-For 等头解析,且只在可信代理链路上取最右侧可信值。伪造头可绕过限流,风控需结合登录用户 ID。多出口 NAT 下同一 IP 可能对应大量用户,限流阈值要放宽。

原理流程

  1. 启动服务时声明 connect info 类型。
  2. 中间件提取 ConnectInfo<SocketAddr> 得到对端地址。
  3. 代理场景按可信链解析真实 IP。
  4. 以 IP 或用户 ID 作为限流键查询配额。

代码或图示

use axum::{extract::ConnectInfo, http::Request, middleware::{self, Next}, response::Response, Router};
use std::net::SocketAddr;

async fn by_ip<B>(
    ConnectInfo(addr): ConnectInfo<SocketAddr>,
    req: Request<B>,
    next: Next<B>,
) -> Response {
    let _ip = addr.ip();
    next.run(req).await
}

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .route_layer(middleware::from_fn(by_ip));
// 启动:into_make_service_with_connect_info::<SocketAddr>()

常见误区

  • 普通 into_make_service 启动却取 ConnectInfo:提取不到连接信息。
  • 直接信任 X-Forwarded-For 最左值:客户端可伪造,需按代理链解析。

追问

  • 登录用户限流用什么键?答:用扩展中的用户 ID 作为键,未登录回退 IP。
  • 多实例限流如何共享计数?答:内存限流只在单节点生效,跨节点用 Redis 等集中计数存储。

04.4.3.2-076 会话存储后端如何选型,内存与持久化后端有什么区别?

一句话结论

开发与单实例可用内存存储,生产多实例需 Redis 等持久化共享后端;会话数据存服务端,Cookie 只保存会话 ID,后端选型决定会话能否跨实例共享与重启保留。

概念解释

会话后端承担键值读写与过期管理。内存存储速度快但重启丢失、多实例不共享;Redis 类后端跨实例共享且可持久化。会话数据量、过期策略、序列化格式由后端与中间件配置。生产环境还要考虑会话 ID 轮换、注销清理与敏感字段加密。具体可用后端 crate 与配置项以 tower-sessions 当前版本文档为准。

原理流程

  1. 选择会话存储后端并初始化连接。
  2. 挂载会话层,配置 Cookie 选项。
  3. 请求加载会话数据,handler 读写字段。
  4. 响应前回写后端并刷新会话 Cookie。

代码或图示

// 依赖:tower-sessions 及所选后端 crate
// 内存后端仅用于开发;生产替换为 Redis 等持久化后端
use axum::{extract::Session, routing::get, Router};

async fn index(session: Session) -> String {
    session.get::<u64>("uid").map(|v| v.to_string()).unwrap_or_else(|| "anon".into())
}

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

常见误区

  • 生产用内存后端:重启登出、多实例会话不一致。
  • 会话中存大对象:后端存储与网络开销放大,只存必要标识。

追问

  • 会话过期在哪里配置?答:会话层与后端的过期/最大年龄选项,具体参数名以当前版本文档为准。
  • 会话与 JWT 如何配合?答:可在会话中保存令牌引用,主体校验仍按认证方案;对比在认证授权主题展开。

04.4.3.2-077 一个完整 AppState 通常包含哪些句柄,如何组织成可克隆结构?

一句话结论

典型 AppState 聚合数据库池、HTTP 客户端、配置、缓存与计数器等句柄,重资源包 Arc,结构体派生 Clone;字段按子系统分组,handler 只取所需分组。

概念解释

状态组织是工程结构问题:启动期构造各资源句柄,聚合进 AppState。数据库池与 HTTP 客户端本身多为可克隆共享句柄,配置与缓存按体积决定是否包 Arc。计数器用原子类型。结构体保持 Clone 派生,避免手写克隆复制重资源。新增资源先判断生命周期:应用级进 State,请求级进扩展。

原理流程

  1. 启动期初始化数据库、客户端、配置、缓存。
  2. 重资源包 Arc,按子系统分组字段。
  3. 派生 Clone 构造 AppState。
  4. with_state 注入路由,handler 分组取用。

代码或图示

use std::sync::Arc;
use std::sync::atomic::AtomicU64;

#[derive(Clone)]
struct Db { pool: Arc<DbPool> }
#[derive(Clone)]
struct Http { client: Arc<reqwest::Client> }
#[derive(Clone)]
struct Cfg { max_items: u32 }

#[derive(Clone)]
struct AppState {
    db: Db,
    http: Http,
    config: Cfg,
    hits: Arc<AtomicU64>,
}

struct DbPool;

常见误区

  • 所有字段平铺且无 Arc:克隆成本随并发放大。
  • 把请求级 DTO 塞进 AppState:生命周期不匹配。

追问

  • 资源初始化失败如何处理?答:启动期校验并快速失败,不要把未初始化句柄放入 State。
  • 状态字段过多如何拆分?答:按子系统拆子结构体,必要时拆成多个状态类型分别收窄。

04.4.3.2-078 测试中如何把 State 替换为内存替身?

一句话结论

把外部依赖抽象为 trait,State 持有 trait 对象或泛型句柄;测试构造内存替身注入 State,oneshot 验证行为,生产绑定真实实现。

概念解释

可测试性来自依赖反转:handler 面向仓库/客户端 trait 编程,State 持有实现句柄。测试替身不连真实数据库与外部 API,返回固定数据或记录调用。替身类型仍需满足 Clone + Send + Sync + 'static。状态注入点在路由构造函数,测试与生产走同一组装路径。替身失败场景也可模拟,覆盖错误分支。

原理流程

  1. 定义外部依赖 trait 与方法签名。
  2. 生产实现对接真实资源,测试实现为内存替身。
  3. State 持有 trait 句柄。
  4. 测试注入替身,oneshot 断言结果。

代码或图示

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

trait Greeter: Send + Sync { fn greet(&self) -> String; }

struct FakeGreeter;
impl Greeter for FakeGreeter { fn greet(&self) -> String { "fake".into() } }

#[derive(Clone)]
struct AppState { greeter: Arc<dyn Greeter> }

async fn hello(State(s): State<AppState>) -> String { s.greeter.greet() }

#[tokio::test]
async fn fake_injected() {
    let app = Router::new().route("/", get(hello))
        .with_state(AppState { greeter: Arc::new(FakeGreeter) });
    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, "fake");
}

常见误区

  • 测试直接连真实外部服务:用例不稳定且污染外部数据。
  • 替身未实现 trait 所需 Send/Sync:状态注入编译失败。

追问

  • 替身需要记录调用次数吗?答:验证交互时可在替身内部加原子计数器,断言调用次数与参数。
  • 异步 trait 方法怎么标注?答:按当前 Rust 版本用 async trait 或返回 boxed Future,约束 Send,具体写法以工具链为准。

04.4.3.2-079 多环境配置如何在同一份代码下注入不同值?

一句话结论

启动期按环境加载配置源(环境变量、配置文件),解析为同一 Config 结构注入 State;业务代码不区分环境,差异只体现在注入的配置值。

概念解释

开发、测试、生产配置不同,但路由与 handler 代码一致。配置在 main 启动阶段读取并校验,构造 AppState 后注入。敏感配置从环境或密钥管理读取,不写进代码库。配置缺失或非法在启动期报错,不延迟到请求期。测试可直接构造 Config 实例绕过配置源。

原理流程

  1. 启动期识别当前环境。
  2. 从对应配置源读取并反序列化 Config。
  3. 校验必填项与取值范围。
  4. 构造 AppState 注入路由。

代码或图示

use std::sync::Arc;

#[derive(Clone)]
struct Config { port: u16, db_url: String }

#[derive(Clone)]
struct AppState { config: Arc<Config> }

// 启动期:读取环境变量/配置文件 → 校验 → 构造 AppState
// let config = load_config()?;
// let state = AppState { config: Arc::new(config) };

常见误区

  • handler 内按环境分支写死逻辑:环境差异应收敛到配置值。
  • 配置文件提交真实密钥:敏感项走环境变量或密钥管理。

追问

  • 配置校验放在哪一层?答:启动期反序列化后集中校验,非法配置快速失败。
  • 多环境配置文件如何组织?答:按环境分文件,启动期选择加载,具体方案按工程约定。

04.4.3.2-080 状态生命周期与服务优雅退出时资源如何释放?

一句话结论

State 句柄随服务存活,进程退出时按 Arc 引用计数与 Drop 规则释放资源;连接池、客户端等需要在优雅停机时关闭,避免连接与任务被强制中断。

概念解释

State 不是全局静态变量,句柄在路由与服务实例间共享。优雅停机阶段停止接收新连接,等待在途请求完成,再关闭连接池与客户端。资源释放顺序由 Drop 实现保证,数据库池与 HTTP 客户端通常有关闭方法。State 内部缓存未落盘数据在退出时按需要持久化。测试与重启场景要验证资源清理。

原理流程

  1. 收到停机信号,服务停止 accept 新连接。
  2. 在途请求处理完成或达到宽限时间。
  3. 关闭数据库池、HTTP 客户端等资源。
  4. 句柄引用计数归零,剩余资源 Drop 释放。

代码或图示

// 优雅停机在启动与信号处理层完成,State 持有可关闭资源句柄
use std::sync::Arc;

struct Pool { closed: bool }
impl Pool {
    async fn close(self) { /* 归还连接、关闭句柄 */ }
}

#[derive(Clone)]
struct AppState { pool: Arc<Pool> }

常见误区

  • 依赖进程直接退出释放连接池:在途请求与连接被截断。
  • State 持有需要显式关闭的资源却不调用关闭方法:连接泄漏。

追问

  • 优雅停机宽限时间在哪里设?答:服务启动与信号处理配置中设置,超时后强制终止在途任务;具体 API 以当前版本为准。
  • 状态内缓存如何落盘?答:退出前按缓存策略刷盘,属于业务资源管理职责。

04.4.3.2-081 连接池放入 State 后,池大小、超时与健康检查如何配置?

一句话结论

池在启动期按并发规模配置最大连接数、获取连接超时与连接生命周期;State 只持有池句柄,池内部管理连接复用与回收,handler 不直接持有单连接。

概念解释

池大小影响并发与数据库压力:过大压垮数据库,过小排队等待。获取连接超时防止请求无限等待;连接空闲回收与健康检查剔除坏连接。配置值按数据库承载能力与接口 SLA 压测调整。handler 每次请求从池借连接,用完归还,不跨请求持有。池监控指标(等待数、空闲数)接入观测体系。

原理流程

  1. 启动期按配置创建连接池。
  2. 请求到达从池借连接,超时未获取则报错。
  3. 查询完成归还连接。
  4. 池后台回收空闲连接并剔除失效连接。

代码或图示

use std::sync::Arc;

struct PoolConfig { max_connections: u32, acquire_timeout_secs: u64 }

#[derive(Clone)]
struct AppState { pool: Arc<DbPool> }

struct DbPool;
// 池的具体配置方法以所选数据库驱动文档为准

常见误区

  • 池大小设成与 CPU 核数相同:数据库连接数要按数据库承载评估。
  • handler 长期持有连接:占用池连接,降低并发复用。

追问

  • 获取连接超时映射成什么响应?答:通常 503 或 500,按统一错误类型映射。
  • 待确认点是什么?答:所选驱动池的配置项名与默认值,验证方式为对应驱动 docs.rs 当前版本文档。

04.4.3.2-082 出站 HTTP 客户端入 State 时,超时与连接复用如何配置?

一句话结论

reqwest::Client 在启动期统一配置总超时、连接池大小与 keep-alive,放入 State 复用;每个出站请求不再新建客户端,连接与 DNS 缓存跨请求复用。

概念解释

客户端配置影响下游调用稳定性:连接超时限制建连,请求超时限制整体等待,连接池控制复用连接数。客户端句柄可克隆,State 持有一份即可。不同下游需要不同超时/认证时,可在 State 放多个客户端或客户端工厂。出站错误要映射成本服务错误响应,避免下游异常直接冒泡。

原理流程

  1. 启动期构造 Client,配置超时与连接池。
  2. Client 句柄放入 State。
  3. handler 复用 Client 发起出站请求。
  4. 底层 keep-alive 连接在多次调用间复用。

代码或图示

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

#[derive(Clone)]
struct AppState { http: reqwest::Client }

async fn call(State(s): State<AppState>) -> String {
    match s.http.get("https://example.com").send().await {
        Ok(_) => "ok".into(),
        Err(_) => "err".into(),
    }
}

let client = reqwest::Client::builder()
    .timeout(Duration::from_secs(5))
    .build()
    .unwrap();

let app = Router::new().route("/call", get(call))
    .with_state(AppState { http: client });

常见误区

  • 客户端不设超时:下游慢响应拖垮本服务并发。
  • 每请求新建 Client:连接与 DNS 缓存无法复用。

追问

  • 连接池大小在哪里配?答:reqwest Client builder 的连接池选项,具体方法名以 docs.rs/reqwest 当前版本为准。
  • 需要按下游区分超时怎么做?答:请求级可覆盖超时,或 State 持有多个预配置客户端。

04.4.3.2-083 把请求级可变数据放进 State 会出现什么串号表现?

一句话结论

当前请求才产生的数据(用户身份、请求参数、临时上下文)放进跨请求共享的 State,会被后续请求读到旧值或互相覆盖,表现为越权、串用户、统计错乱。

概念解释

State 生命周期是应用级,多请求并发共享。请求级数据随请求结束应销毁,放 State 后成为共享可变状态:后写覆盖先写,并发下读到不确定值。典型错误:把登录用户存 State 字段,下个请求读到上一个用户。正确归属:用户主体进 Extension,请求参数进提取器,共享资源进 State。排查串号问题先检查数据生命周期归属。

原理流程

  1. 请求 A 把临时值写入 State 字段。
  2. 请求 B 并发或随后覆盖同字段。
  3. 请求 A 后续读取时拿到 B 的值。
  4. 业务出现串号、越权或统计错误。

代码或图示

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

#[derive(Clone)]
struct AppState {
    // 错误示范:请求级用户标识不应放这里
    current_user: Arc<AtomicU64>,
}

async fn handler(State(_): State<AppState>) -> &'static str { "ok" }
// 正确做法:用户主体由鉴权层写入 Extension,handler 从 Extension 读取

常见误区

  • 图省事把当前用户挂 State:并发串号。
  • 用 State 做请求内缓存:请求结束应释放,扩展或局部变量才对。

追问

  • 如何确认某数据是请求级?答:判断是否每个请求不同、是否随响应结束失效;是则走扩展或参数。
  • 共享计数器放 State 为什么没问题?答:它本来就是跨请求聚合数据,语义与请求级身份不同。

04.4.3.2-084 子路由提前 with_state 后,外层再加层会影响状态可见性吗?

一句话结论

子树提前收窄为 Router<()> 后,外层层无法再向它注入原 State;外层层若需要状态,应使用自己的状态句柄或从扩展读取,子树 handler 也取不到父状态。

概念解释

with_state 是构建期收窄动作,先收窄的子树与父状态脱钩。外层后挂的层包裹整体服务,但不能改变子树已固化的状态类型。需要父子共享资源时,在收窄前把句柄放入子状态,或通过扩展向下传递。排查「外层层读不到状态」先确认子树收窄时机。层本身持有的配置在挂载时固化。

原理流程

  1. 子树构造并 with_state 收窄为 Router<()>。
  2. 父树挂载收窄后的子路由。
  3. 外层层包裹整体服务。
  4. 子树内只能访问收窄时注入的状态。

代码或图示

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

#[derive(Clone)]
struct MainState { label: String }
#[derive(Clone)]
struct SubState { limit: u32 }

async fn sub(State(s): State<SubState>) -> String { s.limit.to_string() }

fn sub_router() -> Router<()> {
    Router::new().route("/sub", get(sub))
        .with_state(SubState { limit: 5 })
}

let app = Router::new().nest("/api", sub_router())
    .with_state(MainState { label: "main".into() });

常见误区

  • 子树收窄后又在 handler 取 MainState:类型已不可用。
  • 期望外层层动态改变子树状态:构建期固化,运行期不改类型。

追问

  • 子树需要主状态句柄怎么办?答:收窄前把主句柄克隆进 SubState 字段,或经 Extension 传递。
  • 外层层能读子树写入的扩展吗?答:响应回传时可读扩展,但请求扩展主要向下游传递。

04.4.3.2-085 层在 into_make_service 阶段何时完成包裹?

一句话结论

Router 上记录的层序列在转换为 Service/MakeService 时逐层包裹完成;with_state 收窄后 into_make_service 触发服务构造,层在此时绑定内层服务。

概念解释

layer 调用只是把层加入序列,真正包裹发生在 Router 转 Service 时。层持有配置,服务实例在工厂产出时克隆。理解时序有助于排查:状态注入与层包裹都在启动构建期完成,运行期不再重组层链。测试 into_service 同样触发包裹。层顺序在序列中固定,运行期不动态调整。

原理流程

  1. 组装 Router 并记录层序列。
  2. with_state 收窄状态。
  3. into_make_service/into_service 按序列包裹出服务链。
  4. 工厂克隆服务实例处理连接。

代码或图示

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

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

// 包裹在 into_make_service / into_service 时完成
let make_svc = app.into_make_service();

常见误区

  • 以为 layer 调用立即包裹内层:序列先记录,转换时才组装。
  • 运行期动态增删层:层链构建期固定,动态逻辑需自定义层判断。

追问

  • 测试 oneshot 会触发层包裹吗?答:会,into_service 同样完成包裹,层逻辑在测试中生效。
  • 层序列顺序在哪个阶段确定?答:layer/route_layer 调用顺序确定,转换时按序包裹。

04.4.3.2-086 中间件如何写单元测试,oneshot 如何验证前置、后置与短路?

一句话结论

把带中间件的 Router 转 Service,oneshot 发请求,断言状态码、响应头与 body;前置逻辑看请求侧效果,后置逻辑看响应头/状态,短路场景断言未进入 handler。

概念解释

中间件测试走黑盒请求视角:构造触发前置条件的请求,验证层行为。短路用例确认响应直接返回且 handler 未执行;后置用例检查响应被加工。需要观测「是否调用内层」时,在 handler 写入标记(响应体或扩展)。带状态中间件测试注入测试 State。层顺序问题可在各层打印日志辅助验证。

原理流程

  1. 构造带目标中间件的 Router 与测试状态。
  2. into_service 后 oneshot 发送请求。
  3. 断言响应状态码、头、body。
  4. 短路用例验证 handler 标记未出现。

代码或图示

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

#[tokio::test]
async fn middleware_short_circuit() {
    let app = Router::new()
        .route("/", get(|| async { "handler-ran" }));
    // 挂载鉴权类中间件后,无凭证请求应短路
    let resp = app.into_service()
        .oneshot(Request::builder().uri("/").body(Body::empty()).unwrap())
        .await.unwrap();
    assert_ne!(resp.status(), StatusCode::INTERNAL_SERVER_ERROR);
}

常见误区

  • 只测放行路径,不测短路:失败分支无覆盖。
  • 直接调用中间件内部函数:应通过请求链路验证层装配。

追问

  • 如何断言 handler 未执行?答:handler 响应带唯一标记,短路响应不含该标记即证明未进入。
  • 中间件写的扩展如何断言?答:在测试 handler 中读取扩展并放进响应体,间接验证写入。

04.4.3.2-087 从中间件视角如何理解 poll_ready 背压模型?

一句话结论

调用内层前先经 poll_ready 确认服务可接收请求,未就绪则等待通知;限流、并发限制等层利用就绪信号控制并发,而不是无限排队请求。

概念解释

tower 服务模型分就绪检查与调用两步。中间件包裹内层时通常透传 poll_ready;自定义并发限制层可在未就绪时让调用方等待。背压向上游传导:内层忙时外层不接收新请求,避免内存堆积。axum handler 层链最终落到该模型。理解 poll_ready 有助于看懂限流器与并发信号量的实现位置。

原理流程

  1. 调用方先轮询服务 poll_ready。
  2. 未就绪则注册等待,被唤醒后重试。
  3. 就绪后调用 call 传入请求。
  4. 中间件把就绪状态透传或按自身容量判断。

代码或图示

use tower::Service;
# struct S;
# impl Service<axum::http::Request<axum::body::Body>> for S {
#     type Response = axum::response::Response;
#     type Error = std::convert::Infallible;
#     type Future = std::future::Ready<Result<Self::Response, Self::Error>>;
#     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: axum::http::Request<axum::body::Body>) -> Self::Future { todo!() }
# }

常见误区

  • 忽略 poll_ready 直接并发 call:背压层无法控制准入。
  • 自定义层不透传就绪状态:内层背压信号丢失。

追问

  • 限流器与 poll_ready 是什么关系?答:限流可在 call 前检查配额短路,也可基于就绪信号控制并发,两种实现位置不同。
  • 该模型与 axum handler 直接关系?答:handler 适配器最终包装为 Service,路由匹配后调用其 call。

04.4.3.2-088 自定义 Layer 返回的服务类型如何标注?

一句话结论

Layer::layer 的关联类型 Service 指向包裹服务结构体;服务结构体保存内层句柄并实现 Service trait,泛型按内层服务类型参数化,返回类型在关联类型中声明。

概念解释

Layer 实现中 type Service = MyService<S>,layer 方法把内层 S 传入构造。MyService<S> 持有 S,自身 Service 实现把请求转发给内层。若层配置需要保存,Layer 结构体持有配置,服务结构体克隆配置。类型标注要保证服务可克隆、Future Send。简单场景优先 from_fn,避免手写复杂类型。

原理流程

  1. 定义层结构体持有配置。
  2. 定义包裹服务结构体,字段为内层与配置。
  3. Layer::layer 构造包裹服务,关联类型指定服务类型。
  4. 服务 Service 实现转发内层。

代码或图示

use tower::Layer;

# #[derive(Clone)]
# struct MyLayer;
# #[derive(Clone)]
# struct Wrap<S> { inner: S };
#
impl<S> Layer<S> for MyLayer {
    type Service = Wrap<S>;
    fn layer(&self, inner: S) -> Self::Service {
        Wrap { inner }
    }
}

常见误区

  • 关联类型写成内层原始类型:包裹逻辑无处安放。
  • 服务结构体不 Clone:服务工厂克隆约束失败。

追问

  • 多层嵌套时服务类型如何组合?答:每层包裹生成新服务类型,外层 Layer 关联类型指向自己的包裹服务,内层类型递归组合。
  • 层需要状态句柄放哪?答:Layer 结构体保存句柄克隆,layer 时传入包裹服务。

04.4.3.2-089 典型中间件链的拓扑与请求/响应流向是什么样的?

一句话结论

层链为洋葱拓扑:请求从最外层向内逐层进入 handler,响应从内层向外逐层返回;每层可在前置与后置两个时机加工,短路响应不进入内层。

概念解释

拓扑由挂载顺序决定:先挂为外,后挂为内。观测类层在最外,覆盖全部请求;安全类在业务前;响应加工类靠近内层。理解画图标注法:左侧请求入口,右侧 handler,箭头双向。排查层行为时按拓扑定位前置/后置时机。短路响应只经过其外层与自身,不进入未到达的内层。

原理流程

  1. 按挂载顺序确定外层到内层序列。
  2. 请求前置逻辑逐层向内。
  3. handler 产出响应。
  4. 响应后置逻辑逐层向外回传。

代码或图示

        ┌──────── Trace/RequestId ────────┐
请求 →  │  前置 → CORS → Auth → Compression → handler
        │  后置 ←───────────────────────────── 响应
        └──────────────────────────────────┘

常见误区

  • 把层链当成单向管道:响应也沿链回传,后置逻辑不可忽略。
  • 短路响应仍画穿全部内层:未调用 next 的层之后不执行。

追问

  • 如何画出实际挂载顺序?答:从根 Router 到子路由逐层列出 layer/route_layer 调用,先挂者在外。
  • 子树层在拓扑哪个位置?答:父层之外层先经过,子树层在父层内部、handler 之前。

04.4.3.2-090 层与状态配置能否热更新,边界在哪里?

一句话结论

层配置在构建期固化,运行期不自动热更新;需要动态调整的策略(限流阈值、开关)放入 State 可变结构,层每次请求读取最新值,重资源层本身不在线重建。

概念解释

层序列与层持有的静态配置在启动构建期确定。动态策略适合放 State:限流阈值、功能开关、白名单由后台任务更新,层前置读取当前值。连接池大小、客户端连接策略、CORS 来源集等重建成本高的配置,通常重启生效。热更新要校验新值并保证进行中请求沿用旧快照。

原理流程

  1. 区分静态层配置与动态策略。
  2. 动态策略放入 State 线程安全结构。
  3. 后台任务校验并更新策略值。
  4. 层每次请求读取当前策略,重资源配置重启生效。

代码或图示

use std::sync::Arc;
use std::sync::atomic::AtomicU32;

#[derive(Clone)]
struct AppState {
    rate_limit: Arc<AtomicU32>,
}
// 中间件前置读取 rate_limit 当前值,而不是把阈值固化在层里

常见误区

  • 期望层挂载后还能动态增删:层链构建期固定。
  • 热更新无校验:非法阈值进入运行期。

追问

  • 动态配置更新如何保证一致性?答:单字段原子更新,复合配置用快照结构整体替换,进行中请求沿用快照。
  • 哪些层适合读动态 State?答:限流、鉴权开关、功能标志;压缩、CORS 编码集等静态配置为主。

04.4.3.2-091 鉴权中间件与 handler 内权限校验如何分工,避免重复?

一句话结论

中间件负责认证(你是谁)与粗粒度放行,handler/服务层负责资源级授权(你能否操作这条数据);主体由中间件写入扩展,下游复用,不重复解析凭证。

概念解释

认证校验令牌/会话有效性,得到用户主体;授权判断主体对具体资源的权限。中间件统一做认证,避免每个 handler 解析凭证;资源归属、角色判定下沉服务层,因为需要业务数据。中间件把主体写入扩展,handler 读取主体再查资源权限。两层职责清晰后不会重复解析令牌,也不会把资源级判断硬塞进通用中间件。

原理流程

  1. 鉴权中间件校验凭证,主体写入扩展。
  2. 无凭证/失效返回 401。
  3. handler 取主体,加载资源并做归属/角色校验。
  4. 权限不足返回 403。

代码或图示

use axum::Extension;

#[derive(Clone)]
struct AuthUser { id: u64, role: String }

async fn handler(Extension(user): Extension<AuthUser>) -> String {
    // 资源级授权在业务层判断:user.role 与资源归属
    format!("user={} role={}", user.id, user.role)
}

常见误区

  • 中间件做资源级权限:拿不到业务数据,规则僵化。
  • 每个 handler 重复解析令牌:应中间件统一解析后放扩展。

追问

  • 粗粒度路由级授权放哪里?答:按路由/模块挂中间件校验角色白名单,细粒度仍在服务层。
  • 401 与 403 在哪一层产生?答:认证失败 401 在中间件,授权失败 403 在 handler 或服务层。

04.4.3.2-092 限流窗口与算法应放在中间件还是服务层?

一句话结论

配额检查与窗口计数放中间件层,按请求统一拦截;业务侧只感知被限流后的错误响应。多实例共享的计数存储由中间件对接,算法选型按防护目标确定。

概念解释

限流是跨切面关注点,天然属于层链:请求进入业务前检查配额。固定窗口、滑动窗口、令牌桶各有取舍,计数器存内存或 Redis。中间件提取限流键、查询配额、放行或 429。业务服务层不关心限流实现,只处理正常请求。限流阈值与键策略属于配置,放 State 便于调整。

原理流程

  1. 中间件提取限流键。
  2. 查询/更新窗口计数。
  3. 未超限调用 next.run。
  4. 超限返回 429 与重试信息。

代码或图示

use axum::{http::Request, middleware::{self, Next}, response::Response, Router};

async fn limiter<B>(req: Request<B>, next: Next<B>) -> Response {
    // 配额检查由限流器完成;业务 handler 不感知计数
    next.run(req).await
}

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .route_layer(middleware::from_fn(limiter));

常见误区

  • 在每个 handler 里重复写限流判断:逻辑分散且易漏。
  • 限流计数放业务数据库请求路径:放大业务链路压力。

追问

  • 令牌桶与滑动窗口怎么选?答:允许突发选令牌桶,平滑速率选滑动窗口;具体取舍在高并发主题展开。
  • 限流状态丢失怎么办?答:内存计数重启清零,关键配额用持久化存储。

04.4.3.2-093 中间件改写请求头后如何保证下游拿到新值?

一句话结论

中间件在调用 next.run 前通过 headers_mut() 改写请求头,改写后的请求对象传入内层;下游读到的是改写后的值,原始头如需保留应先读出再改。

概念解释

请求由 Parts 与 Body 组成,头在 Parts 中可变。前置层补充代理信息、追踪头、内部标记后,把修改后的请求继续向下。下游 handler 与后续层看到的是最新头。需要原始值时,层内先读取保存,不要假设下游还能取到旧值。响应头改写发生在后置阶段,与请求头改写分属两侧。

原理流程

  1. 中间件读取请求头原始值。
  2. headers_mut() 插入或修改头。
  3. 改写后的请求传给 next.run。
  4. 下游读取新头。

代码或图示

use axum::{http::Request, middleware::{self, Next}, response::Response, Router};

async fn add<B>(mut req: Request<B>, next: Next<B>) -> Response {
    req.headers_mut().insert("x-processed", "1".parse().unwrap());
    next.run(req).await
}

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .layer(middleware::from_fn(add));

常见误区

  • 拷贝请求后改副本却传原请求:下游看不到改动。
  • 后置阶段改请求头:请求已进内层,无效。

追问

  • 如何删除请求头?答:headers_mut().remove(name),下游后续读不到该头。
  • 头值需要编码处理吗?答:HeaderValue 只接受合法字节/UTF-8,非法值按类型约束构造。

04.4.3.2-094 中间件改写请求 URI 或路径前缀有哪些场景?

一句话结论

反向代理、前缀剥离、内部路径映射场景在中间件改写 URI;改写后注意 Uri 与 OriginalUri 的区别,路由匹配使用改写后的路径,原始路径用 OriginalUri 读取。

概念解释

外层网关转发后可能需要剥离前缀再交业务路由;或把外部路径映射到内部路径。中间件改写请求 URI 后,内层匹配树在新路径上查找。原始请求 URI 保留在 OriginalUri,日志应记录原始值。改写 URI 属于较底层操作,优先用 nest 前缀挂载解决结构问题,确需动态改写再在层处理。

原理流程

  1. 中间件读取原始 URI。
  2. 按规则计算新路径。
  3. 重建请求 URI 后传给内层。
  4. 内层在新路径上匹配,原始 URI 经提取器读取。

代码或图示

use axum::{http::Request, middleware::{self, Next}, response::Response, Router, http::Uri};

async fn rewrite<B>(mut req: Request<B>, next: Next<B>) -> Response {
    let new_path = req.uri().path().replacen("/proxy", "", 1);
    let uri = Uri::builder()
        .path_and_query(new_path)
        .build()
        .unwrap();
    *req.uri_mut() = uri;
    next.run(req).await
}

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .layer(middleware::from_fn(rewrite));

常见误区

  • 改写后日志仍用 Uri:记录的是内部路径,应用 OriginalUri。
  • 只改路径不保留查询串:重建 URI 时丢失查询参数。

追问

  • 前缀剥离为什么不直接用 nest?答:静态前缀用 nest 更清晰;动态规则或外部代理改写才在层处理。
  • 待确认点是什么?答:当前版本 URI 重建方式与 OriginalUri 保留行为,验证方式为 docs.rs/axum/latest 与改写用例。

04.4.3.2-095 State、Extension 与层上下文三者如何综合选型?

一句话结论

应用级共享资源进 State,单次请求上下文进 Extension,跨切面处理逻辑进层;层负责产生上下文写入扩展,handler 通过 State 与 Extension 取用,职责按生命周期与处理位置划分。

概念解释

三者配合形成完整上下文模型:State 启动期注入、跨请求共享;Extension 请求期由层写入、随请求消亡;层是处理逻辑的挂载位置,本身不持有业务数据(除配置句柄)。选型先问数据生命周期,再问处理发生在哪一层。常见组合:鉴权层从凭证生成主体写 Extension,handler 取 State 中的仓库与 Extension 中的主体。

原理流程

  1. 数据分类:应用级 / 请求级 / 处理逻辑。
  2. 应用级资源构造句柄进 State。
  3. 层在请求链路生成请求上下文写 Extension。
  4. handler 分别取用 State 与 Extension。

代码或图示

应用级资源(池/客户端/配置) → State(with_state 注入,跨请求共享)
请求级上下文(主体/租户/请求ID) → Extension(层写入,请求结束释放)
跨切面逻辑(日志/鉴权/限流/压缩) → Layer(挂全局或路由层)

常见误区

  • 请求级数据进 State 导致串号;重资源进 Extension 导致重复构造。
  • 把业务处理逻辑塞进层:层只做跨切面,业务下沉 handler/服务层。

追问

  • 层配置属于哪一类?答:层持有的静态配置随服务克隆,动态策略放 State 读取。
  • 三者都要求线程安全吗?答:跨线程传递共享都要求 Send,共享状态另需 Sync,Extension 值按提取约束可克隆。

04.4.3.2-096 中间件读取或包装响应 body 有哪些注意事项?

一句话结论

响应 body 是流,中间件需要读取时先聚合字节再重建响应;全量聚合有内存成本,流式响应不应缓冲,包装 body 流要保持透传与错误传播。

概念解释

后置层常见需求:记录响应体、替换错误体、压缩 body。聚合 body 会缓冲整个响应,大响应或流式接口不适用。包装 body 流可在不缓冲的情况下加工字节,但实现复杂。多数场景只改状态码与头,不动 body。读取响应体做审计时评估体积上限与敏感信息。

原理流程

  1. 内层返回响应。
  2. 需要时聚合 body 字节。
  3. 校验/加工后用字节重建 Body。
  4. 加工后的响应回传。

代码或图示

use axum::{http::Request, middleware::{self, Next}, response::Response, body::Body};

async fn inspect<B>(req: Request<B>, next: Next<B>) -> Response {
    let resp = next.run(req).await;
    // 按需读取 body:let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX).await;
    resp
}

常见误区

  • 对所有响应聚合 body:大响应内存膨胀。
  • 读取 body 后不重建响应:下游/客户端收到空 body。

追问

  • 压缩层如何处理 body?答:在流上包装压缩编码,不全量缓冲;具体实现见 tower-http 压缩层。
  • 响应体审计如何避免泄露敏感信息?答:按白名单记录字段或脱敏,不全量落日志。

04.4.3.2-097 日志、鉴权、限流、压缩、超时分别应归属哪一层?

一句话结论

日志追踪与请求 ID 归最外层观测层;CORS、鉴权、限流、超时归业务前安全资源层;压缩归响应加工内层;静态兜底与业务路由各自配置专属层。

概念解释

关注点分层决定挂载点:观测需要覆盖全链路,挂最外;安全校验要在业务前拦截;压缩靠近响应侧;超时保护资源链路。各层职责单一,不混合多个关注点。挂载范围按作用域选全局层或路由层。分层清晰后新增关注点知道挂在哪一层,不污染 handler。

原理流程

  1. 列出跨切面关注点及其作用范围。
  2. 观测类挂全局最外层。
  3. 安全与资源保护类挂业务前层。
  4. 响应加工类挂靠近路由的内层。

代码或图示

外层:RequestId / Trace(观测全链路)
中层:CORS / CatchPanic / Timeout / RateLimit / Auth
内层:Compression(响应加工)
路由:handler

常见误区

  • 把压缩放鉴权前:未鉴权响应也被压缩。
  • 日志层挂路由内层:短路与兜底请求记录不到。

追问

  • 哪个关注点可以放 handler 内?答:业务级参数校验、资源授权不属于跨切面,放 handler/服务层。
  • 层职责过厚怎么拆?答:按关注点拆成多个层,每层单一职责,顺序按推荐链排列。

04.4.3.2-098 中间件内部发生 panic 如何被上层捕获与传播?

一句话结论

中间件 Future 内 panic 沿服务链向上传播,由外层 CatchPanicLayer 兜底转成错误响应;未被捕获时按运行时 panic 策略处理,中间件自身不应依赖 panic 表达可预期错误。

概念解释

层与 handler 同处于异步任务,panic 在 Future 执行中发生。CatchPanicLayer 包裹内层可捕获其范围内 panic。中间件前置/后置逻辑 panic 同样会被外层 panic 层捕获。可预期的校验失败返回短路响应,不用 panic。层内状态不变量被 panic 破坏后,资源一致性需自行评估。panic 信息对外响应脱敏。

原理流程

  1. 中间件执行前置/后置逻辑。
  2. 发生 panic,Future 终止。
  3. 外层 panic 层捕获并转换错误响应。
  4. 未捕获则按运行时策略处理。

代码或图示

use axum::{routing::get, Router};
use tower_http::catch_panic::CatchPanicLayer;

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

常见误区

  • 中间件用 panic 表示校验失败:应返回短路错误响应。
  • 以为 panic 后层内变量状态仍一致:panic 中途退出,不变量可能被破坏。

追问

  • 自定义层如何捕获内层 panic?答:可在层内包裹 Future 做 catch panic,或依赖外层 CatchPanicLayer;实现方式以 tower 模型为准。
  • panic 栈信息进入日志吗?答:由 panic hook 与日志配置记录,对外响应不输出内部栈。

04.4.3.2-099 版本敏感的 tower/tower-http API 如何核对而不编造?

一句话结论

层名、配置方法、feature 名与默认阈值以 docs.rs/tower-http 与 docs.rs/tower 当前版本为准;不确定处标注「待确认」并写明验证步骤,不在文档里写死未核实的变体与默认值。

概念解释

tower-http 迭代较快,层配置方法、编码 feature、拒绝状态码映射可能跨版本变化。工程核对流程:先查 docs.rs 对应层条目,再写最小用例编译运行观察行为。Cargo 版本写宽松 semver,锁定以 Cargo.lock 为准。题库与代码中无法确认的项标注验证点:文档地址、用例步骤、预期观察结果。

原理流程

  1. 识别版本敏感点:层 API、feature、默认值、状态码。
  2. 打开 docs.rs/tower-http/latest 对应层页面核对签名。
  3. 最小用例编译运行,打印实际行为。
  4. 未确认项标注待确认与验证方式。

代码或图示

待确认示例:
- 验证对象:CompressionLayer 支持的编码与对应 feature
- 验证方式:docs.rs/tower-http/latest 查 compression 模块,Cargo.toml 开启 feature 后编译
- 版本表述:以 docs.rs 当前版本为准,不写死次版本号

常见误区

  • 凭记忆写配置方法名或默认字节数:版本升级后与实际不符。
  • 把待确认行为写成确定结论进入面试答案。

追问

  • 如何确认 feature 真实存在?答:查 crate 文档 feature 列表与 Cargo.toml [features],cargo tree 核对实际依赖。
  • axum 与 tower-http 版本兼容如何确认?答:以 axum 文档声明的 tower/tower-http 依赖范围与 workspace 锁定为准。

04.4.3.2-100 状态与中间件问题的综合排查清单是什么?

一句话结论

按「状态注入与类型 → 层挂载范围与顺序 → 扩展读写时机 → 短路与超时限制 → 线程安全约束」逐层定位:先确认状态是否可取,再确认层是否覆盖、按什么顺序执行,最后检查并发与资源边界。

概念解释

综合排错把本主题各题串成链路:State 取不到先查 with_state 与收窄类型;层没生效查挂载范围与顺序;扩展读不到查写入时机与类型;超时/429/413 查对应层配置;编译报错查 Send/Sync 与参数约束。每一层都能用 oneshot 最小复现。线上问题先还原请求样例,区分是状态、层顺序还是资源限制问题。

原理流程

  1. 状态码与现象分类:取不到状态、层未执行、扩展缺失、超时/限流/超限。
  2. 核对 with_state 类型、子树收窄时机。
  3. 核对层挂载点(全局/路由/子树)与外层到内层顺序。
  4. 核对扩展写入位置先于读取,检查线程安全与资源限制配置。

代码或图示

排查顺序:
1. State 取不到 → with_state、收窄类型、字段归属
2. 层未生效 → layer / route_layer 作用范围、挂载层级
3. 顺序不符 → 外层到内层包裹方向、重复加层
4. Extension 缺失 → 写入时机、类型键、请求是否被重建
5. 401/403/429/413/超时 → 鉴权、限流、body 限制、TimeoutLayer 配置
6. 编译报错 → Send/Sync/'static、提取器位置、body 传递

常见误区

  • 跳过状态类型核对直接怀疑层逻辑:子树收窄后状态不可见是常见根因。
  • 线上凭日志猜层顺序:先在测试用例复现同一样请求,逐层剥离定位。

追问

  • 路由与提取器相关问题在哪继续查?答:路径匹配、提取器选型与拒绝见 04.4.3.1 路由与提取器;错误统一与流式通信见 04.4.3.3。
  • 如何建立可复用最小复现?答:抽路由构造函数,注入测试 State,oneshot 发送问题请求,按清单逐层剥离层与子路由。