Rust 性能优化最佳实践

技能文档

---
name: mcart13-rust-performance-best-practices
title: Rust 性能优化最佳实践
category: 开发工具
description: Rust 性能优化专家指南，覆盖构建配置、内存分配、数据结构、迭代器、锁同步、异步与 I/O 九大类 45 条量化规则，含性能剖析命令与决策树。编写、审查或优化 Rust 代码性能时使用。当用户反馈 Rust 程序慢、编译产物体积大、编译耗时长、锁竞争、内存占用高、需要调优 release profile/LTO、分析 flamegraph 火焰图或排查 Tokio 异步性能问题时触发。触发词：Rust、性能优化、火焰图、LTO、锁竞争、内存分配。
---

# Rust 性能优化最佳实践

面向实战的 Rust 性能优化指南：9 大类 45 条规则，每条均附真实基准数据、典型收益幅度与适用条件。

## 适用场景

- 排查 Rust 程序运行慢、延迟高的问题
- 优化构建耗时或二进制体积
- 审查分配密集型代码
- 定位锁竞争或线程扩展性问题
- 为生产环境配置 release profile
- 使用 Tokio、async-std 等异步运行时时排查性能问题

## 不适用场景

出现以下情况时先不要优化：

- 代码不在热路径上（先做剖析！）
- 优化会显著损害可读性
- 尚未实测出性能问题
- 需要引入无法验证安全性的 unsafe
- 过早优化会拖延交付

## 技能工作流

**核心原则**：大多数 Rust 代码不需要优化。先剖析，后优化。

### 步骤1：先测量

在改动任何代码之前，先用工具定位真实瓶颈，禁止凭感觉猜测：

```bash
# CPU 剖析（Linux）
cargo flamegraph --bin myapp
perf record -g ./target/release/myapp && perf report

# 内存剖析
heaptrack ./target/release/myapp && heaptrack_gui heaptrack.myapp.*.gz
DHAT_LOG_FILE=dhat.out cargo run --release && dh_view.py dhat.out

# 基准测试
cargo bench                          # 全部基准
cargo bench hot_function             # 指定基准

# 分配追踪
MALLOC_TRACE=/tmp/mtrace.log ./target/release/myapp
mtrace ./target/release/myapp /tmp/mtrace.log

# 汇编检查
cargo asm my_crate::hot_function --rust

# 系统调用计数
strace -c ./target/release/myapp 2>&1 | head -20
```

### 步骤2：检查构建配置

构建配置是收益最大的一层（调试版与发布版差距可达 10-100 倍）：

- 是否为 release 模式？（对比 debug 有 10-100 倍差距）
- 是否启用 LTO？（通常提升 5-20%）
- 是否设置 target-cpu？（SIMD 场景可提升 10-30%）

### 步骤3：修复算法与数据结构问题

算法复杂度的改进远比微优化重要：

- O(n²) 降为 O(n log n) 优先于任何微优化
- 检查数据结构选型（HashMap/BTreeMap/VecDeque 等）
- 消除不必要的工作

### 步骤4：减少内存分配

每次堆分配都有代价，分配密集场景收益 2-50 倍：

- 预分配集合容量（`with_capacity`）
- 复用缓冲区（`clear()` 后重复使用）
- 用借用替代 `clone()`

### 步骤5：优化热点循环与 I/O

- 迭代器优于下标循环
- 缩小锁作用范围
- 合并批量化 I/O 操作（BufReader/BufWriter）

### 步骤6：再次测量验证

用基准测试确认改进幅度，确认其他路径无回归，并记录优化结论。

## 常见场景速查

### 「程序运行慢」

```text
是否在 debug 模式运行？
├── 是 → build-release-profile（10-100 倍提升）
└── 否
    │
    火焰图显示时间花在哪？
    ├── malloc/free → alloc-* 规则（with_capacity、复用缓冲区）
    ├── Mutex::lock → sync-* 规则（RwLock、原子类型、缩小锁范围）
    ├── read/write 系统调用 → io-* 规则（BufReader/BufWriter）
    ├── clone/drop → alloc-avoid-clone，改用引用
    └── 自身代码 → iter-* 规则、算法改进
```

### 「二进制体积过大」

```text
1. 启用 LTO：build-enable-lto（缩小 10-20%）
2. 设 opt-level = 'z'：build-opt-level（按体积优化）
3. panic = 'abort'：build-panic-abort（去除栈展开代码）
4. 剥离符号：Cargo.toml 中 strip = true
5. 去除调试信息：debug = 0
```

### 「内存占用高」

```text
1. 预分配容量：alloc-*-with-capacity
2. 复用分配：alloc-reuse-buffers
3. 避免克隆：alloc-avoid-clone
4. API 用切片：alloc-use-slices-in-apis
5. 考虑 arena 分配器：bumpalo crate
```

