用途
该技能面向在 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,仅当这些模型更契合时才选用它们。
使用方式
技能规定了一套强制性的智能体工作流:
构建服务前并行执行:
- fuse-ai-pilot:explore-codebase — 检测现有 router、state 与 DB 层
- fuse-ai-pilot:research-expert — 通过 Context7/Exa 验证当前 axum/sqlx API(axum 0.8 改动了若干 API)
- mcp__context7__query-docs — 拉取精确的提取器/处理器签名
构建后运行 fuse-ai-pilot:sniper。
关键规则:
- 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 实现必须去掉该宏。
参考指南包含概念文档(architecture.md、error-handling.md、database.md、observability.md)与模板(rest-service.md,用于完整最小 REST 服务:router + state + handlers + errors + tracing)。
快速参考示例:
带 0.8 路径语法的 Router:
let app = Router::new() .route("/users", get(list).post(create)) .route("/users/{id}", get(show)) // NOT /:id .with_state(state);
编译期校验查询:
let user = sqlx::query_as!(User, "SELECT id, name FROM users WHERE id = $1", id) .fetch_optional(&pool) .await?;
最佳实践:
- 保持一个实现 IntoResponse 的应用错误类型。
- 通过 tower-http 分层处理横切关注点(trace、timeout、cors)。
- 用 query!/query_as! 在编译期验证查询。
- 不要使用 /:id 路由语法(仅 0.7 及更早版本)。
- 不要在处理器中 .unwrap() — 返回类型化错误。
- 不要在异步代码中使用 diesel 而不考虑其同步特性。
适用场景
适用于需要按标准栈搭建 Rust REST/HTTP 后端的开发者,尤其是使用 axum 0.8 与 sqlx 0.9 的项目,需要路由、状态、中间件、错误处理与数据库访问的规范做法。
限制
不覆盖原始异步/并发原语与跨领域 crate 选型。资料中未提供收费、价格、平台支持范围等具体信息。