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);

Tower Middleware

use tower_http::{cors::CorsLayer, trace::TraceLayer};
use tower::ServiceBuilder;

let app = Router::new()
    .route("/", get(index))
    .layer(
        ServiceBuilder::new()
            .layer(TraceLayer::new_for_http())
            .layer(CorsLayer::permissive())
    );

Health Checks

async fn health() -> Json<Value> {
    Json(json!({ "status": "healthy" }))
}

async fn ready(State(state): State<Arc<AppState>>) -> Result<Json<Value>, StatusCode> {
    sqlx::query("SELECT 1")
        .execute(&state.db_pool)
        .await
        .map_err(|_| StatusCode::SERVICE_UNAVAILABLE)?;

    Ok(Json(json!({ "status": "ready" })))
}

When NOT to Use This Skill

• Actix-web projects - Actix has more built-in features
• Rocket projects - Rocket has compile-time route checking
• Sync-only Rust code - Axum requires async runtime

Anti-Patterns

Anti-Pattern	Why It's Bad	Solution
Not using Arc for state	Expensive clones	Wrap state in Arc<AppState>
Blocking operations in handlers	Blocks executor	Use tokio::task::spawn_blocking
Missing error conversion	Compiler errors	Implement IntoResponse for errors
Not using extractors	Manual parsing	Use Path, Query, Json extractors

Quick Troubleshooting

Problem	Diagnosis	Fix
"Handler doesn't implement Handler"	Wrong signature	Check extractor order and return type
Route not matching	Conflicting routes	Order routes from specific to general
State not accessible	Wrong state type	Ensure with_state() matches State<T>
Missing CORS headers	No layer	Add CorsLayer from tower-http

Production Checklist

• Tracing/logging configured
• CORS properly set up
• Error handling with custom types
• Health/readiness endpoints
• Graceful shutdown
• State management with Arc
• Input validation

Reference Documentation

• Extractors
• Middleware