1. 江湖溯源（背景介绍）
axum 是由 Rust 异步运行时 Tokio 团队打造的一柄轻量级「绣春刀」。它以异步编程为核心，基于高性能的 Hyper HTTP 库，专为构建现代化 Web 应用而生。axum 继承了 Tokio 的「快意恩仇」和高并发特性，同时提供了简洁的 API 设计，让开发者能够以「刀光剑影」般的速度斩断复杂的 Web 开发难题。其模块化设计理念，使得开发者可以「按需取刃」，灵活组合功能。
2. 武学妙用（应用场景）
- 构建 RESTful API 服务：快速实现 HTTP 接口的注册和请求处理。
- 开发微服务架构：轻量级路由和中间件支持，适合分布式系统。
- 实时 Web 应用：通过 WebSocket 支持实现双向通信。
- 单页应用后端：无缝对接前端框架（如 React/Vue）的 API 需求。
- 中间件扩展：通过 Tower 生态集成认证、日志、限流等功能。
3. 兵器锻造（依赖引入）
在 Cargo.toml 中添加以下配置。若需启用 WebSocket 等高级特性，可指定额外 features：
toml
[dependencies]
axum = { version = "0.7.3", features = ["ws"] }# 基础依赖，启用 WebSocket
tokio = { version = "1.0", features = ["full"] }# 异步运行时
4. 初窥门径（5分钟上手）
4.1 基本招式（Hello World）
目标：用 axum 启动一个返回 "Hello World" 的服务器。
use axum::{Router, routing::get, response::Html};
#[tokio::main]
async fn main() {
// 创建路由，绑定 GET 请求到根路径 "/"
let app = Router::new().route("/", get(|| async { Html("Hello World") }));
// 启动服务器，监听 3000 端口
axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
.serve(app.into_make_service())
.await
.unwrap();
}
代码逻辑：
- 定义异步主函数，通过
Router注册路由。 - 当访问根路径
/时，返回 HTML 格式的 "Hello World"。 - 绑定本地 3000 端口，启动服务。
4.2 十八般武艺（功能示例）
招式一：路径参数与 JSON 响应
目标：从 URL 中提取参数，返回 JSON 数据。
use axum::{routing::get, Json, Router};
use serde_json::json;
let app = Router::new().route("/user/:id", get(|id: axum::extract::Path<String>| async {
Json(json!({ "user_id": id.0 }))// 将路径参数包装为 JSON
}));
代码逻辑：
- 通过
:id捕获 URL 中的动态参数。 - 使用
Json类型自动序列化响应数据。
招式二：请求体解析与状态共享
目标：解析 POST 请求的 JSON 数据，并共享数据库连接池。
use axum::{routing::post, Extension, Json};
use std::sync::Arc;
struct DatabasePool;// 模拟数据库连接池
let app = Router::new()
.route("/create_user", post(|Json(payload): Json<serde_json::Value>, Extension(db): Extension<Arc<DatabasePool>>| async {
// 使用 db 和 payload 创建用户
}))
.layer(Extension(Arc::new(DatabasePool)));// 共享状态到所有路由
代码逻辑：
- 通过
Extension中间件共享全局状态（如数据库连接）。 - 使用
Json提取器自动解析请求体。
招式三：中间件鉴权
目标：为路由添加身份验证中间件。
use axum::{routing::get, Router, middleware::from_fn};
async fn auth_middleware<B>(req: axum::http::Request<B>, next: axum::middleware::Next<B>) -> axum::response::Response {
// 检查请求头中的 Token
if req.headers().get("Token").is_none() {
return axum::response::Response::builder().status(401).body("Unauthorized".into()).unwrap();
}
next.run(req).await
}
let app = Router::new()
.route("/admin", get(|| async { "Secret Page" }))
.route_layer(from_fn(auth_middleware));// 应用中间件到特定路由
代码逻辑：
- 自定义中间件检查请求头中的
Token。 - 若未携带 Token，返回 401 未授权错误。
4.3 心法进阶（高级用法）
目标：实现 WebSocket 双向通信。
use axum::{routing::get, Router, response::Response};
use axum::extract::ws::{WebSocket, WebSocketUpgrade};
let app = Router::new().route("/ws", get(|ws: WebSocketUpgrade| async {
ws.on_upgrade(|mut socket: WebSocket| async move {
while let Some(Ok(msg)) = socket.recv().await {// 监听消息
if let Ok(text) = msg.into_text() {
socket.send(format!("Echo: {}", text).into()).await.unwrap();
}
}
})
}));
代码逻辑：
- 通过
WebSocketUpgrade处理握手请求。 - 建立连接后，循环接收客户端消息并返回 "Echo: " 前缀的响应。
6. 秘籍出处（官方资源）
Github：github.com/tokio-rs/ax…
Crates.io：crates.io/crates/axum
至此，你已掌握 axum 的「刀法精髓」。快手持这柄绣春刀，斩开 Rust Web 开发的江湖之路吧！
