Rust語言 - 介面設計的建議之不意外（unsurprising）

来源:https://www.cnblogs.com/QiaoPengjun/archive/2023/06/08/17467240.html
-Advertisement-
Play Games

# Rust - 介面設計建議之不意外（unsurprising） 書：Rust for Rustaceans ## Rust介面設計的原則（建議） - 四個原則： - 不意外（unsurprising） - 靈活（flexible） - 顯而易見（obvious） - 受約束（constraine ...


Rust - 介面設計建議之不意外（unsurprising）

書：Rust for Rustaceans

Rust介面設計的原則（建議）

不意外（unsurprising）

  • 最少意外原則：
    • 介面應儘可能直觀（可預測，用戶能猜對）
    • 至少應該不讓人感到驚奇
  • 核心思想：
    • 貼近用戶已經知道的東西（不必重學概念）
  • 讓介面可預測：
    • 命名
    • 實現常用的 Traits
    • 人體工程學（Ergonomic）Traits
    • 包裝類型（Wrapper Type）

命名實踐

  • 介面的名稱，應符合慣例，便於推斷其功能
    • 例：
      • 方法 iter，大概率應將 &self 作為參數，並應該返回一個迭代器（iterator）
      • 叫做 into_inner 的方法，大概率應將 self 作為參數，並返回某個包裝的類型
      • 叫做 SomethingError 的類型，應實現 std::error::Error，並出現在各類 Result 里
  • 將通用/常用的名稱依然用於相同的目的，讓用戶好猜、好理解
  • 推論：同名的事物應該以相同的方式工作
    • 否則，用戶大概率會寫出錯誤的代碼
  • 遵循 as_, to_, into_ 規範 用以特定類型轉換
名稱首碼 記憶體代價 所有權
as_ 無代價 borrowed -> borrowed
to_ 代價昂貴 borrowed -> borrowed borrowed -> owned (非 Copy 類型) owned -> owned (Copy 類型)
into_ 視情況而定 owned -> owned (非 Copy 類型)

實現常用的 Trait

  • 用戶通常會假設介面中的一切均可“正常工作”，例：
    • 使用 {:?} 列印任何類型
    • 可發送任何東西到另外的線程
    • 期望每個類型都是 Clone 的
  • 建議積極實現大部分標準 Trait，即使不立即用到
  • 用戶無法為外部類型實現外部的 Trait
    • 即使能包裝你的介面類型，也難以寫出合理實現

Rust 的 trait 系統堅持 孤兒原則 ：大致說的是， 每個 impl 塊必須

  1. 要麼存在於定義 trait 的 crate 中，
  2. 要麼存在於給類型實現 trait 的 crate 中。

所以，定義新類型的 crates 應該儘早實現所有合適的、常見的 traits 。

std 中可給類型實現的、最重要的、常見的 traits 有：

給類型實現 Default trait 和空的 new 構造函數是常見和有必要的。
new 是 Rust 中常規的構造函數，所以不使用參數來構造基本的類型時， new 對使用者來說就理應存在。
default 方法功能上與 new 方法一致，所以也應當存在。

建議實現 Debug Trait

  • 幾乎所有的類型都能、應該實現 Debug
    • #[derive(Debug)]，通常是最佳實現方式
      • 註意：派生的 Trait 會為任意泛型參數添加相同的約束（bound）
    • 利用 fmt::Formatter 提供的各種 debug_xxx 輔助方法手動實現
      • debug_struct
      • debug_tuple
      • debug_list
      • debug_set
      • debug_map

例子一

use std::fmt::Debug;

#[derive(Debug)]
struct Pair<T> {
  a: T,
  b: T,
}

fn main() {
  let pair = Pair {a: 5, b: 10};
  println!("Pair: {:?}", pair); // i32 實現了 Debug Trait 故可以列印出來
}

例子二

use std::fmt::Debug;

struct Person {
  name: String,
}

#[derive(Debug)]
struct Pair<T> {
  a: T,
  b: T,
}

