王柳 发表于 2023-6-19 18:26:00

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 函数,要在文档里写明需要满足什么条件才能安全的调用这个函数。
例子一:
// 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 级,包括端到端的用例
[*]不是针对特定类型或方法,了解所有内容如何组合到一起
[*]对接口的整体结构有一个相对清晰的理解
[*]让开发者快速了解到各方法和类型的功能,以及在哪使用

[*]提供定制化使用的起点
[*]通过复制粘贴,结合需求进行修改


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

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

例子二:
/// 一个简单的模块,包含一些用于内部使用的函数和结构体。
pub mod internal {
/// 一个用于内部计算的辅助函数。
#
pub fn internal_helper() {
    // 内部计算的具体实现 ...
}

/// 一个仅用于内部使用的结构体。
#
pug struct InternalStruct {
    // 结构体的字段和方法 ...
}
}

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

/// 一个公共结构体,包含一些公共字段和方法。
[*]尽可能的丰富文档
[*]可以链接到解释这些内容的外部资源:
[*]相关的规范文件(RFC)、博客、白皮书 ...

[*]使用 # 突出显示仅在特定配置下可用的项
[*]用户能快速了解为什么在文档中列出的某个方法不可用

[*]使用 # 可让用户以其他名称搜索到类型和方法
[*]在顶层文档中,引导用户了解常用的模块、Trait、类型、方法

例子三:
//! 这是一个用于处理图像的库。
//!
//! 这个库提供了一些常用的图像处理功能,例如:
//! - 读取和保存不同格式的图像文件 [`Image::load`] [`Image::save`]
//! - 调整图像的大小、旋转和裁剪 [`Image::resize`] [`Image::rotate`] [`Image::crop`]
//! - 应用不同的滤镜和效果 [`Filter`] [`Effect`]
//!
//! 如果您想了解更多关于图像处理的原理和算法,您可以参考以下的资源:
//! - [数字图像处理](https://book.douban.com/subject/5345798/),一个经典的教科书,介绍了图像处理的基本概念和方法。
//! - (https://learnopencv.com/),一个网站,提供了很多用OpenCV实现图像处理功能的教程和示例代码。
//! - (https://github.com/jbhuang0604/awesome-computer-vision),一个GitHub仓库,收集计算机视觉资源。

/// 一个表示图像的结构体
#
pub struct Image {
// ...
}

impl Image {
/// 从指定的路径加载一个图像文件
///
/// 支持的格式有:PNG、JPEG、GIF、BMP 等
///
/// # 参数
///
/// - `path`: 图像文件的路径
///
/// # 返回值
///
/// 如果成功,返回一个 [`Image`] 实例;如果失败,返回一个 [`Error`]。
///
/// # 示例
///
/// ```no_run
/// use image::Image;
///
/// let img = Image::load("test.png")?;
/// ```
#
#
pub fn load<P: AsRef<Path>>(path: P) -> Result<Self, Error> {
    // ...
}

/// 将图像保存到指定的路径
///
/// 支持的格式有:PNG、JPEG、GIF、BMP 等
///
/// # 参数
///
}例子四:
/// 一个只在启用了 `foo` 特性时才可用的结构体。
#
#
pub struct Foo;

impl Foo {
/// 一个只在启用了 `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!");
}

[*]# 注解

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

例子七:
#
fn process_data(data: Data) -> Result<(), Error> {
// 处理数据的逻辑

Ok(())
}

// 在这个示例中,我们使用 # 注解将 process_data 函数标记为必须使用期返回值。
// 如果用户在调用该函数后没有显式处理返回的 Result 类型,编译器将发出警告。
// 这有助于提醒用户在处理潜在的错误情况时要小心,并减少可能得错误。

fn main() {
println!("Hello, world!");
}
免责声明:如果侵犯了您的权益,请联系站长,我们会及时删除侵权内容,谢谢合作!
页: [1]
查看完整版本: Rust语言 - 接口设计的建议之显而易见(Obvious)