Rust로 구현한 고성능 웹서버: Node.js 대비 3배 성능 달성기

// 프로젝트 디렉토리 구조
// 왜 이렇게 나눴나? → 각 레이어의 책임을 명확히 분리하기 위해서입니다.
// 테스트할 때도 각 레이어를 독립적으로 테스트할 수 있습니다.

src/
├── main.rs           // 진입점: 서버 설정과 라우터 조립만 담당
├── config.rs         // 환경 변수 로드, 설정 구조체 정의
├── routes/
│   ├── mod.rs        // 라우트 모듈 공개
│   ├── api.rs        // API 라우트 (/api/v1/*)
│   └── health.rs     // 헬스체크 (/health, /ready)
├── handlers/
│   ├── mod.rs
│   ├── users.rs      // 사용자 CRUD 핸들러
│   └── analytics.rs  // 분석 데이터 수집 핸들러
├── services/
│   ├── mod.rs
│   ├── user_service.rs   // 사용자 관련 비즈니스 로직
│   └── cache_service.rs  // Redis 캐싱 로직
├── models/
│   ├── mod.rs
│   └── user.rs       // User 구조체, DTO 정의
└── error.rs          // 커스텀 에러 타입, HTTP 에러 변환

use axum::{Router, routing::get, routing::post};
use std::net::SocketAddr;
use tower_http::cors::CorsLayer;
use tower_http::trace::TraceLayer;
use sqlx::postgres::PgPoolOptions;

// #[tokio::main]이 하는 일:
// 1. Tokio 런타임을 생성
// 2. async fn main()을 일반 fn main()으로 변환
// 3. 런타임 위에서 비동기 코드 실행
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // ==========================================
    // 1단계: 환경 설정 로드
    // ==========================================
    // dotenvy는 .env 파일을 읽어서 환경 변수로 설정합니다.
    // .ok()를 붙인 이유: .env 파일이 없어도 에러 없이 진행
    // (프로덕션에서는 환경 변수를 직접 설정하므로)
    dotenvy::dotenv().ok();
    
    // 로깅 설정. RUST_LOG 환경 변수로 로그 레벨 조절 가능
    // 예: RUST_LOG=debug cargo run
    tracing_subscriber::init();

    // ==========================================
    // 2단계: 데이터베이스 연결 풀 생성
    // ==========================================
    // 왜 커넥션 풀인가?
    // - DB 연결은 생성 비용이 높음 (TCP 핸드셰이크, 인증 등)
    // - 매 요청마다 연결하면 성능 저하
    // - 풀에서 미리 만들어둔 연결을 재사용하면 빠름
    let database_url = std::env::var("DATABASE_URL")?;
    let pool = PgPoolOptions::new()
        .max_connections(50)  // 최대 동시 연결 수
        .min_connections(5)   // 최소 유지 연결 (항상 이만큼은 열어둠)
        .acquire_timeout(std::time::Duration::from_secs(3))  // 3초 안에 연결 못 얻으면 에러
        .connect(&database_url)
        .await?;
    
    // 왜 이 숫자들인가?
    // - max_connections(50): CPU 코어 수 * 2 + 여유분. 너무 많으면 DB에 부담
    // - min_connections(5): Cold start 방지. 트래픽 없을 때도 연결 유지
    // - acquire_timeout(3초): 풀이 가득 찼을 때 무한 대기 방지

    // ==========================================
    // 3단계: Redis 클라이언트 설정
    // ==========================================
    // Redis는 캐싱용. DB 쿼리 결과를 캐싱해서 응답 속도 향상
    let redis_client = redis::Client::open(
        std::env::var("REDIS_URL")?
    )?;

    // ==========================================
    // 4단계: 앱 상태 구성
    // ==========================================
    // AppState는 모든 핸들러에서 공유하는 상태입니다.
    // DB 풀, Redis 클라이언트 등을 담아서 의존성 주입처럼 사용
    let app_state = AppState {
        db: pool,
        redis: redis_client,
    };

    // ==========================================
    // 5단계: 라우터 구성
    // ==========================================
    // 라우터는 URL → 핸들러 매핑을 정의합니다.
    let app = Router::new()
        // 헬스체크: 로드밸런서가 서버 상태 확인용으로 호출
        .route("/health", get(health_check))
        
        // RESTful API 설계:
        // GET /users → 목록 조회
        // POST /users → 새 사용자 생성
        .route("/api/v1/users", get(list_users).post(create_user))
        
        // GET /users/:id → 특정 사용자 조회
        // PUT /users/:id → 특정 사용자 수정
        .route("/api/v1/users/:id", get(get_user).put(update_user))
        
        .route("/api/v1/analytics", post(track_event))
        
        // 미들웨어 레이어 (순서 중요: 아래에서 위로 실행됨)
        .layer(TraceLayer::new_for_http())  // 요청/응답 로깅
        .layer(CorsLayer::permissive())     // CORS 허용
        .with_state(app_state);             // 상태 주입

    // ==========================================
    // 6단계: 서버 시작
    // ==========================================
    // 0.0.0.0은 모든 네트워크 인터페이스에서 접속 허용
    // 127.0.0.1로 하면 로컬에서만 접속 가능
    let addr = SocketAddr::from(([0, 0, 0, 0], 8080));
    tracing::info!("Server listening on {}", addr);
    
    axum::Server::bind(&addr)
        .serve(app.into_make_service())
        .await?;

    Ok(())
}

