It also names the honest alternatives — sea-orm for an ActiveRecord-style ORM, diesel for a
mature but synchronous alternative needing spawn_blocking — and structured observability via
tracing.
Out of scope: raw async/concurrency primitives (channels, locks, task spawning) belong to
rust-async-concurrency; cross-domain crate selection belongs to rust-ecosystem-crates.
Rust Web Backend
Agent Workflow (MANDATORY)
Before building the service, spawn in parallel:
- fuse-ai-pilot:explore-codebase — detect the existing router, state, and DB layer
- fuse-ai-pilot:research-expert — verify current axum/sqlx APIs via Context7/Exa (axum 0.8 changed several APIs)
- mcp__context7__query-docs — pull exact extractor/handler signatures
After building, run fuse-ai-pilot:sniper.
The 2026 standard stack
| Layer |
Crate |
Why |
| Runtime |
tokio |
De-facto async runtime; everything targets it |
| HTTP framework |
axum 0.8.x |
Tower-based, extractor ergonomics, minimal magic |
| Middleware |
tower / tower-http |
Composable layers (trace, cors, timeout, compression) |
| Database |
sqlx 0.9 |
Async, query! compile-time-checked SQL, no DSL; Postgres/MySQL/SQLite |
| Observability |
tracing + tracing-subscriber |
Structured, async-aware spans and logs |
Honest alternatives: sea-orm (ActiveRecord-style ORM, higher-level than sqlx), diesel 2.x (mature, synchronous — needs spawn_blocking or a sync pool in async apps). Prefer sqlx for the standard stack; reach for these only when their model fits.
Critical Rules
- axum 0.8 path syntax is
/{id}, not /:id — /*rest became /{*rest}. The old matchit syntax will not compile.
- Errors implement
IntoResponse — never .unwrap() in a handler. Map domain errors to a status + body via one app error type.
- Share state with
State<T>, wrapped once — put the pool/config in an Arc-friendly struct; extract it with State, do not use globals.
sqlx::query! needs DATABASE_URL at compile time — or a committed .sqlx/ offline cache (cargo sqlx prepare). Plan this before CI.
- No
#[async_trait] on axum extractors — 0.8 uses RPITIT; custom FromRequestParts impls must drop the macro.
Reference Guide
Concepts
| Topic |
Reference |
When to Consult |
| Architecture |
architecture.md |
Router, extractors, State, tower middleware layout |
| Error handling |
error-handling.md |
App error type + IntoResponse |
| Database |
database.md |
sqlx pool, query!, migrations, alternatives |
| Observability |
observability.md |
tracing spans, subscriber, request logging |
Templates
| Template |
When to Use |
| rest-service.md |
Complete minimal REST service (router + state + handlers + errors + tracing) |
Quick Reference
Router with the 0.8 path syntax
let app = Router::new()
.route("/users", get(list).post(create))
.route("/users/{id}", get(show)) // NOT /:id
.with_state(state);
→ See architecture.md
Compile-time-checked query
let user = sqlx::query_as!(User, "SELECT id, name FROM users WHERE id = $1", id)
.fetch_optional(&pool)
.await?;
→ See database.md
Best Practices
DO
- Keep one app error type that implements
IntoResponse.
- Layer cross-cutting concerns (trace, timeout, cors) via
tower-http.
- Verify queries at compile time with
query!/query_as!.
DON'T
- Use
/:id route syntax (0.7 and earlier only).
.unwrap() in handlers — return a typed error.
- Reach for diesel in async code without accounting for its sync nature.
Sources (verified)
- tokio.rs/blog/2025-01-01-announcing-axum-0-8-0 — path syntax, Option extractor,
#[async_trait] removal (fetched 2026-07-05)
- crates.io — axum 0.8.9, sqlx 0.9.0, tokio 1.52.3, tracing 0.1.44 (current at fetch)
1---2name: rust-web-backend3description: Use when building a REST/HTTP backend in Rust — axum routing, extractors, shared state, middleware, error responses, sqlx database access. Not for raw async/concurrency (rust-async-concurrency).4versions:5 axum: "0.8.9"6 tokio: "1.52"7 sqlx: "0.9"8 tracing: "0.1"9 rust-edition: "2024"10user-invocable: false11references: references/architecture.md, references/error-handling.md, references/database.md, references/observability.md, references/templates/rest-service.md12related-skills: rust-async-concurrency, solid-rust13metadata:14 source: https://skillmd.com/skills/fusengine/rust-web-backend15---1617<objective>18This skill covers the 2026 standard Rust web-backend stack: axum 0.8.x routing (including19the /{id} path syntax that replaced /:id) and extractors, sharing state via State<T>,20composing tower-http middleware (trace, cors, timeout, compression), mapping domain errors21to IntoResponse instead of unwrapping in handlers, and sqlx 0.9 database access with22compile-time-checked query!/query_as! (including the .sqlx/ offline cache for CI).2324It also names the honest alternatives — sea-orm for an ActiveRecord-style ORM, diesel for a25mature but synchronous alternative needing spawn_blocking — and structured observability via26tracing.2728Out of scope: raw async/concurrency primitives (channels, locks, task spawning) belong to29rust-async-concurrency; cross-domain crate selection belongs to rust-ecosystem-crates.30</objective>3132# Rust Web Backend3334## Agent Workflow (MANDATORY)3536Before building the service, spawn in parallel:37381. **fuse-ai-pilot:explore-codebase** — detect the existing router, state, and DB layer392. **fuse-ai-pilot:research-expert** — verify current axum/sqlx APIs via Context7/Exa (axum 0.8 changed several APIs)403. **mcp__context7__query-docs** — pull exact extractor/handler signatures4142After building, run **fuse-ai-pilot:sniper**.4344---4546## The 2026 standard stack4748| Layer | Crate | Why |49|-------|-------|-----|50| **Runtime** | tokio | De-facto async runtime; everything targets it |51| **HTTP framework** | axum 0.8.x | Tower-based, extractor ergonomics, minimal magic |52| **Middleware** | tower / tower-http | Composable layers (trace, cors, timeout, compression) |53| **Database** | sqlx 0.9 | Async, `query!` compile-time-checked SQL, no DSL; Postgres/MySQL/SQLite |54| **Observability** | tracing + tracing-subscriber | Structured, async-aware spans and logs |5556**Honest alternatives:** `sea-orm` (ActiveRecord-style ORM, higher-level than sqlx), `diesel` 2.x (mature, **synchronous** — needs `spawn_blocking` or a sync pool in async apps). Prefer sqlx for the standard stack; reach for these only when their model fits.5758---5960## Critical Rules61621. **axum 0.8 path syntax is `/{id}`, not `/:id`** — `/*rest` became `/{*rest}`. The old `matchit` syntax will not compile.632. **Errors implement `IntoResponse`** — never `.unwrap()` in a handler. Map domain errors to a status + body via one app error type.643. **Share state with `State<T>`, wrapped once** — put the pool/config in an `Arc`-friendly struct; extract it with `State`, do not use globals.654. **`sqlx::query!` needs `DATABASE_URL` at compile time** — or a committed `.sqlx/` offline cache (`cargo sqlx prepare`). Plan this before CI.665. **No `#[async_trait]` on axum extractors** — 0.8 uses RPITIT; custom `FromRequestParts` impls must drop the macro.6768---6970## Reference Guide7172### Concepts7374| Topic | Reference | When to Consult |75|-------|-----------|-----------------|76| **Architecture** | [architecture.md](references/architecture.md) | Router, extractors, State, tower middleware layout |77| **Error handling** | [error-handling.md](references/error-handling.md) | App error type + `IntoResponse` |78| **Database** | [database.md](references/database.md) | sqlx pool, `query!`, migrations, alternatives |79| **Observability** | [observability.md](references/observability.md) | tracing spans, subscriber, request logging |8081### Templates8283| Template | When to Use |84|----------|-------------|85| [rest-service.md](references/templates/rest-service.md) | Complete minimal REST service (router + state + handlers + errors + tracing) |8687---8889## Quick Reference9091### Router with the 0.8 path syntax9293```rust94let app = Router::new()95 .route("/users", get(list).post(create))96 .route("/users/{id}", get(show)) // NOT /:id97 .with_state(state);98```99100→ See [architecture.md](references/architecture.md)101102### Compile-time-checked query103104```rust105let user = sqlx::query_as!(User, "SELECT id, name FROM users WHERE id = $1", id)106 .fetch_optional(&pool)107 .await?;108```109110→ See [database.md](references/database.md)111112---113114## Best Practices115116### DO117- Keep one app error type that implements `IntoResponse`.118- Layer cross-cutting concerns (trace, timeout, cors) via `tower-http`.119- Verify queries at compile time with `query!`/`query_as!`.120121### DON'T122- Use `/:id` route syntax (0.7 and earlier only).123- `.unwrap()` in handlers — return a typed error.124- Reach for diesel in async code without accounting for its sync nature.125126---127128## Sources (verified)129130- tokio.rs/blog/2025-01-01-announcing-axum-0-8-0 — path syntax, Option extractor, `#[async_trait]` removal (fetched 2026-07-05)131- crates.io — axum 0.8.9, sqlx 0.9.0, tokio 1.52.3, tracing 0.1.44 (current at fetch)