mirror of
https://github.com/tokio-rs/axum.git
synced 2026-08-25 00:00:23 +02:00
David Pedersen
857ecd7314
For 0.3 I'm thinking about some changes I wanna make to the docs. I
don't like how information is currently spread over so many places.
Still thinking about how I wanna re-organize it.
However I do think it makes sense to break the root module docs into
separate files that get included with `#![doc = include_str!("file")]`.
Makes working on a single section easier and more focused. It looks the
same for the user reading the docs.
This means axum's MSRV is now 1.54 but since thats two releases ago I'm
fine with that.
149 lines
4.4 KiB
Markdown
149 lines
4.4 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
|
|
|
|
```rust
|
|
use axum::{
|
|
handler::{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
|