fn main() {
  let pair = Pair {
    a: Person { name: "Dave".to_string() },
    b: Person { name: "Nick".to_string() },
  }；
  println!("Pair: {:?}", pair);  // 報錯 `Person` doesn't implement `Debug` Person 沒有實現 Debug Trait
}

例子三

use std::fmt;

struct Pair<T> {
  a: T,
  b: T,
}

impl<T: fmt::Debug> fmt::Debug for Pair<T> {
  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    f.debug_struct("Pair").field("a", &self.a).field("b", &self.b).finish()
  }
}

fn main() {
  let pair = Pair { a: 5, b: 10 };
  println!("Pair: {:?}", pair);
}

建議實現 Send 和 Sync（unpin）

  • 不是 Send 的類型無法放在 Mutex 中，也不能在包含線程池的應用程式中傳遞使用

例子四

#[derive(Debug)]
struct MyBox(*mut u8);

unsafe impl Send for MyBox {}

use std::rc::Rc;

fn main() {
  let mb = MyBox(Box::into_raw(Box::new(42)));
  
  let x = Rc::new(42);
  
  std::thread::spawn(move || {
    println!("{:?}", x); // error: `Rc<i32>` cannot be sent between threads safely
  });
  
  //std::thread::spawn(move || {
  //  println!("{:?}", mb); // mb 實現了 Send Trait 
  //});
}
  • 不是 Sync 的類型無法通過 Arc 共用，也無法被放置在靜態變數中

例子五

use std::cell::RefCell;
use std::sync::Arc;

fn main() {
  let x = Arc::new(RefCell::new(42));
  std::thread::spawn(move || {
    let mut x = x.borrow_mut(); // error: `RefCell<i32>` cannot be shared between threads safely
    *x += 1;
  });
}
  • 如果沒實現上述 Trait，建議在文檔中說明

建議實現 Clone 和 Default

例子六

#[derive(Debug, Clone)]
struct Person {
  name: String,
  age: u32,
}

impl Person {
  fn new(name: String, age: u32) -> Person {
    Person { name, age }
  }
}

fn main() {
  let person1 = Person::new("Alice".to_owned(), 25);
  let person2 = person1.clone();
  
  println!("Person 1: {:?}", person1);
  println!("Person 2: {:?}", person2);
}

例子七

#[derive(Default)]
struct Point {
  x: i32,
  y: i32,
}

fn main() {
  let point = Point::default(); // 提供預設的初始值
  
  println!("Point: ({}, {})", point.x, point.y); // Point: (0, 0)
}
  • 如果沒實現上述 Trait，建議在文檔中說明

建議實現 PartialEq、PartialOrd、Hash、Eq、Ord

  • PartialEq 特別有用
    • 用戶會希望使用 == 或 assert_eq! 比較你類型的兩個實例

例子八

#[derive(Debug, PartialEq)]
struct Point {
  x: i32,
  y: i32,
}

fn main() {
  let point1 = Point { x: 1, y: 2 };
  let point2 = Point { x: 1, y: 2 };
  let point3 = Point { x: 3, y: 4 };
  
  println!("point1 == point2: {}", point1 == point2);
  println!("point1 == point3: {}", point1 == point3);
}
  • PartialOrd 和 Hash 相對更專門化
    • 將類型作為 Map 中的 Key
      • 須實現 PartialOrd，以便進行 Key 的比較
    • 使用 std::collection 的集合類型進行去重的類型
      • 須實現 Hash，以便進行哈希計算

例子九

use std::collections::BTreeMap;

#[derive(Debug, PartialEq, PartialOrd, Eq, Ord, Clone)]
struct Person {
  name: String,
  age: u32,
}

fn main() {
  let mut ages = BTreeMap::new();
  
  let person1 = Person {
    name: "Alice".to_owned(),
    age: 25,
  };
  let person2 = Person {
    name: "Bob".to_owned(),
    age: 30,
  };
  let person3 = Person {
    name: "Charlie".to_owned(),
    age: 20,
  };
  
  ages.insert(person1.clone(), "Alice's age");
  ages.insert(person2.clone(), "Bob's age");
  ages.insert(person3.clone(), "Charlie's age");
  
  for (person, description) in &ages {
    println!("{}: {} - {:?}", person.name, person.age, description);
  }
}

