axum From Zero
axum is the web framework from the Tokio team, and it has quietly become the default for new Rust web
services — including the one serving this very page. Its appeal is that it leans entirely on Rust's type
system instead of macros or magic: you write plain async fn handlers, and axum figures out how to call
them based on their argument and return types. It sits on top of hyper (the HTTP implementation) and
tower (a universal middleware abstraction), so learning axum also teaches you the layer the rest of
the async Rust ecosystem shares.
The mental model is two ideas. A Router maps paths to handlers (and can be nested and layered). And
a handler is an async fn whose arguments are extractors — types like Path, Query, Json, and
State that pull pieces out of the request — and whose return value implements IntoResponse. Once
you see "arguments extract from the request, the return value becomes the response," axum stops looking
clever and starts looking inevitable.
📝 This teaches the framework — it assumes you know Rust: ownership, traits,
Result, andasync/await(Rust From Zero). It builds on Tokio and hyper/tower, which have their own roots guides (Tokio, hyper & tower) — read those to remove the last of the magic. Compare with actix-web and Rocket. axum compiles and runs as a Rust program, so examples are shown with the commands to run them.
How to read this
Read in order — it grows one service (a small books API) from a single route to a tested, deployable REST API. Phases carry difficulty badges.
The phases
Part 1 — The core (🟢 Basic → 🟡)
- What axum Is & Your First Server 🟢 — the
Router, the async handler, and a running server on Tokio. - Routing & Extractors 🟢 — methods,
Path/Query, nesting and merging routers. - Handlers & IntoResponse 🟡 —
Jsonin and out, what makes a valid handler, and how return types become responses.
Part 2 — A real API (🟡 → 🔴)
4. Shared State 🟡 — State<T>, with_state, and giving handlers a database pool without globals.
5. Middleware with Tower 🔴 — Layer/Service, ServiceBuilder, and tower-http (tracing, CORS, timeouts).
6. Building a REST API 🟡 — full CRUD wired through extractors, state, and IntoResponse.
7. Error Handling 🔴 — a custom error type that implements IntoResponse, and the ? operator in handlers.
Part 3 — Ship it (🟡 → 🟢)
8. Testing & Production 🟡 — oneshot handler tests, graceful shutdown, and deployment.
9. Where to Go Next 🟢 — axum vs actix/Rocket, sqlx/SeaORM for data, and the tokio/hyper/tower roots.
The throughline: a
Routersends a request to anasync fnwhose arguments extract from it and whose return value becomes the response, with tower layers wrapped around the whole thing. Hold that and axum is plain Rust.