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

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 函数，要在文档里写明需要满足什么条件才能安全的调用这个函数。
例子一：

1. // Panic（恐慌）是这两种情况的一个很好的例子：如果代码可能发生 Panic，请在文档中明确说明这一点，以及可能导致 Panic 的情况。
2. // 同样，如果代码可能返回错误，请记录它返回错误的情况。
3. // 对于 unsafe 的函数，请记录调用者必须保证什么条件，才能确保调用时安全的。
5. /// 除法运算，返回两个数的结果。
6. ///
7. /// # Panics
8. ///
9. /// 如果除数为零，该函数会发生 panic。
10. ///
11. /// # 示例
12. ///
13. /// ```
14. /// let result = divide(10, 2);
15. /// assert_eq!(result, 5);
16. /// ```
17. pub fn divide(dividend: i32, divisor: i32) -> i32 {
18.   // 实现代码 ...
19. }

复制代码

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

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

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

例子二：

1. /// 一个简单的模块，包含一些用于内部使用的函数和结构体。
2. pub mod internal {
3.   /// 一个用于内部计算的辅助函数。
4.   #[doc(hidden)]
5.   pub fn internal_helper() {
6.     // 内部计算的具体实现 ...
7.   }
8.   
9.   /// 一个仅用于内部使用的结构体。
10.   #[doc(hidden)]
11.   pug struct InternalStruct {
12.     // 结构体的字段和方法 ...
13.   }
14. }
16. /// 一个公共接口函数，调用了内部的辅助函数。
17. pub fn public_function() {
18.   // 调用内部辅助函数
19.   internal::internal_helper();
20. }
22. /// 一个公共结构体，包含一些公共字段和方法。

复制代码

• 尽可能的丰富文档
  
  
  • 可以链接到解释这些内容的外部资源：
    
    
    • 相关的规范文件（RFC）、博客、白皮书 ...
      
    
    
  • 使用 #[doc(cfg(..))] 突出显示仅在特定配置下可用的项
    
    
    • 用户能快速了解为什么在文档中列出的某个方法不可用
      
    
    
  • 使用 #[doc(alias = "...")] 可让用户以其他名称搜索到类型和方法
    
  • 在顶层文档中，引导用户了解常用的模块、Trait、类型、方法
    
  
  

例子三：

1. //! 这是一个用于处理图像的库。
2. //!
3. //! 这个库提供了一些常用的图像处理功能，例如：
4. //! - 读取和保存不同格式的图像文件 [`Image::load`] [`Image::save`]
5. //! - 调整图像的大小、旋转和裁剪 [`Image::resize`] [`Image::rotate`] [`Image::crop`]
6. //! - 应用不同的滤镜和效果 [`Filter`] [`Effect`]
7. //!
8. //! 如果您想了解更多关于图像处理的原理和算法，您可以参考以下的资源：
9. //! - [数字图像处理](https://book.douban.com/subject/5345798/)，一个经典的教科书，介绍了图像处理的基本概念和方法。
10. //! - [Learn OpenCV](https://learnopencv.com/)，一个网站，提供了很多用OpenCV实现图像处理功能的教程和示例代码。
11. //! - [Awesome Computer Vision](https://github.com/jbhuang0604/awesome-computer-vision)，一个GitHub仓库，收集计算机视觉资源。
13. /// 一个表示图像的结构体
14. #[derive(Debug, Clone)]
15. pub struct Image {
16.   // ...
17. }
19. impl Image {
20.   /// 从指定的路径加载一个图像文件
21.   ///
22.   /// 支持的格式有：PNG、JPEG、GIF、BMP 等
23.   ///
24.   /// # 参数
25.   ///
26.   /// - `path`: 图像文件的路径
27.   ///
28.   /// # 返回值
29.   ///
30.   /// 如果成功，返回一个 [`Image`] 实例；如果失败，返回一个 [`Error`]。
31.   ///
32.   /// # 示例
33.   ///
34.   /// ```no_run
35.   /// use image::Image;
36.   ///
37.   /// let img = Image::load("test.png")?;
38.   /// ```
39.   #[doc(alias = "读取")]
40.   #[doc(alias = "打开")]
41.   pub fn load<P: AsRef<Path>>(path: P) -> Result<Self, Error> {
42.     // ...
43.   }
44.   
45.   /// 将图像保存到指定的路径
46.   ///
47.   /// 支持的格式有：PNG、JPEG、GIF、BMP 等
48.   ///
49.   /// # 参数
50.   ///
51. }

