infomankit 0.3.23__py3-none-any.whl

infoman/service/exception/handler.py

@@ -0,0 +1,238 @@
+from fastapi import HTTPException, Request, Response
+from fastapi.responses import JSONResponse
+from fastapi.exceptions import RequestValidationError
+from pydantic import ValidationError
+from tortoise.exceptions import (
+    OperationalError,
+    DoesNotExist,
+    IntegrityError,
+    ValidationError as MysqlValidationError,
+)
+from typing import List, Dict, Any, Type
+import traceback
+
+from infoman.service.exception.error import DatabaseError, RequestError, AppSystemError
+from infoman.service.exception.exception import AppException
+from infoman.logger import logger
+
+
+def format_error_response(
+    code: int, message: str, data: Any = None, details: Any = None
+) -> Dict[str, Any]:
+    response = {"code": code, "message": message, "data": data or {}}
+    if details:
+        response["details"] = details
+    return response
+
+
+def format_validation_errors(errors: List[Dict]) -> List[Dict[str, str]]:
+    formatted_errors = []
+    for error in errors:
+        loc_path = " -> ".join([str(loc) for loc in error.get("loc", [])])
+        formatted_errors.append(
+            {
+                "field": loc_path,
+                "message": error.get("msg", "Unknown error"),
+                "type": error.get("type", "unknown"),
+                "input": str(error.get("input", "")) if "input" in error else None,
+            }
+        )
+    return formatted_errors
+
+
+async def http_exception_handler(request: Request, exc: HTTPException) -> Response:
+    """处理 HTTP 异常"""
+    logger.warning(
+        f"HTTP Exception: status={exc.status_code}, "
+        f"detail={exc.detail}, path={request.url.path}"
+    )
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=format_error_response(code=exc.status_code, message=exc.detail),
+        headers=exc.headers,
+    )
+
+
+async def handle_app_exception(_: Request, exc: AppException) -> Response:
+    """处理应用自定义异常"""
+    logger.error(f"App Exception: code={exc.error_code}, message={exc.message}")
+    return JSONResponse(
+        format_error_response(code=exc.error_code, message=exc.message), status_code=200
+    )
+
+
+async def mysql_validation_error_handler(
+    request: Request, exc: MysqlValidationError
+) -> Response:
+    """处理 MySQL 验证错误"""
+    logger.error(
+        f"MySQL Validation Error at {request.url.path}\n"
+        f"Error: {exc}\n"
+        f"Traceback: {traceback.format_exc()}"
+    )
+    err = DatabaseError.VALIDATION_ERROR
+    return JSONResponse(
+        format_error_response(code=err.code, message=err.message, details=str(exc)),
+        status_code=200,
+    )
+
+
+async def mysql_integrity_error_handler(
+    request: Request, exc: IntegrityError
+) -> Response:
+    """处理 MySQL 完整性约束错误"""
+    error_msg = str(exc)
+    logger.error(
+        f"MySQL Integrity Error at {request.url.path}\n"
+        f"Error: {error_msg}\n"
+        f"Traceback: {traceback.format_exc()}"
+    )
+
+    # 提取更友好的错误信息
+    friendly_message = DatabaseError.INTEGRITY_ERROR.message
+    if "Duplicate entry" in error_msg:
+        friendly_message = "数据已存在，请勿重复添加"
+    elif "foreign key constraint" in error_msg.lower():
+        friendly_message = "关联数据不存在或已被引用"
+
+    err = DatabaseError.INTEGRITY_ERROR
+    return JSONResponse(
+        format_error_response(
+            code=err.code, message=friendly_message, details=error_msg
+        ),
+        status_code=200,
+    )
+
+
+async def mysql_does_not_exist_handler(request: Request, exc: DoesNotExist) -> Response:
+    """处理 MySQL 记录不存在错误"""
+    logger.warning(f"MySQL Record Not Found at {request.url.path}: {exc}")
+    err = DatabaseError.RECORD_NOT_FOUND
+    return JSONResponse(
+        format_error_response(code=err.code, message=err.message, details=str(exc)),
+        status_code=200,
+    )
+
+
+async def mysql_operational_error_handler(
+    request: Request, exc: OperationalError
+) -> Response:
+    """处理 MySQL 操作错误"""
+    error_msg = str(exc)
+    logger.error(
+        f"MySQL Operational Error at {request.url.path}\n"
+        f"Error: {error_msg}\n"
+        f"Traceback: {traceback.format_exc()}"
+    )
+
+    # 提取更友好的错误信息
+    friendly_message = DatabaseError.OPERATIONAL_ERROR.message
+    if "Lost connection" in error_msg:
+        friendly_message = "数据库连接已断开"
+    elif "Deadlock" in error_msg:
+        friendly_message = "数据库死锁，请稍后重试"
+
+    err = DatabaseError.OPERATIONAL_ERROR
+    return JSONResponse(
+        format_error_response(
+            code=err.code, message=friendly_message, details=error_msg
+        ),
+        status_code=200,
+    )
+
+
+async def validation_exception_handler(
+    request: Request, exc: RequestValidationError
+) -> Response:
+    """处理请求验证错误"""
+    error_details = format_validation_errors(exc.errors())
+
+    logger.warning(
+        f"Request Validation Error at {request.url.path}\n"
+        f"Method: {request.method}\n"
+        f"Errors: {error_details}"
+    )
+
+    err = RequestError.VALIDATION_ERROR
+    if len(error_details) == 1:
+        main_message = f"{error_details[0]['field']}: {error_details[0]['message']}"
+    else:
+        main_message = f"发现 {len(error_details)} 个验证错误"
+
+    return JSONResponse(
+        format_error_response(
+            code=err.code, message=main_message, details=error_details
+        ),
+        status_code=200,
+    )
+
+
+async def pydantic_validation_handler(
+    request: Request, exc: ValidationError
+) -> Response:
+    """处理 Pydantic 验证错误"""
+    error_details = format_validation_errors(exc.errors())
+
+    logger.warning(
+        f"Pydantic Validation Error at {request.url.path}\n"
+        f"Method: {request.method}\n"
+        f"Errors: {error_details}"
+    )
+
+    err = RequestError.VALIDATION_ERROR
+    # 生成更友好的错误消息
+    if len(error_details) == 1:
+        main_message = f"{error_details[0]['field']}: {error_details[0]['message']}"
+    else:
+        main_message = f"数据验证失败，发现 {len(error_details)} 个错误"
+
+    return JSONResponse(
+        format_error_response(
+            code=err.code, message=main_message, details=error_details
+        ),
+        status_code=200,
+    )
+
+
+async def unhandled_exception_handler(request: Request, exc: Exception) -> Response:
+    """处理未捕获的异常"""
+    logger.error(
+        f"Unhandled Exception at {request.url.path}\n"
+        f"Method: {request.method}\n"
+        f"Exception Type: {type(exc).__name__}\n"
+        f"Error: {str(exc)}\n"
+        f"Traceback: {traceback.format_exc()}"
+    )
+    err = AppSystemError.UNKNOWN_ERROR
+    return JSONResponse(
+        format_error_response(
+            code=err.code,
+            message="服务器内部错误，请稍后重试",
+            details=str(exc) if logger.level == "DEBUG" else None,
+        ),
+        status_code=500,
+    )
+
+
+EXCEPTION_HANDLERS: Dict[Type[Exception], Any] = {
+    # 应用异常
+    AppException: handle_app_exception,
+    # HTTP 异常
+    HTTPException: http_exception_handler,
+    # 请求验证异常
+    RequestValidationError: validation_exception_handler,
+    ValidationError: pydantic_validation_handler,
+    # MySQL 异常
+    DoesNotExist: mysql_does_not_exist_handler,
+    IntegrityError: mysql_integrity_error_handler,
+    MysqlValidationError: mysql_validation_error_handler,
+    OperationalError: mysql_operational_error_handler,
+    # 兜底异常
+    Exception: unhandled_exception_handler,
+}
+
+
+def register_exception_handlers(app) -> None:
+    for exception_class, handler_func in EXCEPTION_HANDLERS.items():
+        app.add_exception_handler(exception_class, handler_func)
+        # logger.info(f"Registered handler for {exception_class.__name__}")

