moai-lang-rust

快速参考（30 秒）

Rust 1.92+ 开发专家，深入掌握高性能、内存安全应用的模式。

自动触发：.rs、Cargo.toml、async/await、Tokio、Axum、SQLx、serde、生命周期、trait

核心用例：

• 高性能 REST API 和微服务
• 内存安全的并发系统
• CLI 工具和系统实用程序
• WebAssembly 应用
• 低延迟网络服务

常用模式：

Axum REST API：使用路由宏链式指定路径和处理器，创建 Router。添加 with_state 以共享状态。使用 tokio::net 绑定 TcpListener，并通过 axum::serve 启动服务。

使用 SQLx 的异步处理器：定义异步处理器函数，使用 State 提取器获取 AppState，使用 Path 提取器获取 id。使用 sqlx::query_as! 宏编写 SQL 字符串并绑定参数。在连接池上调用 fetch_optional 并等待，然后使用 ok_or 转换错误。返回由 Json 包装的结果。

---

实现指南（5 分钟）

Rust 1.92 特性

现代 Rust 特性：

• Rust 2024 Edition 已推出（随 Rust 1.85 发布）
• async trait 已稳定（不再需要 async-trait crate）
• const 泛型支持编译时数组尺寸设定
• 使用 let-else 进行模式匹配并提前返回
• 借用检查器得到改进，支持 polonius

异步 trait（已稳定）：定义包含 async fn 签名的 trait。为具体类型实现 trait，并使用 async fn 实现。直接在 trait 方法中调用 sqlx 宏。

Let-Else 模式：使用 let Some(value) = option else，并在其中通过 return 提前退出。可串联多个 let-else 语句进行顺序验证。在 else 代码块中返回错误类型。

Web 框架：Axum 0.8

安装：在 Cargo.toml 的 dependencies 部分添加 axum 版本 0.8、启用 full 特性的 tokio 版本 1.48，以及启用 cors 和 trace 特性的 tower-http 版本 0.6。

完整 API 设置：从 axum::extract 导入提取器和路由宏。定义派生 Clone 的 AppState 结构体以保存 PgPool。在 tokio::main 异步 main 函数中，通过设置 max_connections 并使用环境变量中的 DATABASE_URL 连接，创建连接池。使用路径和处理器的路由链构建 Router，添加 CorsLayer，并调用 with_state。绑定 TcpListener 并调用 axum::serve。

处理器模式：定义异步处理器，使用类型适当的 State、Path 和 Query 提取器。使用 sqlx::query_as! 进行带位置绑定参数的类型安全查询。返回包含 Json 成功响应和 AppError 错误响应的 Result。

异步运行时：Tokio 1.48

任务生成与通道：创建具有指定容量的 mpsc 通道。使用 tokio::spawn 生成工作任务，并在循环中从通道接收消息。对于超时，使用 tokio::select! 宏设置操作分支和 sleep 分支，在超时时返回错误。

数据库：SQLx 0.8

类型安全查询：在结构体上派生 sqlx::FromRow，以自动映射数据。使用 query_as! 宏进行编译时检查的查询。在连接池上调用 fetch_one 或 fetch_optional。对于事务，调用 pool.begin，在事务引用上执行查询，然后调用 tx.commit。

序列化：Serde 1.0

在结构体上派生 Serialize 和 Deserialize。使用带有 rename_all 的 serde 属性进行大小写转换。使用 rename 属性指定字段名称。使用 skip_serializing_if 和 Option::is_none。使用 default 属性设置默认值。

错误处理

thiserror：在枚举上派生 Error，并使用 error 属性设置显示消息。使用 from 属性自动转换源错误。通过匹配不同变体实现 IntoResponse，并返回状态码以及包含错误消息的 Json 响应体。

CLI 开发：clap

在主 Cli 结构体上派生 Parser，并使用 command 属性设置 name、version 和 about。使用 arg 属性设置全局标志。在枚举上派生 Subcommand 以定义命令。在 main 函数中匹配 command 并分发逻辑。

测试模式

创建带有 cfg(test) 属性的测试模块。定义 tokio::test 异步函数。调用设置辅助函数，执行待测函数，并使用 assert! 宏进行验证。

---

高级模式

如需全面了解以下内容：

• 高级所有权模式、生命周期和智能指针
• trait 设计和泛型编程
• 性能优化策略和性能分析
• 工程最佳实践和编码指南
• 异步模式和并发

请参阅：reference/engineering.md，了解所有权和 trait；reference/performance.md，了解优化；reference/guidelines.md，了解编码标准

性能优化

发布构建：在 Cargo.toml 的 profile.release 部分中，启用 lto，将 codegen-units 设为 1，将 panic 设为 abort，并启用 strip。

部署

最小化容器：使用多阶段 Dockerfile。第一阶段使用 rust alpine 镜像，复制 Cargo 文件，创建用于依赖缓存的虚拟 main，构建 release 版本，复制源代码，触碰 main.rs 以触发重新构建，再构建最终的 release 版本。第二阶段使用 alpine，从构建器复制二进制文件，暴露端口并设置 CMD。

并发

限速操作：创建一个由 Arc 包装的 Semaphore，并设置最大许可数。遍历各项并生成任务；每个任务获取许可、处理数据并返回结果。使用 futures::future::join_all 收集结果。

---

Context7 集成

库文档访问：

• /rust-lang/rust - Rust 语言和标准库
• /tokio-rs/tokio - Tokio 异步运行时
• /tokio-rs/axum - Axum Web 框架
• /launchbadge/sqlx - SQLx 异步 SQL
• /serde-rs/serde - 序列化框架
• /dtolnay/thiserror - 错误派生
• /clap-rs/clap - CLI 解析器

---

配合使用效果良好

• moai-lang-go - Go 系统编程模式
• moai-domain-backend - REST API 架构和微服务模式
• moai-foundation-quality - Rust 应用的安全加固
• moai-workflow-testing - 测试驱动开发工作流

---

故障排查

常见问题：

• Cargo 错误：运行 cargo clean，然后运行 cargo build
• 版本检查：运行 rustc --version 和 cargo --version
• 依赖问题：运行 cargo update 和 cargo tree
• 编译时 SQL 检查：运行 cargo sqlx prepare

性能特征：

• 启动时间：50-100 ms
• 内存使用量：基础占用 5-20 MB
• 吞吐量：100k-200k req/s
• 延迟：p99 小于 5 ms
• 容器大小：5-15 MB（alpine）

---

其他资源

请参阅 reference/engineering.md，了解高级所有权模式和 trait 设计。

请参阅 reference/performance.md，了解优化策略和性能分析技术。

请参阅 reference/guidelines.md，了解 Rust 编码标准和最佳实践。

---

最后更新：2026-01-11 版本：1.2.0