Rust 代码质量指南

技能文档

---
name: masayuki-kono-rust-code-quality-guide
title: Rust 代码质量指南
category: 开发工具
description: Rust 代码质量规范指南，覆盖类型转换错误处理、内联格式化参数、错误信息携带致错值、Clippy 告警治理等核心规则，并给出正反代码对照。当用户编写 Rust 代码、审查 Rust 代码质量、修复 Clippy 告警、处理类型转换或错误处理问题时触发。触发词：Rust、代码质量、Clippy、类型转换、错误处理。
---

# Rust 代码质量指南

Rust 代码质量规范：类型转换必须有显式错误处理、`format!` 使用内联参数、错误信息必须携带致错值、生产代码禁止压制 Clippy 告警。

## 适用场景

- 编写涉及类型转换或错误处理的新 Rust 代码
- 审查 Rust 代码的质量问题
- 确保错误信息与 Clippy 合规符合最佳实践
- 修复 Clippy 告警或理解某些模式为何不被推荐

## 技能工作流

### 步骤1：对照速查表识别问题模式

| 反模式 | 替代方案 |
|---|---|
| `as` 强制类型转换 | `try_from()` + `map_err()` |
| `unwrap_or(default)` 兜底 | `map_err()` 携带显式错误 |
| `format!` 分离参数 | 内联参数 `{var}` |
| 错误信息缺少致错值 | 错误信息必须包含实际参数值 |
| `#[allow(clippy::...)]` | 仅允许在测试代码中使用 |

### 步骤2：按规则修正代码

#### 规则1：类型转换禁止静默兜底

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

```rust
// ❌ DANGEROUS - Silent failure with wrong value
let offset = u16::try_from(offset_value).unwrap_or(u16::MAX);

// ❌ DANGEROUS - Silent failure with wrong value (negative to zero)
let value_u8 = u8::try_from(value.max(0))
    .map_err(|_| "value exceeds u8::MAX")?;

// ❌ DANGEROUS - Silent failure with wrong value
let value = u8::try_from(negative_value).unwrap_or(0);

// ✅ SAFE - Explicit error handling
let offset = u16::try_from(offset_value)
    .map_err(|_| format!("offset {offset_value} exceeds u16::MAX"))?;

// ✅ SAFE - Explicit error handling (negative values cause error)
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! 使用内联参数

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

```rust
// ❌ BAD - Causes clippy::uninlined_format_args warning
let message = format!("Error: {} occurred at line {}", error, line);

// ✅ GOOD - Use inline format arguments
let message = format!("Error: {error} occurred at line {line}");
```

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

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

#### 规则3：错误信息携带致错值

**关键**：错误信息中始终包含引发错误的实际参数值。

```rust
// ❌ BAD - Generic error message without context
return Err("Invalid count".into());

// ✅ GOOD - Include the actual parameter value
return Err(format!("Invalid count: {count} (must be 1-474)").into());

// ✅ GOOD - Include multiple parameters for complex validation
return Err(format!("Range exceeds maximum: {start}-{end} (max 99)").into());
```

**原因**：错误信息带上实际参数值能提供即时上下文，显著降低调试成本。

**规则**：错误信息始终通过内联格式化参数携带致错的实际参数值。

#### 规则4：用 try_from() 代替 as

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

```rust
// ❌ BAD - Silent truncation with as casting
let value = large_number as u8;

// ✅ GOOD - Explicit error handling with 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
// ❌ BAD - Suppressing warnings in production code
#[allow(clippy::too_many_lines)]
pub async fn process_request(...) {
    // 100+ lines of code
}

// ✅ GOOD - Refactor the function to be smaller
pub async fn process_request(...) {
    // Call smaller helper functions
    handle_validation(...).await?;
}

async fn handle_validation(...) {
    // Smaller, focused function
}
```

**原因**：压制告警会掩盖代码质量问题；应当重构代码解决根本问题（如拆分大函数、修复类型问题）。

**规则**：
- 生产代码：始终修复根本问题，而不是压制告警
- 测试代码：`#[allow(...)]` 可用于测试专属模式（如 `unwrap_used`、`significant_drop_tightening`）
- 确实无法合理修复的告警：用注释说明豁免原因

### 步骤3：验证 Clippy 合规

修正完成后运行 `cargo clippy` 复核：确认无新增告警、无生产代码中的 `#[allow]` 压制、错误信息均携带致错值。

使用说明

# Rust 代码质量指南

五条 Rust 代码质量硬规则：类型转换禁止静默兜底、`format!` 内联参数、错误信息携带致错值、`try_from()` 代替 `as`、生产代码禁止压制 Clippy 告警，全部配有正反代码对照。

## 使用

```text
帮我审查这段 Rust 代码的类型转换和错误处理
cargo clippy 报了 uninlined_format_args，帮我修一下
```

编写或审查 Rust 代码时直接引用规则即可，技能会对照速查表定位反模式并给出修正写法。

## 工作原理

技能以「速查表识别 → 规则修正 → cargo clippy 复核」三步流程治理代码质量：先用对照表发现 `as` 转换、`unwrap_or` 兜底、分离格式化参数等反模式，再按五条规则以 `try_from()` + `map_err()` 等显式错误处理方式重写，最后用 Clippy 验证合规。

如何安装此技能？

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