Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tokio-rs/axum

Ergonomic and modular web framework built with Tokio, Tower, and Hyper
https://github.com/tokio-rs/axum

Last synced: 11 days ago
JSON representation

Ergonomic and modular web framework built with Tokio, Tower, and Hyper

Awesome Lists containing this project

README 

        
# axum



`axum` is a web application framework that focuses on ergonomics and modularity.



[![Build status](https://github.com/tokio-rs/axum/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/tokio-rs/axum/actions/workflows/CI.yml)

[![Crates.io](https://img.shields.io/crates/v/axum)](https://crates.io/crates/axum)

[![Documentation](https://docs.rs/axum/badge.svg)][docs]



More information about this crate can be found in the [crate documentation][docs].



## High level features



- Route requests to handlers with a macro free API.

- Declaratively parse requests using extractors.

- Simple and predictable error handling model.

- Generate responses with minimal boilerplate.

- Take full advantage of the [`tower`] and [`tower-http`] ecosystem of

  middleware, services, and utilities.



In particular the last point is what sets `axum` apart from other frameworks.

`axum` doesn't have its own middleware system but instead uses

[`tower::Service`]. This means `axum` gets timeouts, tracing, compression,

authorization, and more, for free. It also enables you to share middleware with

applications written using [`hyper`] or [`tonic`].



## ⚠ Breaking changes ⚠



We are currently working towards axum 0.8 so the `main` branch contains breaking

changes. See the [`0.7.x`] branch for what's released to crates.io.



[`0.7.x`]: https://github.com/tokio-rs/axum/tree/v0.7.x



## Usage example



```rust

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 our application with a route

    let app = Router::new()

        // `GET /` goes to `root`

        .route("/", get(root))

        // `POST /users` goes to `create_user`

        .route("/users", post(create_user));



    // run our app with hyper, listening globally on port 3000

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

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

}



// basic handler that responds with a static string

async fn root() -> &'static str {

    "Hello, World!"

}



async fn create_user(

    // this argument tells axum to parse the request body

    // as JSON into a `CreateUser` type

    Json(payload): Json,

) -> (StatusCode, Json) {

    // insert your application logic here

    let user = User {

        id: 1337,

        username: payload.username,

    };



    // this will be converted into a JSON response

    // with a status code of `201 Created`

    (StatusCode::CREATED, Json(user))

}



// the input to our `create_user` handler

#[derive(Deserialize)]

struct CreateUser {

    username: String,

}



// the output to our `create_user` handler

#[derive(Serialize)]

struct User {

    id: u64,

    username: String,

}

```



You can find this [example][readme-example] as well as other example projects in

the [example directory][examples].



See the [crate documentation][docs] for way more examples.



## Performance



`axum` is a relatively thin layer on top of [`hyper`] and adds very little

overhead. So `axum`'s performance is comparable to [`hyper`]. You can find

benchmarks [here](https://github.com/programatik29/rust-web-benchmarks) and

[here](https://web-frameworks-benchmark.netlify.app/result?l=rust).



## Safety



This crate uses `#![forbid(unsafe_code)]` to ensure everything is implemented in

100% safe Rust.



## Minimum supported Rust version



axum's MSRV is 1.75.



## Examples



The [examples] folder contains various examples of how to use `axum`. The

[docs] also provide lots of code snippets and examples. For full-fledged examples, check out community-maintained [showcases] or [tutorials].



## Getting Help



In the `axum`'s repo we also have a [number of examples][examples] showing how

to put everything together. Community-maintained [showcases] and [tutorials] also demonstrate how to use `axum` for real-world applications. You're also welcome to ask in the [Discord channel][chat] or open a [discussion] with your question.



## Community projects



See [here][ecosystem] for a list of community maintained crates and projects

built with `axum`.



## Contributing



🎈 Thanks for your help improving the project! We are so happy to have

you! We have a [contributing guide][contributing] to help you get involved in the

`axum` project.



## License



This project is licensed under the [MIT license][license].



### Contribution



Unless you explicitly state otherwise, any contribution intentionally submitted

for inclusion in `axum` by you, shall be licensed as MIT, without any

additional terms or conditions.



[readme-example]: https://github.com/tokio-rs/axum/tree/main/examples/readme

[examples]: https://github.com/tokio-rs/axum/tree/main/examples

[docs]: https://docs.rs/axum

[`tower`]: https://crates.io/crates/tower

[`hyper`]: https://crates.io/crates/hyper

[`tower-http`]: https://crates.io/crates/tower-http

[`tonic`]: https://crates.io/crates/tonic

[contributing]: https://github.com/tokio-rs/axum/blob/main/CONTRIBUTING.md

[chat]: https://discord.gg/tokio

[discussion]: https://github.com/tokio-rs/axum/discussions/new?category=q-a

[`tower::Service`]: https://docs.rs/tower/latest/tower/trait.Service.html

[ecosystem]: https://github.com/tokio-rs/axum/blob/main/ECOSYSTEM.md

[showcases]: https://github.com/tokio-rs/axum/blob/main/ECOSYSTEM.md#project-showcase

[tutorials]: https://github.com/tokio-rs/axum/blob/main/ECOSYSTEM.md#tutorials

[license]: https://github.com/tokio-rs/axum/blob/main/axum/LICENSE