feat: 增强错误调试功能，完善traceback信息记录

- 完善异常处理器，添加详细的错误上下文和堆栈跟踪信息
- 新增调试助手工具，提供清晰的错误日志格式
- 增强日志上下文管理，支持请求级别的调试信息追踪
- 优化中间件异常处理，记录完整的请求生命周期
- 改进日志配置，新增关键错误日志文件
- 新增通用异常处理器，确保所有未捕获异常都被记录

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: JiayuXu

src/core/exceptions.py

@@ -1,9 +1,12 @@
+import json
+import traceback
 from fastapi import HTTPException, Request
 from fastapi.exceptions import RequestValidationError, ResponseValidationError
 from fastapi.responses import JSONResponse
 from starlette.responses import Response
 from tortoise.exceptions import DoesNotExist, IntegrityError
 
+from log import logger
 from settings.config import settings
 
 
@@ -12,6 +15,35 @@ class SettingNotFound(Exception):
 
 
 async def DoesNotExistHandle(req: Request, exc: DoesNotExist) -> JSONResponse:
+    # 记录详细的错误信息到日志
+    error_details = {
+        "method": req.method,
+        "url": str(req.url),
+        "path": req.url.path,
+        "query_params": dict(req.query_params),
+        "client_ip": req.client.host if req.client else None,
+        "user_agent": req.headers.get("user-agent"),
+        "exception_type": type(exc).__name__,
+        "exception_msg": str(exc),
+        "traceback": traceback.format_exc()
+    }
+    
+    # 构建详细的错误信息
+    error_message = f"DoesNotExist异常: {req.method} {req.url.path} - {exc}\n"
+    error_message += f"Exception Type: {type(exc).__name__}\n"
+    error_message += f"Exception Message: {str(exc)}\n"
+    error_message += f"\nStack Trace:\n{error_details.get('traceback', 'No traceback available')}\n"
+    error_message += f"\nRequest Context:\n"
+    for key, value in error_details.items():
+        if key != 'traceback':
+            if isinstance(value, dict):
+                error_message += f"  {key}: {json.dumps(value, indent=2, ensure_ascii=False)}\n"
+            else:
+                error_message += f"  {key}: {value}\n"
+    error_message += "=" * 80
+    
+    logger.error(error_message)
+    
     # 根据环境决定错误信息详细程度
     if settings.DEBUG:
         msg = f"Object not found: {exc}, query_params: {req.query_params}"
@@ -23,6 +55,30 @@ async def DoesNotExistHandle(req: Request, exc: DoesNotExist) -> JSONResponse:
 
 
 async def HttpExcHandle(request: Request, exc: HTTPException):
