【Rust中级教程】2.9. API设计原则之显然性(obvious) ：文档与类型系统、语义化类型、使用“零大小”类型

news/2025/2/25 9:17:58

喜欢的话别忘了点赞、收藏加关注哦（加关注即可阅读全文），对接下来的教程有兴趣的可以关注专栏。谢谢喵！(=･ω･=)
请添加图片描述

2.9.1. 文档与类型系统

用户可能不会完全理解API的所有规则和限制。所以你写的API应该让你的用户易于理解，并且难以用错。

通过Rust的文档与类型系统，我们可以尽量实现这个需求。

2.9.2. 文档

让API透明化的第一步就是写出好的文档。

写出好的文档有这么几点要求：

1. 清楚的记录

清楚的记录可能出现的意外情况，或它依赖于用户执行超出类型签名要求的操作。

例如：何时会发生panic、何时返回错误。如果使用了unsafe函数，那么需要写明用户需要什么条件才能安全地调用这个函数。

看个例子：

rust">/// 除法运算，返回两个数的结果
///
/// # Panics
///
/// 如果除数为0，该函数会发生 panic。
/// 
/// # 示例
/// 
/// ```
/// let result = divide(10, 2);
/// assert_eq!(result, 5);
/// ```
pub fn divide(dividend: i32, divisor: i32) -> i32 {
	// ...此处省略
}
  • 这里我们把会发生恐慌的情况写进去了

2. 包含端到端的用例

在crate或module级别，要包含端到端的用例，而不是针对特定的类型或方法。

这么做的好处是让用户了解这些内容是如何组合到一起的，对API的整体结构有一个相对清晰的理解，从而让开发者快速了解到各方法和类型的功能，以及在哪里使用。

在你提供了端到端的用例之后，用户就可以把这段代码复制粘贴到自己的项目里，相当于给用户提供了一个定制化使用的起点。

举个例子：

假设我们有一个math_utils crate，它提供了一些数学运算功能，包括基本的加法、减法和一个复杂的计算函数。这里每个函数的文档注释我就只简单写功能了，但是你自己在写的时候一定要写好每个函数的文档注释。

rust">// lib.rs (crate 根模块)
pub mod math_utils {
    /// 计算两个数的和
    pub fn add(a: i32, b: i32) -> i32 {
        a + b
    }

    /// 计算两个数的差
    pub fn subtract(a: i32, b: i32) -> i32 {
        a - b
    }

    /// 执行复杂的数学运算（如 a * b + (a - b)）
    pub fn complex_calculation(a: i32, b: i32) -> i32 {
        (a * b) + subtract(a, b)
    }
}

// --- 端到端用例（crate 级别文档测试） ---
/// ```
/// use my_crate::math_utils;
///
/// fn main() {
///     let sum = math_utils::add(10, 5);
///     let difference = math_utils::subtract(10, 5);
///     let result = math_utils::complex_calculation(10, 5);
///
///     println!("Sum: {}", sum); // 15
///     println!("Difference: {}", difference); // 5
///     println!("Complex Calculation Result: {}", result); // 55
/// }
/// ```

3. 组织好文档

利用模块来将语义相关的项目进行分组。然后使用内部文档链接将这些项相互连接起来。

有时候你可以考虑使用#[doc(hidden)]这个注解标记那些不打算公开但出于遗留的原因需要的接口部分，避免弄乱文档。

看个例子：

rust">/// 一个简单的模块，包含一些用于内部使用的函数和结构体。
pub mod internal {
    /// 一个用于内部计算的辅助函数。
    #[doc(hidden)]
    pub fn internal_helper() {
        // 内部计算的具体实现...
    }

    /// 一个仅用于内部使用的结构体。
    #[doc(hidden)]
    pub struct InternalStruct {
        // 结构体的字段和方法...
    }
}
  • internal_helper()函数和InternalStruct结构体都是只供内部使用的。
  • 给它们标注了#[doc(hidden)]，它们的文档注释就不会出现在生成的文档注释中

4.尽可能地丰富文档

有时候需要解释一些内容和概念，你就可以添加链接到外部资源。比如：相关的规范文件（RFC）、博客、白皮书…

在顶层文档中需要引导用户了解常用的模块、trait、类型和方法。

一些有关文档内容的注解：

  • 使用#[doc(cfg(..))]突出显示仅在特定配置下可用的项，这样用户就能快速了解为什么在文档中列出的某个方法不可用。
  • 使用#[doc(alias = "...")]可以让用户以其他名称搜索到类型和方法

例子1:

rust">//! 这是一个用于处理图像的库。
//!
//! 这个库提供了一些常用的图像处理功能，例如：
//! - 读取和保存不同格式的图像文件 [`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 {
    // ...
}
// ...
  • 这里使用到了外部链接，可以看到外部链接的格式是[你想展示在文档中的字](链接)，这就是标准的markdown格式，只要是写过自述文件的人肯定都非常熟悉。

例子2:

rust">impl Image {
	// ...
	// ...
	#[doc(alias = "读取")]
	#[doc(alias = "打开")]
	pub fn load<P: AsRef<Path>>(path: P) -> Result<Self, Error> {
		// ...
	}
	// ...
}
  • 使用了#[doc(alias = "读取")]和#[doc(alias = "打开")]这两个注释，这样在文档中搜索“读取”和“打开”时就能搜到这个函数。

例子3:

rust">/// 一个只在启用了 `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!");
}
  • #[cfg(feature = "foo")]：只有当启用了"foo"特性时，Foo结构体及其方法bar才会包含在最终的编译产物中。
  • #[doc(cfg(feature = "foo"))]：在API说明中标注该结构体和方法依赖foo特性，让使用者知道它们并非默认可用。

2.9.3. 类型系统

我们使用Rust的类型系统可以确保：

  • 接口明显
  • 自我描述
  • 难以被误用

语义化类型

有一些值具有超过它表面的意义的，比如说1和0可以代表男和女。这时候我们就可以添加类型来表示值的意义。

看例子：

rust">fn processData(dryRun: bool, overwrite: bool, validate: bool) {
    // 处理数据的逻辑
}
  • 这个函数的3个参数都是布尔类型，很容易记混，用户极有可能错误地使用

为了解决这个问题，我们可以创建3个类型，并让参数是3个不同的类型：

rust">
enum DryRun {
    Yes,
    No,
}

enum Overwrite {
    Yes,
    No,
}

enum Validate {
    Yes,
    No,
}

fn processData(dryRun: DryRun, overwrite: Overwrite, validate: Validate) {
    // 处理数据的逻辑
}
  • 把3个布尔类型变成3个枚举类型

用户在调用的时候就会写：

rust">processData(DryRun::Yes, Overwrite::No, Validate::Yes)

这样更加的清晰明了。

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

举个例子：

假入我们有一个结构体Rocket，它有方法launch用于发射，这个火箭没有出于已发射状态时调用这个方法肯定是没有问题的。但是如果火箭已经处于已发射状态了就不能再使用发射方法了。同样的，在火箭发射后我们能控制火箭加速或减速，但在地面不行。

rust">// 定义不同的火箭状态
struct Grounded;
struct Launched;

// 颜色枚举
enum Color {
    White,
    Black,
}

// 质量结构体，使用 newtype 模式封装 u32
struct Kilograms(u32);

// 泛型火箭结构体，带有默认状态 Grounded
struct Rocket<Stage = Grounded> {
    stage: std::marker::PhantomData<Stage>,
}

// 为 Grounded 状态的 Rocket 实现 Default
impl Default for Rocket<Grounded> {
    fn default() -> Self {
        Self {
            stage: Default::default(),
        }
    }
}

// 为 Grounded 状态的 Rocket 实现方法
impl Rocket<Grounded> {
    pub fn launch(self) -> Rocket<Launched> {
        Rocket {
            stage: Default::default(),
        }
    }
}

// 为 Launched 状态的 Rocket 实现方法
impl Rocket<Launched> {
    pub fn accelerate(&mut self) {}
    pub fn decelerate(&mut self) {}
}

// 为所有状态的 Rocket 实现通用方法
impl<Stage> Rocket<Stage> {
    pub fn color(&self) -> Color {
        Color::White
    }

    pub fn weight(&self) -> Kilograms {
        Kilograms(0)
    }
}

  • Grounded和Launched这两个结构体没有任何字段，因此它们的大小为零，Rust编译器不会为它们分配内存空间。它们仅用于标记Rocket处于哪种状态，而不需要额外的存储开销。

  • 我们定义了Rocket结构体，它带有一个泛型参数Stage，该参数默认是Grounded。在定义中我们还使用了std::marker::PhantomData<T>，它是零大小类型 (ZST, Zero-Sized Type)，它在编译期影响类型系统，但运行时不会占用内存。

  • launch方法仅在Rocket<Grounded>实例上可用。

  • launch()被调用后，会返回一个Rocket<Launched>，表示火箭已经进入发射状态。Rocket<Launched>不再有launch()方法，确保无法重复发射。

  • accelerate方法代表加速，decelerate方法代表减速，这些方法只对Rocket<Launched>实例有效，防止在Grounded状态下加速或减速。

  • 有些方法在任何状态下都可以使用，我们就写在impl<Stage> Rocket<Stage>这个块里即可。

