Rust語言 - 介面設計的建議之受約束（Constrained）

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

# Rust語言 - 介面設計的建議之受約束（Constrained） - [Rust API 指南 GitHub](https://github.com/rust-lang/api-guidelines)：https://github.com/rust-lang/api-guidelines - ...


Rust語言 - 介面設計的建議之受約束（Constrained）

受約束（Constrained）

介面的更改要三思

  • 做出用戶可見的更改，需三思而後行
    • 確保你做出的變化：
      • 不會破壞現有用戶的代碼
      • 這次變化應保留一段時間
    • 頻繁的向後不相容的更改（主版本增加），會引起用戶不滿

向後不相容的修改

  • 有些是顯而易見的，有些則很微妙（與 Rust 工作方式相關）
    • 主要介紹微妙棘手的更改，以及如何為其制定計劃
    • 有時需要在介面靈活性上做出權衡、妥協

類型修改

  • 移除或重命名公共類型幾乎肯定會破壞用戶的代碼
    • 解決：儘可能利用可見性修飾符
      • 例如 pub(crate)、pub(in path) ...
    • 公共類型越少，更改時（保證不會破壞現有代碼）就越自由

例子一：

pub mod outer_mod {
  pub mod inner_mod {
    // This function is visible within `outer_mod`
    pub(in crate::outer_mod) fn outer_mod_visible_fn() {}
    
    // This function is visible to the entire crate
    pub(crate) fn crate_visible_fn() {}
    
    // This function is visible within `outer_mod`
    pub(super) fn super_mod_visible_fn() {
      // This function is visible since we're in the same `mod`
      inner_mod_visible_fn();
    }
    
    // This function is visible only within `inner_mod`,
    // which is the same as leaving it private.
    pub(self) fn inner_mod_visible_fn() {}
  }
  
  pub fn foo() {
    inner_mod::outer_mod_visible_fn();
    inner_mod::crate_visible_fn();
    inner_mod::super_mod_visible_fn();
    
    // This function is no longer visible since we're outside of `inner_mod`
    // Error! `inner_mod_visible_fn` is private
    // inner_mod::inner_mod_visible_fn();
  }
}

fn bar() {
  // This function is still visible since we're in the same crate
  outer_mod::inner_mod::crate_visible_fn();
  
  // This function is no longer visible since we're outside of `outer_mod`
  // Error! `super_mod_visible_fn` is private
  outer_mod::inner_mod::super_mod_visible_fn();
  
  // This function is no longer visible since we're outside of `outer_mod`
  // Error! `outer_mod_visible_fn` is private
  outer_mod::inner_mod::outer_mod_visible_fn();
  
  outer_mod::foo();
}

fn main() {
  bar()
}
  • 用戶代碼不僅僅通過名稱依賴於你的類型

例子二：

lib.rs

pub struct Unit;

main.rs

fn main() {
  let u = constrained::Unit; // v0 庫是 constrained
}

修改一

lib.rs

pub struct Unit {
  pub field: bool,
}

main.rs

fn is_true(u: constrained::Unit) -> bool {
  matches!(u, constrained::Unit { field: true })
}

fn main() {
  let u = constrained::Unit; // v0  報錯，因為添加欄位之後 Unit struct 原有的構造方式不可用
}

修改二

lib.rs

pub struct Unit {
  local: i32, // 增加私有欄位
}

main.rs

fn main() {
  let u = constrained::Unit; // v0  報錯，雖然欄位看不見，但是編譯器可以看到
}
  • Rust 提供 #[non_exhaustive] 來緩解這些問題
    • non_exhaustive 表示類型或枚舉在將來可能會添加更多欄位或變體
      • 它可以應用於 struct、enums 和 enum variants。
    • 在其它 crate，使用 non_exhaustive 定義的類型，編譯器會禁止：
      • 隱式構造，lib::Unit { field1: true }
      • 以及非窮盡模式匹配（即沒有尾隨 , .. 的模式）
    • 若介面穩定的話，儘量避免使用該註解

例子三：

lib.rs

#[non_exhaustive]
pub struct Config {
  pub window_width: u16,
  pub window_height: u16,
}

fn SomeFunction() {
  let config = Config {
    window_width: 640,
    window_height: 480,
  };
  
  // Non-exhaustive structs can be matched on exhaustively within the defining crate.
  if let Config {
    window_width,
    window_height,
  } = config
  {
    // ...
  }
}

main.rs

use constrained::Config;

fn main() {
  // Not allowed.
  let config =  Config {  // 報錯
    window_width: 640,
    window_height: 480,
  };
  
  if let Config {
    window_width,
    window_height,
    .. // This is the only difference. 必須加 .. 否則報錯
  } = config
  {
    // ...
  }
}

Trait 實現

  • 一致性規則禁止把某個 Trait 為某類型進行多重實現
  • 破壞性變更
    • 為現有 Trait 添加 Blanket Implementation 通常是破壞性變更（impl <T> Foo for T）
    • 為現有類型實現外部 Trait，或為外部類型實現現有 Trait
    • 移除 Trait 實現
      • 為新類型實現 Trait 就不是問題
  • 為現有類型實現任何 Trait 都要小心

