Actix-web Framework Guide

Applies to: Actix-web 4+, Rust Web APIs, High-Performance Services Complements: .claude/skills/rust-guide/SKILL.md

Core Principles

•Type-Safe Extraction: Use extractors (web::Json, web::Path, web::Query) for request data
•Thin Handlers: Handlers delegate to services; no business logic in handlers
•Structured Errors: Implement ResponseError for all error types; never return raw strings
•Shared State via web::Data: Application state is injected, never global
•Middleware for Cross-Cutting: Auth, logging, CORS belong in middleware, not handlers

Project Structure

code

myproject/
├── Cargo.toml
├── src/
│   ├── main.rs                # Entry point, server bootstrap
│   ├── config.rs              # Configuration loading
│   ├── routes.rs              # Route registration
│   ├── handlers/
│   │   ├── mod.rs
│   │   ├── users.rs           # User-related handlers
│   │   └── health.rs          # Health check endpoint
│   ├── models/
│   │   ├── mod.rs
│   │   └── user.rs            # Domain models + DTOs
│   ├── services/
│   │   ├── mod.rs
│   │   └── user_service.rs    # Business logic layer
│   ├── repositories/
│   │   ├── mod.rs
│   │   └── user_repository.rs # Database access layer
│   ├── middleware/
│   │   ├── mod.rs
│   │   └── auth.rs            # Authentication middleware
│   └── errors/
│       ├── mod.rs
│       └── app_error.rs       # Centralized error types
├── tests/
│   └── integration_tests.rs
└── migrations/

•main.rs bootstraps server, loads config, creates pool, wires routes
•Business logic lives in services/, not in handlers
•Database access isolated in repositories/
•One error enum per crate with ResponseError impl

Dependencies (Cargo.toml)

toml

[dependencies]
actix-web = "4"
actix-rt = "2"
actix-cors = "0.7"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
sqlx = { version = "0.7", features = ["runtime-tokio", "postgres", "uuid", "chrono"] }
validator = { version = "0.16", features = ["derive"] }
thiserror = "1.0"
anyhow = "1.0"
log = "0.4"
env_logger = "0.10"
tracing = "0.1"
tracing-actix-web = "0.7"
uuid = { version = "1.0", features = ["v4", "serde"] }
chrono = { version = "0.4", features = ["serde"] }

[dev-dependencies]
actix-rt = "2"

Application Entry Point

rust

use actix_cors::Cors;
use actix_web::{middleware, web, App, HttpServer};
use sqlx::postgres::PgPoolOptions;

pub struct AppState {
    pub pool: sqlx::PgPool,
    pub config: config::Config,
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    dotenvy::dotenv().ok();
    env_logger::init_from_env(env_logger::Env::new().default_filter_or("info"));

    let config = config::Config::load().expect("Failed to load configuration");
    let pool = PgPoolOptions::new()
        .max_connections(10)
        .connect(&config.database_url)
        .await
        .expect("Failed to create database pool");

    sqlx::migrate!("./migrations")
        .run(&pool)
        .await
        .expect("Failed to run migrations");

    let app_state = web::Data::new(AppState {
        pool,
        config: config.clone(),
    });

    HttpServer::new(move || {
        let cors = Cors::default()
            .allow_any_origin()
            .allow_any_method()
            .allow_any_header()
            .max_age(3600);

        App::new()
            .app_data(app_state.clone())
            .wrap(cors)
            .wrap(middleware::Logger::default())
            .wrap(middleware::Compress::default())
            .configure(routes::configure)
    })
    .bind(format!("{}:{}", config.host, config.port))?
    .run()
    .await
}

Routing

rust

use actix_web::web;

pub fn configure(cfg: &mut web::ServiceConfig) {
    cfg.service(
        web::scope("/api/v1")
            .route("/health", web::get().to(handlers::health::health_check))
            .service(
                web::scope("/auth")
                    .route("/register", web::post().to(handlers::users::register))
                    .route("/login", web::post().to(handlers::users::login)),
            )
            .service(
                web::scope("/users")
                    .wrap(crate::middleware::auth::AuthMiddleware)
                    .route("", web::get().to(handlers::users::list_users))
                    .route("/{id}", web::get().to(handlers::users::get_user))
                    .route("/{id}", web::put().to(handlers::users::update_user))
                    .route("/{id}", web::delete().to(handlers::users::delete_user)),
            ),
    );
}

