Rust Axum 框架實戰：打造高效能 REST API 服務完整指南

// 引入 SQLx 的 FromRow derive 巨集
// 這個巨集會自動實作將資料庫查詢結果轉換為 Rust struct 的邏輯
use sqlx::FromRow;

// Todo 結構體定義
// 代表資料庫中 todos 表格的一筆記錄
// #[derive(FromRow)] 讓 SQLx 能夠自動將查詢結果對映到此結構
#[derive(sqlx::FromRow)]
pub struct Todo {
    // 主鍵欄位，使用 i64 與 SQLite 的 INTEGER PRIMARY KEY 對應
    id: i64,
    // 待辦事項的內容描述
    body: String,
    // 完成狀態標記，true 表示已完成，false 表示未完成
    completed: bool,
}

// 為 Todo 結構體實作 getter 方法
// 這些方法提供對私有欄位的唯讀存取
// 採用此模式可以確保資料的封裝性，防止外部程式碼直接修改內部狀態
impl Todo {
    // 取得待辦事項的唯一識別碼
    // 回傳值為 i64 型別的副本，因為 i64 實作了 Copy trait
    pub fn id(&self) -> i64 {
        self.id
    }

    // 取得待辦事項的內容描述
    // 回傳字串切片的參考，避免不必要的記憶體配置
    // 使用 as_ref() 將 String 轉換為 &str
    pub fn body(&self) -> &str {
        self.body.as_ref()
    }

    // 取得待辦事項的完成狀態
    // 回傳布林值的副本
    pub fn completed(&self) -> bool {
        self.completed
    }
}

// 引入 serde 的 Deserialize derive 巨集
// 用於將 JSON 請求主體反序列化為 Rust struct
use serde::Deserialize;

// CreateTodo 結構體定義
// 用於接收建立新待辦事項的 API 請求
// 只包含 body 欄位，id 由資料庫自動產生，completed 預設為 false
#[derive(Deserialize)]
pub struct CreateTodo {
    // 新待辦事項的內容描述
    body: String,
}

impl CreateTodo {
    // 取得待辦事項的內容描述
    // 提供唯讀存取，確保資料不會被意外修改
    pub fn body(&self) -> &str {
        self.body.as_ref()
    }
}

// UpdateTodo 結構體定義
// 用於接收更新待辦事項的 API 請求
// 包含 body 與 completed 兩個欄位，允許同時更新內容與狀態
#[derive(Deserialize)]
pub struct UpdateTodo {
    // 更新後的待辦事項內容
    body: String,
    // 更新後的完成狀態
    completed: bool,
}

impl UpdateTodo {
    // 取得更新後的內容描述
    pub fn body(&self) -> &str {
        self.body.as_ref()
    }

    // 取得更新後的完成狀態
    pub fn completed(&self) -> bool {
        self.completed
    }
}

// 引入 SQLx 相關型別
use sqlx::{query_as as query, SqlitePool, Error as SqlxError};

impl Todo {
    // 列出所有待辦事項
    // 執行不帶條件的 SELECT 查詢，回傳所有記錄
    // dbpool 參數是資料庫連線池的參考
    pub async fn list(dbpool: &SqlitePool) -> Result<Vec<Todo>, Error> {
        // 使用 query_as 巨集執行 SQL 查詢
        // select * from todos 會取得 todos 表格的所有記錄
        // fetch_all 方法會等待查詢完成並回傳所有結果列
        query("select * from todos")
            .fetch_all(dbpool)
            .await
            // 將 sqlx::Error 轉換為自定義的 Error 型別
            .map_err(Into::into)
    }

    // 讀取單一待辦事項
    // 根據 id 查詢特定記錄，可能存在也可能不存在
    // 回傳 Option<Todo> 來表示查詢結果可能為空的情況
    pub async fn read(dbpool: &SqlitePool, id: i64) -> Result<Option<Todo>, Error> {
        // 使用參數化查詢防止 SQL 注入攻擊
        // ? 是 SQLite 的參數佔位符號
        query("select * from todos where id = ?")
            // bind 方法將 id 值繫結到第一個參數佔位符
            .bind(id)
            // fetch_optional 在找不到記錄時回傳 None 而非錯誤
            .fetch_optional(dbpool)
            .await
            .map_err(Into::into)
    }

