增加接口日志输出

LOG_GUIDE.md

@@ -0,0 +1,268 @@
+# 日志系统使用指南
+
+## 概述
+
+本项目集成了完整的日志系统，支持多级别日志记录、文件轮转、彩色输出等功能。
+
+## 日志配置
+
+### 环境变量配置
+
+在 `.env` 文件中配置以下日志相关参数：
+
+```bash
+# 日志级别: DEBUG, INFO, WARNING, ERROR, CRITICAL
+LOG_LEVEL=INFO
+
+# 日志文件路径
+LOG_FILE=logs/app.log
+
+# 单个日志文件最大大小（字节）
+LOG_MAX_BYTES=10485760  # 10MB
+
+# 备份文件数量
+LOG_BACKUP_COUNT=5
+
+# 日志格式
+LOG_FORMAT=%(asctime)s - %(name)s - %(levelname)s - %(message)s
+
+# 时间格式
+LOG_DATE_FORMAT=%Y-%m-%d %H:%M:%S
+```
+
+### 日志级别说明
+
+- **DEBUG**: 详细的调试信息，通常只在开发时使用
+- **INFO**: 一般信息，记录应用正常运行状态
+- **WARNING**: 警告信息，表示可能出现问题
+- **ERROR**: 错误信息，表示发生了错误但不影响应用运行
+- **CRITICAL**: 严重错误，可能导致应用崩溃
+
+## 使用方法
+
+### 1. 获取日志器
+
+```python
+from app.logger import get_logger
+
+# 方式1: 指定名称
+logger = get_logger("my_module")
+
+# 方式2: 自动获取模块名
+logger = get_logger()  # 自动获取调用者的模块名
+```
+
+### 2. 记录日志
+
+```python
+logger.debug("这是调试信息")
+logger.info("这是一般信息")
+logger.warning("这是警告信息")
+logger.error("这是错误信息")
+logger.critical("这是严重错误信息")
+
+# 记录异常信息（包含堆栈跟踪）
+try:
+    # 可能出错的代码
+    result = 1 / 0
+except Exception as e:
+    logger.error(f"计算失败: {e}", exc_info=True)
+```
+
+### 3. 使用预定义日志器
+
+```python
+from app.logger import (
+    app_logger,      # 应用级日志
+    api_logger,      # API接口日志
+    db_logger,       # 数据库操作日志
+    redis_logger,    # Redis操作日志
+    external_api_logger  # 外部API调用日志
+)
+
+# 使用示例
+api_logger.info("API接口被访问")
+db_logger.info("数据库操作完成")
+```
+
+## 日志输出
+
+### 控制台输出
+
+控制台输出支持彩色显示，不同级别的日志使用不同颜色：
+
+- 🔵 DEBUG: 青色
+- 🟢 INFO: 绿色
+- 🟡 WARNING: 黄色
+- 🔴 ERROR: 红色
+- 🟣 CRITICAL: 紫色
+
+### 文件输出
+
+日志文件保存在配置的路径中，支持自动轮转：
+
+- 当文件大小超过 `LOG_MAX_BYTES` 时，会自动创建备份文件
+- 备份文件命名格式：`app.log.1`, `app.log.2`, ...
+- 最多保留 `LOG_BACKUP_COUNT` 个备份文件
+
+## 项目中的日志记录
+
+### 1. 应用启动/关闭日志
+
+```python
+# 应用启动
+logger.info("🚀 应用启动中...")
+logger.info("✅ 数据库连接成功")
+logger.info("🎉 应用启动完成!")
+
+# 应用关闭
+logger.info("🛑 应用关闭中...")
+logger.info("👋 应用已关闭")
+```
+
+### 2. API接口日志
+
+```python
+# 请求接收
+logger.info(f"🔥 收到AI Talk回调请求: siteId={siteId}, count={count}")
+
+# 业务逻辑
+logger.info(f"✅ count={count} >= {threshold}，直接返回")
+logger.info(f"📞 调用外部API，重试次数: {retry_count}")
+
+# 错误处理
+logger.error(f"❌ 服务器内部错误: {e}", exc_info=True)
+```
+
+### 3. 数据库操作日志
+
+```python
+# 数据库初始化
+logger.info("📊 初始化数据库表结构...")
+logger.info("✅ 数据库表结构初始化完成")
+
+# 数据记录
+logger.info(f"📝 记录回调请求: siteId={siteId}, count={count}")
+```
+
+### 4. Redis操作日志
+
+```python
+# 锁操作
+logger.debug(f"🔒 尝试获取Redis锁: {key}")
+logger.debug(f"✅ Redis锁获取成功: {key}")
+```
+
+### 5. 外部API调用日志
+
+```python
+# API调用
+logger.info(f"🌐 开始调用外部API: {url}")
+logger.debug(f"📤 第{attempt + 1}次尝试调用外部API")
+logger.info(f"✅ 外部API调用成功，状态码: {status}")
+logger.warning(f"⚠️ 外部API返回错误状态码: {status}")
+```
+
+## 日志查看和分析
+
+### 1. 实时查看日志
+
+```bash
+# 查看最新日志
+tail -f logs/app.log
+
+# 查看带颜色的日志（如果支持）
+tail -f logs/app.log | ccze  # 需要安装ccze
+```
+
+### 2. 搜索日志
+
+```bash
+# 搜索错误日志
+grep "ERROR" logs/app.log
+
+# 搜索特定接口的日志
+grep "siteId=123" logs/app.log
+
+# 搜索特定时间范围的日志
+grep "2024-12-02 10:" logs/app.log
+```
+
+### 3. 日志统计
+
+```bash
+# 统计不同级别的日志数量
+grep -c "INFO" logs/app.log
+grep -c "ERROR" logs/app.log
+grep -c "WARNING" logs/app.log
+
+# 查看最频繁的错误
+grep "ERROR" logs/app.log | sort | uniq -c | sort -nr
+```
+
+## 最佳实践
+
+### 1. 日志级别使用建议
+
+- **生产环境**: 使用 INFO 或 WARNING 级别
+- **开发环境**: 使用 DEBUG 级别查看详细信息
+- **测试环境**: 使用 INFO 级别
+
+### 2. 日志内容建议
+
+- 包含关键业务参数（如 siteId, count）
+- 使用表情符号增强可读性
+- 错误日志包含完整的异常信息
+- 重要操作记录开始和结束状态
+
+### 3. 性能考虑
+
+- 避免在高频循环中记录 DEBUG 日志
+- 使用日志级别控制避免不必要的字符串格式化
+- 合理设置日志轮转大小和数量
+
+### 4. 安全考虑
+
+- 避免在日志中记录敏感信息（密码、密钥等）
+- 生产环境注意日志文件的访问权限
+- 定期清理旧的日志文件
+
+## 故障排查
+
+### 1. 常见问题
+
+**问题**: 日志文件没有创建
+- 检查日志目录是否存在且有写权限
+- 检查 LOG_FILE 配置是否正确
+
+**问题**: 日志没有输出到控制台
+- 检查 LOG_LEVEL 配置是否过高
+- 检查是否有其他处理器冲突
+
+**问题**: 日志轮转不工作
+- 检查 LOG_MAX_BYTES 设置是否合理
+- 检查文件系统权限
+
+### 2. 调试日志系统
+
+```python
+# 检查日志器配置
+import logging
+logger = logging.getLogger()
+print(f"日志级别: {logger.level}")
+print(f"处理器数量: {len(logger.handlers)}")
+for handler in logger.handlers:
+    print(f"处理器: {handler.__class__.__name__}")
+```
+
+## 测试
+
+运行日志系统测试：
+
+```bash
+# 运行日志测试
+python -m pytest test_logger.py -v
+
+# 运行特定测试
+python -m pytest test_logger.py::TestLogger::test_logger_setup -v
+```