6.4 KiB

Raw Blame History

日志系统迁移执行摘要

创建日期: 2026-01-29
状态: 待执行
优先级: 高

快速概览

项目	内容
问题	项目使用 `loguru`，不符合技术栈规范（要求使用标准库 `logging`）
影响范围	23 个文件
预计时间	11 小时
风险等级	中等
回滚难度	低（有完整备份和回滚脚本）

为什么要迁移？

✅ 技术栈统一: 符合 Jointo 技术栈规范
✅ 减少依赖: 移除不必要的第三方库
✅ 降低成本: 减少团队学习和维护成本
✅ 文档一致: 新文档已按标准库编写

迁移计划

阶段划分

阶段 1: 核心模块 (2h) ━━━━━━━━━━━━━━━━━━━━ 最高优先级
  └─ app/core/logging.py (关键)
  └─ app/core/database.py
  └─ app/core/cache.py
  └─ app/middleware/logging.py

阶段 2: 服务层 (3h) ━━━━━━━━━━━━━━━━━━━━━ 高优先级
  └─ 5 个服务文件

阶段 3: API + 仓储 (2h) ━━━━━━━━━━━━━━━━ 中优先级
  └─ 4 个文件

阶段 4: 任务层 (2h) ━━━━━━━━━━━━━━━━━━━ 中优先级
  └─ 5 个任务文件

阶段 5: 迁移脚本 (1h) ━━━━━━━━━━━━━━━━━ 低优先级
  └─ 6 个迁移脚本

阶段 6: 清理验证 (1h) ━━━━━━━━━━━━━━━━━ 最高优先级
  └─ 移除依赖、测试、文档

时间线

Day 1 (4h):  阶段 1 + 阶段 2 (部分)
Day 2 (4h):  阶段 2 (完成) + 阶段 3
Day 3 (3h):  阶段 4 + 阶段 5 + 阶段 6

技术方案

新的日志配置

# app/core/logging.py - 全新设计

✅ 彩色输出（开发环境）
✅ 结构化日志（生产环境）
✅ 自动日志轮转（按天）
✅ 多级别输出（控制台 + 文件）
✅ 第三方库日志控制

代码变更示例

Before:

from loguru import logger
logger.info(f"用户 {user_id} 登录")

After:

import logging
logger = logging.getLogger(__name__)
logger.info("用户 %s 登录", user_id)

执行步骤

1. 准备阶段

# 1. 创建分支
git checkout -b feature/logging-migration

# 2. 备份当前代码
./scripts/backup_before_migration.sh

2. 实施阶段

每个阶段执行：

# 1. 备份文件
cp <file>.py <file>.py.bak

# 2. 修改代码
# - 替换导入语句
# - 修改日志调用

# 3. 测试验证
docker exec jointo-server-app pytest tests/unit/<test>.py -v

# 4. 提交变更
git add <file>.py
git commit -m "refactor: migrate <file> from loguru to logging"

3. 验证阶段

# 1. 全局搜索残留
grep -r "from loguru import" server/app/
grep -r "import loguru" server/app/

# 2. 运行完整测试
docker exec jointo-server-app pytest tests/ -v

# 3. 检查日志输出
docker exec jointo-server-app tail -f logs/app.log

# 4. 性能测试
docker exec jointo-server-app pytest tests/performance/ -v

4. 清理阶段

# 1. 移除 loguru 依赖
# 编辑 server/requirements.txt
# 删除: loguru==0.7.2

# 2. 重新构建容器
docker-compose -f server/docker-compose.yml build app
docker-compose -f server/docker-compose.yml up -d

# 3. 删除备份文件
find server/app -name "*.py.bak" -delete

风险控制

高风险项

风险	缓解措施	回滚方案
日志格式变化	保持相似格式	恢复备份文件
性能下降	使用异步处理器	回滚到 loguru

回滚脚本

#!/bin/bash
# scripts/rollback_logging_migration.sh

# 1. 恢复备份文件
for file in $(find server/app -name "*.py.bak"); do
    mv "$file" "${file%.bak}"
done

# 2. 恢复 requirements.txt
git checkout server/requirements.txt

# 3. 重新构建容器
docker-compose -f server/docker-compose.yml build app
docker-compose -f server/docker-compose.yml up -d

echo "✅ 回滚完成"

成功标准

所有 23 个文件已迁移
requirements.txt 中移除 loguru
全局搜索无 loguru 残留
所有测试通过（单元测试 + 集成测试）
日志功能正常（控制台 + 文件 + 轮转）
彩色输出正常工作
性能无明显下降（< 5%）
文档已更新

快速开始

立即执行阶段 1

# 1. 创建分支
git checkout -b feature/logging-migration

# 2. 备份核心模块
cp server/app/core/logging.py server/app/core/logging.py.bak
cp server/app/core/database.py server/app/core/database.py.bak
cp server/app/core/cache.py server/app/core/cache.py.bak
cp server/app/middleware/logging.py server/app/middleware/logging.py.bak

# 3. 开始迁移
# 参考 RFC 201 中的代码示例

团队协作

分工建议

开发者 A: 阶段 1 + 阶段 2
开发者 B: 阶段 3 + 阶段 4
开发者 C: 阶段 5 + 阶段 6（验证）

沟通渠道

📢 进度更新: 每完成一个阶段在团队频道通知
🐛 问题反馈: 遇到问题立即在技术频道讨论
✅ 代码审查: 每个阶段完成后进行 Code Review

常见问题

Q1: 为什么不能继续使用 loguru？

A: 技术栈规范要求使用标准库，减少外部依赖，降低维护成本。

Q2: 迁移会影响现有功能吗？

A: 不会。日志是横切关注点，只要保持相同的日志级别和格式，不影响业务逻辑。

Q3: 如果迁移出问题怎么办？

A: 有完整的备份和回滚脚本，可以在 5 分钟内回滚到迁移前状态。

Q4: 新的日志系统有什么优势？

✅ 无外部依赖
✅ 更好的性能
✅ 更灵活的配置
✅ 更好的生态支持

Q5: 需要学习新的 API 吗？

A: 标准库 logging 是 Python 内置模块，大多数开发者已经熟悉。RFC 中提供了完整的使用指南。

联系方式

RFC 作者: System
技术负责人: [待指定]
项目经理: [待指定]

最后更新: 2026-01-29
文档版本: v1.0

6.4 KiB Raw Blame History