Routing Guardrails

•Group routes by resource under web::scope
•Apply middleware at the scope level, not per-route
•Use web::ServiceConfig for modular route registration
•Version API routes (/api/v1/...)
•Keep route definitions separate from handler implementations

Extractors

Extractors are how Actix-web injects request data into handler functions.

Extractor	Purpose	Example
`web::Json<T>`	Deserialize JSON body	`body: web::Json<CreateDto>`
`web::Path<T>`	URL path parameters	`path: web::Path<Uuid>`
`web::Query<T>`	Query string parameters	`query: web::Query<PaginationQuery>`
`web::Data<T>`	Shared application state	`state: web::Data<AppState>`
`web::Form<T>`	URL-encoded form data	`form: web::Form<LoginForm>`
`HttpRequest`	Raw request (headers, extensions)	`req: HttpRequest`

Extractor Rules

•Always validate extracted data (use validator crate with Validate derive)
•Prefer typed extractors over manually parsing HttpRequest
•Use web::Data for immutable shared state (wrapped in Arc internally)
•Limit JSON body size with .app_data(web::JsonConfig::default().limit(4096))

Handlers

Handlers are async functions that take extractors and return impl Responder.

rust

use actix_web::{web, HttpResponse};

pub async fn register(
    state: web::Data<AppState>,
    body: web::Json<CreateUserDto>,
) -> AppResult<HttpResponse> {
    let service = UserService::new(state.pool.clone(), state.config.clone());
    let response = service.register(body.into_inner()).await?;
    Ok(HttpResponse::Created().json(response))
}

pub async fn get_user(
    state: web::Data<AppState>,
    path: web::Path<Uuid>,
) -> AppResult<HttpResponse> {
    let service = UserService::new(state.pool.clone(), state.config.clone());
    let user = service.get_user(path.into_inner()).await?;
    Ok(HttpResponse::Ok().json(user))
}

Handler Rules

•Return Result<HttpResponse, AppError> (aliased as AppResult<HttpResponse>)
•Use .into_inner() to unwrap extractors before passing to services
•No business logic in handlers -- delegate to service layer
•One handler per HTTP method per resource action

Application State

rust

pub struct AppState {
    pub pool: sqlx::PgPool,
    pub config: Config,
}

// Register in HttpServer closure:
let app_state = web::Data::new(AppState { pool, config });
App::new().app_data(app_state.clone())

// Access in handlers:
pub async fn handler(state: web::Data<AppState>) -> impl Responder {
    let pool = &state.pool;
    // use pool...
}

State Rules

•Wrap in web::Data (internally uses Arc)
•Clone web::Data in HttpServer::new closure (cheap Arc clone)
•Keep state immutable; use tokio::sync::RwLock if mutation is required
•Do not store request-scoped data in AppState

Error Handling

rust

use actix_web::{http::StatusCode, HttpResponse, ResponseError};

#[derive(Debug)]
pub enum AppError {
    NotFound(String),
    BadRequest(String),
    Unauthorized(String),
    Forbidden(String),
    Conflict(String),
    Validation(String),
    Internal(String),
    Database(sqlx::Error),
}

impl ResponseError for AppError {
    fn error_response(&self) -> HttpResponse {
        let (status, message) = match self {
            AppError::NotFound(msg) => (StatusCode::NOT_FOUND, msg.clone()),
            AppError::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg.clone()),
            AppError::Unauthorized(msg) => (StatusCode::UNAUTHORIZED, msg.clone()),
            AppError::Forbidden(msg) => (StatusCode::FORBIDDEN, msg.clone()),
            AppError::Conflict(msg) => (StatusCode::CONFLICT, msg.clone()),
            AppError::Validation(msg) => (StatusCode::UNPROCESSABLE_ENTITY, msg.clone()),
            AppError::Internal(_) => (StatusCode::INTERNAL_SERVER_ERROR, "Internal error".into()),
            AppError::Database(_) => (StatusCode::INTERNAL_SERVER_ERROR, "Database error".into()),
        };
        HttpResponse::build(status).json(serde_json::json!({
            "success": false,
            "error": { "code": status.as_u16(), "message": message }
        }))
    }
}

