Rust Axumとは？Tokioベースの次世代Webフレームワーク完全ガイド

// 0.7以前
Router::new().route("/users/:id", get(get_user));

// 0.8以降
Router::new().route("/users/{id}", get(get_user));

// 0.7以前
#[async_trait]
impl<S> FromRequest<S> for MyExtractor
where
    S: Send + Sync,
{
    type Rejection = StatusCode;

    async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
        // ...
    }
}

// 0.8以降（#[async_trait]が不要）
impl<S> FromRequest<S> for MyExtractor
where
    S: Send + Sync,
{
    type Rejection = StatusCode;

    async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
        // ...
    }
}

[dependencies]
axum = { version = "0.8", features = ["json", "query"] }

use axum::extract::{Path, Query};
use serde::Deserialize;

#[derive(Deserialize)]
struct Pagination {
    page: u32,
    per_page: u32,
}

async fn get_user(
    Path(user_id): Path<u64>,
    Query(pagination): Query<Pagination>,
) -> String {
    format!(
        "User {} - page {}, {} items",
        user_id, pagination.page, pagination.per_page
    )
}

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup default stable

cargo new axum-demo
cd axum-demo

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

[dependencies]
axum = "0.8"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"

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

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

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await
        .unwrap();

    println!("Listening on http://localhost:3000");
    axum::serve(listener, app).await.unwrap();
}

cargo run

use axum::{
    routing::{get, post, put, delete},
    Router,
};

let app = Router::new()
    .route("/", get(index))
    .route("/users", get(list_users).post(create_user))
    .route("/users/{id}", get(get_user).put(update_user).delete(delete_user));

use axum::extract::Path;

async fn get_user(Path(id): Path<u64>) -> String {
    format!("User ID: {}", id)
}

// 複数のパスパラメータ
async fn get_user_post(
    Path((user_id, post_id)): Path<(u64, u64)>,
) -> String {
    format!("User {} / Post {}", user_id, post_id)
}

let app = Router::new()
    .route("/users/{id}", get(get_user))
    .route("/users/{user_id}/posts/{post_id}", get(get_user_post));

use axum::extract::Query;
use serde::Deserialize;

#[derive(Deserialize)]
struct SearchParams {
    q: String,
    page: Option<u32>,
    sort: Option<String>,
}

async fn search(Query(params): Query<SearchParams>) -> String {
    let page = params.page.unwrap_or(1);
    format!("Searching '{}' - page {}", params.q, page)
}

fn user_routes() -> Router {
    Router::new()
        .route("/", get(list_users).post(create_user))
        .route("/{id}", get(get_user).put(update_user).delete(delete_user))
}

fn post_routes() -> Router {
    Router::new()
        .route("/", get(list_posts).post(create_post))
        .route("/{id}", get(get_post))
}

let app = Router::new()
    .nest("/users", user_routes())
    .nest("/posts", post_routes());

use axum::Json;
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct CreateUser {
    name: String,
    email: String,
}

#[derive(Serialize)]
struct UserResponse {
    id: u64,
    name: String,
    email: String,
}

async fn create_user(
    Json(payload): Json<CreateUser>,
) -> Json<UserResponse> {
    let response = UserResponse {
        id: 1,
        name: payload.name,
        email: payload.email,
    };
    Json(response)
}

use axum::extract::State;
use std::sync::Arc;

#[derive(Clone)]
struct AppState {
    db_pool: sqlx::PgPool,
    config: Arc<AppConfig>,
}

struct AppConfig {
    api_key: String,
    max_retries: u32,
}

async fn get_users(
    State(state): State<AppState>,
) -> Json<Vec<UserResponse>> {
    // state.db_pool を使ってデータベースにアクセス
    todo!()
}

// Routerに状態を注入
let state = AppState {
    db_pool: pool,
    config: Arc::new(config),
};

let app = Router::new()
    .route("/users", get(get_users))
    .with_state(state);

use axum::{
    http::{StatusCode, HeaderMap},
    response::IntoResponse,
};

async fn custom_response() -> impl IntoResponse {
    let mut headers = HeaderMap::new();
    headers.insert("X-Custom-Header", "my-value".parse().unwrap());

    (StatusCode::CREATED, headers, Json(serde_json::json!({
        "message": "Resource created"
    })))
}

use axum::{
    extract::FromRequestParts,
    http::{request::Parts, StatusCode},
};

struct AuthenticatedUser {
    user_id: u64,
    role: String,
}