    // 建立新待辦事項
    // 插入一筆新記錄到資料庫，並回傳包含自動產生 id 的完整記錄
    pub async fn create(dbpool: &SqlitePool, create_todo: CreateTodo) -> Result<Todo, Error> {
        // INSERT 語句搭配 RETURNING 子句
        // SQLite 3.35.0 版本開始支援 RETURNING 語法
        // 這讓我們能在單一查詢中完成插入並取得結果
        // completed 預設值設為 0（false）
        query("insert into todos (body, completed) values (?, 0) returning *")
            // 將 create_todo 的 body 欄位值繫結到參數
            .bind(create_todo.body())
            // fetch_one 預期查詢會回傳正好一筆記錄
            .fetch_one(dbpool)
            .await
            .map_err(Into::into)
    }

    // 更新待辦事項
    // 根據 id 找到記錄並更新其 body 與 completed 欄位
    pub async fn update(
        dbpool: &SqlitePool,
        id: i64,
        updated_todo: UpdateTodo
    ) -> Result<Todo, Error> {
        // UPDATE 語句搭配 RETURNING 子句
        // 同時更新 body 與 completed 兩個欄位
        // 注意參數繫結的順序必須與 ? 佔位符的順序一致
        query("update todos set body = ?, completed = ? where id = ? returning *")
            // 第一個參數：新的 body 值
            .bind(updated_todo.body())
            // 第二個參數：新的 completed 值
            .bind(updated_todo.completed())
            // 第三個參數：要更新的記錄 id
            .bind(id)
            .fetch_one(dbpool)
            .await
            .map_err(Into::into)
    }

    // 刪除待辦事項
    // 根據 id 從資料庫中移除記錄
    // 刪除操作不需要回傳資料，因此回傳型別為 Result<(), Error>
    pub async fn delete(dbpool: &SqlitePool, id: i64) -> Result<(), Error> {
        // DELETE 語句不需要 RETURNING 子句
        query("delete from todos where id = ?")
            .bind(id)
            // execute 方法用於不需要回傳資料的查詢
            // 會回傳 QueryResult 包含受影響的列數等資訊
            .execute(dbpool)
            .await?;
        // 刪除成功後回傳空的 Ok
        Ok(())
    }
}

// 引入 Axum 相關型別與函式
use axum::{
    routing::{get, post, put, delete},
    Router,
};
// 引入 Tower HTTP 中介層
use tower_http::cors::{CorsLayer, Any};
use tower_http::trace::TraceLayer;
// 引入 SQLx 連線池型別
use sqlx::{Pool, Sqlite};

// 建立並設定 API Router
// 這是應用程式的核心路由配置函式
// 接收資料庫連線池作為參數，並將其注入到應用程式狀態中
pub async fn create_router(dbpool: Pool<Sqlite>) -> Router {
    Router::new()
        // 存活探測端點
        // 僅檢查應用程式本身是否正常運作
        // 回傳簡單的字串 "ok" 即可
        .route("/alive", get(|| async { "ok" }))
        // 就緒探測端點
        // 檢查應用程式是否已準備好接收流量
        // 包含資料庫連線檢查
        .route("/ready", get(ping))
        // 使用 nest 方法建立路由前綴
        // 所有巢狀路由都會加上 /v1 前綴
        // 這種設計便於未來進行 API 版本管理
        .nest(
            "/v1",
            Router::new()
                // /v1/todos 端點
                // GET 方法對應 todo_list 處理函式（列出所有待辦事項）
                // POST 方法對應 todo_create 處理函式（建立新待辦事項）
                .route("/todos", get(todo_list).post(todo_create))
                // /v1/todos/:id 端點
                // :id 是路徑參數，可以透過 Path 抽取器取得
                // GET 方法對應 todo_read（讀取單一待辦事項）
                // PUT 方法對應 todo_update（更新待辦事項）
                // DELETE 方法對應 todo_delete（刪除待辦事項）
                .route(
                    "/todos/:id",
                    get(todo_read).put(todo_update).delete(todo_delete)
                ),
        )
        // 將資料庫連線池注入為應用程式狀態
        // 處理函式可以透過 State 抽取器取得此狀態
        .with_state(dbpool)
        // 套用 CORS 中介層
        // 允許任意來源與任意 HTTP 方法
        // 生產環境應該根據實際需求設定更嚴格的規則
        .layer(CorsLayer::new().allow_methods(Any).allow_origin(Any))
        // 套用追蹤中介層
        // 自動記錄每個請求的處理資訊
        .layer(TraceLayer::new_for_http())
}

// 引入 Axum 抽取器與回應型別
use axum::{
    extract::{State, Path, Json},
};
// 引入 SQLx 連線池型別
use sqlx::SqlitePool;