例子四：

lib.rs

pub struct Unit;

pub trait Fool {
  fn foo(&self);
}

main.rs

use constrained::{Foo1, Unit};

trait Foo2 {
  fn foo(&self);
}

impl Foo2 for Unit {
  fn foo(&self) {
    println!("foo2");
  }
}

fn main() {
  Unit.foo()
}

修改一

lib.rs

pub struct Unit;

pub trait Fool {
  fn foo(&self);
}

// case 1: Add impl Foo1 for Unit in this crate
impl Foo1 for Unit {
  fn foo(&self) {
    println!("foo1");
  }
}

main.rs

use constrained::{Foo1, Unit};

trait Foo2 {
  fn foo(&self);
}

impl Foo2 for Unit {
  fn foo(&self) {
    println!("foo2");
  }
}

fn main() {
  Unit.foo() // 報錯
}

修改二

lib.rs

pub struct Unit;

pub trait Fool {
  fn foo(&self);
}

// case 2: Add a new public Trait
pub trait Bar1 {
  fn foo(&self); // with the same name
}

impl Bar1 for Unit {
  fn foo(&self) {
    println!("bar1");
  }
}

main.rs

use constrained::{Foo1, Unit};

trait Foo2 {
  fn foo(&self);
}

impl Foo2 for Unit {
  fn foo(&self) {
    println!("foo2");
  }
}

fn main() {
  Unit.foo()  // 因為沒有引入lib.rs中的Bar1，所以暫時沒有報錯
}

main.rs

use constrained::*;

trait Foo2 {
  fn foo(&self);
}

impl Foo2 for Unit {
  fn foo(&self) {
    println!("foo2");
  }
}

fn main() {
  Unit.foo()  // 報錯
}
  • 大多數到現有 Trait 的更改也是破壞性更改
    • 改變方法簽名
    • 添加新方法
      • 如果有預設實現倒是可以
  • 封閉 Trait（Sealed Trait）：
    • 只能被其它 crate 用，不能實現
    • 防止 Trait 添加新方法時造成破壞性變更
    • 不是內建功能，有多種實現方法
  • Sealed Trait 常用於派生 Trait
    • 為實現特定其它 Trait 的類型提供 blanket implementation 的 Trait
  • 封閉 Trait（Sealed Trait）：
    • 只有在外部 crate 不該實現你的 Trait 時，才使用 Sealed Trait
    • 嚴重限制 Trait 的可用性
      • 下游 crate 無法為其自己類型實現該 Trait
    • 可使用 Sealed Trait 來限制可用作類型參數的類型
      • 例：將 Rocket 示例中的 Stage 類型限製為僅允許 Grounded 和 Launched 類型

例子五：

lib.rs

use std::fmt::{Debug, Display};

mod sealed {
  use std::fmt::{Debug, Display};
  
  pug trait Sealed {}
  impl<T> Sealed for T where T: Debug + Display {}
}

pub trait CanUseCannotImplement: sealed::Sealed {
  // ..
}

impl<T> CanUseCannotImplement for T where T: Debug + Display {}

main.rs

use std::fmt::{Debug, Display};

use constrained::CanUseCannotImplement;
pub struct Bar {}

impl Debug for Bar {
  fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
    Ok(())
  }
}

impl Display for Bar {
  fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
    Ok(())
  }
}

// impl CanUseCannotImplement for Bar {}  // 報錯 因為在 lib.rs 中已經實現好了，不能再實現
// Conflicting implementation,
// The trait `CanUseCannotImplement` has been already implemented
// for the types that satisfy the bounds specified by the sealed trait which are `Debug + Display`

pub struct Foo {}

impl CanUseCannotImplement for Foo {} // 報錯 沒有實現 Debug 和 Display

fn main() {}

隱藏的契約

  • 有時，你對代碼的某一部分所做的更改會以微妙的方式影響到介面其他地方的契約。這種情況主要發生在：
    • 重新導出（re-exports）
    • 自動 Traits （auto-traits）

隱藏的契約 - 重新導出（Re-Exports）

  • 如果你的介面的某部分暴露了外部類型，那麼外部類型的任何更改也將成為你介面的變更
    • 最好用新類型模式（newtype pattern）包裹外部類型，僅僅暴露外部類型中你認為有用的部分

例子六：

lib.rs

// 你的 crate,叫 bestiter
pub fn iter<T>() -> itercrate::Empty<T> { .. }

// 依賴的外部 crate，叫 itercrate (v1.0)，提供了 Empty<T> 類型

// 用戶的 crate 中
struct EmptyIterator { it: itercrate::Empty<()> }

EmptyIterator { it: bestiter::iter() }

// ---------------------------------------------------------------
// 你的 crate, 叫 bestiter
pub fn iter<T>() -> itercrate::Empty<T> { .. }

