3.Rust + Axum 提取器模式深度剖析

摘要

深入解读 Rust + Axum 提取器模式，涵盖内置提取器及自定义实现。

一、引言

在 Rust 的 Web 开发领域，Axum 作为一款轻量级且高效的 Web 框架，为开发者提供了强大的功能。其中，提取器（Extractor）模式是 Axum 中一个非常重要的特性，它允许开发者从 HTTP 请求中提取所需的数据，并将其转换为合适的 Rust 类型。通过提取器，开发者可以方便地处理查询参数、JSON 数据、表单数据等，同时还能进行数据验证和错误处理。本文将深入剖析 Axum 提取器模式，包括内置提取器的使用场景、自定义提取器的实现以及错误处理与 FromRequest trait 的设计。

二、内置提取器的使用场景

2.1 Query 提取器

Query 提取器用于从 URL 的查询字符串中提取数据。在处理 GET 请求时，查询字符串通常用于传递一些可选的参数。例如，我们有一个处理用户搜索请求的 API，用户可以通过查询字符串指定搜索关键词和分页信息。以下是一个示例：

rust 复制代码

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

#[derive(Deserialize)]
struct SearchParams {
    keyword: String,
    page: u32,
}

async fn search(Query(params): Query<SearchParams>) -> String {
    format!("Searching for '{}' on page {}", params.keyword, params.page)
}

#[tokio::main]
async fn main() {
    let app = Router::new()
      .route("/search", get(search));

    axum::Server::bind(&"127.0.0.1:3000".parse().unwrap())
      .serve(app.into_make_service())
      .await
      .unwrap();
}

在这个示例中，SearchParams 结构体使用 serde::Deserialize 进行反序列化，Query 提取器会自动将查询字符串中的参数转换为 SearchParams 结构体的实例。当客户端访问 /search?keyword=rust&page=1 时，服务器会返回相应的搜索信息。

2.2 Json 提取器

Json 提取器用于从请求体中提取 JSON 数据。在处理 POST、PUT 等请求时，客户端通常会将数据以 JSON 格式发送到服务器。以下是一个处理用户注册请求的示例：

rust 复制代码

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

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

async fn register(Json(user): Json<UserRegistration>) -> String {
    format!("User '{}' registered successfully", user.username)
}

#[tokio::main]
async fn main() {
    let app = Router::new()
      .route("/register", post(register));

    axum::Server::bind(&"127.0.0.1:3000".parse().unwrap())
      .serve(app.into_make_service())
      .await
      .unwrap();
}

在这个示例中，UserRegistration 结构体使用 serde::Deserialize 进行反序列化，Json 提取器会自动将请求体中的 JSON 数据转换为 UserRegistration 结构体的实例。当客户端发送包含 JSON 数据的 POST 请求到 /register 时，服务器会处理注册逻辑。

2.3 Form 提取器

Form 提取器用于从表单数据中提取信息。在处理 HTML 表单提交时，表单数据通常以 application/x-www-form-urlencoded 或 multipart/form-data 格式发送到服务器。以下是一个处理用户登录表单的示例：

rust 复制代码

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

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

async fn login(Form(form): Form<LoginForm>) -> String {
    format!("User '{}' is trying to log in", form.username)
}

#[tokio::main]
async fn main() {
    let app = Router::new()
      .route("/login", post(login));

    axum::Server::bind(&"127.0.0.1:3000".parse().unwrap())
      .serve(app.into_make_service())
      .await
      .unwrap();
}

在这个示例中，LoginForm 结构体使用 serde::Deserialize 进行反序列化，Form 提取器会自动将表单数据转换为 LoginForm 结构体的实例。当客户端提交登录表单时，服务器会处理登录逻辑。

三、自定义提取器实现请求数据验证

有时候，内置提取器可能无法满足我们的需求，我们需要自定义提取器来实现更复杂的请求数据验证。例如，我们希望对用户输入的邮箱地址进行格式验证。以下是一个自定义提取器的示例：

rust 复制代码

use axum::{
    extract::{FromRequest, RequestParts},
    http::Request,
    body::Body,
    response::{IntoResponse, Response},
};
use serde::Deserialize;
use validator::Validate;
use validator::email::Email;

#[derive(Deserialize, Validate)]
struct UserRegistration {
    #[validate(email)]
    email: String,
    password: String,
}

struct ValidatedUserRegistration(UserRegistration);

#[axum::async_trait]
impl FromRequest<Body> for ValidatedUserRegistration {
    type Rejection = Response;

    async fn from_request(req: &mut RequestParts<Body>) -> Result<Self, Self::Rejection> {
        let Json(user) = axum::extract::Json::<UserRegistration>::from_request(req).await.map_err(|e| {
            (axum::http::StatusCode::BAD_REQUEST, e.to_string()).into_response()
        })?;

        if let Err(errors) = user.validate() {
            return Err((axum::http::StatusCode::BAD_REQUEST, errors.to_string()).into_response());
        }

        Ok(ValidatedUserRegistration(user))
    }
}

async fn register(ValidatedUserRegistration(user): ValidatedUserRegistration) -> String {
    format!("User with email '{}' registered successfully", user.email)
}

在这个示例中，我们定义了一个 UserRegistration 结构体，并使用 validator 库对邮箱地址进行格式验证。然后，我们自定义了一个 ValidatedUserRegistration 提取器，在 from_request 方法中，首先使用 Json 提取器提取请求体中的 JSON 数据，然后对数据进行验证。如果验证失败，返回一个包含错误信息的响应；如果验证成功，返回一个包含验证后数据的 ValidatedUserRegistration 实例。

四、错误处理与 FromRequest trait 设计

4.1 FromRequest trait

FromRequest 是 Axum 中用于定义提取器的核心 trait。当我们自定义提取器时，需要实现 FromRequest trait。该 trait 有两个关联类型：Rejection 表示提取失败时返回的类型，from_request 方法用于从请求中提取数据。以下是 FromRequest trait 的基本定义：

rust 复制代码

#[async_trait::async_trait]
pub trait FromRequest<B>
where
    B: Send + 'static,
{
    type Rejection: IntoResponse;

    async fn from_request(req: &mut RequestParts<B>) -> Result<Self, Self::Rejection>;
}

4.2 错误处理

在自定义提取器的 from_request 方法中，我们需要处理各种可能的错误。当提取数据失败或数据验证不通过时，我们需要返回一个合适的错误响应。在前面的自定义提取器示例中，我们使用 axum::http::StatusCode::BAD_REQUEST 表示请求数据无效，并将错误信息作为响应体返回。这样，客户端可以根据返回的状态码和错误信息进行相应的处理。

五、总结

Axum 的提取器模式为 Rust Web 开发提供了强大而灵活的功能。通过内置提取器，我们可以方便地处理查询参数、JSON 数据和表单数据；通过自定义提取器，我们可以实现更复杂的请求数据验证。同时，FromRequest trait 和错误处理机制确保了提取器的可靠性和可维护性。在实际开发中，合理运用提取器模式可以提高代码的可读性和可维护性，为构建高效、安全的 Web 应用提供有力支持。