Actix-web穩健API建構完全指南：整合測試、驗證與錯誤處理實戰

use actix_web::{error, web, Error, HttpResponse};
use diesel::prelude::*;
use diesel::r2d2::{self, ConnectionManager};

// 資料庫連接池型別別名
type DbPool = r2d2::Pool<ConnectionManager<PgConnection>>;

// 貓咪資料模型
#[derive(Queryable, Serialize, Debug)]
struct Cat {
    id: i32,
    name: String,
    age: i32,
    breed: String,
}

/// 天真的 API 端點實作（存在多個問題）
async fn cat_endpoint_naive(
    pool: web::Data<DbPool>,
    cat_id: web::Path<i32>,
) -> Result<HttpResponse, Error> {
    use crate::schema::cats::dsl::*;
    
    // 問題 1: 使用 expect() 可能導致 panic
    let mut connection = pool
        .get()
        .expect("無法從連接池中取得資料庫連線");
    
    // 問題 2: 所有資料庫錯誤都轉為 500 Internal Server Error
    let cat_data = web::block(move || {
        cats.filter(id.eq(cat_id.into_inner()))
            .first::<Cat>(&mut connection)
    })
    .await?
    .map_err(error::ErrorInternalServerError)?;
    
    Ok(HttpResponse::Ok().json(cat_data))
}

// src/routes.rs - 路由配置模組

use actix_web::web;
use crate::handlers::{get_cats_endpoint, get_cat_endpoint, create_cat_endpoint};

/// API 路由配置函數
/// 
/// 此函數可在主程式與測試中重複使用，確保路由一致性
/// 
/// # 參數
/// - `cfg`: Actix-web 的服務配置物件
pub fn api_config(cfg: &mut web::ServiceConfig) {
    cfg.service(
        web::scope("/api")
            // 查詢所有貓咪
            .route("/cats", web::get().to(get_cats_endpoint))
            // 查詢單一貓咪
            .route("/cat/{id}", web::get().to(get_cat_endpoint))
            // 新增貓咪
            .route("/cat", web::post().to(create_cat_endpoint))
            // 更新貓咪資料
            .route("/cat/{id}", web::put().to(update_cat_endpoint))
            // 刪除貓咪
            .route("/cat/{id}", web::delete().to(delete_cat_endpoint))
    );
}

/// 健康檢查路由配置
pub fn health_config(cfg: &mut web::ServiceConfig) {
    cfg.route("/health", web::get().to(health_check_endpoint));
}