// 依賴的外部crate，叫 itercrate，提供了 Empty<T> 類型
// 依賴的版本改為 v2.0，別處沒有更改
// 編譯器認為：itercrate1.0::Empty 和 itercrate2.0::Empty 是不同的類型
// 導致破壞性變更

// 用戶的 crate 中
struct EmptyIterator { it: itercrate::Empty<()> }

隱藏的契約 - 自動 Trait（Auto-Traits）

  • 有些 Trait 根據類型的內容，會對其進行實現
    • 根據它們的特性，它們為介面中幾乎每種類型都添加一個隱藏的承諾
    • Send、Sync
    • Unpin、Sized、UnwindSafe 也存在類似問題
    • 這些特性會傳播，無論是具體類型，還是 impl Trait 等類型擦除情況
  • 這些 Trait 的實現通常是編譯器自動添加的
    • 如果情況不適用，則不會自動添加
  • 例如：
    • 類型 A 包含私有類型 B，預設 A 和 B 都是 Send 的
    • 如果修改 B，讓 B 不再是 Send 的，那麼 A 也變成不 Send 的了
    • 破壞性變化
  • 這類變化難以追蹤和發現
    • 包含一些簡單的測試，檢查你所有的類型都實現了相關的 Traits

例子七：

fn is_normal<T: Sized + Send + Sync + Unpin>() {}

#[test]
fn normal_types() {
  is_normal::<MyType>();
}

設計 Rust 介面的總結

  • 不讓人感到意外、靈活的、顯而易見的和受限制的

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


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

-Advertisement-
Play Games
更多相關文章
  • 基於Redis實現查找附近的人/排行榜
    引言 在日常使用的有些APP中，想什麼微信，百度地圖，可以可以搜尋附近的人，距離自己多遠，以及在地圖上我們可以搜索附近的某個地點，距離自己的位置。針對這種類似的功能，我們可以通過redis就能實現。 redis在3.2版本之後也提供了地理位置的能力，使用redis可以輕鬆實現查找附近的人 一：附近的 ...
  • keycloak~CountDownLatch在keycloak中的使用
    # 概念 在Java中，`CountDownLatch`是一個線程同步的輔助類，用於等待其他線程完成操作。如果`CountDownLatch`實例被丟失或無法訪問，可能會導致無法正常使用該對象。這可能會導致等待線程永遠處於等待狀態，無法繼續執行。 如果意外丟失了`CountDownLatch`對象， ...
  • 通用密鑰,無需密碼,在無密碼元年實現Passkeys通用密鑰登錄(基於Django4.2/Python3.10)
    毋庸諱言，密碼是極其偉大的發明，但拜病毒和黑客所賜，一旦密碼泄露，我們就得絞盡腦汁再想另外一個密碼，但記憶力並不是一個靠譜的東西，一旦遺忘密碼，也會造成嚴重的後果，2023年業界巨頭Google已經率先支持了Passkeys登錄方式，只須在設備上利用PIN碼解鎖、指紋或面部辨識等生物識別方式，即可驗 ...
  • 【numpy基礎】--通用計算
    `numpy`提供了簡單靈活的介面，用於優化數據數組的計算。 通用計算最大的優勢在於通過向量化操作，將迴圈推送至`numpy`之下的編譯層，從而取得更快的執行效率。 `numpy`的通用計算讓我們計算數組時就像計算單獨一個變數一樣， 不用寫迴圈去遍曆數組中的各個元素。 比如，對於一般的`python ...
  • springboot啟動流程 (3) 自動裝配
    在SpringBoot中，EnableAutoConfiguration註解用於開啟自動裝配功能。 本文將詳細分析該註解的工作流程。 # EnableAutoConfiguration註解 啟用SpringBoot自動裝配功能，嘗試猜測和配置可能需要的組件Bean。 自動裝配類通常是根據類路徑和定義 ...
  • Spring源碼核心剖析
    SpringAOP作為Spring最核心的能力之一，其重要性不言而喻。然後需要知道的是AOP並不只是Spring特有的功能，而是一種思想，一種通用的功能。而SpringAOP只是在AOP的基礎上將能力集成到SpringIOC中，使其作為bean的一種，從而我們能夠很方便的進行使用。 ...
  • 【python基礎】類-類屬性
    在初始類中，我們介紹瞭如何訪問類屬性，除了訪問類屬性外還有其他操作類屬性的情況，我們將在這裡做詳細介紹： # 1.給類屬性指定預設值 類中的每個屬性都必須有初始值，哪怕這個值是0或者空字元串。在有些情況下，如設置預設值時，在方法\_\_init\_\_方法內指定這種初始值是可行的，如果對某個屬性這樣 ...
  • SLF4J門面日誌框架源碼探索
    我們通過代碼入手，層層加碼，直觀感受SLF4J列印日誌，並跟蹤代碼追本溯源。主要瞭解，SLF4J是如何作為門面和其他日誌框架進行解耦。 ...
一周排行
    -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.數據驗證 在伺服器端進行嚴格的數據驗證，確保接收到的數據符合預期格 ...
所有分類