# Axum Web 框架使用 Axum 构建可投入生产的 Web 应用程序和 API 的综合技能，Axum 是基于 Tokio 和 Tower 构建的符合人体工程学的模块化 Rust Web 框架。掌握路由、提取器、中间件、状态管理、错误处理和部署模式。 ## 何时使用此技能在以下情况下使用此技能： * 使用 Rust 和 async/await 构建 REST API * 创建具有类型安全性的高性能 Web 服务 * 通过 Tokio 生态系统集成开发微服务 * 实现 WebSocket 服务器或服务器发送事件 (SSE) * 使用 Rust 后端构建 GraphQL API * 创建需要 Tower 集成的中间件密集型应用程序 * 开发需要强大错误处理的生产就绪 Web 应用程序 * 构建需要对 HTTP 请求/响应处理进行细粒度控制的系统 * 实现身份验证、授权和安全中间件 * 使用异步 Rust 创建实时 Web 应用程序 * 开发需要验证和转换请求的API * 使用复杂的路由和嵌套路由器构建 Web 服务 * 实现速率限制、超时和反压处理 * 创建需要自定义提取器和响应类型的 Web 应用程序 ## 核心概念 ### Axum 架构哲学 Axum 建立在三个基本支柱之上： 1. **Tower Services** ：Axum 中的一切都建立在 Tower 的“Service”特性之上，提供可组合性和中间件集成 2. **类型安全提取器**：请求数据提取在编译时检查，消除运行时解析错误 3. **Minimal Boilerplate**：符合人体工程学的 API，在保持明确性的同时减少仪式 ### 路由器 “路由器”是阿克苏姆的中心构建块。它根据路径和方法将 HTTP 请求映射到处理程序。 **关键属性：** * 路由按照定义的顺序进行匹配 * 路由器可以嵌套以进行模块化组织 * 中间件可以应用于路由器、路由或方法级别 * 通用状态类型，用于灵活的状态管理 * 实现 Tower 的“Service”特征以实现可组合性 **路由器创建：** 使用 axum::{路由器，路由::get}；让应用程序 = Router::new() .route("/", get(处理程序)) .route("/users/:id", get(get_user)) .route("/posts", get(list_posts).post(create_post)); ### 处理程序处理程序是处理请求并返回响应的异步函数。 Axum 通过其强大的类型系统支持多个处理程序签名。 **处理者要求：** * 必须是异步函数 * 可以使用提取器从请求中提取数据 * 必须返回实现 `IntoResponse` 的类型 * 最多可以有16个参数（全部必须是提取器） **常见处理程序模式：** // 简单处理程序异步 fn handler() -> &'static str { “你好，世界！” } // 带路径参数的处理程序 async fn get_user(Path(user_id): Path) -> String { 格式!("用户 ID: {}", user_id) } // 具有多个提取器的处理程序异步 fn create_user( 状态（状态）：状态， Json(有效负载): Json, ) -> 结果, StatusCode> { // 实现 } ### 提取器提取器是实现“FromRequest”或“FromRequestParts”的类型，允许从请求中安全地提取数据。 **内置提取器：** 1. **Path** \- 提取路径参数 2. **查询** \- 提取查询字符串参数 3. **Json** \- 解析JSON请求体 4. **Form** \- 解析表单编码的请求体 5. **State** \- 访问共享应用程序状态 6. **扩展** \- 访问请求扩展 7. **Headers** \- 访问请求头 8. **方法** \- 获取HTTP方法 9. **Uri** \- 获取请求URI 10. **请求** \- 获取完整请求 11. **字节** \- 原始请求正文作为字节 12. **String** \- 请求正文为 UTF-8 字符串 13. **Multipart** \- 处理多部分/表单数据 **提取器订购：** * 消耗请求体的提取器必须放在最后 * 一个处理程序中的多个主体提取器将导致编译错误 * `State` 和其他非主体提取器可以按任何顺序 ### 回应任何实现“IntoResponse”的类型都可以从处理程序返回。 Axum 提供了许多内置实现。 **内置响应类型：** * `String`, `&'static str` \- 文本响应 * `Json` \- JSON 响应 * `Html` \- HTML 响应 * `StatusCode` \- 仅状态响应 * `(StatusCode, T)` \- 带有正文的状态 * `(Parts, T)` \- 带正文的自定义标头 * `Response` \- 完全控制响应 * `Result` \- 错误处理（其中 E：IntoResponse） ### 状态管理 Axum 使用“State”提取器在处理程序之间共享数据。状态必须实现“Clone”，并且通常包装在“Arc”中以共享所有权。 **状态模式：** 1. **简单状态：** #[派生（克隆）] 结构体应用程序状态{ api_key：字符串， } 让应用程序 = Router::new() .route("/", get(处理程序)) .with_state(应用程序状态{ api_key: "秘密".to_string(), }); 2. **与 Arc 共享状态：** #[派生（克隆）] 结构体应用程序状态{ db_pool: Arc<数据库池>, 缓存：Arc>, } 3. **多种状态类型：** // 为不同的路由器部分定义单独的状态类型让 api_router: Router = Router::new() .route("/api/data", get(api_handler)); 让 app_router: Router = Router::new() .route("/app", get(app_handler)); // 与最终状态结合让应用程序 = Router::new() .nest("/", app_router.with_state(app_state)) .nest("/", api_router.with_state(api_state)); ### 中间件 Axum 中的中间件来自 Tower，提供请求/响应转换、日志记录、身份验证等。 **中间件类别：** 1. **Tower Middleware** \- 来自 `tower` 和 `tower-http` 包 2. **自定义中间件** \- 使用 `middleware::from_fn` 3. **服务中间件** \- 实现 Tower 的 `Service` 特性 4. **图层模式** \- 使用 Tower 的 `Layer` 实现可组合性 **中间件应用顺序：** * 应用 `.layer()` 从下到上执行（包裹前面的层） * 与`ServiceBuilder`一起应用从上到下执行（更直观） * `Router::layer` 上的中间件在路由之后运行 * 围绕 `Router` 的中间件（使用 `Layer::layer`）在路由之前运行 ### 错误处理 Axum 的错误处理基于“IntoResponse”特征，允许将自定义错误类型转换为 HTTP 响应。 **错误处理策略：** 1. **结果类型：** 异步 fn handler() -> Result, StatusCode> { // 返回 200 OK 或错误状态码 } 2. **自定义错误类型：** 枚举应用程序错误{ 数据库（sqlx::错误），未找到，未经授权， } 为 AppError 实现 IntoResponse { fn into_response(self) -> 响应 { // 转换为HTTP响应 } } 3. **处理错误层：** 使用 axum::error_handling::HandleErrorLayer；让应用程序 = Router::new() .层( 服务构建器::new() .layer(HandleErrorLayer::new(handle_error)) .layer(TimeoutLayer::new(持续时间::from_secs(30))) ）； ### 塔式集成 Axum 构建于 Tower 之上，支持强大的中间件组合和服务抽象。 **关键塔概念：** 1. **Service Trait** \- 异步请求处理 2. **Layer Trait** \- 中间件工厂模式 3. **ServiceBuilder** \-符合人体工学的中间件组成 4. **Timeout** \-请求超时处理 5. **RateLimit** \- 请求速率限制 6. **LoadShed** \- 背压管理 7. **Buffer** \- 请求缓冲 ## 路由 ### 基本路由路由将 HTTP 方法和路径映射到处理程序：使用阿克苏姆::{ 路由器，路由::{获取、发布、放置、删除、修补}, }; 让应用程序 = Router::new() .route("/", 获取(根)) .route("/users", get(list_users).post(create_user)) .route("/users/:id", get(get_user).put(update_user).delete(delete_user)) .route("/posts/:id/comments", get(get_comments).post(add_comment)); ### 路径参数从路径中提取动态段：使用 axum::extract::Path；使用 serde::反序列化； // 单个参数 async fn get_user(Path(user_id): Path) -> String { 格式！（“用户{}”，user_id） } // 多个参数 #[导出（反序列化）] 结构 PostPath { 用户 ID：u32，帖子 ID：u32， } async fn get_post(Path(params): Path) -> String { format!("用户{}帖子{}", params.user_id, params.post_id) } // 使用元组作为多个参数异步 fn get_comment( 路径（（post_id，comment_id））：路径<（u32，u32）> ) -> 字符串 { format!("发表{}评论{}", post_id, comment_id) } ### 通配符路线捕获剩余路径段： // 捕获所有剩余路径异步 fn 处理程序(Path(path): Path) -> String { format!("捕获的路径：{}",路径) } 让应用程序 = Router::new() .route("/{*key}", get(处理程序)); // 获取 /foo/bar/baz -> 路径 = "foo/bar/baz" **重要提示：** 嵌套路由器会去除匹配的前缀，但通配符路由保留完整的 URI。 ### 嵌套路由器使用路由器嵌套将路由组织到模块中：使用 axum::{路由器，路由::get}； fn api_routes() -> 路由器 { 路由器::new() .route("/users", get(list_users)) .route("/users/:id", get(get_user)) .route("/posts", 获取(list_posts)) } fn admin_routes() -> 路由器 { 路由器::new() .route("/仪表板", get(仪表板)) .route("/设置", 获取(设置)) } 让应用程序 = Router::new() .nest("/api", api_routes()) .nest("/admin", admin_routes()) .route("/", get(root)); **筑巢行为：** * 在传递到嵌套路由器之前，匹配的前缀会从 URI 中去除 * 嵌套路由器中的处理程序只能看到相对于嵌套点的路径 * 如果子级中没有定义，后备处理程序将从父级继承 * 中间件可以在嵌套之前或之后应用 ### 后备处理程序处理不匹配的路由：使用 axum::{http::StatusCode, handler::Handler}； async fn Fallback() -> (StatusCode, &'static str) { （状态代码::NOT_FOUND，“未找到”） } 让应用程序 = Router::new() .route("/", get(处理程序)) .fallback(后备); **回退继承：** async fn api_fallback() -> (StatusCode, &'static str) { （StatusCode::NOT_FOUND，“未找到 API 端点”） } 让 api = Router::new() .route("/users", get(list_users)) .fallback(api_fallback); 让应用程序 = Router::new() .nest("/api", api) .fallback(后备); // 用于非/api路由 ### 方法路由处理同一路由上的多个 HTTP 方法：使用 axum::routing::{get, post, MethodRouter}; // 一条路径上有多个方法让应用程序 = Router::new() .route("/users", get(list_users).post(create_user)); // 每个方法有不同的处理程序让应用程序 = Router::new() .route("/资源", 获取（获取资源） .post(创建资源) .put(更新资源) .delete(删除资源) .patch(补丁资源) ）； ## 提取器深入探讨 ### 路径提取器提取键入的路径参数：使用 axum::extract::Path；使用 serde::反序列化； // 简单提取 async fn user_by_id(Path(id): Path) -> String { 格式！（“用户{}”，id） } // 复杂提取 #[导出（反序列化）] 结构参数 { 组织：字符串，回购：字符串，问题：u32， } async fn github_issue(Path(params): Path) -> String { 格式！("{}/{} 问题 #{}", params.org, params.repo, params.issue) } 让应用程序 = Router::new() .route("/users/:id", get(user_by_id)) .route("/repos/:org/:repo/issues/:issue", get(github_issue)); ### 查询提取器提取查询字符串参数：使用 axum::extract::Query；使用 serde::反序列化； #[导出（反序列化）] 结构分页{ 页面：选项，每页：选项， } async fn list_users(Query(pagination): Query<分页>) -> String { 让页面 = pagination.page.unwrap_or(1); 让 per_page = pagination.per_page.unwrap_or(20); format!("第 {} 页，包含 {} 个项目", page, per_page) } // 获取 /users?page=2&per_page=50 ### Json 提取器解析 JSON 请求体：使用 axum::extract::Json；使用 serde::{反序列化，序列化}； #[导出（反序列化）] 结构体创建用户{ 用户名：字符串，电子邮件：字符串， } #[导出（序列化）] 结构用户{ 编号：u32，用户名：字符串，电子邮件：字符串， } async fn create_user(Json(payload): Json) -> Json { 让用户=用户{ 编号：123，用户名：payload.用户名，电子邮件：有效负载.电子邮件， }; json（用户） } **JSON 错误处理：** 使用 axum::extract::rejection::JsonRejection；使用 axum::http::StatusCode；异步 fn create_user( 有效负载：Result, JsonRejection> ) -> 结果, (StatusCode, String)> { 匹配负载{ 好的（Json（create_user））=> { // 有效的 JSON 好的（Json（用户 { /* ... */ }）） } 错误（JsonRejection::MissingJsonContentType(_)）=> { 错误（（状态代码::BAD_REQUEST, “缺少`Content-Type：application / json`”.to_string（），）） } 错误（JsonRejection::JsonDataError(err)）=> { 错误（（状态代码::BAD_REQUEST, 格式！（“无效的 JSON：{}”，错误），）） } 错误（JsonRejection::JsonSyntaxError(err)）=> { 错误（（状态代码::BAD_REQUEST, format!("JSON 语法错误：{}", err), ）） } 错误（_）=> { 错误（（状态代码::INTERNAL_SERVER_ERROR, "未知错误".to_string(), ）） } } } ### 状态提取器访问共享应用程序状态：使用 axum::extract::State；使用 std::sync::Arc； #[派生（克隆）] 结构体应用程序状态{ db_pool: Arc<数据库池>, api_key：字符串， } async fn handler(State(state): State) -> String { 格式！（“API密钥：{}”，state.api_key） } 让状态=应用程序状态{ db_pool: Arc::new(DatabasePool::new()), api_key: "秘密".to_string(), }; 让应用程序 = Router::new() .route("/", get(处理程序)) .with_state(状态); ### 扩展提取器访问请求扩展（对于中间件有用）：使用 axum::extract::Extension； #[派生（克隆）] 结构体当前用户{ 编号：u32，用户名：字符串， } 异步 fn 处理程序（扩展（用户）：扩展）-> 字符串 { 格式！("你好，{}"，用户.用户名) } // 由中间件设置: 异步 fn auth_middleware( mut req：请求，下一个：下一个， ) -> 结果<响应，状态代码> { 让用户=当前用户{ 编号: 1, 用户名：“alice”.to_string(), }; req.extensions_mut().insert(用户); 好的（下一个。运行（请求）。等待） } ### 表单提取器解析表单编码的请求主体：使用 axum::extract::Form；使用 serde::反序列化； #[导出（反序列化）] 结构登录表单{ 用户名：字符串，密码：字符串， } async fn login(Form(form): Form) -> String { format!("登录用户：{}", form.username) } ### 标头提取器访问请求头：使用 axum::http::HeaderMap；异步 fn 处理程序（标头：HeaderMap）-> String { 让 user_agent = 标头 .get("用户代理") .and_then(|v| v.to_str().ok()) .unwrap_or("未知"); 格式！（“用户代理：{}”，user_agent） } ### 自定义提取器通过实现“FromRequest”或“FromRequestParts”创建自定义提取器：使用阿克苏姆::{ 提取::{FromRequest, 请求}, 响应::{IntoResponse, 响应}, http::状态代码，异步特征， }; 结构体AuthenticatedUser { 编号：u32，用户名：字符串， } #[异步特征] 为 AuthenticatedUser 实现 FromRequestParts 哪里 S：发送+同步， { 类型拒绝=响应；异步 fn from_request_parts( 零件： &mut 零件，状态：&S， ) -> 结果<自我,自我::拒绝> { // 提取并验证身份验证令牌让 auth_header = 部分 .headers .get("授权") .and_then(|v| v.to_str().ok()) .ok_or_else(|| { （StatusCode::UNAUTHORIZED，“缺少授权标头”） .into_response() })?; // 验证token并返回用户好的（经过身份验证的用户{ 编号: 1, 用户名：“alice”.to_string(), }) } } 异步fn protected_route（用户：AuthenticatedUser）->字符串{ 格式！("你好，{}"，用户.用户名) } ## 中间件 ### 应用中间件 **应用中间件的三种方式：** 1. **路由器级** \- 影响所有路由 2. **路由级别** \- 影响特定路由 3. **方法级** \- 影响路由上的特定方法使用 axum::{路由器，路由::get，中间件}；使用 tower_http::trace::TraceLayer； // 1. 路由器级让应用程序 = Router::new() .route("/", get(处理程序)) .layer(TraceLayer::new_for_http()); // 2. 路由级别让应用程序 = Router::new() .route("/protected", get(处理程序)) .route_layer(中间件::from_fn(auth_middleware)); // 3.方法级让应用程序 = Router::new() .route("/资源", 获取（处理程序） .route_layer(中间件::from_fn(read_only_auth)) .post（创建处理程序） .route_layer(中间件::from_fn(write_auth)) ）； ### 中间件执行顺序 **使用顺序`.layer()`调用（从下到上）：** 让应用程序 = Router::new() .route("/", get(处理程序)) .layer(layer_third) // 执行第三层 .layer(layer_two) // 执行第二个 .layer(layer_one); // 首先执行 **使用`ServiceBuilder`（从上到下）：** 使用塔::ServiceBuilder；让应用程序 = Router::new() .route("/", get(处理程序)) .层( 服务构建器::new() .layer(layer_one) // 首先执行 .layer(layer_two) // 执行第二个 .layer(layer_third) // 执行第三层）； ### 通用塔中间件 **TraceLayer** \- HTTP 请求跟踪：使用 tower_http::trace::TraceLayer；让应用程序 = Router::new() .route("/", get(处理程序)) .layer(TraceLayer::new_for_http()); **压缩层** \- 响应压缩：使用 tower_http::压缩::压缩层；让应用程序 = Router::new() .route("/", get(处理程序)) .layer(压缩层::new()); **CorsLayer** \- CORS 处理：使用 tower_http::cors::{CorsLayer, Any}; 让 cors = CorsLayer::new() .allow_origin(任意) .allow_methods（任何） .allow_headers(任意); 让应用程序 = Router::new() .route("/api/data", get(处理程序)) .层（cors）； **TimeoutLayer** \- 请求超时：使用 tower::timeout::TimeoutLayer；使用 std::time::Duration；让应用程序 = Router::new() .route("/", get(处理程序)) .layer(TimeoutLayer::new(Duration::from_secs(30))); ### 处理错误层将中间件错误转换为 HTTP 响应：使用阿克苏姆::{ error_handling::HandleErrorLayer, http::{状态代码、方法、Uri}, 框错误， }; 使用塔::ServiceBuilder；使用 std::time::Duration；异步 fn 处理超时错误（方法：方法，乌里：乌里，错误：BoxError， ) -> (状态代码, 字符串) { if err.is::() { （状态代码::REQUEST_TIMEOUT, format!("`{} {}`请求超时", method, uri), ） } 否则{ （状态代码::INTERNAL_SERVER_ERROR, format!("`{} {}` 因 {} 失败", method, uri, err), ） } } 让应用程序 = Router::new() .route("/", get(处理程序)) .层( 服务构建器::new() .layer(HandleErrorLayer::new(handle_timeout_error)) .layer(TimeoutLayer::new(持续时间::from_secs(30))) ）； ### 使用 from_fn 自定义中间件使用异步函数创建自定义中间件：使用阿克苏姆::{ 中间件::{self, 下一个}, 提取::请求，响应::响应， http::状态代码， }; 异步 fn auth_middleware( 请求：请求，下一个：下一个， ) -> 结果<响应，状态代码> { 让 auth_header = req.headers() .get("授权") .and_then(|h| h.to_str().ok()); 如果让一些（auth_header）= auth_header { 如果 validate_token(auth_header).await { 好的（下一个。运行（请求）。等待） } 否则{ 错误（状态代码::未经授权） } } 否则{ 错误（状态代码::未经授权） } } 让应用程序 = Router::new() .route("/protected", get(处理程序)) .layer(中间件::from_fn(auth_middleware)); **将数据从中间件传递到处理程序：** 使用 axum::extract::Extension； #[派生（克隆）] 结构体当前用户{ 编号：u32，用户名：字符串， } 异步 fn auth_middleware( mut req：请求，下一个：下一个， ) -> 结果<响应，状态代码> { 让 auth_header = req.headers() .get("授权") .and_then(|h| h.to_str().ok()) .ok_or(状态代码::未授权)?; if let Some(user) = Authorize_user(auth_header).await { req.extensions_mut().insert(用户); 好的（下一个。运行（请求）。等待） } 否则{ 错误（状态代码::未经授权） } } 异步 fn 处理程序（扩展（用户）：扩展）-> 字符串 { 格式！("你好，{}"，用户.用户名) } 让应用程序 = Router::new() .route("/", get(处理程序)) .layer(中间件::from_fn(auth_middleware)); ### 自定义塔中间件实现 Tower 的 `Service` 和 `Layer` 特征以实现完全控制：使用 tower::{服务，层}；使用 axum::{response::Response, extract::Request}；使用 std::task::{Context, Poll}; 使用 futures_core::future::BoxFuture; #[派生（克隆）] 构造MyLayer；为 MyLayer 实现 Layer { 类型服务 = MyMiddleware; fn 层(&self, 内部: S) -> Self::Service { 我的中间件{内部} } } #[派生（克隆）] 结构 MyMiddleware { 内：S， } 为 MyMiddleware 实现服务哪里 S：服务<请求，响应 = 响应> + 发送 + '静态， S::Future：发送+'静态， { 类型响应 = S::响应；类型错误 = S::错误；类型 Future = BoxFuture<'static, Result>; fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll> { self.inner.poll_ready(cx) } fn call(&mut self, request: Request) -> Self::Future { // 处理请求让 future = self.inner.call(request); Box::pin(异步移动 { 让响应：响应= future.await？； // 处理响应好的（回应） }) } } 让应用程序 = Router::new() .route("/", get(处理程序)) .layer(MyLayer); ### 具有状态访问权限的中间件创建访问应用程序状态的中间件：使用 axum::extract::State；使用 std::sync::Arc； #[派生（克隆）] 结构体应用程序状态{ db: Arc<数据库>, } #[派生（克隆）] 结构我的层{ 状态：应用程序状态， } 为 MyLayer 实现 Layer { 类型服务 = MyService; fn 层(&self, 内部: S) -> Self::Service { 我的服务{ 内在, 状态：self.state.clone(), } } } #[派生（克隆）] 结构体 MyService { 内：S，状态：应用程序状态， } 为 MyService 实现服务哪里 S：服务<请求>， { 类型响应 = S::响应；类型错误 = S::错误；类型 Future = S::Future; fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll> { self.inner.poll_ready(cx) } fn call(&mut self, req: 请求) -> Self::Future { // 这里使用 self.state self.inner.call(req) } } 让状态=应用程序状态{ db: Arc::new(数据库::new()), }; 让应用程序 = Router::new() .route("/", get(处理程序)) .layer(MyLayer { 状态: state.clone() }) .with_state(状态); ### 路由之前的中间件在路由之前应用中间件（例如，用于 URI 重写）：使用塔::层; 使用 axum::ServiceExt； fn rewrite_request_uri(req: 请求) -> 请求 { // 修改请求URI 要求 } 让中间件 = tower::util::MapRequestLayer::new(rewrite_request_uri); 让应用程序 = Router::new() .route("/", get(处理程序)); // 在整个路由器周围应用层让 app_with_middleware = middleware.layer(app); 让listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await?; axum::serve(listener, app_with_middleware.into_make_service()).await?; ## 状态管理 ### 基本状态具有可克隆类型的简单状态：使用 axum::extract::State； #[派生（克隆）] 结构体应用程序状态{ 配置：配置， api_key：字符串， } async fn handler(State(state): State) -> String { 格式！（“配置：{：？}，密钥：{}”，state.config，state.api_key） } 让状态=应用程序状态{ 配置：配置::默认()， api_key: "秘密".to_string(), }; 让应用程序 = Router::new() .route("/", get(处理程序)) .with_state(状态); ### 与 Arc 共享状态使用“Arc”来共享昂贵的克隆类型的所有权：使用 std::sync::Arc；使用 tokio::sync::RwLock； #[派生（克隆）] 结构体应用程序状态{ db_pool: Arc<数据库池>, 缓存：Arc>>, config: Config, // 克隆成本低 } async fn handler(State(state): State) -> Result { // 访问数据库池让 conn = state.db_pool.get().await.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; // 访问缓存（读取）让缓存 = state.cache.read().await; 让 value = cache.get("key"); // 访问缓存（写）删除（缓存）； // 释放读锁让 mut cache = state.cache.write().await; cache.insert("new_key".to_string(), "value".to_string()); 好的("成功".to_string()) } ### 多种状态类型对不同的路由器部分使用不同的状态类型： #[派生（克隆）] 结构体ApiState { api_key：字符串， } #[派生（克隆）] 结构体应用程序状态{ db: Arc<数据库>, } fn api_routes() -> Router { 路由器::new() .route("/data", get(|State(state): State| 异步移动 { 格式！（“API密钥：{}”，state.api_key） }）） } fn app_routes() -> Router { 路由器::new() .route("/users", get(|State(state): State| 异步移动 { “用户”.to_string() }）） } 让 api_state = ApiState { api_key: "secret".to_string() }; 让 app_state = AppState { db: Arc::new(Database::new()) }; 让应用程序 = Router::new() .nest("/api", api_routes().with_state(api_state)) .nest("/app", app_routes().with_state(app_state)); ### 函数中的通用状态返回具有通用状态的路由器以实现灵活性： fn 路由() -> 路由器哪里 S：克隆+发送+同步+'静态， { 路由器::new() .route("/health", get(|| async { "确定" })) .route("/version", get(|| async { "1.0.0" })) } // 可以与任何状态类型组合让应用程序 = Router::new() .合并(路线()) .route("/", get(处理程序)) .with_state(AppState { /* ... */ }); ### 状态转换具有不同状态要求的链式路由器： #[派生（克隆）] 结构体状态A { data_a：字符串， } #[派生（克隆）] 结构体状态B { data_b：字符串， } 让 router_a: Router = Router::new() .route("/a", get(|State(s): State| 异步移动 { s.data_a })); // 提供StateA，下一个缺失的状态是StateB 让 router_b: Router = router_a.with_state(StateA { data_a: "A".to_string(), }); // 添加需要StateB的路由让router_b = router_b .route("/b", get(|State(s): State| 异步移动 { s.data_b })); // 提供StateB，现在我们有Router<()> 让应用程序： Router<()> = router_b.with_state(StateB { data_b: "B".to_string(), }); ## 错误处理 ### 结果的基本错误处理使用 Result 来处理处理程序中的错误：使用 axum::http::StatusCode；异步 fn handler() -> Result { 让结果 = some_operation().await; 比赛结果{ Ok(data) => Ok(format!("成功: {}", data)), Err(_) => Err(StatusCode::INTERNAL_SERVER_ERROR), } } ### 自定义错误类型为自定义错误实现“IntoResponse”：使用阿克苏姆::{ 响应::{IntoResponse, 响应}, http::状态代码，杰森， }; 使用 serde::序列化； #[导出（调试）] 枚举应用程序错误{ 数据库（sqlx::错误），未找到，未经授权，验证错误（字符串）， } #[导出（序列化）] 结构错误响应{ 错误：字符串，消息：字符串， } 为 AppError 实现 IntoResponse { fn into_response(self) -> 响应 { 让（状态，error_message）=匹配自我{ 应用程序错误::数据库(e) => { Tracing::error!("数据库错误：{}", e); （StatusCode::INTERNAL_SERVER_ERROR，“数据库错误”） } AppError::NotFound => (StatusCode::NOT_FOUND，“未找到资源”), AppError::Unauthorized => (StatusCode::UNAUTHORIZED，“未经授权”), AppError::ValidationError(msg) => (StatusCode::BAD_REQUEST, &msg), }; 让 body = Json(ErrorResponse { 错误：status.to_string()，消息：error_message.to_string(), }); （状态，正文）.into_response() } } // 在处理程序中使用 async fn get_user(Path(id): Path) -> Result, AppError> { 让 user = db.get_user(id).await.map_err(AppError::Database)?; user.ok_or(AppError::NotFound).map(Json) } ### 提取器拒绝处理处理提取器拒绝以获得更好的错误消息：使用 axum::extract::rejection::JsonRejection；异步 fn create_user( 有效负载：结果，JsonRejection>， ) -> 结果, AppError> { 让 Json(create_user) = Payload.map_err(|err| 匹配错误 { JsonRejection::MissingJsonContentType(_) => { AppError::ValidationError("Content-Type 必须是 application/json".to_string()) } JsonRejection::JsonDataError(e) => { AppError::ValidationError(format!("无效的 JSON: {}", e)) } JsonRejection::JsonSyntaxError(e) => { AppError::ValidationError(format!("JSON 语法错误：{}", e)) } _ => AppError::ValidationError("请求正文无效".to_string()), })?; // 处理create_user 好的（Json（用户）） } ### 具有错误处理功能的自定义提取器创建具有自定义拒绝类型的提取器：使用阿克苏姆::{ 提取::{FromRequest, 请求}, 响应::{IntoResponse, 响应}, 异步特征， }; struct ValidatedJson(T); #[异步特征] 为 ValidatedJson 实现 FromRequest 哪里 T: serde::de::DeserializeOwned + 验证， S：发送+同步， { 类型拒绝=响应； async fn from_request(req: 请求, 状态: &S) -> Result { 让 Json(数据) = Json::::from_request(req, 状态) .await .map_err(|错误| { （状态代码::BAD_REQUEST, 格式！（“无效的 JSON：{}”，错误）， ).into_response() })?; data.validate().map_err(|err| { （状态代码::BAD_REQUEST, 格式！（“验证错误：{}”，err）， ).into_response() })?; 好的（ValidatedJson（数据）） } } 异步 fn 处理程序(ValidatedJson(data): ValidatedJson) -> String { // 数据已验证格式！（“收到：{：？}”，数据） } ### 中间件错误处理处理来自易出错的中间件的错误：使用 axum::error_handling::HandleErrorLayer；使用塔::ServiceBuilder； async fn handle_timeout_error(err: BoxError) -> (StatusCode, String) { if err.is::() { （状态代码::REQUEST_TIMEOUT, “请求时间太长”.to_string(), ） } 否则{ （状态代码::INTERNAL_SERVER_ERROR, 格式！（“未处理的错误：{}”，err），） } } 让应用程序 = Router::new() .route("/", get(处理程序)) .层( 服务构建器::new() .layer(HandleErrorLayer::new(handle_timeout_error)) .layer(TimeoutLayer::new(持续时间::from_secs(30))) ）； ### 容易出错的服务到可能失败的服务的路由：使用 axum::error_handling::HandleError； async fn fallible_operation() -> Result<(), 无论如何::Error> { // 可能失败的操作好的(()) } 让fallible_service = tower::service_fn(|_req| async { fallible_operation().await?; 好的::<_，无论如何::错误>(响应::新(Body::empty())) }); async fn handle_error(err: 无论如何::错误) -> (StatusCode, String) { （状态代码::INTERNAL_SERVER_ERROR, 格式！（“出了问题：{}”，err），） } 让应用程序 = Router::new().route_service( “/”， HandleError::new（fallible_service，handle_error），）； ## 响应构建 ### JSON 响应返回类型安全的 JSON：使用 axum::Json；使用 serde::序列化； #[导出（序列化）] 结构体ApiResponse { 成功：布尔值，数据：字符串， } 异步 fn handler() -> Json { Json(ApiResponse { 成功：真实，数据：“你好”.to_string(), }) } ### HTML 响应提供 HTML 内容：使用 axum::response::Html；异步 fn handler() -> Html<&'static str> { Html("
你好，世界！
") } async fn dynamic_html(Path(name): Path) -> Html { Html(格式!("
你好，{}
"，名称)) } ### 状态代码响应返回不同的状态码：使用 axum::http::StatusCode；异步 fn 处理程序() -> StatusCode { 状态代码::NO_CONTENT } async fn with_body() -> (StatusCode, String) { (StatusCode::CREATED, "资源已创建".to_string()) } async fn json_with_status() -> (StatusCode, Json) { (StatusCode::CREATED, Json(ApiResponse { /* ... */ })) } ### 自定义标头将自定义标头添加到响应中：使用 axum::http::{HeaderMap, header}; 异步 fn 处理程序() -> (HeaderMap, String) { 让 mut headers = HeaderMap::new(); headers.insert(header::CACHE_CONTROL, "max-age=3600".parse().unwrap()); headers.insert("X-Custom-Header", "value".parse().unwrap()); （标头，“响应正文”.to_string()） } ### 完全响应控制构建完整的响应：使用阿克苏姆::{ 响应::响应， http::{状态代码，标头}，身体::身体, }; 异步 fn 处理程序() -> 响应 { 响应::构建器() .status(状态代码::确定) .header（标头::CONTENT_TYPE，“应用程序/json”） .header("X-自定义", "值") .body(Body::from(r#"{"status":"ok"}"#)) .unwrap() } ### 流式响应将数据流式传输至客户端：使用 axum::response::sse::{Event, Sse}; 使用 futures::stream::{self, Stream}; 使用 std::convert::Infallible； async fn sse_handler() -> Sse>> { 让流 = 流::iter(0..10).map(|i| { Ok(Event::default().data(format!("Event {}", i))) }); Sse::新（流） } ### 文件下载提供文件下载：使用阿克苏姆::{ 响应::{响应，IntoResponse}， http::{标题，状态代码}，身体::身体, }; 使用 tokio::fs::File； async fn download_file() -> 结果 <响应，状态代码> { 让文件=文件::打开(“路径/到/文件.pdf”) .await .map_err(|_| StatusCode::NOT_FOUND)?; 让 body = Body::from_stream(tokio_util::io::ReaderStream::new(file)); 好的（响应::builder() .status(状态代码::确定) .header（标题::CONTENT_TYPE，“应用程序/pdf”） .header( 标头::CONTENT_DISPOSITION， "附件;文件名=\"文件.pdf\"", ） .body(正文) .unwrap()) } ## 生产模式 ### 数据库集成与数据库池集成：使用 sqlx::{PgPool, postgres::PgPoolOptions}; 使用 std::sync::Arc； #[派生（克隆）] 结构体应用程序状态{ 数据库：PgPool， } 异步 fn get_user( 状态（状态）：状态，路径（id）：路径， ) -> 结果, AppError> { 让 user = sqlx::query_as!(User, "SELECT * FROM users WHERE id = $1", id) .fetch_可选(&state.db) .await .map_err(AppError::数据库)? .ok_or(AppError::NotFound)?; 好的（Json（用户）） } #[东京::主要] 异步 fn main() { 让 db = PgPoolOptions::new() .max_connections(5) .connect(&env::var("DATABASE_URL").unwrap()) .await .unwrap(); 让状态 = AppState { db }; 让应用程序 = Router::new() .route("/users/:id", get(get_user)) .with_state(状态); 让listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); axum::serve(listener, app).await.unwrap(); } ### 配置管理使用环境变量和配置：使用 serde::反序列化；使用配置::{配置、配置错误、环境}； #[导出（调试、反序列化、克隆）] 结构设置{ 数据库网址：字符串， redis_url：字符串， jwt_secret：字符串，端口：u16， } 实现设置 { fn new() -> Result { 配置::构建器() .add_source(环境::默认()) .build()？ .try_deserialize() } } #[派生（克隆）] 结构体应用程序状态{ 设置：设置，数据库：PgPool， } #[东京::主要] 异步 fn main() { let settings = Settings::new().expect("加载配置失败"); 让 db = PgPoolOptions::new() .connect(&settings.database_url) .await .expect("连接数据库失败"); 让状态=应用程序状态{ 设置：settings.clone(), 分贝， }; 让应用程序 = Router::new() .route("/", get(处理程序)) .with_state(状态); let addr = format!("0.0.0.0:{}", settings.port); 让listener = tokio::net::TcpListener::bind(addr).await.unwrap(); axum::serve(listener, app).await.unwrap(); } ### 结构化日志记录实施全面的日志记录：使用跟踪::{信息、错误、调试、仪器}；使用tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt}； #[东京::主要] 异步 fn main() { 追踪订阅者::registry() .与( Tracing_subscriber::EnvFilter::try_from_default_env() .unwrap_or_else(|_| "info".into()), ） .with(tracing_subscriber::fmt::layer()) .init(); info!("正在启动服务器"); 让应用程序 = Router::new() .route("/", get(处理程序)) .layer(TraceLayer::new_for_http()); 让listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); info!("监听 {}",listener.local_addr().unwrap()); axum::serve(listener, app).await.unwrap(); } #[仪器] 异步 fn 处理程序(Path(id): Path) -> Result { debug!("处理用户 {} 的请求", id); 匹配 get_user_from_db(id).await { 好的（用户）=> { info!("成功检索用户{}", id); 好的（格式！（“用户：{}”，用户）） } 错误（e）=> { error!("获取用户{}失败：{}", id, e); 错误（应用程序错误::数据库（e）） } } } ### 优雅关闭实现优雅的关闭处理：使用 tokio::signal; 异步 fn shutdown_signal() { 让 ctrl_c = 异步 { 信号::ctrl_c() .await .expect("安装 Ctrl+C 处理程序失败"); }; #[cfg(unix)] 让终止=异步{ 信号::unix::信号(信号::unix::SignalKind::terminate()) .expect("安装信号处理程序失败") .recv() .等待； }; #[cfg(不是(unix))] 让终止= std::future::pending::<()>(); 东京::选择！ { _ = ctrl_c => {}, _ = 终止 => {}, } println!("收到信号，开始正常关机"); } #[东京::主要] 异步 fn main() { let app = Router::new().route("/", get(handler)); 让listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); axum::serve（监听器，应用程序） .with_graceful_shutdown(shutdown_signal()) .await .unwrap(); } ### 健康检查实施健康检查端点：使用 serde::序列化； #[导出（序列化）] 结构健康响应{ 状态：字符串，数据库：字符串，缓存：字符串， } async fn health_check(State(state): State) -> Json { 让 db_status = 匹配 sqlx::query("SELECT 1").fetch_one(&state.db).await { 好的（_）=>“健康”， Err(_) => "不健康", }; 让cache_status = match state.redis.ping().await { 好的（_）=>“健康”， Err(_) => "不健康", }; Json(健康响应{ 状态：如果db_status ==“健康”&&cache_status ==“健康”{ “健康”.to_string() } 否则{ “降级”.to_string() }, 数据库：db_status.to_string(), 缓存：cache_status.to_string(), }) } 让应用程序 = Router::new() .route("/health", 获取(health_check)) .route("/ready", 获取(readiness_check)) .with_state(状态); ### 速率限制实施速率限制：使用 tower::limit::RateLimitLayer；使用 std::time::Duration；让应用程序 = Router::new() .route("/api/data", get(处理程序)) .layer(RateLimitLayer::new( 100, // 最大请求数 Duration::from_secs(60), // 每分钟））； ### 请求验证使用自定义提取器验证请求：使用验证器::{Validate, ValidationError}; #[推导（调试、反序列化、验证）] 结构体CreateUserRequest { #[验证（长度（最小值= 3，最大值= 50））] 用户名：字符串， #[验证（电子邮件）] 电子邮件：字符串， #[验证（长度（最小值= 8））] 密码：字符串， } struct ValidatedJson(T); #[异步特征] 为 ValidatedJson 实现 FromRequest 哪里 T：反序列化拥有+验证， S：发送+同步， { 类型拒绝 = (StatusCode, String); async fn from_request(req: 请求, 状态: &S) -> Result { 让 Json(数据) = Json::::from_request(req, 状态) .await .map_err(|e| (StatusCode::BAD_REQUEST, e.to_string()))?; 数据.validate() .map_err(|e| (StatusCode::BAD_REQUEST, e.to_string()))?; 好的（ValidatedJson（数据）） } } 异步 fn create_user( ValidatedJson(用户): ValidatedJson, ) -> 结果, AppError> { // 用户已验证好的（Json（用户 { /* ... */ }）） } ## 测试 ### 单元测试处理程序隔离测试处理程序： #[cfg（测试）] 模组测试{ 使用超级::*; 使用 axum::body::Body；使用 axum::http::{Request, StatusCode}; 使用塔::ServiceExt; #[东京::测试] 异步 fn test_handler() { let app = Router::new().route("/", get(handler)); 让响应=应用程序 .oneshot(Request::builder().uri("/").body(Body::empty()).unwrap()) .await .unwrap(); assert_eq!(response.status(), StatusCode::OK); } } ### 集成测试测试完整的应用程序： #[cfg（测试）] 模组测试{ 使用超级::*; 使用 axum::body::Body；使用 axum::http::{请求、状态代码、方法}；使用塔::ServiceExt; 使用 serde_json::json; #[东京::测试] 异步 fn test_create_user() { 让状态 = AppState::test(); 让应用程序 = create_app(状态); 让 request_body = json!({ “用户名”：“测试用户”， “电子邮件”：“test@example.com” }); 让响应=应用程序 .oneshot( 请求::构建器() .method(方法::POST) .uri(“/用户”) .header(“内容类型”，“应用程序/json”) .body(Body::from(request_body.to_string())) .unwrap() ） .await .unwrap(); assert_eq!(response.status(), StatusCode::CREATED); } } ## 最佳实践 ### 处理程序组织 1. **保持处理程序精简** \- 将业务逻辑移至服务层 2. **使用提取器** \- 让类型系统处理提取 3. **返回结果类型** \- 使用自定义错误类型 4. **仪器处理程序** \- 添加跟踪以实现可观察性 ### 状态管理 1. **对昂贵的类型使用 Arc** \- 数据库池、缓存 2. **保持状态最小化** \- 仅真正共享的内容 3. **实现克隆** \- 状态提取器所需 4. **避免突变** \- 在需要时使用内部可变性（RwLock、Mutex） ### 错误处理 1. **创建自定义错误类型** \- 实施 IntoResponse 2. **提供上下文** \- 包括有用的错误消息 3. **适当地记录错误** \- 使用跟踪 4. **返回正确的状态代码** \- 匹配HTTP语义 ### 中间件 1. **使用ServiceBuilder** \-更直观的排序 2. **在正确的级别应用** \- 路由器 vs 路由 vs 方法 3. **处理错误** \- 对易出错的中间件使用 HandleErrorLayer 4. **保持中间件重点** \- 单一职责 ### 性能 1. **使用连接池** \- 用于数据库和外部服务 2. **启用压缩** \- 用于响应的 CompressionLayer 3. **实现缓存** \-减少冗余操作 4. **使用背压** \- LoadShedLayer、RateLimitLayer 5. **优化序列化** \- 使用高效的 JSON 库 ### 安全 1. **验证输入** \- 使用自定义提取器进行验证 2. **实现身份验证** \- 使用中间件进行身份验证 3. **使用HTTPS** \- 在生产环境中 4. **设置安全标头** \- CORS、CSP 等。 5. **速率限制** \- 防止滥用 ## 常见模式 ### 存储库模式特征 UserRepository { async fn get(&self, id: u32) -> Result; async fn create(&self, user: CreateUser) -> Result; async fn update(&self, id: u32, user: UpdateUser) -> Result; async fn delete(&self, id: u32) -> Result<(), AppError>; } 结构 PostgresUserRepository { 池：PgPool， } 为 PostgresUserRepository 实现 UserRepository { async fn get(&self, id: u32) -> Result { // 实现 } } #[派生（克隆）] 结构体应用程序状态{ user_repo: Arc, } 异步 fn get_user( 状态（状态）：状态，路径（id）：路径， ) -> 结果, AppError> { 让 user = state.user_repo.get(id).await?; 好的（Json（用户）） } ### 服务层模式结构体用户服务{ 存储库：Arc， email_service: Arc, } 实现用户服务{ async fn create_user(&self, data: CreateUser) -> Result { 让 user = self.repo.create(data).await?; self.email_service.send_welcome_email(&user).await?; 好的（用户） } } #[派生（克隆）] 结构体应用程序状态{ user_service: Arc<用户服务>, } ### 版本化 API fn v1_routes() -> Router { 路由器::new() .route("/users", get(v1::list_users)) .route("/users/:id", get(v1::get_user)) } fn v2_routes() -> Router { 路由器::new() .route("/users", get(v2::list_users)) .route("/users/:id", get(v2::get_user)) } 让应用程序 = Router::new() .nest("/api/v1", v1_routes()) .nest("/api/v2", v2_routes()) .with_state(状态); ** ** **技能版本**：1.0.0 **最后更新**：2025 年 10 月 **技能类别**：Web 开发、REST API、Rust、异步编程 **兼容**：Axum 0.7+、Tokio 1.0+、Tower 0.4+

阿克苏姆网络框架

包含技能