Rust Web Frameworks Expert

Framework Selection Guide

Choose Axum When

• Building new projects without specific actor-model needs
• Your team uses Tower middleware (tracing, auth, rate-limiting)
• You want maximum composability -- handlers, layers, services interoperate via the Service trait
• You need tight integration with hyper or other Tokio-ecosystem crates
• Building microservices that share middleware via a common tower::Layer library

Choose Actix Web When

• You need actor-per-connection state machines for WebSocket at scale
• Raw throughput is critical and profiling confirms the difference matters
• Your team has existing Actix ecosystem investment (actix-session, actix-files)
• You need fine-grained per-worker isolation

Default recommendation for new projects: Axum. The Tower ecosystem backing and lower conceptual overhead make it the better starting point.

Core Concepts

Handlers (Axum)

Any async function whose arguments implement FromRequestParts (or FromRequest) and whose return type implements IntoResponse is a valid handler. No trait bounds in the function signature.

async fn get_user(
    State(state): State<Arc<AppState>>,
    Path(user_id): Path<u64>,
    Query(params): Query<Pagination>,
) -> Result<Json<User>, AppError> {
    let user = state.db.find_user(user_id).await?
        .ok_or(AppError::NotFound(format!("User {user_id}")))?;
    Ok(Json(user))
}

Extractors resolve left-to-right. Body-consuming extractors (Json<T>, Bytes) must be last.

Handlers (Actix Web)

async fn get_user(
    path: web::Path<UserId>,
    query: web::Query<Pagination>,
    db: web::Data<DbPool>,
) -> Result<HttpResponse, AppError> {
    let user = db.find_user(path.id).await?
        .ok_or(AppError::NotFound("User".into()))?;
    Ok(HttpResponse::Ok().json(user))
}

Extractors

Both frameworks support custom extractors. In Axum, implement FromRequestParts<S> (non-body) or FromRequest<S> (body). In Actix, implement FromRequest.

Error Handling

Axum -- AppError + IntoResponse

use axum::{response::IntoResponse, http::StatusCode, Json};
use thiserror::Error;

#[derive(Debug, Error)]
pub enum AppError {
    #[error("Not found: {0}")]
    NotFound(String),
    #[error("Validation: {0}")]
    Validation(String),
    #[error("Database error")]
    Database(#[from] sqlx::Error),
    #[error("Unauthorized")]
    Unauthorized,
    #[error("Internal error")]
    Internal(#[from] anyhow::Error),
}

impl IntoResponse for AppError {
    fn into_response(self) -> axum::response::Response {
        let (status, msg) = match &self {
            AppError::NotFound(m)   => (StatusCode::NOT_FOUND, m.clone()),
            AppError::Validation(m) => (StatusCode::UNPROCESSABLE_ENTITY, m.clone()),
            AppError::Database(_)   => (StatusCode::INTERNAL_SERVER_ERROR, "Database error".into()),
            AppError::Unauthorized  => (StatusCode::UNAUTHORIZED, "Unauthorized".into()),
            AppError::Internal(_)   => (StatusCode::INTERNAL_SERVER_ERROR, "Internal error".into()),
        };
        tracing::error!(error = ?self, "Request error");
        (status, Json(serde_json::json!({"error": msg}))).into_response()
    }
}

Actix Web -- AppError + ResponseError

impl ResponseError for AppError {
    fn status_code(&self) -> actix_web::http::StatusCode { /* match variants */ }
    fn error_response(&self) -> HttpResponse {
        HttpResponse::build(self.status_code())
            .json(serde_json::json!({"error": self.to_string()}))
    }
}

Error Crate Roles

• thiserror -- Define structured error enums with #[derive(Error)]. Use in libraries and domain layers.
• anyhow -- Catch-all anyhow::Error for application code. Add context with .context("msg").
• Neither replaces the other -- Use thiserror for your AppError enum, anyhow for internal plumbing where you just need ? propagation with context.

State Management

// Axum: Arc<AppState> with .with_state()
#[derive(Clone)]
struct AppState {
    db: PgPool,
    config: Arc<Config>,
}

let state = Arc::new(AppState { db: pool, config: Arc::new(config) });
let app = Router::new()
    .route("/users/:id", get(get_user))
    .with_state(state);

// Actix: web::Data<T> (internally Arc)
let data = web::Data::new(AppState { db: pool, config });
App::new().app_data(data.clone())

For mutable shared state, use tokio::sync::RwLock or DashMap inside the state struct. Avoid std::sync::Mutex in async code -- it blocks the Tokio thread.

Middleware

Axum -- Tower Layers

use tower_http::{cors::CorsLayer, compression::CompressionLayer,
    timeout::TimeoutLayer, trace::TraceLayer};

let app = Router::new()
    .nest("/api", api_router)
    .layer(
        tower::ServiceBuilder::new()
            .layer(TraceLayer::new_for_http())
            .layer(TimeoutLayer::new(Duration::from_secs(30)))
            .layer(CompressionLayer::new())
            .layer(CorsLayer::permissive()),
    );

// Function middleware (simplest custom middleware)
async fn require_auth(request: Request, next: Next) -> Result<Response, StatusCode> {
    let token = request.headers().get("Authorization")
        .ok_or(StatusCode::UNAUTHORIZED)?;
    // validate...
    Ok(next.run(request).await)
}
app.route_layer(middleware::from_fn(require_auth));

Actix -- wrap / wrap_fn

App::new()
    .wrap(middleware::Logger::default())
    .wrap(middleware::Compress::default())
    .wrap_fn(|req, srv| {
        println!("{} {}", req.method(), req.uri());
        srv.call(req)
    })

Full custom Actix middleware requires implementing the Transform trait, which is more verbose than Tower layers.

Database Integration

// SQLx compile-time checked query
let user = sqlx::query_as!(User,
    "SELECT id, name, email FROM users WHERE id = $1", id)
    .fetch_optional(&pool).await?;

// Diesel in async handler (requires spawn_blocking)
let users = tokio::task::spawn_blocking(move || {
    let conn = &mut pool.get().unwrap();
    users::table.filter(users::is_active.eq(true)).load::<User>(conn)
}).await??;

Tokio Runtime

Both Axum and Actix run on Tokio. Key patterns:

• tokio::spawn -- Spawn async tasks onto the runtime
• spawn_blocking -- Run CPU-bound or sync code on a dedicated thread pool (required for Diesel)
• JoinSet -- Manage multiple concurrent tasks with structured results
• select! -- Race multiple futures, cancel losers
• Channels -- mpsc, broadcast, watch for inter-task communication

// Graceful shutdown
let (tx, rx) = tokio::sync::oneshot::channel::<()>();