與人類溝通

請務必先閱讀教學中的 CLI 輸出章節。此章節涵蓋如何撰寫終端機輸出，而本章節將探討輸出什麼內容。

當一切順利時

即使一切順利，仍建議記錄應用程式的進度。務必在這些訊息中提供資訊並簡潔扼要。請勿在記錄中使用過於專業的術語。請記住：應用程式並未崩潰，因此使用者沒有理由查詢錯誤。

最重要的是，溝通風格必須一致。請使用相同的開頭語和句式，讓使用者能輕易瀏覽記錄。

請讓應用程式的輸出敘述它正在執行的動作，及其如何影響使用者。這可能包含顯示所涉步驟的時間表，甚至是一個進度條和長執行動作的指標。使用者絕不應該有應用程式正在執行他們無法理解的神祕動作的感覺。

當難以說明執行狀況時

當傳達非正常狀態時，保持一致性很重要。過度記錄卻不遵循嚴格記錄層級的應用程式，提供的資訊量與不記錄的應用程式相同，甚至更少。

因此，定義事件和相關訊息的嚴重程度很重要；然後為它們使用一致的記錄層級。如此一來，使用者可以透過 --verbose 旗標或環境變數（例如 RUST_LOG）自行選擇記錄量。

常用的 log crate 定義的層級如下（依嚴重程度遞增排序）

追蹤
除錯
資訊
警告
錯誤

不妨將 info 視為預設日誌層級，然後用它來表達有意義的輸出結果。（某些會傾向於更簡潔的輸出模式的應用程式可能預設只會顯示警告和錯誤。）

此外，我們建議在各種日誌訊息中使用相似的字首和句子結構，這樣一來就能善用像 grep 這樣的工具來過濾它們。訊息本身應該提供足夠的內容，讓使用者在過濾後的日誌中也能輕鬆讀懂，同時也不至於過度詳細。

日誌陳述範例

error: could not find `Cargo.toml` in `/home/you/project/`

=> Downloading repository index
=> Downloading packages...

以下日誌是從 wasm-pack 中擷取的

 [1/7] Adding WASM target...
 [2/7] Compiling to WASM...
 [3/7] Creating a pkg directory...
 [4/7] Writing a package.json...
 > [WARN]: Field `description` is missing from Cargo.toml. It is not necessary, but recommended
 > [WARN]: Field `repository` is missing from Cargo.toml. It is not necessary, but recommended
 > [WARN]: Field `license` is missing from Cargo.toml. It is not necessary, but recommended
 [5/7] Copying over your README...
 > [WARN]: origin crate has no README
 [6/7] Installing WASM-bindgen...
 > [INFO]: wasm-bindgen already installed
 [7/7] Running WASM-bindgen...
 Done in 1 second

發生恐慌

有一個常被遺忘的方面，就是您的程式在當機時也會輸出一些東西。在 Rust 中，「當機」通常是指「恐慌」（例如與「作業系統強制終止程式」相對應的「受控當機」）。預設情況下，發生恐慌時，會有「恐慌處理常式」將一些資訊印在主控台上。

例如，如果您使用 cargo new --bin foo 建立新的二進制專案並將 fn main 的內容替換為 panic!("Hello World")，執行程式時會得到這個結果

thread 'main' panicked at 'Hello, world!', src/main.rs:2:5
note: Run with `RUST_BACKTRACE=1` for a backtrace.

對於身為開發人員的您來說，這是一個有用的資訊。（驚不驚喜！程式因為 main.rs 檔案中的第 2 行而當機了。）但對於甚至無法取得原始程式碼的使用者來說，這一點用都沒有，甚至還可能讓他們感到困惑。這正是建議您建立自訂恐慌處理常式的原因，這樣一來就能提供更偏重使用者體驗的輸出結果。

有一套函式庫剛好符合這些條件，叫做 human-panic。要將它新增到您的 CLI 專案，請在 main 函式的開頭匯入它，然後呼叫 setup_panic!() 巨集

use human_panic::setup_panic;

fn main() {
   setup_panic!();

   panic!("Hello world")
}

這樣一來就會顯示一則非常友善的訊息，告訴使用者他們可以採取哪些行動

Well, this is embarrassing.

foo had a problem and crashed. To help us diagnose the problem you can send us a crash report.

We have generated a report file at "/var/folders/n3/dkk459k908lcmkzwcmq0tcv00000gn/T/report-738e1bec-5585-47a4-8158-f1f7227f0168.toml". Submit an issue or email with the subject of "foo Crash Report" and include the report as an attachment.

- Authors: Your Name <your.name@example.com>

We take privacy seriously, and do not perform any automated error collection. In order to improve the software, we rely on people to submit reports.

Thank you kindly!

Rust 中的命令列應用程式

與人類溝通

當一切順利時

當難以說明執行狀況時

日誌陳述範例

發生恐慌