Loguru项目中的多行日志格式化技巧与实践

在实际开发过程中，日志记录是调试和监控的重要工具。当我们需要记录包含多行文本的日志时，如何优雅地实现格式化显示成为一个常见需求。本文将以Python的Loguru日志库为例，深入探讨多行日志记录的解决方案。

问题背景

开发者在使用Loguru时，经常会遇到需要记录多行文本的情况。例如，当我们需要记录一个表格数据或复杂数据结构时，直接使用换行符分隔的字符串进行日志记录：

logger.info('1\n2\n3')

理想情况下，我们希望每行日志都能显示完整的日志头信息（时间戳、日志级别等），而不是只有第一行有头信息，后续行只有内容。

初步解决方案

一个直观的解决方案是自定义日志格式化函数。通过分割消息内容，为每一行单独添加日志头：

def custom_formatter(record):
    message = record["message"]
    lines = message.split("\n")
    
    formatted_lines = [
        "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | "
        "<level>{level: <8}</level> | "
        f"<level>{line}</level>\n"
        for line in lines
    ]
    return "".join(formatted_lines)

这种方法在大多数情况下工作良好，但当遇到包含特殊字符（如反斜杠）的消息时，会导致格式化错误：

logger.info('\\')  # 会抛出ValueError异常

问题分析

这种实现方式的问题根源在于将用户消息直接嵌入到格式字符串中。当消息包含特殊字符时，会干扰Loguru的标签解析机制。特别是当消息包含反斜杠时，会被错误地解析为转义字符，导致标签不匹配。

改进方案

方案一：使用extra字典传递数据

更安全的做法是通过extra字典传递多行数据，避免直接字符串拼接：

def custom_formatter(record):
    message = record["message"]
    lines = message.split("\n")
    record["extra"]["lines"] = lines

    formatted_lines = [
        "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | "
        "<level>{level: <8}</level> | "
        f"<level>{{extra[lines][{i}]}}</level>\n"
        for i in range(len(lines))
    ]
    return "".join(formatted_lines)

这种方法通过索引访问extra字典中的行数据，避免了直接将用户消息嵌入格式字符串。

方案二：辅助函数逐行记录

更推荐的做法是编写辅助函数，逐行记录日志：

def log_multi_line_message(message: str):
    for line in message.split("\n"):
        logger.opt(depth=1).info(line)

这种方法简单可靠，完全避免了格式化问题，是生产环境中的首选方案。

方案三：显式换行格式化

对于简单的多行文本，可以直接在格式字符串中使用换行符：

table = "1\n2\n3"
logger.info("My table:\n{}", table)

这种方式保持了消息的完整性，同时提供了良好的可读性。

最佳实践建议

1. 对于简单的多行日志，优先使用显式换行格式化
2. 对于复杂的多行结构，使用辅助函数逐行记录
3. 避免直接拼接用户消息到格式字符串中
4. 考虑使用logger.opt()方法来控制日志记录的深度和行为

安全注意事项

在处理日志消息时，应当注意：

1. 避免直接将不受信任的输入嵌入格式字符串
2. 对特殊字符进行适当转义处理
3. 考虑日志注入攻击的可能性

通过遵循这些原则和实践，开发者可以安全、高效地使用Loguru记录多行日志，满足各种复杂的日志记录需求。

Loguru作为Python生态中强大的日志库，其灵活性和易用性使其成为许多项目的首选。理解其内部工作原理并掌握正确的使用模式，可以帮助开发者充分发挥其潜力，构建更健壮的日志系统。