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

04.4.4.2 中间件与Actor模型

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

04.4.4.2-001 actix-web 中间件在请求处理链中的定位是什么?

一句话结论

中间件是包裹在最终路由 service 外层的一层或多层 service,可在请求进入 handler 之前预处理、在响应返回之后后处理,也可以直接短路返回响应而不调用下游。

概念解释

actix-web 的请求处理是一条 service 链:最外层是 App 级中间件,向内依次是 Scope、Resource 级中间件,最内层是路由匹配后的 handler。每个中间件拿到一个 ServiceRequest,决定是放行给下一层还是自己构造 ServiceResponse。中间件适合做横切关注点:日志、鉴权、CORS、压缩、响应头补全、限流等。

原理流程

  1. App::new().wrap(Mw) 在构建期把中间件包进 service 链。
  2. 请求到达时从最外层中间件开始依次向内传递。
  3. 某层调用下一层的 call,等待其返回响应。
  4. 响应沿链向外逐层经过后置处理。
  5. 任一层都可以提前返回 ServiceResponse 或 Error 终止链路。

代码或图示

use actix_web::{App, middleware::from_fn, web, HttpResponse};

async fn mw(req: actix_web::dev::ServiceRequest,
            next: actix_web::middleware::Next<impl actix_web::body::MessageBody>)
    -> Result<actix_web::dev::ServiceResponse<impl actix_web::body::MessageBody>, actix_web::Error>
{
    let res = next.call(req).await?;
    Ok(res)
}

let app = App::new().wrap(from_fn(mw)).route("/", web::get().to(|| async { HttpResponse::Ok() }));

常见误区

  • 把中间件当成 handler 里的公共函数调用:中间件是链路上的独立 service,不是在 handler 内部顺序执行的代码。
  • 以为中间件只能改响应:请求头、路径、扩展数据同样可以在前置阶段修改。

追问

  • 中间件与提取器的分工?答:提取器只在 handler 参数构造阶段读取请求片段,不能拦截整条链路;中间件在链路上层,可以短路与改写响应。
  • 横切逻辑写在中间件还是 handler 基类?答:跨路由复用、需要在 handler 之前或之后执行的写中间件;只服务于单个 handler 业务逻辑的留在 handler。

04.4.4.2-002 Transform 与 Service 两个 trait 各自承担什么职责?

一句话结论

Transform 是中间件的构建器,负责把下一层 service 包装成一个新的中间件 service;Service 才是真正处理请求的异步操作单元,Transform::new_transform 产出 Service 实例。

概念解释

actix-web 的复杂中间件由一对类型组成:实现 Transform<S, ServiceRequest> 的外层类型通常持有配置,实现 Service<ServiceRequest> 的内层类型持有被包装的 service: S。这种 Builder 与实例分离的设计让同一个中间件配置可以为每个 worker 链路上分别构造实例,配置在构造期共享,运行期状态在实例内隔离。

原理流程

  1. App 构建时调用 Transform::new_transform(service),传入下一层 service。
  2. new_transform 返回 Future<Result<Self::Transform, Self::InitError>>。
  3. 产出的中间件 Service 在 call 中决定何时调用 self.service.call(req)。
  4. 请求响应结果再由中间件 Service 加工后返回。
  5. 内置中间件(Logger、DefaultHeaders 等)全部遵循这一 Builder 加实例的模式。

代码或图示

use actix_web::dev::{Service, ServiceRequest, ServiceResponse, Transform};
use actix_web::{Error, web};
use std::future::{ready, Ready, Future};
use std::pin::Pin;

pub struct SayHi;

impl<S, B> Transform<S, ServiceRequest> for SayHi
where
    S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error>,
    S::Future: 'static, B: 'static,
{
    type Response = ServiceResponse<B>;
    type Error = Error;
    type InitError = ();
    type Transform = SayHiMw<S>;
    type Future = Ready<Result<Self::Transform, Self::InitError>>;

    fn new_transform(&self, service: S) -> Self::Future {
        ready(Ok(SayHiMw { service }))
    }
}

pub struct SayHiMw<S> { service: S }

常见误区

  • 把两个 trait 混在一个类型里实现:虽然可行,但运行期状态会和配置耦合,多 worker 下难以隔离。
  • 以为 Transform 直接处理请求:真正的 call 写在 Service 实现上。

追问

  • Transform::InitError 用在哪?答:构造期失败(如配置非法)时返回,启动阶段即可暴露,而不是等到请求到来。
  • 为什么 new_transform 返回 Future 而不是同步值?答:为支持需要异步初始化的中间件(如预热外部资源),与 service 构造链路保持一致。

04.4.4.2-003 Transform 的 S 泛型与 B 泛型分别表示什么?

一句话结论

S 是被包装的下一层 service 类型,B 是下一层响应体的 body 类型;中间件应尽量对 B 保持泛型,只在确实需要消费或替换 body 时才固定具体类型。

概念解释

Transform<S, ServiceRequest> 中 S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error>,S 代表链路里紧邻的内层 service。B 是该 service 返回的响应体类型,可能是 BoxBody、流式 body、压缩 body 等。对 B 泛型化可以让中间件叠加在任意 body 类型之上,避免把下游 body 类型钉死。

原理流程

  1. 声明 impl<S, B> Transform<S, ServiceRequest> for Mw。
  2. 约束 S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error>。
  3. 中间件 Service 的 Response 保持 ServiceResponse<B>,不改动 body 类型。
  4. 若需要改写 body(如压缩、注入内容),才把 B 替换为新的 body 类型。
  5. 编译期由 trait 约束检查链路类型是否衔接。

代码或图示

impl<S, B> Service<ServiceRequest> for SayHiMw<S>
where
    S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error>,
    S::Future: 'static, B: 'static,
{
    type Response = ServiceResponse<B>;
    type Error = Error;
    type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;

    actix_web::dev::forward_ready!(service);

    fn call(&self, req: ServiceRequest) -> Self::Future {
        let fut = self.service.call(req);
        Box::pin(async move { fut.await })
    }
}

常见误区

  • 把 B 写成具体的 BoxBody:导致下游返回其它 body 类型时无法叠加该中间件。
  • 在不需要读取 body 的中间件里强行消费 body:body 只能读一次,消费后下游拿不到。

追问

  • 中间件替换 body 类型后 Response 关联类型怎么写?答:把 type Response = ServiceResponse<NewBody>,并在 call 中构造新的 ServiceResponse。
  • MessageBody trait 起什么作用?答:抽象响应体的帧读取与长度,中间件泛型约束通常要求 B: MessageBody + 'static。

04.4.4.2-004 Service trait 的 call 与 ready 以及 forward_ready! 宏如何配合?

一句话结论

Service::call 处理请求,Service::poll_ready 表达当前是否可接收请求;forward_ready! 宏把 ready 状态直接转发给内层 service,避免手写转发逻辑。

概念解释

actix-service 的 Service trait 包含 poll_ready 与 call 两个方法:调度器先通过 poll_ready 确认 service 就绪,再调用 call。绝大多数透传型中间件自身没有独立的就绪状态,直接复用内层 service 的就绪状态即可,forward_ready!(service) 就是生成这段转发代码的宏。

原理流程

  1. 调度器调用外层 service 的 poll_ready。
  2. forward_ready! 展开为转发到 self.service.poll_ready。
  3. 内层 service 就绪后,调度器调用外层 call。
  4. 外层 call 再把请求交给内层 call。
  5. 若中间件自身有容量限制(如信号量),则不转发,在 poll_ready 中返回未就绪实现背压。

代码或图示

impl<S, B> Service<ServiceRequest> for Mw<S>
where S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error>,
      S::Future: 'static, B: 'static,
{
    type Response = ServiceResponse<B>;
    type Error = Error;
    type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;

    actix_web::dev::forward_ready!(service);

    fn call(&self, req: ServiceRequest) -> Self::Future {
        Box::pin(async move { self.service.call(req).await })
    }
}

常见误区

  • 只实现 call 忽略 poll_ready:trait 有默认实现,但默认行为可能不符合内层 service 的真实就绪语义。
  • 在 call 里做背压判断:背压应放在 poll_ready,call 假设已经通过就绪检查。

追问

  • 带并发上限的中间件如何实现就绪状态?答:在 poll_ready 中检查占用计数,未达上限时注册唤醒并返回就绪,否则返回未就绪。
  • Service::Future 与 call 返回的 Future 有何关系?答:Future 是关联类型,call 返回该类型的实例,输出为 Result<Response, Error>。

04.4.4.2-005 wrap 与 wrap_fn 两种注册方式有何区别?

一句话结论

wrap 接收实现 Transform 的中间件类型(复杂中间件),wrap_fn 接收一个异步函数(简单中间件),二者最终都进入同一条 service 链,注册顺序规则一致。

概念解释

App::wrap(mw) 要求 mw: Transform<S, Req>,适合需要持有配置、拆分 Builder 与实例的复杂中间件。App::wrap_fn(f) 把一个签名为 async fn(ServiceRequest, Next) -> Result<ServiceResponse, Error> 的函数包装成中间件,适合用少量代码完成预处理与后处理,无需手写两个 trait。

原理流程

  1. 选择横切逻辑复杂度:单段函数逻辑用 wrap_fn,需要构造期状态或泛型 body 处理用 wrap。
  2. wrap 传入 Transform 实例;wrap_fn 传入函数引用。
  3. 构建期两者都被包进 service 链的对应层级。
  4. 请求按链顺序经过同一套 call 流程。
  5. 二者可以混用,按注册的逆序执行。

代码或图示

use actix_web::{App, middleware::{self, Next}, dev::ServiceResponse, Error, HttpResponse};

async fn log_mw(
    req: actix_web::dev::ServiceRequest,
    next: Next<impl actix_web::body::MessageBody>,
) -> Result<ServiceResponse<impl actix_web::body::MessageBody>, Error> {
    let start = std::time::Instant::now();
    let res = next.call(req).await?;
    println!("elapsed {:?}", start.elapsed());
    Ok(res)
}

let app = App::new()
    .wrap(middleware::Logger::default())
    .wrap_fn(log_mw)
    .route("/", web::get().to(|| async { HttpResponse::Ok() }));

常见误区

  • 以为 wrap_fn 是闭包专用:它接收的是异步函数,闭包若满足签名也可以传入。
  • 在 wrap_fn 里为每个请求克隆大量外部状态:外部状态应通过 web::Data 注入并共享。

追问

  • wrap_fn 底层调用哪个辅助函数?答:middleware::from_fn,wrap_fn 是 App/Scope/Resource 上对它的便捷封装。
  • 函数中间件能否访问应用状态?答:可以在函数参数里再加 web::Data<T> 提取器,或通过请求扩展获取。

04.4.4.2-006 middleware::from_fn 的签名是什么,Next 起什么作用?

一句话结论

from_fn 把 async fn(ServiceRequest, Next<B>) -> Result<ServiceResponse<B>, Error> 包装成 Transform 中间件;Next 是对下一层 service 的包装,调用 next.call(req) 才会把请求放行给下游。

概念解释

Next 内部持有链路中紧邻的下一层 service 及其响应体类型。中间件在前置阶段检查、修改请求后,必须显式调用 next.call(req).await 才会继续;不调用 next.call 就是短路。Next 泛型随下游 body 类型推导,函数签名里通常用 Next<impl MessageBody> 保持泛型。

原理流程

  1. 定义异步函数,参数为 ServiceRequest 与 Next<impl MessageBody>。
  2. 前置逻辑:读请求头、路径、扩展数据或做鉴权。
  3. 需要放行时执行 next.call(req).await?。
  4. 拿到 ServiceResponse 后做后置处理(补头、记日志)。
  5. 返回 Ok(res);失败返回 Error 或提前构造响应。

代码或图示

use actix_web::{middleware::{self, Next}, dev::{ServiceRequest, ServiceResponse}, Error, body::MessageBody};

async fn auth(
    req: ServiceRequest,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    if req.headers().contains_key("x-token") {
        next.call(req).await
    } else {
        Ok(req.into_response(actix_web::HttpResponse::Unauthorized().finish()))
    }
}

let app = App::new().wrap(middleware::from_fn(auth));

常见误区

  • 忘记 next.call(req).await:请求直接挂起,无响应返回。
  • 调用 next.call(req) 后又修改已被消费的请求头:放行后 req 的部分状态已移动给下游。

追问

  • Next::call 返回什么?答:Result<ServiceResponse<B>, Error>,与下游 service 的响应类型一致。
  • 如何在函数中间件里自定义拒绝响应?答:用 req.into_response(HttpResponse::... ) 包装成 ServiceResponse 返回。

04.4.4.2-007 中间件如何提前短路返回响应而不调用下一个 service?

一句话结论

在中间件 call 或函数中间件中直接构造 HttpResponse 并用 ServiceRequest::into_response 包装为 ServiceResponse 返回,不调用 next.call 即可短路。

概念解释

短路适用于鉴权失败、限流拒绝、路径非法、请求体超限等场景。此时不需要下游 handler 参与,中间件直接产出响应。注意短路响应仍会沿外层中间件链做后置处理,外层日志、响应头补全依旧生效。

原理流程

  1. 中间件读取请求并判定拒绝条件。
  2. 构造状态码与响应体(JSON、文本或空体)。
  3. 调用 req.into_response(resp) 得到 ServiceResponse。
  4. 不调用内层 service.call。
  5. 响应向外经过其余中间件后置逻辑后返回客户端。

代码或图示

async fn guard(
    req: ServiceRequest,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    let token = req.headers().get("authorization").and_then(|h| h.to_str().ok());
    match token {
        Some(_) => next.call(req).await,
        None => Ok(req.into_response(
            HttpResponse::Unauthorized().json(serde_json::json!({"error": "missing token"}))
        )),
    }
}

常见误区

  • 短路时丢弃原始请求信息,导致外层日志拿不到路径与方法。
  • 在短路响应里忘记设置正确的 Content-Type 或 WWW-Authenticate 头。

追问

  • 短路后下游提取器还会执行吗?答:不会,请求没有进入路由匹配与提取阶段。
  • 如何记录一次短路拒绝?答:在中间件短路前写入请求扩展或直接记日志,外层 Logger 会按最终状态码输出。

04.4.4.2-008 复杂中间件为什么通常拆成 Builder 类型与 Middleware 类型两个结构体?

一句话结论

Builder 类型只持有构造期配置并实现 Transform,Middleware 类型持有内层 service 并实现 Service;拆分后配置可在构建期共享,运行期状态在每个 service 实例内独立维护。

概念解释

如果把配置、内层 service、运行期可变状态混在一个结构体里,多 worker 构造与复用边界会变模糊。规范写法是:Mw(Builder)字段为配置项,MwService<S>(实例)字段为 service: S 与运行期状态。new_transform 把配置复制进实例并包装内层 service。

原理流程

  1. 定义 Mw { limit: usize } 作为 Transform 实现类型。
  2. 定义 MwService<S> { service: S, limit: usize, used: atomic::AtomicUsize }。
  3. new_transform 读取 self.limit,构造 MwService。
  4. 每个链路上的实例各自维护计数,互不干扰。
  5. 配置修改需要在 App 重建时生效,运行期计数不回写 Builder。

代码或图示

pub struct RateMw { pub limit: usize }

pub struct RateMwService<S> {
    service: S,
    limit: usize,
    used: std::sync::atomic::AtomicUsize,
}

impl<S, B> Transform<S, ServiceRequest> for RateMw
where S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error>,
      S::Future: 'static, B: 'static,
{
    type Response = ServiceResponse<B>;
    type Error = Error;
    type InitError = ();
    type Transform = RateMwService<S>;
    type Future = Ready<Result<Self::Transform, Self::InitError>>;

    fn new_transform(&self, service: S) -> Self::Future {
        ready(Ok(RateMwService {
            service,
            limit: self.limit,
            used: Default::default(),
        }))
    }
}

常见误区

  • 在 Builder 结构体里放 Arc 可变计数:把运行期状态错误地提升为全局共享。
  • 实例结构体保存跨请求复用的昂贵资源时未共享:应通过 web::Data 注入,而不是每个实例各造一份。

追问

  • 两个结构体之间如何共享不可变配置?答:new_transform 把 Builder 字段复制或 Arc 克隆进实例;需要全局只读配置时用 Arc 包裹。
  • 实例需要 Send 吗?答:actix-web 的 service 链路在 worker 线程内调度,Service 实例本身不强制 Send,但其 Future 通常要求 'static。

04.4.4.2-009 中间件返回的 Future 为什么不强制 Send?

一句话结论

actix-web 的 service 调度以 worker 单线程事件循环为模型,中间件 Service 与其 Future 不要求 Send;这也是 actix 生态与要求全链路 Send 的 tokio 栈中间件写法上的差别之一。

概念解释

actix-service 文档明确说明:new_transform 产出的 service 不必是 Send 或 Sync。内部任务在 actix-rt 的单线程 runtime 上调度,允许使用 LocalBoxFuture。若把 service Future 要求成 Send,会逼开发者用 Arc 与 Mutex 包裹本可留在线程局部的数据,增加不必要成本。

原理流程

  1. Service::Future 关联类型不写 Send bound。
  2. 实例内部可持有非 Send 的线程局部状态。
  3. Future 用 Pin<Box<dyn Future + 'static>> 装箱。
  4. worker 事件循环在同一线程内 poll 这些 Future。
  5. 需要跨线程共享的状态才放到 web::Data(Arc 加锁)中。

代码或图示

type LocalBoxFuture<T> = Pin<Box<dyn Future<Output = T> + 'static>>;

impl<S, B> Service<ServiceRequest> for MwService<S>
where S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error>,
      S::Future: 'static, B: 'static,
{
    type Response = ServiceResponse<B>;
    type Error = Error;
    type Future = LocalBoxFuture<Result<Self::Response, Self::Error>>;

    actix_web::dev::forward_ready!(service);
    fn call(&self, req: ServiceRequest) -> Self::Future {
        Box::pin(async move { self.service.call(req).await })
    }
}

常见误区

  • 照搬 tokio 中间件写法给 Future 加 Send 约束:在 actix 里多余,还会拒绝合法的线程局部实现。
  • 把非 Send 状态存进 web::Data:编译期即报 Data 要求 Send + Sync。

追问

  • actix-rt 是否完全单线程?答:actix-rt 是基于 tokio 的单线程 runtime;actix-web 多 worker 下每个 worker 一个独立事件循环,跨 worker 共享仍走 Arc。
  • 哪些类型不能放进非 Send Future 的捕获?答:Rc、RefCell 等非 Send 类型可以留在单线程 Future 内,但不能跨线程移动。

04.4.4.2-010 自定义中间件要满足哪些常见泛型约束?

一句话结论

典型约束是 S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error>、S::Future: 'static、B: 'static,实例 Future 用 LocalBoxFuture,并通过 forward_ready! 转发就绪状态。

概念解释

约束的核心是把内层 service 的请求/响应/错误类型对齐到 actix-web 约定:请求为 ServiceRequest,响应为 ServiceResponse<B>,错误为 actix_web::Error。'static 约束保证 Future 捕获的数据能活到请求结束;B 泛型让中间件可叠加在不同响应体之上。

原理流程

  1. 写 impl<S, B> Transform<S, ServiceRequest> for Mw。
  2. where 子句限定 S 的响应、错误与 Future 生命周期。
  3. 声明关联类型 Response/Error/InitError/Transform/Future。
  4. 实例 Service 复用同样的 S、B 约束。
  5. 编译期检查链路类型衔接,不满足时按编译器提示补 bound。

代码或图示

impl<S, B> Transform<S, ServiceRequest> for Mw
where
    S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error>,
    S::Future: 'static,
    B: 'static,
{
    type Response = ServiceResponse<B>;
    type Error = Error;
    type InitError = ();
    type Transform = MwService<S>;
    type Future = Ready<Result<Self::Transform, Self::InitError>>;

    fn new_transform(&self, service: S) -> Self::Future {
        ready(Ok(MwService { service }))
    }
}

常见误区

  • 漏掉 S::Future: 'static:装箱 Future 捕获内层 Future 时生命周期不足。
  • 错误类型写成自定义 MyError:actix-web 链路上错误统一为 actix_web::Error,自定义错误需实现 ResponseError 转换。

追问

  • InitError 必须是 () 吗?答:不必须,可返回构造失败类型;启动阶段该错误会导致服务构建失败。
  • 约束里 B: MessageBody 什么时候加?答:需要在中间件里读取或判断 body 帧时加;只透传响应时 B: 'static 即可。

04.4.4.2-011 ServiceRequest 与 HttpRequest 在中间件里怎么拿?

一句话结论

中间件前置阶段拿到的是 ServiceRequest,它持有可变的请求头、路径与扩展;需要只读的请求视图时,通过 req.request() 得到 &HttpRequest。

概念解释

ServiceRequest 是 actix-web dev 层类型,等价于「可被链路继续处理的请求」,内含 HttpRequest 视图与可变扩展映射。中间件在 call 里持有 ServiceRequest 所有权;handler 提取器收到的 HttpRequest 是其只读视图。ServiceRequest 提供 headers_mut、match_pattern、app_data 等方法。

