Axum Service Skill

Idiomatic Axum 0.8 web-service generation and review - an Agent Skill for Rust 1.97.0, Tokio 1.x, and serde 1.0.

What This Skill Does

Produces a deployable HTTP service checklist: workspace Cargo.toml, Router modules, shared AppState (PgPool, reqwest::Client), /health and /ready, tracing subscriber, thiserror domain errors mapped to status codes, and integration tests with tower::ServiceExt.

When to Invoke

• New microservice or BFF in a Rust workspace
• Reviewing PRs for blocking DB calls in async handlers
• Splitting a monolithic binary into routed modules
• Standardizing hackathon Axum code before production

Inputs

Outputs

• Cargo.toml with axum, tokio, tower-http, tracing, serde, optional sqlx
• src/main.rs with TcpListener, graceful shutdown
• src/routes/mod.rs, health.rs, domain routers
• src/error.rs with IntoResponse mapping
• tests/health.rs using oneshot requests
• Verification command block

Guardrails

1. Async handlers must not block - use spawn_blocking or async DB only.
2. No secrets in generated files - .env.example placeholders only.
3. Health routes before domain routes - load balancers need them day one.
4. Structured tracing - #[instrument] on handlers; no println! in prod paths.
5. Clone cheap state - Arc<PgPool> and reused reqwest::Client.
6. Map errors to status - never leak internal strings on 500 in public APIs.

Recipe

cd services/billing-api
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test
cargo run &
curl -sf http://localhost:3000/health
curl -sf http://localhost:3000/ready

Working Example (skeleton)

use axum::{routing::get, Router};
use std::net::SocketAddr;
use tokio::net::TcpListener;
 
mod routes;
 
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    tracing_subscriber::fmt::init();
    let app = Router::new()
        .merge(routes::health::router());
    let addr = SocketAddr::from(([0, 0, 0, 0], 3000));
    let listener = TcpListener::bind(addr).await?;
    axum::serve(listener, app).await?;
    Ok(())
}

FAQs

Related

• Axum basics
• reqwest & sqlx
• Async / Tokio Skill
• Error-Handling Skill

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.