impl<S> FromRequestParts<S> for AuthenticatedUser
where
    S: Send + Sync,
{
    type Rejection = StatusCode;

    async fn from_request_parts(
        parts: &mut Parts,
        _state: &S,
    ) -> Result<Self, Self::Rejection> {
        let auth_header = parts
            .headers
            .get("Authorization")
            .and_then(|v| v.to_str().ok())
            .ok_or(StatusCode::UNAUTHORIZED)?;

        // トークンを検証してユーザー情報を取得
        let user = verify_token(auth_header)
            .map_err(|_| StatusCode::UNAUTHORIZED)?;

        Ok(user)
    }
}

// ハンドラで使うだけで認証が自動適用される
async fn protected_route(user: AuthenticatedUser) -> String {
    format!("Welcome, user {}", user.user_id)
}

[dependencies]
tower-http = { version = "0.6", features = ["cors", "compression", "trace", "timeout"] }
tracing = "0.1"
tracing-subscriber = "0.3"

use axum::Router;
use tower_http::{
    cors::{CorsLayer, Any},
    compression::CompressionLayer,
    trace::TraceLayer,
    timeout::TimeoutLayer,
};
use std::time::Duration;

let app = Router::new()
    .route("/", get(index))
    .route("/users", get(list_users))
    .layer(TraceLayer::new_for_http())
    .layer(CompressionLayer::new())
    .layer(
        CorsLayer::new()
            .allow_origin(Any)
            .allow_methods(Any)
            .allow_headers(Any),
    )
    .layer(TimeoutLayer::new(Duration::from_secs(30)));

use axum::{
    middleware::{self, Next},
    http::Request,
    response::Response,
};
use std::time::Instant;

async fn timing_middleware(
    request: Request<axum::body::Body>,
    next: Next,
) -> Response {
    let start = Instant::now();
    let path = request.uri().path().to_string();
    let method = request.method().to_string();

    let response = next.run(request).await;

    let duration = start.elapsed();
    tracing::info!(
        method = %method,
        path = %path,
        duration_ms = %duration.as_millis(),
        status = %response.status(),
        "Request completed"
    );

    response
}

let app = Router::new()
    .route("/", get(index))
    .layer(middleware::from_fn(timing_middleware));

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

// アプリケーション固有のエラー型
enum AppError {
    NotFound(String),
    BadRequest(String),
    InternalError(anyhow::Error),
}

// エラー型をHTTPレスポンスに変換
impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, message) = match self {
            AppError::NotFound(msg) => (StatusCode::NOT_FOUND, msg),
            AppError::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg),
            AppError::InternalError(err) => {
                tracing::error!("Internal error: {:?}", err);
                (
                    StatusCode::INTERNAL_SERVER_ERROR,
                    "Internal server error".to_string(),
                )
            }
        };

        let body = serde_json::json!({
            "error": message,
        });

        (status, Json(body)).into_response()
    }
}

// anyhow::Errorからの自動変換
impl From<anyhow::Error> for AppError {
    fn from(err: anyhow::Error) -> Self {
        AppError::InternalError(err)
    }
}

// ハンドラでResult<T, AppError>を返す
async fn get_user(Path(id): Path<u64>) -> Result<Json<UserResponse>, AppError> {
    let user = find_user(id)
        .await
        .ok_or_else(|| AppError::NotFound(format!("User {} not found", id)))?;

    Ok(Json(user))
}

src/
├── main.rs          # エントリポイント
├── handlers.rs      # ハンドラ関数
└── models.rs        # データモデル

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Task {
    pub id: u64,
    pub title: String,
    pub description: Option<String>,
    pub completed: bool,
}

#[derive(Debug, Deserialize)]
pub struct CreateTask {
    pub title: String,
    pub description: Option<String>,
}

#[derive(Debug, Deserialize)]
pub struct UpdateTask {
    pub title: Option<String>,
    pub description: Option<String>,
    pub completed: Option<bool>,
}

use axum::{
    extract::{Path, State},
    http::StatusCode,
    Json,
};
use std::sync::Arc;
use tokio::sync::RwLock;
use std::collections::HashMap;

use crate::models::{Task, CreateTask, UpdateTask};

pub type SharedState = Arc<RwLock<HashMap<u64, Task>>>;

pub async fn list_tasks(
    State(state): State<SharedState>,
) -> Json<Vec<Task>> {
    let tasks = state.read().await;
    let mut result: Vec<Task> = tasks.values().cloned().collect();
    result.sort_by_key(|t| t.id);
    Json(result)
}

pub async fn create_task(
    State(state): State<SharedState>,
    Json(payload): Json<CreateTask>,
) -> (StatusCode, Json<Task>) {
    let mut tasks = state.write().await;
    let id = tasks.len() as u64 + 1;

    let task = Task {
        id,
        title: payload.title,
        description: payload.description,
        completed: false,
    };

    tasks.insert(id, task.clone());
    (StatusCode::CREATED, Json(task))
}

