rust-stable

Rust 稳定版语言语义

将此技能用于语言语义：所有权、借用、生命周期、trait、泛型、模式匹配、错误传播和 Edition 差异。首先确认项目实际使用的工具链和最低支持 Rust 版本（MSRV）。

对于标准库 API 的选择（使用哪种集合、智能指针、字符串类型、I/O trait），请使用 rust-stdlib。对于具体模式示例（“如何编写 X”），请使用 rust-by-example。

开始前的准备工作

1. 运行 rustc --version --verbose 和 cargo --version。
2. 检查 rust-toolchain.toml、rust-toolchain 和 Cargo.toml 中的 rust-version 字段。
3. 区分三个版本：本地工具链版本、项目 MSRV 和当前官方稳定版。
4. 遇到对版本敏感的 API 时，请查阅 当前稳定版基线，并以官方发行说明和 API 文档作为最终依据。
5. 如果项目锁定在较旧版本，则严格遵循仅在该特定版本中已稳定的语法和 API。

**当前离线基线：**Rust 1.97.1（于 2026 年 7 月 16 日发布）。这是带日期的仓库基线，不会自动更新。

能力范围

适合处理

• 所有权、借用、生命周期和移动语义。
• struct、enum、模式匹配、trait、泛型和关联类型。
• Option、Result 错误传播和自定义错误（语言机制）。
• 闭包（Fn/FnMut/FnOnce）、属性语法、格式字符串（语言机制）。
• 模块、可见性修饰符、pub/pub(crate)/pub(super)。
• Edition 差异（语言层面——unsafe extern、RPIT 捕获、match ergonomics）。
• 常见编译错误、借用检查失败和稳定版迁移判断。

转交给专用技能

用户意图	首选技能
“我应该使用哪种标准库集合 / 智能指针 / 字符串类型？”	rust-stdlib
“如何在 Rust 中编写 X？”（具体模式）	rust-by-example
API 设计（命名、trait、面向未来的设计、约 100 条 C-* 规则）	rust-api-design
项目布局、模块树、工作区结构	rust-workspace、rust-module-layout
Cargo.toml 依赖、功能、配置、发布	rust-cargo-build
依赖治理、供应链、cargo-deny	rust-dependencies
Semver、破坏性变更分类、发布工作流	rust-semver
Java Maven/Gradle 项目迁移和组件替换	rust-java-migration
Java 到 Rust 的源代码测试一致性、Rust 义务和迁移测试审计	rust-java-migration-testing
线程、锁、原子操作、通道、Tokio	rust-concurrency
单元测试、集成测试、文档测试、覆盖率	rust-testing
原始指针、内存布局、FFI、Miri	rust-unsafe-ffi
UniFFI 生成的 Kotlin、Swift、Python、Ruby 或 WASM 绑定	rust-uniffi-building
macro_rules、派生宏、过程宏	rust-macros
命令契约、标准流、退出码、CLI	rust-cli
服务端 HTTP API、处理程序、中间件	rust-web
SQL/ORM、架构、迁移、事务、连接池	rust-database
Web 身份验证、授权、会话、令牌	rust-web-security
裸机固件、no_std 驱动程序、硬件验证	rust-embedded
风险、正确性、API 和安全审查	rust-code-review
rustfmt、Clippy、Edition 迁移、lint 策略	rust-style-clippy

不要用此技能替代领域专用技能的完整工作流。

工作流

1. 确定版本边界 — 记录工具链版本、版本类型、MSRV 和目标平台。
2. 缩小问题范围 — 确定问题属于所有权／类型系统／标准库／编译器错误，还是某个专门领域。
3. 阅读最少量的资源 — 只打开与问题直接相关的参考资料；不要一次性加载整套文档。
4. 实现最小的正确方案 — 优先使用稳定的标准库，明确所有权语义，并显式传播错误。
5. 运行质量门禁检查 — 执行 cargo fmt --check、cargo check（包括所有目标／功能）和相关测试。
6. 处理版本差异 — 如果 MSRV 不支持某个 API，则选择旧版兼容 API 或实现兼容层；否则明确提高 MSRV。
7. 转交给专门技能 — 进入异步、unsafe 宏、Web、嵌入式等领域后，加载相应技能。

