Actix-web 4.9.0认证中间件返回错误的实现问题排查

核心问题梳理 #

Actix-web 4.x 对中间件的类型约束更严格，Either 的误用是导致类型不匹配的常见原因——只有当需要返回两种不同响应体类型的分支时才需要用它，普通的认证失败场景直接返回标准错误即可。

1. 定义认证配置结构体 #

use actix_web::{
    dev::{Service, ServiceRequest, ServiceResponse, Transform},
    Error, HttpResponse,
};
use futures_util::{future::LocalBoxFuture, FutureExt};
use std::task::{Context, Poll};

// 存储验证所需的token
#[derive(Clone)]
pub struct AuthConfig {
    pub valid_token: String,
}

2. 实现中间件工厂（Transform trait） #

Transform 负责将中间件注入服务链，注意泛型参数的约束必须匹配 Actix-web 的要求：

pub struct AuthFactory {
    config: AuthConfig,
}

impl AuthFactory {
    pub fn new(config: AuthConfig) -> Self {
        Self { config }
    }
}

impl<S, B> Transform<S, ServiceRequest> for AuthFactory
where
    S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error> + 'static,
    S::Future: 'static,
    B: 'static,
{
    type Response = ServiceResponse<B>;
    type Error = Error;
    type Transform = AuthMiddleware<S>;
    type InitError = ();
    type Future = LocalBoxFuture<'static, Result<Self::Transform, Self::InitError>>;

    fn new_transform(&self, service: S) -> Self::Future {
        let config = self.config.clone();
        async move { Ok(AuthMiddleware { service, config }) }.boxed_local()
    }
}

3. 实现核心认证中间件（Service trait） #

这里直接通过 Result 分支处理验证逻辑，无需滥用 Either：

pub struct AuthMiddleware<S> {
    service: S,
    config: AuthConfig,
}

impl<S, B> Service<ServiceRequest> for AuthMiddleware<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<'static, Result<Self::Response, Self::Error>>;

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

    fn call(&self, req: ServiceRequest) -> Self::Future {
        let config = self.config.clone();
        let mut service = self.service.clone();

        async move {
            // 从Authorization头提取token（格式：Bearer <token>）
            let token = req.headers()
                .get("Authorization")
                .and_then(|h| h.to_str().ok())
                .and_then(|h| h.strip_prefix("Bearer "));

            // 验证token
            if token != Some(&config.valid_token) {
                // 验证失败，返回401错误
                return Err(Error::from(HttpResponse::Unauthorized().json("Invalid or missing token")));
            }

            // 验证通过，传递请求到下一个服务
            service.call(req).await
        }.boxed_local()
    }
}

4. 中间件注册与使用 #

use actix_web::{web, App, HttpServer};

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    let auth_config = AuthConfig {
        valid_token: "my-secure-token-123".to_string(),
    };

    HttpServer::new(move || {
        App::new()
            .wrap(AuthFactory::new(auth_config.clone()))
            .route("/protected", web::get().to(|| async { "Authenticated access granted" }))
    })
    .bind(("127.0.0.1", 8080))?
    .run()
    .await
}

Either 的正确使用场景 #

只有当你需要返回两种不同响应体类型时才需要用 EitherBody 包裹，比如验证失败返回字符串，正常请求返回 JSON：

use actix_web::body::EitherBody;

// 调整中间件的Response类型为ServiceResponse<EitherBody<B, String>>
// 在call方法中分支处理：
if token_invalid {
    let err_resp = HttpResponse::Unauthorized().body("Invalid token").map_into_right_body();
    Ok(err_resp)
} else {
    let resp = service.call(req).await?;
    Ok(resp.map_into_left_body())
}

常见类型错误排查 #

• 确保 Transform 和 Service 的泛型参数完全符合 Actix-web 的生命周期与类型约束
• 错误返回必须使用 Actix-web 提供的 Error 类型（可通过 Error::from(HttpResponse) 或预定义的 ErrorUnauthorized 构造）
• 所有分支的返回值类型必须统一，避免出现不一致的响应体类型

内容的提问来源于stack exchange，提问作者JACK M