Rust 實務專案與最佳實踐：安全編碼實踐

---

簡介

在現代系統開發中，安全性往往是最先被檢視的指標之一。Rust 之所以在近年迅速崛起，正是因為它在編譯期就能捕捉大多數記憶體安全問題，讓開發者可以在不犧牲效能的前提下，寫出 「不會產生未定義行為」 的程式碼。

本單元的 安全編碼實踐 旨在說明如何在實務專案中善用 Rust 的所有權、借用檢查、型別系統與標準函式庫，避免常見的安全漏洞，並提供可直接套用的範例與最佳實踐。即使你是剛接觸 Rust 的初學者，或是已有一定經驗的中級開發者，都能從本文獲得具體可執行的建議。

---

核心概念

1. 所有權與借用（Ownership & Borrowing）

Rust 的所有權模型是安全編碼的根基。每個值都有唯一的 所有者（owner），所有者離開作用域時，值會被自動釋放（drop）。同時，借用（borrowing）允許在不取得所有權的情況下讀取或修改資料，分為 不可變借用（&T）與 可變借用（&mut T）。

為什麼重要？

• 防止 雙重釋放（double free）與 使用已釋放的記憶體（use-after-free）。
• 編譯器在編譯期就能檢查 資料競爭（data race），保證多執行緒程式的安全性。

範例 1：避免雙重釋放

fn main() {
    let s = String::from("Rust 安全");
    // let s2 = s; // 這裡若寫成 `let s2 = s;`，s 的所有權會被移動
    // println!("{}", s); // 編譯錯誤：s 已被移動
    let s2 = s.clone(); // 使用 clone 產生深拷貝，兩者各自擁有所有權
    println!("s2 = {}", s2);
}

註解：clone 會在堆上分配新記憶體，避免所有權移動導致的使用錯誤。

---

2. 不可變性（Immutability）與安全的可變性

Rust 預設變數是 不可變（let x = ...），必須顯式加上 mut 才能變更。這樣的設計鼓勵 資料不可變 的思考方式，減少意外的狀態改變。

範例 2：使用不可變參考避免競爭條件

use std::thread;

fn main() {
    let data = vec![1, 2, 3, 4, 5];
    let mut handles = vec![];

    for i in 0..5 {
        // 只傳遞不可變參考，保證每個執行緒只能讀取
        let slice = &data[i];
        let handle = thread::spawn(move || {
            println!("thread {} sees {}", i, slice);
        });
        handles.push(handle);
    }

    for h in handles {
        h.join().unwrap();
    }
}

註解：若改成 &mut data[i]，編譯器會報錯，因為同時有多個可變借用會產生資料競爭。

---

3. Result 與錯誤處理（Error Handling）

Rust 沒有例外機制，錯誤資訊透過 Result<T, E> 型別傳遞。顯式處理錯誤 能讓開發者在每一次可能失敗的操作上都思考如何回應，避免錯誤被忽略而導致安全漏洞。

範例 3：安全的檔案 I/O

use std::fs::File;
use std::io::{self, Read};

fn read_file(path: &str) -> io::Result<String> {
    let mut file = File::open(path)?; // 若檔案不存在，錯誤會立即傳回
    let mut contents = String::new();
    file.read_to_string(&mut contents)?; // 讀取過程中若出錯，同樣傳回 Err
    Ok(contents)
}

fn main() {
    match read_file("config.toml") {
        Ok(text) => println!("檔案內容:\n{}", text),
        Err(e) => eprintln!("讀取失敗: {}", e),
    }
}

註解：? 運算子會自動將 Err 轉換為函式的返回值，讓錯誤傳遞變得簡潔且不易遺漏。

---

4. unsafe 區塊的最小化

unsafe 允許繞過編譯器的安全檢查，直接使用裸指標、呼叫外部 C 函式等。最佳實踐是將 unsafe 程式碼封裝在小且明確的模組中，並在上層提供安全的抽象介面。

範例 4：安全封裝 unsafe 計算

/// 一個簡單的向量長度計算，使用 SIMD 指令（僅示意，實際需要 target_feature）
pub fn dot_product(a: &[f32], b: &[f32]) -> f32 {
    assert_eq!(a.len(), b.len());
    unsafe { dot_product_unchecked(a, b) }
}

unsafe fn dot_product_unchecked(a: &[f32], b: &[f32]) -> f32 {
    // 假設此處呼叫了底層的 SIMD 指令，必須保證長度相等且指標有效
    let mut sum = 0.0;
    for i in 0..a.len() {
        sum += *a.get_unchecked(i) * *b.get_unchecked(i);
    }
    sum
}

註解：外部呼叫者只能使用 dot_product，而 unsafe 內部實作被嚴格限制在同一檔案，降低錯誤擴散的風險。

---

5. 防止資料競爭（Data Races）與同步原語

Rust 的型別系統保證 在同一時間只能有一個可變借用，因此在多執行緒環境下，資料競爭會在編譯期被捕捉。若需要共享可變資料，必須使用同步原語（Mutex、RwLock）或原子類型（AtomicUsize）。

範例 5：使用 Arc<Mutex<T>> 安全共享狀態

use std::sync::{Arc, Mutex};
use std::thread;

fn main() {
    let counter = Arc::new(Mutex::new(0usize));
    let mut handles = vec![];

    for _ in 0..10 {
        let cnt = Arc::clone(&counter);
        let handle = thread::spawn(move || {
            // 取得鎖定後才可修改
            let mut num = cnt.lock().unwrap();
            *num += 1;
        });
        handles.push(handle);
    }

    for h in handles {
        h.join().unwrap();
    }

    println!("最終計數: {}", *counter.lock().unwrap());
}

