如何在 CLI 中分离调试日志与用户界面输出?
结论
将用户提示和诊断日志分成两套输出:
- 用户提示由专门的
Ui或Reporter类型负责。 - 调试信息仍使用
logcrate。 - 程序启动时根据
--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 层更容易处理这些差异。
备注:内容仅供参考。
