Rust学习笔记 - axum

2026-05-10

全文 ≈ 1.4k字 | 预计阅读时长 7分钟

Axum 是由 Tokio 官方团队开发的一个高性能、设计优雅的现代化 Web 框架。

为什么选择Axum？

Tokio 是 Rust 社区中最流行的异步编程框架之一（在区块链和智能合约圈子比较受欢迎），而Axum是由Tokio官方开发、且深度集成的Web框架。

快速使用

假设已经安装了Rust开发环境

// main.rs
use axum::{Router, routing};
use tokio::net::TcpListener;

#[tokio::main]
async fn main() {
    let router = Router::new().route("/", routing::get(async || "Hi, Rust!"));
    let addr = "0.0.0.0:8000";
    let listener = TcpListener::bind(&addr).await.unwrap();
    println!("listening on {}", addr);
    axum::serve(listener, router).await.unwrap();
}

1 2	$ curl -X GET 'http://127.0.0.1:8000' Hi, Rust!

进阶使用

登录场景的需求，如下实现

// main.rs

// ...
let router = Router::new()
    .route("/", routing::get(async || "Hi, Rust!"))
    .route("/auth/login", routing::post(login));
// ...

#[derive(Serialize, Deserialize)]
struct LoginRequest {
    user: String,
    password: String,
}

async fn login(Json(req): Json<LoginRequest>) -> Response {
    // 这里两种写法都可以，模式匹配
    // async fn login(payload: Json<LoginRequest>) -> Response {
    //     let Json(req) = payload;
    (StatusCode::OK, format!("Hello, {}!", req.user)).into_response()
}

1 2	$ curl -X POST 'http://127.0.0.1:8000/auth/login' -H 'Content-Type: application/json' -d '{"user":"mark","password":"123456"}' Hello, mark!

JWT

Web项目一般会采用JSON-Web-Token（JWT）来做鉴权，进行如下修改

// jwt.rs
use chrono::Utc;
use jsonwebtoken::{Algorithm, EncodingKey, Header, errors};
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Debug)]
pub struct Claims {
    pub sub: String,
    pub iat: i64,
    pub exp: i64,
    pub iss: String,
}

const JWT_SECRET: &str = "jwt_secret";
const JWT_ISSUER: &str = "jwt_issuer";

impl Claims {
    pub fn new(sub: String) -> Self {
        let now = Utc::now().timestamp();
        Self {
            sub,
            iat: now,
            exp: now + 60 * 60 * 24 * 30,
            iss: JWT_ISSUER.to_string(),
        }
    }
}

pub fn generate_token(claims: Claims) -> Result<String, errors::Error> {
    jsonwebtoken::encode(
        &Header::new(Algorithm::HS256),
        &claims,
        &EncodingKey::from_secret(JWT_SECRET.as_bytes()),
    )
}

// main.rs
// 引入JWT

// ...

#[derive(Serialize, Deserialize)]
struct LoginResponse {
    token: String,
}

async fn login(Json(req): Json<LoginRequest>) -> Response {
    match generate_token(Claims::new(req.user)) {
        Ok(token) => {
            let resp = LoginResponse { token };
            (StatusCode::OK, Json(resp)).into_response()
        }
        Err(err) => (
            StatusCode::BAD_REQUEST,
            format!("failed to generate token: {err}"),
        )
            .into_response(),
    }
}

1
2

