3.6 KiB

Raw Blame History

日志系统迁移 RFC 创建

日期: 2026-01-29
类型: RFC 文档
影响范围: 全项目日志系统

概述

创建了 RFC 201，规划从 loguru 迁移到 Python 标准库 logging 的完整方案。

背景

在修复 payment-service.md 文档的技术栈合规性时，发现项目中大量使用了 loguru，而技术栈规范要求使用标准库 logging。

RFC 内容

1. 影响范围分析

通过全局代码扫描，确认了 23 个文件使用 loguru：

服务层: 5 个文件
API 层: 2 个文件
仓储层: 2 个文件
任务层: 5 个文件
核心模块: 3 个文件（包括关键的 app/core/logging.py）
迁移脚本: 6 个文件
中间件: 1 个文件

2. 设计方案

2.1 新的日志配置模块

设计了完整的 app/core/logging.py 模块，提供：

✅ 彩色输出: 开发环境支持彩色日志
✅ 结构化日志: 生产环境支持结构化日志（request_id, user_id）
✅ 日志轮转: 自动按天轮转，保留 30 天应用日志，90 天错误日志
✅ 多级别输出: 控制台 + 应用日志 + 错误日志
✅ 第三方库控制: 合理设置第三方库日志级别

2.2 配置项

添加环境变量配置：

LOG_LEVEL: 日志级别（默认 INFO）
LOG_DIR: 日志目录（默认 logs）
ENVIRONMENT: 运行环境（development/production）

3. 迁移策略

分 6 个阶段执行

阶段 1: 核心模块（2 小时）- 最高优先级
阶段 2: 服务层（3 小时）- 高优先级
阶段 3: API 和仓储层（2 小时）- 中优先级
阶段 4: 任务层（2 小时）- 中优先级
阶段 5: 迁移脚本（1 小时）- 低优先级
阶段 6: 清理和验证（1 小时）- 最高优先级

总预计时间: 11 小时

代码替换模式

替换前:

from loguru import logger
logger.info(f"用户 {user_id} 创建订单 {order_no}")

替换后:

import logging
logger = logging.getLogger(__name__)
logger.info("用户 %s 创建订单 %s", user_id, order_no)

4. 风险管理

高风险

日志格式变化 → 保持相似格式
性能影响 → 使用异步处理器

中风险

遗漏文件 → 全局搜索验证
第三方库兼容性 → 集成测试

低风险

开发体验 → 提供迁移指南

5. 回滚计划

提供了完整的回滚脚本，可以快速恢复到迁移前状态。

成功标准

✅ 所有文件不再使用 loguru
✅ requirements.txt 中移除 loguru 依赖
✅ 所有测试通过
✅ 日志功能正常
✅ 应用性能无明显下降
✅ 文档已更新

附录内容

RFC 包含了详细的附录：

附录 A: 日志级别使用指南
附录 B: 常见日志模式示例
附录 C: 迁移检查清单

下一步

立即: 团队评审 RFC 201
批准后: 开始阶段 1（核心模块迁移）
持续: 按计划执行后续阶段

备注

此 RFC 是在修复 payment-service 文档时发现的全局性问题。虽然 payment-service 文档已修复完成，但实际代码实现时仍需遵循此 RFC 的日志规范。

建议优先执行日志系统迁移，然后再开始新服务的实现，以避免引入更多使用 loguru 的代码。

3.6 KiB Raw Blame History