axum

Axum Core Knowledge

Full Reference: See advanced.md for authentication middleware, WebSocket handling, graceful shutdown, and custom error types.

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: axum for comprehensive documentation.

Basic Setup

# Cargo.toml
[dependencies]
axum = "0.7"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
tower-http = { version = "0.5", features = ["cors", "trace"] }

use axum::{routing::get, Router};

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

#[tokio::main]
async fn main() {
    let app = Router::new().route("/", get(hello));

    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Routing

let app = Router::new()
    .route("/", get(index))
    .route("/users", get(list_users).post(create_user))
    .route("/users/:id", get(get_user).put(update_user).delete(delete_user));

// Nested Routes
let api_routes = Router::new()
    .route("/users", get(list_users));

let app = Router::new().nest("/api/v1", api_routes);

Extractors

use axum::extract::{Path, Query, Json, State};

// Path parameters
async fn get_user(Path(id): Path<u32>) -> String {
    format!("User {}", id)
}

// Query parameters
#[derive(Deserialize)]
struct Pagination { page: Option<u32>, per_page: Option<u32> }

async fn list_users(Query(pagination): Query<Pagination>) -> Json<Value> {
    Json(json!({ "page": pagination.page.unwrap_or(1) }))
}

// JSON body
async fn create_user(Json(payload): Json<CreateUser>) -> (StatusCode, Json<Value>) {
    (StatusCode::CREATED, Json(json!({ "name": payload.name })))
}

Application State

use std::sync::Arc;

struct AppState {
    db_pool: sqlx::PgPool,
}

async fn handler(State(state): State<Arc<AppState>>) -> String {
    // Use state.db_pool
}

let state = Arc::new(AppState { db_pool: pool });
let app = Router::new()
    .route("/", get(handler))
    .with_state(state);