// 就緒探測處理函式
// 檢查資料庫連線是否正常
// State(dbpool) 語法使用解構來同時提取狀態並繫結到變數
pub async fn ping(State(dbpool): State<SqlitePool>) -> Result<String, Error> {
    // 從連線池取得一個連線
    // acquire 方法會從池中取得可用連線，若池已滿則等待
    let mut conn = dbpool.acquire().await?;
    // 執行 ping 操作測試連線是否有效
    // ping 會發送簡單的查詢來確認資料庫回應正常
    conn.ping()
        .await
        // ping 成功則回傳 "ok" 字串
        .map(|_| "ok".to_string())
        // 將可能的錯誤轉換為自定義 Error 型別
        .map_err(Into::into)
}

// 列出所有待辦事項
// 不需要任何額外輸入，僅需要資料庫連線池
pub async fn todo_list(
    State(dbpool): State<SqlitePool>,
) -> Result<Json<Vec<Todo>>, Error> {
    // 呼叫 Todo::list 取得所有待辦事項
    Todo::list(&dbpool)
        .await
        // 將 Vec<Todo> 包裝成 Json 型別
        // Axum 會自動將其序列化為 JSON 格式並設定適當的 Content-Type
        .map(Json::from)
}

// 讀取單一待辦事項
// 需要從路徑中提取 id 參數
pub async fn todo_read(
    State(dbpool): State<SqlitePool>,
    // Path(id) 會從 /todos/:id 中提取 id 值
    // 自動將字串轉換為 i64 型別
    Path(id): Path<i64>,
) -> Result<Json<Todo>, Error> {
    // 呼叫 Todo::read 查詢指定 id 的待辦事項
    Todo::read(&dbpool, id)
        .await?
        // read 回傳 Option<Todo>，需要處理找不到記錄的情況
        // ok_or 將 None 轉換為 Error::NotFound
        .ok_or(Error::NotFound)
        // 將 Todo 包裝成 Json 型別
        .map(Json::from)
}

// 建立新待辦事項
// 需要從請求主體中提取 JSON 資料
pub async fn todo_create(
    State(dbpool): State<SqlitePool>,
    // Json(new_todo) 會將請求主體反序列化為 CreateTodo 結構體
    Json(new_todo): Json<CreateTodo>,
) -> Result<Json<Todo>, Error> {
    // 呼叫 Todo::create 建立新記錄
    Todo::create(&dbpool, new_todo)
        .await
        .map(Json::from)
}

// 更新待辦事項
// 同時需要路徑參數（id）與請求主體（更新內容）
pub async fn todo_update(
    State(dbpool): State<SqlitePool>,
    Path(id): Path<i64>,
    Json(updated_todo): Json<UpdateTodo>,
) -> Result<Json<Todo>, Error> {
    // 呼叫 Todo::update 更新指定記錄
    Todo::update(&dbpool, id, updated_todo)
        .await
        .map(Json::from)
}

// 刪除待辦事項
// 僅需要路徑參數中的 id
pub async fn todo_delete(
    State(dbpool): State<SqlitePool>,
    Path(id): Path<i64>,
) -> Result<(), Error> {
    // 呼叫 Todo::delete 刪除指定記錄
    // 刪除成功回傳空的 Ok，Axum 會回傳 200 OK 無內容
    Todo::delete(&dbpool, id).await
}

// 引入 Axum HTTP 狀態碼型別
use axum::http::StatusCode;
// 引入 Axum 回應相關型別
use axum::response::{IntoResponse, Response};

// 自定義錯誤列舉
// 使用 Debug derive 讓錯誤可以被格式化輸出用於除錯
#[derive(Debug)]
pub enum Error {
    // 資料庫相關錯誤
    // 包含 HTTP 狀態碼與錯誤訊息
    // 狀態碼讓我們能夠針對不同的資料庫錯誤回傳適當的 HTTP 狀態
    Sqlx(StatusCode, String),
    // 資源不存在錯誤
    // 用於查詢不到指定 id 的記錄時
    NotFound,
}

// 實作從 sqlx::Error 到自定義 Error 的轉換
// 這讓我們可以在程式碼中使用 ? 運算子自動轉換錯誤型別
impl From<sqlx::Error> for Error {
    fn from(err: sqlx::Error) -> Error {
        // 使用 match 針對不同的 sqlx 錯誤類型進行處理
        match err {
            // RowNotFound 錯誤表示查詢沒有回傳任何記錄
            // 這在使用 fetch_one 時會發生，對映到 NotFound 錯誤
            sqlx::Error::RowNotFound => Error::NotFound,
            // 其他所有資料庫錯誤都對映為內部伺服器錯誤
            // 錯誤訊息會被轉換為字串供除錯使用
            _ => Error::Sqlx(
                StatusCode::INTERNAL_SERVER_ERROR,
                err.to_string(),
            ),
        }
    }
}