例子十

use std::collections::HashSet;
use std::hash::{Hash, Hasher};

#[derive(Debug, PartialEq, Eq, Clone)]
struct Person {
  name: String,
  age: u32,
}

impl Hash for Person {
  fn hash<H: Hasher>(&self, state: &mut H) {
    self.name.hash(state);
    self.age.hash(state);
  }
}

fn main() {
  let mut persons = HashSet::new();
  
  let person1 = Person {
    name: "Alice".to_owned(),
    age: 25,
  };
  let person2 = Person {
    name: "Bob".to_owned(),
    age: 30,
  };
  let person3 = Person {
    name: "Charlie".to_owned(),
    age: 20,
  };
  
  persons.insert(person1.clone());
  persons.insert(person2.clone());
  persons.insert(person3.clone());
  
  println!("Persons: {:?}", persons);
}
  • Eq 和 Ord 有額外的語義要求（相對 PartialEq 和 PartialOrd）
    • 只應在確信這些語義適用於你的類型時才實現它們

例子十一

// Eq
// 反身性（Reflexivity）：對於任何對象 x，x == x 必須為真。
// 對稱性（Symmetry）：對於任何對象 x 和 y，如果 x == y 為真，則 y == x 也必須為真。
// 傳遞性（Transitivity）：對於任何對象 x、y 和 z，如果 x == y 為真，並且 y == z 為真，則 x == z 也必須為真。

// Ord
// 自反性（Reflexivity）：對於任何對象 x，x <= x 和 x >= x 必須為真。
// 反對稱性（Antisymmetry）：對於任何對象 x 和 y，如果 x <= y 和 y <= x 都為真，則 x == y 必須為真。
// 傳遞性（Transitivity）：對於任何對象 x、y 和 z，如果 x <= y 和 y <= z 都為真，則 x <= z 必須為真。


fn main() {
  
}

建議實現 serde 下的 Serialize、Deserialize

  • serde_derive（crate）提供了機制，可以覆蓋單個欄位或枚舉變體的序列化
    • 由於 serde 是第三方庫，你可能不希望強制添加對它的依賴
    • 大多數庫選擇提供一個 serde 的功能（feature），只有當用戶選擇啟用該功能時才添加對 serde 的支持

例子十二：你寫的庫

[dependencies]
serde = { version = "1.0", optional = true}

[features]
serde = ["serde"]

例子十三：別人用的時候

[dependencies]
mylib = { version = "0.1", features = ["serde"] }

為什麼沒建議實現 Copy

  • 用戶通常不期望類型是 Copy 的
    • 如果想要兩個副本，通常希望調用 clone
  • Copy 改變了移動給定類型值的語義
    • 讓用戶 surprise
  • Copy 類型受到很多限制，一個最初簡單的類型很容易變得不再滿足 Copy 的要求
    • 例如持有了 String 或者其他非 Copy 的類型 ---> 不得不移除 Copy

例子十四

#[derive(Debug, Copy, Clone)]
struct Point {
  x: i32,
  y: i32,
}

fn main() {
  let point1 = Point { x: 10, y: 20 };
  let point2 = point1; // 這裡發生複製，而不是移動
  
  println!("point1: {:?}", point1);
  println!("point2: {:?}", point2);
}

人體工程學 Trait 實現

  • Rust 不會自動為實現 Trait 的類型的引用提供對應的實現
    • Bar 實現了 Trait，也不能將 &Bar 傳遞給 fn foo<T: Trait>(t: T)
      • 因為 Trait 可能包含接受 &mut self 或 self 的方法，而這些方法無法在 &Bar 上調用
    • 對於看到 Trait 只有 &self 方法的用戶來說，這會非常令人驚訝
  • 定義新的 Trait 時，通常需要為下列提供相應的全局實現
    • &T where T: Trait
    • &mut T where T: Trait
    • Box<T> where T: Trait
  • Iterator（迭代器）：為類型的引用添加 Trait 實現
    • 對於任何可迭代的類型，考慮為 &MyType 和 &mut MyType 實現 IntoIterator
      • 在迴圈中可直接使用借用實例，符號用戶預期。

