Funlog

English | 中文

一个用于跟踪 Rust 函数调用的过程宏库。

简介

Funlog 是一个轻量级的 Rust 过程宏，用于自动记录函数的调用信息。它可以记录函数的参数、返回值，并支持多种日志级别和灵活的配置选项。

特性

• 🚀 零运行时开销 - 仅在 debug 构建中生效，release 构建中完全移除
• 📝 多种日志级别 - 支持 trace、debug、info、warn、error 和 print
• 🎯 灵活的参数记录 - 可选择记录所有参数、指定参数或不记录参数
• ⏰ 位置控制 - 可在函数开始、结束或两者都记录
• 🔄 返回值记录 - 可选择记录函数返回值
• 🛠️ 易于使用 - 简单的属性宏语法

安装

将以下内容添加到您的 Cargo.toml 文件中：

[dependencies]
funlog = "0.1.0"

# 如果使用日志级别（非 print），还需要添加日志库
log = "0.4"
env_logger = "0.10"

快速开始

基本用法

use funlog::funlog;

#[funlog(debug)]
fn add(a: i32, b: i32) -> i32 {
    a + b
}

fn main() {
    env_logger::init();
    let result = add(3, 5);
    println!("Result: {}", result);
}

使用 print（无需日志库）

use funlog::funlog;

#[funlog(print)]
fn greet(name: &str) {
    println!("Hello, {}!", name);
}

fn main() {
    greet("World");
}

配置选项

日志级别

• print - 使用 println! 宏（无需日志库设置）
• trace - 使用 log::trace!
• debug - 使用 log::debug!
• info - 使用 log::info!
• warn - 使用 log::warn!
• error - 使用 log::error!

参数记录选项

• all - 记录所有函数参数（默认）
• none - 不记录参数
• params(param1, param2, ...) - 记录指定参数

位置控制选项

• onStart - 仅在函数开始时记录
• onEnd - 仅在函数结束时记录
• onStartEnd - 在开始和结束时都记录（默认）

返回值记录

• retVal - 在日志中包含返回值

使用示例

记录所有参数和返回值

#[funlog(info, all, retVal)]
fn multiply(a: i32, b: i32) -> i32 {
    a * b
}

记录指定参数

#[funlog(debug, params(name, age))]
fn create_user(name: &str, age: u32, email: &str) -> String {
    format!("User: {} ({})", name, age)
}

仅在函数结束时记录

#[funlog(warn, onEnd, retVal)]
fn expensive_calculation() -> f64 {
    // 复杂计算
    std::thread::sleep(std::time::Duration::from_millis(100));
    42.0
}

组合多个选项

#[funlog(info, onStartEnd, params(input), retVal)]
fn process_data(input: &str, config: &Config) -> Result<String, Error> {
    // 处理逻辑
    Ok(input.to_uppercase())
}

示例项目

项目包含了丰富的示例，展示了所有功能组合：

# 运行基本示例
cargo run --example raw_debug

# 运行参数记录示例
cargo run --example raw_all
cargo run --example raw_params

# 运行位置控制示例
cargo run --example raw_position_start
cargo run --example raw_position_end

# 运行返回值记录示例
cargo run --example raw_return_value

# 查看所有示例
ls examples/

详细的示例说明请参考 examples/README.md。

测试

运行所有测试：

# 运行单元测试
cargo test

# 运行示例测试脚本
./run_tests.sh

工作原理

Funlog 是一个过程宏，在编译时分析函数并生成相应的日志代码。它只在 debug 构建中生效，在 release 构建中会完全移除，确保零运行时开销。

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

贡献

欢迎提交 Issue 和 Pull Request！

作者

• Levy Gu 32436334@qq.com

更新日志

v0.1.0

• 初始版本发布
• 支持多种日志级别
• 支持灵活的参数和返回值记录
• 支持位置控制
• 完整的测试覆盖和示例