Codex CLI Rust 开发指南：自动生成测试、修复 Clippy 错误与 Rust 工作流

Rust 以内存安全和零成本抽象著称，但其借用检查器、生命周期和严格的类型系统也让开发者频繁与编译器"搏斗"。Codex CLI 深度理解 Rust 的所有权模型，能够批量生成符合惯例的单元测试、精准修复 Clippy 警告、重写错误处理代码，并帮助你完成 async/await 迁移和 WebAssembly 集成。本指南覆盖 Rust 项目的完整 Codex 使用场景。

1. Rust 项目的 AGENTS.md 配置

在项目根目录放置 AGENTS.md，明确告知 Codex CLI 你的 Rust 项目的构建命令、代码规范和工具链要求。以下是适用于生产级 Rust 项目的完整配置示例：

# Rust 项目规范

## 构建与测试
- 始终运行 `cargo build` 验证编译
- 运行测试：`cargo test -- --nocapture`
- Lint：`cargo clippy -- -D warnings`
- 格式化：`cargo fmt --check`
- 安全审计：`cargo audit`（需安装 cargo-audit）

## 代码规范
- 所有 unwrap() 必须替换为合适的错误处理（? 操作符或 match）
- 使用 thiserror 定义自定义错误类型
- 异步代码使用 Tokio runtime
- 避免 clone()——优先使用引用或 Arc

## 项目结构
- src/lib.rs 核心库代码
- src/main.rs 可执行文件入口
- tests/ 集成测试
- benches/ 性能基准测试

各部分的意义：

• 构建与测试：--nocapture 标志让测试输出实时显示，便于调试；cargo audit 检查已知 CVE 漏洞，适合在 CI 中使用。
• 代码规范：明确禁止 unwrap() 是最有效的单条规则——这一条能让 Codex 始终生成健壮的错误处理代码，而非快速原型级代码。
• 项目结构：区分 lib.rs（库）和 main.rs（可执行文件）帮助 Codex 将新代码放在正确位置，benches/ 提示 Codex 可以生成 criterion 基准测试。

2. 自动生成 Rust 单元测试

Rust 的测试模块通过 #[cfg(test)] 属性与源码放在同一文件中，这是语言级别的约定。Codex CLI 理解这一模式，可以分析函数签名、返回类型和文档注释，生成覆盖正常路径、错误路径和边界情况的完整测试模块。

2.1 基础提示词

$ codex "为 parse_config 函数生成覆盖边界情况的 Rust 单元测试"
$ codex "为 src/lib.rs 中所有 pub fn 生成测试模块"

2.2 生成的测试示例

以下是 Codex 为 parse_config 函数生成的典型 #[cfg(test)] 模块：

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_parse_config_valid() {
        let input = r#"{"port": 8080, "host": "localhost"}"#;
        let config = parse_config(input).unwrap();
        assert_eq!(config.port, 8080);
        assert_eq!(config.host, "localhost");
    }

    #[test]
    fn test_parse_config_invalid_json() {
        let result = parse_config("not json");
        assert!(result.is_err());
    }

    #[test]
    fn test_parse_config_missing_field() {
        let input = r#"{"port": 8080}"#;
        let result = parse_config(input);
        assert!(result.is_err());
    }
}

2.3 批量生成整个模块的测试

$ codex "扫描 src/lib.rs，为每个 pub fn 生成 #[cfg(test)] 测试模块：
- 每个函数至少包含：正常输入、空值/零值、边界值、错误路径四个用例
- 错误路径使用 assert!(result.is_err()) 或 matches!(err, MyError::...)
- 对于返回 Result 的函数，同时测试 Ok 和 Err 变体
- 测试函数命名：test_{function_name}_{scenario}"

2.4 属性测试（Property Testing）

$ codex "为 serialize_and_deserialize 函数添加 proptest 属性测试，
验证任意合法输入经过序列化再反序列化后与原值相等（round-trip property）"

3. 修复 Clippy 错误

Clippy 是 Rust 官方的 lint 工具，内置超过 700 条代码质量规则。Codex CLI 理解所有常见的 Clippy lint，可以批量修复警告，同时保持函数的原有行为不变。

3.1 将 Clippy 输出传给 Codex

# 第一步：收集 Clippy 警告
$ cargo clippy 2&1 | head -60

# 第二步：将输出粘贴到 Codex
$ codex "修复以下 Clippy 警告，保持函数行为不变：[粘贴输出]"

# 或者直接用管道（交互模式）
$ cargo clippy 2&1 | codex "修复这些 Clippy 警告"

3.2 常见 Clippy Lint 与 Codex 修复提示

3.3 批量修复整个仓库

$ codex "运行 cargo clippy -- -D warnings，修复所有警告直到 clippy 零输出"

4. 所有权与借用错误修复

Rust 的借用检查器是新手最大的障碍。Codex CLI 能够解读 rustc 的错误输出，结合代码上下文推断最合适的修复方式——是添加引用、引入 Clone，还是使用 RefCell/Mutex 实现内部可变性。