#[must_use]注解

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

看一个例子：

rust">#[must_use]
fn process_data(data: Data) -> Result<(), Error> {
    // ...

    Ok(())
}
  • 我们使用#[must_use]注解将process_data函数标记为必须使用其返回值
  • 如果用户在调用该函数后没有显式处理返回的Result类型，编译器将发出警告
  • 这有助于提醒用户在处理潜在的错误情况时要小心，并减少可能的错误

http://www.niftyadmin.cn/n/5865308.html

相关文章

双指针1：283. 移动零

双指针1：283. 移动零

双指针的基本思想&#xff1a; 首先根据异地操作确定指针的基本步骤&#xff0c;再将异地操作优化成原地操作的双指针解法 链接&#xff1a;283. 移动零 - 力扣&#xff08;LeetCode&#xff09; 题解&#xff1a; 异地操作&#xff1a;fast指针指向原数组&#xff0c;slow指…
阅读更多...
tableau之人口金字塔、漏斗图、箱线图

tableau之人口金字塔、漏斗图、箱线图

一、人口金字塔 人口金字塔在本质上就是成对的条形图 人口金字塔是一种特殊的旋风图 1、数据处理 对异常数据进行处理 2、创建人口金字塔图 将年龄进行分桶 将男女人数数据隔离开 分别绘制两个条形图 双击男性条形图底部&#xff0c;将数据进行翻转&#xff08;倒序&a…
阅读更多...
本周行情——250222

本周行情——250222

本周A股行情展望与策略 结合近期盘面特征及市场主线演化&#xff0c;本周A股预计延续结构性分化行情&#xff0c;科技成长与政策催化板块仍是资金主战场&#xff0c;但需警惕高标股分歧带来的波动。以下是具体分析与策略建议&#xff1a; 1. 行情核心驱动因素 主线延续性&…
阅读更多...
JavaScript系列（86）--现代构建工具详解

JavaScript系列（86）--现代构建工具详解

JavaScript 现代构建工具详解 &#x1f528; 现代前端开发离不开构建工具&#xff0c;它们帮助我们处理模块打包、代码转换、资源优化等任务。让我们深入了解主流的构建工具及其应用。 构建工具概述 &#x1f31f; &#x1f4a1; 小知识&#xff1a;构建工具主要解决代码转换…
阅读更多...
C语言堆学习笔记

C语言堆学习笔记

1. 堆的定义 堆&#xff08;Heap&#xff09;是一种特殊的树形数据结构&#xff0c;它满足以下性质&#xff1a; 堆是一个完全二叉树。堆中每个节点的值都大于或等于&#xff08;最大堆&#xff09;或小于或等于&#xff08;最小堆&#xff09;其子节点的值。 1.1 最大堆 在…
阅读更多...
SpringBoot之自定义简单的注解和AOP

SpringBoot之自定义简单的注解和AOP

1.引入依赖 <!-- AOP依赖--> <dependency><groupId>org.aspectj</groupId><artifactId>aspectjweaver</artifactId><version>1.9.8</version> </dependency>2.自定义一个注解 package com.example.springbootdemo3.an…
阅读更多...
鸿蒙ArkTS页面如何与H5页面交互？

鸿蒙ArkTS页面如何与H5页面交互？

鸿蒙页面如何与H5页面交互&#xff1f; 先看效果前言通信功能介绍Web组件使用问题 Harmony OS NEXT版本&#xff08;接口及解决方案兼容API12版本或以上版本) 先看效果 功能介绍 点击Click Me按钮可以接收展示鸿蒙传递给html的内容点击霓虹灯按钮可以同步更新底部鸿蒙页面的按…
阅读更多...
Flutter系列教程之(2)——Dart语言快速入门

Flutter系列教程之(2)——Dart语言快速入门

目录 1.变量与类型 1.1 num类型 1.2 String类型 1.3 Object与Dynamic 1.4 类型判断/转换 1.5 变量和常量 2.方法/函数 3.类、接口、抽象类 3.1 类 3.2 接口 4.集合 4.1 List 4.2 Set 4.3 Map 5.总结 Dart语言的语法和Kotlin、Java有类似之处&#xff0c;这里就通…
阅读更多...
最新文章

Copyright @ 2022~2023