Rust Axum : API REST haute performance — tutoriel 2026

Introduction

En 2026, la question du choix technologique pour construire une API REST n’est plus seulement une affaire de popularité : c’est une décision économique qui touche directement au coût d’infrastructure, à la fiabilité sous charge et à la durée de vie du code. Dans ce contexte, Axum s’est imposé comme l’une des options les plus sérieuses de l’écosystème Rust. Développé et maintenu par l’équipe de Tokio — la runtime asynchrone de référence pour Rust — Axum repose sur des fondations éprouvées : le runtime tokio, la couche de service abstraite tower, et l’outillage HTTP de bas niveau hyper. Ce n’est pas un cadre qui réinvente la roue : c’est une couche ergonomique posée sur des briques de production que la communauté Rust utilise depuis plusieurs années.

Ce qui différencie Axum des autres frameworks web Rust, c’est d’abord sa philosophie de conception. Là où Actix-Web choisit son propre système d’acteurs, et où Rocket privilégie la magie des macros procédurales, Axum opte pour la composabilité explicite. Chaque handler est une fonction async standard. Chaque extractor de paramètre implémente un trait générique. Le routeur compose des services tower::Service, ce qui signifie que tout le middleware de l’écosystème Tower — logging, compression, rate-limiting, authentification — s’intègre sans friction. Le résultat est un framework qui reste proche du métal tout en restant lisible et maintenable.

Pour une PME ou une startup tech en Afrique de l’Ouest qui cherche à exposer une API pour son application mobile, son service de paiement Wave ou CinetPay, ou sa plateforme SaaS, Axum présente un argument supplémentaire : le binaire compilé pèse moins de 5 Mo, tourne sans runtime JVM ni interpréteur Python, et maintient des latences sub-milliseconde même sur un VPS entrée de gamme. Ce tutoriel vous mène de zéro à une API REST production-ready en environ 40 minutes de lecture active.

Prérequis

Avant de commencer, assurez-vous d’avoir les éléments suivants en place sur votre machine de développement. Ce tutoriel cible Rust 1.75 ou supérieur, qui est la version minimale requise par Axum 0.7.x pour bénéficier du support complet des types async fn dans les traits — une fonctionnalité qui simplifie considérablement l’écriture des handlers et des couches middleware.

• Rust et Cargo : installer via rustup.rs (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh). Vérifier avec rustc --version.
• PostgreSQL 14+ : une instance locale ou distante accessible (pour l’étape 6). En développement, un docker run -e POSTGRES_PASSWORD=secret -p 5432:5432 postgres:16-alpine suffit.
• Docker : pour l’étape de déploiement (étape 7).
• sqlx-cli (optionnel mais recommandé) : cargo install sqlx-cli --no-default-features --features postgres.
• Niveau : intermédiaire — vous êtes à l’aise avec Rust de base (ownership, borrowing, traits). Vous n’avez pas besoin d’avoir déjà écrit une API web en Rust.
• Temps estimé : 40 minutes en lisant, 90 minutes en codant au fur et à mesure.

Étape 1 — Pourquoi Axum plutôt qu’Actix-Web ou Rocket ?

La question revient systématiquement dès qu’on évoque un framework web Rust. Les trois noms les plus cités sont Actix-Web, Rocket et Axum. Comprendre leurs différences vous évitera des regrets six mois plus tard.

Actix-Web est le plus ancien des trois et historiquement le plus performant dans les benchmarks synthétiques TechEmpower. Il maintient son propre runtime basé sur un système d’acteurs, ce qui lui permet d’atteindre des performances remarquables en solo. Le problème apparaît à l’intégration : si votre application utilise déjà Tokio (pour accéder à Postgres via sqlx, pour envoyer des emails via lettre, pour appeler une API tierce via reqwest), vous vous retrouvez à gérer deux runtimes asynchrones qui coexistent de manière parfois imprévisible. Actix-Web 4.x a largement corrigé cela en s’appuyant sur Tokio, mais l’écosystème reste plus cloisonné.