// Node.js에서 자주 발생하는 버그
app.get('/users', (req, res) => {
  const page = req.query.page;  // "1" (문자열!)
  const offset = (page - 1) * 10;  // NaN 또는 예상치 못한 값
  // 타입 에러가 런타임에서야 발견됨
});

use axum::{
    extract::{Path, Query, State},
    http::StatusCode,
    Json,
};
use serde::{Deserialize, Serialize};

// ==========================================
// 요청 파라미터 정의
// ==========================================
// Deserialize 트레잇을 derive하면 Axum이 자동으로 쿼리 스트링을 파싱
// Option<T>는 선택적 파라미터를 의미
#[derive(Deserialize)]
pub struct UserQuery {
    page: Option<u32>,      // ?page=1 (없으면 None)
    limit: Option<u32>,     // ?limit=20
    search: Option<String>, // ?search=john
}
// 왜 u32인가? 
// - 페이지 번호는 음수가 될 수 없음
// - i32보다 의도가 명확함

// ==========================================
// 응답 구조체 정의
// ==========================================
// Serialize 트레잇으로 자동 JSON 변환
#[derive(Serialize)]
pub struct UserResponse {
    id: i64,
    name: String,
    email: String,
    created_at: chrono::DateTime<chrono::Utc>,
}
// 왜 created_at에 chrono를 쓰나?
// - Rust 표준 라이브러리에는 DateTime이 없음
// - chrono는 사실상 표준으로 쓰이는 날짜/시간 라이브러리
// - serde와 잘 통합됨

// ==========================================
// 핸들러 함수
// ==========================================
pub async fn list_users(
    // State 추출자: AppState에서 DB 풀을 가져옴
    State(state): State<AppState>,
    // Query 추출자: 쿼리 스트링을 UserQuery로 파싱
    Query(params): Query<UserQuery>,
) -> Result<Json<Vec<UserResponse>>, AppError> {
    // unwrap_or: None이면 기본값 사용
    let page = params.page.unwrap_or(1);
    
    // .min(100): limit이 100을 넘지 못하게 제한
    // 왜? 악의적 사용자가 limit=999999 보내면 DB 과부하
    let limit = params.limit.unwrap_or(20).min(100);
    
    let offset = (page - 1) * limit;

    // sqlx::query_as! 매크로의 장점:
    // 1. 컴파일 타임에 SQL 문법 검사 (DB에 연결해서 확인)
    // 2. 결과를 자동으로 UserResponse로 매핑
    // 3. SQL 인젝션 불가능 ($1, $2 바인딩)
    let users = sqlx::query_as!(
        UserResponse,
        r#"
        SELECT id, name, email, created_at
        FROM users
        WHERE ($1::text IS NULL OR name ILIKE '%' || $1 || '%')
        ORDER BY created_at DESC
        LIMIT $2 OFFSET $3
        "#,
        params.search,     // $1: 검색어 (없으면 NULL)
        limit as i64,      // $2: 페이지 크기
        offset as i64      // $3: 시작 위치
    )
    .fetch_all(&state.db)
    .await?;  // 에러 발생 시 자동으로 AppError로 변환

    // Json()으로 감싸면 자동으로 JSON 응답 + Content-Type 헤더 설정
    Ok(Json(users))
}

