Axum 最佳實踐：如何構建優雅的 Rust 錯誤處理系統？（三）

引言

作為開發者，我們都經歷過這樣的場景：項目上線后，你打開日志監控，鋪天蓋地的 500 Internal Server Error 撲面而來。這些錯誤像個黑洞，吞噬著你的調試時間，你甚至不知道它們是從數據庫查詢失敗，還是某個第三方 API 調用超時。

更糟的是，這些錯誤未經處理，直接甩給了前端。用戶看到一個冰冷的 500 頁面，或者一個包含敏感信息的 JSON 響應，這不僅破壞了用戶體驗，更暴露了服務器的內部實現。

從異常種類來說，異常的種類有很多，有前端傳來的參數不對導致的異常，有數據庫連接超時異常，有查詢數據查不到需要返回業務異常。不同的異常，我們希望有錯誤發生時，提供更優雅的響應提示客戶。同時，也可以對不同異常設置不同的異常響應碼，使前端更方便的處理接口返回值。

Rust 開發 Web 程序時的常見痛點：

大量的 match 語句，代碼變得冗長且難以閱讀。
錯誤信息不統一，前端拿到一堆難以處理的 500 錯誤。
調試困難，服務器內部的詳細錯誤信息沒有被記錄。
如何優雅區分服務器異常與業務異常。

我們使用四招來實現優雅處理 Axum Web 應用中的錯誤處理。

本文相關源碼來自本人 Rust Axum 開發 Websocket as a Service 項目。 GitHub 地址：HTTPS://GitHub.com/BruceZhang54110/RTMate

第一招：定義統一接口響應結構

定義一個結構體 RtResponse 統一接口返回結構，代碼如下。業務成功時調用 ok_with_data 默認 code 是 200，業務失敗時，調用 err 方法。那么如何讓系統異常和業務異常都轉換為 RtResponse 呢？這時候就要看第二招了。

#[derive(Serialize, Debug)]
pub struct RtResponse<T> {code: i32,message: String,data: Option<T>,
}impl<T> RtResponse<T> {/// 創建一個帶數據的業務成功響應pub fn ok_with_data(data: T) -> Self {RtResponse {code: 200,message: 「success」.to_string(),data: Some(data),}}/// 創建一個無數據的業務成功響應pub fn ok() -> Self {RtResponse {code: 200,message: 「success」.to_string(),data: None,}}/// 創建一個業務失敗響應pub fn err(code: i32, message: &str) -> Self {RtResponse {code,message: message.to_string(),data: None,}}
}

接口返回的 JSON 結果就會是如下 JSON 格式：

{「code」: 200,「message」: 「success」,「data」: {「app_id」: 「abc」,「token」: 「eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcHBfaWQiOiJhYmMiLCJjbGllbnRfaWQiOiJlZDU0ZDE2My1iM2EyLTRhZmMtODc4OC01MjAyODA4Yjk0OTEiLCJpYXQiOjE3NTcxNzYwNjgsImV4cCI6MTc1NzE4MzI2OH0.3LNM7jAeG3YL4jb88p4_Ew96gXvw4AoE38MBEYLvK-s」}
}
{「code」: 500,「message」: 「系統內部錯誤」,「data」: null
}

第二招：統一異常封裝

我們不能將數據庫錯誤或文件寫入錯誤信息原封不動的返回給前端，這時需要有一個統一異常處理。因此我們創建一個 ArrError 結構體：

pub struct AppError {pub code: i32,pub message: String,pub source: Option<anyhow::Error>,
}

code：業務錯誤碼，用于前端精確判斷錯誤類型。

message：對前端友好的提示信息。

source：一個 anyhow::Error，用于在日志中打印完整的錯誤鏈，這個字段永遠不會發送給前端。

Axum 提供了一個用來生成響應結果的 IntoResponse trait，一般情況下，使用 Axum 開發接口時不是必須要實現 IntoResponse trait，如果需要處理程序返回的自定義錯誤類型，這個時候則有必要使用。在這里實現方法中轉換為 RtResponse。

