rust-happy-log 😊

一个美观、高性能的 Rust 日志库，支持控制台和文件输出。

✨ 特性

• 🎨 美观输出: 支持彩色输出和 emoji 图标，让日志更易读
• 🚀 高性能: 异步写入，主线程零阻塞，使用 crossbeam-channel 实现高效队列
• 🔒 线程安全: 全局单例模式，多线程环境下安全使用
• 📁 文件轮转: 支持按文件大小自动轮转，自动管理备份文件
• ⚙️ 灵活配置: Builder 模式配置，简单易用
• 📍 位置信息: 自动记录文件名和行号，快速定位问题
• 🎯 零依赖侵入: 全局单例，各模块无需传递 Logger 实例

📦 安装

在 Cargo.toml 中添加依赖：

[dependencies]
rust-happy-log = "0.1"

🚀 快速开始

基础使用

use rust_happy_log::{LoggerBuilder, Level, info, warn, error};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 初始化全局日志器（仅需一次）
    LoggerBuilder::new()
        .level(Level::Info)
        .console(true)
        .init()?;

    // 在任意位置使用便捷宏
    info!("应用启动");
    warn!("这是一个警告: {}", "注意");
    error!("发生错误: {}", "错误信息");

    Ok(())
}

输出到文件

use rust_happy_log::{LoggerBuilder, Level, info};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    LoggerBuilder::new()
        .level(Level::Info)
        .console(true)                          // 控制台输出
        .file("logs/app.log")                   // 文件输出
        .file_max_size(10 * 1024 * 1024)       // 10MB 轮转
        .file_max_backups(5)                    // 保留 5 个备份
        .init()?;

    info!("日志将同时输出到控制台和文件");
    Ok(())
}

多模块使用（全局单例）

use rust_happy_log::{LoggerBuilder, Level, info, error};

// 模块 A
mod auth {
    use rust_happy_log::info;
    
    pub fn login(user: &str) {
        info!("用户 {} 登录", user);  // 直接使用，无需传递 Logger
    }
}

// 模块 B
mod database {
    use rust_happy_log::error;
    
    pub fn query(sql: &str) {
        error!("查询失败: {}", sql);  // 直接使用全局实例
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 仅在主函数初始化一次
    LoggerBuilder::new()
        .level(Level::Info)
        .console(true)
        .init()?;

    // 各模块直接使用，无需传递 Logger 实例
    auth::login("admin");
    database::query("SELECT * FROM users");

    Ok(())
}

🎨 输出示例

控制台彩色输出效果：

[2025-10-06 15:24:30.123] 🔍 TRACE 这是追踪级别日志
[2025-10-06 15:24:30.124] 🐛 DEBUG 这是调试级别日志
[2025-10-06 15:24:30.125] ℹ️  INFO  应用启动成功
[2025-10-06 15:24:30.126] ⚠️  WARN  这是一个警告
[2025-10-06 15:24:30.127] ❌ ERROR 发生错误

⚙️ 配置选项

完整配置示例

use rust_happy_log::{LoggerBuilder, Level};

LoggerBuilder::new()
    // 日志级别
    .level(Level::Debug)
    
    // 控制台配置
    .console(true)                    // 启用控制台输出
    .console_color(true)              // 彩色输出
    .console_emoji(true)              // emoji 图标
    .console_thread(true)             // 显示线程 ID
    .console_location(true)           // 显示文件位置（文件名:行号）
    
    // 文件配置
    .file("logs/app.log")             // 日志文件路径
    .file_max_size(10 * 1024 * 1024) // 最大 10MB
    .file_max_backups(5)              // 保留 5 个备份文件
    
    .init()
    .expect("日志初始化失败");

日志级别

• Level::Trace: 最详细的日志，用于追踪程序执行
• Level::Debug: 调试信息
• Level::Info: 一般信息（默认）
• Level::Warn: 警告信息
• Level::Error: 错误信息

运行时调整级别

use rust_happy_log::{Logger, Level};

// 获取全局 Logger 并调整级别
if let Ok(logger) = Logger::global() {
    logger.set_level(Level::Debug);
}

📝 可用宏

trace!("追踪信息: {}", value);
debug!("调试信息: {}", value);
info!("一般信息: {}", value);
warn!("警告信息: {}", value);
error!("错误信息: {}", value);

所有宏都支持 format! 风格的格式化。

🏗️ 架构设计

核心特性

1. 全局单例: 使用 once_cell::OnceCell 实现线程安全的全局实例
2. 异步写入: 后台线程处理日志写入，主线程零阻塞
3. 高性能队列: 使用 crossbeam-channel 实现无锁队列
4. 优雅关闭: 程序退出时自动刷新所有日志

性能优化

• 使用有界队列（容量 10000）避免内存无限增长
• 非阻塞发送，队列满时丢弃日志而不阻塞主线程
• 使用 parking_lot::Mutex 替代标准库 Mutex，性能更优
• 文件写入使用 BufWriter 缓冲，减少系统调用

📚 示例

查看 examples/ 目录获取更多示例：

# 基础使用
cargo run --example basic

# 文件输出
cargo run --example file_output

# 多模块使用
cargo run --example multi_module

# 高级配置
cargo run --example advanced

🔧 开发

# 检查代码
cargo check

# 运行测试
cargo test

# 格式化代码
cargo fmt

# Clippy 检查
cargo clippy

# 构建文档
cargo doc --open

📄 许可证

本项目采用双许可证：

• MIT License
• Apache License 2.0

您可以选择其中任意一个许可证使用本项目。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📮 联系方式

• 仓库: https://github.com/yourusername/rust-happy-log
• 问题反馈: https://github.com/yourusername/rust-happy-log/issues

🙏 致谢

本项目使用了以下优秀的 Rust 库：

• colored - 彩色终端输出
• crossbeam-channel - 高性能并发通道
• once_cell - 单例模式支持
• thiserror - 错误处理
• chrono - 时间处理
• parking_lot - 高性能同步原语