axum
axum is a web application framework that focuses on ergonomics and modularity.
More information about this crate can be found in the crate documentation.
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
towerandtower-httpecosystem 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.
Usage example
use axum::{
routing::{get, post},
http::StatusCode,
response::IntoResponse,
Json, Router,
};
use serde::{Deserialize, Serialize};
use std::net::SocketAddr;
#[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
// `axum::Server` is a re-export of `hyper::Server`
let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
tracing::debug!("listening on {}", addr);
axum::Server::bind(&addr)
.serve(app.into_make_service())
.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<CreateUser>,
) -> impl IntoResponse {
// 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 as well as other example projects in the example directory.
See the crate documentation 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 a benchmark here.
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.54.
Examples
The examples folder contains various examples of how to use axum. The docs also have lots of examples
Getting Help
In the axum's repo we also have a number of examples showing how to put everything together. You're also welcome to ask in the Discord channel or open an issue with your question.
Community projects
See here for a list of community maintained crates and projects built with axum.
Contributing
axum project.
License
This project is licensed under the MIT 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.
47 Dec 9, 2022
48 Oct 11, 2023
3 Mar 18, 2022
1.4k Jun 26, 2023
12 Sep 25, 2023
1.2k Jan 8, 2023
16.2k Jan 2, 2023
1.7k Dec 26, 2022
31 Dec 29, 2022
7 Dec 18, 2022
45 Sep 6, 2023
32 Apr 11, 2022
913 Dec 27, 2022
2.2k Jan 6, 2023
3.6k Jan 6, 2023
1 Dec 11, 2021
475 Jan 2, 2023
115 Dec 29, 2022
27 Nov 3, 2022