// Tell axum how to convert `AppError` into a response.
impl IntoResponse for AppError {fn into_response(self) -> axum::response::Response {// 使用 () 作為 T，表示沒有數據let response = RtResponse::<()> {code: self.code,message: self.message,data: None,};(StatusCode::OK, Json(response)).into_response()}}

第三招：轉換服務器異常類型

前面定義了統一異常結構體，這時候就要派上用場了。我們需求是，對于數據庫連接失敗，文件寫入失敗這些我們無法預料的錯誤，我們希望它們都統一返回 500，保證敏感錯誤信息不展示給前端的同時，在服務端有日志打印可以看到錯誤異常堆棧信息。

我們可以利用 anyhow 處理不同的錯誤，因為它能將任何實現了 std::error::Error 的類型封裝起來。anyhow 的錯誤信息如何轉換為 AppError 呢，這里我們要用到 From 與 Into，統一轉換為 code 是 500， message 是 “系統服務器異常” 的 AppError，代碼如下：

impl <E> From<E> for AppError
whereE: Into<anyhow::Error>
{fn from(value: E) -> Self {let source = value.into();tracing::error!(「Internal error: {:?}」, source);AppError {code: 500, // 500 表示服務器異常message: 「系統內部錯誤」.to_string(),source: Some(source),}}}

在這里有必要講一下 From trait ，它定義了一個類型定義如何從另一個類型創建自身，從而提供了一種非常簡單的在多種類型之間轉換的機制。標準庫中有許多此 trait 的實現，用于原始類型和常見類型的轉換。

例如，我們可以輕松地將 a 轉換 str 為 a String

let my_str = 「hello」;
let my_string = String::from(my_str);

Into trait 可以理解為 From trait 的反轉，如果一個類型實現了 From，那么編譯器會自動為它實現 Into 。

From 表示可以從 T 類型轉換為實現 From trait 的類型
Into 表示某個類型可以轉換為 T

所以在我們異常轉換的場景中就實現了 From trait ，將其他異常轉換為我們統一定義的 AppErrr**。**

impl <E> From<E> for AppError  // AppError 是目標類型
whereE: Into<anyhow::Error> // 這里被轉換類型

單元測試：

// 測試 anyhow::Error 是否能正確轉換為 AppError#[test]fn test_anyhow_error_to_app_error_conversion() {let anyhow_error = anyhow!(「數據庫連接失敗」);let app_error = AppError::from(anyhow_error);assert_eq!(app_error.code, 500);assert_eq!(app_error.message, 「系統內部錯誤」);}

執行結果：

running 1 test
test tests::test_anyhow_error_to_app_error_conversion ... oksuccesses:successes:tests::test_anyhow_error_to_app_error_conversiontest result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out; finished in 0.00s

這樣我們就實現了讓它們都統一返回 500，保證敏感錯誤信息不展示給前端的同時，在服務端有日志打印可以看到錯誤異常堆棧信息。

第四招：轉換自定義異常類型

我使用枚舉定義一些業務異常，這些業務異常對前端來說是重要的，所以業務異常 code 和 message 需要和系統異常區分開，讓前端清晰的判斷業務異常。

pub enum BizError {// 應用未找到AppNotFound,// 參數錯誤InvalidParams,// 非法簽名InvalidSignature,
}

為 AppError 實現 From trait，這樣業務異常也能轉換為 AppError 了，這里我們使用 match 對于不同的業務異常返回不同的 code 和 message。

impl From<BizError> for AppError {fn from(value: BizError) -> Self {match value {BizError::AppNotFound => AppError {code: 1004,message: 「您的 app 未找到，請檢查 appId」.to_string(),source: None,},BizError::InvalidParams => AppError {code: 400,message: 「參數錯誤」.to_string(),source: None,},BizError::InvalidSignature => AppError {code: 1005,message: 「簽名驗證失敗，請檢查您的請求是否合法」.to_string(),source: None,},}}
}

單元測試：

// 測試 BizError::AppNotFound 是否能正確轉換為 AppError#[test]fn test_biz_error_to_app_error_conversion() {// 創建一個 BizError 實例let biz_error = BizError::AppNotFound;let app_error = AppError::from(biz_error);assert_eq!(app_error.code, 1004);assert_eq!(app_error.message, 「您的 app 未找到，請檢查 appId」);}

執行結果：

running 1 test
test tests::test_biz_error_to_app_error_conversion ... oksuccesses:successes:tests::test_biz_error_to_app_error_conversion

那么如何使用呢？

fn get() -> Result<Json<RtResponse<AppAuthResult>>, AppError> {/////// 省略if signature != rt_app_param.signature {// 簽名不匹配，返回錯誤return Err(AppError::from(BizError::InvalidSignature));}/////// 省略Ok(Json(RtResponse::ok_with_data(result)))
}
let rt_app = web_context.dao.get_rt_app_by_app_id(&rt_app_param.app_id).await?.ok_or(BizError::AppNotFound))?;

這里有兩點需要注意：

第一是使用了錯誤傳播運算符? ，如果 Result 的值是 Ok，這個表達式將會返回 Ok 中的值而程序將繼續執行。如果值是 Err，Err 將作為整個函數的返回值，就好像使用了 return 關鍵字一樣，這樣錯誤值就被傳播給了調用者。

所以如果 get_rt_app_by_app_id 返回了 Error，錯誤就會立馬返回，而且因為 AppError 實現了 From trait，會自動將錯誤類型進行轉換。到了上方調用者錯誤就轉換為了 AppError。

第二，如果 get_rt_app_by_app_id 查不到返回 None，在這里使用了 ok_or 將 None 轉換為 Err，參數是自定義的枚舉異常。如果查不到 app_id 就會返回 BizError::AppNotFound 業務異常。由于 BizError 實現了 From trait，同樣可以轉換為 AppError。

方法返回了 AppError 之后，Axum 根據我們實現的 IntoResponse 方法，將 AppError 的 code 和 message 轉換為 RtResponse 的 code 和 message，data 是 None。

總結一下，正常結果轉換為 RtResponse，業務異常先轉換為有業務自定義 code 和 message 的 AppError，AppError 轉換為 RtResponse，最后返回給前端響應。如果是系統異常，結合錯誤傳播運算符?，系統異常轉換為 AppError，AppError 轉換為 RtResponse，最后返回給前端響應。這樣我們就以一種簡潔優雅的方式統一了錯誤返回。

初次學習 Axum 開發 Web 應用，雖然 Rust 學習難度大，但是隨著學習的深入，發現類似 From trait 這種巧妙的設計，開發出簡潔優雅且性能并未打折的代碼，還有是小小的爽感的。在學習和寫項目過程中，寫技術博客幫助自己鞏固知識點，后續 Rust 相關技術文章繼續更新，歡迎點贊關注。