原理流程

  1. 中间件函数参数或 call 参数拿到 ServiceRequest。
  2. 只读访问方法、URI、头时用 req.request() 或 req.method()、req.path()。
  3. 修改头用 req.headers_mut()。
  4. 需要把请求交给下游时把 req 整体传给 next.call。
  5. 短路时用 req.into_response 消费请求。

代码或图示

async fn inspect(
    req: ServiceRequest,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    let method = req.method().clone();
    let path = req.path().to_owned();
    let http: &HttpRequest = req.request();
    let host = http.headers().get("host").cloned();
    println!("{method} {path} host={host:?}");
    next.call(req).await
}

常见误区

  • 在中间件里期望直接拿到 handler 提取后的业务对象:提取器在更内层执行,中间件只能拿到原始请求片段。
  • 短路后还继续借用 req 的字段:into_response 已消费请求。

追问

  • ServiceRequest::match_pattern 返回什么?答:当前匹配到的路由模板(如 /users/{id}),用于日志区分真实路由与路径参数。
  • 中间件里能拿到查询字符串吗?答:可以,req.query_string() 取原始串;结构化解析可借助 web::Query 提取器或 serde_urlencoded。

04.4.4.2-012 中间件里如何读取与修改请求头?

一句话结论

ServiceRequest 提供 headers() 与 headers_mut(),读取用 Headers::get,修改用插入或删除;改动发生在放行给下游之前,下游提取器即可看到新头。

概念解释

请求头是 actix_http::HeaderMap。中间件可在前置阶段做协议升级头校验、注入内部标识头、剥离客户端伪造的内部头。注意 body 头与 Host、Content-Length 等受限头的修改要符合 HTTP 语义,避免下游解析矛盾。

原理流程

  1. req.headers().get(name) 读取单个头,返回 Option<&HeaderValue>。
  2. 多值头用 headers().get_all 迭代。
  3. req.headers_mut().insert(...) 覆盖,append 追加,remove 删除。
  4. 处理完成后把 req 传给下游。
  5. 若修改了 Content-Length 相关语义,需同步调整 body 长度声明。

代码或图示

async fn trace_header(
    req: ServiceRequest,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    let has_trace = req.headers().contains_key("x-request-id");
    if !has_trace {
        if let Ok(v) = HeaderValue::from_str(&uuid::Uuid::new_v4().to_string()) {
            req.headers_mut().insert("x-request-id", v);
        }
    }
    next.call(req).await
}

常见误区

  • 用中文或非 ASCII 内容构造 HeaderValue 不校验:HeaderValue::from_str 失败需处理。
  • 在下游已开始读取 body 之后回头改请求头:类型上 req 已被移动,无法再改。

追问

  • 如何读取 Authorization 头并解析 Bearer token?答:headers().get("authorization") 转字符串,按 Bearer 前缀切片;完整方案常用 actix-web-httpauth。
  • 转发内部头给下游时要不要防伪造?答:应在边界中间件剥离客户端传入的内部标识头,再由服务端重新注入。

04.4.4.2-013 中间件里如何修改响应头与响应体?

一句话结论

后置阶段拿到 ServiceResponse,用 res.headers_mut() 改响应头;需要替换 body 时构造新的 ServiceResponse,把原响应的请求与状态码带过去。

概念解释

响应由 ServiceResponse<B> 包装,B 为 body 类型。补安全头、加 X-Response-Time 属于纯头修改,保留原 body 即可;压缩、注入包装内容属于 body 改写,需要引入新的 body 类型并调整 Response 关联类型。

原理流程

  1. next.call(req).await? 得到 ServiceResponse。
  2. 头修改:res.headers_mut().insert(...)。
  3. 状态码读取:res.status();响应头读取:res.headers()。
  4. 若替换 body:用 ServiceResponse::new(req, HttpResponse::... ) 或 map_into_boxed_body。
  5. 返回加工后的响应。

代码或图示

async fn secure_headers(
    req: ServiceRequest,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    let mut res = next.call(req).await?;
    res.headers_mut().insert("x-frame-options", "DENY".parse().unwrap());
    res.headers_mut().insert("x-content-type-options", "nosniff".parse().unwrap());
    Ok(res)
}

常见误区

  • 在后置阶段读取并消费响应 body 后放回:body 流只能读一次,需要缓存或用 body 包装层。
  • 覆盖下游已经设置的 Content-Type:应先判断是否已存在再决定插入。

追问

  • ServiceResponse::map_body 做什么?答:把响应 body 映射为另一种 body 类型,保持请求与状态码不变。
  • 如何给所有响应统一加 Cache-Control?答:在最外层中间件后置阶段按响应路径或状态码条件插入,静态资源与接口分别策略。

04.4.4.2-014 一个中间件如何访问 App 注入的 web::Data?

一句话结论

通过 ServiceRequest::app_data::<T>() 取得 web::Data<T> 引用,或在函数中间件参数中追加 web::Data<T> 提取器;注入的数据必须在 App 构建时用 app_data 登记。

概念解释

web::Data<T> 是 actix-web 的共享状态包装,中间件与 handler 共用同一份注入表。req.app_data::<T>() 返回 Option<&Data<T>>,未注入时为 None。需要在中间件持有配置或客户端(日志配置、限流器、HTTP 客户端)时,优先走 Data 共享,而不是在 Transform 里克隆全局状态。

原理流程

  1. App 构建时 .app_data(web::Data::new(config))。
  2. 中间件前置阶段调用 req.app_data::<Config>()。
  3. 取到 Data<Config> 后通过 Deref 读配置。
  4. 未取到时按降级策略返回错误或默认行为。
  5. 函数中间件也可把 web::Data<Config> 作为额外参数由框架注入。

代码或图示

#[derive(Clone)]
struct AppConfig { rate_limit: usize }

async fn mw_with_data(
    req: ServiceRequest,
    data: web::Data<AppConfig>,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    println!("limit = {}", data.rate_limit);
    next.call(req).await
}

let app = App::new()
    .app_data(web::Data::new(AppConfig { rate_limit: 100 }))
    .wrap_fn(mw_with_data);

常见误区

  • 在中间件里自己 Data::new(...) 造一份状态:与 handler 拿到的不是同一份。
  • 注入类型未实现 Clone + Send + Sync + 'static:app_data 编译期不接受。

追问

  • app_data::<T>() 与提取 web::Data<T> 有何差别?答:前者从请求上查询并返回引用,后者由框架按参数注入;未注入时前者返回 None,后者在提取期拒绝。
  • 中间件能否修改共享配置?答:只读字段直接读;可改字段需包 Arc<Mutex<RwLock>>,且避免跨 await 持锁。

04.4.4.2-015 from_fn 闭包能否捕获外部状态,捕获类型有什么约束?

一句话结论

可以捕获,但捕获的数据要满足中间件 Future 的生命周期与线程约束;长期复用的状态应 Arc 化后通过 web::Data 注入,避免每个请求闭包持有不可共享的克隆。

概念解释

wrap_fn/from_fn 接收的是函数或满足签名的闭包。若闭包捕获外部变量,这些变量会被 move 进中间件实例。actix-web service 实例不强制 Send,但注入 App 后被多 worker 使用时,跨线程场景下捕获值通常需要 Send + Sync;按值捕获的大块数据会在构造期复制,成本高。

原理流程

  1. 识别闭包捕获:不可变借用、move 捕获 Arc 或按值复制。
  2. 长期只读状态构造 Arc,再经 web::Data 注入。
  3. 短暂请求内的局部状态在函数内新建。
  4. 闭包返回的 Future 捕获值要求 'static。
  5. 编译期按 worker 线程模型校验 Send 约束。

代码或图示

let config = web::Data::new(AppConfig { rate_limit: 100 });
let app = App::new()
    .app_data(config.clone())
    .wrap_fn(move |req: ServiceRequest, next: Next<impl MessageBody>| async move {
        // 闭包内不再直接捕获大对象;需要配置时从 req.app_data 取
        next.call(req).await
    });

常见误区

  • 闭包捕获 Rc 或线程局部句柄:多 worker 下无法跨线程构造,编译报错。
  • 每个请求都在闭包里克隆昂贵客户端:应复用 Data 中的 reqwest::Client 或 awc::Client。

追问

  • 闭包捕获的 Arc<T> 会被复制几次?答:构造期克隆一份进中间件实例;运行期多次 Deref 共享同一个 Arc 指向的对象。
  • 函数中间件签名里 Next 的 body 类型如何推导?答:由内层 service 的响应体类型决定,写 impl MessageBody 即可让编译器推导。

04.4.4.2-016 中间件中能否拿到匹配的路由信息与提取结果?

一句话结论

可以拿到路由模板(match_pattern)与原始请求片段,但提取器解析出的业务参数在更内层构造,中间件通常拿不到;需要共享解析结果时由中间件写入 request extensions,供 handler 提取。

概念解释

中间件位于提取器之外,因此 web::Path、web::Query 等解析结果对它不可见。ServiceRequest 暴露 match_pattern() 返回当前匹配模板,用于日志聚合;路径段、查询串仍需中间件自行从原始 URI 解析。

原理流程

  1. 路由匹配发生在进入内层 service 时。
  2. 中间件通过 req.match_pattern() 读模板字符串。
  3. 业务参数解析在 handler 提取器阶段完成。
  4. 若中间件已解析出用户身份,放入 extensions 供 handler 读取。
  5. handler 侧用自定义提取器从 extensions 取回。

代码或图示

async fn route_log(
    req: ServiceRequest,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    let pattern = req.match_pattern().map(|s| s.to_owned()).unwrap_or_else(|| "*".into());
    let res = next.call(req).await?;
    println!("route={} status={}", pattern, res.status());
    Ok(res)
}

常见误区

  • 期望在中间件直接 Path::<u64>::extract(&req):提取器面向 handler 参数契约,中间件请求类型不匹配。
  • 把路由参数解析逻辑重复写在中间件与 handler:应只在一处解析,结果经 extensions 传递。

追问

  • match_pattern 未命中路由时返回什么?答:通常为 None,日志里用通配符占位。
  • 中间件解析出的身份如何交给 handler?答:写入 req.extensions_mut().insert(Identity(...)),handler 自定义提取器用 Extensions 查询。

04.4.4.2-017 中间件里发生错误如何转换成 actix_web::Error?

一句话结论

实现 ResponseError trait 的错误可通过 ? 或 into() 转成 actix_web::Error;未实现时用 Error::from 包装,或直接短路返回 HttpResponse 对应状态。

概念解释

链路错误类型统一为 actix_web::Error。自定义错误类型实现 ResponseError(status_code 与 error_response)后可参与框架的错误渲染。中间件前置校验失败更常见的做法是直接构造 HttpResponse 短路,而不是抛错误穿越链路。

原理流程

  1. 定义错误枚举并 #[derive(thiserror::Error)]。
  2. 为其实现 ResponseError,指定状态码与 JSON 响应。
  3. 中间件中 Err(e)? 自动转换为 Error。
  4. 框架错误处理器把 Error 渲染为响应。
  5. 简单拒绝可跳过错误类型,直接 req.into_response(HttpResponse::...)。

代码或图示

#[derive(thiserror::Error, Debug)]
enum GuardError {
    #[error("unauthorized")]
    Unauthorized,
}

impl actix_web::ResponseError for GuardError {
    fn status_code(&self) -> actix_web::http::StatusCode {
        actix_web::http::StatusCode::UNAUTHORIZED
    }
}

async fn guard(
    req: ServiceRequest,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    if req.headers().contains_key("x-token") {
        next.call(req).await
    } else {
        Err(Error::from(GuardError::Unauthorized))
    }
}

常见误区

  • 错误类型只实现 std::error::Error 不实现 ResponseError:默认按 500 渲染,丢失业务状态码。
  • 在中间件里 unwrap 解析请求头:应返回明确错误响应,而不是 panic 打断 worker。

追问

  • ResponseError::error_response 默认行为是什么?答:默认返回状态码对应文本响应;可重写为 JSON 错误体。
  • Error::from 与 Error::bad_request 怎么选?答:有类型化错误走 ResponseError 转换;一次性拒绝用 Error::from(HttpResponse::BadRequest())。

04.4.4.2-018 为什么建议中间件对响应体类型 B 保持泛型?

一句话结论

保持 B: 'static 泛型让中间件能叠加在任意下游 body(普通 body、压缩 body、流式 body)之上;固定具体 body 类型会限制可组合的位置,并在叠加其它改写 body 的中间件时编译失败。

概念解释

actix-web 链路中 body 类型会随中间件叠加变化:下游可能返回 BoxBody,压缩中间件包出压缩 body,流式接口返回帧流。透传型中间件不消费 body,自然无需知道 B 的具体结构。只有中间件本身要读取、缓存或替换 body 时,才需要约束或固定 B。

原理流程

  1. 实例 Service 声明 impl<S, B> Service<ServiceRequest> for MwService<S>。
  2. where 子句只要求 B: 'static(必要时加 MessageBody)。
  3. 后置处理只改响应头,不触碰 body。
  4. 该中间件可置于 body 类型不同的下游之上。
  5. 需要 body 改写时,把 Response 关联类型改为新 body 类型。

代码或图示

impl<S, B> Service<ServiceRequest> for HeaderMw<S>
where S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error>,
      S::Future: 'static, B: 'static,
{
    type Response = ServiceResponse<B>;
    type Error = Error;
    type Future = LocalBoxFuture<Result<Self::Response, Self::Error>>;

    actix_web::dev::forward_ready!(service);
    fn call(&self, req: ServiceRequest) -> Self::Future {
        let fut = self.service.call(req);
        Box::pin(async move {
            let mut res = fut.await?;
            res.headers_mut().insert("x-mw", "1".parse().unwrap());
            Ok(res)
        })
    }
}

常见误区

  • 透传中间件把 B 写成 BoxBody:与返回其它 body 类型的 service 无法组合。
  • 在泛型 B 上调用需要具体 body 的方法:类型不满足时编译器会提示。

追问

  • 如何把任意 body 统一装箱?答:ServiceResponse::map_into_boxed_body 把 body 转为 BoxBody,需要固定响应类型的场景使用。
  • 压缩中间件是否固定 body 类型?答:压缩层会读取下游 body 帧并产出压缩 body,其 Response 使用新的压缩 body 类型。

04.4.4.2-019 actix-web 中间件与 tower Layer/Service 模型是什么对应关系?

一句话结论

两者都是「包装下一层 service」的责任链模型:actix 的 Transform 对应 tower 的 Layer,actix 的 Service 对应 tower 的 Service;差异在 trait 定义、Future 的 Send 约束与运行时绑定。

概念解释

tower 是 tokio 生态的通用服务抽象,Layer::layer 包装内层 Service,Service::call 返回 Send Future。actix-service 是 actix 生态自有的同类抽象,service 与 Future 不强制 Send,调度在 actix-rt worker 上。axum 直接基于 tower,actix-web 使用自有 service 抽象;两者概念可互译,但 trait 与类型不能直接混用。

原理流程

  1. 概念映射:Transform 约等于 Layer,new_transform 约等于 layer。
  2. Service::call 两边都是异步请求操作。
  3. tower 层要求 Service: Send、Future Send;actix 不强制。
  4. 需要在两边复用同一横切逻辑时,通常按各自 trait 各写一层薄适配。
  5. 社区也有把 tower 服务接入 actix 的适配方案,具体以 docs.rs 当前版本为准。

代码或图示

