Rust 异步 Web 框架 Axum：核心原理与实战进阶

一、Axum 框架的架构与核心组件

1.1 Axum 的设计理念

Axum 是建立在 Tokio 异步运行时之上的 Rust Web 框架，由 Tokio 团队官方维护。它的设计初衷很明确：既要利用 Rust 的类型系统保证安全，又要提供足够的灵活性让开发者按需组合功能。

核心特点包括：

模块化：通过中间件、请求提取器和响应映射器，你可以像搭积木一样构建应用。
类型安全：编译期就能发现很多潜在错误，减少运行时崩溃。
异步优先：完全基于 Tokio，充分利用现代硬件的并发能力。
易用性：API 设计直观，新手能快速上手，老手也能发挥极限性能。

1.2 核心组件详解

1.2.1 请求提取器

请求提取器（Extractor）是 Axum 最迷人的部分之一。它负责从 HTTP 请求中解析数据，比如路径参数、查询字符串或请求体。内置了多种提取器，也支持自定义。

内置提取器示例：

use axum::{extract::Path, response::IntoResponse, routing::get, Router};

async fn get_user(Path(user_id): Path<i32>) -> impl IntoResponse {
    format!("Get user with ID: {}", user_id)
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/users/:id", get(get_user));
    axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
        .serve(app.into_make_service())
        .await
        .unwrap();
}

自定义提取器示例：有时候我们需要更复杂的逻辑，比如从 Header 中提取用户代理。

use axum::{async_trait, extract::FromRequestParts, http::request::Parts, response::IntoResponse, routing::get, Router};

 ();


 <()>   {
      = ();

      (parts: & Parts, _state: &())  <, ::Rejection> {
        parts.headers.()
            .(|value| value.().())
            .(|s| (s.()))
            .(())
    }
}

  (agent: UserAgent)    {
    (, agent.)
}


  () {
      = Router::().(, (get_user_agent));
    axum::Server::(&.().())
        .(app.())
        .
        .();
}

use axum::{async_trait, extract::FromRequestParts, http::request::Parts, response::IntoResponse, routing::{get, post}, Router}; use jsonwebtoken::{decode, encode, Algorithm, DecodingKey, EncodingKey, Header, Validation}; use serde::{Deserialize, Serialize}; use std::time::{Duration, SystemTime, UNIX_EPOCH}; #[derive(Debug, Serialize, Deserialize)] struct Claims { sub: String, exp: usize, } impl Claims { fn new(sub: &str) -> Self { let expiration = SystemTime::now() .checked_add(Duration::from_secs(3600)) .unwrap() .duration_since(UNIX_EPOCH) .unwrap() .as_secs() as usize; Claims { sub: sub.to_string(), exp: expiration } } } struct JwtSecret(String); #[async_trait] impl FromRequestParts<JwtSecret> for Claims { type Rejection = (); async fn from_request_parts(parts: &mut Parts, state: &JwtSecret) -> Result<Self, Self::Rejection> { parts.headers.get("authorization") .and_then(|value| value.to_str().ok()) .and_then(|s| s.strip_prefix("Bearer ").map(|s| s.to_string())) .and_then(|token| { decode::<Claims>(&token, &DecodingKey::from_secret(state.0.as_bytes()), &Validation::new(Algorithm::HS256)).ok() }) .map(|data| data.claims) .ok_or(()) } } async fn login() -> impl IntoResponse { let claims = Claims::new("user123"); let token = encode(&Header::new(Algorithm::HS256), &claims, &EncodingKey::from_secret(b"secret")).unwrap(); token } async fn protected(claims: Claims) -> impl IntoResponse { format!("Welcome, {}", claims.sub) } #[tokio::main] async fn main() { let secret = JwtSecret("secret".to_string()); let public_routes = Router::new().route("/login", post(login)); let protected_routes = Router::new() .route("/protected", get(protected)) .with_state(secret.clone()); let app = public_routes.merge(protected_routes); axum::Server::bind(&"0.0.0.0:3000".parse().unwrap()) .serve(app.into_make_service()) .await .unwrap(); }

Rust 异步 Web 框架 Axum：核心原理与实战进阶