Rust语言 – 接口设计的建议之显而易见(Obvious)
- Rust API 指南 GitHub:https://github.com/rust-lang/api-guidelines
- Rust API 指南 中文:https://rust-chinese-translation.github.io/api-guidelines/
- Rust API 指南:https://rust-lang.github.io/api-guidelines/
显而易见(Obvious)
文档与类型系统
- 用户可能不会完全理解接口的所有规则和限制
- 重要:让用户容易理解接口,并难以用错
文档
- 接口透明化的第一步:写出好的文档
- 清楚的记录:
- 可能出现意外的情况,或它依赖于用户执行超出类型签名要求的操作
- 例:panic、返回错误、unsafe 函数…
如果你的代码可能会发生恐慌 panic,要把这一点记录到你的文档里,并且要记录在什么情况下,它会发生恐慌。
如果你的代码要返回错误,要把这一点记录到你的文档里,并且要记录在什么情况下,它会返回错误。
unsafe 函数,要在文档里写明需要满足什么条件才能安全的调用这个函数。
例子一:
// Panic(恐慌)是这两种情况的一个很好的例子:如果代码可能发生 Panic,请在文档中明确说明这一点,以及可能导致 Panic 的情况。 // 同样,如果代码可能返回错误,请记录它返回错误的情况。 // 对于 unsafe 的函数,请记录调用者必须保证什么条件,才能确保调用时安全的。 /// 除法运算,返回两个数的结果。 /// /// # Panics /// /// 如果除数为零,该函数会发生 panic。 /// /// # 示例 /// /// ``` /// let result = divide(10, 2); /// assert_eq!(result, 5); /// ``` pub fn divide(dividend: i32, divisor: i32) -> i32 { // 实现代码 ... }
- 在 crate 或 module 级,包括端到端的用例
- 不是针对特定类型或方法,了解所有内容如何组合到一起
- 对接口的整体结构有一个相对清晰的理解
- 让开发者快速了解到各方法和类型的功能,以及在哪使用
- 提供定制化使用的起点
- 通过复制粘贴,结合需求进行修改
例子:查看标准库等相关文档
- 组织好文档
- 利用模块来将语义相关的项进行分组
- 利用内部文档链接将这些项相互连接起来
- 考虑使用
#[doc(hidden)]
标记那些不打算公开但出于遗留原因需要的接口部分,避免弄乱文档
例子二:
/// 一个简单的模块,包含一些用于内部使用的函数和结构体。 pub mod internal { /// 一个用于内部计算的辅助函数。 #[doc(hidden)] pub fn internal_helper() { // 内部计算的具体实现 ... } /// 一个仅用于内部使用的结构体。 #[doc(hidden)] pug struct InternalStruct { // 结构体的字段和方法 ... } } /// 一个公共接口函数,调用了内部的辅助函数。 pub fn public_function() { // 调用内部辅助函数 internal::internal_helper(); } /// 一个公共结构体,包含一些公共字段和方法。
- 尽可能的丰富文档
- 可以链接到解释这些内容的外部资源:
- 相关的规范文件(RFC)、博客、白皮书 …
- 使用
#[doc(cfg(..))]
突出显示仅在特定配置下可用的项- 用户能快速了解为什么在文档中列出的某个方法不可用
- 使用
#[doc(alias = "...")]
可让用户以其他名称搜索到类型和方法 - 在顶层文档中,引导用户了解常用的模块、Trait、类型、方法
- 可以链接到解释这些内容的外部资源:
例子三:
//! 这是一个用于处理图像的库。 //! //! 这个库提供了一些常用的图像处理功能,例如: //! - 读取和保存不同格式的图像文件 [`Image::load`] [`Image::save`] //! - 调整图像的大小、旋转和裁剪 [`Image::resize`] [`Image::rotate`] [`Image::crop`] //! - 应用不同的滤镜和效果 [`Filter`] [`Effect`] //! //! 如果您想了解更多关于图像处理的原理和算法,您可以参考以下的资源: //! - [数字图像处理](https://book.douban.com/subject/5345798/),一个经典的教科书,介绍了图像处理的基本概念和方法。 //! - [Learn OpenCV](https://learnopencv.com/),一个网站,提供了很多用OpenCV实现图像处理功能的教程和示例代码。 //! - [Awesome Computer Vision](https://github.com/jbhuang0604/awesome-computer-vision),一个GitHub仓库,收集计算机视觉资源。 /// 一个表示图像的结构体 #[derive(Debug, Clone)] pub struct Image { // ... } impl Image { /// 从指定的路径加载一个图像文件 /// /// 支持的格式有:PNG、JPEG、GIF、BMP 等 /// /// # 参数 /// /// - `path`: 图像文件的路径 /// /// # 返回值 /// /// 如果成功,返回一个 [`Image`] 实例;如果失败,返回一个 [`Error`]。 /// /// # 示例 /// /// ```no_run /// use image::Image; /// /// let img = Image::load("test.png")?; /// ``` #[doc(alias = "读取")] #[doc(alias = "打开")] pub fn load<P: AsRef<Path>>(path: P) -> Result<Self, Error> { // ... } /// 将图像保存到指定的路径 /// /// 支持的格式有:PNG、JPEG、GIF、BMP 等 /// /// # 参数 /// }
例子四:
/// 一个只在启用了 `foo` 特性时才可用的结构体。 #[cfg(feature = "foo")] #[doc(cfg(feature = "foo"))] pub struct Foo; impl Foo { /// 一个只在启用了 `foo` 特性时才可用的方法。 #[cfg(feature = "foo")] #[doc(cfg(feature = "foo"))] pub fn bar(&self) { // ... } } fn main() { println!("Hello, world!"); }
类型系统
- 类型系统可确保:
- 接口明显
- 自我描述
- 难以被误用
- 语义化类型:
- 添加类型来表示值的意义(不仅仅适用基本类型)
例子五:
fn processDate(dryRun: bool, overwrite: bool, validate: bool) { // 处理数据的逻辑 } enum DryRun { Yes, No, } enum Overwrite { Yes, No, } enum Validate { Yes, No, } fn processData(dryRun: DryRun, overwrite: Overwrite, validate: Validate) { // 处理数据的逻辑 } processData(DryRun::Yes, Overwrite::No, Validate::Yes); fn main() { println!("Hello, world!"); }
- 使用”零大小“类型来表示关于类型实例的特定事实
例子六:
struct Grounded; struct Launched; // and so on enum Color { White, Black, } struct Kilograms(u32); struct Rocket<Stage = Grounded> { stage: std::marker::PhantomData<Stage>, } impl Default for Rocket<Grounded> { fn default() -> Self { Self { stage: Default::default() } } } impl Rocket<Grounded> { pub fn launch(self) -> Rocket<Launched> { Rocket { stage: Default::default(), } } } impl Rocket<Launched> { pub fn accelerate(&mut self) {} pub fn decelerate(&mut self) {} } impl<Stage> Rocket<Stage> { pub fn color(&self) -> Color { Color::White } pub fn weight(&self) -> Kilograms { Kilograms(0) } } fn main() { println!("Hello, world!"); }
#[must_use]
注解- 将其添加到类型、Trait 或函数中,如果用户的代码接收到该类型或 Trait 的元素,或调用了该函数,并且没有明确处理它,编译器将发出警告
例子七:
#[must_use] fn process_data(data: Data) -> Result<(), Error> { // 处理数据的逻辑 Ok(()) } // 在这个示例中,我们使用 #[must_use] 注解将 process_data 函数标记为必须使用期返回值。 // 如果用户在调用该函数后没有显式处理返回的 Result 类型,编译器将发出警告。 // 这有助于提醒用户在处理潜在的错误情况时要小心,并减少可能得错误。 fn main() { println!("Hello, world!"); }
评论前必须登录!
注册