Confession: I migrated a small service from Actix Web to Axum about a year ago because I lost a borrow-checker fight that, in retrospect, was entirely my fault. I want to say the migration was strategic. It wasn’t. It was a tantrum.<\/p>\n
Twelve months later I’m still on Axum, and I have opinions worth writing down.<\/p>\n
This isn’t an introduction. The Axum docs<\/a> are fine; you can read them yourself. This is the post I wish I’d had a year ago: the small set of patterns I keep reaching for and the ones I tried and quietly dropped. If you want the broader picture of how Axum stacks up against Actix Web and Rocket, I covered that in my Rust web frameworks comparison<\/a>. This one goes deeper into a single framework.<\/p>\n For about a month I treated Axum like a slightly weird Express. Routes and handlers. Done. That worked, but I kept getting confused whenever the type errors got loud.<\/p>\n What finally clicked was this: Axum is a thin layer over Tower<\/a>. Every handler is a The practical version: when something feels weird, ask whether the same pattern would feel weird if you wrote it as a plain async function returning a Extractors are Axum’s best idea. You declare what your handler needs, and the framework hands it to you. I use about four of them daily and ignore the rest.<\/p>\n The two I most often see misused: For anything custom (auth tokens, request IDs, tenant context), I write a The This is the layered setup I actually run in production:<\/p>\n Order matters. Layers wrap the router from the bottom up, which means The other thing that took me too long to internalize: route-specific middleware lives on the route, not the global app.<\/p>\n If you find yourself reaching for global middleware plus a “skip this path” predicate, that’s the universe telling you to put the layer on the route instead.<\/p>\n This was where I burned the most time. I wanted one error type, one The trick I missed for too long: pattern-match on the variant inside the The The mental model that finally clicked<\/h2>\n
Service<\/code>, and middleware is a Layer<\/code> that wraps it. Routing is composition all the way down. Once I stopped thinking “web framework” and started thinking “Tower with sugar”, everything got easier. The compiler error messages even started looking like they were trying to help me, which was a first.<\/p>\nResponse<\/code>. Usually yes. The pain is structural, not Axum’s fault.<\/p>\nExtractors I actually use<\/h2>\n
use axum::{\n extract::{Path, Query, State, Json},\n response::IntoResponse,\n};\nuse serde::Deserialize;\nuse sqlx::PgPool;\n\n#[derive(Deserialize)]\nstruct ListParams {\n q: Option<String>,\n limit: Option<i64>,\n}\n\nasync fn get_user(\n State(db): State<PgPool>,\n Path(user_id): Path<i64>,\n) -> Result<Json<User>, AppError> {\n let user = sqlx::query_as!(\n User,\n "SELECT id, email FROM users WHERE id = $1",\n user_id\n )\n .fetch_one(&db)\n .await?;\n Ok(Json(user))\n}\n\nasync fn list_users(\n State(db): State<PgPool>,\n Query(params): Query<ListParams>,\n) -> Result<Json<Vec<User>>, AppError> {\n \/\/ ...\n unimplemented!()\n}\n<\/code><\/pre>\nQuery<T><\/code> where T<\/code> has a field that’s actually optional but isn’t Option<...><\/code>, and Json<T><\/code> where the struct doesn’t Deserialize<\/code> cleanly because someone forgot #[serde(rename = \"...\")]<\/code>. Both produce error responses that look like Axum is broken when really serde<\/code> is.<\/p>\nFromRequestParts<\/code> impl rather than reading headers in every handler. Once you’ve written one, the next ten take five minutes each.<\/p>\nState and middleware: stop fighting Tower<\/h2>\n
State<\/code> extractor is fine for the database pool and a config struct. For everything else, layers.<\/p>\nuse axum::{Router, routing::get};\nuse tower_http::{\n trace::TraceLayer,\n timeout::TimeoutLayer,\n compression::CompressionLayer,\n cors::CorsLayer,\n};\nuse std::time::Duration;\n\nlet app = Router::new()\n .route("\/healthz", get(healthz))\n .route("\/users\/:id", get(get_user))\n .route("\/users", get(list_users))\n .with_state(db_pool)\n .layer(TraceLayer::new_for_http())\n .layer(TimeoutLayer::new(Duration::from_secs(10)))\n .layer(CompressionLayer::new())\n .layer(CorsLayer::permissive());\n<\/code><\/pre>\nTraceLayer<\/code> runs first on the way in and last on the way out. I got this wrong for two weeks: I had a timeout outside my trace layer and spent embarrassingly long wondering why timed-out requests had no spans.<\/p>\nlet app = Router::new()\n .route(\n "\/admin\/users",\n get(admin_list_users)\n .layer(axum::middleware::from_fn(require_admin)),\n )\n .route("\/users\/:id", get(get_user))\n .with_state(db_pool);\n<\/code><\/pre>\nError handling that doesn’t make you cry<\/h2>\n
?<\/code> in every handler, and meaningful HTTP responses. It took me three rewrites to land on the pattern below.<\/p>\nuse axum::{\n http::StatusCode,\n response::{IntoResponse, Response},\n Json,\n};\nuse serde_json::json;\nuse thiserror::Error;\n\n#[derive(Debug, Error)]\npub enum AppError {\n #[error("not found")]\n NotFound,\n #[error("database error: {0}")]\n Database(#[from] sqlx::Error),\n #[error("validation: {0}")]\n Validation(String),\n #[error("internal")]\n Internal(#[source] anyhow::Error),\n}\n\nimpl IntoResponse for AppError {\n fn into_response(self) -> Response {\n let (status, code) = match &self {\n AppError::NotFound => (StatusCode::NOT_FOUND, "not_found"),\n AppError::Validation(_) => (StatusCode::BAD_REQUEST, "validation"),\n AppError::Database(sqlx::Error::RowNotFound) => {\n (StatusCode::NOT_FOUND, "not_found")\n }\n AppError::Database(_) | AppError::Internal(_) => {\n (StatusCode::INTERNAL_SERVER_ERROR, "internal")\n }\n };\n\n if status.is_server_error() {\n tracing::error!(error = ?self, "request failed");\n }\n\n let body = Json(json!({\n "error": { "code": code, "message": self.to_string() }\n }));\n (status, body).into_response()\n }\n}\n<\/code><\/pre>\nFrom<sqlx::Error><\/code> path so that RowNotFound<\/code> becomes a clean 404 instead of a 500. My on-call past self would like a word.<\/p>\nObservability without ceremony<\/h2>\n
tracing<\/code> crate plus tower_http::trace::TraceLayer<\/code> does about ninety percent of what I need. I add one custom span per request to carry the request ID and user ID, and the rest writes itself.<\/p>\nuse tower_http::trace::{DefaultMakeSpan, TraceLayer};\nuse tracing::Span;\n\nlet trace = TraceLayer::new_for_http()\n .make_span_with(DefaultMakeSpan::new().include_headers(false))\n .on_request(|req: &axum::http::Request<_>, _span: &Span| {\n tracing::info!(\n method = %req.method(),\n path = %req.uri().path(),\n "request"\n );\n });\n<\/code><\/pre>\n