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

响应映射器

响应映射器负责将请求处理函数的返回值转换为 HTTP 响应。Axum 允许通过实现 IntoResponse trait 来自定义响应格式。

内置与自定义示例：

use axum::{http::StatusCode, response::IntoResponse, routing::get, Router};
use serde_json::json;

struct ApiResponse {
    code: i32,
    message: String,
    data: serde_json::Value,
}

impl IntoResponse for ApiResponse {
    fn into_response(self) -> axum::response::Response {
        let status = if self.code == 200 { StatusCode::OK } else { StatusCode::BAD_REQUEST };
        (status, json!({"code": self.code, "message": self.message, "data": self.data})).into_response()
    }
}

async fn get_user() -> ApiResponse {
    ApiResponse {
        code: 200,
        message: "Success".to_string(),
        data: json!({"id": 1, "name": "张三", "email": "[email protected]"}),
    }
}

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

中间件

中间件是 Axum 中用于请求和响应处理的通用组件，可以在请求到达路由之前或响应返回客户端之前执行特定逻辑，如身份验证、日志记录、CORS 处理等。

使用 tower_http 内置中间件：

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

async fn handler() -> &'static str { "Hello, World!" }

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

二、Axum 框架的路由系统

2.1 路由的定义与匹配

Axum 的路由系统基于路径匹配，支持静态路径、动态路径参数和通配符路径。

静态与动态路径：

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

async fn get_product(Path((category_id, product_id)): Path<(i32, i32)>) -> impl IntoResponse {
    format!("Get product {} in category {}", product_id, category_id)
}

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

通配符路径：

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

async fn catch_all(Path(path): Path<String>) -> impl IntoResponse {
    format!("Not found: {}", path)
}

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

2.2 路由的嵌套与组合

Axum 支持路由的嵌套与组合，允许开发者将相关的路由组织成模块，提高代码的可读性和可维护性。

路由嵌套：

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

async fn create_user() -> impl IntoResponse { "User created successfully" }

#[tokio::main]
async fn main() {
    let user_routes = Router::new()
        .route("/:id", get(|p: Path<i32>| format!("Get user {}", p.0)))
        .route("/", post(create_user));
    let app = Router::new().nest("/users", user_routes);
    axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
        .serve(app.into_make_service())
        .await
        .unwrap();
}

2.3 路由的状态共享

Axum 支持通过 Router.with_state 共享数据，如数据库连接池、配置信息等。

use axum::{extract::State, response::IntoResponse, routing::get, Router};
use sqlx::PgPool;
use std::sync::Arc;

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

async fn get_user_count(State(state): State<AppState>) -> impl IntoResponse {
    // 实际项目中需处理 error
    format!("Total users: 100")
}

#[tokio::main]
async fn main() {
    let state = AppState { /* init logic */ };
    let app = Router::new()
        .route("/users/count", get(get_user_count))
        .with_state(state);
    axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
        .serve(app.into_make_service())
        .await
        .unwrap();
}

三、Axum 框架的高级功能

3.1 WebSocket 支持

Axum 提供了对 WebSocket 的原生支持，允许开发者实现实时通信功能。

use axum::{extract::WebSocketUpgrade, response::IntoResponse, routing::get, Router};
use tokio_tungstenite::tungstenite::Message;

async fn websocket_handler(ws: WebSocketUpgrade) -> impl IntoResponse {
    ws.on_upgrade(|mut socket| async move {
        println!("WebSocket connection established");
        while let Some(msg) = socket.next().await {
            match msg {
                Ok(Message::Text(text)) => {
                    println!("Received text message: {}", text);
                    socket.send(Message::Text(format!("Echo: {}", text))).await.unwrap();
                }
                Ok(Message::Binary(data)) => {
                    println!("Received binary message with length: {}", data.len());
                    socket.send(Message::Binary(data)).await.unwrap();
                }
                Ok(Message::Close(frame)) => {
                    println!("WebSocket connection closing: {:?}", frame);
                }
                Err(e) => {
                    println!("WebSocket error: {:?}", e);
                }
                _ => {}
            }
        }
        println!("WebSocket connection closed");
    })
}

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

3.2 流式请求与响应

Axum 支持流式处理请求体和响应体，适用于处理大量数据的场景。

流式响应示例：

use axum::{body::Body, response::IntoResponse, routing::get, Router};
use futures::stream::{self, StreamExt};
use http_body_util::Full;