4.1 修复借用错误的通用提示词

$ codex "修复这段 Rust 代码的借用检查器错误，解释原因：
[粘贴 rustc 错误输出和相关代码]"

4.2 常见所有权错误与修复策略

Move 错误（值被移动后再次使用）

// 错误：value moved here
let s = String::from("hello");
process(s);       // s 被 move 进函数
println!("{}", s); // error: value borrowed here after move

// Codex 修复方案一：传引用
process(&s);
println!("{}", s); // OK

// Codex 修复方案二：Clone（仅在必要时）
process(s.clone());
println!("{}", s); // OK

多重可变借用

// 错误：cannot borrow as mutable more than once
let mut v = vec![1, 2, 3];
let first = &mut v[0];
v.push(4); // error: second mutable borrow

// Codex 修复：缩短借用作用域
{
    let first = &mut v[0];
    *first = 10;
} // first 在此处释放
v.push(4); // OK

4.3 生命周期标注

$ codex "为这个结构体添加正确的生命周期标注，
结构体持有对外部数据的引用：
[粘贴结构体定义和 rustc 错误]"

// Codex 生成的带生命周期标注的结构体示例
struct Parser<'a> {
    input: &'a str,
    cursor: usize,
}

impl<'a> Parser<'a> {
    fn new(input: &'a str) -> Self {
        Parser { input, cursor: 0 }
    }

    fn peek(&self) -> Option<&'a str> {
        self.input.get(self.cursor..)
    }
}

5. 异步 Rust（Tokio）

将同步代码迁移到异步是 Rust 项目中最常见的重构任务之一。Codex CLI 理解 async/await 语法、Tokio 运行时配置和 Future trait，可以自动完成迁移并添加对应的异步测试。

5.1 同步转异步提示词

$ codex "将这个同步 HTTP 客户端改为使用 reqwest 的异步版本，
函数签名改为 async fn，添加适当的 .await 调用"

$ codex "将 src/db.rs 中所有数据库操作改为使用 sqlx 的异步接口，
保持现有错误处理逻辑不变"

5.2 AGENTS.md 中配置 Tokio

## 异步运行时
- 使用 Tokio 作为异步运行时（tokio = { features = ["full"] }）
- main 函数使用 #[tokio::main] 属性
- 测试使用 #[tokio::test]
- 避免在异步上下文中使用 std::thread::sleep，改用 tokio::time::sleep

5.3 异步测试示例

#[tokio::test]
async fn test_fetch_user() {
    let client = UserClient::new("http://test-server");
    let user = client.fetch(42).await.unwrap();
    assert_eq!(user.id, 42);
}

#[tokio::test]
async fn test_concurrent_requests() {
    let client = UserClient::new("http://test-server");
    let (user1, user2) = tokio::join!(
        client.fetch(1),
        client.fetch(2)
    );
    assert!(user1.is_ok());
    assert!(user2.is_ok());
}

5.4 超时和取消

$ codex "为所有外部 HTTP 调用添加 tokio::time::timeout，
超时时间从配置读取，超时返回自定义的 TimeoutError"

6. 错误处理现代化（thiserror / anyhow）

Rust 早期代码常用 Box<dyn Error> 或手写 impl std::error::Error，这在大型项目中难以维护。Codex CLI 可以将这类代码迁移到现代错误处理模式：库代码用 thiserror，应用代码用 anyhow。

6.1 迁移提示词

$ codex "用 thiserror 重写这个 Error 枚举，添加合适的 Display 实现：
[粘贴现有 Error 枚举]"

$ codex "将 src/main.rs 中的错误处理改为使用 anyhow::Result，
保留所有错误上下文信息（.context()）"

6.2 迁移前后对比

迁移前（手写实现）：

use std::fmt;

#[derive(Debug)]
pub enum AppError {
    IoError(std::io::Error),
    ParseError(String),
    NotFound,
}

impl fmt::Display for AppError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            AppError::IoError(e) => write!(f, "IO error: {}", e),
            AppError::ParseError(s) => write!(f, "Parse error: {}", s),
            AppError::NotFound => write!(f, "Not found"),
        }
    }
}

impl std::error::Error for AppError {}

迁移后（thiserror）：

use thiserror::Error;