Rocket mise sur une expérience développeur très fluide grâce à ses macros procédurales. Écrire une route ressemble à Ruby on Rails ou à Python FastAPI : propre, déclaratif, peu de friction. L’inconvénient principal est que cette magie se paie à la compilation (temps de build plus long) et qu’elle crée une dépendance forte aux patterns Rocket — il est plus difficile de réutiliser vos handlers dans un contexte non-Rocket, par exemple dans un worker Lambda ou un test d’intégration hors-framework.

Axum choisit une voie différente : zéro macro obligatoire, composabilité maximale via Tower, et une intégration Tokio native puisqu’il est maintenu par la même équipe. Chaque handler est une fonction async ordinaire. Les extractors (les mécanismes pour récupérer le body JSON, les paramètres d’URL, les headers) implémentent un trait standard que vous pouvez étendre ou remplacer. Le middleware est n’importe quel tower::Layer, ce qui signifie que vous pouvez utiliser tower-http pour le logging et la compression, ou écrire vos propres couches en quelques lignes.

Pour un projet de PME en 2026, Axum est le choix le plus sage : l’équipe Tokio est pérenne, la compatibilité avec l’écosystème async Rust est totale, et la courbe d’apprentissage, bien que réelle, mène à une maîtrise durable plutôt qu’à une dépendance à la magie du framework. Les benchmarks récents montrent qu’Axum atteint des performances comparables à Actix-Web dans les scénarios réalistes (avec I/O base de données), et nettement supérieures à la plupart des frameworks Node.js ou Python.

Étape 2 — cargo init et configuration du Cargo.toml

Créons le projet depuis zéro. La commande cargo new génère une structure minimale ; nous l’enrichissons ensuite avec les dépendances précises dont nous aurons besoin tout au long de ce tutoriel. Il est important de choisir les versions avec soin dès le départ pour éviter les incompatibilités entre crates qui partagent des traits asynchrones.

# Créer le projet
cargo new mon-api-axum --bin
cd mon-api-axum

Cette commande crée un répertoire mon-api-axum/ avec un Cargo.toml minimal et un src/main.rs de base. Ouvrez maintenant Cargo.toml et remplacez la section [dependencies] par le contenu suivant :

[package]
name = "mon-api-axum"
version = "0.1.0"
edition = "2021"

[dependencies]
# Framework web et runtime async
axum = { version = "0.7", features = ["macros"] }
tokio = { version = "1", features = ["full"] }
tower = "0.4"
tower-http = { version = "0.5", features = ["trace", "cors", "compression-gzip"] }

# Sérialisation / désérialisation JSON
serde = { version = "1", features = ["derive"] }
serde_json = "1"

# Base de données Postgres
sqlx = { version = "0.7", features = ["runtime-tokio-rustls", "postgres", "uuid", "chrono", "migrate"] }

# JWT pour l'authentification
jsonwebtoken = "9"

# Variables d'environnement
dotenvy = "0.15"

# Logging structuré
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

# Gestion des erreurs
thiserror = "1"
anyhow = "1"

# UUID pour les identifiants
uuid = { version = "1", features = ["v4", "serde"] }

# Dates et heures
chrono = { version = "0.4", features = ["serde"] }

[profile.release]
opt-level = 3
lto = true
codegen-units = 1
strip = true

Deux points méritent une explication ici. Premièrement, la section [profile.release] avec lto = true (Link-Time Optimization) et strip = true est ce qui permet d’obtenir un binaire final d’environ 4 à 6 Mo au lieu de 15 à 20 Mo. La LTO permet au compilateur d’optimiser à travers les frontières des crates, ce qui améliore à la fois la taille et les performances. L’option strip = true supprime les symboles de debug du binaire. Deuxièmement, sqlx est configuré avec runtime-tokio-rustls plutôt que runtime-tokio-native-tls, ce qui évite une dépendance sur OpenSSL système — un choix crucial pour le cross-compilation et les images Docker Alpine.