包裝類型（Wrapper Types）

  • Rust 沒有傳統意義上的繼承
  • Deref 和 AsRef 提供了類似繼承的東西
    • 你有一個類型為 T 的值，並滿足 T: Deref<Target = U>，可以在 T 類型值上直接調用類型 U 的方法

例子十五

use std::ops::Deref;

struct MyVec(Vec<i32>);

impl Deref for MyVec {
  type Target = Vec<i32>;
  
  fn deref(&self) -> &Self::Target {
    &self.0
  }
}

fn main() {
  let my_vec = MyVec(vec![1, 2, 3, 4, 5]);
  
  println!("Length: {}", my_vec.len());
  println!("First element: {}", my_vec[0]);
}
  • 如果你提供了相對透明的類型（例 Arc）
    • 實現 Deref 允許你的包裝類型在使用點運算符時，自動解引用為內部類型，從而可以直接調用內部類型的方法
    • 如果訪問內部類型不需要任何複雜或潛在的低效邏輯，應考慮實現 AsRef，這樣用戶可以輕鬆地將 &WrapperType 作為 &InnerType 使用
    • 對於大多數包裝類型，還應該在可能的情況下實現 From<InnerType> 和 Into<InnerType>，以便用戶可輕鬆地添加或移除包裝。

例子十六

use std::ops::Deref;

struct Wrapper(String);

impl Deref for Wrapper {
  type Target = String;
  
  fn deref(&self) -> *Self::Target {
    &self.0
  }
}

impl AsRef<str> for Wrapper {
  fn as_ref(&self) -> &str {
    &self.0
  }
}

impl From<String> for Wrapper {
  fn from(s: String) -> Self {
    Wrapper(s)
  }
}

impl From<Wrapper> for String {
  fn from(wrapper: Wrapper) -> Self {
    wrapper.0
  }
}

fn main() {
  let wrapper = Wrapper::from("Hello".to_string());
  
  // 使用 . 運算符調用內部字元串類型的方法
  println!("Length: {}", wrapper.len());
  
  // 使用 as_ref 方法將 Wrapper 轉換為 &str 類型
  let inner_ref: &str = wrapper.as_ref();
  println!("Inner: {}", inner_ref);
  
  // 將 Wrapper 轉換為內部類型 String
  let inner_string: String = wrapper.into();
  println!("Inner String: {}", inner_string);
}
  • Borrow Trait （與 Deref 和 AsRef 有些類似）
    • 針對更為狹窄的使用情況進行了定製：
      • 允許調用者提供同一類型的多個本質上相同的變體中的任意一個
        • 可叫做：Equivalent
        • 例：對於一個 HashSet<String>，Borrow 允許調用者提供 &str 或 &String。
          • 雖然使用 AsRef 也可以實現類似的效果，但如果沒有 Borrow 的額外要求，這種實現時不安全的，因為 Borrow 要求目標類型實現的 Hash、Eq、和 Ord 必須與實現類型完全相同
      • Borrow 還為 Borrow<T>、&T 和 &mut T 提供了通用實現
        • 這使得在 Trait 約束中使用它來接受給定類型的擁有值或引用值非常方便。
    • Borrow 僅適用於當你的類型本質上與另一個類型等價時
    • 而 Deref 和 AsRef 則適用於更廣泛地實現你的類型可以“充當”的情況

例子十七

use std::borrow::Borrow;

fn print_length<S>(string: S)
where
	S: Borrow<str>,
{
  println!("Length: {}", string.borrow().len());
}

