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 路由和请求处理库，注重易用性和模块化——就是那种用来构建 Web 服务和 API 的 crate。
它是一个完整的 Web 框架，还是套在别的东西上面的薄封装？它是一个库，不是独立的应用：你把它加到 Rust 项目里，它作为 hyper HTTP 实现之上的薄封装，把请求路由到你的处理函数。
我怎么把它加到 Rust 项目里？把它作为 Cargo 依赖添加（cargo add axum）。仓库的 examples 文件夹里有完整的示例项目，docs.rs 上的 crate 文档里还有更多代码片段。
用之前我需要装好什么？只需要一个 Rust 工具链——最低支持的 Rust 版本是 1.80。其他的东西（hyper、tower）都会作为普通依赖自动装上。
现在选版本有什么需要注意的地方吗？有——main 分支正在向 0.9 过渡，包含破坏性改动；稳定版本发布在 crates.io 的 0.8.x 分支上，所以要把依赖固定到已发布的版本。
这个许可证能用于商业用途吗？可以——它是 MIT，一种宽松的许可证。贡献的代码默认也按 MIT 授权，除非你明确声明其他条款。
axum 和其他 Rust Web 库相比有什么不同？它没有自己的中间件系统——而是直接接入 tower::Service，所以超时、追踪、压缩和鉴权这些功能都是现成的，中间件还能和用 hyper 或 tonic 写的应用共享。
处理函数的代码长什么样——需要用宏吗？完全不用宏：路由用的是无宏 API。处理函数通过提取器以声明式的方式获取请求数据，错误处理遵循一个简单可预测的模型，写响应所需的样板代码也很少。
它快吗？快——README 里说性能和 hyper 相当，因为 axum 在它之上增加的开销非常小，并附上了公开发布的基准测试链接。
代码是用安全 Rust 写的吗？是的——这个 crate 使用了 #![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.2 MB
Stars
27.5K
Updated
CommitOct 19Releaseaxum-v0.8.9Apr 14
Age
5y
Commits · 90 Days