设计规则

• 优先使用 &T／&mut T；只有在需要转移所有权或需要独立生命周期时才克隆。
• 使用类型表达不变量；优先选择枚举／新类型，而不是布尔参数和不受约束的字符串。
• 库代码应返回结构化错误；应用程序边界可以在决定如何展示错误前添加上下文。
• 优先使用迭代器和标准集合，但不要为了链式调用语法而牺牲可读性。
• 不要把 unsafe 当作绕过借用检查的手段；应先证明安全抽象无法表达需求。
• 不要默认导入第三方 crate；应与稳定版 std、MSRV、维护成本和供应链风险进行比较。
• 除非官方发行说明或带有 since 标记的 API 页面能够确认，否则绝不要声称某个 API 在特定版本中已稳定。

验证门禁

按风险从低到高运行验证门禁：

cargo fmt --all --check
cargo check --all-targets --all-features
cargo test --all-targets --all-features
cargo clippy --all-targets --all-features -- -D warnings

如果项目不支持 --all-features，或包含特定于平台的目标，请记录原因并使用定义好的功能／目标矩阵。对于 unsafe 代码，添加 cargo miri test；对于 MSRV 问题，在声明的最低工具链上重复运行 cargo check 和测试。

按需阅读的必备文档

版本与语言语义

• 当前稳定版基线：最新版本、兼容性说明、更新步骤。
• 所有权与生命周期：借用设计、返回值和生命周期判断规则。
• Trait 与泛型：约束、关联类型、Trait 对象、API 权衡。
• 模式与惯用风格：构建器模式、新类型、RAII、类型状态管理。
• 风格指南：命名约定、模块组织、文档风格和 API 设计原则。

交叉参考（改用相应技能）

• “该用哪种 std 集合／智能指针／字符串类型？” → rust-stdlib（其 references/ 涵盖 collections、smart-pointers、string-types、iterators、I/O、interior-mutability、combinators、std-concurrency、process-and-fs、std-module-index）
• “如何编写 X？” → rust-by-example（其 references/ 涵盖 conversions、flow-control、closures、modules、generics-traits、error-handling、attributes、unsafe、procedural-macros-overview、inline-asm、migrating-from-other-languages）
• API 设计 → rust-api-design；Cargo 清单 → rust-cargo-build；依赖治理 → rust-dependencies

可复现示例

• 快速入门工作流
• 所有权模式（examples/ownership-patterns.md）
• 集合模式（examples/collections-patterns.md）
• Trait 设计模式（examples/trait-design-patterns.md）
• 错误处理模式（examples/error-handling-patterns.md）
• examples/golden-basic/：由仓库 CI 编译的最小黄金示例。

应避免的常见问题

1. 将“当前稳定版”与项目的 MSRV 混为一谈。
2. 只运行 cargo check，遗漏测试、示例、基准测试或特性组合。
3. 仅为避免借用错误就盲目使用 clone、封装为 Arc<Mutex<_>> 或调用 unsafe。
4. 在异步代码中跨 .await 调用持有同步锁。
5. 将带版本号的历史文档描述为持续更新的资源。
6. 复制代码片段时，未包含依赖项、特性、错误类型和平台限制。

官方来源

• Rust 发布说明
• Rust 程序设计语言（The Rust Programming Language）
• 标准库参考
• 参考手册
• Rust 示例集
• Edition 指南

数据隐私政策

此技能仅提供本地知识、示例和验证工作流。它不会收集、存储或传输用户数据。访问官方文档前，必须遵守用户的网络访问要求，才能访问公开资源。