用途:帮助理解 Axum 的整体架构,用于启动项目、在 Rust Web 框架间做选型、解释 Axum 各层如何协作,或排查 handler 无法通过编译的问题。
核心模型:Axum 自身几乎不实现底层能力,而是组合三层——tokio 负责运行时、TcpListener、定时器与任务调度;hyper 1.x 负责 HTTP/1 与 HTTP/2 及字节解析;tower 提供服务抽象与中间件生态。Axum 只新增 Router、具体提取器、Handler trait、IntoResponse 和 axum::serve。因此超时、追踪、压缩、CORS、限流等可直接复用 tower / tower-http,不应重复实现。Axum 0.7 及以后要求 hyper ^1.1.0 与 http ^1.0.0。
设计特点:路由是普通数据,handler 是普通 async fn,没有路由宏;最小应用唯一用到的宏 #[tokio::main] 属于 tokio。请求生命周期为:TcpListener 接受连接,hyper 解析为 http::Request,axum::serve 以 tower::Service 驱动 Router,Router 匹配路径并选择 MethodRouter,再选方法对应 handler,各参数依次运行提取器(FromRequestParts 处理非 body 部分,FromRequest 处理 body 且必须放最后),handler 返回后经 IntoResponse 转为 http::Response,最后由 hyper 写回。
用法要点:应用二进制依赖 axum;仅实现 FromRequest、FromRequestParts 或 IntoResponse 的库应依赖 axum-core,以隔离路由与提取器接口的破坏性变更。Router<()> 本身即 tower::Service,可直接传给 axum::serve,也可嵌套、合并或用 oneshot 测试;服务前须用 with_state 提供全部状态。axum::serve 的 future 永不完成,main 会一直阻塞;0.8 已移除 axum::Server。
限制与排错:Axum 只提供构建块,不含内置认证、ORM 或模板引擎;handler future 必须 Send,不能在 .await 期间持有 Rc、RefCell 或 std::sync::MutexGuard。遇到 Handler trait 未满足的晦涩报错时,可加 #[axum::debug_handler](需 macros 特性)获得精确诊断。若需要属性宏路由可选 Rocket 或 Actix Web,非 tokio 运行时则不适用 Axum。