Rust 高性能后端开发完全指南 2026：Axum + Tokio + SQLx + 生产级实战

1
use axum::{
2
    http::StatusCode,
3
    response::{IntoResponse, Response},
4
    Json,
5
};
6
use serde_json::json;
7

8
#[derive(Debug)]
9
pub enum AppError {
10
    DatabaseError(sqlx::Error),
11
    NotFound(String),
12
    Unauthorized(String),
13
    BadRequest(String),
14
    InternalServerError,
15
}
16

17
// 自动将 sqlx::Error 转换为 AppError
18
impl From<sqlx::Error> for AppError {
19
    fn from(err: sqlx::Error) -> Self {
20
        tracing::error!("Database query failed: {:?}", err);
21
        AppError::DatabaseError(err)
22
    }
23
}
24

25
// 实现 IntoResponse，让 AppError 可以直接作为 Handler 返回值
26
impl IntoResponse for AppError {
27
    fn into_response(self) -> Response {
28
        let (status, error_message) = match self {
29
            AppError::NotFound(msg) => (StatusCode::NOT_FOUND, msg),
30
            AppError::Unauthorized(msg) => (StatusCode::UNAUTHORIZED, msg),
31
            AppError::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg),
32
            AppError::DatabaseError(_) | AppError::InternalServerError => (
33
                StatusCode::INTERNAL_SERVER_ERROR,
34
                "Internal server error".to_string(),
35
            ),
36
        };
37

38
        let body = Json(json!({
39
            "code": status.as_u16(),
40
            "message": error_message,
41
        }));
42

43
        (status, body).into_response()
44
    }
45
}

1
use sqlx::PgPool;
2
use std::sync::Arc;
3

4
#[derive(Clone)]
5
pub struct AppState {
6
    pub db: PgPool,
7
    pub jwt_secret: String,
8
}
9

10
impl AppState {
11
    pub fn new(db: PgPool, jwt_secret: String) -> Self {
12
        Self { db, jwt_secret }
13
    }
14
}

1
use axum::{
2
    extract::{Path, State},
3
    http::StatusCode,
4
    Json,
5
};
6
use serde::{Deserialize, Serialize};
7
use uuid::Uuid;
8
use chrono::{DateTime, Utc};
9
use crate::{error::AppError, state::AppState};
10

11
#[derive(Serialize, sqlx::FromRow)]
12
pub struct User {
13
    pub id: Uuid,
14
    pub username: String,
15
    pub email: String,
16
    pub created_at: DateTime<Utc>,
17
}
18

19
#[derive(Deserialize)]
20
pub struct CreateUserRequest {
21
    pub username: String,
22
    pub email: String,
23
}
24

25
// 1. 创建用户
26
pub async fn create_user(
27
    State(state): State<AppState>,
28
    Json(payload): Json<CreateUserRequest>,
29
) -> Result<(StatusCode, Json<User>), AppError> {
30
    if payload.username.is_empty() || payload.email.is_empty() {
31
        return Err(AppError::BadRequest("Username and email cannot be empty".into()));
32
    }
33

34
    let user = sqlx::query_as!(
35
        User,
36
        r#"
37
        INSERT INTO users (id, username, email, created_at)
38
        VALUES ($1, $2, $3, $4)
39
        RETURNING id, username, email, created_at
40
        "#,
41
        Uuid::new_v4(),
42
        payload.username,
43
        payload.email,
44
        Utc::now()
45
    )
46
    .fetch_one(&state.db)
47
    .await?;
48

49
    Ok((StatusCode::CREATED, Json(user)))
50
}
51

52
// 2. 根据 ID 查询用户
53
pub async fn get_user_by_id(
54
    State(state): State<AppState>,
55
    Path(user_id): Path<Uuid>,
56
) -> Result<Json<User>, AppError> {
57
    let user = sqlx::query_as!(
58
        User,
59
        r#"
60
        SELECT id, username, email, created_at
61
        FROM users
62
        WHERE id = $1
63
        "#,
64
        user_id
65
    )
66
    .fetch_optional(&state.db)
67
    .await?
68
    .ok_or_else(|| AppError::NotFound(format!("User with id {} not found", user_id)))?;
69

70
    Ok(Json(user))
71
}

1
mod error;
2
mod state;
3
mod handlers;
4

5
use axum::{
6
    routing::{get, post},
7
    Router,
8
};
9
use sqlx::postgres::PgPoolOptions;
10
use std::time::Duration;
11
use tower_http::{
12
    cors::{Any, CorsLayer},
13
    trace::TraceLayer,
14
    timeout::TimeoutLayer,
15
};
16
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
17
use crate::state::AppState;
18

19
#[tokio::main]
20
async fn main() -> Result<(), Box<dyn std::error::Error>> {
21
    // 1. 初始化结构化日志
22
    tracing_subscriber::registry()
23
        .with(tracing_subscriber::EnvFilter::try_from_default_env().unwrap_or_else(|_| "info,rust_axum_service=debug".into()))
24
        .with(tracing_subscriber::fmt::layer().json())
25
        .init();
26

27
    // 2. 初始化数据库连接池
28
    let database_url = std::env::var("DATABASE_URL")
29
        .unwrap_or_else(|_| "postgres://postgres:password@localhost:5432/app_db".into());
30

31
    let pool = PgPoolOptions::new()
32
        .max_connections(50)
33
        .min_connections(5)
34
        .acquire_timeout(Duration::from_secs(3))
35
        .idle_timeout(Duration::from_secs(600))
36
        .connect(&database_url)
37
        .await?;
38

39
    let state = AppState::new(pool, "my-super-secret-jwt-key".into());
40

41
    // 3. 构建洋葱模型中间件层
42
    let cors = CorsLayer::new()
43
        .allow_origin(Any)
44
        .allow_methods(Any)
45
        .allow_headers(Any);
46

47
    // 4. 构建路由
48
    let app = Router::new()
49
        .route("/health", get(|| async { "OK" }))
50
        .route("/api/v1/users", post(handlers::user::create_user))
51
        .route("/api/v1/users/:id", get(handlers::user::get_user_by_id))
52
        .layer(TraceLayer::new_for_http())
53
        .layer(TimeoutLayer::new(Duration::from_secs(10)))
54
        .layer(cors)
55
        .with_state(state);
56

57
    // 5. 绑定端口启动高性能异步服务器
58
    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await?;
59
    tracing::info!("Server listening on http://0.0.0.0:8080");
60

61
    axum::serve(listener, app).await?;
62
    Ok(())
63
}