[Intermediate → Advanced] — Axum is a thin layer over hyper and tower. Understanding the layers below it is what makes the rest predictable.

Source: [reference]. Assumes the Rust course, especially async.

The stack

your handlers
    │
  AXUM        routing, extractors, IntoResponse
    │
  TOWER       Service trait, Layer, middleware
    │
  HYPER       HTTP/1 + HTTP/2 protocol
    │
  TOKIO       async runtime, I/O

Unlike most frameworks, these are genuinely separate crates with separate maintainers, and you can use each without the ones above it. Axum’s design goal was to add routing and ergonomics without inventing its own middleware system — which is why it’s roughly 5,000 lines rather than 50,000.

The practical consequence: tower middleware written for a gRPC client works in your HTTP server, because both are Services.

The Service trait

The abstraction everything rests on:

trait Service<Request> {
    type Response;
    type Error;
    type Future: Future<Output = Result<Self::Response, Self::Error>>;
 
    fn poll_ready(&mut self, cx: &mut Context) -> Poll<Result<(), Self::Error>>;
    fn call(&mut self, req: Request) -> Self::Future;
}

An async function from request to response. That’s it — and it’s deliberately not HTTP-specific, which is why the same trait covers HTTP servers, HTTP clients, gRPC, and database connection pools.

poll_ready is the part that doesn’t exist in other ecosystems: a service can say “not yet”. That’s how backpressure works — a rate limiter or a full connection pool returns Pending, and the caller waits rather than queueing unboundedly. Most frameworks have no equivalent.

A Layer wraps one Service in another:

trait Layer<S> {
    type Service;
    fn layer(&self, inner: S) -> Self::Service;
}

Same shape as Go’s func(Handler) Handler from middleware as composition, with types attached.

A minimal server

use axum::{Router, routing::get, Json};
 
#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/", get(root))
        .route("/users/{id}", get(get_user).delete(delete_user))
        .route("/users", post(create_user));
 
    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}
 
async fn root() -> &'static str { "hello" }

Note {id} — Axum 0.8 switched from :id to {id} to match the standard library and other ecosystems. Older tutorials use the colon form.

Handlers are plain async functions

async fn get_user(Path(id): Path<u64>) -> Json<User> { ... }

No macros, no attributes, no registration. A handler is any async function whose arguments are extractors and whose return type implements IntoResponse.

This is the trick that makes Axum feel light: everything is expressed in the type system rather than in annotations. Compare with #[get("/users/{id}")] in Actix or @GetMapping in Spring — those need a macro or reflection to connect a route to a function; Axum just passes the function to get().

The magic is a set of blanket impls: Handler is implemented for every async fn taking 0–16 extractors. That’s also why a handler with a non-extractor argument produces a famously unhelpful error — the trait simply isn’t satisfied, and the compiler explains it badly. axum::debug_handler fixes that:

#[axum::debug_handler]                  // turns the trait error into a readable one
async fn get_user(Path(id): Path<u64>) -> Json<User> { ... }

Reach for #[debug_handler] the moment a handler won’t compile. It’s the single most useful debugging tool in Axum.

Tower middleware

use tower_http::{trace::TraceLayer, compression::CompressionLayer, cors::CorsLayer};
use tower::ServiceBuilder;
 
let app = Router::new()
    .route("/users", get(list_users))
    .layer(
        ServiceBuilder::new()
            .layer(TraceLayer::new_for_http())        // outermost
            .layer(CompressionLayer::new())
            .layer(CorsLayer::permissive())
            .layer(TimeoutLayer::new(Duration::from_secs(30)))
            .into_inner(),
    );

ServiceBuilder applies layers top-to-bottom (outermost first). Bare .layer() calls apply bottom-to-top. This reversal catches everyone. Use ServiceBuilder and read it as a request travelling downward.

tower-http gives you the standard set without writing any of it:

