actix-web

Actix-web コアナレッジ

完全なリファレンス：カスタムタイミングミドルウェア、認証ミドルウェア、カスタムエラー型、WebSocket アクター、グレースフルシャットダウンのパターンについては、advanced.md を参照してください。

詳細なナレッジ：包括的なドキュメントについては、テクノロジーに actix-web を指定して mcp__documentation__fetch_docs を使用してください。

基本的なセットアップ

# Cargo.toml
[dependencies]
actix-web = "4"
actix-rt = "2"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["full"] }

use actix_web::{web, App, HttpServer, HttpResponse, Responder};

async fn hello() -> impl Responder {
    HttpResponse::Ok().body("Hello, World!")
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(|| {
        App::new()
            .route("/", web::get().to(hello))
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}

ルートマクロ

use actix_web::{get, post, web, HttpResponse, Responder};

#[get("/users/{id}")]
async fn get_user(path: web::Path<u32>) -> impl Responder {
    let id = path.into_inner();
    HttpResponse::Ok().json(serde_json::json!({ "id": id }))
}

#[post("/users")]
async fn create_user(body: web::Json<CreateUser>) -> impl Responder {
    HttpResponse::Created().json(body.into_inner())
}

// Register with App
App::new()
    .service(get_user)
    .service(create_user)

エクストラクター

エクストラクター	用途
web::Path<T>	URL パスパラメーター
web::Query<T>	クエリー文字列
web::Json<T>	JSON ボディ
web::Form<T>	フォームデータ
web::Data<T>	アプリケーションの状態

アプリケーションの状態

struct AppState {
    db_pool: Pool<Postgres>,
}

#[get("/users")]
async fn list_users(data: web::Data<AppState>) -> impl Responder {
    let users = sqlx::query_as!(User, "SELECT * FROM users")
        .fetch_all(&data.db_pool)
        .await?;
    HttpResponse::Ok().json(users)
}

HttpServer::new(move || {
    App::new()
        .app_data(web::Data::new(state.clone()))
        .service(list_users)
})

組み込みミドルウェア

use actix_web::middleware::{Logger, Compress, NormalizePath};

App::new()
    .wrap(Logger::default())
    .wrap(Compress::default())
    .wrap(NormalizePath::trim())

ヘルスチェック

#[get("/health")]
async fn health() -> impl Responder {
    HttpResponse::Ok().json(serde_json::json!({ "status": "healthy" }))
}

#[get("/ready")]
async fn ready(data: web::Data<AppState>) -> impl Responder {
    match data.db_pool.acquire().await {
        Ok(_) => HttpResponse::Ok().json(serde_json::json!({
            "status": "ready",
            "database": "connected"
        })),
        Err(_) => HttpResponse::ServiceUnavailable().json(serde_json::json!({
            "status": "not ready"
        })),
    }
}

このスキルを使用しない場合

• Axum プロジェクト - Axum は Tower エコシステムとの連携がより直感的です
• Rocket プロジェクト - Rocket はコンパイル時の保証がより優れています
• Warp プロジェクト - Warp は合成にフィルターを使用します
• シンプルな CLI ツール - Web サーバーは不要です
• 組み込みシステム - リソースが限られたデバイスには重すぎます

アンチパターン

アンチパターン	問題点	解決策
リクエストごとに .clone() を実行する	パフォーマンスのオーバーヘッド	共有状態には web::Data<Arc<T>> を使用します
非同期ハンドラー内でブロッキング I/O を行う	エグゼキュータースレッドがブロックされます	ブロッキング操作には web::block() を使用します
エクストラクターを使用しない	手動の解析はエラーが発生しやすくなります	Json、Path、Query エクストラクターを使用します
#[actix_web::main] がない	ランタイムを手動でセットアップする必要があります	シンプルなセットアップにはマクロを使用します
グローバルな可変状態	データ競合が発生します	web::Data と Mutex または RwLock を使用します
カスタムエラー型がない	汎用的なエラーメッセージになります	ResponseError トレイトを実装します

トラブルシューティングの概要

問題	診断	修正
「Cannot move out of borrowed content」	所有権の問題	データをクローンするか、web::Data<Arc<T>> を使用します
ハンドラーが見つからない（404）	ルートが登録されていません	.service() または .route() の呼び出しを確認します
JSON の解析に失敗する	Content-Type が正しくありません	クライアントが Content-Type: application/json を送信していることを確認します
パフォーマンスが遅い	ブロッキング I/O	ブロッキングコードを web::block() でラップします
WebSocket 接続が閉じる	ping/pong がありません	ハートビートの仕組みを実装します
状態にアクセスできない	アプリに追加されていません	アプリの構築時に .app_data() を使用します

チェックリスト

• CORS が適切に設定されている
• 認証ミドルウェア
• カスタムエラー処理
• リクエストログ（Logger ミドルウェア）
• ヘルス／レディネスエンドポイント
• グレースフルシャットダウン
• データベースのコネクションプーリング
• 入力検証
• レート制限（actix-ratelimit）

リファレンスドキュメント

• エクストラクター
• ミドルウェア