rust-web

Framework Selection

Framework	Characteristics	Recommended For
axum	Modern, Tokio ecosystem, type-safe	New projects (default choice)
actix-web	High performance, Actor model	Performance-critical services
rocket	Developer-friendly, zero-config	Rapid prototyping
warp	Filter-based, functional style	Niche use cases

Recommendation: Start with axum for most projects. It has excellent ergonomics, strong ecosystem integration, and active development.

Solution Patterns

Pattern 1: Axum Basic Structure

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

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/", get(root))
        .route("/users", get(list_users).post(create_user))
        .route("/users/:id", get(get_user).delete(delete_user))
        .with_state(app_state());

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

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

Key insight: Routes are type-safe, handlers are async functions.

Pattern 2: Handler Patterns

use axum::{extract::{Path, Query, Json}, http::StatusCode};

// Path parameters
async fn get_user(Path(id): Path<u32>) -> Result<Json<User>, StatusCode> {
    User::find(id).await
        .map(Json)
        .ok_or(StatusCode::NOT_FOUND)
}

// JSON body
async fn create_user(
    Json(payload): Json<CreateUserRequest>
) -> Result<Json<User>, StatusCode> {
    User::create(payload).await
        .map(Json)
        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)
}

// Query parameters
async fn list_users(
    Query(params): Query<ListUsersParams>
) -> Json<Vec<User>> {
    Json(User::list(params).await)
}

// Multiple extractors
async fn update_user(
    Path(id): Path<u32>,
    State(db): State<DbPool>,
    Json(update): Json<UserUpdate>,
) -> Result<Json<User>, ApiError> {
    User::update(&db, id, update).await
        .map(Json)
}

When to use: Each extractor pattern for different input types.

Pattern 3: State Management

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

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

// Extract state in handlers
async fn handler(State(state): State<AppState>) -> Json<Response> {
    let user = User::fetch(&state.db, 123).await?;
    Json(Response { user })
}

// Setup
let state = AppState {
    db: PgPoolOptions::new()
        .max_connections(5)
        .connect(&db_url)
        .await?,
    config: Arc::new(load_config()),
};

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

When to use: Share database pools, configuration, clients across handlers.

Trade-offs: State must be Clone + Send + Sync + 'static.

Pattern 4: Error Handling

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

#[derive(Error, Debug)]
pub enum ApiError {
    #[error("resource not found")]
    NotFound,

    #[error("invalid input: {0}")]
    Validation(String),

