Rust + Axum Backend Mastery

Production-ready patterns for building scalable Rust backends with Axum and PostgreSQL.

When to Use This Skill

• Building REST APIs or GraphQL with Axum
• Designing database schemas with SQLx + PostgreSQL
• Implementing authentication (JWT, OAuth 2.1)
• Writing async code with Tokio
• Creating middleware and extractors
• Testing Axum applications
• Deploying to production (Docker, Kubernetes)
• Performance optimization and monitoring

---

Quick Start

Minimal Axum Server

use axum::{routing::get, Router};

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/", get(|| async { "Hello, Axum!" }));

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Essential Dependencies (Cargo.toml)

[dependencies]
axum = "0.7"
tokio = { version = "1", features = ["full"] }
tower = "0.4"
tower-http = { version = "0.5", features = ["cors", "trace"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
sqlx = { version = "0.7", features = ["runtime-tokio", "postgres", "uuid", "time"] }
uuid = { version = "1", features = ["v4", "serde"] }
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
thiserror = "1"
anyhow = "1"

---

Reference Navigation

Core Rust Patterns

| Topic | File | Description | |-------|------|-------------| | Rust Idioms | rust-patterns.md | Enums, iterators, error handling | | Async/Tokio | async-tokio.md | Async patterns, spawn, channels |

Axum Framework (70%)

| Topic | File | Description | |-------|------|-------------| | Axum Guide | axum-complete-guide.md | Routing, handlers, state | | Extractors | axum-extractors.md | Path, Query, Json, State | | Middleware | middleware-patterns.md | Tower layers, auth middleware |

Database (PostgreSQL)

| Topic | File | Description | |-------|------|-------------| | SQLx | sqlx-postgresql.md | Queries, transactions, migrations | | Patterns | database-patterns.md | Connection pools, optimization |

Architecture

| Topic | File | Description | |-------|------|-------------| | Project Structure | project-structure.md | Folder organization | | Patterns | architecture-patterns.md | Microservices, modulith |

Security & Auth

| Topic | File | Description | |-------|------|-------------| | Authentication | authentication.md | JWT, OAuth 2.1, sessions | | Security | security-owasp.md | OWASP Top 10 for Rust |

Testing & Quality

| Topic | File | Description | |-------|------|-------------| | Testing | testing-guide.md | Unit, integration, E2E | | Error Handling | error-handling.md | HTTP errors, thiserror |

DevOps & Production

| Topic | File | Description | |-------|------|-------------| | Deployment | deployment.md | Docker, Kubernetes | | Monitoring | monitoring.md | Tracing, Prometheus |

---

Decision Guide

When to Choose Axum (70% - Primary)

✅ Choose Axum when:
- Building new Rust web projects
- Need tower ecosystem compatibility
- Want ergonomic, type-safe extractors
- Prefer modular, composable design
- Need excellent async performance

When to Consider Alternatives (30%)

Actix-web - When you need:
- Maximum raw performance (benchmarks leader)
- Actor model for complex state
- Established ecosystem with more examples

Rocket - When you need:
- Simplest learning curve
- Most "magical" developer experience
- Rapid prototyping

---

Core Patterns Summary

Error Handling

use axum::{http::StatusCode, response::IntoResponse, Json};
use serde_json::json;

pub enum AppError {
    NotFound(String),
    Database(sqlx::Error),
    Unauthorized,
}

impl IntoResponse for AppError {
    fn into_response(self) -> axum::response::Response {
        let (status, message) = match self {
            Self::NotFound(msg) => (StatusCode::NOT_FOUND, msg),
            Self::Database(e) => (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()),
            Self::Unauthorized => (StatusCode::UNAUTHORIZED, "Unauthorized".into()),
        };
        (status, Json(json!({ "error": message }))).into_response()
    }
}

Handler Pattern

use axum::{extract::{Path, State}, Json};
use uuid::Uuid;

async fn get_user(
    State(pool): State<PgPool>,
    Path(id): Path<Uuid>,
) -> Result<Json<User>, AppError> {
    let user = sqlx::query_as!(User, "SELECT * FROM users WHERE id = $1", id)
        .fetch_optional(&pool)
        .await?
        .ok_or_else(|| AppError::NotFound("User not found".into()))?;
    
    Ok(Json(user))
}

State Management

use std::sync::Arc;
use sqlx::PgPool;

#[derive(Clone)]
pub struct AppState {
    pub db: PgPool,
    pub config: Arc<Config>,
}

let app = Router::new()
    .route("/users/:id", get(get_user))
    .with_state(AppState { db: pool, config: Arc::new(config) });

---

Examples

• axum-starter - Minimal project template
• axum-rest-api - Complete REST API with auth

---

Best Practices Checklist

API Design

• [ ] Use proper HTTP methods (GET, POST, PUT, DELETE)
• [ ] Return appropriate status codes
• [ ] Validate input with extractors
• [ ] Document with OpenAPI/Swagger

Database

• [ ] Use connection pooling (SQLx built-in)
• [ ] Always use parameterized queries
• [ ] List columns explicitly (no SELECT *)
• [ ] Use transactions for multi-step operations

Security

• [ ] Validate all input
• [ ] Use Argon2id for passwords
• [ ] Implement rate limiting
• [ ] Set security headers (tower-http)

Testing

• [ ] Unit tests for business logic
• [ ] Integration tests for handlers
• [ ] Use testcontainers for database tests

Production

• [ ] Structured logging (tracing)
• [ ] Health check endpoints
• [ ] Graceful shutdown
• [ ] Docker multi-stage builds

---

Resources

• Axum: https://docs.rs/axum
• Tower: https://docs.rs/tower
• SQLx: https://docs.rs/sqlx
• Tokio: https://tokio.rs