// Result<T, E>는 두 가지 상태를 가짐:
// - Ok(T): 성공, T 타입의 값을 담고 있음
// - Err(E): 실패, E 타입의 에러를 담고 있음

// 예시: 파일 읽기
let content = std::fs::read_to_string("config.json");
// content는 Result<String, std::io::Error> 타입

// 이 Result를 처리하지 않으면 컴파일 경고!
// "unused Result that must be used"

use axum::{
    http::StatusCode,
    response::{IntoResponse, Response},
    Json,
};
use serde_json::json;

// ==========================================
// 애플리케이션 에러 타입 정의
// ==========================================
// 모든 에러를 하나의 enum으로 통합
// 왜 enum인가? → 패턴 매칭으로 에러 종류별 처리 가능
#[derive(Debug)]
pub enum AppError {
    // DB 관련 에러
    Database(sqlx::Error),
    // 입력값 검증 실패
    Validation(String),
    // 리소스 없음 (404)
    NotFound(String),
    // 인증 실패 (401)
    Unauthorized,
    // 기타 에러 (500)
    Internal(anyhow::Error),
}

// ==========================================
// HTTP 응답으로 변환
// ==========================================
// IntoResponse 트레잇을 구현하면 핸들러에서 바로 반환 가능
impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        // 에러 종류에 따라 다른 HTTP 상태 코드와 메시지 반환
        let (status, message) = match self {
            // DB 에러는 내부 에러로 처리 (상세 내용 숨김)
            AppError::Database(e) => {
                // 서버 로그에는 상세 에러 기록
                tracing::error!("Database error: {:?}", e);
                // 클라이언트에는 일반적인 메시지만
                (StatusCode::INTERNAL_SERVER_ERROR, "Database error".to_string())
            }
            // 검증 에러는 사용자에게 상세 내용 전달
            AppError::Validation(msg) => {
                (StatusCode::BAD_REQUEST, msg)
            }
            // 404 에러
            AppError::NotFound(resource) => {
                (StatusCode::NOT_FOUND, format!("{} not found", resource))
            }
            // 인증 에러
            AppError::Unauthorized => {
                (StatusCode::UNAUTHORIZED, "Unauthorized".to_string())
            }
            // 기타 내부 에러
            AppError::Internal(e) => {
                tracing::error!("Internal error: {:?}", e);
                (StatusCode::INTERNAL_SERVER_ERROR, "Internal server error".to_string())
            }
        };

        // JSON 형식으로 에러 응답
        let body = Json(json!({
            "error": message,
            "status": status.as_u16()
        }));

        (status, body).into_response()
    }
}

// ==========================================
// 자동 에러 변환 (From 트레잇)
// ==========================================
// sqlx::Error를 AppError로 자동 변환
// 덕분에 ? 연산자 사용 가능
impl From<sqlx::Error> for AppError {
    fn from(err: sqlx::Error) -> Self {
        AppError::Database(err)
    }
}

// anyhow::Error도 자동 변환
impl From<anyhow::Error> for AppError {
    fn from(err: anyhow::Error) -> Self {
        AppError::Internal(err)
    }
}