# Axum (Rust) - 生产 Web API ## 概述 Axum 是一个基于 Hyper 和 Tower 构建的 Rust Web 框架。使用它进行类型安全的请求处理，具有可组合的中间件、结构化错误和出色的可测试性。 ## 快速入门 ### 最小服务器 ✅ **正确：类型化处理程序 + JSON 响应** 使用 axum::{routing::get, Json, Router}; 使用 serde::序列化；使用 std::net::SocketAddr； #[导出（序列化）] 结构健康{ 状态：&'静态str， } 异步 fn health() -> Json { Json(健康{状态:“好的”}) } #[东京::主要] 异步 fn main() { 让 app = Router::new().route("/health", get(health)); let addr: SocketAddr = "0.0.0.0:3000".parse().unwrap(); 让listener = tokio::net::TcpListener::bind(addr).await.unwrap(); axum::serve(listener, app).await.unwrap(); } ❌ **错误：阻止异步运行时** 异步 fn 处理程序() { std::thread::sleep(std::time::Duration::from_secs(1)); // 阻塞执行器 } ## 核心概念 ### 路由器+处理程序处理程序是返回实现“IntoResponse”的内容的异步函数。 ✅ **正确：路线嵌套** 使用 axum::{routing::get, Router}; fn 路由器() -> 路由器 { 让 api = Router::new() .route("/users", get(list_users)) .route("/users/:id", get(get_user)); Router::new().nest("/api/v1", api) } async fn list_users() -> &'static str { "[]" } async fn get_user() -> &'static str { "{}" } ### 提取器更喜欢在边界处进行解析和验证的提取器： * `Path`：输入路径参数 * `Query`: 查询字符串 * `Json`：JSON 主体 * `State`: 共享应用程序状态 ✅ **正确：输入路径+ JSON** 使用 axum::{extract::Path, Json}; 使用 serde::{反序列化，序列化}； #[导出（反序列化）] 结构体创建用户{ 电子邮件：字符串， } #[导出（序列化）] 结构用户{ id：字符串，电子邮件：字符串， } async fn create_user(Json(body): Json) -> Json { Json(用户 { id: "1".into(), 电子邮件: body.email }) } async fn get_user(Path(id): Path) -> Json { Json(用户 { id, 电子邮件: "a@example.com".into() }) } ## 生产模式 ### 1) 共享状态（数据库池、配置、客户端）使用“State>”并尽可能保持状态不可变。 ✅ **正确：通过 Arc 的 AppState** 使用 axum::{extract::State,routing::get,Router}; 使用 std::sync::Arc； #[派生（克隆）] 结构体应用程序状态{ build_sha: &'静态 str, } async fn version(State(state): State>) -> String { state.build_sha.to_string() } fn app(状态: Arc) -> 路由器 { Router::new().route("/version", get(version)).with_state(state) } ### 2) 结构化错误处理 (`IntoResponse`) 将错误映射集中到 HTTP 状态代码和 JSON。 ✅ **正确：AppError 转换为响应** 使用 axum::{http::StatusCode, response::IntoResponse, Json}；使用 serde::序列化； #[导出（调试）] 枚举应用程序错误{ 未找到， BadRequest(&'静态str), 内部， } #[导出（序列化）] 结构错误体{ 错误：&'静态str， } 为 AppError 实现 IntoResponse { fn into_response(self) -> axum::response::Response { 让（状态，消息）=匹配自我{ AppError::NotFound => (StatusCode::NOT_FOUND, "not_found"), AppError::BadRequest(_) => (StatusCode::BAD_REQUEST，“bad_request”), AppError::Internal => (StatusCode::INTERNAL_SERVER_ERROR, "内部"), }; (状态, Json(ErrorBody { 错误: msg })).into_response() } } ### 3) 中间件（塔层）将“tower-http”用于生产级层：跟踪、超时、请求 ID、CORS。 ✅ **正确：跟踪 + 超时 + CORS** 使用 axum::{routing::get, Router}; 使用 std::time::Duration；使用塔::ServiceBuilder；使用 tower_http::{ cors::{任何，CorsLayer}，超时::超时层，跟踪::跟踪层， }; fn app() -> 路由器 { 让层= ServiceBuilder::new() .layer(TraceLayer::new_for_http()) .layer(TimeoutLayer::new(持续时间::from_secs(10))) .layer(CorsLayer::new().allow_origin(Any)); 路由器::new() .route("/health", get(|| 异步 { "ok" })) .层（层） } ### 4) 正常关闭在 SIGINT/SIGTERM 时终止并让正在进行的请求耗尽。 ✅ **正确：with_graceful_shutdown** 异步 fn shutdown_signal() { 让 ctrl_c = 异步 { 东京::信号::ctrl_c().await.ok(); }; #[cfg(unix)] 让终止=异步{ tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) .ok() .and_then(|mut s| s.recv().await); }; #[cfg(不是(unix))] 让终止= std::future::pending::<()>(); 东京::选择！ { _ = ctrl_c => {} _ = 终止 => {} } } #[东京::主要] 异步 fn main() { 让应用程序=应用程序（）；让listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); axum::serve（监听器，应用程序） .with_graceful_shutdown(shutdown_signal()) .await .unwrap(); } ## 测试使用“tower::ServiceExt”测试没有套接字的路由器。 ✅ **正确：请求/响应测试** 使用 axum::{body::Body, http::Request, Router}；使用塔::ServiceExt; #[东京::测试] 异步 fn health_returns_ok() { 让 app: Router = super::app(); 让资源=应用程序 .oneshot(Request::builder().uri("/health").body(Body::empty()).unwrap()) .await .unwrap(); assert_eq!(res.status(), 200); } ## 决策树 ### Axum 与其他 Rust 框架 * 对于 Tower 中间件组合和类型化提取器，更喜欢 **Axum**。 * 更喜欢 **Actix Web** 以获得成熟的生态系统和参与者式运行时模型。 * 对于功能过滤器和极简主义，更喜欢 **Warp**。 ## 反模式 * 阻止异步运行时（`std::thread::sleep`，阻止处理程序内的 I/O）。 * 在请求路径中使用`unwrap()`；相反，返回结构化错误。 * 运行无超时；添加请求超时和上游截止日期。 ## 资源 * Axum 文档： * Tower HTTP 层： * 追踪：

阿克苏姆

包含技能