9장: CLI 도구 개발

[package]
name = "myctl"
version = "0.1.0"
edition = "2024"
 
[dependencies]
clap = { version = "4.4", features = ["derive", "env"] }
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
config = "0.14"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
indicatif = "0.17"
anyhow = "1"

use clap::{Parser, Subcommand};
use anyhow::Result;
 
#[derive(Parser)]
#[command(
    name = "myctl",
    version,
    about = "백엔드 관리 CLI 도구",
    long_about = "데이터베이스 마이그레이션, 시드 데이터 생성, 서버 관리 등을 수행하는 CLI 도구입니다."
)]
struct Cli {
    /// 설정 파일 경로
    #[arg(short, long, default_value = "config.toml")]
    config: String,
 
    /// 로그 레벨 (trace, debug, info, warn, error)
    #[arg(short, long, default_value = "info", env = "LOG_LEVEL")]
    log_level: String,
 
    /// 출력 형식
    #[arg(long, default_value = "text")]
    format: OutputFormat,
 
    #[command(subcommand)]
    command: Commands,
}
 
#[derive(Subcommand)]
enum Commands {
    /// 데이터베이스 관련 명령
    Db {
        #[command(subcommand)]
        action: DbCommands,
    },
    /// 서버 시작
    Serve {
        /// 포트 번호
        #[arg(short, long, default_value = "3000")]
        port: u16,
 
        /// 바인딩 주소
        #[arg(long, default_value = "0.0.0.0")]
        host: String,
    },
    /// 사용자 관리
    User {
        #[command(subcommand)]
        action: UserCommands,
    },
}
 
#[derive(Subcommand)]
enum DbCommands {
    /// 마이그레이션 실행
    Migrate,
    /// 마이그레이션 되돌리기
    Rollback {
        /// 되돌릴 단계 수
        #[arg(short, long, default_value = "1")]
        steps: u32,
    },
    /// 시드 데이터 생성
    Seed {
        /// 생성할 레코드 수
        #[arg(short, long, default_value = "100")]
        count: u32,
    },
}
 
#[derive(Subcommand)]
enum UserCommands {
    /// 사용자 목록 조회
    List {
        #[arg(long, default_value = "20")]
        limit: u32,
    },
    /// 관리자 생성
    CreateAdmin {
        /// 관리자 이름
        #[arg(short, long)]
        name: String,
        /// 관리자 이메일
        #[arg(short, long)]
        email: String,
    },
}
 
#[derive(Clone, clap::ValueEnum)]
enum OutputFormat {
    Text,
    Json,
}
 
#[tokio::main]
async fn main() -> Result<()> {
    let cli = Cli::parse();
 
    // 로깅 초기화
    setup_logging(&cli.log_level);
 
    // 설정 로드
    let config = load_config(&cli.config)?;
 
    // 서브커맨드 분기
    match cli.command {
        Commands::Db { action } => handle_db(action, &config).await?,
        Commands::Serve { port, host } => handle_serve(port, &host, &config).await?,
        Commands::User { action } => handle_user(action, &config).await?,
    }
 
    Ok(())
}

# 도움말
myctl --help
myctl db --help
myctl db seed --help
 
# 사용 예시
myctl db migrate
myctl db seed --count 500
myctl db rollback --steps 2
myctl serve --port 8080
myctl user list --limit 50
myctl user create-admin --name "Admin" --email "admin@example.com"

use config::{Config, ConfigError, File, Environment};
use serde::Deserialize;
 
#[derive(Debug, Deserialize, Clone)]
pub struct AppConfig {
    pub database: DatabaseConfig,
    pub server: ServerConfig,
    pub auth: AuthConfig,
}
 
#[derive(Debug, Deserialize, Clone)]
pub struct DatabaseConfig {
    pub url: String,
    pub max_connections: u32,
    pub min_connections: u32,
}
 
#[derive(Debug, Deserialize, Clone)]
pub struct ServerConfig {
    pub host: String,
    pub port: u16,
}
 
#[derive(Debug, Deserialize, Clone)]
pub struct AuthConfig {
    pub jwt_secret: String,
    pub token_expiry_hours: u64,
}
 
pub fn load_config(path: &str) -> Result<AppConfig, ConfigError> {
    let config = Config::builder()
        // 1. 기본값
        .set_default("server.host", "0.0.0.0")?
        .set_default("server.port", 3000)?
        .set_default("database.max_connections", 20)?
        .set_default("database.min_connections", 5)?
 
        // 2. 설정 파일 (선택적)
        .add_source(File::with_name(path).required(false))
 
        // 3. 환경 변수 (APP_ 접두사, __ 로 중첩 구분)
        // APP_DATABASE__URL → database.url
        .add_source(
            Environment::with_prefix("APP")
                .separator("__")
        )
 
        .build()?;
 
    config.try_deserialize()
}

[database]
url = "postgresql://localhost/mydb"
max_connections = 20
min_connections = 5
 
[server]
host = "0.0.0.0"
port = 3000
 
[auth]
jwt_secret = "change-me-in-production"
token_expiry_hours = 24

use tracing::{info, warn, error, debug, instrument};
use tracing_subscriber::{EnvFilter, fmt};
 
fn setup_logging(level: &str) {
    let filter = EnvFilter::try_from_default_env()
        .unwrap_or_else(|_| EnvFilter::new(level));
 
    fmt()
        .with_env_filter(filter)
        .with_target(true)
        .with_thread_ids(true)
        .with_file(true)
        .with_line_number(true)
        .init();
}
 
