SuperAPI AI 工具集

rust-web-backend

编程与开发

查看项目

更新于 11-10 08:11

技能介绍

用途

该技能用于在 Rust 中构建 REST/HTTP 后端服务,覆盖 axum 路由、提取器、共享状态、中间件、错误响应以及 sqlx 数据库访问。它明确划定了范围:原始异步/并发原语(通道、锁、任务生成)属于 rust-async-concurrency;跨领域的 crate 选型属于 rust-ecosystem-crates。

主要能力与推荐技术栈

文档给出的 2026 标准技术栈包括:运行时 tokio(事实上的异步运行时);HTTP 框架 axum 0.8.x(基于 Tower,提取器易用、魔法少);中间件 tower / tower-http(可组合层,含 trace、cors、timeout、compression);数据库 sqlx 0.9(异步、query! 编译期检查 SQL、无 DSL,支持 Postgres/MySQL/SQLite);可观测性 tracing + tracing-subscriber(结构化、异步感知的 span 与日志)。

文档还列出诚实的替代方案:sea-orm(ActiveRecord 风格 ORM,比 sqlx 更高层);diesel 2.x(成熟但同步,在异步应用中需要 spawn_blocking 或同步连接池)。标准栈优先选 sqlx,只有模型契合时才选用替代方案。

关键规则

  • axum 0.8 路径语法为 /{id},而非 /:id;/*rest 变为 /{*rest},旧 matchit 语法无法编译。
  • 错误需实现 IntoResponse,处理器中不得 .unwrap();通过单一应用错误类型把领域错误映射为状态码与响应体。
  • 使用 State<T> 共享状态,只包裹一次——把连接池/配置放入便于 Arc 的结构体,用 State 提取,不使用全局变量。
  • sqlx::query! 编译期需要 DATABASE_URL,或提交 .sqlx/ 离线缓存(cargo sqlx prepare),需在 CI 前规划。
  • axum 提取器上不要用 #[async_trait]——0.8 使用 RPITIT,自定义 FromRequestParts 实现须去掉该宏。

使用方式

文档要求代理按强制工作流程执行:在构建服务前并行启动 explore-codebase(检测现有路由器、状态与数据库层)、research-expert(通过 Context7/Exa 核实当前 axum/sqlx API,axum 0.8 变更了多项 API)、mcp__context7__query-docs(拉取准确的提取器/处理器签名);构建完成后运行 sniper。

参考指南按主题组织:architecture.md(路由器、提取器、State、tower 中间件布局)、error-handling.md(应用错误类型 + IntoResponse)、database.md(sqlx 连接池、query!、迁移、替代方案)、observability.md(tracing span、subscriber、请求日志)。模板 rest-service.md 提供完整最小 REST 服务(路由 + 状态 + 处理器 + 错误 + tracing)。

适用场景与限制

适用于需要搭建 Rust REST/HTTP 后端的开发场景,尤其是采用 axum 与 sqlx 的项目。文档中的快速参考示例展示了 0.8 路径语法与编译期检查查询的写法。最佳实践包括:保持单一实现 IntoResponse 的应用错误类型;通过 tower-http 分层横切关注点(trace、timeout、cors);用 query!/query_as! 在编译期验证查询。不要使用 /:id 路由语法(仅 0.7 及更早版本);不要在处理器中 .unwrap();不要在异步代码中未考虑 diesel 同步特性就选用它。

文档给出的来源为 tokio.rs 关于 axum 0.8 发布的博客(路径语法、Option 提取器、移除 #[async_trait])与 crates.io 版本信息(axum 0.8.9、sqlx 0.9.0、tokio 1.54.1、tracing 0.1.44、tower-http 0.7.1)。