SQL 오류를 빌드 시점에 잡아내는 Rust API 서버 — Axum + SQLx 타입 안전 패턴 정리

[dependencies]
axum = { version = "0.8", features = ["macros"] }
sqlx = { version = "0.8", features = [
    "runtime-tokio-native-tls",
    "postgres",
    "macros",
    "chrono",
    "uuid",
] }
tokio = { version = "1", features = ["full"] }
tower-http = { version = "0.6", features = ["trace", "cors", "compression-gzip"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
thiserror = "2"

use axum::{Router, routing::get};
use sqlx::PgPool;
 
#[derive(Clone)]
struct AppState {
    db: PgPool,
}
 
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    tracing_subscriber::fmt()
        .with_env_filter("info,sqlx=warn")
        .init();
 
    let database_url = std::env::var("DATABASE_URL")
        .expect("DATABASE_URL must be set");
 
    let pool = sqlx::postgres::PgPoolOptions::new()
        .max_connections(20)
        .min_connections(5)
        .max_lifetime(std::time::Duration::from_secs(1800))
        .idle_timeout(std::time::Duration::from_secs(300))
        .acquire_timeout(std::time::Duration::from_secs(30))
        .connect(&database_url)
        .await?;
 
    // 마이그레이션 실패 시 ? 로 에러가 전파되어 프로세스가 종료됩니다.
    // 마이그레이션이 실패한 상태로 서버를 띄우는 것보다 빠르게 실패(fail-fast)하는 편이 안전합니다.
    sqlx::migrate!("./migrations").run(&pool).await?;
 
    let state = AppState { db: pool };
 
    let app = Router::new()
        .route("/users", get(list_users).post(create_user))
        .route("/users/:id", get(get_user))
        .layer(tower_http::trace::TraceLayer::new_for_http())
        .layer(
            tower_http::cors::CorsLayer::new()
                .allow_origin(tower_http::cors::Any) // 프로덕션에서는 명시적 출처를 지정할 것
        )
        .with_state(state);
 
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await?;
    tracing::info!("서버 시작: http://0.0.0.0:3000");
    axum::serve(listener, app).await?;
 
    Ok(())
}

use axum::{
    extract::{Path, State},
    http::StatusCode,
    Json,
};
use serde::{Deserialize, Serialize};
use uuid::Uuid;
 
#[derive(Serialize)]
struct User {
    id: Uuid,
    email: String,
    name: String,
    created_at: chrono::DateTime<chrono::Utc>,
}
 
#[derive(Deserialize)]
struct CreateUserRequest {
    email: String,
    name: String,
}
 
async fn list_users(
    State(state): State<AppState>,
) -> Result<Json<Vec<User>>, AppError> {
    let users = sqlx::query_as!(
        User,
        "SELECT id, email, name, created_at FROM users ORDER BY created_at DESC"
    )
    .fetch_all(&state.db)
    .await?;
 
    Ok(Json(users))
}
 
async fn get_user(
    Path(id): Path<Uuid>,
    State(state): State<AppState>,
) -> Result<Json<User>, AppError> {
    let user = sqlx::query_as!(
        User,
        "SELECT id, email, name, created_at FROM users WHERE id = $1",
        id
    )
    .fetch_optional(&state.db)
    .await?
    .ok_or(AppError::NotFound)?;
 
    Ok(Json(user))
}
 
async fn create_user(
    State(state): State<AppState>,
    Json(req): Json<CreateUserRequest>,
) -> Result<(StatusCode, Json<User>), AppError> {
    let user = sqlx::query_as!(
        User,
        r#"
        INSERT INTO users (id, email, name, created_at)
        VALUES ($1, $2, $3, NOW())
        RETURNING id, email, name, created_at
        "#,
        Uuid::new_v4(),
        req.email,
        req.name
    )
    .fetch_one(&state.db)
    .await?;
 
    Ok((StatusCode::CREATED, Json(user)))
}

use axum::{http::StatusCode, response::{IntoResponse, Response}, Json};
use thiserror::Error;
 
#[derive(Error, Debug)]
enum AppError {
    #[error("리소스를 찾을 수 없습니다")]
    NotFound,
    #[error("데이터베이스 오류: {0}")]
    Database(#[from] sqlx::Error),
    #[error("유효하지 않은 요청: {0}")]
    BadRequest(String),
}
 
impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, message) = match self {
            AppError::NotFound => {
                (StatusCode::NOT_FOUND, "리소스를 찾을 수 없습니다".to_string())
            }
            AppError::Database(e) => {
                // 내부 에러 원인은 클라이언트에 노출하지 않고 서버 로그에만 기록합니다
                tracing::error!(error = %e, "데이터베이스 오류 발생");
                (StatusCode::INTERNAL_SERVER_ERROR, "내부 서버 오류가 발생했습니다".to_string())
            }
            AppError::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg),
        };
 
        (status, Json(serde_json::json!({ "error": message }))).into_response()
    }
}

async fn transfer_credits(
    State(state): State<AppState>,
    Json(req): Json<TransferRequest>,
) -> Result<StatusCode, AppError> {
    let mut tx = state.db.begin().await?;
 
    let result = sqlx::query!(
        "UPDATE accounts SET credits = credits - $1 WHERE id = $2 AND credits >= $1",
        req.amount,
        req.from_id
    )
    .execute(&mut *tx)
    .await?;
 
    // WHERE 조건 불만족(잔액 부족)이면 affected row가 0 — 명시적으로 확인해야 합니다.
    // 이 검사 없이 넘어가면 출금 없이 입금만 실행되는 버그가 생깁니다.
    if result.rows_affected() == 0 {
        return Err(AppError::BadRequest("잔액이 부족합니다".into()));
        // 여기서 함수를 나가면 tx가 Drop되며 자동 롤백됩니다
    }
 
    sqlx::query!(
        "UPDATE accounts SET credits = credits + $1 WHERE id = $2",
        req.amount,
        req.to_id
    )
    .execute(&mut *tx)
    .await?;
 
    tx.commit().await?;
    Ok(StatusCode::OK)
}

# 로컬에서 메타데이터 생성 (DB 연결 필요)
cargo sqlx prepare
 
# 생성된 .sqlx/ 디렉토리를 git에 커밋
git add .sqlx/
git commit -m "sqlx offline 메타데이터 업데이트"

# .github/workflows/ci.yml
- name: Build
  env:
    SQLX_OFFLINE: "true"
  run: cargo build --release