### 「锁竞争 / 线程扩展性差」

```text
1. 剖析确认锁热点
2. 缩小锁范围：sync-keep-lock-scope-short
3. 读多写少？→ sync-use-rwlock
4. 简单计数器？→ sync-use-atomics
5. 消息传递？→ sync-use-channels
6. 统计类数据用 thread-local + 定期汇总
```

### 「文件 I/O 慢」

```text
1. 包一层 BufReader/BufWriter：io-use-bufreader、io-use-bufwriter
2. 返回前 flush：io-flush-bufwriter（防止丢数据！）
3. 复用行缓冲：io-read-line-with-bufread
4. 随机访问考虑 mmap：memmap2 crate
```

## 规则总表

### 1. 构建配置（最关键，优先检查）

适用于所有 Rust 代码，优先级最高。

| 规则 | 收益 | 要点 |
| -------------------- | ----------- | ------------------------------------ |
| `build-release-profile` | 10-100x | 始终用 release 构建交付 |
| `build-opt-level` | 2-5x | 追求速度用 opt-level=3，追求体积用 'z' |
| `build-enable-lto` | 5-20% | LTO 启用跨 crate 优化 |
| `build-codegen-units` | 5-15% | codegen-units=1 获得最大优化空间 |
| `build-panic-abort` | 体积 | panic='abort' 去除栈展开代码 |
| `build-target-cpu` | 10-30% | target-cpu=native 启用 SIMD |
| `build-pgo` | 5-20% | 基于剖析的引导优化 |
| `build-incremental-off` | 5-10% | release 构建关闭增量编译 |

### 2. 基准测试（必做）

测不到就优化不了。

| 规则 | 目的 |
| --------------------- | ----------------------------------- |
| `bench-cargo-bench` | 使用 `cargo bench` + criterion |
| `bench-bench-profile` | bench profile 需保留优化 |
| `bench-black-box` | 防止死代码消除 |
| `bench-avoid-io` | I/O 波动会毁掉测量结果 |

### 3. 内存分配

每次分配都是一次系统调用，尽量减少。

| 规则 | 收益 | 模式 |
| ----------------------------- | ----------- | ----------------------------------------------------------------- |
| `alloc-vec-with-capacity` | 2-10x | 用 `Vec::with_capacity(n)` 而非 `Vec::new()` |
| `alloc-string-with-capacity` | 2-5x | `String::with_capacity(n)` |
| `alloc-hashmap-with-capacity` | 2-5x | `HashMap::with_capacity(n)` |
| `alloc-reuse-buffers` | 2-10x | `.clear()` 后复用，不重新分配（紧循环中可达 50 倍） |
| `alloc-use-slices-in-apis` | 灵活性 | 参数用 `&[T]` 而非 `Vec<T>` |
| `alloc-avoid-clone` | 2-10x | 用借用 `&T` 替代 `clone()`（数据越大收益越高） |

### 4. 数据结构

选对数据结构胜过一切微优化。

| 规则 | 适用场景 |
| -------------------------------- | ----------------------------- |
| `data-avoid-linkedlist` | 几乎总是避免（Vec 更优） |
| `data-choose-vecdeque-for-queue` | FIFO 队列 |
| `data-choose-map-type` | HashMap=O(1)，BTreeMap=有序 |
| `data-use-entry-api` | 插入或更新模式 |
| `data-repr-transparent` | FFI newtype |

### 5. 迭代

迭代器与手写循环同速且更安全。

| 规则 | 收益 | 模式 |
| ------------------------------ | ------------- | --------------------------------------- |
| `iter-avoid-collect-then-loop` | 2-3x | 链式迭代器，不要先 collect |
| `iter-use-lazy-iterators` | 2-3x | `.filter().map()` 而非中间 Vec |
| `iter-use-any-find` | 短路求值 | 用 `.any()` 而非 `.filter().count() > 0` |
| `iter-use-retain` | 原地修改 | `.retain()` 而非 `.filter().collect()` |
| `iter-use-binary-search` | O(log n) | 有序数据用 `.binary_search()` |

### 6. 同步

锁很昂贵，把竞争降到最低。

| 规则 | 收益 | 适用场景 |
| ---------------------------- | -------------- | --------------------------------------------- |
| `sync-share-with-arc` | 避免复制 | 跨线程共享较大（>64B）数据 |
| `sync-use-rwlock` | 读场景 2-8 倍 | 读占比 >80%、写少；可考虑 parking_lot |
| `sync-keep-lock-scope-short` | 4x | 最小化锁内代码 |
| `sync-use-channels` | 3-4x | 用消息传递替代共享状态 |
| `sync-use-atomics` | 20x | 简单计数器、标志位 |
| `sync-use-parking-lot` | 1.5-5x | 用 `parking_lot` 替代 std 同步原语 |

### 7. I/O

系统调用有成本，务必加缓冲。