+    # 记录HTTP异常详情
+    error_details = {
+        "method": request.method,
+        "url": str(request.url),
+        "path": request.url.path,
+        "query_params": dict(request.query_params),
+        "client_ip": request.client.host if request.client else None,
+        "user_agent": request.headers.get("user-agent"),
+        "status_code": exc.status_code,
+        "exception_type": type(exc).__name__,
+        "exception_msg": str(exc.detail),
+        "traceback": traceback.format_exc()
+    }
+    
+    # 根据状态码决定日志级别
+    if exc.status_code >= 500:
+        logger.bind(**error_details).error(
+            f"HTTP {exc.status_code}异常: {request.method} {request.url.path} - {exc.detail}"
+        )
+    elif exc.status_code >= 400:
+        logger.bind(**error_details).warning(
+            f"HTTP {exc.status_code}异常: {request.method} {request.url.path} - {exc.detail}"
+        )
+    
     if exc.status_code == 401 and exc.headers and "WWW-Authenticate" in exc.headers:
         return Response(status_code=exc.status_code, headers=exc.headers)
     return JSONResponse(
@@ -32,6 +88,23 @@ async def HttpExcHandle(request: Request, exc: HTTPException):
 
 
 async def IntegrityHandle(request: Request, exc: IntegrityError):
+    # 记录数据完整性错误详情
+    error_details = {
+        "method": request.method,
+        "url": str(request.url),
+        "path": request.url.path,
+        "query_params": dict(request.query_params),
+        "client_ip": request.client.host if request.client else None,
+        "user_agent": request.headers.get("user-agent"),
+        "exception_type": type(exc).__name__,
+        "exception_msg": str(exc),
+        "traceback": traceback.format_exc()
+    }
+    
+    logger.bind(**error_details).error(
+        f"数据完整性错误: {request.method} {request.url.path} - {exc}"
+    )
+    
     # 根据环境决定错误信息详细程度
     if settings.DEBUG:
         msg = f"IntegrityError: {exc}"
@@ -43,11 +116,29 @@ async def IntegrityHandle(request: Request, exc: IntegrityError):
 
 
 async def RequestValidationHandle(
-    _: Request, exc: RequestValidationError
+    request: Request, exc: RequestValidationError
 ) -> JSONResponse:
+    # 记录请求验证错误详情
+    error_details = {
+        "method": request.method,
+        "url": str(request.url),
+        "path": request.url.path,
+        "query_params": dict(request.query_params),
+        "client_ip": request.client.host if request.client else None,
+        "user_agent": request.headers.get("user-agent"),
+        "exception_type": type(exc).__name__,
+        "exception_msg": str(exc),
+        "validation_errors": exc.errors(),
+        "traceback": traceback.format_exc()
+    }
+    
+    logger.bind(**error_details).warning(
+        f"请求参数验证失败: {request.method} {request.url.path} - {len(exc.errors())}个错误"
+    )
+    
     # 根据环境决定错误信息详细程度
     if settings.DEBUG:
-        msg = f"RequestValidationError: {exc}"
+        msg = f"RequestValidationError: {exc.errors()}"
     else:
         msg = "请求参数验证失败，请检查输入格式"
 
@@ -56,13 +147,68 @@ async def RequestValidationHandle(
 
 
 async def ResponseValidationHandle(
-    _: Request, exc: ResponseValidationError
+    request: Request, exc: ResponseValidationError
 ) -> JSONResponse:
+    # 记录响应验证错误详情
+    error_details = {
+        "method": request.method,
+        "url": str(request.url),
+        "path": request.url.path,
+        "query_params": dict(request.query_params),
+        "client_ip": request.client.host if request.client else None,
+        "user_agent": request.headers.get("user-agent"),
+        "exception_type": type(exc).__name__,
+        "exception_msg": str(exc),
+        "validation_errors": exc.errors(),
+        "traceback": traceback.format_exc()
+    }
+    
+    logger.bind(**error_details).error(
+        f"响应格式验证错误: {request.method} {request.url.path} - {len(exc.errors())}个错误"
+    )
+    
     # 根据环境决定错误信息详细程度
     if settings.DEBUG:
-        msg = f"ResponseValidationError: {exc}"
+        msg = f"ResponseValidationError: {exc.errors()}"
     else:
         msg = "服务器响应格式错误"
 
     content = dict(code=500, msg=msg)
     return JSONResponse(content=content, status_code=500)
+
+
+async def UnhandledExceptionHandle(request: Request, exc: Exception) -> JSONResponse:
+    """处理所有未捕获的异常"""
+    # 记录未处理异常的详细信息
+    error_details = {
+        "method": request.method,
+        "url": str(request.url),
+        "path": request.url.path,
+        "query_params": dict(request.query_params),
+        "client_ip": request.client.host if request.client else None,
+        "user_agent": request.headers.get("user-agent"),
+        "exception_type": type(exc).__name__,
+        "exception_msg": str(exc),
+        "exception_module": getattr(exc, "__module__", "unknown"),
+        "traceback": traceback.format_exc()
+    }
+    
+    # 尝试获取请求体信息（如果可能）
+    try:
+        if hasattr(request, "_body"):
+            error_details["request_body_size"] = len(request._body) if request._body else 0
+    except Exception:
+        pass
+    
+    logger.bind(**error_details).critical(
+        f"未处理的异常: {request.method} {request.url.path} - {type(exc).__name__}: {exc}"
+    )
+    
+    # 根据环境决定错误信息详细程度
+    if settings.DEBUG:
+        msg = f"Unhandled exception: {type(exc).__name__}: {exc}"
+    else:
+        msg = "服务器内部错误，请稍后重试"
+
+    content = dict(code=500, msg=msg)
+    return JSONResponse(content=content, status_code=500)

src/core/init_app.py

@@ -21,6 +21,7 @@
     RequestValidationHandle,
     ResponseValidationError,
     ResponseValidationHandle,
+    UnhandledExceptionHandle,
 )
 from core.middlewares import (
     BackGroundTaskMiddleware,
@@ -68,6 +69,8 @@ def register_exceptions(app: FastAPI):
     app.add_exception_handler(IntegrityError, IntegrityHandle)
     app.add_exception_handler(RequestValidationError, RequestValidationHandle)
     app.add_exception_handler(ResponseValidationError, ResponseValidationHandle)
+    # 注册通用异常处理器（必须放在最后，作为兜底）
+    app.add_exception_handler(Exception, UnhandledExceptionHandle)
     # 注册限流异常处理
     app.state.limiter = limiter
     app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)

src/core/middlewares.py

@@ -13,6 +13,7 @@
 
 from core.dependency import AuthControl
 from log import logger
+from log.context import LogContext
 from models.admin import AuditLog, User
 
 from .bgtask import BgTasks
@@ -261,35 +262,45 @@ async def dispatch(
     ) -> Response:
         """处理请求并记录日志"""
         start_time = datetime.now()
+        
+        # 设置请求级上下文信息
+        request_id = LogContext.set_request_id()
+        LogContext.update_context(
+            method=request.method,
+            path=request.url.path,
+            url=str(request.url),
+            query_params=dict(request.query_params),
+            client_ip=request.client.host if request.client else None,
+            user_agent=request.headers.get("user-agent"),
+            content_type=request.headers.get("content-type"),
+            content_length=request.headers.get("content-length"),
+            start_time=start_time.isoformat(),
+        )
+
+        # 获取带上下文的logger
+        context_logger = LogContext.get_logger()
 
         # 记录请求开始
-        logger.info(
-            f"请求开始: {request.method} {request.url.path}",
-            extra={
-                "method": request.method,
-                "path": request.url.path,
-                "query_params": dict(request.query_params),
-                "client_ip": request.client.host if request.client else None,
-                "user_agent": request.headers.get("user-agent"),
-            },
-        )
+        context_logger.info(f"请求开始: {request.method} {request.url.path}")
 
         try:
             response = await call_next(request)
 
             # 计算处理时间
             end_time = datetime.now()
             process_time = (end_time - start_time).total_seconds() * 1000
+            
+            # 更新上下文信息
+            LogContext.update_context(
+                status_code=response.status_code,
+                process_time_ms=process_time,
+                end_time=end_time.isoformat(),
+                response_headers=dict(response.headers),
+            )
 
             # 记录请求完成
-            logger.info(
-                f"请求完成: {request.method} {request.url.path} - {response.status_code} ({process_time:.2f}ms)",
-                extra={
-                    "method": request.method,
-                    "path": request.url.path,
-                    "status_code": response.status_code,
-                    "process_time_ms": process_time,
-                },
+            context_logger.info(
+                f"请求完成: {request.method} {request.url.path} - {response.status_code} ({process_time:.2f}ms)"
             )
 
             return response
@@ -298,16 +309,23 @@ async def dispatch(
             # 计算处理时间
             end_time = datetime.now()
             process_time = (end_time - start_time).total_seconds() * 1000
+            
+            # 更新上下文信息
+            LogContext.update_context(
+                exception_occurred=True,
+                exception_type=type(e).__name__,
+                exception_msg=str(e),
+                process_time_ms=process_time,
+                end_time=end_time.isoformat(),
+                traceback=traceback.format_exc()
+            )
 
-            # 记录请求异常
-            logger.error(
-                f"请求异常: {request.method} {request.url.path} - {str(e)} ({process_time:.2f}ms)",
-                extra={
-                    "method": request.method,
-                    "path": request.url.path,
-                    "error": str(e),
-                    "process_time_ms": process_time,
-                },
+            # 记录详细的请求异常信息
+            context_logger.error(
+                f"请求处理异常: {request.method} {request.url.path} - {type(e).__name__}: {str(e)} ({process_time:.2f}ms)"
             )
 
             raise
+        finally:
+            # 清理请求上下文
+            LogContext.clear()