    #[error("database error")]
    Database(#[from] sqlx::Error),

    #[error("authentication required")]
    Unauthorized,
}

impl IntoResponse for ApiError {
    fn into_response(self) -> Response {
        let (status, message) = match self {
            ApiError::NotFound => (StatusCode::NOT_FOUND, self.to_string()),
            ApiError::Validation(msg) => (StatusCode::BAD_REQUEST, msg),
            ApiError::Database(e) => {
                tracing::error!("database error: {}", e);
                (StatusCode::INTERNAL_SERVER_ERROR, "internal error".to_string())
            }
            ApiError::Unauthorized => (StatusCode::UNAUTHORIZED, self.to_string()),
        };

        (status, Json(serde_json::json!({
            "error": message
        }))).into_response()
    }
}

When to use: Custom error types for domain-specific failures.

Workflow

Step 1: Choose Framework

Need high performance?
  → actix-web

Want modern ergonomics + Tokio ecosystem?
  → axum (recommended)

Rapid prototyping?
  → rocket

Step 2: Design Handler Signatures

What data comes from?
  Path → Path<T>
  Query string → Query<T>
  JSON body → Json<T>
  Headers → TypedHeader<T>
  State → State<AppState>

Step 3: Implement Error Handling

Library code?
  → Custom error enum + IntoResponse

Application code?
  → anyhow::Error with context

Step 4: Add Middleware

Logging → tower_http::trace
CORS → tower_http::cors
Rate limiting → tower::limit
Authentication → custom middleware

Middleware Patterns

Logging Middleware

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

async fn log_requests<B>(
    req: Request<B>,
    next: Next<B>,
) -> Response {
    let start = Instant::now();
    let method = req.method().clone();
    let uri = req.uri().clone();

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

    tracing::info!(
        "{} {} {} - {:?}",
        method,
        uri,
        response.status(),
        start.elapsed()
    );

    response
}

// Apply middleware
let app = Router::new()
    .route("/", get(handler))
    .layer(middleware::from_fn(log_requests));

Authentication Middleware

use axum::{
    middleware,
    extract::Request,
    http::{StatusCode, header},
};

async fn auth_middleware(
    mut req: Request,
    next: Next,
) -> Result<Response, StatusCode> {
    let auth_header = req.headers()
        .get(header::AUTHORIZATION)
        .and_then(|h| h.to_str().ok())
        .ok_or(StatusCode::UNAUTHORIZED)?;

    let user = validate_token(auth_header)
        .ok_or(StatusCode::UNAUTHORIZED)?;

    req.extensions_mut().insert(user);
    Ok(next.run(req).await)
}

Database Integration

SQLx Pattern

use sqlx::{PgPool, FromRow};
use chrono::{DateTime, Utc};

// Define model
#[derive(Debug, FromRow)]
struct User {
    id: i32,
    name: String,
    email: String,
    created_at: DateTime<Utc>,
}

// Query
async fn get_user(pool: &PgPool, id: i32) -> Result<User, sqlx::Error> {
    sqlx::query_as!(
        User,
        "SELECT id, name, email, created_at FROM users WHERE id = $1",
        id
    )
    .fetch_one(pool)
    .await
}

// Transaction
async fn create_user_with_profile(
    pool: &PgPool,
    user: NewUser,
) -> Result<User, sqlx::Error> {
    let mut tx = pool.begin().await?;

    let user_id = sqlx::query!(
        "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING id",
        user.name,
        user.email
    )
    .fetch_one(&mut *tx)
    .await?
    .id;

    sqlx::query!(
        "INSERT INTO profiles (user_id, bio) VALUES ($1, $2)",
        user_id,
        user.bio
    )
    .execute(&mut *tx)
    .await?;

    tx.commit().await?;

    get_user(pool, user_id).await
}

Best Practices

Concern	Recommendation
JSON serialization	#[derive(Serialize, Deserialize)] + serde
Configuration	config crate + environment variables
Logging	tracing + tracing-subscriber
Health check	GET /health endpoint returning 200
CORS	tower_http::cors::CorsLayer
Rate limiting	tower::limit::RateLimitLayer
OpenAPI	utoipa for API documentation
Request validation	validator crate with #[validate]
Graceful shutdown	tokio::signal for SIGTERM handling

Common Pitfalls

Pitfall	Problem	Solution
Using Rc for state	Not thread-safe	Use Arc
Holding locks across .await	Potential deadlock	Minimize lock scope
Not handling errors	Handler panics	Implement IntoResponse for errors
Large request bodies	Memory pressure	Set body size limits with DefaultBodyLimit
Missing CORS headers	Browser blocks requests	Add CorsLayer
Synchronous blocking	Blocks executor	Use spawn_blocking for CPU work

Domain-Driven Project Structure

Recommended structure for medium-to-large projects:

src/
├── main.rs                              # Entry point (load config, start HTTP)
├── bootstrap/
│   ├── mod.rs
│   └── app_builder.rs                   # Global assembly (DB/Cache/Telemetry)
├── domains/
│   ├── user/                            # Domain directory with all layers
│   │   ├── mod.rs
│   │   ├── http.rs                      # Routes + handlers + DTO mapping
│   │   ├── app.rs                       # Use cases / commands / queries
│   │   ├── entity.rs                    # Domain entities
│   │   ├── value.rs                     # Value objects
│   │   ├── policy.rs                    # Domain rules/policies
│   │   ├── port.rs                      # Port definitions (traits)
│   │   ├── repo.rs                      # Infrastructure implementation
│   │   ├── cache.rs                     # Caching adapter
│   │   ├── errors.rs                    # Domain errors
│   │   └── tests.rs                     # Domain tests
│   ├── auth/
│   │   ├── mod.rs
│   │   ├── http.rs
│   │   ├── app.rs
│   │   ├── entity.rs
│   │   ├── policy.rs
│   │   ├── port.rs
│   │   ├── repo.rs
│   │   ├── jwt.rs
│   │   ├── errors.rs
│   │   └── tests.rs
│   └── order/
│       ├── mod.rs
│       ├── http.rs
│       ├── app.rs
│       ├── entity.rs
│       ├── port.rs
│       ├── repo.rs
│       ├── events.rs
│       ├── errors.rs
│       └── tests.rs
├── shared/
│   ├── mod.rs
│   ├── error.rs                         # Common error model
│   ├── result.rs                        # Unified Result alias
│   ├── types.rs                         # Common types (ID/Time)
│   └── middleware.rs                    # Cross-domain middleware
└── tests/
    ├── integration/
    └── fixtures/

Structural Principles:

• Domain-centric: Each domain contains interface/application/domain/infrastructure concerns
• File naming: Single-word filenames clarify responsibility (app.rs, port.rs, repo.rs, http.rs)
• Loose coupling: Domains collaborate through application-layer interfaces, avoid direct access
• Shared utilities: Common capabilities in shared/, domain-specific logic stays local

File Responsibilities:

• http.rs - HTTP routes, handlers, request/response DTOs
• app.rs - Application services, use case orchestration
• entity.rs - Domain entities with business logic
• port.rs - Port trait definitions (hexagonal architecture)
• repo.rs - Repository implementations (database, cache)
• errors.rs - Domain-specific error types

Review Checklist

When reviewing web service code:

• Handlers have appropriate extractors (Path, Query, Json)
• Shared state uses Arc for thread safety
• Error types implement IntoResponse
• Database operations use connection pooling
• Middleware is composable and reusable
• API responses follow consistent JSON format
• Authentication/authorization properly enforced
• Request body size limits configured
• CORS configured for browser clients
• Health check endpoint exists
• Logging/tracing properly instrumented
• Graceful shutdown implemented

Verification Commands

# Check compilation
cargo check

# Run tests
cargo test

# Integration tests
cargo test --test integration

# Check for common mistakes
cargo clippy -- -D warnings

# Run development server
cargo run

# Build optimized release
cargo build --release

# Run with environment variables
DATABASE_URL=postgres://localhost cargo run

Performance Optimization

Connection Pooling

use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .max_connections(100)
    .min_connections(10)
    .acquire_timeout(Duration::from_secs(5))
    .idle_timeout(Duration::from_secs(600))
    .connect(&database_url)
    .await?;

Response Compression

use tower_http::compression::CompressionLayer;

let app = Router::new()
    .route("/", get(handler))
    .layer(CompressionLayer::new());

Caching Headers

use axum::http::{header, HeaderMap};

async fn cached_handler() -> (HeaderMap, Json<Data>) {
    let mut headers = HeaderMap::new();
    headers.insert(
        header::CACHE_CONTROL,
        "public, max-age=3600".parse().unwrap(),
    );

    (headers, Json(get_data()))
}

Related Skills

• rust-async - Async patterns for handlers
• rust-concurrency - Thread safety in web services
• rust-database - Database integration patterns
• rust-error - Error handling strategies
• rust-auth - Authentication and authorization
• rust-middleware - Middleware patterns
• rust-observability - Logging and metrics

Localized Reference

• Chinese version: SKILL_ZH.md - 完整中文版本，包含所有内容