AI 辅助设计 Rust 公共 API让模型评审接口的易用性和一致性一、API 设计这件事没有标准答案设计公共 API 大概是编程里最难教的一项能力。算法可以学语法可以查但一个函数的参数顺序怎么排、错误类型能不能统一、命名风格是否和整个生态保持一致——这些问题每个开发者都有自己的偏好而且很难讲清楚为什么你的设计不好。我刚学 Rust 半年左右的时候写过一个文本分块库。暴露了一组函数用来把长文章切成小块但不同函数的参数命名完全不统一——有的叫size有的叫max_len有的传引用有的直接 move。后来一个用过这个库的朋友很委婉地说你这些函数的调用方式我需要每次都翻文档才能想起来。这个反馈让我意识到API 的一致性和易用性不能只靠感觉——尤其是对于自学的开发者缺少团队 review 的环境更容易写出只有自己能看懂的接口。AI 工具的一个好用场景出现了把 API 定义交给大模型让它从多个维度评审你的接口设计。二、让 AI 从四个维度评审你的 APIAI 做不了性能判断也不了解你项目的内部实现细节。但它擅长一件事在给定的规范框架下识别出明显的不一致和反模式。我把评审的标准压缩成四个维度一致性命名风格、参数顺序、返回值类型在整个模块内是否统一。易用性用户能不能不看文档就猜出参数含义常见错误有没有被类型系统兜住错误处理错误类型是否恰当是可恢复错误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) - VecString { let chars: Vecchar 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()不是Defaulttrait 的实现用户会困惑该用哪个。中严重度chunk()的公开文档缺少可运行的/// # Examples代码块cargo doc和cargo test --doc都无法验证。这几条反馈每一条都实用。第一条关于panic和Result的取舍尤其重要——很多人写库函数时惯性地用unwrap()和assert!但在错误可以被调用方处理的场景下返回Result才是正确的选择。四、AI 评审做不到的事第一性能评估。AI 可以说这个函数的时间复杂度看起来是 O(n)但它看不到被调用的那些库函数的内部实现。如果你的chunk函数里实际上调了一个复杂的内存分配逻辑AI 根本不知道。第二并发安全。Rust 的SendSynctrait 是在编译器层面保证的AI 只能从函数签名上猜测某个类型实现了什么 trait无法模拟多线程调用的实际行为。如果 API 设计隐含了数据竞争的可能光看函数签名是发现不了的。第三生态一致性。Rust 生态里有很多约定——比如构造者模式用with_xxx返回Self、错误类型应该实现std::error::Errortrait——这些约定 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 风格。