async fn stream_response() -> impl IntoResponse {
    let items = vec!["First item", "Second item", "Third item"];
    let stream = stream::iter(items).map(|item| Ok::<_, std::io::Error>(Full::new(item.as_bytes())));
    Body::wrap_stream(stream)
}

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

3.3 错误处理与响应

Axum 提供了灵活的错误处理机制，允许开发者自定义错误类型和错误响应。

use axum::{extract::Path, http::StatusCode, response::{IntoResponse, Response}, routing::get, Router};
use serde_json::json;
use thiserror::Error;

#[derive(Error, Debug)]
enum AppError {
    #[error("User not found")]
    UserNotFound,
    #[error("Invalid request")]
    InvalidRequest,
    #[error(transparent)]
    Unexpected(#[from] anyhow::Error),
}

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, message) = match self {
            AppError::UserNotFound => (StatusCode::NOT_FOUND, "User not found"),
            AppError::InvalidRequest => (StatusCode::BAD_REQUEST, "Invalid request"),
            AppError::Unexpected(_) => (StatusCode::INTERNAL_SERVER_ERROR, "Internal server error"),
        };
        (status, json!({"code": status.as_u16(), "message": message})).into_response()
    }
}

async fn get_user(Path(user_id): Path<i32>) -> Result<impl IntoResponse, AppError> {
    if user_id == 0 { return Err(AppError::InvalidRequest); }
    if user_id == 999 { return Err(AppError::UserNotFound); }
    Ok(json!({"id": user_id, "name": "张三", "email": "[email protected]"}))
}

#[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();
}

3.4 CORS 与身份验证

Axum 通过 tower_http::cors 中间件提供跨域支持，并支持 JWT 等多种认证方式。

CORS 配置：

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

async fn handler() -> impl IntoResponse { "CORS enabled" }

#[tokio::main]
async fn main() {
    let cors = CorsLayer::new()
        .allow_origin(Any)
        .allow_methods(Any)
        .allow_headers(Any);
    let app = Router::new().route("/", get(handler)).layer(cors);
    axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
        .serve(app.into_make_service())
        .await
        .unwrap();
}

四、Axum 框架的性能优化

4.1 工作线程数配置

Axum 使用 Tokio 异步运行时，工作线程数的配置直接影响系统的并发能力。通常建议根据 CPU 核心数进行设置。

use axum::{response::IntoResponse, routing::get, Router};
use num_cpus;
use tokio::runtime::Builder;

async fn handler() -> impl IntoResponse { "Hello, World!" }

fn main() {
    let runtime = Builder::new_multi_thread()
        .worker_threads(num_cpus::get())
        .max_blocking_threads(10)
        .build()
        .unwrap();
    
    runtime.block_on(async {
        let app = Router::new().route("/", get(handler));
        axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
            .serve(app.into_make_service())
            .await
            .unwrap();
    });
}

4.2 避免重复解析

在自定义请求提取器时，注意缓存已解析的数据，避免重复解析 Header 或 Query 参数。

4.3 中间件优化

合理使用 tower_http 的内置中间件，如 TraceLayer，可以减少手动编写日志和监控代码的开销。

五、实战项目的 Axum 应用

在实际微服务架构中，Axum 常被用于集成用户同步、订单处理和监控服务。

健康检查与业务接口：

use axum::{http::StatusCode, response::IntoResponse, routing::{get, post}, Router};

async fn health() -> impl IntoResponse { StatusCode::OK }

async fn sync_users() -> impl IntoResponse {
    // 模拟业务逻辑
    StatusCode::ACCEPTED
}

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

六、常见问题与解决方案

1. 请求提取器类型不匹配：确保提取器类型与 URL 参数类型一致，例如 :id 应为 i32 而非 f64。
2. 响应映射器返回值：确保返回值实现了 IntoResponse trait，可使用 (StatusCode, Json) 元组。
3. 中间件顺序：中间件按从外到内顺序执行，身份验证应放在路由处理前，CORS 通常在最外层。
4. 状态共享生命周期：共享状态需实现 Clone 并使用 Arc 管理，防止生命周期错误。

七、总结

Axum 凭借其类型安全和模块化设计，为 Rust 开发者提供了构建高效异步 Web 服务的强大工具。掌握其核心组件、路由机制及高级特性，结合性能优化实践，能够显著提升开发效率与系统稳定性。