fn main() {
  let str1: &str = "Hello";
  let string1: String = String::from("World");
  
  print_length(str1);
  print_length(string1);
}

本文來自博客園，作者：尋月隱君，轉載請註明原文鏈接：https://www.cnblogs.com/QiaoPengjun/p/17467240.html


您的分享是我們最大的動力!

-Advertisement-
Play Games
更多相關文章
  • CentOS7環境編譯python3.9版本pjsua
    環境：CentOS 7.6_x64 Python版本 ：3.9.12 pjsip版本：2.13 一、背景描述 pjsip地址：https://www.pjsip.org/ GitHub地址：https://github.com/pjsip/pjproject pjsip文檔地址：https://do ...
  • C++面試八股文：C++中，設計一個類要註意哪些東西？
    某日二師兄參加XXX科技公司的C++工程師開發崗位第9面： > 面試官：C++中，設計一個類要註意哪些東西？ > > 二師兄：設計一個類主要考慮以下幾個方面：1.面向對象的封裝、繼承及多態。2.`big three`或者`big five`。3.運算符和函數重載、靜態成員、友元、異常處理等相關問題。 ...
  • python 爬蟲某東網商品信息 | 沒想到銷量最高的是
    哈嘍大家好，我是鹹魚 好久沒更新 python 爬蟲相關的文章了，今天我們使用 selenium 模塊來簡單寫個爬蟲程式——爬取某東網商品信息 網址鏈接：https://www.jd.com/ 完整源碼在文章最後 ## 元素定位 我們需要找到網頁上元素的位置信息（xpth 路徑） ![image]( ...
  • 逍遙自在學C語言 | 枚舉的那些事兒
    ## 前言 在C語言中，枚舉是一種方便組織和表示一組相關常量的工具。枚舉類型有助於提高代碼的可讀性和可維護性。本文將介紹C語言枚舉的基本概念、語法和用法，以及一些高級技巧。 ## 一、人物簡介 - 第一位閃亮登場，有請今後會一直教我們C語言的老師 —— 自在。 ![](https://img2023 ...
  • static
    | static基本知識 | header | | | | | | | 類名.靜態成員變數(推薦) 同一個類中靜態成員變數的訪問可以省略類名。 1.靜態成員變數（有static修飾，屬於類、載入一次，可以被共用訪問），訪問格式 類名.靜態成員變數(推薦) 對象.靜態成員變數(不推薦)。 2.實例成員 ...
  • rust學習 - 構建mini 命令行工具
    rust 的運行速度、安全性、單二進位文件輸出和跨平臺支持使其成為構建命令行程式的最佳選擇。 實現一個命令行搜索工具`grep`,可以在指定文件中搜索指定的字元串。想實現這個功能呢，可以按照以下邏輯流程處理： 1. 獲取輸入文件路徑、需要搜索的字元串 2. 讀取文件; 3. 在文件內容中查找字元串所 ...
  • 如何吃透一個Java項目？
    現在Austin的文檔我覺得還是比較全的，但到了看代碼的時候，可能有的同學就不知道應該怎麼看，有想知道模塊之間的調用鏈路，有想一點一點把細節給全看了。這時候就很可能在項目里犯迷糊了，繞不出不來了。 > **Java開源項目消息推送平臺🔥推送下發【郵件】【簡訊】【微信服務號】【微信小程式】【企業微信 ...
  • 實體類中嵌套Enum類型並想轉換成JSON字元串時遇到的問題。
    ## 實體類中嵌套Enum類型並想轉換成JSON字元串時遇到的問題。 先說明問題的產生，在自己寫著玩的時候，新建了一個**User**類如下： ```java package com.ma.xdo; import lombok.*; import java.io.Serializable; /** ...
