rust-backend-axum
Build production-ready Rust backend APIs with Axum framework. Covers router composition, state management, extractors, middleware (auth, tracing), error handling with IntoResponse, and graceful shutdown. Use when building Rust web services, REST APIs, or when working with Axum, Tower middleware, or async Rust backends.
When & Why to Use This Skill
This Claude skill enables developers to build high-performance, production-ready Rust backend APIs using the Axum framework. It provides expert guidance on modular router composition, type-safe state management, and robust middleware integration, ensuring your web services are scalable, maintainable, and follow async Rust best practices.
Use Cases
- Developing high-performance RESTful microservices and web backends using the Rust programming language.
- Implementing secure authentication and authorization layers using Tower-compatible middleware.
- Architecting scalable API structures with nested routing and efficient shared state management using Arc.
- Ensuring application reliability through standardized error handling with IntoResponse and graceful shutdown procedures.
- Optimizing request processing by correctly ordering body-consuming extractors and leveraging type-safe data extraction.
| name | rust-backend-axum |
|---|---|
| description | Build production-ready Rust backend APIs with Axum framework. Covers router composition, state management, extractors, middleware (auth, tracing), error handling with IntoResponse, and graceful shutdown. Use when building Rust web services, REST APIs, or when working with Axum, Tower middleware, or async Rust backends. |
Body-consuming extractors (Json, Form, Bytes) must come LAST in handler parameters.
// CORRECT: State and Path before Json
async fn handler(
State(state): State<AppState>,
Path(id): Path<Uuid>,
Json(body): Json<CreateRequest>,
) -> impl IntoResponse { }
2. State Must Be Clone
AppState passed to .with_state() must implement Clone. Use Arc for expensive-to-clone fields.
#[derive(Clone)]
struct AppState {
db: sqlx::PgPool, // PgPool is cheap to clone
config: Arc<Config>, // Arc for expensive data
}
3. route_layer vs layer
- route_layer() - Applies only to routes defined BEFORE it
- layer() - Applies to ALL routes
use axum::{routing::get, Router};
use std::sync::Arc;
#[derive(Clone)]
struct AppState {
db: sqlx::PgPool,
}
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let db = sqlx::PgPool::connect(&std::env::var("DATABASE_URL")?).await?;
let state = AppState { db };
let app = Router::new()
.route("/health", get(|| async { "ok" }))
.with_state(state);
let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await?;
axum::serve(listener, app).await?;
Ok(())
}
**Modular Router Composition**
pub fn create_router(state: AppState) -> Router {
Router::new()
.nest("/api/v1", api_routes())
.route("/health", axum::routing::get(health))
.with_state(state)
}
fn api_routes() -> Router<AppState> {
Router::new()
.nest("/users", users::routes())
.nest("/items", items::routes())
}
**Authentication Middleware with Extension**
use axum::{
extract::{Request, Extension},
middleware::Next,
http::{header, StatusCode},
};
pub async fn auth_middleware(
mut req: Request,
next: Next,
) -> Result<Response, StatusCode> {
let auth_header = req.headers()
.get(header::AUTHORIZATION)
.and_then(|h| h.to_str().ok())
.and_then(|h| h.strip_prefix("Bearer "));
let token = auth_header.ok_or(StatusCode::UNAUTHORIZED)?;
let user = validate_jwt(token).await.map_err(|_| StatusCode::UNAUTHORIZED)?;
req.extensions_mut().insert(user);
Ok(next.run(req).await)
}
// Apply to routes
pub fn protected_routes() -> Router<AppState> {
Router::new()
.route("/profile", get(protected_handler))
.route_layer(middleware::from_fn(auth_middleware))
}
**Tower Middleware Stack**
use tower::ServiceBuilder;
use tower_http::{trace::TraceLayer, timeout::TimeoutLayer, compression::CompressionLayer};
let app = Router::new()
.nest("/api", api_routes())
.with_state(state)
.layer(
ServiceBuilder::new()
.layer(TraceLayer::new_for_http())
.layer(TimeoutLayer::new(Duration::from_secs(30)))
.layer(CompressionLayer::new())
);
- [ ] Router compiles with all routes registered
- [ ] State is Clone and contains Arc for expensive fields
- [ ] Extractors are ordered correctly (body consumers last)
- [ ] Error type implements IntoResponse
- [ ] Auth middleware uses Extension for user propagation
- [ ] Graceful shutdown handles SIGTERM/SIGINT
- [ ] cargo clippy passes without warnings