fbc_starter/

lib.rs

pub mod config;
#[cfg(feature = "database")]
pub mod database;
pub mod error;
pub mod handlers;
pub mod middleware;
#[cfg(feature = "redis")]
pub mod redis;
pub mod routing;
pub mod server;

pub use config::Config;
#[cfg(feature = "database")]
pub use database::{
    get_database, get_mysql_pool, get_postgres_pool, get_sqlite_pool, init_database, DatabasePool,
};
pub use error::{AppError, AppResult};
pub use handlers::AppState;
#[cfg(feature = "redis")]
pub use redis::{get_redis_client, get_redis_connection, init_redis};
pub use routing::{registry, RouteGroup, RouteRegistry};
pub use server::Server;

/// 启动 Web 服务器（自动加载配置和初始化日志）
///
/// 此函数会：
/// 1. 从环境变量加载配置（.env 文件）
/// 2. 初始化日志系统（时区设置为 +8）
/// 3. 启动 Web 服务器
pub async fn start() -> Result<(), Box<dyn std::error::Error>> {
    let config = load_and_init_config(true)?;
    let server = create_server(config).await?;
    server
        .start()
        .await
        .map_err(|e| -> Box<dyn std::error::Error> { format!("{}", e).into() })
}

/// 启动 Web 服务器并添加自定义路由
///
/// # 参数
/// - `custom_routes`: 可选的自定义路由 Router，会与基础路由（/health 等）自动合并
///
/// # 示例
/// ```no_run
/// use fbc_starter::start_with_routes;
/// use axum::{routing::get, Router};
///
/// #[tokio::main]
/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
///     // 定义你的 API 路由
///     let api_routes = Router::new()
///         .route("/api/users", get(get_users))
///         .route("/api/posts", get(get_posts));
///     
///     // 启动服务器并合并路由
///     start_with_routes(Some(api_routes)).await?;
///     Ok(())
/// }
///
/// async fn get_users() -> &'static str { "users" }
/// async fn get_posts() -> &'static str { "posts" }
/// ```
pub async fn start_with_routes(
    custom_routes: Option<axum::Router>,
) -> Result<(), Box<dyn std::error::Error>> {
    let config = load_and_init_config(true)?;
    let server = create_server(config).await?;
    server
        .start_with_routes(custom_routes)
        .await
        .map_err(|e| -> Box<dyn std::error::Error> { format!("{}", e).into() })
}

/// 使用已有配置启动 Web 服务器（不自动初始化日志）
///
/// 适用于需要自定义日志配置的场景
pub async fn start_with_config(config: Config) -> Result<(), anyhow::Error> {
    let server = Server::new(config).await?;
    server.start().await
}

/// 加载配置并初始化系统（内部函数）
///
/// # 参数
/// - `verbose`: 是否显示详细的加载信息
fn load_and_init_config(verbose: bool) -> Result<Config, Box<dyn std::error::Error>> {
    if verbose {
        eprintln!("正在加载配置...");
    }

    // 加载配置
    let config = match Config::from_env() {
        Ok(cfg) => {
            if verbose {
                eprintln!("✓ 配置加载成功, 日志级别: {}", cfg.log.level);
            }
            cfg
        }
        Err(e) => {
            if verbose {
                eprintln!("⚠ 警告: 无法从环境变量加载配置: {}, 使用默认配置", e);
            } else {
                eprintln!("警告: 无法从环境变量加载配置，使用默认配置");
            }
            Config::default()
        }
    };

    // 初始化日志
    if verbose {
        eprintln!("正在初始化日志系统...");
    }
    init_logging(&config).map_err(|e| -> Box<dyn std::error::Error> { format!("{}", e).into() })?;
    if verbose {
        eprintln!("✓ 日志系统初始化完成");
    }

    tracing::info!(
        "启动 {} v{}",
        env!("CARGO_PKG_NAME"),
        env!("CARGO_PKG_VERSION")
    );

    tracing::info!("服务器配置: {}:{}", config.server.addr, config.server.port);
    if let Some(ref context_path) = config.server.context_path {
        tracing::info!("上下文路径: {}", context_path);
    }

    Ok(config)
}

/// 创建并初始化服务器（内部函数）
async fn create_server(config: Config) -> Result<Server, Box<dyn std::error::Error>> {
    // 初始化数据库（如果配置了且启用了 database 特性）
    #[cfg(feature = "database")]
    if let Some(ref db_config) = config.database {
        database::init_database(
            &db_config.url,
            db_config.max_connections,
            db_config.min_connections,
        )
        .await
        .map_err(|e| -> Box<dyn std::error::Error> {
            format!("数据库初始化失败: {}", e).into()
        })?;
    }

    // 初始化 Redis（如果配置了且启用了 redis 特性）
    #[cfg(feature = "redis")]
    if let Some(ref redis_config) = config.redis {
        redis::init_redis(
            &redis_config.url,
            redis_config.password.as_deref(),
            redis_config.pool_size,
        )
        .await
        .map_err(|e| -> Box<dyn std::error::Error> {
            format!("Redis 初始化失败: {}", e).into()
        })?;
    }

    // 创建服务器
    Server::new(config)
        .await
        .map_err(|e| -> Box<dyn std::error::Error> { format!("{}", e).into() })
}

/// 初始化日志系统
///
/// 设置时区为 +8（东八区，中国时区）
fn init_logging(config: &Config) -> Result<(), anyhow::Error> {
    use time::UtcOffset;
    use tracing_subscriber::{
        fmt::time::OffsetTime, layer::SubscriberExt, util::SubscriberInitExt,
    };

    // 设置时区为 +8 (东八区，中国时区)
    let offset =
        UtcOffset::from_hms(8, 0, 0).map_err(|e| anyhow::anyhow!("无效的时区偏移: {}", e))?;
    let timer = OffsetTime::new(
        offset,
        time::format_description::parse(
            "[year]-[month]-[day] [hour]:[minute]:[second].[subsecond digits:3]",
        )
        .map_err(|e| anyhow::anyhow!("时间格式解析失败: {}", e))?,
    );

    // 初始化日志
    // 优先使用 RUST_LOG 环境变量，如果没有则使用配置的日志级别
    // 默认显示所有 crate 的 info 级别及以上的日志
    let env_filter = tracing_subscriber::EnvFilter::try_from_default_env().unwrap_or_else(|_| {
        // 如果没有设置 RUST_LOG，使用配置的日志级别，显示所有 crate 的日志
        // 格式：直接使用日志级别，如 "info" 会显示所有 crate 的 info 级别日志
        config.log.level.as_str().into()
    });

    let subscriber = tracing_subscriber::registry().with(env_filter);

    if config.log.json {
        subscriber
            .with(tracing_subscriber::fmt::layer().json().with_timer(timer))
            .init();
    } else {
        // 使用紧凑格式，禁用源代码位置显示，避免换行
        subscriber
            .with(
                tracing_subscriber::fmt::layer()
                    .compact()
                    .with_timer(timer)
                    .with_target(true)
                    .with_file(true)
                    .with_line_number(true),
            )
            .init();
    }

    Ok(())
}