Étape 3 — Premier handler GET /health

Avant de construire des routes complexes, il est utile de vérifier que le projet compile et que le serveur démarre correctement. Le endpoint /health est le plus simple qui soit : il ne prend aucun paramètre et renvoie un statut HTTP 200 avec un corps JSON. C’est aussi le premier endpoint que configurera votre load balancer ou votre Kubernetes liveness probe en production.

Remplacez le contenu de src/main.rs :

use axum::{
    http::StatusCode,
    response::IntoResponse,
    routing::get,
    Json, Router,
};
use serde_json::json;
use std::net::SocketAddr;

#[tokio::main]
async fn main() {
    // Initialiser le logging
    tracing_subscriber::fmt()
        .with_env_filter("mon_api_axum=debug,tower_http=debug")
        .init();

    // Construire le routeur
    let app = Router::new()
        .route("/health", get(health_handler));

    // Démarrer le serveur
    let addr = SocketAddr::from(([0, 0, 0, 0], 8080));
    tracing::info!("Serveur démarré sur http://{}", addr);

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

async fn health_handler() -> impl IntoResponse {
    (StatusCode::OK, Json(json!({
        "status": "ok",
        "version": env!("CARGO_PKG_VERSION")
    })))
}

Lancez cargo run (le premier build prend 1 à 2 minutes le temps de compiler toutes les dépendances). Une fois le serveur démarré, testez avec curl http://localhost:8080/health — vous devez obtenir {"status":"ok","version":"0.1.0"}. Notez la syntaxe impl IntoResponse comme type de retour du handler : c’est le trait central d’Axum pour convertir n’importe quelle valeur en réponse HTTP. Un tuple (StatusCode, Json) implémente automatiquement ce trait, ce qui vous évite d’assembler manuellement les headers et le body.

Étape 4 — Routes RESTful avec extractors

Un CRUD complet nécessite de gérer des paramètres d’URL, un body JSON, et des codes de statut différents selon le résultat. Axum résout cela via le concept d’extractors : des types qui implémentent le trait FromRequest ou FromRequestParts et sont injectés directement dans la signature de vos fonctions handler par le framework. Cela ressemble à l’injection de dépendance de Spring ou FastAPI, sauf que c’est entièrement vérifiable à la compilation.

Créons un module src/routes/articles.rs qui expose quatre routes CRUD pour une ressource Article :

// src/routes/articles.rs
use axum::{
    extract::{Path, State},
    http::StatusCode,
    response::IntoResponse,
    Json,
};
use serde::{Deserialize, Serialize};
use uuid::Uuid;

// DTO entrant pour la création / mise à jour
#[derive(Debug, Deserialize)]
pub struct CreateArticleDto {
    pub titre: String,
    pub contenu: String,
    pub auteur_id: Uuid,
}

// DTO sortant
#[derive(Debug, Serialize)]
pub struct ArticleResponse {
    pub id: Uuid,
    pub titre: String,
    pub contenu: String,
    pub auteur_id: Uuid,
    pub cree_le: String,
}

// GET /articles/:id
pub async fn get_article(
    Path(id): Path,
    State(pool): State,
) -> impl IntoResponse {
    // Simulation — la vraie requête sqlx arrive à l'étape 6
    tracing::info!(article_id = %id, "Récupération article");
    StatusCode::NOT_IMPLEMENTED
}

// POST /articles
pub async fn create_article(
    State(pool): State,
    Json(body): Json,
) -> impl IntoResponse {
    tracing::info!(titre = %body.titre, "Création article");
    StatusCode::NOT_IMPLEMENTED
}

// DELETE /articles/:id
pub async fn delete_article(
    Path(id): Path,
    State(_pool): State,
) -> impl IntoResponse {
    tracing::info!(article_id = %id, "Suppression article");
    StatusCode::NO_CONTENT
}

Plusieurs extractors sont utilisés ici simultanément dans la même signature de fonction, et Axum les résout tous dans le bon ordre. Path extrait et désérialise automatiquement le segment :id de l’URL, échouant avec un 400 Bad Request si la valeur n’est pas un UUID valide — sans que vous écriviez une seule ligne de validation. State injecte le pool de connexions que vous avez enregistré au démarrage de l’application (nous verrons cela à l’étape 6). Json désérialise le body JSON et renvoie automatiquement une erreur 422 Unprocessable Entity si des champs requis sont manquants ou du mauvais type.

Étape 5 — Middleware : logging et authentification JWT

Le middleware dans Axum est basé sur tower::Layer, ce qui signifie qu’il s’applique uniformément à toutes les routes d’un routeur ou à un sous-ensemble via Router::nest(). Nous allons ajouter deux couches essentielles : le logging des requêtes HTTP via tower-http, et un middleware d’authentification JWT maison pour protéger les routes sensibles.

Modifiez src/main.rs pour ajouter le middleware de logging :

use tower_http::trace::TraceLayer;
use tower_http::cors::{CorsLayer, Any};

let app = Router::new()
    .route("/health", get(health_handler))
    .nest("/api/v1", api_router())
    .layer(
        tower::ServiceBuilder::new()
            .layer(TraceLayer::new_for_http())
            .layer(
                CorsLayer::new()
                    .allow_origin(Any)
                    .allow_methods(Any)
                    .allow_headers(Any)
            )
    );

Pour l’authentification JWT, créez src/middleware/auth.rs qui extrait et valide le token Bearer :

// src/middleware/auth.rs
use axum::{
    extract::FromRequestParts,
    http::{request::Parts, StatusCode},
    response::{IntoResponse, Response},
};
use jsonwebtoken::{decode, DecodingKey, Validation, Algorithm};
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
pub struct Claims {
    pub sub: String,      // identifiant utilisateur
    pub role: String,     // "admin" | "user"
    pub exp: usize,       // timestamp d'expiration (Unix)
}

// Extractor d'authentification — utilisable directement dans les handlers
pub struct AuthUser(pub Claims);

#[axum::async_trait]
impl FromRequestParts for AuthUser
where
    S: Send + Sync,
{
    type Rejection = Response;

    async fn from_request_parts(parts: &mut Parts, _state: &S) -> Result {
        // Extraire le header Authorization
        let auth_header = parts
            .headers
            .get(axum::http::header::AUTHORIZATION)
            .and_then(|v| v.to_str().ok())
            .ok_or_else(|| {
                (StatusCode::UNAUTHORIZED, "Header Authorization manquant").into_response()
            })?;

        // Vérifier le préfixe Bearer
        let token = auth_header
            .strip_prefix("Bearer ")
            .ok_or_else(|| {
                (StatusCode::UNAUTHORIZED, "Format invalide — attendu: Bearer ").into_response()
            })?;

        // Décoder et valider le JWT
        let secret = std::env::var("JWT_SECRET").unwrap_or_else(|_| "dev-secret".to_string());
        let claims = decode::(
            token,
            &DecodingKey::from_secret(secret.as_bytes()),
            &Validation::new(Algorithm::HS256),
        )
        .map_err(|e| {
            tracing::warn!(error = %e, "JWT invalide");
            (StatusCode::UNAUTHORIZED, "Token JWT invalide ou expiré").into_response()
        })?;

        Ok(AuthUser(claims.claims))
    }
}

DATABASE_URL=postgres://postgres:secret@localhost:5432/mon_api_db
JWT_SECRET=changez-moi-en-production-32-chars-minimum
RUST_LOG=mon_api_axum=debug,sqlx=warn,tower_http=info

# Créer la base de données
sqlx database create

# Créer le répertoire de migrations
mkdir -p migrations

# Créer la première migration
sqlx migrate add create_articles

-- migrations/XXXXXXXXXXXXXX_create_articles.sql
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

CREATE TABLE articles (
    id          UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    titre       VARCHAR(255) NOT NULL,
    contenu     TEXT NOT NULL,
    auteur_id   UUID NOT NULL,
    cree_le     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    mis_a_jour  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_articles_auteur ON articles(auteur_id);
CREATE INDEX idx_articles_cree_le ON articles(cree_le DESC);

// Dans main() — connexion au pool
let database_url = std::env::var("DATABASE_URL")
    .expect("DATABASE_URL doit être défini");

let pool = sqlx::PgPool::connect(&database_url)
    .await
    .expect("Impossible de se connecter à PostgreSQL");

// Lancer les migrations automatiquement au démarrage
sqlx::migrate!("./migrations")
    .run(&pool)
    .await
    .expect("Échec des migrations");

// Injecter le pool dans l'état de l'application
let app = Router::new()
    /* ... routes ... */
    .with_state(pool);

pub async fn create_article(
    State(pool): State,
    Json(body): Json,
) -> Result<(StatusCode, Json), (StatusCode, String)> {
    let article = sqlx::query_as!(
        ArticleDb,
        r#"
            INSERT INTO articles (titre, contenu, auteur_id)
            VALUES ($1, $2, $3)
            RETURNING id, titre, contenu, auteur_id,
                      cree_le::text as "cree_le!"
        "#,
        body.titre,
        body.contenu,
        body.auteur_id
    )
    .fetch_one(&pool)
    .await
    .map_err(|e| {
        tracing::error!(error = %e, "Erreur INSERT article");
        (StatusCode::INTERNAL_SERVER_ERROR, "Erreur base de données".to_string())
    })?;

    Ok((StatusCode::CREATED, Json(ArticleResponse {
        id: article.id,
        titre: article.titre,
        contenu: article.contenu,
        auteur_id: article.auteur_id,
        cree_le: article.cree_le,
    })))
}

# Étape 1 : compilation
FROM rust:1.75-alpine AS builder

# Dépendances système nécessaires pour la compilation statique avec sqlx + rustls
RUN apk add --no-cache musl-dev pkgconfig

WORKDIR /app

# Copier les manifestes en premier pour bénéficier du cache Docker
COPY Cargo.toml Cargo.lock ./

# Trick : créer un src/main.rs factice pour compiler uniquement les dépendances
RUN mkdir src && echo 'fn main() {}' > src/main.rs
RUN cargo build --release
RUN rm src/main.rs

# Copier le vrai code source et compiler l'application
COPY src ./src
COPY migrations ./migrations
RUN touch src/main.rs && cargo build --release

# Étape 2 : image finale légère
FROM alpine:3.19

RUN apk add --no-cache ca-certificates tzdata

# Créer un utilisateur non-root pour la sécurité
RUN addgroup -S appgroup && adduser -S appuser -G appgroup

WORKDIR /app
COPY --from=builder /app/target/release/mon-api-axum ./mon-api-axum
COPY --from=builder /app/migrations ./migrations

USER appuser
EXPOSE 8080

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s \
    CMD wget -q -O- http://localhost:8080/health || exit 1

CMD ["./mon-api-axum"]

# Build (environ 5 minutes la première fois, <1 minute grâce au cache ensuite)
docker build -t mon-api-axum:latest .

# Vérifier la taille de l'image
docker image ls mon-api-axum
# Attendu : entre 12 et 18 Mo (binaire ~5 Mo + Alpine ~8 Mo)

# Lancer avec les variables d'environnement
docker run -d \
  --name mon-api \
  -p 8080:8080 \
  -e DATABASE_URL="postgres://user:pass@host:5432/db" \
  -e JWT_SECRET="votre-secret-32-chars-minimum" \
  mon-api-axum:latest