AI 辅助设计 Rust 公共 API：让模型评审接口的易用性和一致性
一、API 设计这件事，没有标准答案
设计公共 API 大概是编程里最难教的一项能力。算法可以学，语法可以查，但一个函数的参数顺序怎么排、错误类型能不能统一、命名风格是否和整个生态保持一致——这些问题每个开发者都有自己的偏好，而且很难讲清楚"为什么你的设计不好"。
我刚学 Rust 半年左右的时候，写过一个文本分块库。暴露了一组函数用来把长文章切成小块，但不同函数的参数命名完全不统一——有的叫 size，有的叫 max_len，有的传引用有的直接 move。后来一个用过这个库的朋友很委婉地说："你这些函数的调用方式，我需要每次都翻文档才能想起来。"
这个反馈让我意识到，API 的一致性和易用性不能只靠"感觉"——尤其是对于自学的开发者，缺少团队 review 的环境，更容易写出只有自己能看懂的接口。AI 工具的一个好用场景出现了：把 API 定义交给大模型，让它从多个维度评审你的接口设计。
二、让 AI 从四个维度评审你的 API
AI 做不了性能判断，也不了解你项目的内部实现细节。但它擅长一件事：在给定的规范框架下，识别出明显的不一致和"反模式"。我把评审的标准压缩成四个维度：
- 一致性：命名风格、参数顺序、返回值类型在整个模块内是否统一。
- 易用性：用户能不能不看文档就猜出参数含义？常见错误有没有被类型系统兜住？
- 错误处理：错误类型是否恰当？是可恢复错误（Result）还是不可恢复（panic!）？
- 文档覆盖：每个公开函数是否有清晰的代码示例？public API 是否全部有注释？
这四点的评审流程图如下。每次你提交一组 API 定义，AI 就按这个维度逐项检查，输出一个结构化的评审报告。
flowchart LR
A["开发者提交 Rust API\\n函数签名 + 类型定义"] –> B["AI 模型接收 API 描述"]
B –> C1["维度1: 一致性检查\\n• 命名风格(naming convention)\\n• 参数顺序是否一致\\n• 返回类型风格统一性"]
B –> C2["维度2: 易用性评估\\n• 参数名是否自解释\\n• 布尔参数是否应换枚举\\n• 默认值是否合理"]
B –> C3["维度3: 错误处理\\n• Result vs panic 使用恰当?\\n• 错误类型粒度是否合适?\\n• 是否过度使用 unwrap"]
B –> C4["维度4: 文档覆盖\\n• 公共 API 是否有 doc 注释?\\n• 注释中有可运行示例?\\n• 示例是否通过 doc test"]
C1 –> D["汇总报告\\n列出发现的问题 + 改进建议"]
C2 –> D
C3 –> D
C4 –> D
D –> E["开发者逐条评估,\\n接受或拒绝建议"]
三、一个实用的 Prompt 模板和评审示例
下面这个 Prompt 模板是我反复调整后稳定下来的版本。它的核心是把"评审职责"和"反馈格式"说清楚，避免 AI 输出一堆"这个接口不错"的废话。
// ==========================================
// 待评审的 API 定义 (提交给 AI 的代码)
// ==========================================
/// 文本分块器 — 将长文本按策略切分成片段
pub struct TextChunker {
chunk_size: usize, // 每个片段的最大字符数
overlap: usize, // 相邻片段的重叠字符数
}
impl TextChunker {
/// 创建分块器 — 普通构造函数
pub fn new(chunk_size: usize, overlap: usize) -> Self {
assert!(overlap < chunk_size, "重叠量不能超过分块大小");
TextChunker { chunk_size, overlap }
}
/// 创建默认 1000 字符、重叠 200 的分块器
pub fn default() -> Self {
TextChunker::new(1000, 200)
}
/// 切分文本 — 返回片段列表
/// 参数顺序: 先文本, 再策略
pub fn chunk(&self, text: &str) -> Vec<String> {
let chars: Vec<char> = text.chars().collect();
let mut chunks = Vec::new();
let mut start = 0;
while start < chars.len() {
let end = (start + self.chunk_size).min(chars.len());
chunks.push(chars[start..end].iter().collect());
start = self.chunk_size – self.overlap + start;
}
chunks
}
}
提交给 AI 时使用的 Prompt：
你是一位 Rust API 设计审查专家。请从以下四个维度评审上述 API：
1. 一致性：命名风格、参数顺序、返回类型在全模块中是否统一？
2. 易用性：用户能否不经文档理解每个参数？布尔参数是否应该改为枚举？
3. 错误处理：使用了 panic、assert 还是 Result？是否应该在库中使用 panic？
4. 文档覆盖：公开 API 的 Doc 注释中是否包含可编译运行的示例？
请用以下结构化格式输出：
– 问题类型: [一致性/易用性/错误处理/文档]
– 位置: 函数/结构体名称
– 严重程度: 高/中/低
– 问题描述:
– 改进建议:
不要输出设计良好的部分，只列出需要改进的地方。
AI 给出的典型反馈会是：
- 高严重度：TextChunker 的 new 函数对 overlap >= chunk_size 使用了 assert! 做 panic，作为库函数应该返回 Result，让调用方能优雅处理配置错误。
- 中严重度：default() 返回 Self 和 new() 返回 Self 共存在同一类型上，且 default() 不是 Default trait 的实现，用户会困惑该用哪个。
- 中严重度：chunk() 的公开文档缺少可运行的 /// # Examples 代码块，cargo doc 和 cargo test –doc 都无法验证。
这几条反馈每一条都实用。第一条关于 panic 和 Result 的取舍尤其重要——很多人写库函数时惯性地用 unwrap() 和 assert!，但在错误可以被调用方处理的场景下，返回 Result 才是正确的选择。
四、AI 评审做不到的事
第一，性能评估。AI 可以说"这个函数的时间复杂度看起来是 O(n)"，但它看不到被调用的那些库函数的内部实现。如果你的 chunk 函数里实际上调了一个复杂的内存分配逻辑，AI 根本不知道。
第二，并发安全。Rust 的 Send + Sync trait 是在编译器层面保证的，AI 只能从函数签名上猜测某个类型实现了什么 trait，无法模拟多线程调用的实际行为。如果 API 设计隐含了数据竞争的可能，光看函数签名是发现不了的。
第三，生态一致性。Rust 生态里有很多"约定"——比如构造者模式用 with_xxx 返回 Self、错误类型应该实现 std::error::Error trait——这些约定 AI 知道，但它不一定能把你的设计放在整个标准库和主流 crate 的上下文里比较。
所以 AI 评审的正确使用方式是：把它当第一位 reviewer，过滤掉明显的命名不一致、panic 滥用、文档缺失；然后用 cargo check、cargo clippy、cargo test –doc 这一套 Rust 自带工具做机械检查；最后交给真正的人类 reviewer 来评估 API 的结构设计是否合理。
五、总结
API 设计的评审很难自动化——它不像代码格式可以用 rustfmt 一键修好，也不像逻辑错误可以用测试覆盖。AI 在这里的价值不是"替代人的判断"，而是"降低明显问题的漏过率"。不一致的参数名、滥用的 panic、缺失的文档——这些是 AI 在几秒内就能扫出来、但你改完后可能忘了回头检查的东西。
对于没有团队 review 环境的自学开发者来说，把 AI 评审当成 CI 流水线里的一个检查步骤，是低成本且高回报的做法。把 Prompt 固化下来，每次暴露新 API 之前跑一遍，久而久之，你会发现自己的接口设计变得越来越"像 Rust 风格"。