tower:   Layer -> layer(inner Service) -> Service { call(req) -> Future<Send> }
actix:   Transform -> new_transform(inner S) -> Service { call(req) -> Future<'static> }

常见误区

  • 把 tower-http 的 Layer 直接传给 App::wrap:类型不匹配,需要适配。
  • 以为 actix 中间件底层就是 tower:actix-web 4 基于自有 actix-service 抽象,与 hyper/tower 有衔接但中间件层不共享 trait。

追问

  • actix-web 能否使用 tokio 客户端与中间件?答:客户端(reqwest 等)可在 handler/中间件中调用;tower 中间件不能直接挂载,需自行适配。
  • 两套抽象各自优势?答:tower 跨 tokio 生态复用广、强制 Send;actix 单线程调度模型更轻量,允许线程局部状态。

04.4.4.2-020 中间件构造时机:new_transform 何时被调用,能否在其中做初始化?

一句话结论

new_transform 在 App 构建 service 链期间被调用,每个 worker 链路各构造一份中间件实例;可以在此做轻量初始化,昂贵或共享资源应提前构造好经 web::Data 注入。

概念解释

服务启动时,框架为每个 worker 组装 service 链,依次对各层 Transform 调用 new_transform(内层 service)。构造期适合复制配置、持有内层 service 引用;不适合在此连接外部数据库、加载大文件等阻塞操作。跨实例共享的资源(连接池、客户端、配置)在 App 工厂阶段构造一次并注入 Data。

原理流程

  1. 启动阶段执行 App 工厂闭包,构造 Data 共享资源。
  2. 框架为每个 worker 构建链,调用各 Transform::new_transform。
  3. 实例保存内层 service 与复制来的配置。
  4. 运行期请求才进入 call。
  5. 构造失败通过 InitError 上报,启动即失败。

代码或图示

fn new_transform(&self, service: S) -> Self::Future {
    // 轻量:复制配置、记录构造时间
    let started = std::time::Instant::now();
    ready(Ok(MwService { service, limit: self.limit, started }))
}

常见误区

  • 在 new_transform 里发起网络连接:每个 worker 各建一份,且阻塞构建流程。
  • 把全局计数器放进 Builder 字段:多实例各持一份,计数不准。

追问

  • 每个 worker 的中间件实例是同一份吗?答:不是,按链路分别构造;需要全局共享的状态放 Data 内 Arc。
  • 构造期如何校验配置?答:在 App 工厂阶段先校验并返回错误;InitError 用于 service 包装失败的场景。

04.4.4.2-021 多个 service 复用同一个 Transform 实例时状态如何隔离?

一句话结论

Transform 实例只携带配置,运行期可变状态在 new_transform 产出的每个 Service 实例内隔离;需要跨实例共享的可变状态必须显式放入 Arc 并经 Data 注入。

概念解释

同一个 Mw 配置可被 App、多个 Scope 或 Resource 复用,框架为每条链分别调用 new_transform。若可变计数写在 Builder 字段,复制进各实例后彼此独立;写在 Arc<AtomicUsize> 里才是全局共享。隔离边界是否符合预期,要先想清楚状态是「每链路」还是「全局」。

原理流程

  1. 区分状态归属:每链路独立计数 vs 全局限流。
  2. 每链路状态:实例字段普通类型。
  3. 全局状态:Builder 持有 Arc,new_transform 克隆 Arc 进实例。
  4. 跨请求共享再上层用 web::Data。
  5. 压测时核对计数归属,避免把局部计数当全局指标。

代码或图示

pub struct SharedMw {
    counter: std::sync::Arc<std::sync::atomic::AtomicUsize>,
}

pub struct SharedMwService<S> {
    service: S,
    counter: std::sync::Arc<std::sync::atomic::AtomicUsize>,
}

常见误区

  • 用普通 usize 字段做全局统计:各实例计数互不可见。
  • 每个实例各自初始化共享资源:应在启动阶段构造一次注入。

追问

  • 全局计数器用 Arc<Mutex<usize>> 还是原子类型?答:纯计数优先 AtomicUsize;需要复合更新或复杂结构才用 Mutex。
  • Scope 级中间件实例与 App 级实例隔离吗?答:各自链路独立构造;共享状态仍以 Data 注入为准。

04.4.4.2-022 中间件里阻塞操作有什么风险,应放到哪里执行?

一句话结论

中间件运行在 worker 事件循环上,阻塞调用会卡住该 worker 的所有在途与新请求;阻塞型计算或 IO 应通过 web::block 或专用阻塞线程池执行,再把结果带回异步链路。

概念解释

actix-web 的 worker 是单线程事件循环,中间件 call 与 handler future 都在其上 poll。同步文件读写、CPU 密集哈希、阻塞驱动调用一旦阻塞循环,吞吐与延迟同时恶化。异步等待(IO future)不阻塞循环,可直接 await;同步阻塞必须搬出 worker 线程。

原理流程

  1. 识别操作性质:异步 IO 直接 await,同步阻塞需转移。
  2. 阻塞计算用 web::block(move || ...) 提交阻塞线程池。
  3. web::block 返回 future,在中间件中 await 取结果。
  4. 释放锁、避免在阻塞任务里持有跨线程异步资源。
  5. 监控 worker 延迟,定位阻塞调用。

代码或图示

async fn hash_mw(
    req: ServiceRequest,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    let input = req.path().to_owned();
    let digest = web::block(move || {
        // 阻塞型 CPU 计算,放在阻塞线程池
        sha256::digest(input.as_bytes())
    }).await?;
    println!("digest={}", digest);
    next.call(req).await
}

常见误区

  • 在中间件里调用同步 Redis/MySQL 客户端:阻塞 worker,应换异步驱动或 web::block 包装。
  • 阻塞任务内部再 await 异步 future:web::block 闭包是同步上下文,不能 await。

追问

  • web::block 底层对应什么线程池?答:actix-web 提供的阻塞线程池,与 tokio spawn_blocking 角色对应;具体实现以 docs.rs 当前版本为准。
  • 阻塞任务 panic 会怎样?答:web::block 结果返回错误,需处理,避免 panic 沿链路冒泡。

04.4.4.2-023 如何给中间件加请求超时(超时短路)?

一句话结论

在中间件中用 tokio::time::timeout(或 actix 提供的超时组合)包住下游 call,超时即取消内层 future 并返回 504 响应,不等待下游完成。

概念解释

超时保护是中间件常见职责:下游 handler 或外部依赖卡住时,中间件在限定时间后放弃等待,释放 worker 上的资源并给客户端明确响应。注意超时只是放弃等待,内层 future 被取消后其持有的资源应能随 drop 释放;连接级超时还需配合客户端/服务端配置。

原理流程

  1. 设定 Duration 超时阈值。
  2. tokio::time::timeout(dur, next.call(req)) 包下游调用。
  3. Err(elapsed) 时构造 504 响应短路。
  4. Ok(Ok(res)) 正常返回响应。
  5. 超时记录指标,区分下游慢与自身阻塞。

代码或图示

async fn timeout_mw(
    req: ServiceRequest,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    match tokio::time::timeout(std::time::Duration::from_secs(5), next.call(req)).await {
        Ok(res) => res,
        Err(_) => Ok(req.into_response(HttpResponse::GatewayTimeout().finish())),
    }
}

常见误区

  • 超时后仍持有内层资源句柄不释放:依赖 future drop 触发取消与清理。
  • 把超时设得过短,误杀正常慢接口:应按接口分级配置。

追问

  • 超时与 keep-alive 超时区别?答:请求超时限制单次请求处理时长;keep-alive 限制空闲连接存活时间,由服务端连接层管理。
  • actix-web 是否内置超时中间件?答:内置模块未提供通用请求超时层;可按上述方式自研,或调研社区 crate(待确认:以 docs.rs 与 crates.io 当前版本为准)。

04.4.4.2-024 from_fn 与手写 Transform 各自适用什么场景?

一句话结论

单段前后置逻辑、无需复杂配置与 body 改写用 from_fn;需要构造期状态、泛型 body 处理、就绪背压或复杂生命周期管理时手写 Transform 加 Service 一对类型。

概念解释

from_fn 把样板 trait 实现收敛到一个异步函数,表达力覆盖绝大多数日志、鉴权、补头场景。手写 Transform 的收益在于:Builder 保存配置、实例保存内层 service 与运行期状态、poll_ready 实现容量控制、Future 精确选择本地装箱。选型先按复杂度判断,避免过度设计。

原理流程

  1. 列出中间件职责:是否需要配置、状态、body 改写、背压。
  2. 职责简单:定义异步函数,wrap_fn 挂载。
  3. 职责复杂:拆 Builder 与实例,实现两个 trait。
  4. 需要共享资源时挂 web::Data。
  5. 评审时确认 trait 约束与 body 泛型合理。

代码或图示

// 简单:函数中间件
App::new().wrap_fn(log_mw);

// 复杂:Transform 对类型
App::new().wrap(RateMw { limit: 100 });

常见误区

  • 给每个中间件都手写两个 trait:样板代码冗余,简单场景应优先 from_fn。
  • 函数中间件内塞入大量分支与状态:应重构为结构化的 Transform 实现。

追问

  • 函数中间件能否实现背压?答:from_fn 封装的是 call 路径,poll_ready 由封装层处理;需要自定义就绪状态时手写 Service。
  • 两者性能差异?答:主要在编译期抽象与装箱方式,运行期请求路径差异很小;选型以可维护性为先。

04.4.4.2-025 中间件能否改写请求路径后再进入路由匹配?

一句话结论

可以在前置阶段通过 ServiceRequest 修改路径相关信息,使后续路由按新路径匹配;但路径匹配规则、尾斜杠归一化等要与 NormalizePath 中间件行为对齐。

概念解释

路径改写常用于 API 版本前缀剥离、旧路径兼容、内部路由重写。ServiceRequest 持有 URI 视图,改写需保证方法、路径、查询串一致。注意 actix-web 的路由匹配基于请求 URI 路径,中间件位于匹配之前时改写生效;位于匹配之后则只影响日志与下游视图。

原理流程

  1. 在最外层中间件前置阶段读取原始路径。
  2. 按规则构造新路径与新 URI。
  3. 替换请求中的 URI 信息。
  4. 放行给下游匹配新路径。
  5. 配合 NormalizePath 处理尾斜杠与大小写策略。

代码或图示

async fn rewrite(
    mut req: ServiceRequest,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    // 示例:/v1/items -> /items;具体 URI 改写 API 以 docs.rs 当前版本为准
    let path = req.path().to_owned();
    let new_path = path.strip_prefix("/v1").unwrap_or(&path).to_owned();
    if new_path != path {
        let new_uri = actix_http::Uri::try_from(new_path.as_str()).map_err(Error::from)?;
        req.match_info_mut().retain(); // 待确认:改写后匹配信息重置方式
    }
    next.call(req).await
}

常见误区

  • 只改日志显示路径不改请求 URI:下游匹配仍用旧路径。
  • 改写后残留旧的匹配段与扩展数据:应在改写时清理对应状态。

追问

  • 路径归一化由哪个内置中间件负责?答:NormalizePath,支持尾斜杠行为枚举 TrailingSlash。
  • 旧路径兼容更适合路由重定向还是中间件改写?答:对外兼容旧 URL 用 301/302 重定向;内部前缀剥离且对客户端透明时用中间件改写。

04.4.4.2-026 App、Scope、Resource 三级 wrap 的作用范围有何区别?

一句话结论

App::wrap 作用于整个应用,Scope::wrap 只作用于该前缀下的子路由,Resource::wrap 只作用于单个路由;层级越靠内,覆盖范围越小。

概念解释

actix-web 允许在应用、作用域、资源三个层级分别挂中间件。App 级适合全局日志、安全头、全局 CORS;Scope 级适合某一组 API 的鉴权或限流;Resource 级适合单个接口的特殊处理。请求先经过外层 App 链,再进入对应 Scope 链,最后到 Resource 链。

原理流程

  1. App 构建时挂全局中间件。
  2. web::scope("/admin") 内部挂 Scope 级中间件。
  3. 具体路由 web::resource("/x") 挂 Resource 级中间件。
  4. 请求按 App → Scope → Resource → handler 顺序穿过。
  5. 响应按相反顺序穿出各层。

代码或图示

let app = App::new()
    .wrap(Logger::default())
    .service(
        web::scope("/admin")
            .wrap(RequireAdmin)
            .route("/users", web::get().to(admin_list))
    );

常见误区

  • 把只属于某组接口的鉴权挂到 App 级:所有接口都被拦截,需要额外白名单绕过。
  • 以为 Resource 级中间件能看到兄弟路由:它只包裹该 Resource 自身。

追问

  • Scope 级中间件能否访问 App 注入的 Data?答:可以,Data 注入表沿链路共享。
  • 三级中间件类型必须一致吗?答:不要求,每层可挂不同 Transform 实现。

04.4.4.2-027 多个 wrap 注册后执行顺序为什么与注册顺序相反?

一句话结论

wrap 像一层层向内包裹:后注册的层在最外侧,请求先到达;因此请求处理顺序与 builder 链上的注册顺序相反,响应返回时再按注册顺序向外经过。

概念解释

文档明确:多次使用 wrap/wrap_fn 时,最后出现的先执行。注册 wrap(A).wrap(B).wrap(C),链路为 C → B → A → handler。原因是每次 wrap 都把新中间件包在当前链的外层,先注册的被压到内侧。

原理流程

  1. 第一次 wrap(A):链为 A → inner。
  2. 第二次 wrap(B):B 包住整链,链为 B → A → inner。
  3. 第三次 wrap(C):链为 C → B → A → inner。
  4. 请求从 C 进入,依次向内。
  5. 响应从 A 向外回到 C。

代码或图示

注册:App::new().wrap(A).wrap(B).wrap(C)
请求:C → B → A → handler
响应:handler → A → B → C

常见误区

  • 按注册顺序理解为 A 先执行:实际 C 先看到请求。
  • 调整日志位置时忽略反向规则:想记录最原始请求应把 Logger 放最后注册。

追问

  • wrap_fn 是否遵循同一规则?答:是,函数中间件与 Transform 中间件共用反向注册顺序。
  • 顺序写反会有什么实际问题?答:例如鉴权在内层、日志在外层,被拒绝请求仍会先记日志;或压缩层与头补全层顺序颠倒导致响应头被覆盖。

04.4.4.2-028 外层 App 中间件与内层 Resource 中间件先后顺序如何叠加?

一句话结论

请求先穿过 App 级链(按 App 内注册逆序),再穿过 Scope 级链,最后穿过 Resource 级链;同层内部仍按注册逆序,跨层先外后内。

概念解释

文档说明:当被包裹的 service 自身也带中间件时,App 级先按逆序执行,再对被包裹 service 内部按逆序执行。即层级顺序优先于层内注册顺序。排查「某中间件有没有看到请求/响应」时,先定位层级,再看层内顺序。

原理流程

  1. 请求进入 App 链,逆序经过 App 中间件。
  2. 命中 Scope 后进入 Scope 链,逆序经过 Scope 中间件。
  3. 命中 Resource 后进入 Resource 链。
  4. handler 产出响应。
  5. 响应按 Resource → Scope → App 反向穿出。

代码或图示

App:  wrap(A1).wrap(A2)
Scope: wrap(S1)
Resource: wrap(R1)
请求:A2 → A1 → S1 → R1 → handler
响应:handler → R1 → S1 → A1 → A2

常见误区

  • 把同层逆序与跨层先后混为一谈:跨层永远先外后内。
  • 以为 Scope 中间件在 App 之前看到原始请求:App 外层已先处理。

追问

  • 短路发生在 Scope 层时,App 后置逻辑执行吗?答:执行,响应仍会向外经过 App 各层后置阶段。
  • 如何用日志验证层级顺序?答:在各层前置/后置打点,按请求 trace 串联观察进入与离开顺序。

04.4.4.2-029 Logger 应该放在 wrap 链的最外层还是最内层?

一句话结论

Logger 应作为最外层中间件(builder 链最后注册),这样它能记录到完整请求与最终响应状态码、耗时,包括被内层短路或拒绝的请求。

概念解释

最外层 Logger 前置阶段拿到原始请求,后置阶段拿到经过所有内层处理后的最终响应,状态码、响应头、耗时都完整。若 Logger 在内层,外层短路的请求不会经过它,日志出现缺口。actix-web 内置 Logger 中间件默认输出方法、路径、状态码、耗时等字段。

原理流程

  1. 注册顺序:业务中间件先 wrap,Logger 最后 wrap。
  2. 请求先到 Logger 前置,记录开始时间与请求信息。
  3. 内层处理、短路或正常响应。
  4. Logger 后置读取最终状态码与耗时输出。
  5. 未被内层处理的异常也由 Logger 兜底记录。

代码或图示

let app = App::new()
    .wrap(auth_mw)        // 内层:先注册
    .wrap(Logger::default()); // 外层:最后注册,最先执行

常见误区

  • Logger 最先注册,结果它在最内层,外层拒绝请求漏记。
  • 在 Logger 之外再包一层会改写响应的中间件:Logger 记录的状态码可能被外层改写。

追问

  • Logger 与 tracing 接入如何共存?答:内置 Logger 输出访问日志;结构化追踪用 tracing 中间件或在 handler/提取器中挂 span,二者按职责分层。
  • 如何只对部分路径记详细日志?答:在 Logger 前置按路径过滤,或在 Scope 级挂独立 Logger。

04.4.4.2-030 CORS 预检请求(OPTIONS)在哪一层处理最合适?

一句话结论

CORS 中间件应挂在 App 或对应 Scope 的较外层,确保预检 OPTIONS 请求在进入业务鉴权与路由之前就被处理并返回预检响应。

概念解释

浏览器跨域先发送 OPTIONS 预检,询问允许的来源、方法、头。若 CORS 层在鉴权内层,预检可能先被 401 拒绝,浏览器拿不到正确 CORS 头,正式请求也无法发起。actix-cors 的 Cors 构建器可用于 App、Scope、Resource。

原理流程

  1. 配置允许来源、方法、头与凭证策略。
  2. wrap(Cors::new().finish()) 挂在外层。
  3. 预检到达时 CORS 层直接返回 200/204 加预检头。
  4. 正式请求携带凭证与头进入内层。
  5. 非跨域请求正常穿过。

代码或图示

# Cargo.toml
actix-cors = "0.7"
use actix_cors::Cors;

let cors = Cors::default()
    .allowed_origin("https://example.com")
    .allowed_methods(vec!["GET", "POST"])
    .allowed_headers(vec!["authorization", "content-type"])
    .supports_credentials();

let app = App::new().wrap(cors).service(web::scope("/api"));

常见误区

  • 把 CORS 挂在鉴权之后:预检被 401 拦截,浏览器报 CORS 错误。
  • 允许凭证时又用通配来源:浏览器规范禁止 * 与凭证共存。

追问

  • 简单请求与预检请求区别?答:满足方法/头/内容类型限制的简单请求不发预检,直接带 Origin;复杂请求先发 OPTIONS。
  • expose_headers 做什么?答:声明浏览器 JS 可读的响应头,默认只暴露简单响应头。

04.4.4.2-031 条件中间件 Condition 的判定时机与用法?

一句话结论

Condition 包装另一个中间件并按谓词判定是否启用:谓词基于请求在前置阶段求值,满足则走被包装中间件链,不满足则直接放行内层 service。

概念解释

内置 Condition 用于「按请求条件才启用某层」的场景,例如仅对 /api 前缀挂压缩、仅对带某头的请求启用调试中间件。判定发生在请求进入时,不是构建期一次性决定。被包装的中间件类型仍需满足 Transform 约束。

原理流程

  1. 定义判定闭包:&ServiceRequest -> bool。
  2. Condition::new(predicate, inner_mw) 包装。
  3. 请求到达先求谓词。
  4. 为真:经过 inner_mw 再到内层;为假:直接调用内层 service。
  5. 响应阶段按实际是否经过 inner_mw 决定后置路径。

代码或图示

use actix_web::middleware::Condition;

let mw = Condition::new(
    |req: &ServiceRequest| req.path().starts_with("/api/"),
    Compress::default(),
);
let app = App::new().wrap(mw).route("/api/x", web::get().to(handler));

常见误区

  • 把判定条件写成构建期常量:应基于请求动态求值。
  • 谓词里做阻塞或远程调用:前置阶段阻塞 worker,判定应轻量。

追问

  • Condition 与 Scope 级挂中间件如何选择?答:按路径分组优先 scope;条件依赖头、方法、查询等请求特征时用 Condition。
  • 被禁用的中间件后置逻辑会执行吗?答:请求未经过它,其后置处理也不会执行。

04.4.4.2-032 同一个中间件能否同时挂在 App 与 Scope 上,会执行几次?

一句话结论

可以分别挂载,且每个层级各构造一份实例;请求若经过该 Scope,会依次经过 App 层一次与 Scope 层一次,即同一逻辑执行两遍。

概念解释

App 与 Scope 是不同链路位置,wrap 各自组装。复用同一个 Transform 实例或同一类型都行,但运行期是两份 service 实例。需要全局生效就只挂 App;Scope 内再加通常是为了差异化配置,而非重复全局逻辑。

原理流程

  1. App 级挂载 Mw 实例 A。
  2. Scope 级挂载 Mw 实例 B(配置可不同)。
  3. 命中 Scope 的请求:A 前置 → B 前置 → handler → B 后置 → A 后置。
  4. 未进入该 Scope 的请求只经过 A。
  5. 实例内状态按链路隔离,全局状态经 Data 共享。

代码或图示

let app = App::new()
    .wrap(Logger::default())
    .service(web::scope("/v2").wrap(Logger::new("%a %{x-request-id}i")));

常见误区

  • 以为挂两层只是配置生效一次:实际前后置各执行两次。
  • 两层使用同一可变计数实例:若未走 Arc,计数各自独立。

追问

  • 全局日志为什么不建议 Scope 再挂一遍?答:会产生重复访问日志,除非 Scope 需要不同字段。
  • 两层中间件配置冲突时谁生效?答:按链路先后,后写入的响应头可能覆盖先写入的,需核对顺序。

04.4.4.2-033 wrap 链中某层返回早期响应,下游中间件的后置逻辑是否还执行?

一句话结论

未被经过的下游中间件其前置与后置都不执行;已经过的上游中间件后置逻辑仍会在响应返回时执行。短路只跳过它内层的链路。

概念解释

早期响应由当前层直接构造返回,不再调用内层 service.call,因此内层中间件与 handler 都不运行。外层已经走过的中间件在响应回溯时照常做后置处理(记日志、补头)。排查「后置逻辑缺失」时,先确认请求是否真的经过了该层。

原理流程

  1. 请求进入外层 A 前置。
  2. 到达内层 B,B 判定拒绝并短路返回。
  3. B 内层的 C 与 handler 不执行。
  4. 响应回到 A 后置,A 照常处理。
  5. 短路层自身的后置代码在 call 内随返回路径执行。

代码或图示

A 前置 → B 前置 → B 短路(C、handler 不执行)→ A 后置

常见误区

  • 以为短路后所有中间件后置都会跑:未经过的层不产生后置。
  • 在短路层依赖内层写入的扩展数据:内层未执行,数据不存在。

追问

  • 全局错误兜底应放在哪一层?答:最外层中间件,保证短路与异常都能被后置阶段观察到。
  • 如何让内层也记录一次拒绝?答:由短路层写入响应扩展或直接记日志,不要依赖未执行的内层。

04.4.4.2-034 响应回到中间件链时的经过顺序是怎样的?

一句话结论

响应从 handler 出发,按与请求相反的方向回溯:Resource 层 → Scope 层 → App 层;同层内按注册的正向顺序经过后置逻辑。

概念解释

请求是外→内,响应是内→外。注册 wrap(A).wrap(B)(请求 B→A),响应路径为 A→B。后置修改响应头、压缩、日志都在回溯阶段生效。理解双向顺序是排查响应头被覆盖、压缩位置错误的基础。

原理流程

  1. handler 返回响应体与状态码。
  2. Resource 中间件后置加工。
  3. Scope 中间件后置加工。
  4. App 中间件后置加工(Logger 在此输出最终结果)。
  5. 响应发出客户端。

代码或图示

注册:App.wrap(A).wrap(B)
请求:B → A → handler
响应:handler → A → B → 客户端

常见误区

  • 把响应顺序也当成逆序:同层响应回溯与注册顺序一致。
  • 在后置阶段假设请求扩展仍存在:请求扩展随请求生命周期,响应阶段应读响应扩展或快照。

追问

  • 压缩应挂在补头层内侧还是外侧?答:先补业务响应头,再压缩 body;头补全在内侧、压缩在外侧,响应回溯时先压缩再回补头的需求需实测确认。
  • 后置阶段能否替换响应状态码?答:可以,ServiceResponse 暴露状态码修改接口,具体方法以 docs.rs 当前版本为准。

04.4.4.2-035 调整中间件顺序时如何验证链行为?

一句话结论

用集成测试发起请求断言响应头、状态码与日志输出,并在各层前后置打点观察进入/离开顺序;顺序改动同时覆盖正常请求与短路拒绝两类用例。

概念解释

中间件顺序问题常表现为:日志缺口、响应头被覆盖、预检失败、内层看不到外层注入的数据。验证手段分三层:代码层确认注册层级与顺序;测试层断言可观察结果;运行层用 trace 日志还原链路。变更后回归鉴权、CORS、压缩、日志四类用例。

原理流程

  1. 在各中间件前置/后置输出带层名的日志。
  2. 测试客户端发起正常请求与被拒绝请求。
  3. 断言响应状态码、CORS 头、安全头是否齐全。
  4. 对照日志顺序核对外→内与内→外路径。
  5. 调整后重跑集成测试,防止顺序回归。

代码或图示

// 集成测试:actix_web::test::init_service 起 App,test::call_service 发请求
let app = test::init_service(app).await;
let req = test::TestRequest::get().uri("/api/x").to_request();
let res = test::call_service(&app, req).await;
assert_eq!(res.status(), http::StatusCode::OK);

常见误区

  • 只测正常 200 请求:短路、401、预检 OPTIONS 的链路行为未覆盖。
  • 只看响应不看日志顺序:头覆盖类问题需要确认谁后写入。

追问

  • actix-web 测试用哪些辅助类型?答:actix_web::test 模块提供 init_service、TestRequest、call_service 等。
  • 如何断言响应头集合?答:res.headers() 取 HeaderMap,逐项 contains_key 与值比对。

04.4.4.2-036 Logger 中间件的日志格式字段有哪些?

一句话结论

内置 Logger 支持类 Apache 格式串,常用字段包括远程地址、方法、路径、版本、状态码、响应时长、请求/响应头占位;Logger::default() 使用默认格式,Logger::new(format) 自定义。

概念解释

actix_web::middleware::Logger 在后置阶段输出访问日志。格式占位符与 actix-http 日志约定一致,例如请求方法、URI、状态码、耗时(毫秒),以及 %{name}i 取请求头、%{name}o 取响应头。具体占位符全集以 docs.rs 当前版本 Logger 文档为准,不确定的字段标注待确认。

原理流程

  1. Logger::new("%a \"%r\" %s %T") 定义格式串。
  2. 前置阶段记录请求开始时间。
  3. 后置阶段读取响应状态码、耗时与头。
  4. 按格式串拼装并输出到日志目标。
  5. 可在 Scope 级挂不同格式的 Logger。

代码或图示

use actix_web::middleware::Logger;

let logger = Logger::new("%a \"%m %U\" %s %Dms \"%{x-request-id}i\"");
let app = App::new().wrap(logger);

常见误区

  • 假设字段名与其它框架完全一致:actix-web 占位符需对照文档确认。
  • 在格式串里打印敏感头(Cookie、Authorization):日志泄漏凭证,应避免。

追问

  • Logger 输出到哪里?答:默认走标准日志输出通道;接入 tracing/第三方日志库需按对应集成方式配置。
  • 耗时字段单位?答:文档中耗时占位符有秒/毫秒等变体,以当前版本文档为准。

04.4.4.2-037 NormalizePath 的 TrailingSlash 枚举有哪几种行为?

一句话结论

TrailingSlash 控制路径尾斜杠归一化策略,典型取值为 TrimSlash(去除尾斜杠后匹配)、AlwaysSlash(补尾斜杠)与 None(不归一化);具体变体名与默认值以 docs.rs 当前版本为准。

概念解释

NormalizePath 中间件在路由匹配前规整请求路径,解决 /foo 与 /foo/ 互相 404 的问题。TrailingSlash 枚举决定去除、补齐还是保持原样。它属于路径层规整,不改变查询串与方法。

原理流程

  1. 请求路径到达 NormalizePath 层。
  2. 按枚举策略处理尾斜杠。
  3. 必要时重定向或改写内部路径。
  4. 规整后路径进入路由匹配。
  5. 匹配不到再按 404 处理。

代码或图示

use actix_web::middleware::{NormalizePath, TrailingSlash};

let mw = NormalizePath::new(TrailingSlash::Trim);
let app = App::new().wrap(mw).route("/foo", web::get().to(handler));

常见误区

  • 把尾斜杠兼容全部交给路由注册:同一路由重复带/不带斜杠注册容易冲突。
  • 期望归一化处理大小写或编码:NormalizePath 只管路径斜杠策略,不做大小写折叠。

追问

  • 归一化后是 301 重定向还是内部改写?答:行为随枚举策略而定,重定向场景返回 3xx,具体以文档为准。
  • 与路由模板末尾 {tail:.*} 通配如何配合?答:通配段保留剩余路径,尾斜杠策略不影响已捕获的 tail 内容。

04.4.4.2-038 DefaultHeaders 中间件如何设置默认响应头,是否覆盖已有头?

一句话结论

DefaultHeaders 按名称追加默认响应头;默认只在响应未携带该头时补全,是否覆盖已存在头由其 builder 方法控制,具体方法名以 docs.rs 当前版本为准。

概念解释

默认响应头用于统一 X-Content-Type-Options、Server、Cache-Control 等。DefaultHeaders::new().add((name, value)) 登记键值对,后置阶段写入响应。下游 handler 已设置同名头时,默认层通常不覆盖,避免把业务头冲掉。

原理流程

  1. 构建 DefaultHeaders,逐条 add 头。
  2. 中间件后置阶段遍历待补头。
  3. 响应未携带该名时插入;已存在则按策略保留或覆盖。
  4. 响应继续向外层回溯。
  5. 404 等框架产生的响应同样经过该层。

代码或图示

use actix_web::middleware::DefaultHeaders;

let headers = DefaultHeaders::new()
    .add(("x-content-type-options", "nosniff"))
    .add(("x-frame-options", "DENY"));
let app = App::new().wrap(headers);

常见误区

  • 用 DefaultHeaders 设置需要按接口区分的头:策略不同应在 handler 或专用中间件处理。
  • 依赖默认层覆盖下游错误头:默认层语义是补全而非强制覆盖。

追问

  • 安全头应该挂全局还是按响应类型?答:通用安全头挂全局;按内容类型区分的缓存、下载头在 handler/Resource 层设置。
  • 如何设置多条同名头?答:add 追加语义由 builder 决定,多值头使用 HeaderValue 列表,具体 API 查文档确认。

04.4.4.2-039 ErrorHandlers 如何按状态码注册自定义错误响应?

一句话结论

ErrorHandlers 按 HTTP 状态码注册处理闭包,框架生成对应错误响应时回调闭包改写响应体或头,常用于统一 404/500 页面或 JSON 错误结构。

概念解释

内置 ErrorHandlers 挂载在链路上,对最终响应状态码匹配注册项。闭包接收 ServiceResponse,返回 ErrorHandlerResponse。它处理的是「响应已经产生、状态码不符预期」的统一包装,与 handler 内部 ? 传播的业务错误互补。

原理流程

  1. ErrorHandlers::new().handler(StatusCode::NOT_FOUND, not_found) 登记。
  2. 响应产出后按状态码查找处理器。
  3. 命中闭包,读取原响应并构造新响应。
  4. 返回 ErrorHandlerResponse(改写或透传)。
  5. 继续向外层回溯。

代码或图示

use actix_web::middleware::ErrorHandlers;
use actix_web::{HttpResponse, http::StatusCode};

fn not_found(res: ServiceResponse<impl MessageBody>) -> ErrorHandlerResponse<impl MessageBody> {
    ErrorHandlerResponse::Response(res.into_response(
        HttpResponse::NotFound().json(serde_json::json!({"error": "not found"}))
    ))
}

let app = App::new()
    .wrap(ErrorHandlers::new().handler(StatusCode::NOT_FOUND, not_found));

常见误区

  • 把业务校验错误都交给 ErrorHandlers:业务错误应在 handler 用类型化错误返回,状态分层清晰。
  • 闭包内消费响应 body 后未放回:body 流只能读一次。

追问

  • 500 响应也能统一包装吗?答:可以注册 INTERNAL_SERVER_ERROR 处理器,但不要在其中泄漏内部错误细节。
  • ErrorHandlers 与 ResponseError 分工?答:ResponseError 定义单个错误类型如何转响应;ErrorHandlers 在响应层按状态码做统一包装。

04.4.4.2-040 ErrorHandlerResponse 的返回形式与响应改写时机?

一句话结论

ErrorHandlerResponse 枚举标记处理器是改写了响应还是透传原响应;改写时机在响应回溯阶段、状态码已确定之后。

概念解释

处理器闭包不能在请求前置阶段介入,只能在响应产生后包装。返回值携带新的 ServiceResponse,框架据此替换或保留原响应。读取原响应状态、头是安全的;读取 body 需注意一次性消费。

原理流程

  1. 响应状态码确定并匹配注册项。
  2. 闭包拿到原 ServiceResponse。
  3. 构造新响应:换 JSON 体、加错误头、保留原状态码。
  4. 包装为 ErrorHandlerResponse::Response(...) 返回。
  5. 框架用新响应继续链路。

代码或图示

use actix_web::middleware::ErrorHandlerResponse;

fn wrap_500(res: ServiceResponse<impl MessageBody>) -> ErrorHandlerResponse<impl MessageBody> {
    let new = res.into_response(
        HttpResponse::InternalServerError().json(serde_json::json!({"error": "internal"}))
    );
    ErrorHandlerResponse::Response(new)
}

常见误区

  • 在处理器里改变 HTTP 方法或重写路径:该层只处理响应,不应回改请求。
  • 改写后丢掉原始请求引用:into_response 会把请求绑定进新响应。

追问

  • 处理器能否只加头不改 body?答:可以,在原 ServiceResponse 上 headers_mut 插入后返回透传包装形式,具体变体以文档为准。
  • 未匹配任何处理器时行为?答:原响应直接通过,不做改写。

04.4.4.2-041 Compress 中间件支持哪些压缩编码,如何与请求头协商?

一句话结论

内置 Compress 按请求 Accept-Encoding 与响应内容协商压缩编码(br、gzip、deflate、zstd 等,具体集合以 docs.rs 当前版本为准),压缩响应 body 并设置对应 Content-Encoding 头。

概念解释

压缩层位于响应回溯阶段,读取下游 body 帧,按协商结果压缩。文本类响应收益明显,已压缩资源(图片、压缩包)不应重复压缩。编码选择受客户端 Accept-Encoding 与中间件配置共同决定;不支持或不适合压缩时透传。

原理流程

  1. 读取请求 Accept-Encoding。
  2. 对比中间件启用的编码集合,选优先级最高者。
  3. 后置阶段压缩响应 body。
  4. 写入 Content-Encoding 与调整 Content-Length/传输编码。
  5. 不压缩场景透传原 body。

代码或图示

use actix_web::middleware::Compress;

let app = App::new()
    .wrap(Compress::default())
    .route("/text", web::get().to(|| async { "hello" }));

常见误区

  • 对二进制大文件全局开启压缩:浪费 CPU 且无收益。
  • 压缩层放在安全头补全外侧导致头顺序问题:调整层级实测确认。

追问

  • 如何对特定接口关闭压缩?答:在该 Scope/Resource 不挂 Compress,或响应设置不协商压缩的策略;按当前版本 API 确认。
  • 压缩会影响 SSE/WebSocket 吗?答:实时流通常不走普通响应压缩;WebSocket 帧有自身分片与压缩扩展机制。

04.4.4.2-042 Condition 中间件如何按请求条件启用其它中间件?

一句话结论

Condition::new(判定闭包, 被包装中间件) 在每个请求上求值闭包,为真才把请求交给被包装中间件,为假直接放行内层 service。

概念解释

适用场景:仅对 API 前缀启用压缩、仅调试环境开启详细日志、按请求头切换实验性中间件。判定闭包只读 &ServiceRequest,必须轻量无阻塞。被包装中间件自身仍是完整 Transform 实现。

原理流程

  1. 编写 Fn(&ServiceRequest) -> bool 谓词。
  2. 用 Condition 包裹目标中间件。
  3. 请求进入先求值谓词。
  4. 真:走目标中间件链;假:直达内层。
  5. 响应按实际路径回溯。

代码或图示

use actix_web::middleware::{Condition, Compress};

let compress_api = Condition::new(
    |req: &ServiceRequest| req.path().starts_with("/api/"),
    Compress::default(),
);
let app = App::new().wrap(compress_api);

常见误区

  • 谓词访问 web::Data 未通过 req.app_data:闭包参数只有请求,需从请求取注入状态。
  • 谓词内做远程鉴权:判定过重会阻塞前置链路。

追问

  • Condition 能否包裹多个中间件?答:先把多个中间件组成内层链,再整体作为被包装项;单参数形式只接一个 Transform。
  • 条件为假时被包装中间件的初始化仍发生吗?答:Transform 构造在构建期完成,运行期只是跳过调用。

04.4.4.2-043 Compat 中间件解决什么类型不匹配问题?

一句话结论

Compat 用于把满足某套 service 约束的中间件适配到 Resource::wrap 或 Condition 等位置,解决泛型/响应体类型不兼容的包装问题。

概念解释

文档说明:Compat 是启用任意中间件在 Resource::wrap 与 Condition 中使用的适配层。actix-web 不同挂载点对 service 泛型与 body 类型的约束略有差异,Compat 在中间件与目标位置之间做类型桥接。具体适配的 trait 边界以 docs.rs 当前版本为准。

原理流程

  1. 目标挂载点要求特定 service 类型约束。
  2. 现有中间件类型不直接满足。
  3. 用 Compat 包装该中间件。
  4. 包装后的 Transform 满足挂载点约束。
  5. 正常进入链路处理请求。

代码或图示

use actix_web::middleware::Compat;

// 待确认:具体构造参数与泛型按 docs.rs/actix_web/middleware/Compat 当前版本核对
let app = App::new().service(
    web::resource("/x").wrap(Compat::new(SomeMiddleware))
);

常见误区

  • 把 Compat 当成功能型中间件:它只做类型适配,不改变请求处理语义。
  • 忽略版本差异:Compat 字段与用法在 actix-web 4 内有演进,需对照当前文档。

追问

  • 哪些位置需要 Compat?答:文档列出 Resource::wrap 与 Condition 场景;其余挂载点直接 wrap 即可。
  • 适配后性能有损耗吗?答:仅增加一层薄包装,请求路径开销很小。

04.4.4.2-044 Identity 中间件的用途是什么?

一句话结论

Identity 是一个不改动请求与响应的透传 no-op 中间件,用于占位、条件分支中保持链路结构一致或作为自定义中间件的空白基类。

概念解释

内置 Identity 直接把请求交给内层 service、原样返回响应。它没有可观测的横切行为,存在意义是类型占位:例如根据配置在「真实中间件」与「不做事」之间选择同一类型的 Transform,或作为示例中间件的起点。

原理流程

  1. 链路组装时把 Identity 放入某层。
  2. 请求到达 Identity,直接调用内层 service。
  3. 响应原样返回。
  4. 不读写头、不改写 body。
  5. 调试时可临时替换为真实中间件。

代码或图示

use actix_web::middleware::Identity;

let app = App::new()
    .wrap(Identity) // 占位:后续替换为真实鉴权/日志中间件
    .route("/", web::get().to(handler));

常见误区

  • 以为 Identity 承担身份认证:名字易误解,它与登录身份无关。
  • 生产环境保留 Identity 占位层:应移除无意义包装。

追问

  • Identity 与 Condition 禁用场景等价吗?答:Condition 禁用时直接跳层;Identity 是经过一层空包装,语义接近但结构不同。
  • 内置 no-op 还有其它类型吗?答:以当前 middleware 模块文档列出的结构体为准。

04.4.4.2-045 内置中间件在 docs.rs 当前版本中的模块路径是什么?

一句话结论

内置中间件位于 actix_web::middleware 模块,典型包括 Logger、NormalizePath、DefaultHeaders、ErrorHandlers、Compress、Condition、Compat、Identity,辅助类型有 Next、TrailingSlash、ErrorHandlerResponse。

概念解释

actix-web 4 的中间件统一从 actix_web::middleware 引入;复杂 trait 与 dev 类型从 actix_web::dev 引入。社区中间件(CORS、认证、限流)位于独立 crate,不在内置模块内。引入前对照当前版本模块清单,避免引用已移除或改名的项。

原理流程

  1. 查 docs.rs actix_web::middleware 模块项列表。
  2. 内置项直接 use actix_web::middleware::...。
  3. 自定义 trait 用 use actix_web::dev::{Service, Transform, ...}。
  4. 社区能力按 crate 名单独引入。
  5. 编译期若类型路径不存在,核对版本与模块归属。

代码或图示

use actix_web::middleware::{Logger, NormalizePath, DefaultHeaders, ErrorHandlers, Compress};
use actix_web::dev::{Service, Transform, ServiceRequest, ServiceResponse};

常见误区

  • 把 actix-cors、actix-web-httpauth 写进 actix_web::middleware 路径:它们是独立 crate。
  • 引用旧版本文档中的模块名:4.x 与 3.x 中间件组织有差异。

追问

  • 会话中间件在内置模块吗?答:会话支持由独立 crate(如 actix-session 生态)提供,具体以 crates.io 当前版本为准。
  • 压缩与响应头补全都算内置吗?答:Compress、DefaultHeaders 在内置模块;静态文件、CORS、认证属于扩展 crate。

04.4.4.2-046 是否存在内置 Trace 中间件,请求追踪在 actix-web 里怎么做?

一句话结论

actix-web 4 内置 middleware 模块未提供名为 Trace 的通用追踪中间件;请求追踪通常用内置 Logger 输出访问日志,或接入 tracing 生态在中间件/handler 层挂 span,社区集成 crate 需以 crates.io 当前版本为准。

概念解释

任务清单中的 Trace 对应请求级追踪需求:记录请求方法、路径、状态码、耗时与关联标识。actix-web 没有内建等价于 tower-http TraceLayer 的中间件;可行路径是自研 from_fn 中间件在前置创建 span、后置记录状态码,或使用社区 tracing 集成。不确定的具体 crate 名标注待确认。

原理流程

  1. 确定追踪目标:访问日志、结构化 span、跨服务 trace id。
  2. 轻量方案:Logger 输出访问日志。
  3. 结构化方案:中间件前置 tracing::info_span! 绑定请求信息。
  4. 后置读取响应状态码记录事件。
  5. 跨服务用 x-request-id 或 trace 头串联。

代码或图示

async fn tracing_mw(
    req: ServiceRequest,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    let span = tracing::info_span!("request", method = %req.method(), path = %req.path());
    let res = span.in_scope(|| next.call(req)).await?;
    tracing::info!(status = %res.status(), "completed");
    Ok(res)
}

常见误区

  • 假设内置有 middleware::Trace:当前内置清单未列出,勿编造 API。
  • 在 span 内跨 await 持有句柄不当:in_scope 只同步绑定,异步场景按 tracing 文档处理 span 进入方式。

追问

  • 如何把 trace id 传到响应头?答:中间件前置生成或读取 x-request-id,后置写入响应头并记录到 span。
  • 社区有无现成 tracing 集成?答:可检索 crates.io 上 actix-web 与 tracing 集成 crate,版本与维护状态待确认后再引入。

04.4.4.2-047 Logger 日志里如何带上自定义请求标识(request id)?

一句话结论

在最外层中间件生成或读取请求 id 放入请求扩展与请求头,Logger 格式串用请求头占位符引用;响应阶段再把同一 id 写回响应头,便于前后端与日志串联。

概念解释

request id 贯穿访问日志、业务日志与响应头。生成时机要早于 Logger 后置输出:在最外层前置阶段完成。若 id 来自客户端请求头,需校验格式;否则服务端生成 UUID 或雪花标识。Logger 占位符读取请求头的写法以当前版本文档为准。

原理流程

  1. 最外层中间件前置:取 x-request-id,缺失则生成。
  2. 写入请求头与扩展映射。
  3. Logger 格式串引用该请求头输出。
  4. 后置阶段把 id 写入响应头。
  5. 业务日志通过 span 或扩展读取同一 id。

代码或图示

async fn request_id(
    mut req: ServiceRequest,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    let id = req.headers().get("x-request-id")
        .and_then(|v| v.to_str().ok().map(str::to_owned))
        .unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
    req.headers_mut().insert("x-request-id", id.parse().unwrap());
    let mut res = next.call(req).await?;
    res.headers_mut().insert("x-request-id", id.parse().unwrap());
    Ok(res)
}

常见误区

  • id 在 handler 内才生成:Logger 后置拿不到,访问日志缺标识。
  • 信任客户端传入的任意 id 不校验:可能注入脏数据或超长值。

追问

  • 如何在业务 handler 中取到同一 id?答:从请求 extensions 读取,或自定义提取器封装。
  • Logger 与 tracing 都打 id 会不会重复?答:按职责分层,访问日志与结构化 span 各保留一份便于检索。

04.4.4.2-048 NormalizePath 对 /foo/ 与 /foo 路由匹配的影响?

一句话结论

开启 NormalizePath 后,带与不带尾斜杠的请求会按策略归一化到同一模板匹配;未开启时两种写法分别注册或各自 404。

概念解释

路由表按模板精确匹配,/foo 模板不会自动匹配 /foo/。NormalizePath 在匹配前规整路径,使两种访问落到同一 handler。策略选择「去斜杠」还是「补斜杠」影响未注册变体是重定向还是内部改写。

原理流程

  1. 注册模板 /foo。
  2. 请求 /foo/ 进入 NormalizePath。
  3. 按 TrailingSlash 策略规整为 /foo(或反向补斜杠)。
  4. 规整后路径参与匹配。
  5. 命中 handler 或返回 404。

代码或图示

let app = App::new()
    .wrap(NormalizePath::new(TrailingSlash::Trim))
    .route("/foo", web::get().to(handler));

常见误区

  • 同时注册 /foo 与 /foo/ 两个路由:容易触发路径冲突或重复处理。
  • 指望归一化兼容多级 // 空段:斜杠策略不清理重复空段。

追问

  • 尾斜杠策略对重定向 SEO 有影响吗?答:对外站点应统一一种规范 URL,必要时用 301 明确跳转,避免重复收录。
  • 通配路由受影响吗?答:{tail:.*} 捕获剩余段,尾斜杠是否计入 tail 以当前匹配规则为准。

04.4.4.2-049 DefaultHeaders 对 404/500 响应是否也生效?

一句话结论

生效:DefaultHeaders 作为链路上的中间件,对所有经过该层的响应补头,包括框架生成的 404、错误处理器包装的 500 响应。

概念解释

只要响应经过挂有 DefaultHeaders 的链路层,无论由 handler 正常返回还是路由未命中、错误处理器产出,都会经过后置补头。未挂载该层的 Scope/Resource 除外。这也是把通用安全头挂全局的原因之一。

原理流程

  1. 请求未命中路由,框架生成 404 响应。
  2. 响应回溯经过 DefaultHeaders 层。
  3. 按登记表补全缺失的默认头。
  4. 继续向外层返回。
  5. 客户端收到带头的错误响应。

代码或图示

let app = App::new()
    .wrap(DefaultHeaders::new().add(("x-content-type-options", "nosniff")))
    .route("/", web::get().to(handler));

常见误区

  • 以为错误响应不经过中间件:错误响应同样回溯整条链。
  • 在 DefaultHeaders 之外又包一层会删除头的中间件:补全可能被外层抵消。

追问

  • 静态文件响应也会补头吗?答:只要经过同一 App 链路即生效;独立文件服务配置可追加自身头。
  • 如何让某类错误响应不补默认头?答:在更内层 Resource 控制,或默认层按响应状态/路径条件判断。

04.4.4.2-050 ErrorHandlers 与 handler 内部返回的错误如何分工?

一句话结论

handler 内部用类型化错误(实现 ResponseError)表达业务失败并决定状态码;ErrorHandlers 在响应层对最终状态码做统一包装,二者分层:前者决定错误是什么,后者决定响应长什么样。

概念解释

业务校验失败、资源不存在在 handler 内 Err 返回,错误类型带语义。全局 404 JSON 包装、500 脱敏展示由 ErrorHandlers 统一处理。混用会导致错误状态码被覆盖或业务细节泄漏。接口设计时先确定哪些错误由类型负责,哪些由全局层兜底。

原理流程

  1. handler 校验失败返回业务错误枚举。
  2. 错误经 ResponseError 转成基础响应(状态码 + 体)。
  3. 响应回溯经过 ErrorHandlers。
  4. 匹配状态码的处理器做统一包装/脱敏。
  5. 最终响应发出。

代码或图示

#[derive(thiserror::Error, Debug)]
enum ApiError {
    #[error("not found")]
    NotFound,
}

impl ResponseError for ApiError {
    fn status_code(&self) -> StatusCode { StatusCode::NOT_FOUND }
}

async fn item() -> Result<HttpResponse, ApiError> {
    Err(ApiError::NotFound)
}

常见误区

  • 在 ErrorHandlers 里解析业务错误语义:该层只看到响应,拿不到原始错误类型。
  • 业务错误直接 500 交给全局兜底:丢失应有的 4xx 状态码与可操作信息。

追问

  • 错误链上下文如何保留?答:类型化错误携带源错误,ResponseError::error_response 决定对外体;内部链通过日志记录。
  • 全局兜底能否区分预期错误与 panic?答:panic 由 worker 错误处理与日志捕获,预期错误走 Result;分层监控分别统计。

04.4.4.2-051 Compress 与下游自定义 Content-Encoding 头如何配合?

一句话结论

Compress 按协商结果设置 Content-Encoding;下游若已显式声明编码,压缩层不应重复叠加编码,否则客户端按双重编码解码失败。

概念解释

响应 body 的编码由压缩层统一协商。下游 handler 直接返回已压缩字节并手写 Content-Encoding 时,再经过 Compress 会二次处理或覆盖头。常见问题是图片、预压缩文件被重复压缩,或编码头与实际 body 不符导致解压报错。

原理流程

  1. 下游产出 body 与可能的编码声明。
  2. Compress 读取 Accept-Encoding 与现有头。
  3. 未编码 body 按协商压缩并写编码头。
  4. 已是压缩资源则跳过压缩。
  5. 校验响应头与 body 编码一致。

代码或图示

// 预压缩资源:绕过 Compress,在 handler 直接设置编码
async fn precompressed() -> HttpResponse {
    HttpResponse::Ok()
        .insert_header(("content-encoding", "gzip"))
        .body(COMPRESSED_BYTES)
}

常见误区

  • 同一 body 经过两层压缩:编码头只剩一个,字节却被压两次。
  • 压缩后未更新 Content-Length:分块传输场景由 body 帧管理,长度头需与实际一致。

追问

  • 如何按响应类型决定是否压缩?答:在 Scope/Resource 级挂 Compress,文本接口挂、二进制接口不挂;或在中间件按 content-type 判断。
  • Content-Encoding 与 Transfer-Encoding 区别?答:前者表示 body 内容编码,后者表示传输层分帧方式,二者可共存。

04.4.4.2-052 内置中间件哪些需要 feature 开关?

一句话结论

内置中间件随 actix-web 默认编译;特定压缩编码(如 zstd)、TLS、WebSocket 等能力由对应 feature 或独立 crate 控制,具体 feature 名以 actix-web 当前 Cargo.toml 文档为准。

概念解释

actix-web 的可选能力通过 feature 裁剪体积与依赖:压缩算法、TLS 后端(OpenSSL/Rustls)、WebSocket 支持等可能独立开关。引入社区中间件 crate 时再按其文档启用对应 feature。不确定的 feature 名标注待确认,不凭记忆写死。

原理流程

  1. 查 docs.rs actix-web feature 列表。
  2. 在 Cargo.toml 按需启用编码/TLS feature。
  3. 社区 crate(cors、httpauth、ws)单独声明版本。
  4. cargo build 核对编译特性与依赖树。
  5. 发布构建裁剪不需要的 feature。

代码或图示

# Cargo.toml 示例:具体 feature 名以 docs.rs/actix-web 当前版本为准
[dependencies]
actix-web = { version = "4", features = ["compress-zstd"] }
actix-ws = "0.4"

常见误区

  • 照搬旧版本 feature 名:4.x feature 集合可能调整。
  • 在生产构建保留全部压缩算法:增大二进制与编译时间。

追问

  • 如何查看当前启用的 feature?答:cargo tree -e features 或查 Cargo.lock 依赖特征。
  • TLS 属于 actix-web 核心吗?答:TLS 由独立后端集成提供,绑定方法如 bind_rustls/bind_openssl,对应 feature 按文档开启。

04.4.4.2-053 如何在中间件层统一追加安全响应头?

一句话结论

用最外层 DefaultHeaders 或自研 from_fn 中间件后置阶段补全 X-Frame-Options、X-Content-Type-Options、Strict-Transport-Security、Referrer-Policy 等安全头,并按响应类型调整策略。

概念解释

安全头是跨接口的横切职责,适合全局中间件统一处理。HSTS 仅在 HTTPS 下发送;Content-Security-Policy 按页面与接口区分;下载类响应需要 Content-Disposition。全局补默认值,特殊响应在 handler 覆盖。

原理流程

  1. 列出安全头清单与取值策略。
  2. 全局中间件后置阶段插入缺失头。
  3. HTTPS 场景追加 HSTS。
  4. 静态/下载响应按需要覆盖策略。
  5. 用安全头扫描工具复核线上响应。

代码或图示

async fn security_headers(
    req: ServiceRequest,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    let mut res = next.call(req).await?;
    let h = res.headers_mut();
    h.insert("x-frame-options", "DENY".parse().unwrap());
    h.insert("x-content-type-options", "nosniff".parse().unwrap());
    h.insert("referrer-policy", "no-referrer".parse().unwrap());
    Ok(res)
}

常见误区

  • 在内层 handler 逐个接口加安全头:遗漏风险高,应全局兜底。
  • 开发环境也下发 HSTS:浏览器会强制记住 HTTPS,本地调试受影响。

追问

  • 安全头与 CORS 头谁先写入?答:两层独立,顺序不影响最终头;注意不要互相覆盖同名头。
  • 如何给特定路径放宽 CSP?答:在 Resource/Scope 层覆写,全局默认严格策略。

04.4.4.2-054 NormalizePath 与路由冲突:两个路由分别带/不带尾斜杠会怎样?

一句话结论

同时注册 /foo 与 /foo/ 属于同一路径的两个模板,可能触发路由匹配歧义;配合 NormalizePath 时应只保留一种规范写法,避免两套匹配规则并存。

概念解释

路由表对模板精确匹配,尾斜杠是模板的一部分。两个变体都注册后,归一化层改写与原始匹配可能竞争,行为依赖匹配顺序。规范做法是选定一种 URL 风格,另一种由归一化策略重定向或兼容,而不是双注册。

原理流程

  1. 审查路由表是否存在斜杠变体重复。
  2. 确定规范风格(通常无尾斜杠)。
  3. 用 NormalizePath 处理变体兼容。
  4. 删除重复模板。
  5. 集成测试两种访问写法的响应与跳转。

代码或图示

// 推荐:只注册规范模板
let app = App::new()
    .wrap(NormalizePath::new(TrailingSlash::Trim))
    .route("/foo", web::get().to(handler));

常见误区

  • 靠双注册解决兼容:匹配顺序一变行为就变。
  • 归一化与重定向策略不一致:外部链接跳来跳去。

追问

  • 路由冲突在启动期报错还是运行期歧义?答:actix-web 对路径冲突的处理时机以当前版本为准;不确定时用集成测试覆盖。
  • REST 资源集合用尾斜杠吗?答:约定俗成集合与单项均不带尾斜杠,风格在项目内统一即可。

04.4.4.2-055 社区中间件与内置中间件如何选择:Logger 与 tracing 集成?

一句话结论

内置 Logger 满足纯访问日志;需要结构化 span、字段关联、与 OpenTelemetry 对接时选 tracing 生态集成,二者可分层共存,不重复记录同一维度。

概念解释

内置 Logger 输出一行式访问记录,零额外依赖。tracing 提供分层 span、结构化字段、订阅器导出到 Jaeger/OTLP 等。选型看可观测性要求:小项目用 Logger;微服务链路追踪引入 tracing。社区集成 crate 的成熟度需在 crates.io 核对当前版本。

原理流程

  1. 评估日志需求:行式访问记录还是结构化追踪。
  2. 简单场景挂 Logger。
  3. 复杂场景中间件创建请求 span,handler 内记录事件。
  4. 配置 tracing subscriber 导出格式与目标。
  5. 保留 Logger 作为兜底访问日志或关闭避免重复。

代码或图示

use actix_web::middleware::Logger;

let app = App::new()
    .wrap(Logger::default()) // 访问日志兜底
    // tracing span 在自研中间件中创建
    .route("/", web::get().to(handler));

常见误区

  • 同时启用两套详细日志:字段重复、日志量翻倍。
  • 引入未维护的社区 tracing 适配:先核对发布时间与 actix-web 版本兼容。

追问

  • tracing span 如何绑定请求生命周期?答:前置创建 span,后置记录状态码事件;异步任务的 span 传递按 tracing 文档处理。
  • 内置 Logger 能否输出 JSON?答:默认格式为文本;结构化 JSON 需接 tracing 或自定义日志层。

04.4.4.2-056 actix-web-httpauth 提供哪两种认证方案?

一句话结论

actix-web-httpauth 提供 bearer(Bearer Token/JWT 风格)与 basic(Basic 用户名密码)两类认证提取器封装,基于 HttpAuthentication trait 从 Authorization 头解析凭证。

概念解释

该 crate 是 actix-web 生态的 HTTP 认证辅助层,把头解析、凭证校验与拒绝响应收敛到提取器。Bearer 用于 token 场景(JWT、不透明令牌),Basic 用于用户名密码拼装的传统场景。具体类型名与 feature 以 crate 当前版本为准。

原理流程

  1. Cargo.toml 引入 actix-web-httpauth。
  2. 构造认证配置(校验函数或密钥)。
  3. handler 参数使用对应提取器。
  4. 框架从 Authorization 头解析方案与凭证。
  5. 校验失败按 crate 约定返回 401。

代码或图示

# Cargo.toml
actix-web-httpauth = "0.8"
use actix_web_httpauth::extractors::bearer::{BearerAuth, Config};
use actix_web_httpauth::extractors::HttpAuthentication;

async fn profile(auth: HttpAuthentication<BearerAuth>) -> String {
    format!("token={}", auth.token())
}

常见误区

  • 把 httpauth 当会话框架:它只做头解析与校验,会话存储与刷新需自行实现。
  • 忽略 crate 与 actix-web 版本兼容:按其文档匹配 actix-web 4。

追问

  • JWT 校验在该 crate 内完成吗?答:crate 提供提取与方案封装;签名校验通常配合 jsonwebtoken 等库在校验闭包中完成。
  • Basic 凭证格式?答:Authorization: Basic base64(user:pass),crate 负责解码。

04.4.4.2-057 HttpAuthentication 提取器如何在 handler 中使用?

一句话结论

把认证提取器作为 handler 参数,框架在构造参数阶段解析头;校验通过拿到凭证对象,失败由提取器直接返回 401 拒绝,handler 内无需再判空。

概念解释

提取器遵循 actix-web FromRequest 契约:解析 Authorization 头、按方案解码、调用配置的校验逻辑。handler 只接受通过校验的凭证,简化业务函数签名。校验闭包可访问 web::Data 中的密钥或客户端。

原理流程

  1. 构造认证 Config 与校验闭包。
  2. handler 参数声明 HttpAuthentication<BearerAuth>。
  3. 请求进入后提取器解析头。
  4. 校验闭包验证 token/凭证。
  5. 通过则注入参数;失败短路 401。

代码或图示

async fn me(
    bearer: HttpAuthentication<BearerAuth>,
    data: web::Data<AppState>,
) -> Result<HttpResponse, actix_web::Error> {
    let claims = verify_token(bearer.token(), &data.jwt_secret)?;
    Ok(HttpResponse::Ok().json(claims))
}

常见误区

  • 在 handler 里重复解析 Authorization 头:提取器已完成解析。
  • 校验闭包内做阻塞 IO:应使用异步校验或 web::block 转移阻塞操作。

追问

  • 提取器拒绝响应可定制吗?答:通过配置的错误响应或自定义拒绝类型调整,具体 API 查 crate 文档。
  • 多个接口共用认证逻辑放哪?答:提取器复用同一校验配置;跨切面的前置鉴权也可放中间件,二者按是否需要业务对象选择。

04.4.4.2-058 认证失败在 actix-web-httpauth 中返回什么响应?

一句话结论

凭证缺失、格式非法或校验不通过时,提取器返回未认证拒绝,通常映射为 401 状态码并可携带 WWW-Authenticate 头;具体响应体结构以 crate 当前版本为准。

概念解释

HTTP 语义上未认证返回 401,并通过 WWW-Authenticate 告知客户端认证方案。crate 默认行为覆盖常见拒绝场景;业务需要统一 JSON 错误体时,可在提取器配置或外层 ErrorHandlers 包装。注意不要把未认证(401)与无权限(403)混淆。

原理流程

  1. 头缺失或方案不匹配:提取器拒绝。
  2. 凭证解码失败:拒绝。
  3. 校验闭包返回失败:拒绝。
  4. 拒绝转为 401 响应,附认证挑战头。
  5. 外层中间件可统一包装错误体。

代码或图示

// 401 语义:未提供或凭证无效;403 是已认证但无权访问
async fn admin(auth: HttpAuthentication<BearerAuth>) -> Result<HttpResponse, ActixError> {
    if !is_admin(auth.token()) {
        return Err(ActixError::from(Forbidden));
    }
    Ok(HttpResponse::Ok().finish())
}

常见误区

  • 认证失败返回 403:403 表示身份已识别但权限不足。
  • 401 响应不返回 WWW-Authenticate:客户端无法弹出正确登录交互。

追问

  • 如何把 401 体改成项目统一 JSON?答:自定义拒绝响应实现 IntoResponse,或用 ErrorHandlers 按 401 状态码包装。
  • token 过期与无效怎么区分?答:校验层返回细分错误类型,分别映射 401 与提示刷新;HTTP 状态码仍为 401。

04.4.4.2-059 actix-cors 的 Cors 构建器如何配置允许来源、方法、头?

一句话结论

Cors::default() 链式调用 allowed_origin、allowed_methods、allowed_headers、max_age 等方法配置策略,finish() 产出可 wrap 的中间件实例。

概念解释

构建器分别控制 Origin 白名单、HTTP 方法、请求头暴露与允许、预检缓存时长。来源可用精确域名、前缀或通配策略;方法与头用数组传入。配置过宽(全来源全方法)会放大 CSRF 与数据泄露风险,按实际前端域名收敛。

原理流程

  1. Cors::default() 起步。
  2. 白名单来源逐个 allowed_origin。
  3. allowed_methods 列出允许动词。
  4. allowed_headers 列出请求头,expose_headers 列出可读响应头。
  5. finish() 后挂到 App/Scope/Resource。

代码或图示

use actix_cors::Cors;

let cors = Cors::default()
    .allowed_origin("https://app.example.com")
    .allowed_methods(vec!["GET", "POST", "PUT", "DELETE"])
    .allowed_headers(vec!["authorization", "content-type"])
    .expose_headers(vec!["x-request-id"])
    .max_age(3600);

let app = App::new().wrap(cors);

常见误区

  • allowed_origin("*") 同时开启凭证:浏览器规范禁止该组合。
  • 忘记允许 authorization 头:携带 token 的跨域请求被预检拒绝。

追问

  • 多个来源怎么配?答:多次调用 allowed_origin,或按构建器支持的来源匹配器配置。
  • 预检缓存 max_age 作用?答:浏览器缓存预检结果,减少 OPTIONS 请求;过长会使策略变更生效变慢。

04.4.4.2-060 CORS 中间件为什么要放在 wrap 链靠前位置处理预检?

一句话结论

OPTIONS 预检必须在鉴权、路由匹配之前由 CORS 层应答;放在内层会先被 401 或 404 拦截,浏览器拿不到 CORS 头而阻断正式请求。

概念解释

跨域流程中预检是独立请求,不带业务凭证语义。若 CORS 层在鉴权内层,预检先撞上 401,浏览器报告 CORS 错误而非 401。因此 CORS 应挂在 App 外层,先完成预检应答,再让正式请求进入鉴权与业务。

原理流程

  1. 浏览器发送 OPTIONS /api/x 带 Origin 与 ACA 头。
  2. 外层 CORS 层识别预检并返回预检响应。
  3. 正式请求携带凭证进入内层鉴权。
  4. 业务响应带回 CORS 响应头。
  5. 浏览器放行跨域读取。

代码或图示

let app = App::new()
    .wrap(cors)          // 外层:先处理预检
    .wrap(auth_mw)       // 内层:正式请求鉴权
    .route("/api/x", web::get().to(handler));

常见误区

  • 预检被 401 后去排查 token:根因是 CORS 层级错误。
  • 只在正式响应加 CORS 头:预检响应缺失,浏览器仍拦截。

追问

  • 简单跨域请求需要 CORS 层应答吗?答:不发预检,但正式响应仍需带 Access-Control-Allow-Origin。
  • CORS 与 CSRF 防护关系?答:CORS 控制跨域读取,CSRF 防护靠 SameSite Cookie/CSRF Token,二者不互相替代。

04.4.4.2-061 actix-cors 如何允许携带凭证?

一句话结论

构建器调用 supports_credentials() 开启凭证支持,此时允许来源不能用通配 *,必须显式列出可信域名,且响应头会按规范回带凭证标记。

概念解释

跨域请求带 Cookie 或 Authorization 时,服务端必须声明允许凭证,浏览器才会把响应交给页面。规范要求:允许凭证时 Origin 不能为 *,Access-Control-Allow-Methods/Headers 也不能靠通配放宽。配置需同时满足来源白名单与凭证开关。

原理流程

  1. 明确前端可信域名列表。
  2. allowed_origin 逐个配置精确域名。
  3. supports_credentials() 开启。
  4. 预检与正式响应回带凭证允许头。
  5. 浏览器携带 Cookie/Authorization 发送并允许读取响应。

代码或图示

let cors = Cors::default()
    .allowed_origin("https://app.example.com")
    .allowed_methods(vec!["GET", "POST"])
    .allowed_headers(vec!["authorization", "content-type"])
    .supports_credentials();

常见误区

  • 开凭证又 allowed_origin("*"):浏览器拒绝该组合。
  • 以为开凭证就自动放行所有头:允许头仍需显式列出。

追问

  • 凭证模式下 Cookie 还需哪些配套?答:Cookie 设置 SameSite、Secure,后端确认 Path/Domain 匹配。
  • 开发环境 localhost 跨域怎么配?答:白名单加入本地开发来源,生产构建再替换为线上域名。

04.4.4.2-062 限流中间件在 actix-web 中有哪些现成 crate?

一句话结论

常见现成方案是 actix-governor(基于 governor 令牌桶算法的 actix-web 限流中间件);自研可基于 governor、dashmap 或自实现令牌桶挂到 Service 链,具体版本以 crates.io 当前为准。

概念解释

限流按维度(IP、用户、API)在单位时间内放行请求。actix-governor 提供中间件与键提取器;governor 是 Rust 生态常用的限速器库。除 IP 限流外,登录、短信等敏感接口需要更细粒度策略。选型核对 crate 维护状态与 actix-web 版本兼容。

原理流程

  1. 确认限流维度与配额(每秒/每分钟请求数)。
  2. 引入 actix-governor 或自研中间件。
  3. 配置键提取器与超限响应。
  4. 前置阶段计数判断,超限短路 429。
  5. 放行请求进入内层。

代码或图示

# Cargo.toml:版本以 crates.io 当前为准
actix-governor = "0.8"
// 具体配置 API  actix-governor 当前文档为准;此处为结构示意
// RateLimit::builder().key_extractor(peer_ip).limit(100).build()
let app = App::new().route("/api", web::get().to(handler));

常见误区

  • 把单实例限流当成分布式限流:多 worker/多实例需共享计数(Redis 等)。
  • 限流键取错(如全取同一固定值):所有用户共享配额。

追问

  • 429 响应应带什么头?答:Retry-After 提示重试间隔,可选 X-RateLimit-Remaining 等配额头。
  • governor 算法类型?答:令牌桶,支持突发容量与补充速率;具体参数语义查 governor 文档。

04.4.4.2-063 governor 限流器按什么维度计数(KeyExtractor)?

一句话结论

限流维度由键提取器决定:从请求中取客户端 IP、用户 ID、API 路由等组成键,DashMap 或限速器按键分别维护配额;同一键共享桶,不同键独立计数。

概念解释

默认维度常为对端 IP;登录接口按用户名,下单接口按用户 ID,全局接口按路由。键提取器在前置阶段从 ServiceRequest 解析出稳定标识。多实例部署时本地键计数不全局生效,需要外部存储共享。

原理流程

  1. 定义键来源:IP、token 解析出的用户、路径。
  2. 实现提取逻辑生成 String 或结构化键。
  3. 限速器按键取/建桶。
  4. 每个桶记录令牌数与补充时间。
  5. 超限请求短路并记录指标。

代码或图示

fn key(req: &ServiceRequest) -> String {
    req.connection_info().peer_addr()
        .map(|s| s.to_owned())
        .unwrap_or_else(|| "unknown".into())
}

常见误区

  • 键包含可变片段(如完整查询串):同一用户被分散到大量桶。
  • 未登录用户与已登录用户混用 IP 键:共享配额误伤。

追问

  • 如何从请求取对端地址?答:connection_info().peer_addr();反向代理后需正确传递 X-Forwarded-For 并可信解析。
  • 键过期策略?答:本地缓存需清理长期未用的桶,避免内存无限增长。

04.4.4.2-064 自研限流中间件的令牌桶/漏桶如何与 Service 链结合?

一句话结论

自研中间件在前置阶段对键取桶:令牌充足则扣减并调用 next.call,不足则短路 429;桶状态存放在 web::Data 共享的并发结构中,按 worker/实例决定是否需要外部存储。

概念解释

令牌桶允许一定突发,漏桶平滑流出。中间件实现要点:键提取、桶查找与创建、令牌判断、超限响应、指标记录。本地内存实现简单但多实例不全局;分布式限流接 Redis 计数或令牌服务。阻塞操作不进入计数路径。

原理流程

  1. 前置阶段提取限流键。
  2. 从共享映射取桶(不存在则创建)。
  3. 按当前时间补充令牌。
  4. 有令牌:扣减放行;无令牌:返回 429 与 Retry-After。
  5. 响应后置记录配额指标。

代码或图示

struct Bucket { tokens: f64, last: std::time::Instant }

async fn rate_limit(
    req: ServiceRequest,
    data: web::Data<DashMap<String, Bucket>>,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    let key = req.connection_info().peer_addr().unwrap_or("?").to_owned();
    // 补充令牌、判断配额;超限短路 429
    next.call(req).await
}

常见误区

  • 计数映射用 Mutex 包住整表:热点串行,应按桶细分锁或用 DashMap。
  • 桶永不清理:空闲键长期占内存。

追问

  • 令牌补充时间如何计算?答:按距上次补充的时间差乘以补充速率,补到桶上限。
  • 突发量怎么配?答:桶容量大于补充速率,吸收短时突发;容量为 1 即平滑限流。

04.4.4.2-065 熔断中间件如何统计错误率并在半开/关闭/打开状态间切换?

一句话结论

熔断器维护关闭、打开、半开三态:关闭时统计失败率,超阈值进入打开并快速失败;冷却时间后进入半开放少量探测请求,成功恢复关闭、失败回到打开。

概念解释

熔断保护下游依赖不被持续压垮。中间件前置按当前状态决定放行或短路;后置记录成功/失败更新统计。阈值、窗口、冷却时长、探测比例可配置。actix-web 生态可基于 tower 兼容熔断器或自研;状态需跨请求共享。

原理流程

  1. 关闭态:放行请求,滑动窗口统计失败率。
  2. 失败率超阈值:切换打开态,短路返回降级响应。
  3. 冷却计时结束:进入半开态。
  4. 半开放行探测请求:成功则关闭,失败则重新打开。
  5. 状态变更记录指标与日志。

代码或图示

CLOSED --失败率超阈值--> OPEN --冷却结束--> HALF_OPEN
HALF_OPEN --探测成功--> CLOSED
HALF_OPEN --探测失败--> OPEN

常见误区

  • 把熔断当限流:熔断针对下游故障快速失败,限流针对入口流量配额。
  • 半开放行全部流量:应只放少量探测,避免再次压垮。

追问

  • 熔断器状态存哪?答:本地内存 Data 共享;多实例各自熔断,需要全局视图时上报指标。
  • 哪些错误计入失败?答:5xx、超时、连接错误计入;4xx 客户端错误通常不计入下游故障。

04.4.4.2-066 限流与熔断中间件共享状态为什么用 web::Data 加锁?

一句话结论

跨 worker、跨请求共享的计数器/熔断器必须放进 web::Data 包装的 Arc 并发结构;普通字段实例各自独立,计数与状态不可见。锁粒度按桶/状态细分,避免整表互斥。

概念解释

中间件实例按链路构造,本地字段不跨请求共享。全局配额与熔断状态需要 Arc 进入 Data:计数用原子类型,复合结构用 Mutex/RwLock 或 DashMap。锁不能跨 await 持有,IO 与远程调用放到锁外。

原理流程

  1. 启动阶段构造共享状态并 app_data(web::Data::new(...))。
  2. 中间件/handler 提取 Data。
  3. 按键取桶,短临界区更新计数。
  4. 锁释放后再做 IO 与响应构造。
  5. 多实例场景评估是否需要外部存储。

代码或图示

use dashmap::DashMap;

struct State { buckets: DashMap<String, Bucket> }

let app = App::new()
    .app_data(web::Data::new(Arc::new(State { buckets: DashMap::new() })))
    .wrap_fn(rate_limit);

常见误区

  • 在中间件结构体字段放 usize 计数:多实例各计各的。
  • 持锁调用远程校验:阻塞其它请求,应先在锁内取快照再放行校验。

追问

  • 原子计数与 DashMap 怎么选?答:单值计数用原子;按键分桶用 DashMap 或 HashMap<Mutex<Bucket>>。
  • Data 为什么要求 Clone?答:提取时按值克隆 Data 句柄(内部 Arc 克隆),类型本身需可克隆。

04.4.4.2-067 中间件里调用外部鉴权服务要注意什么?

一句话结论

远程鉴权是异步 IO,应在中间件中 await 异步客户端并设置超时;避免阻塞 worker,控制并发与缓存,失败策略(放行/拒绝)按安全等级明确。

概念解释

内部 token 校验可本地完成;第三方鉴权或 introspection 需远程调用。中间件前置等待远程结果期间不占用阻塞线程,但要设超时与并发上限。鉴权结果可短时缓存降低下游压力。安全敏感接口默认拒绝(fail-closed),可降级的只读接口才考虑放行。

原理流程

  1. 提取 token 与请求上下文。
  2. 查本地缓存是否已有结论。
  3. 未命中则异步调用鉴权客户端,带超时。
  4. 成功解析身份写入扩展;失败按策略短路。
  5. 记录鉴权耗时与失败指标。

代码或图示

async fn remote_auth(
    req: ServiceRequest,
    next: Next<impl MessageBody>,
    client: web::Data<reqwest::Client>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    let token = req.headers().get("authorization").cloned();
    let verdict = tokio::time::timeout(
        std::time::Duration::from_secs(2),
        introspect(&client, token),
    ).await;
    // 按 verdict 放行或短路 401
    next.call(req).await
}

常见误区

  • 用同步 HTTP 客户端在中间件阻塞调用:卡住 worker。
  • 远程超时后默认放行:敏感接口形成鉴权绕过。

追问

  • 鉴权结果缓存键是什么?答:token 字符串或其哈希;注意缓存有效期与撤销列表。
  • 鉴权与授权分层怎么做?答:远程鉴权确认「是谁」,handler 内授权判断「能做什么」。

04.4.4.2-068 Basic 认证在生产环境为什么必须配合 HTTPS?

一句话结论

Basic 凭证仅做 Base64 编码、并非加密;明文 HTTP 下可被中间人直接解码拿到用户名密码,生产必须在 TLS 之下使用。

概念解释

Basic 方案把 user:pass Base64 后放入 Authorization 头,编码可逆,不提供机密性。HTTP 链路中任何中间节点都能读取。生产环境 HTTPS 加密传输,Basic 才可接受;现代接口更推荐 Bearer Token 加短期凭证。

原理流程

  1. 浏览器/客户端拼装 user:pass。
  2. Base64 编码后放入请求头。
  3. TLS 链路加密传输。
  4. 服务端解码并校验。
  5. 明文 HTTP 部署时凭证等价公开。

代码或图示

Authorization: Basic dXNlcjE6cGFzc3dvcmQxMjM=
解码后即为 user1:password123

常见误区

  • 以为 Base64 是加密:它只是编码,可直接还原。
  • 内网服务忽略 HTTPS:内网中间人风险仍存在。

追问

  • Basic 适合长期会话吗?答:每次请求都带凭证,难以撤销;短期或运维场景使用,业务接口用令牌。
  • HTTPS 下还要注意什么?答:HSTS、安全 Cookie、凭证不落日志。

04.4.4.2-069 CORS 配置为允许所有来源时凭证相关的限制?

一句话结论

Access-Control-Allow-Origin: * 与凭证(Cookie/Authorization)不能共存;允许凭证时必须显式回显具体 Origin,浏览器才会放行带凭证的跨域响应。

概念解释

规范层面通配来源禁止搭配凭证模式。即使服务端配置了 *,浏览器在带凭证场景下也会拒绝读取响应。需要支持凭证的站点必须维护来源白名单,按请求 Origin 回显匹配项。调试阶段不要用全来源掩盖白名单缺失。

原理流程

  1. 判断接口是否携带凭证。
  2. 无凭证:可使用宽松来源策略。
  3. 有凭证:配置精确白名单并回显匹配 Origin。
  4. 预检与正式响应保持同一策略。
  5. 浏览器校验通过后放行读取。

代码或图示

// 凭证模式:显式来源,不用通配
let cors = Cors::default()
    .allowed_origin("https://app.example.com")
    .supports_credentials();

常见误区

  • 开了 supports_credentials 又用 *:浏览器拦截,调试难定位。
  • 回显任意请求 Origin 而不校验:等同于全来源且带凭证,风险高。

追问

  • 如何按请求 Origin 动态回显白名单内值?答:构建器支持来源匹配时,请求 Origin 命中白名单才回显;具体 API 查 actix-cors 文档。
  • 无凭证的公开 API 可以全来源吗?答:技术上可以,但仍建议按业务最小化开放。

04.4.4.2-070 限流触发后返回的响应状态码与 Retry-After 头怎么设置?

一句话结论

超限请求返回 429 Too Many Requests,并设置 Retry-After 告知客户端等待秒数;可附加剩余配额、重置时间等头便于客户端退避。

概念解释

429 表示因限流被拒绝,区别于 5xx 服务故障。Retry-After 支持秒数或日期;客户端据此做指数退避。响应体说明限流原因与配额窗口。限流指标(被拒次数、键维度)应上报监控,而不是只靠日志。

原理流程

  1. 桶判定无令牌。
  2. 构造 429 响应。
  3. 计算建议等待时长写入 Retry-After。
  4. 可选写 X-RateLimit-Remaining/Reset。
  5. 记录限流指标后返回客户端。

代码或图示

let res = HttpResponse::TooManyRequests()
    .insert_header(("retry-after", "5"))
    .json(serde_json::json!({"error": "rate limited", "retry_after": 5}));
Ok(req.into_response(res))

常见误区

  • 限流返回 503:503 是服务不可用,限流是客户端请求过快,语义不同。
  • 不提供重试间隔:客户端可能立刻重试加剧风暴。

追问

  • 配额头标准有哪些?答:常见 X-RateLimit-Limit/Remaining/Reset,非强制标准,按团队约定。
  • 多实例限流计数不准时 429 会怎样?答:本地桶各自计数,超限判断偏松或偏严;分布式需共享存储。

04.4.4.2-071 actix-web 的 extensions 在请求生命周期中如何传递数据?

一句话结论

每个请求持有一个类型键的扩展映射(Extensions),中间件前置写入、同链路下游提取器/handler 读取,随请求结束销毁;它用于在链路各层之间传递请求级派生数据,区别于全局 web::Data。

概念解释

扩展映射以类型为键存储任意 'static 值。典型链路:认证中间件解析出 Identity 写入请求扩展,handler 自定义提取器取回。请求级数据不跨请求、不跨连接;全局共享状态才放 Data。响应也有独立扩展映射,用于链路后置阶段传递信息。

原理流程

  1. 请求进入链路,创建空扩展映射。
  2. 中间件解析数据并 insert。
  3. 下游按类型 get 读取。
  4. 请求结束,扩展随请求销毁。
  5. 响应扩展在响应回溯阶段使用。

代码或图示

#[derive(Clone)]
struct Identity { user_id: String }

async fn auth(
    mut req: ServiceRequest,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    let identity = Identity { user_id: "u1".into() };
    req.extensions_mut().insert(identity);
    next.call(req).await
}

常见误区

  • 把跨请求缓存放进请求扩展:请求结束即丢失。
  • 用同名不同类型结构写入:类型键冲突时后者覆盖前者。

追问

  • 扩展类型需要 Send + Sync 吗?答:请求在 worker 内传递,约束按 actix-web 当前版本;跨线程场景下放入值需满足对应标记。
  • 如何读取扩展?答:req.extensions().get::<T>() 返回 Option<&T>。

04.4.4.2-072 中间件如何把解析出的用户信息放入 request extensions 供 handler 读取?

一句话结论

中间件前置解析凭证得到身份结构体,req.extensions_mut().insert(identity) 写入;handler 用自定义提取器从 extensions().get::<Identity>() 取出,避免在业务代码重复解析头。

概念解释

链路分层后,认证层负责解析与校验,业务层只消费身份对象。身份类型需在共享模块定义,供中间件与提取器引用。未写入时提取器返回未认证拒绝,形成类型安全的契约。这也是 actix-web 中「横切解析 + 提取器取用」的标准模式。

原理流程

  1. 共享模块定义 Identity 结构体。
  2. 认证中间件校验 token,构造 Identity 插入扩展。
  3. 定义提取器实现 FromRequest/FromRequestParts。
  4. 提取器从扩展取身份,缺失则拒绝。
  5. handler 参数直接使用 Identity。

代码或图示

// 中间件写入
req.extensions_mut().insert(Identity { user_id: "u1".into() });

// 提取器读取(示意)
let identity = req.extensions().get::<Identity>().cloned()
    .ok_or(AuthError::MissingIdentity)?;

常见误区

  • handler 里再自己解析 Authorization:重复逻辑且绕过中间件结论。
  • 身份结构体含非 'static 引用:扩展映射要求 'static 类型。

追问

  • 提取器失败如何返回 401?答:拒绝类型实现 IntoResponse,映射 401 与挑战头。
  • 权限角色也放扩展吗?答:可以,身份与权限组合成一个上下文对象;权限校验仍可在 handler 内细化。

04.4.4.2-073 自定义提取器如何从 extensions 取中间件写入的数据?

一句话结论

提取器实现 actix-web 提取器 trait,在 from_request_parts/from_request 中访问请求扩展映射,按类型取出自定义值;取到则返回,缺失返回拒绝响应。

概念解释

actix-web 提取器从请求构造 handler 参数。读取请求级派生数据属于 FromRequestParts(不消费 body)。扩展查询是提取器与中间件之间的类型化通道。提取器可组合已有提取器(如先取头再解析),最终拒绝类型需可转响应。

原理流程

  1. 定义提取器包装 Identity。
  2. 实现 FromRequestParts。
  3. 从 parts.extensions().get::<Identity>() 取值。
  4. 存在则返回,缺失构造拒绝。
  5. handler 参数声明该提取器类型。

代码或图示

use actix_web::FromRequestParts;

struct AuthUser(Identity);

impl FromRequestParts for AuthUser {
    type Rejection = AuthError;
    async fn from_request_parts(
        parts: &mut actix_web::HttpRequest, _: &actix_web::web::Data<()>,
    ) -> Result<Self, Self::Rejection> {
        parts.extensions().get::<Identity>()
            .cloned().map(AuthUser).ok_or(AuthError::Missing)
    }
}

常见误区

  • 实现了 FromRequest 却不碰 body:应使用 Parts 版本,避免占用最后一位参数。
  • 提取器内做重计算:派生数据应在中间件预处理完成。

追问

  • 提取器需要访问应用状态怎么办?答:trait 方法参数传入 &web::Data<S>,可按类型查询注入数据。
  • 多个提取器读取同一扩展会重复克隆吗?答:get 返回引用,需要持有则 clone;结构体宜 Clone 廉价。

04.4.4.2-074 extensions 与 web::Data 注入的应用状态有何区别?

一句话结论

web::Data 是应用级共享状态,启动时注入、跨请求跨连接存活;request extensions 是请求级派生数据,随请求创建与销毁,类型键存储。

概念解释

二者都是类型化容器,但生命周期与可见范围不同。Data 放连接池、客户端、配置、全局计数器;extensions 放当前请求解析出的身份、追踪 id、临时决策结果。混淆会导致:把请求数据存进 Data 造成跨请求串数据;把全局资源存进扩展则每请求重建。

原理流程

  1. 启动阶段构造全局资源,app_data 注入 Data。
  2. 请求到达后创建请求扩展映射。
  3. 中间件把请求级结果写入扩展。
  4. handler 同时取用 Data(全局)与扩展(请求级)。
  5. 请求结束扩展销毁,Data 存活到服务停机。

代码或图示

let app = App::new()
    .app_data(web::Data::new(pool))   // 全局:跨请求共享
    .wrap_fn(auth)                     // 写入请求扩展
    .route("/me", web::get(me));

常见误区

  • 在 Data 里存每请求可变上下文:被所有请求共享污染。
  • 每次请求新建 HTTP 客户端放扩展:应复用 Data 中的客户端。

追问

  • Data 提取出来是克隆对象吗?答:克隆的是 Data 句柄(内部 Arc 克隆),指向同一底层对象。
  • 响应扩展与请求扩展用途区分?答:请求扩展向前传递给下游;响应扩展在回溯链路中向后层传递后置阶段信息。

04.4.4.2-075 响应 extensions 与请求 extensions 分别用在哪?

一句话结论

请求扩展在前置链路从中间件向 handler 传递派生数据;响应扩展在回溯链路从内层向外层传递后置阶段信息(如下游标记、指标、内部决策),两者生命周期与方向不同。

概念解释

ServiceResponse 持有响应扩展映射。内层 service/handler 可在响应上写入标记,外层中间件后置阶段读取。典型用途:内层标记「该响应需要额外压缩/记录审计」,外层据此处理。不要把请求身份等前置数据放到响应扩展回溯查找。

原理流程

  1. 请求阶段:扩展随 ServiceRequest 向下传递。
  2. handler 产出响应,可写入响应扩展。
  3. 响应回溯经过中间件后置阶段。
  4. 外层读取响应扩展做决策。
  5. 响应发出后扩展销毁。

代码或图示

// 内层写入响应标记
res.extensions_mut().append(AuditMark::new());

// 外层后置读取
if res.extensions().get::<AuditMark>().is_some() {
    audit_log(&res);
}

常见误区

  • 用响应扩展向前传请求数据:方向相反,外层前置时响应尚未产生。
  • 响应扩展存大对象:随响应复制移动,应放句柄或引用。

追问

  • 响应扩展类型键冲突如何排查?答:按类型唯一定义,审计标记等用新类型包装避免与标准类型撞键。
  • 两个中间件都写同一标记会覆盖吗?答:同类型 insert 覆盖;需要多条记录用列表类型或 append 语义,按当前 API 确认。

04.4.4.2-076 中间件如何生成并回写 request id 到响应头?

一句话结论

最外层前置阶段读取或生成 x-request-id,写入请求头与扩展;后置阶段把同一标识写回响应头,使访问日志、业务日志与客户端报错共享同一追踪键。

概念解释

request id 要在链路最前端确定,避免内层日志缺标识。客户端传入时校验格式与长度,缺失由服务端生成(UUID 或雪花式)。后置阶段从请求扩展取同一值写响应,保证进出标识一致。该模式与 04.4.4.3 实战中的 tracing 接入衔接。

原理流程

  1. 前置:读 x-request-id,无则生成。
  2. 校验后写入请求头与请求扩展。
  3. 业务链路按扩展中的 id 记录日志。
  4. 后置:从扩展取回 id 写入响应头。
  5. 客户端报错时携带 id 即可检索服务端日志。

代码或图示

async fn request_id(
    mut req: ServiceRequest,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    let id = req.headers().get("x-request-id")
        .and_then(|v| v.to_str().ok().map(str::to_owned))
        .filter(|s| !s.is_empty())
        .unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
    req.extensions_mut().insert(RequestId(id.clone()));
    req.headers_mut().insert("x-request-id", id.parse().unwrap());
    let mut res = next.call(req).await?;
    res.headers_mut().insert("x-request-id", id.parse().unwrap());
    Ok(res)
}

常见误区

  • 后置阶段重新生成 id:与请求日志不一致。
  • 直接信任超长或含换行的客户端 id:注入脏数据,需长度与字符集校验。

追问

  • id 如何进入 tracing span?答:中间件把 id 放入 span 字段或扩展,后续日志事件携带同一字段。
  • 反向代理已生成 id 怎么办?答:约定可信代理头,校验后透传;不可信来源重新生成。

04.4.4.2-077 在中间件中读取 Cookie、Session 的常用方式?

一句话结论

Cookie 从请求头 Cookie 解析(actix-web 提供 Cookie 类型与提取器);Session 由会话 crate 包装存储后端,中间件/handler 通过会话访问器读取,中间件层只做前置读取与注入。

概念解释

Cookie 头是分号分隔的键值对,框架提供解析与 Cookie 结构体。会话机制在 Cookie 中存会话标识,服务端按标识取状态(内存/Redis/数据库)。actix 生态会话由独立 crate 提供,具体名称与 API 以 crates.io 当前版本为准。中间件可读取会话判断登录态,但会话读写宜在 handler 或专用提取器完成。

原理流程

  1. 中间件前置读取 Cookie 头。
  2. 解析目标 Cookie 值或会话标识。
  3. 必要时把身份/会话状态写入请求扩展。
  4. 下游 handler 通过会话访问器读写。
  5. 响应阶段会话 crate 回写 Cookie。

代码或图示

use actix_web::cookie::Cookie;

async fn session_mw(
    req: ServiceRequest,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    let token = req.headers()
        .get("cookie")
        .and_then(|h| h.to_str().ok())
        .and_then(|s| s.split("; ").find(|p| p.starts_with("session=")))
        .and_then(|p| p.strip_prefix("session="))
        .map(str::to_owned);
    req.extensions_mut().insert(SessionToken(token));
    next.call(req).await
}

常见误区

  • 在中间件直接解密/校验会话内容:存储后端与校验逻辑应由会话层封装。
  • 把敏感会话值写进访问日志:泄漏会话标识。

追问

  • Cookie 的 HttpOnly/Secure/SameSite 在哪设置?答:响应阶段由会话 crate 或 handler 设置 Cookie 属性,防止 XSS 窃取与 CSRF。
  • 会话过期在中间件怎么判断?答:读取会话状态中的过期时间或由后端返回未登录,再短路 401/重定向。

04.4.4.2-078 如何避免中间件写入的扩展类型被同名覆盖?

一句话结论

扩展以 Rust 类型为键,使用项目内专属 newtype 包装身份、标记、id 等数据,避免与标准类型或其它中间件撞键;同一语义只由一个中间件写入。

概念解释

Extensions 没有字符串命名空间,键就是类型本身。String、u64 这类通用类型极易与其它层冲突。规范做法是为每种派生数据定义独立结构体(Identity、RequestId、AuditMark),类型即命名空间。写入方单一化,读取方按类型查找。

原理流程

  1. 为请求级数据定义专属结构体。
  2. 明确唯一写入中间件。
  3. 读取方按类型查询。
  4. 冲突风险高的数据用新type包装。
  5. 代码评审检查扩展类型清单。

代码或图示

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

#[derive(Clone)]
struct Identity { user_id: String, roles: Vec<String> }

// 不要把 String 直接作为扩展键
// req.extensions_mut().insert("u1".to_owned()); // 易与其它 String 冲突

常见误区

  • 用 String/i64 直接存扩展:类型键撞车被覆盖。
  • 多个中间件写同一身份类型:后写覆盖前写,语义混乱。

追问

  • 扩展需要实现 Clone 吗?答:读取时常 cloned() 取出,派生数据宜实现 Clone;类型需满足 'static。
  • 调试时如何列出当前扩展类型?答:扩展映射未暴露便捷枚举接口;可在写入点打点记录类型名,或自查代码中的 insert 调用。

04.4.4.2-079 请求体在中间件层被读取后,handler 还能再读吗?

一句话结论

不能直接再读:HTTP body 是一次性流式消费,中间件读取后 body 已被排空;需要下游再用时,应在中间件缓存 body 字节并以可复用的方式放回请求,或改为在提取器/handler 层读取。

概念解释

actix-web 请求 body 由 Payload 流提供,帧按序消费一次。中间件若读取 body 做校验、签名计算,消费后下游 Json/Bytes 提取器拿不到数据。常见解法是中间件聚合完整 body 到 Bytes,再包装成新的 body 传给下游;body 大小需限制,避免内存放大。

原理流程

  1. 中间件决定是否需要预检 body。
  2. 流式聚合(限制最大字节)得到 Bytes。
  3. 基于副本做校验/签名计算。
  4. 把 Bytes 包装为新 body 放回 ServiceRequest。
  5. 下游提取器从新 body 读取。

代码或图示

// 示意:聚合 body 后回灌;具体 body 包装类型以 docs.rs 当前版本为准
let bytes = web::Bytes::from(/* 聚合结果 */);
// req 上替换 body,再 next.call(req).await

常见误区

  • 中间件读完 body 直接放行:下游解析空 body 报错。
  • 不限制聚合大小:恶意大 body 撑爆内存。

追问

  • 签名校验通常在哪一层做?答:按架构选择中间件统一验签,或在 handler 提取器内完成;需要 body 副本时注意缓存成本。
  • 流式大上传适合在中间件预检吗?答:不适合聚合,应在 handler 内流式处理并边读边校验。

04.4.4.2-080 中间件里记录耗时与状态码的完整做法?

一句话结论

前置阶段记录开始时间,调用下游后在后置阶段读取响应状态码与耗时,结合请求方法、路径、id 输出访问日志;失败响应与 panic 场景也要有兜底记录。

概念解释

耗时统计必须包住完整下游调用:从 next.call 之前到响应返回之后。状态码从 ServiceResponse::status() 读取。日志字段包括方法、路径模板、状态码、耗时、request id。被短路的请求同样经过外层后置,因此最外层记录最完整。

原理流程

  1. 前置:Instant::now(),读取方法/路径/id。
  2. next.call(req).await? 拿到响应。
  3. 计算 elapsed,读取 res.status()。
  4. 输出结构化访问日志。
  5. 错误路径由错误处理器与兜底日志补全。

代码或图示

async fn timing(
    req: ServiceRequest,
    next: Next<impl MessageBody>,
) -> Result<ServiceResponse<impl MessageBody>, Error> {
    let start = std::time::Instant::now();
    let method = req.method().clone();
    let path = req.path().to_owned();
    let res = next.call(req).await;
    let elapsed = start.elapsed();
    match &res {
        Ok(r) => tracing::info!(%method, %path, status = %r.status(), elapsed = ?elapsed, "request"),
        Err(e) => tracing::error!(%method, %path, error = %e, elapsed = ?elapsed, "request failed"),
    }
    res
}

常见误区

  • 只在成功分支记耗时:错误请求无日志。
  • 耗时不含排队等待:若需要纯业务耗时,应在 handler 内部单独计时。

追问

  • 路径记录原始 URI 还是模板?答:原始路径便于复现,模板便于聚合;两者可同时记录。
  • 慢请求如何标记?答:后置阶段按耗时阈值打 slow 标记并上报指标。

04.4.4.2-081 actix Actor trait 定义了哪些关联类型与生命周期钩子?

一句话结论

Actor trait 声明 type Context 关联类型,并提供 started、stopping、stopped 等生命周期钩子;actor 实例在其上下文内被调度,状态变更通过消息处理驱动。

概念解释

actix::Actor 是 actor 实现的入口:Context 决定运行上下文类型(如 Context<Self> 普通上下文、SyncContext 多线程上下文)。钩子在生命周期节点由运行时回调:启动后、停止判定时、销毁前。actor 字段即私有可变状态,外部只能通过消息交互。

原理流程

  1. 结构体实现 Actor,指定 type Context = Context<Self>。
  2. 实现生命周期钩子(按需覆写)。
  3. Actor::start 或 Supervisor::start 启动实例。
  4. 运行时回调 started。
  5. 停止流程依次经过 stopping、stopped。

代码或图示

use actix::{Actor, Context};

struct Counter { count: usize }

impl Actor for Counter {
    type Context = Context<Self>;

    fn started(&mut self, ctx: &mut Self::Context) {
        println!("actor started, addr={:?}", ctx.address());
    }

    fn stopped(&mut self, _: &mut Self::Context) {
        println!("actor stopped, final count={}", self.count);
    }
}

常见误区

  • 在 actor 结构体字段里放需要跨线程共享的句柄:actor 状态由自身消息循环独占。
  • 直接调用 actor 方法修改状态:必须发消息由 Handler 处理。

追问

  • stopping 钩子返回什么?答:返回 Running/Stop 决策控制是否继续停止,具体枚举名以 actix 0.13 文档为准。
  • Context 与 SyncContext 区别?答:Context 绑定单线程 arbiter,SyncContext 用于多线程同步 actor 支持,按 actor 类型选择。

04.4.4.2-082 Message trait 与 Handler trait 如何配合定义一条消息?

一句话结论

Message 声明消息类型及其 Result 返回类型;Handler<M> 在 actor 上实现 handle 方法处理该消息并返回结果;二者配对定义 actor 可接收的消息协议。

概念解释

消息是 actor 间通信的不可变输入。Message trait 关联 Result 类型,决定 send 请求的返回值。Handler::handle 接收消息与可变上下文,更新内部状态并产出结果。一个 actor 可为多种消息实现多个 Handler,形成协议面。

原理流程

  1. 定义消息结构体(可携带字段)。
  2. impl Message for Msg { type Result = ...; }。
  3. 在 actor 上 impl Handler<Msg>。
  4. handle 内更新状态、返回 Result。
  5. 外部通过 Addr 发送该消息。

代码或图示

use actix::{Actor, Context, Message, Handler, Addr};

#[derive(Message)]
#[rtype(result = "usize")]
struct Add(usize);

impl Handler<Add> for Counter {
    type Result = usize;

    fn handle(&mut self, msg: Add, _: &mut Context<Self>) -> Self::Result {
        self.count += msg.0;
        self.count
    }
}

常见误区

  • Message::Result 与 Handler::Result 类型不一致:编译期 trait 约束报错。
  • 消息携带可变引用:actor 消息应拥有数据或传克隆引用,避免跨循环引用。

追问

  • #[rtype(...)] 宏做什么?答:简化 Message 的 Result 关联类型声明;宏形式与 actix 版本配套,以 docs.rs 当前为准。
  • 消息可以没有返回值吗?答:可以,Result = (),用 do_send/try_send 发 Fire-and-forget 消息。

04.4.4.2-083 Addr 与 Recipient 两种引用类型有何区别?

一句话结论

Addr<A> 是 actor 的通用地址,可发送该 actor 支持的所有消息;Recipient<M> 是针对某条消息类型的类型化接收端,只暴露该消息的发送接口,用于解耦具体 actor 类型。

概念解释

持有 Addr<A> 依赖具体 actor 类型;Recipient<M> 把「能处理消息 M 的接收方」抽象出来,多个 actor 可实现同一消息协议,订阅者只持有 Recipient。Addr::recipient() 可把地址转换为某消息的 Recipient。事件分发、观察者模式常用 Recipient 列表。

原理流程

  1. 启动 actor 得到 Addr<A>。
  2. 需要多态接收方时调用 addr.recipient::<M>()。
  3. 保存 Recipient<M> 到订阅表。
  4. 发送时 recipient.send(msg),不暴露 actor 类型。
  5. actor 更换只要仍实现 Handler<M> 即可替换。

代码或图示

let addr: Addr<Counter> = Counter { count: 0 }.start();
let recipient: Recipient<Add> = addr.recipient();

// 订阅表:Vec<Recipient<Events>>

常见误区

  • 用 Addr<具体Actor> 做事件订阅:新增订阅方必须引入 actor 类型,耦合反向。
  • 同一 Addr 为不同消息取多个 Recipient:这是正常用法,各自独立类型化。

追问

  • Recipient 内部保存什么?答:转发到对应 actor mailbox 的发送端点,不持有 actor 本身。
  • 断开订阅如何移除?答:订阅表按 Recipient 相等性或订阅 id 移除;Recipient 相等性支持情况以文档为准。

04.4.4.2-084 消息发送的 do_send / try_send / send 各自语义是什么?

一句话结论

do_send 无条件入队、不检查 mailbox 可用性且无返回结果;try_send 尝试入队并返回邮箱错误;send 是异步请求-响应,等待 actor 处理并返回 Message::Result。

概念解释

三种发送对应不同耦合度:do_send 最快但可能向关闭 actor 投递;try_send 同步判断邮箱状态;send 返回 Request future,.await 拿到处理结果或邮箱错误。需要背压与结果用 send;通知类事件用 do_send/try_send。

原理流程

  1. 判断是否需要处理结果:需要则 send。
  2. 通知场景选 do_send(不检查)或 try_send(检查邮箱)。
  3. 消息进入 actor mailbox。
  4. actor 循环取出消息调用 Handler::handle。
  5. send 结果通过请求通道返回发送方。

代码或图示

// Fire-and-forget
addr.do_send(Add(1));

// 检查邮箱
match addr.try_send(Add(1)) { Ok(_) => {}, Err(e) => println!("mailbox: {e}") }

// 请求-响应
let count = addr.send(Add(10)).await?;

常见误区

  • 用 do_send 后期待结果:它不返回任何值。
  • 在 actor 内部 await self.send(...) 给自己发消息:形成自等待死锁。

追问

  • send 返回的 Request 可以不 await 吗?答:可以丢弃,但处理结果与错误将被忽略;丢弃前确认事件可容忍丢失。
  • mailbox 关闭后哪种发送最先报错?答:try_send 同步返回邮箱错误;send 在 await 时返回错误;do_send 不报告。

04.4.4.2-085 Actor 上下文 Context 提供哪些常用能力?

一句话结论

Context<A> 提供地址获取、消息计划任务(run_later)、向自己发消息(notify)、停止 actor(stop)、派生子 actor 与状态读写等能力,是 actor 运行时与外部交互的句柄。

概念解释

上下文在 started/handle/stopping 等钩子中以 &mut 传入。常用方法:address() 取 Addr,run_later(duration, cb) 延迟执行闭包,notify/notify_later 向自己发消息,stop() 终止,spawn 派生异步任务。上下文还维护 mailbox 与生命周期状态。

原理流程

  1. actor 钩子拿到 &mut Context<Self>。
  2. 需要自引用时 ctx.address()。
  3. 定时任务用 run_later 注册闭包。
  4. 内部事件用 ctx.notify(Msg) 入队自身消息。
  5. 满足退出条件调用 ctx.stop()。

代码或图示

impl Handler<Tick> for Worker {
    type Result = ();
    fn handle(&mut self, _: Tick, ctx: &mut Context<Self>) -> Self::Result {
        self.tick += 1;
        if self.tick >= 10 {
            ctx.stop();
        } else {
            ctx.run_later(std::time::Duration::from_secs(1), |act, ctx| {
                ctx.notify(Tick);
            });
        }
    }
}

常见误区

  • 在 handle 里阻塞等待外部结果:占用 actor 消息循环,后续消息排队。
  • 把上下文保存到 actor 字段:上下文仅在钩子调用期间有效。

追问

  • run_later 与 notify_later 区别?答:前者注册闭包回调,后者延迟向自己发一条消息;按是否需要消息协议选择。
  • 上下文能否访问 web::Data?答:actor 在启动时通过构造函数或消息注入共享句柄,上下文本身不携带 actix-web 应用状态。

04.4.4.2-086 Actor 生命周期:started、stopping、stopped 钩子何时触发?

一句话结论

started 在 actor 启动后首次调度前触发;stopping 在停止流程中决定是否继续退出;stopped 在实例销毁前做资源清理;三者构成启动-停止-销毁的回调链。

概念解释

生命周期由 arbiter 驱动。started 适合初始化定时任务、获取地址;stopping 可根据在途消息或连接决定推迟停止;stopped 释放持有资源(连接、订阅注销、文件句柄)。钩子不应当做长时间阻塞操作,清理逻辑要快速完成。

原理流程

  1. Actor::start 创建实例与上下文。
  2. 运行时回调 started。
  3. 消息循环处理消息;满足条件后进入停止。
  4. stopping 判定是否停止,可返回继续运行。
  5. 最终 stopped 清理后销毁实例。

代码或图示

impl Actor for SessionActor {
    type Context = Context<Self>;

    fn started(&mut self, ctx: &mut Self::Context) {
        ctx.run_later(Duration::from_secs(30), |act, ctx| ctx.stop());
    }

    fn stopped(&mut self, _: &mut Self::Context) {
        self.subscriptions.clear();
    }
}

常见误区

  • 在 stopped 里发跨 actor 消息:实例即将销毁,应在 stopping 或外部清理流程处理。
  • 把初始化放构造函数:拿不到上下文与地址,需要在 started 完成。

追问

  • stopping 如何推迟停止?答:返回继续运行的决策枚举,保留在途工作;具体枚举名以 actix 0.13 文档为准。
  • actor panic 会触发 stopped 吗?答:panic 中断当前消息处理,重启行为由 Supervisor/arbiter 决定,清理钩子执行情况需结合监督策略验证。

04.4.4.2-087 Supervisor 如何监督失败重启的 actor,重启策略是什么?

一句话结论

Supervisor 包装 actor 启动并在其失败后按策略重启;默认在 actor 停止/失败时重建实例,可配置重启策略与重启次数限制,监督者不参与业务消息处理。

概念解释

监督模式把容错从 actor 自身剥离:actor 崩溃后由 Supervisor 决定是否重启。Supervisor::start 接收工厂闭包创建新实例。重启策略控制何时重建(失败即重启、按错误类型、限制次数)。状态不自动保留,需要持久化或在重启后从外部恢复。

原理流程

  1. Supervisor::start(|_| Actor::new()) 注册工厂。
  2. 被监督 actor 启动并处理消息。
  3. 处理失败或停止触发监督逻辑。
  4. 按策略决定重建实例。
  5. 新实例从初始状态运行,必要时加载外部状态。

代码或图示

use actix::{Supervisor, Actor, Context, Handler, Message};

let addr: Addr<Worker> = Supervisor::start(|_| Worker { retry: 0 });

常见误区

  • 以为重启后内存状态自动恢复:实例是新建的,字段回到初始值。
  • Supervisor 承担业务路由:它只做生命周期监督。

追问

  • 重启策略有哪些可选项?答:actix 提供重启策略枚举,如始终重启、失败重启等;具体变体名以 docs.rs/actix 当前版本为准。
  • 无限重启风暴怎么防护?答:限制重启次数、退避间隔,并上报崩溃指标。

04.4.4.2-088 一个后台 actor 如何在 App 启动时创建并把 Addr 注入 web::Data?

一句话结论

在构造 App 前用 Actor::start 或 Supervisor::start 创建后台 actor 得到 Addr,再 app_data(web::Data::new(addr)) 注入;handler/中间件提取 web::Data<Addr<Worker>> 后发消息。

概念解释

actor 生命周期应先于 HTTP 服务就绪。启动阶段创建 actor 并共享其地址;Addr 可克隆跨 worker 传递。注入类型需满足 Clone + Send + Sync + 'static。停机时 actor 随系统 arbiter 停止,需要优雅关闭时显式通知。

原理流程

  1. 启动阶段构造后台 actor 并 start 得到 Addr。
  2. App::new().app_data(web::Data::new(addr))。
  3. handler 提取 web::Data<Addr<Worker>>。
  4. 业务调用 addr.send(Msg).await。
  5. 服务停机时通知 actor 清理并退出。

代码或图示

let worker = Worker::new().start();

let app = App::new()
    .app_data(web::Data::new(worker))
    .route("/jobs", web::post(enqueue));

async fn enqueue(
    data: web::Data<Addr<Worker>>,
    body: web::Json<Job>,
) -> Result<HttpResponse, actix_web::Error> {
    let id = data.send(JobMsg(body.0)).await?.into_inner();
    Ok(HttpResponse::Created().json(id))
}

常见误区

  • 在每个 handler 内 Actor::start:每请求新建 actor,状态与邮箱失控。
  • 注入 Addr 后忽略停机通知:后台任务随进程退出,资源未释放。

追问

  • 多 worker 共享同一个 Addr 吗?答:注入的是同一 Addr 句柄克隆,指向同一 actor mailbox;actor 自身运行在启动它的 arbiter 上。
  • actor 需要访问数据库池怎么办?答:启动时把 Data<Pool> 克隆进 actor 构造函数,actor 内部持有句柄。

04.4.4.2-089 web handler 与 Actor 之间如何通信,边界在哪里?

一句话结论

handler 通过注入的 Addr 向 actor 发消息并 await 结果;边界是 handler 不直接访问 actor 字段,actor 不依赖 actix-web 请求类型,二者经消息协议解耦。

概念解释

HTTP 请求是短生命周期,actor 是长生命周期后台实体。handler 负责协议适配(解析请求、构造消息、包装响应),actor 负责内部状态与后台逻辑。消息类型在共享 crate 定义,避免 web 层与 actor 层双向依赖。同步阻塞的业务不适合放进 actor 消息循环。

原理流程

  1. handler 接收请求并校验参数。
  2. 构造 actor 消息,addr.send(msg).await。
  3. actor Handler::handle 处理并返回结果。
  4. handler 把结果转成 HTTP 响应。
  5. actor 内部定时任务与后台事件不经过 handler。

代码或图示

// 共享协议:JobMsg 定义在公共模块
async fn submit(
    worker: web::Data<Addr<Worker>>,
    req: web::Json<SubmitReq>,
) -> Result<HttpResponse, actix_web::Error> {
    let resp = worker.send(JobMsg(req.0.job)).await.map_err(actix_web::Error::from)?;
    Ok(HttpResponse::Accepted().json(resp))
}

常见误区

  • handler 持有 actor 内部可变引用:破坏封装,编译期即被 actor 模型阻止。
  • actor 消息里带 HttpRequest:请求类型不能跨 actor 生命周期持有。

追问

  • 后台任务结果如何推回 handler?答:请求-响应由 send 返回;异步完成的通知经 actor → 订阅者/通道 → SSE/WebSocket,不直接回绑原 handler。
  • 哪些逻辑更适合直接在 handler 用 tokio task?答:无共享可变状态、无需串行消息队列的短任务,不必引入 actor。

04.4.4.2-090 Actor 内部可变状态为什么不需要锁?

一句话结论

actor 状态只在其消息循环所在线程被访问,消息串行处理,不存在并发竞争,因此字段无需 Mutex/RwLock;跨 actor 共享才需要消息传递或并发结构。

概念解释

actor 模型的封装性来自「单邮箱串行处理」:同一时刻只有一条消息在 handle 中执行,状态读写没有数据竞争。这与 Arc<Mutex<T>> 共享内存模型互补。若 actor 状态需要被其它线程直接读取,说明边界设计错误,应通过消息暴露快照。

原理流程

  1. actor 字段为普通可变结构体。
  2. mailbox 消息按序取出。
  3. handle 串行执行,独占状态访问。
  4. 处理完取下一条消息。
  5. 外部只能经消息查询或变更状态。

代码或图示

struct Counter { count: usize } // 无需 Mutex

impl Handler<Add> for Counter {
    type Result = usize;
    fn handle(&mut self, msg: Add, _: &mut Context<Self>) -> usize {
        self.count += msg.0;
        self.count
    }
}

常见误区

  • 给 actor 字段套 Mutex:增加成本且不符合模型;锁用于跨线程共享而非 actor 内部。
  • 在 handle 中把 &mut self 传出 mailbox:逃逸到其它线程会破坏串行假设。

追问

  • SyncContext 下状态还免锁吗?答:多线程同步 actor 的并发模型不同,需按 actix 文档确认其状态访问约束,不能照搬单线程结论。
  • 状态快照怎么给外部?答:定义查询消息,handle 返回克隆快照(Clone 的只读数据)。

04.4.4.2-091 actix actor 的 mailbox 默认容量与消息队列行为是什么?

一句话结论

actor mailbox 是连接发送方与消息循环的队列;容量策略(有界/无界)与默认上限以 actix 0.13 文档为准,消息按入队顺序被串行取出,关闭后投递按发送方式返回不同错误。

概念解释

mailbox 解耦发送速度与处理速度。无界队列在生产积压时可能占用大量内存;有界队列配合 try_send 实现背压。actix 的邮箱抽象区分可检查可用性的发送通道。具体默认容量、是否提供有界邮箱构造,标注待确认并查 docs.rs。

原理流程

  1. 发送方把消息写入 mailbox。
  2. arbiter 调度消息循环取出队首消息。
  3. 调用对应 Handler::handle。
  4. 处理结果经请求通道返回(send 场景)。
  5. actor 停止后邮箱关闭,后续投递进入错误路径。

代码或图示

send/try_send/do_send -> [mailbox queue] -> actor message loop -> Handler::handle

常见误区

  • 假设 mailbox 有固定默认上限:actix 版本间策略可能不同,需查文档确认。
  • 积压消息不监控:无界队列缓慢膨胀最终 OOM。

追问

  • 如何观察 mailbox 积压?答:在 actor 内记录队列长度指标,或监控 try_send 失败率;actix 暴露的邮箱统计接口以文档为准。
  • 消息会按优先级排序吗?答:默认 FIFO;优先级需自定义消息类别与调度逻辑。

04.4.4.2-092 什么情况下 actor 会死锁?

一句话结论

典型死锁是 actor 在 handle 中同步等待自己发出的请求结果(自等待),或多个 actor 循环互等响应;消息循环被阻塞后后续消息全部排队,表现为 actor 无响应。

概念解释

actor 串行处理:当前 handle 未返回前不会处理下一条消息。若在 handle 内 .await 给自己的 send,结果消息排在邮箱尾部,永远等不到;两个 actor 互等对方响应形成循环等待。外部持锁再回调 actor 也可能间接死锁。

原理流程

  1. actor A 处理消息时向 A 自身发送请求。
  2. 请求消息进入 A 邮箱尾部。
  3. handle 阻塞等待响应。
  4. 消息循环无法取出下一条,响应无法产生。
  5. A 挂起,上游超时。

代码或图示

// 反例:在自己的 Handler 里 await 自己的 send
impl Handler<Ask> for Worker {
    type Result = usize;
    fn handle(&mut self, msg: Ask, ctx: &mut Context<Self>) -> Self::Result {
        // 错误:同步等待自身邮箱;正确做法是直接计算或改异步编排
        // let _ = ctx.address().send(Ping).await;
        0
    }
}

常见误区

  • 在 actor 内调用同步阻塞库:卡住消息循环,等价于假死。
  • 多 actor 链路形成环:A 等 B、B 等 C、C 等 A。

追问

  • 如何排查 actor 无响应?答:监控邮箱积压、send 超时与线程 dump;检查 handle 内是否有阻塞调用或自等待。
  • 跨 actor 等待怎么避免?答:用消息编排(请求-回调、事件订阅)替代同步嵌套等待,缩短等待链。

04.4.4.2-093 mailbox 溢出如何处理与背压?

一句话结论

邮箱积压时应基于有界队列与 try_send 拒绝新消息、返回限流/排队错误,并在发送侧做退避;监控积压深度与拒绝率,必要时扩容 actor 分片或降级后台任务。

概念解释

背压要求下游处理能力反向约束上游投递。actor 模型天然串行,单 actor 吞吐有限:积压说明消费速度跟不上。处理手段:邮箱有界化、发送方 try_send 感知拒绝、消息合并/丢弃低优先级任务、按键分片多个 actor。无界堆积只靠重启无法根治。

原理流程

  1. 监控 mailbox 深度与 try_send 错误。
  2. 达到水位后新消息被拒绝或进入外部队列。
  3. 发送侧退避重试。
  4. 分析慢消息与单点热点。
  5. 分片/扩容或降级非关键任务。

代码或图示

match addr.try_send(Event::new(payload)) {
    Ok(_) => {}
    Err(actix::MailboxError::Closed) => return Err(ServiceUnavailable.into()),
    Err(e) => return Err(TooManyRequests.into()),
}

常见误区

  • 积压后盲目重启 actor:内存中的队列丢失,且重建后再次积压。
  • 所有消息同等优先级:应允许丢弃可重建的低价值事件。

追问

  • actix 邮箱错误类型有哪些?答:MailboxError 区分关闭、容量等情形,具体变体以 docs.rs/actix 当前版本为准。
  • 多实例如何分摊消息?答:按消息键哈希分片到多个 actor,各自独立邮箱与队列。

04.4.4.2-094 Actor 与 tokio task 相比,适用与不适用场景分别是什么?

一句话结论

Actor 适合需要串行封装可变状态、消息协议、监督重启与订阅分发的长生命周期实体;tokio task 适合无共享可变状态的异步 IO 并发与一次性任务,共享状态用通道/并发结构协作。

概念解释

actor 把状态、邮箱、监督打包成抽象;tokio task 是轻量执行单元,状态共享需显式 Arc/通道。选 actor 的理由:领域实体天然串行变更、需要订阅观察者、失败重启管理。选 tokio 的理由:纯 IO 并发、请求级任务、状态无竞争。现代 Rust 后端中 tokio task 与通道是更常见的默认选择。

原理流程

  1. 判断是否有需要独占封装的可变状态。
  2. 有状态实体 + 消息协议/订阅/监督:actor。
  3. 无状态 IO 并发:tokio spawn 加通道。
  4. 跨任务共享数据:Arc 加锁或 mpsc 通道。
  5. 混合场景:后台实体用 actor,请求内并发用 task。

代码或图示

// tokio task:一次性异步任务
tokio::spawn(async move {
    let _ = do_work().await;
});

// actor:封装计数状态与消息协议
let addr = Counter { count: 0 }.start();

常见误区

  • 为每个 HTTP 请求起 actor:task 更轻量,actor 邮箱与监督开销不必要。
  • 用 actor 包装无状态 HTTP 客户端调用:徒增消息跳转层。

追问

  • actix-web handler 能直接 spawn tokio task 吗?答:可以在兼容运行时中 spawn;任务生命周期与 'static 约束按 actix-rt/tokio 互操作规则确认。
  • 事件订阅用 actor 还是 tokio 广播通道?答:一对多通知可用 tokio::sync::broadcast;需要接收方类型化协议与生命周期管理时用 actor 订阅表。

04.4.4.2-095 actix-ws 为什么强调 without actors,WebSocket 处理如何脱离 actor?

一句话结论

actix-ws 0.4 把 WebSocket 会话建模为异步任务加读写流,不再要求连接是一个 actix actor;握手后得到 session 与消息流,用普通 async 循环处理收发。

概念解释

早期 actix-web WebSocket 示例把连接实现为 Actor,每个连接一个 actor 邮箱。actix-ws 改为基于 future/stream 的原生异步实现:handle 返回响应、会话句柄与入站流,spawn 一个任务驱动循环。这与 tokio 生态流式模型一致,减少 actor 样板。

原理流程

  1. handler 接收 HttpRequest 与 web::Payload。
  2. actix_ws::handle(&req, pl) 完成握手。
  3. 得到 (response, session, incoming)。
  4. spawn 任务中遍历 incoming,用 session.text/close 回写。
  5. 断开或错误时退出循环并清理资源。

代码或图示

async fn ws(
    req: HttpRequest,
    pl: web::Payload,
) -> Result<HttpResponse, actix_web::Error> {
    let (res, mut session, incoming) = actix_ws::handle(&req, pl)?;
    actix_web::rt::spawn(async move {
        while let Some(Ok(msg)) = incoming.next().await {
            session.text(format!("echo: {msg}")).await.ok();
        }
        session.close(None).await.ok();
    });
    Ok(res)
}

常见误区

  • 仍按旧文档把连接实现成 Actor:actix-ws 模式下不需要。
  • 忘记 spawn 驱动 incoming 流:握手后无人消费消息。

追问

  • actix-ws 依赖 actix actor crate 吗?答:其定位是 without actors,运行在 actix-web 异步任务上;具体依赖以 crate 当前清单为准。
  • 连接状态存哪?答:任务闭包内局部状态,或共享 Data 中的连接表;断开时从表中移除。

04.4.4.2-096 现代 actix-web 4 中 actor 模型的地位与替代方案是什么?

一句话结论

actix-web 4 自身路由与 handler 已完全异步化,actor 模型退为可选后台机制;多数后台任务用 tokio task 加通道实现,actor 仅在需要消息封装、监督重启、类型化订阅时保留。

概念解释

早期 actix 生态以 actor 为核心,web 连接、后台实体都建模为 actor。当前版本 handler 直接返回 future,WebSocket 也脱离 actor。替代方案:tokio::spawn + mpsc/broadcast 做任务与事件,Arc 并发结构共享状态,监督逻辑用任务重启循环手写。引入 actix actor 前先判断是否真需要其模型。

原理流程

  1. 梳理后台职责:任务、状态实体、事件分发。
  2. 无状态任务:tokio task。
  3. 事件广播:broadcast 通道。
  4. 有串行状态实体:评估 actor 或 Mutex 保护的任务。
  5. 需要监督重启:actor Supervisor 或手写重启循环。

代码或图示

旧模式:连接/后台服务 -> actix Actor + mailbox
当前:handler future + rt::spawn task + tokio channel/Arc 共享

常见误区

  • 沿用十年前 actix 教程把一切做成 actor:样板重且与 tokio 生态割裂。
  • 完全否定 actor:复杂有状态实体与订阅场景它仍有抽象价值。

追问

  • actix-web 4 是否强制依赖 actix actor crate?答:web 核心不强制;引入 actor 后台服务需单独依赖 actix crate。
  • 团队技术栈以 tokio 为主怎么选?答:优先 tokio task 与通道,actor 仅作为局部可选抽象,避免双运行时模型认知成本。

04.4.4.2-097 ractor 与 actix actor 框架有何差异?

一句话结论

ractor 是纯 Rust actor 库,绑定 tokio 运行时、消息基于 Rust 类型;actix actor 框架自带 arbiter 运行时与监督体系,历史上与 actix-web 生态深度集成。两者消息模型相似,运行时与生态绑定不同。

概念解释

ractor 提供 actor、消息、监督与集群扩展,执行在 tokio 上;actix 0.13 有自己的 arbiter/上下文抽象。选型时看运行时一致性:全 tokio 栈 ractor 接入更自然;已在 actix 生态内复用 actix actor 成本低。两者 API 概念(消息、Handler、地址、监督)可互译,但类型不能直接互通。

原理流程

  1. 确认项目主运行时:tokio 还是 actix-rt。
  2. tokio 优先:评估 ractor 的消息与监督 API。
  3. actix 生态内:复用 actix crate。
  4. 核对 crate 维护状态、文档完整度与版本兼容。
  5. 小范围验证消息吞吐与错误恢复。

代码或图示

ractor:  Actor + Message + tokio runtime + Supervisor
actix:   Actor + Message + actix arbiter/Context + Supervisor/System

常见误区

  • 把两个框架的地址类型混用:各自 mailbox 抽象不兼容。
  • 只按「都是 actor」选库:运行时绑定与生态成熟度差异实际影响落地。

追问

  • ractor 是否支持分布式?答:ractor 有集群相关扩展组件,具体能力与版本以其 crates.io 文档为准,标注待确认后再用于生产。
  • actix actor 能跑在 tokio 运行时上吗?答:actix-rt 基于 tokio 封装,互操作边界按当前版本文档确认;不要假设两套运行时可任意嵌套。

04.4.4.2-098 如何在 actix System 中启动一个 actor 并等待其退出?

一句话结论

通过 System::new 建立运行时,Actor::start 在系统 arbiter 上启动 actor;等待退出可订阅停止事件或在系统信号处理中 system.stop(),具体阻塞/等待 API 以 actix 0.13 文档为准。

概念解释

System 是 actix 运行时顶层上下文,管理 arbiter 与信号。普通 web 服务由 HttpServer 启动;独立 actor 程序需要显式建 System、启动 actor、驱动事件循环。actor 退出后系统可停止或继续运行其它 arbiter。生产 HTTP 服务一般不手写 System 等待,而用 HttpServer 的停机流程。

原理流程

  1. System::new("main") 创建系统。
  2. Actor::start(实例) 挂载到 arbiter。
  3. 系统运行事件循环。
  4. actor 满足条件 ctx.stop()。
  5. 外部收到停止信号后 System::current().stop() 退出循环。

代码或图示

use actix::{Actor, System, Context, Handler, Message};

let system = System::new("app");
let addr = Worker::new().start();
// 系统驱动直到 stop;阻塞运行方式按 actix 版本 API 确认
system.run()

常见误区

  • 在 actix-web 服务里再手动建嵌套 System:运行时重复,应用 HttpServer 与注入 Addr。
  • 启动后不持有系统句柄:arbiter 可能提前退出。

追问

  • Arbiter 与 System 关系?答:System 管理一组 arbiter,每个 arbiter 是独立事件循环执行单元;具体层级以文档为准。
  • 如何优雅停止后台 actor?答:发停止消息,actor 在 stopping/stopped 清理,再通知系统退出。

04.4.4.2-099 Actor 之间如何订阅与取消订阅(Recipient 列表)?

一句话结论

发布者维护 Vec<Recipient<Event>>,订阅者把自己某消息类型的 Recipient 注册进来;事件到来遍历发送,断开或取消时按标识从列表移除。

概念解释

Recipient<M> 屏蔽具体 actor 类型,只保留「能处理 M」的能力。订阅表存在发布者 actor 内部,变更通过注册/注销消息完成。遍历发送时注意单个订阅者邮箱关闭不影响其它订阅方;移除失效 recipient 防止列表膨胀。

原理流程

  1. 定义事件消息 Event。
  2. 订阅者实现 Handler<Event>,构造自身 Recipient<Event>。
  3. 向发布者发 Subscribe(Recipient<Event>)。
  4. 发布者把 recipient 存入列表。
  5. 事件触发遍历 recipient.do_send(Event);注销消息移除条目。

代码或图示

struct Broker { subs: Vec<Recipient<Event>> }

impl Handler<Subscribe> for Broker {
    type Result = ();
    fn handle(&mut self, msg: Subscribe, _: &mut Context<Self>) {
        self.subs.push(msg.0);
    }
}

impl Handler<Broadcast> for Broker {
    type Result = ();
    fn handle(&mut self, msg: Broadcast, _: &mut Context<Self>) {
        for sub in &self.subs {
            let _ = sub.do_send(Event(msg.0.clone()));
        }
    }
}

常见误区

  • 订阅表存在 actor 外部加锁:破坏 actor 封装,应放入 broker 内部。
  • 不清理关闭的 recipient:列表持续增长,失效发送累积错误。

追问

  • 如何判断 recipient 已失效?答:do_send 不报告错误;需要检测用 try_send 检查邮箱并移除失败项。
  • 订阅者多类型事件怎么注册?答:为每种事件维护独立 Recipient 列表,或消息枚举统一分发。

04.4.4.2-100 一个定时统计后台 actor 的完整骨架怎么写?

一句话结论

定义统计 actor 与查询/增量消息,started 中用 run_later 周期调度自消息,Handler 更新计数并响应查询;启动后把 Addr 注入 web 状态供接口读取指标。

概念解释

该骨架串联 actor 主要要素:状态字段、消息协议、生命周期钩子、定时自调度、请求-响应与外部注入。定时任务通过 run_later 回调再 notify 自身消息实现周期循环;查询消息返回当前快照。生产中再加持久化、阈值告警与停机清理。

原理流程

  1. 定义 CounterActor { count, last_reset }。
  2. 定义 Increment、Snapshot 消息及其 Result。
  3. started 注册首次延迟 tick。
  4. Tick 处理器周期重置/上报并安排下一次。
  5. web 层注入 Addr,查询接口返回快照。

代码或图示

use actix::{Actor, Context, Message, Handler};
use std::time::Duration;

#[derive(Message)] #[rtype(result = "()")] struct Increment(u64);
#[derive(Message)] #[rtype(result = "u64")] struct Snapshot;
#[derive(Message)] #[rtype(result = "()")] struct PeriodicTick;

struct StatsActor { count: u64 }

impl Actor for StatsActor {
    type Context = Context<Self>;
    fn started(&mut self, ctx: &mut Context<Self>) {
        ctx.run_later(Duration::from_secs(60), |_, ctx| ctx.notify(PeriodicTick));
    }
}

impl Handler<Increment> for StatsActor {
    type Result = ();
    fn handle(&mut self, msg: Increment, _: &mut Context<Self>) { self.count += msg.0; }
}
impl Handler<Snapshot> for StatsActor {
    type Result = u64;
    fn handle(&mut self, _: Snapshot, _: &mut Context<Self>) -> u64 { self.count }
}
impl Handler<PeriodicTick> for StatsActor {
    type Result = ();
    fn handle(&mut self, _: PeriodicTick, ctx: &mut Context<Self>) {
        self.count = 0;
        ctx.run_later(Duration::from_secs(60), |_, ctx| ctx.notify(PeriodicTick));
    }
}

常见误区

  • 定时回调闭包捕获外部可变状态:应通过 actor 字段与消息更新。
  • 查询接口直接读 actor 字段:必须经 send(Snapshot) 取快照。

追问

  • 周期任务漂移怎么处理?答:按固定间隔调度并记录上次执行时间,避免堆积;具体调度策略结合负载调整。
  • 指标如何暴露给监控?答:actor 定期把快照推送到指标客户端,或 web 查询接口拉取供采集器抓取。