#[derive(Debug, Error)]
pub enum AppError {
    #[error("IO error: {0}")]
    IoError(#[from] std::io::Error),
    #[error("Parse error: {0}")]
    ParseError(String),
    #[error("Not found")]
    NotFound,
}

6.3 应用层使用 anyhow

use anyhow::{Context, Result};

fn load_config(path: &str) -> Result<Config> {
    let content = std::fs::read_to_string(path)
        .with_context(|| format!("Failed to read config file: {}", path))?;
    let config: Config = serde_json::from_str(&content)
        .context("Failed to parse config JSON")?;
    Ok(config)
}

7. WebAssembly（wasm-bindgen）

Rust 是 WebAssembly 生态最成熟的语言之一。Codex CLI 可以为现有 Rust 库生成 wasm-bindgen 绑定，让 JavaScript 直接调用 Rust 函数，无需手写胶水代码。

7.1 生成 wasm-bindgen 绑定

$ codex "为这个 Rust 库生成 wasm-bindgen 接口，
让 JavaScript 可以调用 parse_csv 函数，
返回值转换为 JavaScript Array 对象"

7.2 wasm-bindgen 属性用法

use wasm_bindgen::prelude::*;

// 导出到 JavaScript
#[wasm_bindgen]
pub fn parse_csv(input: &str) -> Result<JsValue, JsValue> {
    let records = csv_parser::parse(input)
        .map_err(|e| JsValue::from_str(&e.to_string()))?;
    Ok(serde_wasm_bindgen::to_value(&records)?)
}

// 导出结构体
#[wasm_bindgen]
pub struct CsvParser {
    delimiter: char,
}

#[wasm_bindgen]
impl CsvParser {
    #[wasm_bindgen(constructor)]
    pub fn new(delimiter: char) -> Self {
        CsvParser { delimiter }
    }

    pub fn parse(&self, input: &str) -> Result<JsValue, JsValue> {
        // 实现...
        todo!()
    }
}

7.3 构建命令

# 安装 wasm-pack
$ cargo install wasm-pack

# 构建用于 Web 的 WASM 包
$ wasm-pack build --target web --out-dir pkg

# 构建用于 Node.js 的包
$ wasm-pack build --target nodejs --out-dir pkg-node

7.4 请 Codex 生成 TypeScript 类型声明

$ codex "基于 wasm-bindgen 生成的 .d.ts 文件，
为 parse_csv 和 CsvParser 补充详细的 JSDoc 注释和类型说明"

8. GitHub Actions CI for Rust

完整的 Rust CI 流水线需要覆盖编译检查、测试、格式化、Clippy 和安全审计。Codex CLI 可以生成针对 Rust 优化的 GitHub Actions workflow，包含 Swatinem/rust-cache 缓存加速。

8.1 生成 CI 配置的提示词

$ codex "生成一个 GitHub Actions workflow for Rust 项目：
- 在 push 和 pull_request 时触发
- 运行 cargo build、cargo test、cargo clippy、cargo fmt --check
- 使用 rust-cache 缓存依赖
- 添加 cargo audit 安全检查 job"

8.2 完整 workflow 示例

name: Rust CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          components: rustfmt, clippy
      - uses: Swatinem/rust-cache@v2
      - run: cargo build --verbose
      - run: cargo test --verbose
      - run: cargo clippy -- -D warnings
      - run: cargo fmt --check

  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - run: cargo install cargo-audit
      - run: cargo audit

8.3 Matrix 测试多个 Rust 版本

$ codex "修改 CI workflow，用 matrix 策略同时测试 stable 和 beta 工具链，
并添加 MSRV（最低支持 Rust 版本）检查"

strategy:
  matrix:
    rust: [stable, beta, "1.70"]  # 1.70 = MSRV
steps:
  - uses: dtolnay/rust-toolchain@${{ matrix.rust }}

9. 常见问题

Codex 能理解 Rust 的所有权系统吗？

能。Codex CLI 深度理解 Rust 的所有权、借用和生命周期模型，可以精确诊断借用检查器报告的错误，建议使用引用、克隆、RefCell 或 Arc 等合适的解决方案。在提示词中粘贴完整的 rustc 错误输出（包括错误码如 E0505）可获得最准确的修复建议。对于复杂的生命周期问题，可以附上函数调用链，帮助 Codex 理解数据流向。

如何让 Codex 生成符合 Rust 惯例（idiomatic）的代码？

在 AGENTS.md 中明确约定：使用 ? 操作符传播错误、用 thiserror 定义自定义 Error 枚举、避免不必要的 clone()、优先使用迭代器链而非手动 for 循环、用 impl Trait 替代 Box<dyn Trait>。将 cargo clippy -- -D warnings 加入允许命令列表后，Codex 每次修改都会自动验证，持续输出惯用代码。

Codex 支持 Rust 宏（macro）编写吗？

支持。Codex CLI 可以编写声明式宏（macro_rules!）和过程宏（proc macro），理解 derive 宏、属性宏和函数宏的区别。对于复杂的过程宏，建议在提示词中提供宏的预期展开示例，帮助 Codex 理解语义边界。可以用 cargo expand（需安装 cargo-expand）验证宏展开结果，再将输出反馈给 Codex 进行修正。

处理 unsafe Rust 时 Codex 表现如何？

Codex CLI 在处理 unsafe 代码时会保持谨慎，优先建议安全替代方案。对于确实需要 unsafe 的场景（如 FFI 绑定、底层内存操作），Codex 会添加 // Safety: 注释说明不变量（invariant），并建议使用 Miri 工具进行验证。在 AGENTS.md 中明确 unsafe 使用策略（例如仅限特定模块），可以让 Codex 在其他地方始终寻求安全替代。