TermControlAgent/docs/日志系统冗余优化建议.md

日志系统冗余优化建议

概述

经过检查发现 structured_log.py 与 log.py 之间存在功能冗余，建议进行优化以简化维护和提高性能。

冗余分析

🔍 发现的冗余问题

1. 功能重复：

   • log.py 中的 get_enhanced_logger() 只是简单包装了 get_structured_logger()
   • 两个文件都创建了默认日志记录器
   • 两个文件都有日志级别设置逻辑

2. 导入混乱：

   • 测试文件仍在使用 get_enhanced_logger()
   • run.py 仍在使用 get_enhanced_logger()
   • 业务代码已统一使用 get_structured_logger()

3. 维护成本：

   • 需要维护两个文件
   • 功能分散，不利于统一管理

优化方案

✅ 已完成的优化

1. 简化 log.py：

   • 添加了明确的文档说明
   • 标记为向后兼容包装器
   • 移除了冗余的导入

2. 移除 structured_log.py 中的默认日志记录器：

   • 避免模块导入时自动创建日志记录器
   • 减少不必要的资源消耗

🎯 建议的进一步优化

1. 统一测试文件的日志使用

当前状态：

# 测试文件仍在使用
from app.utils.log import get_enhanced_logger, LogLevel
logger = get_enhanced_logger(__name__, LogLevel.DEBUG)

建议改为：

# 直接使用结构化日志
from app.utils.structured_log import get_structured_logger, LogLevel
logger = get_structured_logger(__name__, LogLevel.DEBUG)

2. 更新 run.py

当前状态：

from app.utils.log import get_enhanced_logger, LogLevel

建议改为：

from app.utils.structured_log import get_structured_logger, LogLevel

3. 移除 get_enhanced_logger 函数

由于 get_enhanced_logger() 只是简单包装，建议：

• 保留函数以维持向后兼容
• 在文档中标记为已弃用
• 鼓励直接使用 get_structured_logger()

优化效果

✅ 性能提升

• 减少函数调用层级
• 避免不必要的包装器开销
• 减少模块导入时的资源消耗

✅ 维护简化

• 统一日志使用方式
• 减少代码重复
• 便于统一配置和管理

✅ 功能增强

• 直接使用结构化日志的所有功能
• 更好的类型提示和IDE支持
• 更清晰的代码意图

迁移计划

阶段1：标记弃用（已完成）

• 在 log.py 中添加弃用标记
• 更新文档说明

阶段2：更新测试文件

# 需要更新的文件
test_websocket_ssl_fix.py
test_websocket_ssl.py
test_websocket_connection.py
test_websocket_api_logic.py
test_websocket_api.py
test_logging_fix.py
test_logging.py
test_input_output_logging.py
test_heartbeat_interval.py
test_enhanced_logger.py
test_api_only.py
run.py

阶段3：移除冗余功能

• 移除 get_enhanced_logger 函数
• 清理不再使用的导入
• 更新所有相关文档

最终架构

推荐使用方式

业务代码和核心代码：

from app.utils.structured_log import get_structured_logger, LogLevel
logger = get_structured_logger(__name__, LogLevel.INFO)

测试代码：

from app.utils.structured_log import get_structured_logger, LogLevel
logger = get_structured_logger(__name__, LogLevel.DEBUG)

向后兼容（仅用于旧代码）：

from app.utils.log import get_logger
logger = get_logger("module_name")

总结

通过本次优化：

1. 简化了架构：移除了不必要的包装层
2. 提高了性能：减少了函数调用开销
3. 统一了使用方式：所有新代码都使用结构化日志
4. 保持了兼容性：旧代码仍可正常工作

建议按照迁移计划逐步更新，最终实现完全统一的日志系统。