axum

Introduction to Axum

axum is a web application framework designed with a focus on ergonomics and modularity. It offers a unique and efficient approach to building web applications by emphasizing simplicity and reuse of existing solutions rather than reinventing the wheel.

Features of Axum

Macro-free API: axum allows developers to route requests to handlers without relying on macros. This makes the codebase easier to read and maintain.
Request Parsing: With the use of extractors, requests can be declaratively parsed. This simplifies the process of working with incoming data.
Error Handling: The framework adopts a straightforward and predictable model for handling errors, making it easier for developers to manage different error states.
Response Generation: Responses can be created with minimal boilerplate, streamlining the development process.
Middleware and Services: A standout feature of axum is its integration with the tower and tower-http ecosystems. This connection provides access to a wide range of middleware, services, and utilities, such as timeouts, tracing, compression, and authorization, without any additional effort. This compatibility also allows sharing of middleware with applications built using hyper or tonic.

Breaking Changes

The project is currently evolving towards version 0.8, meaning the main branch contains changes that may not be backward compatible. Users interested in stable features should refer to the 0.7.x branch, which is released on crates.io.

Usage Example

Here is a simple implementation that showcases some basic functionalities of axum:

use axum::{
    routing::{get, post},
    http::StatusCode,
    Json, Router,
};
use serde::{Deserialize, Serialize};

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

    // Build the application with routes
    let app = Router::new()
        .route("/", get(root))
        .route("/users", post(create_user));

    // Run the application
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

// Handler functions
async fn root() -> &'static str {
    "Hello, World!"
}

async fn create_user(Json(payload): Json<CreateUser>) -> (StatusCode, Json<User>) {
    let user = User {
        id: 1337,
        username: payload.username,
    };
    (StatusCode::CREATED, Json(user))
}

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

#[derive(Serialize)]
struct User {
    id: u64,
    username: String,
}

This code exemplifies how to set up basic routes and handlers, demonstrating the simplicity and power of axum.

Performance

axum is built on top of hyper, resulting in minimal overhead. Its performance is comparable to hyper, making it an efficient choice for web application development.

Safety and Requirements

The framework ensures that all code is written in safe Rust with #![forbid(unsafe_code)]. The minimum Rust version required to use axum is 1.75.

Resources and Community

There are numerous examples and tutorials available in the examples directory and the official documentation. The axum community maintains several projects and showcases that illustrate real-world applications of the framework. For further assistance, developers can engage with the community through the Discord channel or GitHub discussions.

Contribution and License

axum is an open-source project licensed under the MIT License. The community welcomes contributions, and contributors are invited to consult the contributing guide to get involved.