// 實作 IntoResponse trait
// 這讓 Error 型別可以被 Axum 轉換為 HTTP 回應
impl IntoResponse for Error {
    fn into_response(self) -> Response {
        match self {
            // Sqlx 錯誤回傳對應的狀態碼與錯誤訊息
            // (StatusCode, String) 元組會被 Axum 轉換為
            // 具有該狀態碼與純文字主體的回應
            Error::Sqlx(code, body) => (code, body).into_response(),
            // NotFound 錯誤僅回傳 404 狀態碼
            // 不包含額外的錯誤訊息
            Error::NotFound => StatusCode::NOT_FOUND.into_response(),
        }
    }
}

// 引入 Tokio 網路相關功能
use tokio::net::TcpListener;
// 引入 SQLx SQLite 連線池
use sqlx::sqlite::SqlitePoolOptions;

// 使用 tokio::main 巨集將 main 函式轉換為非同步入口點
// 這個巨集會自動建立 Tokio 執行時期並執行非同步程式碼
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 初始化追蹤訂閱器
    // 這會啟用 TraceLayer 的日誌輸出功能
    tracing_subscriber::fmt::init();

    // 建立 SQLite 連線池
    // max_connections 設定池中最大連線數
    // 連線字串指定資料庫檔案路徑，?mode=rwc 表示讀寫模式，不存在時自動建立
    let dbpool = SqlitePoolOptions::new()
        .max_connections(5)
        .connect("sqlite:todos.db?mode=rwc")
        .await?;

    // 執行資料庫遷移
    // 確保 todos 表格存在
    // 實務上應該使用 sqlx-cli 工具管理遷移
    sqlx::query(
        "CREATE TABLE IF NOT EXISTS todos (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            body TEXT NOT NULL,
            completed BOOLEAN NOT NULL DEFAULT 0
        )"
    )
    .execute(&dbpool)
    .await?;

    // 建立 Router 並注入資料庫連線池
    let app = create_router(dbpool).await;

    // 建立 TCP 監聽器
    // 綁定到 127.0.0.1:3000 位址
    let listener = TcpListener::bind("127.0.0.1:3000").await?;

    // 輸出啟動訊息
    println!("伺服器正在監聽 http://127.0.0.1:3000");

    // 啟動 Axum 伺服器
    // serve 方法接受監聽器與 Router，並開始處理請求
    axum::serve(listener, app).await?;

    Ok(())
}

# 測試存活探測端點
# 預期回應：HTTP 200 OK，主體內容為 "ok"
# 此端點僅確認應用程式正在執行
http GET 127.0.0.1:3000/alive

# 測試就緒探測端點
# 預期回應：HTTP 200 OK，主體內容為 "ok"
# 此端點會實際測試資料庫連線
http GET 127.0.0.1:3000/ready

# 建立新待辦事項
# HTTP POST 方法，JSON 主體包含 body 欄位
# 預期回應：HTTP 200 OK，JSON 主體包含完整的 Todo 物件（含自動產生的 id）
http POST 127.0.0.1:3000/v1/todos body='完成 Axum 教學文章'

# 列出所有待辦事項
# HTTP GET 方法，無需任何參數
# 預期回應：HTTP 200 OK，JSON 陣列包含所有待辦事項
http GET 127.0.0.1:3000/v1/todos

# 讀取特定待辦事項
# 將 1 替換為實際的待辦事項 id
# 預期回應：HTTP 200 OK，JSON 主體包含該待辦事項
http GET 127.0.0.1:3000/v1/todos/1

# 更新待辦事項
# HTTP PUT 方法，JSON 主體包含 body 與 completed 欄位
# completed:=true 使用 := 語法傳送布林值而非字串
# 預期回應：HTTP 200 OK，JSON 主體包含更新後的待辦事項
http PUT 127.0.0.1:3000/v1/todos/1 body='完成 Axum 教學文章' completed:=true

# 刪除待辦事項
# HTTP DELETE 方法，無需請求主體
# 預期回應：HTTP 200 OK，無回應主體
http DELETE 127.0.0.1:3000/v1/todos/1

# 確認刪除成功
# 嘗試讀取已刪除的待辦事項
# 預期回應：HTTP 404 Not Found
http GET 127.0.0.1:3000/v1/todos/1