pub async fn get_task(
    State(state): State<SharedState>,
    Path(id): Path<u64>,
) -> Result<Json<Task>, StatusCode> {
    let tasks = state.read().await;
    tasks
        .get(&id)
        .cloned()
        .map(Json)
        .ok_or(StatusCode::NOT_FOUND)
}

pub async fn update_task(
    State(state): State<SharedState>,
    Path(id): Path<u64>,
    Json(payload): Json<UpdateTask>,
) -> Result<Json<Task>, StatusCode> {
    let mut tasks = state.write().await;
    let task = tasks.get_mut(&id).ok_or(StatusCode::NOT_FOUND)?;

    if let Some(title) = payload.title {
        task.title = title;
    }
    if let Some(description) = payload.description {
        task.description = Some(description);
    }
    if let Some(completed) = payload.completed {
        task.completed = completed;
    }

    Ok(Json(task.clone()))
}

pub async fn delete_task(
    State(state): State<SharedState>,
    Path(id): Path<u64>,
) -> Result<StatusCode, StatusCode> {
    let mut tasks = state.write().await;
    tasks
        .remove(&id)
        .map(|_| StatusCode::NO_CONTENT)
        .ok_or(StatusCode::NOT_FOUND)
}

use axum::{
    routing::get,
    Router,
};
use std::collections::HashMap;
use std::sync::Arc;
use tokio::sync::RwLock;

mod handlers;
mod models;

use handlers::SharedState;

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt::init();

    let state: SharedState = Arc::new(RwLock::new(HashMap::new()));

    let app = Router::new()
        .route("/tasks", get(handlers::list_tasks).post(handlers::create_task))
        .route(
            "/tasks/{id}",
            get(handlers::get_task)
                .put(handlers::update_task)
                .delete(handlers::delete_task),
        )
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await
        .unwrap();

    tracing::info!("Listening on http://localhost:3000");
    axum::serve(listener, app).await.unwrap();
}

# タスク作成
curl -X POST http://localhost:3000/tasks \
  -H "Content-Type: application/json" \
  -d '{"title":"Axumを学ぶ","description":"チュートリアルを完了する"}'

# タスク一覧取得
curl http://localhost:3000/tasks

# タスク更新
curl -X PUT http://localhost:3000/tasks/1 \
  -H "Content-Type: application/json" \
  -d '{"completed":true}'

# タスク削除
curl -X DELETE http://localhost:3000/tasks/1

[dependencies]
axum = "0.8"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
sqlx = { version = "0.8", features = ["runtime-tokio", "postgres", "chrono", "uuid"] }
uuid = { version = "1", features = ["v4", "serde"] }
chrono = { version = "0.4", features = ["serde"] }

CREATE TABLE tasks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    title VARCHAR(255) NOT NULL,
    description TEXT,
    completed BOOLEAN NOT NULL DEFAULT FALSE,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

use sqlx::postgres::PgPoolOptions;

#[derive(Clone)]
struct AppState {
    pool: sqlx::PgPool,
}

#[tokio::main]
async fn main() {
    let database_url = std::env::var("DATABASE_URL")
        .expect("DATABASE_URL must be set");

    let pool = PgPoolOptions::new()
        .max_connections(20)
        .connect(&database_url)
        .await
        .expect("Failed to create pool");

    // マイグレーション実行
    sqlx::migrate!("./migrations")
        .run(&pool)
        .await
        .expect("Failed to run migrations");

    let state = AppState { pool };

    let app = Router::new()
        .route("/tasks", get(list_tasks).post(create_task))
        .route("/tasks/{id}", get(get_task).put(update_task).delete(delete_task))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await
        .unwrap();

    axum::serve(listener, app).await.unwrap();
}

use axum::extract::{Path, State};
use axum::Json;
use axum::http::StatusCode;
use sqlx::FromRow;
use uuid::Uuid;
use chrono::{DateTime, Utc};

#[derive(Debug, Serialize, FromRow)]
struct Task {
    id: Uuid,
    title: String,
    description: Option<String>,
    completed: bool,
    created_at: DateTime<Utc>,
    updated_at: DateTime<Utc>,
}

async fn list_tasks(
    State(state): State<AppState>,
) -> Result<Json<Vec<Task>>, StatusCode> {
    let tasks = sqlx::query_as::<_, Task>(
        "SELECT id, title, description, completed, created_at, updated_at
         FROM tasks ORDER BY created_at DESC"
    )
    .fetch_all(&state.pool)
    .await
    .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;

    Ok(Json(tasks))
}

async fn create_task(
    State(state): State<AppState>,
    Json(payload): Json<CreateTask>,
) -> Result<(StatusCode, Json<Task>), StatusCode> {
    let task = sqlx::query_as::<_, Task>(
        "INSERT INTO tasks (title, description)
         VALUES ($1, $2)
         RETURNING id, title, description, completed, created_at, updated_at"
    )
    .bind(&payload.title)
    .bind(&payload.description)
    .fetch_one(&state.pool)
    .await
    .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;

    Ok((StatusCode::CREATED, Json(task)))
}

