Axum 是一个基于 Hyper 和 Tower 构建的 Rust Web 框架，适用于需要类型安全请求处理、可组合中间件、结构化错误以及良好可测试性的生产级 API 开发。
【用途】 Axum 用于构建 Rust 生产级 Web API。其核心优势在于：类型安全的请求处理、可组合的中间件、结构化的错误处理，以及出色的可测试性。
【主要能力】
- 路由与处理器：处理器是返回实现了 IntoResponse 的异步函数，支持路由嵌套（nest）。
- 提取器（Extractors）：在请求边界完成解析与校验，包括 Path<T>（类型化路径参数）、Query<T>（查询字符串）、Json<T>（JSON 请求体）、State<T>（共享应用状态）。
- 依赖与 crate 结构：若 crate 同时作为库发布，应将 HTTP 栈隔离为可选 feature，避免给库使用者引入整个 Web 栈。示例中 axum 与 tower-http 设为 optional，通过 http-server feature 控制，二进制目标设置 required-features。
- 共享状态：使用 State<Arc<AppState>>，并尽量保持状态不可变，用于数据库连接池、配置、客户端等。
- 结构化错误处理：通过为自定义错误类型实现 IntoResponse，集中将错误映射为 HTTP 状态码与 JSON 响应体。
- 中间件（Tower 层）：使用 tower-http 提供生产级层，如 TraceLayer（追踪）、TimeoutLayer（超时）、CorsLayer（CORS）、请求 ID 等，可通过 ServiceBuilder 组合。
- 优雅关闭：通过 with_graceful_shutdown 在 SIGINT/SIGTERM 时终止并让在途请求排空。
- 运维层面的优雅关闭：在受监管环境（systemd、launchd、容器编排器）中，由监管进程控制实际终止窗口。systemd 可设置 KillSignal=SIGTERM 与 TimeoutStopSec=120（或更高），默认 90 秒超时可能在网络存储（EBS/EFS）上于 fsync 中途触发导致写入截断，120 秒为在途 HTTP 请求排空加文件系统同步留出安全余量；launchd 应使用 launchctl bootout（发送 SIGTERM 并等待）而非 launchctl kickstart -k（SIGKILL，会截断在途 I/O）；连接该服务的 HTTP 客户端与 MCP 桥接应实现指数退避（起始 200ms，上限 30s），使短暂重启对上游透明。
- 测试：使用 tower::ServiceExt 无需套接字即可测试路由，通过 oneshot 发送请求并断言响应状态。
【使用方式】 快速开始：创建最小服务器，定义返回 Json 的异步处理器，构建 Router 并绑定 TcpListener，调用 axum::serve。 核心概念示例：路由嵌套、类型化路径与 JSON 提取器、AppState 通过 Arc 注入、AppError 实现 IntoResponse、ServiceBuilder 组合 TraceLayer/TimeoutLayer/CorsLayer、with_graceful_shutdown 配合 shutdown_signal、以及使用 oneshot 的请求/响应测试。
【适用场景】 需要类型安全、可组合中间件与结构化错误处理的 Rust 生产 API；需要优雅关闭与可测试性的服务；同时作为库与二进制发布的 crate。
【限制与反模式】 避免阻塞异步运行时（如处理器内使用 std::thread::sleep 或阻塞 I/O）；避免在请求路径中使用 unwrap()，应返回结构化错误；不要在没有超时的情况下运行，应添加请求超时与上游截止时间。
【框架选型】 需要 Tower 中间件组合与类型化提取器时优先选 Axum；需要成熟生态与 actor 风格运行时模型时可选 Actix Web；追求函数式过滤器与极简风格时可选 Warp。
【资源】 Axum 文档：https://docs.rs/axum Tower HTTP 层：https://docs.rs/tower-http Tracing：https://docs.rs/tracing