Cargo 自定义子命令:把 AI 工具的功能拆成 cargo xxx 一键调用
一、Cargo 子命令的工作原理
Cargo 的子命令机制设计得极其简单:只要你的系统 PATH 里有一个叫 cargo-xxx 的可执行文件,就能用 cargo xxx 调用它。
flowchart LR
A[用户输入: cargo review] --> B{cargo 查找}
B -->|内置命令| C[执行内置逻辑]
B -->|非内置| D[搜索 PATH 中的 cargo-review]
D -->|找到| E[执行 cargo-review]
D -->|没找到| F[提示: no such subcommand]
E --> G[cargo-review 接收原样参数]
G --> H[可以解析 Cargo.toml / 调用 cargo metadata]
style E fill:#6bcb77,stroke:#333
style F fill:#ff6b6b,stroke:#333
具体细节:
cargo review→ 找cargo-review可执行文件cargo review --fix→cargo-review收到参数--fixcargo review ./src/→cargo-review收到参数./src/- 内置命令(
build、test、run等)优先级高于自定义子命令
一个真实踩坑
我第一次做 cargo review 时,装了工具,在项目目录里敲 cargo review,Cargo 却告诉我"no such subcommand"。排查了半小时,发现是可执行文件叫 cargo_review(用下划线),而 Cargo 只认连字符 cargo-review。Rust 编译器会自动把 crate 名字里的连字符变成下划线,但操作系统找的是连字符版本的文件名。这个细节不大,但很容易踩到。
二、实现第一个 AI 代码审查子命令:cargo-review
先从一个完整的例子开始。我们要做一个 cargo review 命令,它会:
- 读取当前项目的
Cargo.toml获取项目信息 - 收集待审查的 Rust 源文件
- 调用 AI API 做代码审查
- 输出审查报告
// ========== cargo-review 主程序 ==========
// 编译后的可执行文件命名为 cargo-review,放到 PATH 中
use clap::Parser;
use std::path::PathBuf;
use std::process::Command;
/// cargo review —— AI 代码审查工具
///
/// 用法: cargo review [OPTIONS] [PATH]
#[derive(Parser, Debug)]
#[command(name = "cargo review", about = "AI 代码审查工具")]
struct Cli {
/// 要审查的文件或目录(默认为当前目录下的 src/)
#[arg(default_value = ".")]
path: PathBuf,
/// 自动修复简单问题
#[arg(long, short = 'f')]
fix: bool,
/// 审查严格程度: loose | normal | strict
#[arg(long, default_value = "normal")]
level: String,
/// 输出格式: text | json | markdown
#[arg(long, default_value = "text")]
output: String,
}
fn main() -> Result<(), String> {
let cli = Cli::parse();
// 1️⃣ 获取 Rust 项目根目录(向上寻找 Cargo.toml)
let project_root = find_project_root(&cli.path)
.map_err(|e| format!("找不到 Cargo.toml: {e}"))?;
println!("📁 项目目录: {}", project_root.display());
// 2️⃣ 收集要审查的文件
let target = if cli.path.is_dir() {
cli.path.join("src")
} else {
cli.path.clone()
};
let rust_files = collect_rust_files(&target)?;
if rust_files.is_empty() {
return Err("没有找到 Rust 源文件".to_string());
}
println!("📄 找到 {} 个 Rust 文件待审查", rust_files.len());
// 3️⃣ 逐文件审查
let mut report = String::new();
for file in &rust_files {
let content = std::fs::read_to_string(file)
.map_err(|e| format!("读取 {} 失败: {e}", file.display()))?;
println!("🔍 正在审查: {}", file.display());
let review = ai_review_code(
&content,
&file.display().to_string(),
&cli.level,
)?;
report.push_str(&review);
}
// 4️⃣ 输出报告
match cli.output.as_str() {
"json" => println!("{}", format_as_json(&report)),
"markdown" => {
let md_path = project_root.join("review-report.md");
std::fs::write(&md_path, &report)
.map_err(|e| format!("写入报告失败: {e}"))?;
println!("📝 报告已保存到: {}", md_path.display());
}
_ => println!("{}", report), // 默认文本输出
}
// 5️⃣ 可选:自动修复
if cli.fix {
println!("🔧 自动修复模式已启用(此功能待实现)");
}
Ok(())
}
找到项目根目录
这是 cargo 子命令最重要的能力——自动识别当前 Cargo 项目:
/// 向上遍历目录树,找到包含 Cargo.toml 的目录
fn find_project_root(start: &PathBuf) -> Result<PathBuf, String> {
let mut current = if start.is_file() {
start.parent()
.unwrap_or(start)
.to_path_buf()
} else {
start.clone()
};
// 一直向上找,直到找到 Cargo.toml 或到达文件系统根
loop {
let cargo_toml = current.join("Cargo.toml");
if cargo_toml.exists() {
return Ok(current);
}
match current.parent() {
Some(parent) => current = parent.to_path_buf(),
None => break,
}
}
Err("未找到 Cargo.toml,请确保在 Rust 项目内运行".to_string())
}
/// 收集指定目录下所有 .rs 文件
fn collect_rust_files(dir: &PathBuf) -> Result<Vec<PathBuf>, String> {
if !dir.exists() {
return Err(format!("目录不存在: {}", dir.display()));
}
let mut files = Vec::new();
// 使用 walkdir 遍历目录
for entry in walkdir::WalkDir::new(dir)
.into_iter()
.filter_map(|e| e.ok())
{
let path = entry.path();
if path.extension().map_or(false, |ext| ext == "rs") {
files.push(path.to_path_buf());
}
}
Ok(files)
}
调用 AI 做代码审查
/// AI 代码审查 —— 调用 LLM API
fn ai_review_code(code: &str, filename: &str, level: &str) -> Result<String, String> {
// 构建审查提示词
let strictness = match level {
"loose" => "只关注明显的逻辑错误和安全漏洞",
"strict" => "严格审查:包括命名规范、代码风格、潜在性能问题",
_ => "常规审查:关注正确性、安全性和可读性",
};
let prompt = format!(
r#"你是一个 Rust 代码审查助手。{strictness}。
请审查以下文件 `{filename}`,按照以下格式输出:
### 🔴 严重问题
(影响正确性或安全性的问题)
### 🟡 改进建议
(代码风格、性能、可读性方面的建议)
### 💡 学习建议
(如果发现可以优化的地方,给出 Rust 最佳实践说明)
```rust
{code}
```"#,
);
// 调用 AI API(这里用模拟实现,实际替换成你的 API 调用)
call_ai_api(&prompt)
}
fn call_ai_api(prompt: &str) -> Result<String, String> {
// 实际项目中替换为:
// let client = reqwest::blocking::Client::new();
// let resp = client.post("https://api.openai.com/v1/...")
// .json(&request_body)
// .send()?;
// let body = resp.text()?;
// 模拟返回
Ok(format!(
r#"### 🔴 严重问题
暂无发现严重问题。
### 🟡 改进建议
- 建议添加更多文档注释
### 💡 学习建议
- 可以使用 clippy 检查 Rust 代码风格
---
(共审查 {} 行代码)
"#,
prompt.lines().count()
))
}
格式化输出
/// 将报告转为 JSON 格式
fn format_as_json(report: &str) -> String {
// 简化实现 —— 实际应该解析报告结构
format!(r#"{{"report": "{}"}}"#, report.replace('\n', "\\n"))
}
三、安装和使用:cargo install 一键搞定
编译并安装到系统 PATH 中最方便的方式就是 cargo install:
# Cargo.toml
[package]
name = "cargo-review"
version = "0.1.0"
edition = "2021"
description = "AI 代码审查工具"
[dependencies]
clap = { version = "4", features = ["derive"] }
walkdir = "2"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
[[bin]]
name = "cargo-review" # ← 关键:可执行文件叫 cargo-review
path = "src/main.rs"
安装步骤:
# 在项目目录下
cargo install --path .
# 安装完成后,cargo-review 会在 ~/.cargo/bin/ 下
# 确保这个目录在 PATH 中(rustup 通常已经配好了)
# 使用
cargo review # 审查当前项目
cargo review ./src/main.rs # 审查单个文件
cargo review --level strict # 严格审查模式
cargo review --output markdown # 输出 Markdown 报告
cargo review --fix # 审查并修复
生产环境实战经验
cargo install --path . 有个细节:如果你改完代码想更新安装版本,直接重新 cargo install --path . 不会重新编译,除非加 --force。我第一次更新时改了参数结构,装完还是旧的。后来嫌麻烦,改成了在 CI 里 cargo install --path . --force --debug,开发阶段用 debug 构建,速度快。但注意 debug 构建性能差很多,分发给别人还是要用 release 构建。
四、更完整的体系:cargo ai 命令家族
如果把多个 AI 工具组织在一起,可以设计成 cargo ai 命令家族:
flowchart TD
A[cargo ai] --> B[子命令]
B --> C[review: 代码审查]
B --> D[gen: 生成测试代码]
B --> E[doc: 生成文档注释]
B --> F[explain: 解释代码逻辑]
B --> G[refactor: 重构建议]
C --> C1[cargo review 已有]
D --> D1[cargo ai-gen 待实现]
E --> E1[cargo ai-doc 待实现]
F --> F1[cargo ai-explain 待实现]
G --> G1[cargo ai-refactor 待实现]
实现 cargo ai 作为入口:
// ========== cargo-ai 主程序 ==========
// 用法: cargo ai <SUBCOMMAND>
use clap::{Parser, Subcommand};
#[derive(Parser)]
#[command(name = "cargo ai", about = "AI 辅助开发工具集")]
struct Cli {
#[command(subcommand)]
command: Commands,
}
#[derive(Subcommand)]
enum Commands {
/// AI 代码审查
Review {
#[arg(default_value = ".")]
path: PathBuf,
#[arg(long, default_value = "normal")]
level: String,
},
/// AI 生成测试代码
GenTest {
#[arg(default_value = ".")]
path: PathBuf,
},
/// AI 生成文档注释
GenDoc {
#[arg(default_value = ".")]
path: PathBuf,
},
/// AI 解释代码逻辑
Explain {
file: PathBuf,
/// 解释的详细程度: brief | normal | detailed
#[arg(long, default_value = "normal")]
detail: String,
},
}
fn main() -> Result<(), String> {
let cli = Cli::parse();
match cli.command {
Commands::Review { path, level } => {
// 委托给 review 逻辑
run_review(path, &level)
}
Commands::GenTest { path } => {
println!("🔧 生成测试功能开发中... path={}", path.display());
Ok(())
}
Commands::GenDoc { path } => {
println!("🔧 文档生成功能开发中... path={}", path.display());
Ok(())
}
Commands::Explain { file, detail } => {
run_explain(file, &detail)
}
}
}
使用示例:
# 安装后,以下命令都可用
cargo ai review # 代码审查
cargo ai review --level strict # 严格审查
cargo ai gen-test --path ./src/ # 生成测试
cargo ai gen-doc # 生成文档
cargo ai explain ./src/main.rs --detail detailed # 解释代码
命名冲突的边界案例
设计 cargo ai 命令家族时,需要考虑命名冲突。如果其他人也写了一个 cargo-ai,并且 bin 名字也注册成 cargo-ai,两个工具安装到同一个 PATH 就冲突了。目前 Cargo 没有命名空间机制,只能靠文档说明"如果你是 cargo-ai 作者,请在文档里声明"。团队内部用的话风险不大,但如果发布到 crates.io,建议调研一下是否有同名工具。
我在一次实际开发中,cargo review --fix 不小心覆盖了一个正在编辑的文件,因为没加 --dry-run 预览。后来加了一个 --confirm 参数,默认预览、人工确认后再修改。
五、总结
这篇文章梳理了 Cargo 自定义子命令的三个要点:
约定大于配置:只要可执行文件以
cargo-开头,放进 PATH,就能用cargo xxx调用。这是 Unix 哲学在 Rust 工具链中的体现。clap 做参数解析:
cargo xxx后面的所有参数都会原样传给cargo-xxx,用 clap 的#[derive(Parser)]可以像普通 CLI 工具一样处理。cargo install 分发:
cargo install --path .自动编译并安装到~/.cargo/bin/,用户一行命令就能用上。配合 crates.io 发布,别人cargo install cargo-review就能用。
作为独立开发者,Cargo 的设计让我学会了一件事:好工具的设计应该让人"猜"得出来。不需要读文档,只要知道 cargo test 存在,自然就能想到 cargo review 也应该是类似的工作方式。
如果你也在写 Rust 工具,强烈建议做成 cargo 子命令。不仅能复用 Cargo 的项目上下文(自动找 Cargo.toml),还能让用户零学习成本上手。
有问题欢迎评论区交流!
1984



被折叠的 条评论
为什么被折叠?