一周排行
    -Advertisement-
    Play Games
  • 移動開發（一）：使用.NET MAUI開發第一個安卓APP
    移動開發（一）：使用.NET MAUI開發第一個安卓APP 對於工作多年的C#程式員來說，近來想嘗試開發一款安卓APP，考慮了很久最終選擇使用.NET MAUI這個微軟官方的框架來嘗試體驗開發安卓APP，畢竟是使用Visual Studio開發工具，使用起來也比較的順手，結合微軟官方的教程進行了安卓 ...
  • wpf ToggleButton選中效果和一個登錄界面
    前言 QuestPDF 是一個開源 .NET 庫，用於生成 PDF 文檔。使用了C# Fluent API方式可簡化開發、減少錯誤並提高工作效率。利用它可以輕鬆生成 PDF 報告、發票、導出文件等。 項目介紹 QuestPDF 是一個革命性的開源 .NET 庫，它徹底改變了我們生成 PDF 文檔的方 ...
  • 彈幕樹洞項目功能新增篇
    項目地址 項目後端地址： https://github.com/ZyPLJ/ZYTteeHole 項目前端頁面地址： ZyPLJ/TreeHoleVue (github.com) https://github.com/ZyPLJ/TreeHoleVue 目前項目測試訪問地址： http://tree ...
  • 第27篇 sqlserver2022詳細安裝步驟
    話不多說，直接開乾 一.下載 1.官方鏈接下載： https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads 2.在下載目錄中找到下麵這個小的安裝包 SQL2022-SSEI-Dev.exe，運行開始下載SQL server； 二. ...
  • .NET 開源高性能 MQTT 類庫
    前言 隨著物聯網（IoT）技術的迅猛發展，MQTT（消息隊列遙測傳輸）協議憑藉其輕量級和高效性，已成為眾多物聯網應用的首選通信標準。 MQTTnet 作為一個高性能的 .NET 開源庫，為 .NET 平臺上的 MQTT 客戶端與伺服器開發提供了強大的支持。 本文將全面介紹 MQTTnet 的核心功能 ...
  • Serilog文檔翻譯系列（六） - 可用的接收器、增強器、格式化輸出
    Serilog支持多種接收器用於日誌存儲，增強器用於添加屬性，LogContext管理動態屬性，支持多種輸出格式包括純文本、JSON及ExpressionTemplate。還提供了自定義格式化選項，適用於不同需求。 ...
  • 警惕 Visual Studio 屬性求值副作用導致邏輯不符合預期
    目錄簡介獲取 HTML 文檔解析 HTML 文檔測試參考文章 簡介 動態內容網站使用 JavaScript 腳本動態檢索和渲染數據，爬取信息時需要模擬瀏覽器行為，否則獲取到的源碼基本是空的。 本文使用的爬取步驟如下： 使用 Selenium 獲取渲染後的 HTML 文檔 使用 HtmlAgility ...
  • [使用目前最新版]HybridCLR6.9.0+YooAsset2.2.4實現純C# Unity熱更新方案 (一)
    1.前言 什麼是熱更新 游戲或者軟體更新時，無需重新下載客戶端進行安裝，而是在應用程式啟動的情況下，在內部進行資源或者代碼更新 Unity目前常用熱更新解決方案 HybridCLR，Xlua，ILRuntime等 Unity目前常用資源管理解決方案 AssetBundles，Addressable， ...
  • 在 ASP.NET Core Web API 中使用操作篩選器統一處理通用操作
    本文章主要是在C# ASP.NET Core Web API框架實現向手機發送驗證碼簡訊功能。這裡我選擇是一個互億無線簡訊驗證碼平臺，其實像阿裡雲，騰訊雲上面也可以。 首先我們先去 互億無線 https://www.ihuyi.com/api/sms.html 去註冊一個賬號 註冊完成賬號後，它會送 ...
  • 第28篇 如何.net中實現高效可靠數據同步api
    通過以下方式可以高效，並保證數據同步的可靠性 1.API設計 使用RESTful設計，確保API端點明確，並使用適當的HTTP方法（如POST用於創建，PUT用於更新）。 設計清晰的請求和響應模型，以確保客戶端能夠理解預期格式。 2.數據驗證 在伺服器端進行嚴格的數據驗證，確保接收到的數據符合預期格 ...
所有分類