// src/main.rs

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    let pool = init_database_pool();
    
    HttpServer::new(move || {
        App::new()
            .app_data(web::Data::new(pool.clone()))
            .configure(api_config)      // 載入 API 路由
            .configure(health_config)   // 載入健康檢查路由
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}

// tests/api_integration.rs - 整合測試模組

use actix_web::{test, web, App};
use diesel::r2d2::{self, ConnectionManager};
use diesel::PgConnection;

mod common;
use common::{setup_test_database, cleanup_test_database, insert_test_cat};

type DbPool = r2d2::Pool<ConnectionManager<PgConnection>>;

/// 設定測試用的 App 實例
async fn setup_test_app(pool: DbPool) -> impl Service<
    Request = actix_http::Request,
    Response = ServiceResponse,
    Error = actix_web::Error,
> {
    test::init_service(
        App::new()
            .app_data(web::Data::new(pool))
            .configure(api_config)  // 重用路由配置
    ).await
}

#[actix_web::test]
async fn test_get_cat_success() {
    // 準備測試環境
    let pool = setup_test_database().await;
    let test_cat = insert_test_cat(&pool, "測試貓咪", 3, "波斯貓").await;
    let app = setup_test_app(pool.clone()).await;
    
    // 建立測試請求
    let req = test::TestRequest::get()
        .uri(&format!("/api/cat/{}", test_cat.id))
        .to_request();
    
    // 執行請求
    let resp = test::call_service(&app, req).await;
    
    // 驗證回應
    assert!(resp.status().is_success());
    assert_eq!(resp.status(), StatusCode::OK);
    
    // 驗證回應內容
    let body: Cat = test::read_body_json(resp).await;
    assert_eq!(body.name, "測試貓咪");
    assert_eq!(body.age, 3);
    
    // 清理測試資料
    cleanup_test_database(&pool).await;
}

#[actix_web::test]
async fn test_get_cat_not_found() {
    let pool = setup_test_database().await;
    let app = setup_test_app(pool.clone()).await;
    
    // 查詢不存在的 ID
    let req = test::TestRequest::get()
        .uri("/api/cat/99999")
        .to_request();
    
    let resp = test::call_service(&app, req).await;
    
    // 應該回傳 404
    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
    
    cleanup_test_database(&pool).await;
}

#[actix_web::test]
async fn test_get_cat_invalid_id() {
    let pool = setup_test_database().await;
    let app = setup_test_app(pool.clone()).await;
    
    // 傳入無效的 ID（負數）
    let req = test::TestRequest::get()
        .uri("/api/cat/-1")
        .to_request();
    
    let resp = test::call_service(&app, req).await;
    
    // 應該回傳 400 Bad Request
    assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
    
    cleanup_test_database(&pool).await;
}

# 加入 validator 依賴
cargo add validator --features derive
cargo add serde --features derive

use serde::Deserialize;
use validator::Validate;

/// 貓咪 ID 路徑參數驗證
#[derive(Deserialize, Validate, Debug)]
pub struct CatEndpointPath {
    /// 貓咪 ID，必須為正整數
    #[validate(range(min = 1, message = "貓咪 ID 必須為正整數"))]
    pub id: i32,
}

/// 新增貓咪的請求主體驗證
#[derive(Deserialize, Validate, Debug)]
pub struct CreateCatRequest {
    /// 貓咪名稱，長度限制
    #[validate(length(min = 1, max = 50, message = "名稱長度必須在 1-50 字元之間"))]
    pub name: String,
    
    /// 貓咪年齡，範圍限制
    #[validate(range(min = 0, max = 30, message = "年齡必須在 0-30 歲之間"))]
    pub age: i32,
    
    /// 貓咪品種
    #[validate(length(min = 1, max = 30, message = "品種名稱長度必須在 1-30 字元之間"))]
    pub breed: String,
    
    /// 貓咪信箱（選填，但需符合格式）
    #[validate(email(message = "信箱格式不正確"))]
    pub email: Option<String>,
}

/// 自定義驗證函數範例
fn validate_cat_breed(breed: &str) -> Result<(), validator::ValidationError> {
    let valid_breeds = vec!["波斯貓", "暹羅貓", "英國短毛貓", "美國短毛貓", "其他"];
    
    if !valid_breeds.contains(&breed) {
        return Err(validator::ValidationError::new("invalid_breed"));
    }
    
    Ok(())
}

use actix_web::{web, HttpResponse};
use crate::errors::UserError;

/// 範例：在 Handler 中使用驗證
async fn create_cat_endpoint(
    pool: web::Data<DbPool>,
    cat_data: web::Json<CreateCatRequest>,
) -> Result<HttpResponse, UserError> {
    // 執行驗證
    cat_data.validate()
        .map_err(|validation_errors| {
            let error_messages: Vec<String> = validation_errors
                .field_errors()
                .iter()
                .flat_map(|(field, errors)| {
                    errors.iter().map(move |error| {
                        format!("{}: {}", field, error.message.as_ref()
                            .unwrap_or(&std::borrow::Cow::Borrowed("驗證失敗")))
                    })
                })
                .collect();
            
            UserError::ValidationError(error_messages.join(", "))
        })?;
    
    // 驗證通過，繼續處理業務邏輯
    // ...
    Ok(HttpResponse::Created().json(created_cat))
}

// src/errors.rs - 錯誤處理模組

use actix_web::{error, http::StatusCode, HttpResponse};
use derive_more::Display;
use serde::Serialize;
use serde_json::json;

/// API 自定義錯誤列舉
/// 
/// 涵蓋所有可能的業務錯誤與系統錯誤類型
#[derive(Debug, Display)]
pub enum UserError {
    /// 輸入驗證失敗
    #[display(fmt = "輸入驗證失敗: {}", _0)]
    ValidationError(String),
    
    /// 找不到指定的資源
    #[display(fmt = "找不到指定的資源: {}", _0)]
    NotFoundError(String),
    
    /// 資料庫操作錯誤
    #[display(fmt = "資料庫錯誤: {}", _0)]
    DatabaseError(String),
    
    /// 權限不足
    #[display(fmt = "權限不足: {}", _0)]
    UnauthorizedError(String),
    
    /// 禁止存取
    #[display(fmt = "禁止存取: {}", _0)]
    ForbiddenError(String),
    
    /// 衝突錯誤（如重複的資源）
    #[display(fmt = "資源衝突: {}", _0)]
    ConflictError(String),
    
    /// 內部伺服器錯誤
    #[display(fmt = "內部伺服器錯誤")]
    InternalError,
}

/// 錯誤回應結構
#[derive(Serialize)]
struct ErrorResponse {
    /// 錯誤訊息
    msg: String,
    /// 錯誤代碼（可選）
    #[serde(skip_serializing_if = "Option::is_none")]
    code: Option<String>,
    /// 詳細資訊（可選，僅開發環境）
    #[serde(skip_serializing_if = "Option::is_none")]
    details: Option<String>,
}

impl error::ResponseError for UserError {
    /// 根據錯誤類型決定 HTTP 狀態碼
    fn status_code(&self) -> StatusCode {
        match *self {
            UserError::ValidationError(_) => StatusCode::BAD_REQUEST,
            UserError::NotFoundError(_) => StatusCode::NOT_FOUND,
            UserError::DatabaseError(_) => StatusCode::INTERNAL_SERVER_ERROR,
            UserError::UnauthorizedError(_) => StatusCode::UNAUTHORIZED,
            UserError::ForbiddenError(_) => StatusCode::FORBIDDEN,
            UserError::ConflictError(_) => StatusCode::CONFLICT,
            UserError::InternalError => StatusCode::INTERNAL_SERVER_ERROR,
        }
    }

    /// 生成結構化的 JSON 錯誤回應
    fn error_response(&self) -> HttpResponse {
        let error_response = ErrorResponse {
            msg: self.to_string(),
            code: Some(self.error_code()),
            details: self.error_details(),
        };
        
        HttpResponse::build(self.status_code())
            .json(error_response)
    }
}

impl UserError {
    /// 取得錯誤代碼
    fn error_code(&self) -> String {
        match self {
            UserError::ValidationError(_) => "VALIDATION_ERROR".to_string(),
            UserError::NotFoundError(_) => "NOT_FOUND".to_string(),
            UserError::DatabaseError(_) => "DATABASE_ERROR".to_string(),
            UserError::UnauthorizedError(_) => "UNAUTHORIZED".to_string(),
            UserError::ForbiddenError(_) => "FORBIDDEN".to_string(),
            UserError::ConflictError(_) => "CONFLICT".to_string(),
            UserError::InternalError => "INTERNAL_ERROR".to_string(),
        }
    }
    
    /// 取得詳細錯誤資訊（僅在開發環境）
    fn error_details(&self) -> Option<String> {
        #[cfg(debug_assertions)]
        {
            Some(format!("{:?}", self))
        }
        #[cfg(not(debug_assertions))]
        {
            None
        }
    }
}

/// 從 Diesel 錯誤轉換為自定義錯誤
impl From<diesel::result::Error> for UserError {
    fn from(error: diesel::result::Error) -> Self {
        match error {
            diesel::result::Error::NotFound => {
                UserError::NotFoundError("找不到指定的資源".to_string())
            }
            diesel::result::Error::DatabaseError(kind, info) => {
                log::error!("資料庫錯誤: {:?} - {:?}", kind, info);
                UserError::DatabaseError("資料庫操作失敗".to_string())
            }
            _ => {
                log::error!("未預期的資料庫錯誤: {:?}", error);
                UserError::InternalError
            }
        }
    }
}

/// 從連接池錯誤轉換為自定義錯誤
impl From<r2d2::Error> for UserError {
    fn from(error: r2d2::Error) -> Self {
        log::error!("連接池錯誤: {:?}", error);
        UserError::DatabaseError("無法取得資料庫連線".to_string())
    }
}

use actix_web::{web, HttpResponse};
use crate::errors::UserError;
use crate::models::{Cat, CatEndpointPath};
use diesel::prelude::*;

/// 重構後的貓咪查詢端點
/// 
/// 實作了完整的輸入驗證與錯誤處理
async fn cat_endpoint(
    pool: web::Data<DbPool>,
    cat_id: web::Path<CatEndpointPath>,
) -> Result<HttpResponse, UserError> {
    use crate::schema::cats::dsl::*;
    
    // 步驟 1: 輸入驗證
    cat_id.validate()
        .map_err(|validation_errors| {
            let error_message = validation_errors
                .field_errors()
                .values()
                .flatten()
                .filter_map(|error| error.message.as_ref())
                .map(|msg| msg.to_string())
                .collect::<Vec<_>>()
                .join(", ");
            
            log::warn!("輸入驗證失敗: {}", error_message);
            UserError::ValidationError(error_message)
        })?;
    
    // 步驟 2: 安全地取得資料庫連線
    let mut connection = pool.get()?;  // From trait 自動轉換
    
    // 步驟 3: 執行資料庫查詢
    let cat_data = web::block(move || {
        cats.filter(id.eq(cat_id.id))
            .first::<Cat>(&mut connection)
    })
    .await
    .map_err(|blocking_error| {
        log::error!("Web blocking 錯誤: {:?}", blocking_error);
        UserError::InternalError
    })?  // 處理 web::block 錯誤
    ?;   // 處理 Diesel 錯誤（透過 From trait）
    
    // 步驟 4: 記錄成功查詢
    log::info!("成功查詢貓咪資料: id={}, name={}", cat_data.id, cat_data.name);
    
    // 步驟 5: 回傳成功回應
    Ok(HttpResponse::Ok().json(cat_data))
}

# Cargo.toml

[dependencies]
# 日誌相關依賴
log = "0.4"
env_logger = "0.11"
serde_json = "1.0"
chrono = "0.4"

// src/main.rs

use actix_web::middleware::Logger;
use env_logger::Env;
use std::env;

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    // 初始化日誌系統
    env_logger::Builder::from_env(
        Env::default()
            .default_filter_or("info")  // 預設日誌級別
    )
    .format_timestamp_secs()  // 秒級時間戳
    .init();
    
    log::info!("🚀 正在啟動 Actix-web 伺服器...");
    
    let pool = init_database_pool();
    log::info!("✅ 資料庫連接池初始化完成");
    
    HttpServer::new(move || {
        App::new()
            // 加入 Logger 中介軟體
            .wrap(Logger::default())
            // 自定義日誌格式
            .wrap(Logger::new("%a %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\" %T"))
            .app_data(web::Data::new(pool.clone()))
            .configure(api_config)
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}

// src/logging.rs - 日誌輔助模組

use chrono::Utc;
use serde_json::json;

/// 記錄 API 請求
pub fn log_api_request(
    method: &str,
    path: &str,
    user_id: Option<i32>,
) {
    log::info!(
        target: "api_request",
        "{}",
        json!({
            "timestamp": Utc::now().to_rfc3339(),
            "event": "api_request",
            "method": method,
            "path": path,
            "user_id": user_id,
        })
    );
}

/// 記錄資料庫查詢
pub fn log_database_query(
    query_type: &str,
    table: &str,
    duration_ms: u64,
) {
    log::debug!(
        target: "database",
        "{}",
        json!({
            "timestamp": Utc::now().to_rfc3339(),
            "event": "db_query",
            "query_type": query_type,
            "table": table,
            "duration_ms": duration_ms,
        })
    );
}

/// 記錄錯誤事件
pub fn log_error(
    error_type: &str,
    error_msg: &str,
    context: serde_json::Value,
) {
    log::error!(
        target: "error",
        "{}",
        json!({
            "timestamp": Utc::now().to_rfc3339(),
            "event": "error",
            "error_type": error_type,
            "message": error_msg,
            "context": context,
        })
    );
}