Rust语言 - 接口设计的建议之显而易见(Obvious)

Rust语言 - 接口设计的建议之显而易见(Obvious)

显而易见(Obvious)

文档与类型系统

  • 用户可能不会完全理解接口的所有规则和限制
    • 重要:让用户容易理解接口,并难以用错

文档

  • 接口透明化的第一步:写出好的文档
  1. 清楚的记录:
    1. 可能出现意外的情况,或它依赖于用户执行超出类型签名要求的操作
    2. 例: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 { 
  // 实现代码 ...
}

  1. 在 crate 或 module 级,包括端到端的用例
    1. 不是针对特定类型或方法,了解所有内容如何组合到一起
    2. 对接口的整体结构有一个相对清晰的理解
      1. 让开发者快速了解到各方法和类型的功能,以及在哪使用
    3. 提供定制化使用的起点
      1. 通过复制粘贴,结合需求进行修改

例子:查看标准库等相关文档

  1. 组织好文档
    1. 利用模块来将语义相关的项进行分组
    2. 利用内部文档链接将这些项相互连接起来
    3. 考虑使用 #[doc(hidden)] 标记那些不打算公开但出于遗留原因需要的接口部分,避免弄乱文档

例子二:

/// 一个简单的模块,包含一些用于内部使用的函数和结构体。
pub mod internal {
  /// 一个用于内部计算的辅助函数。
  #[doc(hidden)]
  pub fn internal_helper() {
    // 内部计算的具体实现 ...
  }
  
  /// 一个仅用于内部使用的结构体。
  #[doc(hidden)]
  pug struct InternalStruct {
    // 结构体的字段和方法 ...
  }
}

/// 一个公共接口函数,调用了内部的辅助函数。
pub fn public_function() {
  // 调用内部辅助函数
  internal::internal_helper();
}

/// 一个公共结构体,包含一些公共字段和方法。

  1. 尽可能的丰富文档
    1. 可以链接到解释这些内容的外部资源:
      1. 相关的规范文件(RFC)、博客、白皮书 ...
    2. 使用 #[doc(cfg(..))] 突出显示仅在特定配置下可用的项
      1. 用户能快速了解为什么在文档中列出的某个方法不可用
    3. 使用 #[doc(alias = "...")] 可让用户以其他名称搜索到类型和方法
    4. 在顶层文档中,引导用户了解常用的模块、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!");
}

热门相关:洪荒二郎传      惊世毒妃:轻狂大小姐   特工重生:快穿全能女神   不伦家族