註解：Arc 提供多執行緒共享所有權，Mutex 確保同一時間只有一個執行緒能寫入 counter，避免資料競爭。

---

常見陷阱與最佳實踐

常見陷阱	可能產生的問題	推薦的解決方式
過度使用 clone	產生不必要的記憶體拷貝，降低效能	使用 借用 (&T) 或 引用計數 (Rc/Arc) 取代
在 unsafe 中忘記檢查邊界	產生緩衝區溢位（buffer overflow）	封裝 unsafe 為私有函式，並在外層加入 assert 或 檢查
忽略 Result	錯誤被吞掉，導致未預期行為或資源泄漏	使用 ? 或明確 match，在適當層級記錄或回報錯誤
在多執行緒中直接共享 &mut	編譯錯誤或資料競爭	使用 同步原語（Mutex、RwLock）或 原子類型
過度依賴 unwrap	產生 panic，尤其在生產環境	改用 expect 加上明確訊息，或使用 match 處理錯誤

進階最佳實踐

1. 最小化 unsafe 範圍

   • 把所有 unsafe 放在單一模組或檔案，並提供安全的公共 API。
   • 為每個 unsafe 函式寫 單元測試，確保前置條件（preconditions）被正確驗證。

2. 使用 cargo clippy 與 rustfmt

   • clippy 能自動偵測潛在的安全問題（如未使用的 Result、過度的 clone）。
   • rustfmt 確保程式碼風格一致，減少因格式不當造成的閱讀錯誤。

3. 審視外部 Crate 的安全性

   • 優先選擇已通過 安全審計（security audit）的 crate。
   • 若使用 unsafe crate，請仔細閱讀其文件與測試，必要時自行加入 wrapper。

4. 啟用編譯器的安全警告

   # Cargo.toml
   [profile.release]
   overflow-checks = true   # 整數溢位檢查
   debug-assertions = false
   

   • 在 Release 模式下仍保留溢位檢查，可防止因整數溢位導致的安全漏洞。

---

實際應用場景

1. 網路服務的請求處理

在高併發的 HTTP 伺服器中，使用 hyper + tokio 時，所有的請求資料都以 不可變參考 方式傳遞給各個 handler。若需要共享可變狀態（如計數器、快取），會使用 Arc<RwLock<HashMap>>，確保同時多讀、單寫的安全性。

use std::collections::HashMap;
use std::sync::{Arc, RwLock};
use hyper::{Body, Request, Response, Server};
use hyper::service::{make_service_fn, service_fn};

type Cache = Arc<RwLock<HashMap<String, String>>>;

async fn handler(req: Request<Body>, cache: Cache) -> Result<Response<Body>, hyper::Error> {
    let key = req.uri().path().to_string();
    // 只讀快取
    if let Some(value) = cache.read().unwrap().get(&key) {
        return Ok(Response::new(Body::from(value.clone())));
    }
    // 若未命中，模擬產生資料
    let value = format!("Generated for {}", key);
    cache.write().unwrap().insert(key, value.clone());
    Ok(Response::new(Body::from(value)))
}

2. 嵌入式系統的硬體存取

在嵌入式開發中，必須直接操作記憶體映射的暫存器。此時會使用 volatile 與 unsafe，但仍遵循 封裝 原則，只在 hal（硬體抽象層）模組內使用 unsafe，外層提供安全的 API。

pub mod hal {
    const GPIO_BASE: usize = 0x4002_1000;

    #[inline(always)]
    pub fn set_pin(pin: u8) {
        unsafe {
            core::ptr::write_volatile((GPIO_BASE + pin as usize) as *mut u32, 1);
        }
    }

    #[inline(always)]
    pub fn clear_pin(pin: u8) {
        unsafe {
            core::ptr::write_volatile((GPIO_BASE + pin as usize) as *mut u32, 0);
        }
    }
}

3. 金融系統的交易處理

金融系統要求 零容錯（zero tolerance） 的錯誤處理。使用 Result 搭配自訂錯誤型別，將所有可能的失敗情境列舉清楚，並在每筆交易結束前必須呼叫 commit 或 rollback，確保資料一致性。

#[derive(Debug)]
enum TxError {
    InsufficientFunds,
    NetworkError,
    DatabaseError,
}

fn process_transaction(amount: i64) -> Result<(), TxError> {
    // 檢查餘額
    if amount > get_balance()? {
        return Err(TxError::InsufficientFunds);
    }
    // 模擬外部服務呼叫
    external_service()?.send(amount)?;
    // 最後寫入資料庫
    db::record_transaction(amount).map_err(|_| TxError::DatabaseError)
}

---

總結

安全編碼是 Rust 的核心價值，也是每一個實務專案不可或缺的基礎。透過 所有權與借用、不可變性、顯式錯誤處理、最小化 unsafe 以及 同步原語，開發者可以在編譯期就捕捉大部分的安全缺陷，減少在部署後才發現漏洞的風險。

在日常開發中，遵守以下幾點即可大幅提升程式的安全性：

1. 盡量使用不可變參考，僅在必要時才使用 mut。
2. 每一次可能失敗的操作 都回傳 Result，並使用 ? 或 match 處理。
3. 將所有 unsafe 包裝在私有模組，提供安全的公共 API。
4. 使用 Arc、Mutex、RwLock 等同步原語，避免資料競爭。
5. 持續使用 cargo clippy、rustfmt，並審視第三方 crate 的安全性。

掌握這些概念與實踐方法，你將能在 Rust 專案中寫出 安全、可靠且高效 的程式碼，為未來的系統穩定性奠定堅實的基礎。祝你在 Rust 的旅程中寫出更多安全且優雅的程式！