mirror of
https://github.com/tokio-rs/axum.git
synced 2026-08-16 00:00:18 +02:00
David Pedersen
9465128f3e
This reworks axum's docs in an attempt to make things easier to find. Previously I wasn't a fan of those docs for the same topic were spread across the root module docs and more specific places like types and methods. This changes it such that the root module docs only gives a high level introduction to a topic, perhaps with a small example, and then link to other places where all the details are. This means `Router` is now the single place to learn about routing, and etc for the topics like handlers and error handling.
153 lines
4.6 KiB
Markdown
153 lines
4.6 KiB
Markdown
# axum
|
|
|
|
`axum` is a web application framework that focuses on ergonomics and modularity.
|
|
|
|
[](https://github.com/tokio-rs/axum/actions/workflows/CI.yml)
|
|
[](https://crates.io/crates/axum)
|
|
[](https://docs.rs/axum)
|
|
|
|
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`].
|
|
|
|
## Usage example
|
|
|
|
Note this example uses `main` which contains breaking changes. See the
|
|
[v0.2.x](https://github.com/tokio-rs/axum/tree/v0.2.x) branch for an example
|
|
using 0.2.
|
|
|
|
```rust
|
|
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,
|
|
}
|
|
```
|
|
|
|
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 a
|
|
benchmark [here](https://github.com/programatik29/rust-web-benchmarks).
|
|
|
|
## Safety
|
|
|
|
This crate uses `#![forbid(unsafe_code)]` to ensure everything is implemented in
|
|
100% safe Rust.
|
|
|
|
## Minimum supported Rust version
|
|
|
|
axum 0.2's MSRV is 1.51. axum 0.3's (still work-in-progress) MSRV will be 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][examples] showing how
|
|
to put everything together. You're also welcome to ask in the [Discord
|
|
channel][chat] or open an [issue] with your question.
|
|
|
|
## Contributing
|
|
|
|
:balloon: Thanks for your help improving the project! We are so happy to have
|
|
you! We have a [contributing guide][guide] 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.
|
|
|
|
[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
|
|
[guide]: CONTRIBUTING.md
|
|
[chat]: https://discord.gg/tokio
|
|
[issue]: https://github.com/tokio-rs/axum/issues/new
|
|
[`tower::Service`]: https://docs.rs/tower/latest/tower/trait.Service.html
|