复制代码

例子四：

1. /// 一个只在启用了 `foo` 特性时才可用的结构体。
2. #[cfg(feature = "foo")]
3. #[doc(cfg(feature = "foo"))]
4. pub struct Foo;
6. impl Foo {
7.   /// 一个只在启用了 `foo` 特性时才可用的方法。
8.   #[cfg(feature = "foo")]
9.   #[doc(cfg(feature = "foo"))]
10.   pub fn bar(&self) {
11.     // ...
12.   }
13. }
15. fn main() {
16.   println!("Hello, world!");
17. }

复制代码

类型系统

• 类型系统可确保：
  
  
  
  • 接口明显
    
  • 自我描述
    
  • 难以被误用
    
  
  
• 语义化类型：
  
  
  
  • 添加类型来表示值的意义（不仅仅适用基本类型）
    
  
  

例子五：

1. fn processDate(dryRun: bool, overwrite: bool, validate: bool) {
2.   // 处理数据的逻辑
3. }
5. enum DryRun {
6.   Yes,
7.   No,
8. }
10. enum Overwrite {
11.   Yes,
12.   No,
13. }
15. enum Validate {
16.   Yes,
17.   No,
18. }
20. fn processData(dryRun: DryRun, overwrite: Overwrite, validate: Validate) {
21.   // 处理数据的逻辑
22. }
24. processData(DryRun::Yes, Overwrite::No, Validate::Yes);
26. fn main() {
27.   println!("Hello, world!");
28. }

复制代码

• 使用”零大小“类型来表示关于类型实例的特定事实
  

例子六：

1. struct Grounded;
2. struct Launched;
3. // and so on
5. enum Color {
6.   White,
7.   Black,
8. }
10. struct Kilograms(u32);
12. struct Rocket<Stage = Grounded> {
13.   stage: std::marker::PhantomData<Stage>,
14. }
16. impl Default for Rocket<Grounded> {
17.   fn default() -> Self {
18.     Self {
19.       stage: Default::default()
20.     }
21.   }
22. }
23. impl Rocket<Grounded> {
24.   pub fn launch(self) -> Rocket<Launched> {
25.     Rocket {
26.       stage: Default::default(),
27.     }
28.   }
29. }
31. impl Rocket<Launched> {
32.   pub fn accelerate(&mut self) {}
33.   pub fn decelerate(&mut self) {}
34. }
36. impl<Stage> Rocket<Stage> {
37.   pub fn color(&self) -> Color {
38.     Color::White
39.   }
40.   pub fn weight(&self) -> Kilograms {
41.     Kilograms(0)
42.   }
43. }
45. fn main() {
46.   println!("Hello, world!");
47. }

复制代码

• #[must_use] 注解
  
  
  
  • 将其添加到类型、Trait 或函数中，如果用户的代码接收到该类型或 Trait 的元素，或调用了该函数，并且没有明确处理它，编译器将发出警告
    
  
  

例子七：

1. #[must_use]
2. fn process_data(data: Data) -> Result<(), Error> {
3.   // 处理数据的逻辑
4.   
5.   Ok(())
6. }
8. // 在这个示例中，我们使用 #[must_use] 注解将 process_data 函数标记为必须使用期返回值。
9. // 如果用户在调用该函数后没有显式处理返回的 Result 类型，编译器将发出警告。
10. // 这有助于提醒用户在处理潜在的错误情况时要小心，并减少可能得错误。
12. fn main() {
13.   println!("Hello, world!");
14. }

复制代码

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！