axum README

The project's README from github.com/tokio-rs/axum. As one markdown file: README.md.

axum

axum is an HTTP routing and request-handling library that focuses on ergonomics and modularity.

Build status Crates.io Documentation

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

High level features

In particular the last point is what sets axum apart from other libraries / 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.9 so the main branch contains breaking changes. See the 0.8.x branch for what's released to crates.io.

Usage example

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;
}

// 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>,
) -> (StatusCode, Json<User>) {
    // 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 benchmarks here and 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.80.

Examples

The examples folder contains various examples of how to use axum. The docs also provide lots of code snippets and 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 a discussion with your question.

Contributing

🎈 Thanks for your help improving the project! We are so happy to have you! We have a contributing guide to help you get involved in the 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.

axum (tokio-rs/axum)

Searching Database…

27.5K ·GitHub
Axum
Что это такое?axum — это библиотека для Rust, которая занимается HTTP-маршрутизацией и обработкой запросов. Она сделана с упором на удобство и модульность: именно из таких крейтов собирают веб-сервисы и API.
Это полноценный веб-фреймворк или тонкая прослойка над чем-то ещё?Это библиотека, а не самостоятельное приложение: вы подключаете её к Rust-проекту, и она как тонкая прослойка поверх HTTP-реализации hyper направляет запросы в ваши функции-обработчики.
Как подключить её к Rust-проекту?Добавьте её как зависимость Cargo (cargo add axum). В папке examples репозитория лежат полноценные примеры проектов, а в документации крейта на docs.rs кода ещё больше.
Что должно быть установлено, чтобы ей пользоваться?Только инструментарий Rust — минимальная поддерживаемая версия 1.80. Всё остальное (hyper, tower) приедет как обычные зависимости.
Есть ли сейчас какие-то тонкости с выбором версии?Да — ветка main находится на полпути к 0.9 и содержит несовместимые изменения; стабильные релизы живут на ветке 0.8.x в crates.io, так что зафиксируйте зависимость на выпущенной версии.
Лицензия подходит для коммерческого использования?Да — это MIT, свободная лицензия. Вклад в проект тоже лицензируется под MIT, если вы явно не укажете иное.
Чем axum отличается от других веб-библиотек для Rust?У неё нет собственной системы middleware — она подключается к tower::Service вместо этого, поэтому таймауты, трейсинг, сжатие и авторизация получаются «из коробки», а middleware можно переиспользовать в приложениях на hyper или tonic.
Как выглядит код обработчиков — нужны ли макросы?Макросы не нужны вовсе: маршрутизация построена на API без макросов. Обработчики декларативно получают данные запроса через экстракторы, ошибки устроены просто и предсказуемо, а для ответов нужен минимум шаблонного кода.
Он быстрый?Да — в README сказано, что производительность сопоставима с hyper, потому что axum добавляет поверх него совсем немного накладных расходов, и там же даны ссылки на опубликованные бенчмарки.
Код написан на безопасном Rust?Да — в крейте стоит #![forbid(unsafe_code)], то есть всё реализовано на 100% безопасном Rust.
What are similar projects?martini, Rocket, starlette, hyper, express, mux, koa, sinatra
Which topics is it in?routing, middleware, async, web-framework, http, developers, backend, web-development, performance, rust, framework, api
Creator
tokio-rs
Size
6 MB
Stars
27.5K
Updated
CommitOct 15Releaseaxum-v0.8.9Apr 14
Age
5y
Commits · 90 Days