// #[instrument]는 함수 진입/퇴장을 자동 추적
#[instrument(skip(pool), fields(user_count))]
async fn seed_users(pool: &sqlx::PgPool, count: u32) -> anyhow::Result<()> {
    info!(count, "시드 데이터 생성 시작");
 
    for i in 0..count {
        let name = format!("User {}", i);
        let email = format!("user{}@example.com", i);
 
        match create_user(pool, &name, &email).await {
            Ok(_) => debug!(index = i, name, "사용자 생성 성공"),
            Err(e) => warn!(index = i, error = %e, "사용자 생성 실패"),
        }
    }
 
    info!("시드 데이터 생성 완료");
    Ok(())
}

2026-03-31T10:00:00.000Z  INFO myctl::db: 시드 데이터 생성 시작 count=100
2026-03-31T10:00:00.005Z DEBUG myctl::db: 사용자 생성 성공 index=0 name="User 0"
2026-03-31T10:00:00.010Z DEBUG myctl::db: 사용자 생성 성공 index=1 name="User 1"
...
2026-03-31T10:00:01.234Z  INFO myctl::db: 시드 데이터 생성 완료

use indicatif::{ProgressBar, ProgressStyle, MultiProgress};
use std::time::Duration;
 
async fn seed_with_progress(pool: &sqlx::PgPool, count: u32) -> anyhow::Result<()> {
    let pb = ProgressBar::new(count as u64);
    pb.set_style(
        ProgressStyle::with_template(
            "{spinner:.green} [{elapsed_precise}] [{bar:40.cyan/blue}] {pos}/{len} ({eta})"
        )?
        .progress_chars("=>-"),
    );
 
    for i in 0..count {
        let name = format!("User {}", i);
        let email = format!("user{}@example.com", i);
 
        create_user(pool, &name, &email).await?;
        pb.inc(1);
    }
 
    pb.finish_with_message("시드 데이터 생성 완료");
    Ok(())
}
 
// 여러 작업의 동시 진행 표시
async fn parallel_seed(pool: &sqlx::PgPool) -> anyhow::Result<()> {
    let multi = MultiProgress::new();
 
    let pb_users = multi.add(ProgressBar::new(100));
    pb_users.set_prefix("사용자");
    pb_users.set_style(ProgressStyle::with_template(
        "{prefix:.bold} [{bar:30}] {pos}/{len}",
    )?);
 
    let pb_posts = multi.add(ProgressBar::new(500));
    pb_posts.set_prefix("게시물");
    pb_posts.set_style(ProgressStyle::with_template(
        "{prefix:.bold} [{bar:30}] {pos}/{len}",
    )?);
 
    let pool2 = pool.clone();
    let users_task = tokio::spawn(async move {
        for i in 0..100 {
            // 사용자 생성...
            pb_users.inc(1);
            tokio::time::sleep(Duration::from_millis(10)).await;
        }
        pb_users.finish();
    });
 
    let posts_task = tokio::spawn(async move {
        for i in 0..500 {
            // 게시물 생성...
            pb_posts.inc(1);
            tokio::time::sleep(Duration::from_millis(2)).await;
        }
        pb_posts.finish();
    });
 
    tokio::join!(users_task, posts_task);
    Ok(())
}

async fn handle_db(action: DbCommands, config: &AppConfig) -> Result<()> {
    let pool = create_pool(&config.database).await?;
 
    match action {
        DbCommands::Migrate => {
            info!("마이그레이션 실행");
            sqlx::migrate!("./migrations")
                .run(&pool)
                .await?;
            println!("마이그레이션이 성공적으로 적용되었습니다.");
        }
        DbCommands::Rollback { steps } => {
            info!(steps, "마이그레이션 되돌리기");
            for _ in 0..steps {
                sqlx::migrate!("./migrations")
                    .undo(&pool, 1)
                    .await?;
            }
            println!("{}단계 롤백이 완료되었습니다.", steps);
        }
        DbCommands::Seed { count } => {
            seed_with_progress(&pool, count).await?;
        }
    }
 
    Ok(())
}
 
async fn handle_serve(port: u16, host: &str, config: &AppConfig) -> Result<()> {
    let pool = create_pool(&config.database).await?;
    let state = Arc::new(AppState { db: pool, config: config.clone() });
 
    let app = create_router(state);
    let addr = format!("{}:{}", host, port);
 
    info!(addr, "서버 시작");
    println!("서버가 {}에서 실행 중입니다", addr);
 
    let listener = tokio::net::TcpListener::bind(&addr).await?;
    axum::serve(listener, app)
        .with_graceful_shutdown(shutdown_signal())
        .await?;
 
    Ok(())
}
 
async fn shutdown_signal() {
    tokio::signal::ctrl_c()
        .await
        .expect("Ctrl+C 시그널 수신 실패");
    info!("종료 신호 수신");
}

# 타겟 추가
rustup target add x86_64-unknown-linux-musl
rustup target add aarch64-apple-darwin
rustup target add x86_64-pc-windows-msvc
 
# Linux (정적 링크)
cargo build --release --target x86_64-unknown-linux-musl
 
# macOS ARM
cargo build --release --target aarch64-apple-darwin

# 설치
cargo install cargo-dist
 
# 초기화 — 대화형으로 타겟 플랫폼 선택
cargo dist init
 
# 로컬에서 빌드 테스트
cargo dist build

[workspace.metadata.dist]
cargo-dist-version = "0.27"
ci = "github"
installers = ["shell", "homebrew"]
targets = [
    "aarch64-apple-darwin",
    "x86_64-apple-darwin",
    "x86_64-unknown-linux-gnu",
    "x86_64-pc-windows-msvc",
]

git tag v0.1.0
git push origin v0.1.0
# → GitHub Actions가 자동으로 빌드 및 릴리스 생성