pub type AppResult<T> = Result<T, AppError>;

Error Handling Rules

•Implement ResponseError trait for all custom error types
•Use From<T> impls for automatic conversion: sqlx::Error, validator::ValidationErrors
•Log internal/database errors server-side; return generic messages to clients
•Define AppResult<T> type alias to reduce boilerplate

Middleware

Actix-web middleware uses the Transform + Service traits.

rust

pub struct AuthMiddleware;

impl<S, B> Transform<S, ServiceRequest> for AuthMiddleware
where
    S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error> + 'static,
    B: 'static,
{
    type Response = ServiceResponse<B>;
    type Error = Error;
    type Transform = AuthMiddlewareService<S>;
    type InitError = ();
    type Future = Ready<Result<Self::Transform, Self::InitError>>;

    fn new_transform(&self, service: S) -> Self::Future {
        ok(AuthMiddlewareService { service: Rc::new(service) })
    }
}

Middleware Rules

•Use Transform trait for middleware factories, Service for middleware logic
•Store authenticated user data in request extensions (req.extensions_mut().insert(...))
•Apply middleware at scope level: .service(web::scope("/protected").wrap(AuthMiddleware))
•Use built-in middleware: Logger, Compress, NormalizePath, DefaultHeaders
•Order matters: middleware wraps from bottom to top (last .wrap() runs first)

Configuration

rust

use serde::Deserialize;

#[derive(Clone, Deserialize)]
pub struct Config {
    pub host: String,
    pub port: u16,
    pub database_url: String,
    pub jwt_secret: String,
    pub jwt_expiration_hours: i64,
}

impl Config {
    pub fn load() -> anyhow::Result<Self> {
        let config = config::Config::builder()
            .add_source(config::Environment::default().separator("__").try_parsing(true))
            .set_default("host", "127.0.0.1")?
            .set_default("port", 8080)?
            .build()?;
        Ok(config.try_deserialize()?)
    }
}

Commands

bash

# Development
cargo run                              # Start server
cargo watch -x run                     # Watch mode (requires cargo-watch)
RUST_LOG=actix_web=debug cargo run     # Debug logging

# Build
cargo build --release                  # Production build
cargo check                            # Fast type-check

# Quality
cargo fmt                              # Format code
cargo clippy -- -D warnings            # Lint with deny
cargo test                             # Run all tests
cargo tarpaulin                        # Coverage

# Database
sqlx migrate run                       # Run migrations
sqlx migrate add <name>                # Create migration

Best Practices

Application Structure

•Use web::Data for shared application state
•Organize routes with web::scope and ServiceConfig
•Service layer for business logic, repository layer for data access
•Keep handlers thin: extract, delegate, respond

Performance

•Use connection pooling (sqlx::PgPool or deadpool)
•Enable middleware::Compress for response compression
•Use async/await throughout; avoid blocking operations
•Configure worker count for production: .workers(num_cpus::get())
•Set JSON payload limits to prevent abuse

Security

•Validate all inputs with validator crate
•Use HTTPS in production (terminate at load balancer or use actix-tls)
•Implement rate limiting (actix-governor or custom middleware)
•Sanitize error messages: never expose internal details to clients
•Use actix-cors with explicit origins in production (not allow_any_origin)

Testing

•Use actix_web::test module for integration tests
•Create test app with test::init_service and shared test state
•Assert on status codes, response bodies, and headers
•Test middleware independently from handlers

Advanced Topics

For detailed patterns and examples, see:

•references/patterns.md -- Handler examples, database integration, authentication, actors, testing patterns

Actix-web Framework Guide

Core Principles

Project Structure

Dependencies (Cargo.toml)

Application Entry Point

Routing

Routing Guardrails

Extractors

Extractor Rules

Handlers

Handler Rules

Application State

State Rules

Error Handling

Error Handling Rules

Middleware

Middleware Rules

Configuration

Commands

Best Practices

Application Structure

Performance

Security

Testing

Advanced Topics

External References