$ curl -X POST 'http://127.0.0.1:8000/auth/login' -H 'Content-Type: application/json' -d '{"user":"mark","password":"123456"}'
{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJtYXJrIiwiaWF0IjoxNzc4NjQ1NDgzLCJleHAiOjE3ODEyMzc0ODMsImlzcyI6Imp3dF9pc3N1ZXIifQ.qCBi1joIfMAKwgcMNv5v2bXaD2TVe-NTHleUXys1G2Y"}

IntoResponse

有时需要对Resp返回包体结构进行修改，这样实现

// response.rs
use axum::{
    Json,
    response::{IntoResponse, Response},
};
use serde::Serialize;

#[derive(Serialize)]
pub struct ApiResponse<T: Serialize> {
    pub status: u16,
    pub message: String,
    pub data: T,
}

impl<T: Serialize> IntoResponse for ApiResponse<T> {
    fn into_response(self) -> Response {
        Json(self).into_response()
    }
}

impl<T: Serialize> ApiResponse<T> {
    pub fn new(status: u16, message: impl Into<String>, data: T) -> Self {
        Self {
            status: status,
            message: message.into(),
            data,
        }
    }

    pub fn ok(data: T) -> Response {
        Self::new(0, "ok", data).into_response()
    }
}

impl ApiResponse<()> {
    pub fn error(status: u16, message: impl Into<String>) -> Response {
        Self::new(status, message, ()).into_response()
    }
}

// main.rs

// ...

async fn login(Json(req): Json<LoginRequest>) -> Response {
    match generate_token(Claims::new(req.user)) {
        Ok(token) => {
            let resp = LoginResponse { token };
            ApiResponse::ok(resp)
        }
        Err(err) => ApiResponse::error(400, format!("failed to generate token: {err}")),
    }
}

1
2

$ curl -X POST "http://127.0.0.1:8000/auth/login" -H 'Content-Type: application/json' -d '{"user":"mark","password":"123456"}'
{"status":0,"message":"ok","data":{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJtYXJrIiwiaWF0IjoxNzc4NjQ2Njg4LCJleHAiOjE3ODEyMzg2ODgsImlzcyI6Imp3dF9pc3N1ZXIifQ.vzj_ExYeqBL9rrjqGiMWn0ywbp38PrrBy8H2q1Z40oQ"}}

Extensions

生成了JWT Token之后如何实现鉴权呢？

// jwt_auth.rs
pub async fn jwt_auth(
    headers: HeaderMap,
    request: Request,
    next: Next,
) -> Result<Response, StatusCode> {
    match get_token(&headers) {
        Some(token) => match verify_token(&token) {
            Ok(_) => {
                let response = next.run(request).await;
                Ok(response)
            }
            Err(_) => Ok(ApiResponse::error(401, "unauthorized")),
        },
        _ => Ok(ApiResponse::error(401, "unauthorized")),
    }
}

fn get_token(headers: &HeaderMap) -> Option<&str> {
    let value = headers.get(header::AUTHORIZATION)?.to_str().ok()?;
    if value.starts_with("Bearer ") {
        Some(&value[7..])
    } else {
        None
    }
}

// main.rs

// ...
let router = Router::new()
        .route("/", routing::get(async || "Hi, Rust!"))
        .route("/auth/login", routing::post(login))
        .route("/auth/me", routing::get(me).layer(from_fn(jwt_auth)));
// ...

async fn me() -> Response {
    ApiResponse::ok("ok")
}

$ curl -X GET "http://127.0.0.1:8000/auth/me"
{"status":401,"message":"unauthorized","data":null}

curl -X GET "http://127.0.0.1:8000/auth/me" -H 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJtYXJrIiwiaWF0IjoxNzc4NjQ2Njg4LCJleHAiOjE3ODEyMzg2ODgsImlzcyI6Imp3dF9pc3N1ZXIifQ.vzj_ExYeqBL9rrjqGiMWn0ywbp38PrrBy8H2q1Z40oQ'
{"status":0,"message":"ok","data":"ok"}

Extractor

如果希望在请求中能够获取登录用户，还可以这样做

// model.rs
#[derive(Debug, Clone)]
pub struct User {
    pub name: String,
}

// extract.rs
use axum::{
    extract::FromRequestParts,
    http::{StatusCode, request::Parts},
};

use crate::model::User;

pub struct Auth(pub User);

impl<S> FromRequestParts<S> for Auth
where
    S: Send + Sync,
{
    type Rejection = StatusCode;

    async fn from_request_parts(parts: &mut Parts, _state: &S) -> Result<Self, Self::Rejection> {
        let user = parts
            .extensions
            .get::<User>()
            .cloned()
            .ok_or(StatusCode::UNAUTHORIZED)?;

        Ok(Auth(user))
    }
}

// jwt_auth.rs
pub async fn jwt_auth(
    headers: HeaderMap,
    mut request: Request,
    next: Next,
) -> Result<Response, StatusCode> {
    match get_token(&headers) {
        Some(token) => match verify_token(&token) {
            Ok(claims) => {
                let user = User { name: claims.sub };
                request.extensions_mut().insert(user);
                let response = next.run(request).await;
                Ok(response)
            }
            Err(_) => Ok(ApiResponse::error(401, "unauthorized")),
        },
        _ => Ok(ApiResponse::error(401, "unauthorized")),
    }
}

// main.rs

// ...

async fn me(Auth(user): Auth) -> Response {
    ApiResponse::ok(user.name)
}

1
2

$ curl -X GET "http://127.0.0.1:8000/auth/me" -H 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJtYXJrIiwiaWF0IjoxNzc4NjQ2Njg4LCJleHAiOjE3ODEyMzg2ODgsImlzcyI6Imp3dF9pc3N1ZXIifQ.vzj_ExYeqBL9rrjqGiMWn0ywbp38PrrBy8H2q1Z40oQ'
{"status":0,"message":"ok","data":"mark"}

最后

Axum简单使用的example，涉及Service + Layer、Extractor等核心和关键特性后续会展开深入学习。