| 规则 | 收益 | 模式 |
| --------------------------- | -------- | ------------------------------------ |
| `io-use-bufreader` | 50x | 用 `BufReader` 包装 `File` |
| `io-use-bufwriter` | 18x | 用 `BufWriter` 包装 `File` |
| `io-flush-bufwriter` | 关键 | **必须 flush，否则丢数据！** |
| `io-read-line-with-bufread` | 53x | `read_line` 复用 String 缓冲 |

### 8. 异步 Await（高优先级）

对 Tokio、async-std 应用至关重要。

| 规则 | 收益 | 模式 |
| ------------------------- | ------------- | -------------------------------------------- |
| `async-spawn-blocking` | 防止挂死 | CPU 密集任务用 `spawn_blocking` |
| `async-cooperative` | 延迟 | 长计算中周期性让出（yield） |
| `async-mutex-choice` | 正确性 | 跨 `.await` 点用 `tokio::sync::Mutex` |
| `async-avoid-blocking-io` | 吞吐 | 异步上下文用异步 I/O，不用 std::fs |
| `async-bounded-channels` | 背压 | 用有界 channel 做流控 |

**核心认知**：异步运行时是协作式的。阻塞执行器线程会让所有其他任务挨饿。

```rust
// BAD：阻塞异步运行时
async fn process(data: &[u8]) -> Result<Hash> {
    let hash = expensive_hash(data);  // CPU 密集，阻塞执行器！
    Ok(hash)
}

// GOOD：卸载到阻塞线程池
async fn process(data: Vec<u8>) -> Result<Hash> {
    tokio::task::spawn_blocking(move || expensive_hash(&data)).await?
}
```

### 9. Unsafe（仅限专家）

只在剖析证明确有必要时使用。

| 规则 | 收益 | 风险 |
| ------------------------- | ------------- | ----------------------------- |
| `unsafe-get-unchecked` | 5-30% | 越界即未定义行为 |
| `unsafe-use-maybeuninit` | 分配 20-100 倍 | 写前读取即未定义行为 |
| `unsafe-avoid-transmute` | 正确性 | 优先选择安全替代方案 |
| `unsafe-repr-transparent` | 零成本 | FFI newtype 必需 |

## 决策树

### 何时用 with_capacity？

```text
知道大致大小吗？
├── 精确知道 → with_capacity(精确值)
├── 大概知道 → with_capacity(估算值)
└── 不知道
    │
    会频繁增长吗？
    ├── 会 → 初始给大一点，或用 reserve()
    └── 不会 → Vec::new() 就够了
```

### Mutex、RwLock 还是原子类型？

```text
是简单计数器/标志位吗？
├── 是 → 原子类型（快 20 倍）
└── 否
    │
    读写比例如何？
    ├── 以读为主（>90%）→ RwLock
    ├── 以写为主 → Mutex
    └── 混合 → Mutex（更简单）

    以上场景 parking_lot 均优于 std
```

### unsafe 的 get_unchecked 什么时候值得用？

```text
剖析发现边界检查是瓶颈了吗？
├── 没有 → 别用
└── 是
    │
    确认 LLVM 没有自动消除边界检查？
    ├── 没确认 → 先看汇编（cargo asm）
    └── 确认仍在
        │
        能改用迭代器吗？
        ├── 能 → 用迭代器（同样快且安全）
        └── 不能 → get_unchecked 并写清不变量文档
```

## 优化自查清单

- [ ] 已用火焰图/perf 定位真实瓶颈，而非猜测
- [ ] release profile 已按上表逐项检查（LTO、opt-level、codegen-units、target-cpu）
- [ ] 热路径上没有多余的 `clone()` 与中间集合
- [ ] 集合容量已预分配，缓冲区可复用
- [ ] 锁范围最小化，读写比例匹配锁类型
- [ ] 文件 I/O 全部带缓冲，`BufWriter` 返回前已 flush
- [ ] 异步上下文中没有阻塞执行器的同步调用
- [ ] 每项优化都有前后基准数据，无其他路径回归

使用说明

# Rust 性能优化最佳实践

9 大类 45 条量化规则的 Rust 性能优化指南，附剖析命令、场景速查与决策树。

## 使用

对 Agent 说：

```text
帮我分析这个 Rust 程序为什么慢，并给出优化方案
```

```text
审查这段 Rust 代码的分配与锁使用，按性能最佳实践给出改法
```

## 工作原理

技能按「先测量、后优化」的流程工作：先用 flamegraph/perf/heaptrack 定位真实瓶颈，再依次检查构建配置（release/LTO/target-cpu）、算法与数据结构、内存分配、热点循环与 I/O，最后用基准测试验证收益。45 条规则按构建配置、基准测试、分配、数据结构、迭代、同步、I/O、异步、unsafe 九类组织，每条标注真实基准收益幅度与适用条件。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。