Python 日志规范在团队中的落地方法

顺亿

2026-11-06 • 👁 0人浏览过

日志级别选择需严格匹配场景：DEBUG仅开发测试用且上线必关；INFO是唯一长期开启级别，记录业务动作；WARNING表潜在问题但未崩溃；ERROR必须带exc_info=True；格式化须用懒求值参数传递而非拼接或f-string。日志级别怎么选才不被同事喷团队里最常吵的不是用不用

logging

，而是谁把

logging.debug()

提到生产环境、谁又把

logging.error()

当

print()

乱打。关键不是“能不能用”，而是“在哪用、为什么用这个级别”。

DEBUG

只在开发/测试环境有效，上线前必须关掉（靠

logging.basicConfig(level=...)

或配置文件控制），否则磁盘爆得比日志内容还快

INFO

是唯一该长期开启的级别，只记录“业务发生了什么”——比如

"user_id=123 logged in"

，不记录变量快照、不打印堆栈

WARNING

不代表“问题不大”，而是“可能出错但没崩”，比如第三方 API 返回非预期状态码但兜底逻辑已生效

ERROR

必须带异常上下文：

logger.error("failed to send email", exc_info=True)

，否则查问题时只剩一句“失败了” 格式化字符串别用 % 或 .format() 打日志看似只是写法偏好，实则影响性能和可读性：字符串拼接会在日志未启用时也执行，而

logging

的懒求值机制只在真正输出时才解析参数。错：

logger.info("user %s paid %d" % (user.name, amount))

—— 拼接提前发生，哪怕日志级别是

WARNING

对：

logger.info("user %s paid %d", user.name, amount)

—— 参数延迟传入，不触发计算 Python 3.7+ 可用 f-string？不行。f-string 总是立即求值，

f"user {user.name} paid {amount}"

和

%

一样危险多模块共享 logger 时别用 getLogger(__name__) 就完事看似标准写法，但实际团队协作中容易导致日志归属混乱、配置失效或重复输出。 Python 3.14.3 微软官方的 Python 扩展，是 VS Code 安装量最高的扩展（209M+）。集成 IntelliSense（通过 Pylance）、调试（通过 Python Debugger）、代码检查、格式化、重构和单元测试等功能。支持 Jupyter Notebook、虚拟环境管理和多 Python 版本切换。下载每个模块用

getLogger(__name__)

没问题，但必须确保根 logger（

getLogger()

）已配置 handler，否则日志静默消失避免在模块里调

basicConfig()

—— 它只生效一次，后加载的模块会覆盖前者的配置推荐统一入口初始化：在

main.py

或

app/__init__.py

里调

logging.config.dictConfig(...)

，用 YAML/JSON 配置所有 handler、filter、formatter 如果要用 JSON 配置，注意

class

字段必须是完整路径，比如

"class": "logging.handlers.RotatingFileHandler"

，少个点就报

ValueError: Unable to configure handler 'file'

结构化日志字段不能靠手拼 JSON 想加

trace_id

、

user_id

这类字段？别在每条

logger.info()

里手动塞字典，一来易漏，二来破坏日志解析一致性。立即学习 “ Python免费学习笔记（深入） ”；用

LoggerAdapter

注入上下文：

adapter = LoggerAdapter(logger, {"trace_id": "abc123"})

，之后

adapter.info("order created")

自动带上字段若用

structlog

，务必禁用默认的

stdlib.BoundLogger

包装器，否则和原生

logging

配置冲突，出现双时间戳、双 level 字段字段名统一用小写+下划线（

request_id

而非

requestId

），避免不同服务解析规则打架敏感字段如

password

、

token

必须在 formatter 层过滤，不能依赖“大家自觉不打” 事情说清了就结束。真正难的不是写几行配置，是让所有人改掉

print()

习惯、接受日志要像接口一样约定字段含义、以及接受 ERROR 级别日志必须能直接触发告警而不是等人翻文件。

相关文章