PAYATHON 2026

如何在 CLI 中分离调试日志与用户界面输出?

技术老齐

结论

将用户提示和诊断日志分成两套输出:

  • 用户提示由专门的 Ui 或 Reporter 类型负责。
  • 调试信息仍使用 log crate。
  • 程序启动时根据 --debug 设置 Ui 的模式,业务代码不再重复判断 args.debug。
  • 日志器始终初始化并写入文件。启用 --debug 后,再将日志同时输出到终端。

用户提示不适合直接写成 log::info!,因为它与诊断日志面向不同的读者,对格式和生命周期的要求也不同。

集中管理用户提示

可以把模式判断封装进一个类型:

use std::fmt;

#[derive(Clone, Copy)]
struct Ui {
    visible: bool,
}

impl Ui {
    fn new(visible: bool) -> Self {
        Self { visible }
    }

    fn info(&self, message: fmt::Arguments<'_>) {
        if self.visible {
            eprintln!("[INF] {message}");
        }
    }

    fn error(&self, message: fmt::Arguments<'_>) {
        if self.visible {
            eprintln!("[ERR] {message}");
        }
    }
}

显示模式只需在程序启动时确定:

fn main() {
    let args = Args::parse();

    init_logging(args.debug);

    let ui = Ui::new(!args.debug);

    log::debug!("executing something_happens function");
    ui.info(format_args!("Executing some function"));

    if let Err(error) = something_happens() {
        log::error!("something_happens failed: {error:?}");
        ui.error(format_args!("{error}"));
        std::process::exit(1);
    }
}

业务代码可以同时记录用户提示和诊断信息,无须反复读取命令行参数:

fn process_file(ui: &Ui, path: &str) {
    log::debug!("processing file: {path}");
    ui.info(format_args!("正在处理 {path}"));

    // ...
}

普通模式只显示简化后的用户提示。调试模式关闭 Ui 输出,由终端显示详细日志。模式切换统一放在初始化阶段处理。

始终初始化日志器

如果仅在 --debug 模式下调用 env_logger::init(),普通模式产生的日志就无法写入文件。日志器应在所有模式下初始化,--debug 只决定是否将日志同时复制到终端。

可以为 env_logger 提供自定义 Write,固定写入文件,并根据配置选择是否写入标准错误流:

use log::LevelFilter;
use std::fs::{File, OpenOptions};
use std::io::{self, Write};

struct LogOutput {
    file: File,
    write_to_terminal: bool,
}

impl Write for LogOutput {
    fn write(&mut self, buffer: &[u8]) -> io::Result<usize> {
        self.file.write_all(buffer)?;

        if self.write_to_terminal {
            io::stderr().write_all(buffer)?;
        }

        Ok(buffer.len())
    }

    fn flush(&mut self) -> io::Result<()> {
        self.file.flush()?;

        if self.write_to_terminal {
            io::stderr().flush()?;
        }

        Ok(())
    }
}

fn init_logging(debug: bool) {
    let file = OpenOptions::new()
        .create(true)
        .append(true)
        .open("application.log")
        .expect("failed to open log file");

    let output = LogOutput {
        file,
        write_to_terminal: debug,
    };

    env_logger::Builder::new()
        .filter_level(LevelFilter::Debug)
        .target(env_logger::Target::Pipe(Box::new(output)))
        .init();
}

这段代码主要说明输出结构。实际项目还需要处理日志文件路径、轮转、打开失败和过滤级别。这里所说的“保存所有日志”,仅指未被运行时过滤规则或编译时最大日志级别排除的记录。

文件日志和终端日志如果需要不同的格式或过滤规则,使用单一 Write 会比较受限。可以改用支持多个输出目标的日志实现,也可以自行实现 log::Log。不过,log facade 在一个进程内只能安装一个全局 logger,无法分别初始化两个彼此独立的 logger。

区分 stdout 和 stderr

CLI 通常可以这样分配输出:

  • stdout 用于命令的实际结果,供管道、重定向和脚本读取。
  • stderr 用于运行状态、用户提示和诊断日志。

因此,示例通过 eprintln! 输出用户提示。例如:

my-command > result.json

这样生成的 result.json 不会混入 [INF] 或调试日志。程序如果没有需要交给其他程序处理的结果,使用 println! 也可以,不过提前区分两个输出通道,后续处理通常更方便。

不建议用日志级别代替用户界面

一种常见做法是把简化消息记录为 info!,把详细消息记录为 debug!,再用过滤级别控制输出。但这两类消息仍可能同时出现,而且用户提示和诊断信息的语义会混在一起:

log::info!("Executing some function");
log::debug!("calling something_happens with config: {config:?}");

info! 产生的仍是诊断记录,并不等同于为终端用户设计的提示。用户提示以后可能要支持颜色、进度条、本地化或稳定的输出格式,日志则通常带有模块名、时间戳和内部上下文。单独维护 Ui 层更容易处理这些差异。

备注:内容仅供参考。