TraceLayer            request/response tracing
CompressionLayer      gzip/br/deflate
DecompressionLayer
CorsLayer
TimeoutLayer
RequestBodyLimitLayer     ← cap body size; not on by default
SetSensitiveHeadersLayer  ← redact Authorization from logs
ServeDir / ServeFile      static files
NormalizePathLayer

Per-route middleware via route_layer, which only runs for matched routes:

let app = Router::new()
    .route("/admin", get(admin))
    .route_layer(middleware::from_fn(require_admin))    // 404s don't hit it
    .route("/public", get(public));

route_layer vs layer is a real distinction: layer also wraps the fallback, so a layer-applied auth middleware runs on requests to nonexistent paths.

Writing your own

use axum::middleware::{self, Next};
use axum::extract::Request;
 
async fn auth(mut req: Request, next: Next) -> Result<Response, StatusCode> {
    let token = req.headers()
        .get(header::AUTHORIZATION)
        .and_then(|v| v.to_str().ok())
        .and_then(|v| v.strip_prefix("Bearer "))
        .ok_or(StatusCode::UNAUTHORIZED)?;
 
    let claims = verify(token).map_err(|_| StatusCode::UNAUTHORIZED)?;
    req.extensions_mut().insert(claims);        // pass it downstream
    Ok(next.run(req).await)
}
 
let app = Router::new().route("/", get(h)).layer(middleware::from_fn(auth));

middleware::from_fn is the ergonomic escape hatch — it saves implementing Service and Layer by hand, which is genuinely tedious (a struct, a Layer impl, a Service impl, and usually a Pin<Box<dyn Future>>).

Write a real Layer only when you need poll_ready for backpressure. Otherwise from_fn.

Nesting and merging

let api = Router::new()
    .route("/users", get(list_users))
    .route("/users/{id}", get(get_user));
 
let app = Router::new()
    .nest("/api/v1", api)                       // prefix
    .merge(admin_routes)                        // same level
    .fallback(handler_404)
    .layer(TraceLayer::new_for_http());

nest prefixes paths; merge combines routers at the same level. Both compose Routers, which are themselves Services.

Server configuration

let listener = TcpListener::bind(addr).await?;
 
axum::serve(listener, app)
    .with_graceful_shutdown(shutdown_signal())
    .await?;
 
async fn shutdown_signal() {
    let ctrl_c = async { signal::ctrl_c().await.expect("ctrl_c handler") };
    let terminate = async {
        signal::unix::signal(signal::unix::SignalKind::terminate())
            .expect("SIGTERM handler").recv().await;
    };
    tokio::select! {
        _ = ctrl_c => {},
        _ = terminate => {},
    }
}

Graceful shutdown drains in-flight requests before exiting — the same requirement as Go, and equally necessary under Kubernetes.

Timeouts come from tower rather than the server:

.layer(TimeoutLayer::new(Duration::from_secs(30)))
.layer(RequestBodyLimitLayer::new(1024 * 1024))     // 1MB — DO set this

For lower-level control (HTTP/2 settings, header read timeouts) you drop to hyper_util::server::conn::auto::Builder directly.

Actix Web, briefly

The other major option:

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(|| {
        App::new()
            .app_data(web::Data::new(state.clone()))
            .service(get_user)
    })
    .bind(("0.0.0.0", 8080))?
    .run()
    .await
}
 
#[get("/users/{id}")]
async fn get_user(path: web::Path<u64>) -> impl Responder { ... }
AxumActix Web
Middlewaretower — shared ecosystemits own
Routingfunction callsattribute macros or builder
Runtimetokioown (actix-rt, on tokio)
Per-worker statesharedthread-per-core, state per worker
Ecosystem reusehighlower

Actix is slightly faster in benchmarks and has a thread-per-core model that avoids some cross-thread synchronisation. Axum’s tower compatibility means more reusable middleware and easier integration with tonic (gRPC) and other tower-based tooling.

Axum is the current default recommendation, largely for that ecosystem reason. Actix is mature, fast, and a perfectly good choice.


↑ Back to Rust Backends