majiayu000 Rust 编码规范
核心问题
什么样的 Rust 代码才是"惯用的"？
遵循社区约定，让代码可读、可维护。
命名规范 (Rust 特有)
| 规则 | 正确 | 错误 |
|---|---|---|
方法不用 get_ 前缀 |
fn name(&self) |
fn get_name(&self) |
| 迭代器方法 | iter() / iter_mut() / into_iter() |
get_iter() |
| 转换命名 | as_ (廉价), to_ (昂贵), into_ (所有权) |
混用 |
static 变量大写 |
static CONFIG: Config |
static config: Config |
const 变量 |
const BUFFER_SIZE: usize = 1024 |
无限制 |
通用命名
// 变量和函数：snake_case
let max_connections = 100;
fn process_data() { ... }
// 类型和 trait：CamelCase
struct UserSession;
trait Cacheable {}
// 常量：SCREAMING_SAME_CASE
const MAX_CONNECTIONS: usize = 100;
static CONFIG:once_cell::sync::Lazy<Config> = ...
数据类型规范
| 规则 | 说明 | 示例 |
|---|---|---|
| 用 newtype | 领域语义 | struct Email(String) |
| 用 slice 模式 | 模式匹配 | if let [first, .., last] = slice |
| 预分配 | 避免重新分配 | Vec::with_capacity(), String::with_capacity() |
| 避免 Vec 滥用 | 固定大小用数组 | let arr: [u8; 256] |
字符串
| 规则 | 说明 |
|---|---|
ASCII 数据用 bytes() |
s.bytes() 优于 s.chars() |
可能修改时用 Cow<str> |
借用或拥有 |
用 format! 拼接 |
优于 + 操作符 |
避免嵌套 contains() |
O(n*m) 复杂度 |
错误处理规范
| 规则 | 说明 |
|---|---|
用 ? 传播 |
不用 try!() 宏 |
expect() 优于 unwrap() |
值确定时 |
用 assert! 检查不变量 |
函数入口处 |
// ✅ 好的错误处理
fn read_config() -> Result<Config, ConfigError> {
let content = std::fs::read_to_string("config.toml")
.map_err(ConfigError::from)?;
toml::from_str(&content)
.map_err(ConfigError::parse)
}
// ❌ 避免
fn read_config() -> Config {
std::fs::read_to_string("config.toml").unwrap() // panic!
}
内存与生命周期
| 规则 | 说明 |
|---|---|
| 生命周期命名有意义 | 'src, 'ctx 而非 'a |
RefCell 用 try_borrow |
避免 panic |
| 用 shadowing 转换 | let x = x.parse()? |
并发规范
| 规则 | 说明 |
|---|---|
| 确定锁顺序 | 防止死锁 |
| 原子类型用于原语 | 不用 Mutex<bool> |
| 谨慎选择内存序 | Relaxed/Acquire/Release/SeqCst |
Async 规范
| 规则 | 说明 |
|---|---|
| CPU-bound 用同步 | Async 适用于 I/O |
| 不要跨 await 持有锁 | 使用 scoped guard |
宏规范
| 规则 | 说明 |
|---|---|
| 避免宏（除非必要） | 优先用函数/泛型 |
| 宏输入像 Rust | 可读性优先 |
废弃模式 → 推荐
| 废弃 | 推荐 | 版本 |
|---|---|---|
lazy_static! |
std::sync::OnceLock |
1.70 |
once_cell::Lazy |
std::sync::LazyLock |
1.80 |
std::sync::mpsc |
crossbeam::channel |
- |
std::sync::Mutex |
parking_lot::Mutex |
- |
failure/error-chain |
thiserror/anyhow |
- |
try!() |
? operator |
2018 |
Clippy 规范
[package]
edition = "2024"
rust-version = "1.85"
[lints.rust]
unsafe_code = "warn"
[lints.clippy]
all = "warn"
pedantic = "warn"
常用 Clippy 规则
| Lint | 说明 |
|---|---|
clippy::all |
启用所有警告 |
clippy::pedantic |
更严格的检查 |
clippy::unwrap_used |
避免 unwrap |
clippy::expect_used |
优先 expect |
clippy::clone_on_ref_ptr |
避免 clone Arc |
格式化 (rustfmt)
# 使用默认配置即可
rustfmt src/lib.rs
# 检查格式
rustfmt --check src/lib.rs
# 配置文件 .rustfmt.toml
max_line_width = 100
tab_spaces = 4
edition = "2024"
文档规范
/// 模块文档
//! 本模块处理用户认证...
/// 结构体文档
///
/// # Examples
/// ```
/// let user = User::new("name");
/// ```
pub struct User { ... }
/// 方法文档
///
/// # Arguments
///
/// * `name` - 用户名
///
/// # Returns
///
/// 初始化后的用户实例
///
/// # Panics
///
/// 当用户名为空时 panic
pub fn new(name: &str) -> Self { ... }
快速参考
命名: snake_case (fn/var), CamelCase (type), SCREAMING_CASE (const)
格式: rustfmt (just use it)
文档: /// for public items, //! for module docs
Lint: #![warn(clippy::all)]
代码审查清单
- 命名符合 Rust 惯例
- 使用
?而非unwrap() - 避免不必要的
clone() -
unsafe块有 SAFETY 注释 - 公共 API 有文档注释
- 运行
cargo clippy - 运行
cargo fmt