Python开发技巧：logging最佳实践，告别print搭建工程级日志系统

Python logging模块：告别print，搭建工程级日志系统

在Python开发中，日志系统的重要性毋庸置疑。然而许多开发者，尤其是初学者，习惯于使用print直接输出——调试时满屏信息，上线后却无法追踪。生产环境日志需要分级、持久化、格式化控制，这些功能print无法提供。那么，如何搭建一套专业的工程级日志系统呢？

快速入门：Python logging五大核心组件

Python标准库的 logging 模块，本质上是一套组件化的日志框架。理解它的五大组件，是掌握日志系统的第一步。

简单来说，Logger 负责生成日志消息，Handler 决定消息输出到哪里，Formatter 控制消息的呈现格式，Filter 过滤不需要的消息，Level 则定义消息的严重程度。

最简配置：一行代码快速搭建日志系统

如果您需要快速启用日志，basicConfig 是最简单直接的方式：

 复制代码import logging# 最简配置（同时输出到终端和文件）
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S",
    handlers=[
        logging.StreamHandler(),                    # 终端
        logging.FileHandler("app.log", encoding="utf-8"),  # 文件
    ],
)log = logging.getLogger(__name__)log.info("服务启动成功")
log.warning("磁盘使用率超过 80%%")
log.error("数据库连接超时", exc_info=True)  # 自动打印堆栈

请注意，exc_info=True 参数非常实用，当发生异常时，它会自动捕获完整的堆栈信息，无需手动调用 traceback 模块。

实用技巧：日志轮转机制，防止磁盘空间耗尽

日志文件如果不加限制，会无限增长，最终导致磁盘空间不足。这时可以使用 RotatingFileHandler 实现日志轮转：

 复制代码from logging.handlers import RotatingFileHandlerhandler = RotatingFileHandler(
    "app.log",
    maxBytes=10 * 1024 * 1024,  # 10MB
    backupCount=5,              # 保留 5 个备份
    encoding="utf-8",
)
handler.setFormatter(logging.Formatter(
    "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
))

当单个日志文件达到10MB时，自动切割并保留最近5个备份文件，既防止历史日志丢失，又避免磁盘空间持续告急。

模块化分层：大型Python项目的日志管理必备

在大型项目中，切勿全局使用同一个Logger。每个模块应拥有独立的Logger实例：

 复制代码# utils/db.py
logger = logging.getLogger("app.db")# utils/http.py
logger = logging.getLogger("app.http")

通过 logging.getLogger("app") 统一配置，子Logger自动继承父配置，省时省力。这样当某个模块出现问题时，可以快速定位到具体模块，无需在杂乱输出中手动查找。

高级用法：JSON格式化日志，轻松对接ELK平台

如果项目规模较大，需要对接ELK、Loki等日志收集平台，JSON格式的日志是最佳选择。它支持结构化解析，便于后续搜索和分析。

 复制代码import json
import logging
class JsonFormatter(logging.Formatter):
    def format(self, record: logging.LogRecord) -> str:
        log_obj = {
            "time": self.formatTime(record, self.datefmt),
            "level": record.levelname,
            "logger": record.name,
            "message": record.getMessage(),
        }
        if record.exc_info and record.exc_info[0]:
            log_obj["exception"] = self.formatException(record.exc_info)
        return json.dumps(log_obj, ensure_ascii=False)

避坑指南：常见logging使用误区，你中招了吗？

这里特别强调占位符的使用问题。许多开发者习惯用f-string拼接日志字符串，例如 f"user={user}"。但这样无论日志级别是否触发，都会立即进行字符串格式化，造成性能浪费。而使用 "user=%s" % user 的写法，只有当日志级别被触发时才会进行格式化，这就是惰性求值的优势。

开箱即用：完整日志配置函数模板

以上讲解了许多技巧，最后提供一个可直接复制使用的配置函数：

 复制代码import logging
import logging.handlers
import sys
from pathlib import Path
def setup_logger(
    name: str = __name__,
    level: str = "INFO",
    log_file: str | None = None,
) -> logging.Logger:
    logger = logging.getLogger(name)
    if logger.handlers:
        return logger  # 防止重复添加    logger.setLevel(getattr(logging, level.upper(), logging.INFO))    fmt = logging.Formatter(
        "%(asctime)s [%(levelname)s] %(name)s:%(lineno)d: %(message)s"
    )    # 终端 Handler（始终输出 >= WARNING）
    console = logging.StreamHandler(sys.stdout)
    console.setLevel(logging.WARNING)
    console.setFormatter(fmt)
    logger.addHandler(console)    # 文件 Handler 带轮转（输出全部级别）
    if log_file:
        Path(log_file).parent.mkdir(parents=True, exist_ok=True)
        handler = logging.handlers.RotatingFileHandler(
            log_file, maxBytes=10 << 20, backupCount=5, encoding="utf-8"
        )
        handler.setLevel(logging.DEBUG)
        handler.setFormatter(fmt)
        logger.addHandler(handler)    return logger
# 使用
log = setup_logger("my_app", level="DEBUG", log_file="logs/my_app.log")
log.info(" Logger 初始化完成")

总结：不同场景的日志方案推荐

• 小脚本：使用 logging.basicConfig 一行配置即可
• 中型项目：采用模块化 Logger + 文件轮转机制
• 大型项目/微服务架构：使用JSON格式化日志，并收集至ELK或Loki平台

从现在开始，所有Python项目都值得用 logging 替代 print，这是专业开发者与新手开发者的重要分水岭。