async fn get_task(
    State(state): State<AppState>,
    Path(id): Path<Uuid>,
) -> Result<Json<Task>, StatusCode> {
    let task = sqlx::query_as::<_, Task>(
        "SELECT id, title, description, completed, created_at, updated_at
         FROM tasks WHERE id = $1"
    )
    .bind(id)
    .fetch_optional(&state.pool)
    .await
    .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?
    .ok_or(StatusCode::NOT_FOUND)?;

    Ok(Json(task))
}

# SQLx CLIのインストール
cargo install sqlx-cli

# マイグレーションファイル作成
sqlx migrate add create_tasks_table

# マイグレーション実行
sqlx migrate run

# ビルドステージ
FROM rust:1.83-slim AS builder
WORKDIR /app
COPY Cargo.toml Cargo.lock ./
COPY src ./src
COPY migrations ./migrations
RUN cargo build --release

# 実行ステージ
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY --from=builder /app/target/release/axum-demo /app/axum-demo
COPY migrations ./migrations
EXPOSE 3000
CMD ["./axum-demo"]

[dependencies]
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }

use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};

#[tokio::main]
async fn main() {
    tracing_subscriber::registry()
        .with(
            tracing_subscriber::EnvFilter::try_from_default_env()
                .unwrap_or_else(|_| "axum_demo=debug,tower_http=debug".into()),
        )
        .with(tracing_subscriber::fmt::layer().json())
        .init();

    tracing::info!("Starting server");

    // ... アプリケーション起動コード
}

RUST_LOG=axum_demo=info,tower_http=debug cargo run

use tokio::signal;

#[tokio::main]
async fn main() {
    // ... Router構築コード

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await
        .unwrap();

    tracing::info!("Listening on http://localhost:3000");

    axum::serve(listener, app)
        .with_graceful_shutdown(shutdown_signal())
        .await
        .unwrap();

    tracing::info!("Server shut down gracefully");
}

async fn shutdown_signal() {
    let ctrl_c = async {
        signal::ctrl_c()
            .await
            .expect("Failed to install Ctrl+C handler");
    };

    #[cfg(unix)]
    let terminate = async {
        signal::unix::signal(signal::unix::SignalKind::terminate())
            .expect("Failed to install SIGTERM handler")
            .recv()
            .await;
    };

    #[cfg(not(unix))]
    let terminate = std::future::pending::<()>();

    tokio::select! {
        _ = ctrl_c => {},
        _ = terminate => {},
    }

    tracing::info!("Shutdown signal received");
}

async fn health_check(State(state): State<AppState>) -> StatusCode {
    match sqlx::query("SELECT 1")
        .execute(&state.pool)
        .await
    {
        Ok(_) => StatusCode::OK,
        Err(_) => StatusCode::SERVICE_UNAVAILABLE,
    }
}

let app = Router::new()
    .route("/health", get(health_check))
    // ... 他のルート
    .with_state(state);

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://postgres:password@db:5432/axum_demo
      RUST_LOG: axum_demo=debug,tower_http=debug
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    environment:
      POSTGRES_DB: axum_demo
      POSTGRES_PASSWORD: password
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

#[cfg(test)]
mod tests {
    use super::*;
    use axum::{
        body::Body,
        http::{Request, StatusCode},
    };
    use http_body_util::BodyExt;
    use tower::ServiceExt;

    fn create_app() -> Router {
        let state: SharedState = Arc::new(RwLock::new(HashMap::new()));
        Router::new()
            .route("/tasks", get(list_tasks).post(create_task))
            .route("/tasks/{id}", get(get_task))
            .with_state(state)
    }

    #[tokio::test]
    async fn test_create_and_list_tasks() {
        let app = create_app();

        // タスク作成
        let response = app
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/tasks")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        r#"{"title":"Test task","description":"A test"}"#,
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(response.status(), StatusCode::CREATED);

        // タスク一覧取得
        let response = app
            .oneshot(
                Request::builder()
                    .uri("/tasks")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(response.status(), StatusCode::OK);

        let body = response.into_body().collect().await.unwrap().to_bytes();
        let tasks: Vec<serde_json::Value> = serde_json::from_slice(&body).unwrap();
        assert_eq!(tasks.len(), 1);
        assert_eq!(tasks[0]["title"], "Test task");
    }

    #[tokio::test]
    async fn test_get_nonexistent_task() {
        let app = create_app();

        let response = app
            .oneshot(
                Request::builder()
                    .uri("/tasks/999")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(response.status(), StatusCode::NOT_FOUND);
    }
}