Rust 提供了便捷的檔案操作 API，讓開發者能輕鬆管理檔案路徑。相較於直接操作字串，使用 Path 更具可移植性，能避免因不同作業系統路徑差異產生的問題，同時也更易於除錯。本文將以 ActionKV 專案為例，示範如何使用 Rust 的 Path 和 HashMap 等功能，實作一個具備命令列介面的 key-value 儲存系統。ActionKV 採用日誌結構、僅附加的儲存架構，兼顧高韌性和讀取效能。我們將逐步解析程式碼，從檔案操作、命令列引數處理到核心 CRUD 操作，深入探討 ActionKV 的設計理念和實作細節。
檔案操作在 Rust
Rust 的檔案操作 API 相當直接，對於曾經使用過程式碼操控路徑的人來說，非常容易上手。雖然如此，瞭解為什麼這些功能被包含在語言中仍然很重要，因為許多語言並沒有將檔案操作納入其中。
使用 Path 而非直接操控字串的理由
以下是使用 Path 的好處：
- 明確意圖：
Path提供了像set_extension()這樣的方法，可以清晰地描述操作的意圖，幫助後續維護程式碼的人員理解程式碼的目的。直接操控字串則缺乏這種自我檔案化的能力。 - 可移植性：不同的作業系統對檔案系統路徑的處理方式不同，有些是大小寫不敏感的，而有些則不是。如果使用某個作業系統的慣例，可能會導致在其他系統上出現問題。此外，路徑分隔符也依賴於作業系統，使用 raw 字串可能導致可移植性問題。
- 更容易除錯：如果您嘗試從路徑
/tmp/hello.txt中提取/tmp，手動操作可能會引入微妙的 bug，這些 bug 只有在執行時才會出現。另外，誤計分隔符/後的索引值可能導致編譯時無法捕捉到的 bug。
路徑分隔符的差異
不同的作業系統使用不同的路徑分隔符，例如：
\在 MS Windows 中常用。/是 UNIX-like 作業系統的慣例。:曾經是 classic Mac OS 的路徑分隔符。>是 Stratus VOS 作業系統使用的分隔符。
比較 std::String 和 std::path::Path
以下是使用 std::String 和 std::path::Path 提取檔案父目錄的比較：
// 使用 std::String
fn main() {
let hello = String::from("/tmp/hello.txt");
let tmp_dir = hello.split("/").nth(0);
println!("{:?}", tmp_dir);
}
// 使用 std::path::PathBuf
use std::path::PathBuf;
fn main() {
let mut hello = PathBuf::from("/tmp/hello.txt");
hello.pop();
println!("{:?}", hello.display());
}
第一個範例嘗試使用 split() 方法分割字串，並取出第一個元素作為父目錄。然而，這種方法可能會導致錯誤，因為它依賴於手動計算索引值。
第二個範例使用 PathBuf 來代表路徑，並使用 pop() 方法移除最後一個路徑元件，然後使用 display() 方法列印預出父目錄。這種方法更為可靠和安全。
實作一個 key-value 儲存系統
現在，我們將開始實作一個 key-value 儲存系統，使用 log-structured, append-only 的儲存架構。這種架構設計用於提供極高的韌性和最佳的讀取效能，即使在儲存媒介如 flash 儲存或硬碟驅動器等不可靠的媒介上，也能夠保證資料不會丟失，備份的資料檔案也不會被破壞。
這種架構的優點在於其簡單性和效率，使其成為許多資料函式庫系統的基礎。透過瞭解這種架構，我們可以更好地掌握資料函式庫技術的內部工作原理。
7.5.1 鍵值模型
actionkv 是一個鍵值儲存系統，儲存和檢索任意長度的 byte 序列（[u8]）。每個序列由兩部分組成：第一部分是鍵，第二部分是值。由於 &str 型別在內部被表示為 [u8]，表 7.5 顯示的是純文字表示法，而不是二進位制等效表示法。
鍵值模型使得簡單的查詢成為可能，例如「斐濟的首都是什麼？」但是，它不支援更廣泛的查詢，例如「太平洋島國的首都列表是什麼？」
7.5.2 引入 actionkv v1：一個具有命令列介面的記憶體鍵值儲存
actionkv 的第一個版本向我們介紹了將在整個章節中使用的 API，並且引入了主要的函式庫程式碼。函式庫程式碼在隨後的兩個系統中不會發生變化。在那之前，有一些需要涵蓋的先決條件。
使用 plain String 程式碼可以讓您使用熟悉的方法，但是它可能導致難以在編譯時期檢測到的細微 bug。在這種情況下，我們使用了錯誤的索引號來存取父目錄（/tmp）。使用 path::Path 不會使您的程式碼免疫於細微的錯誤，但是它可以幫助最小化這些錯誤的可能性。Path 提供了針對常見操作的專用方法，例如設定檔案的副檔名。
表 7.5 展示了鍵和值的示例：
| 鍵 | 值 |
|---|---|
| Cook Islands | Avarua |
| 斐濟 | Suva |
| 吉里巴斯 | South Tarawa |
| 紐埃 | Alofi |
實作具有日誌結構、附加儲存架構的鍵值儲存
與本文中的其他專案不同，這個專案使用函式庫範本啟動（cargo new –lib actionkv）。它具有以下結構：
actionkv ├── src │ ├── akv_mem.rs │ └── lib.rs └── Cargo.toml
使用函式庫 crate 可以讓程式設計師在專案中構建可重用的抽象。為了我們的目的，我們將使用相同的 lib.rs 檔案為多個可執行檔案提供服務。為了避免未來的歧義，我們需要描述 actionkv 專案產生的可執行二進位制檔案。
為此，提供一個 bin 節點在兩個方括號對（[[bin]]) 中，位於專案的 Cargo.toml 檔案中。請參閱以下清單中的第 14-16 行。兩個方括號表示該節點可以重複。該清單的原始碼位於 ch7/ch7-actionkv/Cargo.toml。
1 [package] 2 name = “actionkv” 3 version = “1.0.0” 5 edition = “2018” 6 7 [dependencies] 8 byteorder = “1.2” 9 crc = “1.7” 10 11 [lib] 12 name = “libactionkv” 13 path = “src/lib.rs”
flowchart TD
A[開始] --> B[實作鍵值儲存]
B --> C[定義鍵值模型]
C --> D[實作 actionkv v1]
D --> E[定義函式庫程式碼]
E --> F[構建可執行二進位制檔案]
圖表翻譯：
此圖表展示了實作鍵值儲存的步驟。首先，定義鍵值模型，然後實作 actionkv v1，接著定義函式庫程式碼，最後構建可執行二進位制檔案。每個步驟都對應到實作鍵值儲存的不同階段。
ActionKV 專案結構與設計
ActionKV 是一個根據 Rust 的 key-value 儲存系統，旨在提供一個簡單易用的 API 來儲存和查詢資料。以下是 ActionKV 專案的結構和設計概覽。
專案結構
ActionKV 專案由多個檔案組成，包括 Cargo.toml、src/lib.rs 和 src/akv_mem.rs。其中，Cargo.toml 檔案定義了專案的依賴關係和其他相關組態，src/lib.rs 檔案包含了 ActionKV 的核心程式碼，而 src/akv_mem.rs 檔案則實作了 ActionKV 的記憶體儲存功能。
ActionKV API
ActionKV 提供了一個簡單易用的 API 來儲存和查詢資料，包括四個基本操作：get、insert、delete 和 update。這些操作可以透過命令列引數來呼叫，並使用 Rust 的模式匹配機制來高效地分派到正確的內部函式。
記憶體儲存實作
ActionKV 的記憶體儲存功能實作於 src/akv_mem.rs 檔案中，使用 Rust 的 HashMap 來儲存 key-value 對。這個實作提供了一個簡單易用的 API 來儲存和查詢資料，並且可以高效地處理大量資料。
依賴關係
ActionKV 專案依賴於多個外部函式庫，包括 serde 和 checksum。其中，serde 用於序列化和反序列化資料，而 checksum 則用於計算資料的校驗和。
Cargo.toml 組態
Cargo.toml 檔案定義了 ActionKV 專案的依賴關係和其他相關組態，包括專案名稱、版本號和依賴函式庫等。以下是 Cargo.toml 檔案的一個摘錄：
[package]
name = "actionkv"
version = "0.1.0"
[dependencies]
serde = { version = "1.0", features = ["derive"] }
checksum = "1.0.0"
命令列引數處理
ActionKV 使用 Rust 的模式匹配機制來高效地處理命令列引數，並分派到正確的內部函式。以下是命令列引數處理的一個摘錄：
fn main() {
let args: Vec<String> = env::args().collect();
match args[1].as_str() {
"get" => get(args[2].clone()),
"insert" => insert(args[2].clone(), args[3].clone()),
"delete" => delete(args[2].clone()),
"update" => update(args[2].clone(), args[3].clone()),
_ => println!("Invalid command"),
}
}
記憶體儲存 API
ActionKV 的記憶體儲存 API 提供了一個簡單易用的 API 來儲存和查詢資料，包括四個基本操作：get、insert、delete 和 update。以下是記憶體儲存 API 的一個摘錄：
pub fn get(key: String) -> Option<String> {
//...
}
pub fn insert(key: String, value: String) {
//...
}
pub fn delete(key: String) {
//...
}
pub fn update(key: String, value: String) {
//...
}
Actionkv 專案概覽
Actionkv 是一個根據 Rust 的專案，使用 Cargo 作為其包管理器。Cargo.toml 檔案是該專案的核心組態檔案，負責協調各個模組和依賴項之間的關係，最終生成可執行檔案。
Actionkv v1: 前端程式碼
以下是 Actionkv v1 版本的前端程式碼片段：
match action {
"get" => match store.get(key).unwrap() {
None => eprintln!("{:?} not found", key),
Some(value) => println!("{:?}", value),
},
"delete" => store.delete(key).unwrap(),
"insert" => {
let value = maybe_value.expect(&USAGE).as_ref();
store.insert(key, value).unwrap()
}
"update" => {
let value = maybe_value.expect(&USAGE).as_ref();
//...
}
}
這段程式碼使用 match 陳述式來處理不同的動作（action），包括「get」、「delete」、「insert」和「update」。每個動作都會呼叫對應的方法，例如 store.get()、store.delete()、store.insert() 等。
內容解密：
match陳述式是 Rust 中的一種控制流程陳述式，用於根據不同的值執行不同的程式碼塊。store.get(key).unwrap()方法會從儲存函式庫中取出與給定鍵（key）相關的值，如果找不到則會傳回None。eprintln!宏用於列印錯誤資訊，{:?}是一個格式化字串，會將鍵（key）以 debug 格式列印預出來。maybe_value.expect(&USAGE).as_ref()方法會從maybe_value中取出值，如果是None則會傳回錯誤資訊。store.insert(key, value).unwrap()方法會將給定的鍵（key）和值（value）插入到儲存函式庫中，如果操作失敗則會傳回錯誤資訊。
圖表翻譯：
flowchart TD
A[開始] --> B[取得動作]
B --> C{動作型別}
C -->|get| D[取得值]
C -->|delete| E[刪除值]
C -->|insert| F[插入值]
C -->|update| G[更新值]
D --> H[列印值]
E --> I[刪除成功]
F --> J[插入成功]
G --> K[更新成功]
這個流程圖描述了 Actionkv 專案中不同動作之間的關係，以及每個動作的執行流程。
ActionKV 的實作細節
在上述程式碼中，我們可以看到 ActionKV 的實作細節。首先，程式碼定義了一個 USAGE 常數，該常數包含了使用 akv_mem 執行檔的指令。
接下來，程式碼使用 libactionkv 函式庫中的 ActionKV 類別，該類別負責與檔案系統進行互動。ActionKV 的例項被稱為 store，它負責處理所有與檔案系統相關的工作。
在 match 陳述式中，程式碼根據使用者輸入的指令進行不同的操作。例如，如果使用者輸入 get 指令，程式碼就會呼叫 store.get() 方法來從檔案系統中讀取資料。如果使用者輸入 insert 指令，程式碼就會呼叫 store.insert() 方法來將資料寫入檔案系統中。
值得注意的是，程式碼使用 unwrap() 方法來處理可能的錯誤。如果發生錯誤，程式碼就會終止執行並顯示錯誤訊息。
ActionKV 的運作原理
ActionKV 的運作原理在第 7.7 節中有詳細的解釋。簡單來說，ActionKV 是一個負責與檔案系統進行互動的類別，它提供了基本的 CRUD（Create、Read、Update、Delete）操作。
程式碼解析
以下是程式碼的詳細解析：
- 第 1 行：匯入
libactionkv函式庫中的ActionKV類別。 - 第 3 行：定義了一個
USAGE常數，該常數包含了使用akv_mem執行檔的指令。 - 第 12 行：使用
match陳述式來根據使用者輸入的指令進行不同的操作。 - 第 47 行：呼叫
store.update()方法來更新檔案系統中的資料。
Mermaid 圖表
flowchart TD
A[開始] --> B[讀取使用者輸入]
B --> C{判斷指令}
C -->|get| D[呼叫 store.get()]
C -->|insert| E[呼叫 store.insert()]
C -->|update| F[呼叫 store.update()]
C -->|delete| G[呼叫 store.delete()]
D --> H[顯示結果]
E --> H
F --> H
G --> H
圖表翻譯
上述 Mermaid 圖表展示了程式碼的運作流程。首先，程式碼讀取使用者輸入的指令。然後，根據指令的不同，程式碼呼叫不同的方法來與檔案系統進行互動。最後，程式碼顯示結果給使用者。
內容解密
在上述程式碼中，我們可以看到 ActionKV 類別的實作細節。ActionKV 類別負責與檔案系統進行互動，它提供了基本的 CRUD 操作。程式碼使用 match 陳述式來根據使用者輸入的指令進行不同的操作。每個操作都呼叫不同的方法來與檔案系統進行互動。例如，get 指令呼叫 store.get() 方法來從檔案系統中讀取資料。insert 指令呼叫 store.insert() 方法來將資料寫入檔案系統中。以此類別推。
值得注意的是，程式碼使用 unwrap() 方法來處理可能的錯誤。如果發生錯誤，程式碼就會終止執行並顯示錯誤訊息。
使用 Akv_mem 的命令列應用程式
Akv_mem 是一個簡單的鍵值儲存系統，提供基本的 CRUD（Create、Read、Update、Delete）操作。以下是使用 Akv_mem 的命令列應用程式的範例：
命令列引數
Akv_mem 的命令列應用程式接受以下引數：
FILE：儲存檔案的路徑。get：取得鍵值。delete：刪除鍵值。insert：插入鍵值。update：更新鍵值。
使用範例
以下是使用 Akv_mem 的命令列應用程式的範例：
akv_mem example.txt get my_key
akv_mem example.txt delete my_key
akv_mem example.txt insert my_key my_value
akv_mem example.txt update my_key new_value
Rust 程式碼
以下是 Akv_mem 的命令列應用程式的 Rust 程式碼：
const USAGE: &str = "
Usage:
akv_mem FILE get KEY
akv_mem FILE delete KEY
akv_mem FILE insert KEY VALUE
akv_mem FILE update KEY VALUE
";
fn main() {
let args: Vec<String> = std::env::args().collect();
let fname = args.get(1).expect(&USAGE);
//...
}
在這個範例中，USAGE 是一個常數字串，定義了 Akv_mem 的命令列引數。main 函式收集命令列引數，並取得儲存檔案的路徑 fname。
注意，在這個範例中，我們使用 std::env::args() 來收集命令列引數，並使用 expect() 來處理錯誤。如果命令列引數不正確，程式將印出 USAGE 字串並終止。
命令列引數處理
在 Rust 中，我們可以使用 std::env::args() 來收集命令列引數。以下是如何處理命令列引數的範例：
let args: Vec<String> = std::env::args().collect();
let fname = args.get(1).expect(&USAGE);
let action = args.get(2).expect(&USAGE);
let key = args.get(3).expect(&USAGE);
let value = args.get(4);
在這個範例中，我們收集命令列引數，並取得儲存檔案的路徑 fname、動作 action、鍵 key 和值 value。
注意，在這個範例中，我們使用 expect() 來處理錯誤。如果命令列引數不正確，程式將印出 USAGE 字串並終止。
內容解密：
在這個範例中，我們使用 std::env::args() 來收集命令列引數，並使用 expect() 來處理錯誤。這是一種簡單的方式來處理命令列引數，但在實際應用中，我們可能需要更複雜的錯誤處理機制。
圖表翻譯：
flowchart TD
A[開始] --> B[收集命令列引數]
B --> C[取得儲存檔案路徑]
C --> D[取得動作]
D --> E[取得鍵]
E --> F[取得值]
F --> G[執行動作]
在這個圖表中，我們展示瞭如何處理命令列引數的流程。首先，我們收集命令列引數，然後取得儲存檔案路徑、動作、鍵和值。最後，我們執行動作。
注意，在這個圖表中，我們使用 Mermaid 來繪製流程圖。Mermaid 是一種簡單的繪圖語言，允許我們使用文字來繪製圖表。
檔案與儲存
在 Rust 中，檔案和儲存是非常重要的主題。讓我們深入探討如何使用 Rust 來操作檔案和儲存。
檔案路徑
首先，我們需要了解如何在 Rust 中表示檔案路徑。Rust 提供了 std::path::Path 類別來表示檔案路徑。下面的程式碼示範瞭如何建立一個檔案路徑：
let path = std::path::Path::new(&fname);
這裡，fname 是檔案名稱，std::path::Path::new 函式會建立一個新的檔案路徑。
開啟檔案
要開啟檔案，需要使用 ActionKV::open 函式。這個函式會傳回一個 ActionKV 例項，代表檔案的內容。下面的程式碼示範瞭如何開啟檔案：
let mut store = ActionKV::open(path).expect("unable to open file");
這裡，ActionKV::open 函式會嘗試開啟檔案，如果失敗，則會傳回一個錯誤訊息。
載入資料
要載入檔案的內容，需要使用 store.load 函式。下面的程式碼示範瞭如何載入資料：
store.load().expect("unable to load data");
這裡，store.load 函式會嘗試載入檔案的內容，如果失敗，則會傳回一個錯誤訊息。
處理命令列引數
要處理命令列引數，需要使用 args.get 函式。下面的程式碼示範瞭如何取得命令列引數：
let action = args.get(2).expect(&USAGE).as_ref();
let key = args.get(3).expect(&USAGE).as_ref();
let maybe_value = args.get(4);
這裡，args.get 函式會傳回命令列引數的值，如果引數不存在，則會傳回一個錯誤訊息。
處理動作
要處理動作，需要使用 match 陳述式。下面的程式碼示範瞭如何處理動作：
match action {
"get" => match store.get(key).unwrap() {
None => eprintln!("{:?} not found", key),
Some(value) => println!("{:?}", value),
},
}
這裡，match 陳述式會根據動作的型別來執行不同的程式碼。如果動作是 “get”，則會嘗試取得檔案的內容，如果找不到，則會印出錯誤訊息。
圖表翻譯：
flowchart TD
A[取得命令列引數] --> B[開啟檔案]
B --> C[載入資料]
C --> D[處理動作]
D --> E[取得檔案內容]
E --> F[印出結果]
內容解密：
上述程式碼示範瞭如何使用 Rust 來操作檔案和儲存。首先，需要取得命令列引數，然後開啟檔案，載入資料，最後處理動作並取得檔案內容。這個過程需要使用 std::path::Path 類別來表示檔案路徑，ActionKV::open 函式來開啟檔案，store.load 函式來載入資料，match 陳述式來處理動作。
使用 Rust 進行簡單的鍵值儲存操作
以下是使用 Rust 進行簡單的鍵值儲存操作的範例。這個範例展示瞭如何根據使用者的輸入執行不同的操作，包括刪除、插入和更新。
程式碼
use std::collections::HashMap;
fn main() {
let mut store: HashMap<String, String> = HashMap::new();
let mut input = String::new();
loop {
println!("請輸入命令（delete、insert、update）：");
std::io::stdin().read_line(&mut input).expect("Failed to read line");
let command = input.trim();
input.clear();
match command {
"delete" => {
println!("請輸入鍵：");
std::io::stdin().read_line(&mut input).expect("Failed to read line");
let key = input.trim().to_string();
input.clear();
store.remove(&key);
println!("刪除成功！");
}
"insert" => {
println!("請輸入鍵：");
std::io::stdin().read_line(&mut input).expect("Failed to read line");
let key = input.trim().to_string();
input.clear();
println!("請輸入值：");
std::io::stdin().read_line(&mut input).expect("Failed to read line");
let value = input.trim().to_string();
input.clear();
store.insert(key, value);
println!("插入成功！");
}
"update" => {
println!("請輸入鍵：");
std::io::stdin().read_line(&mut input).expect("Failed to read line");
let key = input.trim().to_string();
input.clear();
println!("請輸入新值：");
std::io::stdin().read_line(&mut input).expect("Failed to read line");
let value = input.trim().to_string();
input.clear();
if let Some(old_value) = store.get_mut(&key) {
*old_value = value;
println!("更新成功！");
} else {
println!("鍵不存在！");
}
}
_ => {
println!("無效命令，請重新輸入！");
}
}
}
}
內容解密
上述程式碼使用 HashMap 來實作簡單的鍵值儲存。根據使用者的輸入，程式碼會執行不同的操作：
delete：刪除指定鍵的值。insert：插入新的鍵值對。update：更新指定鍵的值。
每個操作都會先要求使用者輸入相關的鍵和值，然後根據使用者的輸入執行相應的操作。
圖表翻譯
flowchart TD
A[開始] --> B[輸入命令]
B --> C{命令判斷}
C -->|delete| D[刪除]
C -->|insert| E[插入]
C -->|update| F[更新]
D --> G[刪除成功]
E --> H[插入成功]
F --> I{鍵存在判斷}
I -->|存在| J[更新成功]
I -->|不存在| K[鍵不存在]
J --> L[結束]
K --> L
G --> L
H --> L
上述流程圖展示了程式碼的執行流程。根據使用者的輸入，程式碼會執行不同的操作，並給出相應的反饋。
從系統架構的視角來看，Rust 的檔案操作 API 提供了比直接字串操作更安全、更跨平臺的解決方案。Path 的使用強化了程式碼意圖，並避免了因路徑分隔符差異和手動索引計算帶來的潛在錯誤。深入分析 std::String 和 std::path::Path 的比較，更凸顯了 Path 在處理路徑操作時的優勢，有效降低了錯誤發生的機率。然而，Path 並非完美無缺，例如在處理複雜路徑拼接時仍需仔細考量效能。ActionKV 專案的設計，利用 Rust 的語言特性，實作了一個根據日誌結構、附加式儲存架構的鍵值儲存系統。其命令列介面簡潔易用，記憶體儲存的實作也展現了 Rust 在處理資料結構時的效率。但目前版本仍侷限於記憶體操作，缺乏持久化儲存機制。展望未來，ActionKV 的發展方向應著重於資料持久化、效能最佳化以及更豐富的查詢功能。對於追求高效能且可靠的鍵值儲存解決方案的開發者而言，持續關注 ActionKV 的發展將大有裨益。玄貓認為，ActionKV 的設計理念值得借鑒，其在 Rust 生態系統中的發展潛力巨大。
