Rust 代码质量指南

技能文档

---
name: rust-code-quality-guide
title: Rust 代码质量指南
category: 开发工具
description: Rust 代码质量规范，覆盖类型转换、错误处理、格式化参数与 Clippy 合规四大规则。编写或审查 Rust 代码时保证错误信息可追溯、转换无静默失败、无 Clippy 压制。当用户编写 Rust 代码、修复 Clippy 告警、审查代码质量或设计错误处理时触发。触发词：Rust、代码质量、Clippy、错误处理、类型转换。
---

# Rust 代码质量指南

## 适用场景

- 编写涉及类型转换或错误处理的新 Rust 代码
- 审查 Rust 代码的质量问题
- 保证错误信息规范与 Clippy 合规
- 修复 Clippy 告警，或理解某些写法为何不被推荐

## 速查表

- `as` 强制转换 → 改用 `try_from()` + `map_err()`
- `unwrap_or(default)` → 改用 `map_err()` 携带明确错误
- `format!` → 使用内联参数 `{var}`
- 错误信息必须包含引发错误的实际值
- `#[allow(clippy::...)]` 仅允许出现在测试代码中

---

## 技能工作流

### 步骤1：类型转换检查（禁止兜底值）

**关键**：类型转换时严禁使用 `unwrap_or(MAX_VALUE)` 之类的兜底方法。

```rust
// ❌ 危险 - 静默失败并得到错误值
let offset = u16::try_from(offset_value).unwrap_or(u16::MAX);

// ❌ 危险 - 静默失败并得到错误值（负数被归零）
let value_u8 = u8::try_from(value.max(0))
    .map_err(|_| "value exceeds u8::MAX")?;

// ❌ 危险 - 静默失败并得到错误值
let value = u8::try_from(negative_value).unwrap_or(0);

// ✅ 安全 - 显式错误处理
let offset = u16::try_from(offset_value)
    .map_err(|_| format!("offset {offset_value} exceeds u16::MAX"))?;

// ✅ 安全 - 显式错误处理（负数直接报错）
let value_u8 = u8::try_from(value)
    .map_err(|_| format!("value {value} must be between 0 and 255"))?;
```

**原因**：`unwrap_or(MAX_VALUE)`、`max(0)`、`unwrap_or(0)` 等兜底写法会把越界或非法值静默映射成默认值，导致计算错误甚至系统故障。

**规则**：类型转换一律使用 `map_err` 或显式 `match` 做错误处理，绝不把非法值（负数、越界等）静默转成默认值。

### 步骤2：内联格式化参数

**关键**：`format!` 宏必须使用内联格式化参数，避免 Clippy 告警。

```rust
// ❌ 差 - 触发 clippy::uninlined_format_args 告警
let message = format!("Error: {} occurred at line {}", error, line);

// ✅ 好 - 使用内联格式化参数
let message = format!("Error: {error} occurred at line {line}");
```

**原因**：内联参数可读性更好、性能更优，且避免 Clippy 告警。

**规则**：`format!` 宏中始终使用 `{variable}` 语法，不使用分离参数。

### 步骤3：错误信息携带致错值

**关键**：错误信息必须包含引发错误的实际参数值。

```rust
// ❌ 差 - 无上下文的笼统错误
return Err("Invalid count".into());

// ✅ 好 - 携带实际参数值
return Err(format!("Invalid count: {count} (must be 1-474)").into());

// ✅ 好 - 复杂校验携带多个参数
return Err(format!("Range exceeds maximum: {start}-{end} (max 99)").into());
```

**原因**：错误信息中包含实际参数值，能让调试时立刻定位问题现场，显著降低排查成本。

**规则**：使用内联格式化参数，把引发错误的实际值写进错误信息。

### 步骤4：用 try_from() 替代 as 转换

**关键**：类型转换使用 `try_from()` 而非 `as` 强制转换。

```rust
// ❌ 差 - as 转换静默截断
let value = large_number as u8;

// ✅ 好 - try_from 显式错误处理
let value = u8::try_from(large_number)
    .map_err(|_| format!("Value {large_number} exceeds u8::MAX"))?;
```

**原因**：`as` 转换会静默截断数值，`try_from()` 则对越界转换提供显式错误处理。

**规则**：类型转换一律使用 `try_from()` 替代 `as`，并实现规范的错误处理。

### 步骤5：生产代码禁止压制 Clippy 告警

**关键**：生产代码（非测试代码）严禁使用 `#[allow(clippy::...)]` 压制 Clippy 告警。

```rust
// ❌ 差 - 在生产代码中压制告警
#[allow(clippy::too_many_lines)]
pub async fn process_request(...) {
    // 100+ 行代码
}

// ✅ 好 - 把函数重构得更小
pub async fn process_request(...) {
    // 调用更小的辅助函数
    handle_validation(...).await?;
}

async fn handle_validation(...) {
    // 更小、职责单一的函数
}
```

**原因**：压制 Clippy 告警会掩盖代码质量问题。正确做法是解决底层问题（如拆分大函数、修复类型问题等）。

**规则**：
- 生产代码：始终修复底层问题，而不是压制告警
- 测试代码：允许对测试特有模式使用 `#[allow(...)]`（如 `unwrap_used`、`significant_drop_tightening`）
- 若告警确实无法合理修复，用注释说明豁免原因

## 自检清单

审查或提交 Rust 代码前逐项确认：

- [ ] 所有类型转换使用 `try_from()` + `map_err()`，无 `unwrap_or` 兜底
- [ ] `format!` 全部使用内联参数
- [ ] 错误信息包含致错的实际值
- [ ] 生产代码无 `#[allow(clippy::...)]`

使用说明

# Rust 代码质量指南

Rust 编码质量规范：类型转换无静默失败、错误信息可追溯、零 Clippy 压制。

## 使用

```text
用 Rust 代码质量指南审查这段代码
```

```text
帮我修复这个 crate 的所有 Clippy 告警
```

## 规则速览

- 类型转换一律 `try_from()` + `map_err()`，禁止 `unwrap_or` 兜底
- `format!` 使用内联参数 `{var}`
- 错误信息必须携带致错的实际值
- 生产代码禁止 `#[allow(clippy::...)]`，测试代码例外

## 工作原理

技能内置五步检查流（转换检查、格式化参数、错误信息、as 替换、告警压制），编写或审查代码时按步骤逐项核对，并给出正反代码示例对照。

如何安装此技能？

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