TermControlAgent/docs/日志系统统一化报告.md

日志系统统一化报告

概述

本次检查发现项目中存在多种日志使用方式，为了统一管理和维护，将所有业务代码和核心代码统一为使用结构化日志系统。

检查结果

发现的问题

1. 多种日志导入方式并存：

   • 部分文件使用 from app.utils.log import get_enhanced_logger
   • 部分文件使用 from app.utils.structured_log import get_structured_logger
   • 测试文件中仍在使用旧的 get_logger() 方法

2. 依赖层级复杂：

   • log.py 作为包装层，增加了不必要的依赖
   • 不利于统一配置和管理

解决方案

统一所有代码使用 get_structured_logger() 方法，直接从 structured_log.py 导入。

修改详情

业务代码文件

文件路径	修改前	修改后
app/services/auto_discovery_adb_service.py	get_enhanced_logger	get_structured_logger
app/services/device_service.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/services/ssh_service.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/services/adb_service.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/services/at_service.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/services/atx_service.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/services/plnk_service.py	✅ 已使用 get_structured_logger	✅ 无需修改

核心代码文件

文件路径	修改前	修改后
app/core/websocket/adapter.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/core/websocket/client.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/core/websocket/channel.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/core/websocket/manager.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/core/device/manager.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/core/device/dispatcher.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/core/middleware/request.py	get_enhanced_logger	get_structured_logger
app/core/handlers/exception_handlers.py	get_enhanced_logger	get_structured_logger
app/core/config/cors.py	get_enhanced_logger	get_structured_logger
app/core/app/router.py	get_enhanced_logger	get_structured_logger
app/core/app/factory.py	get_enhanced_logger	get_structured_logger

API端点文件

文件路径	修改前	修改后
app/api/v1/endpoints/devices.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/api/v1/endpoints/websocket.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/api/v1/endpoints/ssh.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/api/v1/endpoints/at.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/api/v1/endpoints/plnk.py	✅ 已使用 get_structured_logger	✅ 无需修改

工具类文件

文件路径	修改前	修改后
app/utils/adb_utils.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/utils/serial_utils.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/utils/tcp_utils.py	✅ 已使用 get_structured_logger	✅ 无需修改
app/utils/api_decorators.py	✅ 已使用 get_structured_logger	✅ 无需修改

测试文件

文件路径	修改前	修改后
test_websocket_ssl_fix.py	get_logger	get_enhanced_logger
test_websocket_ssl.py	get_logger	get_enhanced_logger
test_websocket_connection.py	get_logger	get_enhanced_logger
test_websocket_api_logic.py	get_logger	get_enhanced_logger
test_websocket_api.py	get_logger	get_enhanced_logger
test_heartbeat_interval.py	get_logger	get_enhanced_logger
test_api_only.py	get_logger	get_enhanced_logger

统一后的日志使用方式

推荐方式（业务代码和核心代码）

from app.utils.structured_log import get_structured_logger, LogLevel

logger = get_structured_logger(__name__, LogLevel.INFO)

# 使用结构化日志
logger.info("操作成功", user_id="123", operation="login")
logger.error("操作失败", error=str(e), user_id="123")

测试代码方式

from app.utils.log import get_enhanced_logger, LogLevel

logger = get_enhanced_logger(__name__, LogLevel.DEBUG)

# 使用增强日志（内部仍使用结构化日志）
logger.info("测试信息")
logger.debug("调试信息")

向后兼容方式

from app.utils.log import get_logger

logger = get_logger("module_name")

# 使用传统日志格式
logger.info("传统日志信息")

优化效果

✅ 统一性

• 所有业务代码和核心代码使用统一的日志方式
• 便于统一配置和管理
• 减少代码维护成本

✅ 性能优化

• 减少依赖层级
• 直接使用结构化日志，避免包装层开销

✅ 功能增强

• 结构化日志提供更好的上下文信息
• 支持请求追踪和用户会话管理
• JSON格式便于日志分析和处理

✅ 向后兼容

• 保留 get_logger() 方法用于旧代码
• 测试代码可以使用 get_enhanced_logger() 作为过渡

验证结果

导入测试

# 结构化日志测试
python -c "from app.utils.structured_log import get_structured_logger, LogLevel; logger = get_structured_logger('test', LogLevel.DEBUG); logger.info('测试'); print('✅ 成功')"

# 业务代码测试
python -c "from app.services.device_service import DeviceService; service = DeviceService(); print('✅ 成功')"

# 核心代码测试
python -c "from app.core.websocket.adapter import WebSocketAdapter; print('✅ 成功')"

日志输出示例

{
  "timestamp": "2025-08-12T09:44:59.206670",
  "level": "INFO",
  "message": "测试结构化日志",
  "logger_name": "test",
  "context": {
    "request_id": null,
    "user_id": null,
    "session_id": null,
    "module": "structured_log",
    "function": "_log",
    "line_number": 157,
    "timestamp": "2025-08-12T09:44:59.206670",
    "duration_ms": null,
    "extra": {}
  },
  "exception": null,
  "stack_trace": null
}

总结

通过本次统一化工作：

1. 统一了日志使用方式：所有业务代码和核心代码都使用 get_structured_logger()
2. 提高了代码质量：减少了依赖层级，提高了性能
3. 增强了功能：结构化日志提供更好的上下文信息和追踪能力
4. 保持了兼容性：旧代码仍可使用传统日志方式

项目现在具有统一的日志管理方式，便于维护和扩展。