Rust调试工具库dbgf的使用指南

dbgf是一个强大的Rust调试工具库，提供了丰富的调试功能和错误追踪能力，可以显著简化开发过程中的调试工作。

主要特性

1. 增强的调试输出功能
2. 结构化错误追踪
3. 上下文感知的调试信息
4. 可定制的输出格式
5. 低性能开销

安装方法

在Cargo.toml中添加依赖：

[dependencies]
dbgf = "0.3"

基本使用方法

1. 简单调试输出

use dbgf::dbgf;

fn main() {
    let x = 42;
    let name = "Alice";
    dbgf!("x={x}, name={name}");
    
    // 输出示例: [DEBUG] src/main.rs:5 - x=42, name=Alice
}

2. 结构化调试

use dbgf::{DebugStruct, dbgs};

#[derive(Debug)]
struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let p = Point { x: 10, y: 20 };
    dbgs!(p);  // 自动派生Debug trait的结构体可以直接使用
    
    // 自定义格式输出
    dbgf!("Point coordinates: x={}, y={}", p.x, p.y);
}

3. 错误追踪

use dbgf::{ErrorTrace, wrap_err};

fn parse_number(s: &str) -> Result<i32, Box<dyn std::error::Error>> {
    s.parse().wrap_err("Failed to parse number")
}

fn process_input(input: &str) -> Result<(), Box<dyn std::error::Error>> {
    let num = parse_number(input)?;
    if num > 100 {
        return Err("Number too large".into());
    }
    Ok(())
}

fn main() {
    if let Err(e) = process_input("abc") {
        eprintln!("Error trace:");
        eprintln!("{}", e.error_trace());
    }
    
    // 输出示例:
    // Error trace:
    // Failed to parse number
    // Caused by: invalid digit found in string
}

高级功能

1. 条件调试

use dbgf::{dbg_if, Level};

fn expensive_operation(x: i32) -> i32 {
    // 只在调试级别为Debug或更高时执行
    dbg_if!(Level::Debug, {
        println!("Performing expensive calculation...");
        x * x + 2 * x + 1
    })
}

2. 性能计时

use dbgf::timeit;

fn main() {
    let result = timeit!("fibonacci", {
        // 模拟耗时操作
        std::thread::sleep(std::time::Duration::from_millis(100));
        42
    });
    
    // 输出示例: [TIMING] fibonacci took 100.23ms
}

3. 自定义输出目标

use dbgf::{Debugger, Level};
use std::fs::File;

fn main() {
    let log_file = File::create("debug.log").unwrap();
    let mut debugger = Debugger::new()
        .level(Level::Debug)
        .output(log_file);
    
    debugger.log("This will be written to debug.log");
}

配置选项

可以通过环境变量配置dbgf的行为：

# 设置日志级别
export DBGF_LEVEL=DEBUG

# 启用彩色输出
export DBGF_COLOR=true

# 设置时间戳格式
export DBGF_TIMESTAMP="%Y-%m-%d %H:%M:%S"

性能考虑

在生产环境中，建议通过设置日志级别来禁用不必要的调试输出：

dbgf::set_level(dbgf::Level::Error);  // 只显示错误信息

或者通过环境变量：

export DBGF_LEVEL=ERROR

dbgf库经过优化，当调试语句被禁用时，几乎不会产生性能开销。

完整示例代码

下面是一个综合使用dbgf各种功能的完整示例：

use dbgf::{dbgf, dbgs, ErrorTrace, wrap_err, dbg_if, Level, timeit, Debugger};
use std::fs::File;

#[derive(Debug)]
struct User {
    id: u32,
    name: String,
    age: u8,
}

fn parse_id(s: &str) -> Result<u32, Box<dyn std::error::Error>> {
    s.parse().wrap_err("Failed to parse user ID")
}

fn create_user(id_str: &str, name: &str, age: u8) -> Result<User, Box<dyn std::error::Error>> {
    // 条件调试示例
    let id = dbg_if!(Level::Debug, {
        println!("Parsing user ID...");
        parse_id(id_str)?
    });
    
    // 简单调试输出
    dbgf!("Creating user: name={name}, age={age}");
    
    if age < 18 {
        return Err("User must be at least 18 years old".into());
    }
    
    Ok(User { id, name: name.to_string(), age })
}

fn main() {
    // 设置日志级别
    dbgf::set_level(Level::Debug);
    
    // 性能计时示例
    let user = timeit!("create_user", {
        match create_user("123a", "Bob", 25) {
            Ok(u) => {
                // 结构化调试输出
                dbgs!(u);
                Some(u)
            },
            Err(e) => {
                // 错误追踪
                eprintln!("Error creating user:");
                eprintln!("{}", e.error_trace());
                None
            }
        }
    });
    
    // 自定义输出目标示例
    let log_file = File::create("app.log").unwrap();
    let mut debugger = Debugger::new()
        .level(Level::Info)
        .output(log_file);
    
    debugger.log(&format!("Application finished with user: {:?}", user.is_some()));
    
    // 另一个性能计时示例
    let _ = timeit!("fibonacci", {
        fn fib(n: u32) -> u32 {
            match n {
                0 => 1,
                1 => 1,
                _ => fib(n-1) + fib(n-2)
            }
        }
        fib(10)
    });
}

这个示例展示了：

1. 简单调试输出(dbgef!)
2. 结构化调试输出(dbgs!)
3. 错误追踪和包装(wrap_err, error_trace)
4. 条件调试(dbg_if!)
5. 性能计时(timeit!)
6. 自定义日志输出(Debugger)
7. 日志级别控制

可以根据实际需求选择使用其中的功能组合。