infoman/service/infrastructure/__init__.py

@@ -0,0 +1,8 @@
+# !/usr/bin/env python
+# -*-coding:utf-8 -*-
+
+"""
+# Time       ：2025/12/22 22:38
+# Author     ：Maxwell
+# Description：
+"""

infoman/service/infrastructure/base.py

@@ -0,0 +1,212 @@
+# !/usr/bin/env python
+# -*-coding:utf-8 -*-
+
+"""
+# Time       ：2025/12/22 22:38
+# Author     ：Maxwell
+# Description：基础设施组件抽象基类
+统一管理：
+- 数据库（MySQL, PostgreSQL）
+- 缓存（Redis, DragonflyDB）
+- 消息队列（RabbitMQ, Kafka）
+- 搜索引擎（Elasticsearch）
+- 对象存储（MinIO, S3）
+- 等等...
+
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional, Dict, Any, Literal
+from enum import Enum
+from loguru import logger
+
+
+class ComponentType(str, Enum):
+    """组件类型枚举"""
+    DATABASE = "database"  # 数据库
+    CACHE = "cache"  # 缓存
+    MESSAGE_QUEUE = "message_queue"  # 消息队列
+    SEARCH = "search"  # 搜索引擎
+    STORAGE = "storage"  # 对象存储
+    MONITORING = "monitoring"  # 监控
+    TRACING = "tracing"  # 链路追踪
+    LOGGING = "logging"  # 日志
+    OTHER = "other"  # 其他
+
+
+class ComponentStatus(str, Enum):
+    """组件状态枚举"""
+    NOT_CONFIGURED = "not_configured"  # 未配置
+    INITIALIZING = "initializing"  # 初始化中
+    HEALTHY = "healthy"  # 健康
+    UNHEALTHY = "unhealthy"  # 不健康
+    DEGRADED = "degraded"  # 降级
+    STOPPED = "stopped"  # 已停止
+
+
+class BaseInfrastructureComponent(ABC):
+    """
+    基础设施组件抽象基类
+
+    所有基础设施组件（数据库、缓存、MQ 等）都应该继承此类。
+
+    生命周期：
+        1. __init__() - 创建实例
+        2. startup() - 启动组件
+        3. health_check() - 健康检查
+        4. shutdown() - 关闭组件
+    """
+
+    def __init__(
+            self,
+            component_type: ComponentType,
+            name: str,
+            enabled: bool = True,
+    ):
+        """
+        初始化组件
+
+        Args:
+            component_type: 组件类型
+            name: 组件名称（如 "mysql", "redis"）
+            enabled: 是否启用
+        """
+        self.component_type = component_type
+        self.name = name
+        self.enabled = enabled
+        self._status = ComponentStatus.NOT_CONFIGURED
+        self._client: Optional[Any] = None
+        self._metadata: Dict[str, Any] = {}
+
+    @property
+    def status(self) -> ComponentStatus:
+        """获取组件状态"""
+        return self._status
+
+    @property
+    def client(self) -> Optional[Any]:
+        """获取客户端实例"""
+        return self._client
+
+    @property
+    def is_available(self) -> bool:
+        """组件是否可用"""
+        return (
+                self.enabled and
+                self._status in [ComponentStatus.HEALTHY, ComponentStatus.DEGRADED]
+        )
+
+    @abstractmethod
+    async def startup(self) -> bool:
+        """
+        启动组件
+
+        职责：
+        1. 检查配置
+        2. 创建连接/客户端
+        3. 测试连接
+        4. 初始化资源
+
+        Returns:
+            True: 启动成功
+            False: 启动失败
+        """
+        pass
+
+    @abstractmethod
+    async def shutdown(self):
+        """
+        关闭组件
+
+        职责：
+        1. 关闭连接
+        2. 释放资源
+        3. 清理状态
+        """
+        pass
+
+    @abstractmethod
+    async def health_check(self) -> Dict[str, Any]:
+        """
+        健康检查
+
+        Returns:
+            健康状态字典：
+            {
+                "status": "healthy" | "unhealthy" | "not_configured",
+                "component_type": "database",
+                "name": "mysql",
+                "details": {...}
+            }
+        """
+        pass
+
+    async def get_info(self) -> Dict[str, Any]:
+        """
+        获取组件信息
+
+        Returns:
+            组件信息字典
+        """
+        return {
+            "component_type": self.component_type.value,
+            "name": self.name,
+            "enabled": self.enabled,
+            "status": self._status.value,
+            "available": self.is_available,
+            "metadata": self._metadata,
+        }
+
+    async def get_stats(self) -> Dict[str, Any]:
+        """
+        获取统计信息（可选实现）
+
+        Returns:
+            统计信息字典
+        """
+        return {}
+
+    def _set_status(self, status: ComponentStatus):
+        """设置组件状态"""
+        old_status = self._status
+        self._status = status
+
+        if old_status != status:
+            logger.debug(
+                f"[{self.name}] 状态变更: {old_status.value} -> {status.value}"
+            )
+
+    def _log_startup(self, success: bool, message: str = ""):
+        """记录启动日志"""
+        if success:
+            logger.success(
+                f"✅ [{self.component_type.value}] {self.name} 启动成功"
+                + (f": {message}" if message else "")
+            )
+        else:
+            logger.error(
+                f"❌ [{self.component_type.value}] {self.name} 启动失败"
+                + (f": {message}" if message else "")
+            )
+
+    def _log_shutdown(self, success: bool, message: str = ""):
+        """记录关闭日志"""
+        if success:
+            logger.info(
+                f"✅ [{self.component_type.value}] {self.name} 已关闭"
+                + (f": {message}" if message else "")
+            )
+        else:
+            logger.error(
+                f"❌ [{self.component_type.value}] {self.name} 关闭失败"
+                + (f": {message}" if message else "")
+            )
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"type={self.component_type.value}, "
+            f"name={self.name}, "
+            f"status={self._status.value}"
+            f")"
+        )

infoman/service/infrastructure/db_cache/__init__.py

@@ -0,0 +1,8 @@
+# !/usr/bin/env python
+# -*-coding:utf-8 -*-
+
+"""
+# Time       ：2025/12/22 21:39
+# Author     ：Maxwell
+# Description：
+"""

infoman/service/infrastructure/db_cache/manager.py

@@ -0,0 +1,194 @@
+# !/usr/bin/env python
+# -*-coding:utf-8 -*-
+
+"""
+Redis 缓存管理器（支持延迟导入）
+"""
+from typing import Optional, Dict, Any, TYPE_CHECKING
+from fastapi import FastAPI
+from loguru import logger
+from infoman.config import settings
+
+if TYPE_CHECKING:
+    import redis.asyncio as redis
+
+
+class RedisManager:
+    """Redis 管理器"""
+
+    def __init__(self):
+        self.client: Optional[Any] = None
+        self.initialized = False
+
+    @property
+    def is_available(self) -> bool:
+        """是否可用"""
+        return self.client is not None and self.initialized
+
+    async def startup(self, app: Optional[FastAPI] = None) -> bool:
+        """
+        启动 Redis 连接
+
+        Args:
+            app: FastAPI 应用实例（可选）
+
+        Returns:
+            是否成功启动
+        """
+        if self.initialized:
+            logger.warning("⚠️ RedisManager 已初始化，跳过重复初始化")
+            return True
+
+        if not settings.redis_configured:
+            logger.info("⏭️ Redis 未配置，跳过初始化")
+            return False
+
+        # 延迟导入（只在真正需要时导入）
+        try:
+            import redis.asyncio as redis
+            from fastapi_cache import FastAPICache
+            from fastapi_cache.backends.redis import RedisBackend
+        except ImportError as e:
+            logger.error(f"❌ Redis 依赖未安装: {e}")
+            logger.error("请运行: pip install infomankit[cache]")
+            return False
+
+        logger.info("🚀 初始化 Redis...")
+
+        try:
+            # 创建连接池
+            pool = redis.ConnectionPool(
+                host=settings.REDIS_HOST,
+                port=settings.REDIS_PORT,
+                db=settings.REDIS_DB,
+                password=settings.REDIS_PASSWORD,
+                encoding="utf-8",
+                decode_responses=False,
+                max_connections=settings.REDIS_MAX_CONNECTIONS,
+                socket_timeout=settings.REDIS_SOCKET_TIMEOUT,
+                socket_connect_timeout=settings.REDIS_SOCKET_CONNECT_TIMEOUT,
+                health_check_interval=settings.REDIS_HEALTH_CHECK_INTERVAL,
+            )
+
+            # 创建客户端
+            self.client = redis.Redis(connection_pool=pool)
+
+            # 测试连接
+            await self.client.ping()
+
+            # 挂载到 app.state（如果提供了 app）
+            if app:
+                app.state.redis_client = self.client
+                logger.debug("✅ Redis 客户端已挂载到 app.state")
+
+            # 初始化缓存
+            FastAPICache.init(
+                RedisBackend(self.client),
+                prefix=f"{settings.REDIS_CACHE_PREFIX}:v{settings.APP_VERSION}:",
+            )
+
+            self.initialized = True
+            logger.success(f"✅ Redis 连接成功: {settings.REDIS_HOST}:{settings.REDIS_PORT}")
+            return True
+
+        except Exception as e:
+            logger.error(f"❌ Redis 连接失败: {e}")
+            self.client = None
+            return False
+
+    async def shutdown(self):
+        """关闭 Redis 连接"""
+        if not self.initialized:
+            return
+
+        logger.info("⏹️ 关闭 Redis 连接...")
+
+        try:
+            if self.client:
+                await self.client.close()
+                await self.client.connection_pool.disconnect()
+                logger.success("✅ Redis 连接已关闭")
+        except Exception as e:
+            logger.error(f"❌ Redis 关闭失败: {e}")
+        finally:
+            self.initialized = False
+
+    async def health_check(self) -> Dict[str, Any]:
+        """
+        健康检查
+
+        Returns:
+            {
+                "status": "healthy" | "unhealthy" | "not_configured",
+                "name": "redis",
+                "details": {...}
+            }
+        """
+        if not settings.redis_configured:
+            return {
+                "status": "not_configured",
+                "name": "redis",
+                "details": {"enabled": False}
+            }
+
+        if not self.initialized or not self.client:
+            return {
+                "status": "unhealthy",
+                "name": "redis",
+                "details": {"error": "未初始化"}
+            }
+
+        try:
+            await self.client.ping()
+
+            # 获取 Redis 信息
+            info = await self.client.info()
+
+            return {
+                "status": "healthy",
+                "name": "redis",
+                "details": {
+                    "host": settings.REDIS_HOST,
+                    "port": settings.REDIS_PORT,
+                    "db": settings.REDIS_DB,
+                    "connected_clients": info.get("connected_clients", 0),
+                    "used_memory_human": info.get("used_memory_human", "N/A"),
+                }
+            }
+        except Exception as e:
+            return {
+                "status": "unhealthy",
+                "name": "redis",
+                "details": {"error": str(e)}
+            }
+
+    async def get_stats(self) -> Dict[str, Any]:
+        """
+        获取统计信息
+
+        Returns:
+            {
+                "host": str,
+                "port": int,
+                "db": int,
+                "info": {...}
+            }
+        """
+        if not self.is_available:
+            return {}
+
+        try:
+            info = await self.client.info()
+
+            return {
+                "host": settings.REDIS_HOST,
+                "port": settings.REDIS_PORT,
+                "db": settings.REDIS_DB,
+                "connected_clients": info.get("connected_clients", 0),
+                "used_memory": info.get("used_memory_human", "N/A"),
+                "uptime_in_seconds": info.get("uptime_in_seconds", 0),
+                "total_commands_processed": info.get("total_commands_processed", 0),
+            }
+        except Exception as e:
+            logger.error(f"获取 Redis 统计信息失败: {e}")
+            return {}

infoman/service/infrastructure/db_relation/__init__.py

@@ -0,0 +1,41 @@
+"""
+数据库关系层 - 统一导出
+
+Version: 0.3.0
+
+向前兼容说明：
+- 默认导出保持不变（使用原有的 Tortoise 单一后端管理器）
+- 新的混合管理器通过 hybrid_db_manager 导出
+"""
+
+# ==================== 向前兼容（默认使用 Tortoise）====================
+
+from infoman.service.infrastructure.db_relation.manager import (
+    DatabaseManager,
+    db_manager,
+    register_databases as register_databases_tortoise,
+    check_databases_health as check_databases_health_tortoise,
+    close_databases as close_databases_tortoise,
+    get_connection_names as get_connection_names_tortoise,
+)
+
+
+# ==================== 默认导出（向前兼容）====================
+
+# 为了100%向前兼容，默认导出仍然是 Tortoise 单一后端
+__all__ = [
+    # Tortoise 管理器（默认，向前兼容）
+    "DatabaseManager",
+    "db_manager",
+    "register_databases",
+    "check_databases_health",
+    "close_databases",
+    "get_connection_names",
+
+]
+
+# 默认导出指向 Tortoise 版本（向前兼容）
+register_databases = register_databases_tortoise
+check_databases_health = check_databases_health_tortoise
+close_databases = close_databases_tortoise
+get_connection_names = get_connection_names_tortoise