aury-boot 0.0.2__py3-none-any.whl → 0.0.3__py3-none-any.whl

aury/boot/infrastructure/database/manager.py

@@ -0,0 +1,317 @@
+"""数据库管理器 - 命名多实例实现。
+
+提供统一的数据库连接管理、会话创建和健康检查功能。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+from sqlalchemy import text
+from sqlalchemy.exc import DisconnectionError, OperationalError
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
+
+from aury.boot.common.logging import logger
+from aury.boot.infrastructure.database.config import DatabaseConfig
+
+
+class DatabaseManager:
+    """数据库管理器（命名多实例）。
+    
+    职责：
+    1. 管理数据库引擎和连接池
+    2. 提供会话工厂
+    3. 健康检查和重连机制
+    4. 生命周期管理
+    5. 支持多个命名实例，如主库/从库、不同业务数据库等
+    
+    使用示例:
+        # 默认实例
+        db_manager = DatabaseManager.get_instance()
+        await db_manager.initialize()
+        
+        # 命名实例
+        primary = DatabaseManager.get_instance("primary")
+        replica = DatabaseManager.get_instance("replica")
+        
+        # 获取会话
+        async with db_manager.session() as session:
+            # 使用 session 进行数据库操作
+            pass
+        
+        # 清理
+        await db_manager.cleanup()
+    """
+    
+    _instances: dict[str, DatabaseManager] = {}
+    
+    def __init__(self, name: str = "default") -> None:
+        """初始化数据库管理器。
+        
+        Args:
+            name: 实例名称
+        """
+        self.name = name
+        self._initialized: bool = False
+        self._config: DatabaseConfig | None = None
+        self._engine: AsyncEngine | None = None
+        self._session_factory: async_sessionmaker | None = None
+        self._max_retries: int = 3
+        self._retry_delay: float = 1.0
+    
+    @classmethod
+    def get_instance(cls, name: str = "default") -> DatabaseManager:
+        """获取指定名称的实例。
+        
+        Args:
+            name: 实例名称，默认为 "default"
+            
+        Returns:
+            DatabaseManager: 数据库管理器实例
+        """
+        if name not in cls._instances:
+            cls._instances[name] = cls(name)
+        return cls._instances[name]
+    
+    @classmethod
+    def reset_instance(cls, name: str | None = None) -> None:
+        """重置实例（仅用于测试）。
+        
+        Args:
+            name: 要重置的实例名称。如果为 None，则重置所有实例。
+            
+        注意：调用此方法前应先调用 cleanup() 释放资源。
+        """
+        if name is None:
+            cls._instances.clear()
+        elif name in cls._instances:
+            del cls._instances[name]
+    
+    def configure(self, config: DatabaseConfig) -> None:
+        """配置数据库管理器。
+        
+        Args:
+            config: 数据库配置
+        """
+        self._config = config
+    
+    @property
+    def engine(self) -> AsyncEngine:
+        """获取数据库引擎。"""
+        if self._engine is None:
+            raise RuntimeError("数据库管理器未初始化，请先调用 initialize()")
+        return self._engine
+    
+    @property
+    def session_factory(self) -> async_sessionmaker:
+        """获取会话工厂。"""
+        if self._session_factory is None:
+            raise RuntimeError("数据库管理器未初始化，请先调用 initialize()")
+        return self._session_factory
+    
+    @property
+    def is_initialized(self) -> bool:
+        """检查是否已初始化。"""
+        return self._initialized
+    
+    async def initialize(
+        self,
+        url: str | None = None,
+        *,
+        echo: bool | None = None,
+        pool_size: int | None = None,
+        max_overflow: int | None = None,
+        pool_timeout: int | None = None,
+        pool_recycle: int | None = None,
+        isolation_level: str | None = None,
+    ) -> None:
+        """初始化数据库连接。
+        
+        Args:
+            url: 数据库连接字符串，默认从配置读取
+            echo: 是否打印SQL语句
+            pool_size: 连接池大小
+            max_overflow: 最大溢出连接数
+            pool_timeout: 连接超时时间（秒）
+            pool_recycle: 连接回收时间（秒）
+            isolation_level: 事务隔离级别
+        """
+        if self._initialized:
+            logger.warning("数据库管理器已初始化，跳过重复初始化")
+            return
+        
+        # 使用提供的参数或配置中的默认值
+        db_isolation_level: str | None = None
+        if self._config is not None:
+            database_url = url or self._config.url
+            db_echo = echo if echo is not None else self._config.echo
+            db_pool_size = pool_size or self._config.pool_size
+            db_max_overflow = max_overflow or self._config.max_overflow
+            db_pool_timeout = pool_timeout or self._config.pool_timeout
+            db_pool_recycle = pool_recycle or self._config.pool_recycle
+            db_isolation_level = isolation_level or self._config.isolation_level
+        else:
+            # 如果没有配置，使用环境变量
+            import os
+            database_url = url or os.getenv("DATABASE_URL")
+            if not database_url:
+                raise ValueError(
+                    "数据库 URL 未配置。请通过以下方式之一提供："
+                    "1. 使用 DatabaseManager.configure() 设置配置"
+                    "2. 通过 initialize(url=...) 参数传入"
+                    "3. 设置环境变量 DATABASE_URL"
+                )
+            db_echo = echo if echo is not None else os.getenv("DB_ECHO", "false").lower() == "true"
+            db_pool_size = pool_size or int(os.getenv("DB_POOL_SIZE", "5"))
+            db_max_overflow = max_overflow or int(os.getenv("DB_MAX_OVERFLOW", "10"))
+            db_pool_timeout = pool_timeout or int(os.getenv("DB_POOL_TIMEOUT", "30"))
+            db_pool_recycle = pool_recycle or int(os.getenv("DB_POOL_RECYCLE", "1800"))
+            db_isolation_level = isolation_level or os.getenv("DATABASE_ISOLATION_LEVEL")
+        
+        # 构建引擎参数
+        engine_kwargs: dict = {
+            "echo": db_echo,
+            "future": True,
+            "pool_pre_ping": True,
+            "pool_size": db_pool_size,
+            "max_overflow": db_max_overflow,
+            "pool_timeout": db_pool_timeout,
+            "pool_recycle": db_pool_recycle,
+        }
+        
+        # 添加隔离级别（如果配置了）
+        if db_isolation_level:
+            engine_kwargs["isolation_level"] = db_isolation_level
+            logger.info(f"事务隔离级别设置为: {db_isolation_level}")
+        
+        self._engine = create_async_engine(database_url, **engine_kwargs)
+        
+        self._session_factory = async_sessionmaker(
+            self._engine,
+            expire_on_commit=False,
+            autoflush=False,
+            class_=AsyncSession,
+        )
+        
+        # 验证连接
+        await self.health_check()
+        
+        self._initialized = True
+        logger.info("数据库管理器初始化完成")
+    
+    async def health_check(self) -> bool:
+        """健康检查。
+        
+        Returns:
+            bool: 连接是否正常
+        """
+        try:
+            async with self.engine.begin() as conn:
+                await conn.execute(text("SELECT 1"))
+            logger.debug("数据库健康检查通过")
+            return True
+        except Exception as exc:
+            logger.error(f"数据库健康检查失败: {exc}")
+            return False
+    
+    async def _check_session_connection(self, session: AsyncSession) -> None:
+        """检查会话连接状态，必要时重连。
+        
+        使用 SQLAlchemy 的通用异常类，支持所有数据库后端。
+        
+        Args:
+            session: 数据库会话
+            
+        Raises:
+            Exception: 重试次数耗尽后抛出异常
+        """
+        retries = self._max_retries
+        while retries > 0:
+            try:
+                await session.execute(text("SELECT 1"))
+                return
+            except (DisconnectionError, OperationalError) as exc:
+                logger.warning(f"数据库连接丢失，剩余重试次数: {retries}, 错误: {exc}")
+                retries -= 1
+                if retries == 0:
+                    logger.error("数据库连接重试失败")
+                    raise
+                await asyncio.sleep(self._retry_delay)
+            except Exception as exc:
+                # 其他异常直接抛出，不重试
+                logger.error(f"数据库连接检查失败: {exc}")
+                raise
+    
+    @asynccontextmanager
+    async def session(self) -> AsyncGenerator[AsyncSession]:
+        """获取数据库会话（上下文管理器）。
+        
+        Yields:
+            AsyncSession: 数据库会话
+            
+        使用示例:
+            async with db_manager.session() as session:
+                result = await session.execute(query)
+        """
+        session = self.session_factory()
+        try:
+            await self._check_session_connection(session)
+            yield session
+        except Exception as exc:
+            await session.rollback()
+            logger.exception(f"数据库会话异常: {exc}")
+            raise
+        finally:
+            await session.close()
+    
+    async def create_session(self) -> AsyncSession:
+        """创建新的数据库会话（需要手动关闭）。
+        
+        Returns:
+            AsyncSession: 数据库会话
+            
+        注意：使用后需要手动调用 await session.close()
+        建议使用 session() 上下文管理器代替此方法。
+        """
+        session = self.session_factory()
+        await self._check_session_connection(session)
+        return session
+    
+    async def get_session(self) -> AsyncGenerator[AsyncSession, None]:
+        """FastAPI 依赖注入专用的会话获取器。
+        
+        Yields:
+            AsyncSession: 数据库会话
+            
+        使用示例（FastAPI 路由）:
+            @router.get("/items")
+            async def get_items(
+                session: AsyncSession = Depends(db_manager.get_session),
+            ):
+                ...
+        """
+        async with self.session() as session:
+            yield session
+    
+    async def cleanup(self) -> None:
+        """清理资源，关闭所有连接。"""
+        if self._engine is not None:
+            await self._engine.dispose()
+            logger.info("数据库连接已关闭")
+        
+        self._engine = None
+        self._session_factory = None
+        self._initialized = False
+    
+    def __repr__(self) -> str:
+        """字符串表示。"""
+        status = "initialized" if self._initialized else "not initialized"
+        return f"<DatabaseManager status={status}>"
+
+
+__all__ = [
+    "DatabaseManager",
+]
+

aury/boot/infrastructure/database/query_tools/__init__.py

@@ -0,0 +1,164 @@
+"""查询优化工具。
+
+提供缓存和性能监控装饰器。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import wraps
+import hashlib
+import time
+
+from aury.boot.common.logging import logger
+
+# 查询性能监控配置
+QUERY_SLOW_THRESHOLD = 1.0  # 慢查询阈值（秒）
+
+
+def cache_query(
+    ttl: int = 300,
+    key_prefix: str = "",
+    key_func: Callable | None = None,
+) -> Callable:
+    """查询结果缓存装饰器。
+    
+    缓存查询结果，减少数据库访问。
+    集成现有的 CacheManager。
+    
+    Args:
+        ttl: 缓存过期时间（秒），默认 300 秒
+        key_prefix: 缓存键前缀
+        key_func: 自定义缓存键生成函数
+    
+    用法:
+        class UserRepository(BaseRepository):
+            @cache_query(ttl=600, key_prefix="user")
+            async def get_by_email(self, email: str):
+                return await self.get_by(email=email)
+    """
+    
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(self, *args, **kwargs):
+            try:
+                from aury.boot.infrastructure.cache import CacheManager
+                
+                cache = CacheManager.get_instance()
+                
+                # 生成缓存键
+                if key_func:
+                    cache_key = key_func(self, *args, **kwargs)
+                else:
+                    # 默认缓存键生成策略
+                    key_parts = [key_prefix, func.__name__]
+                    if args:
+                        key_parts.extend(str(arg) for arg in args)
+                    if kwargs:
+                        key_parts.extend(f"{k}:{v}" for k, v in sorted(kwargs.items()))
+                    
+                    # 使用 MD5 生成固定长度的键
+                    key_str = ":".join(str(p) for p in key_parts)
+                    cache_key = f"repo:{hashlib.md5(key_str.encode()).hexdigest()}"
+                
+                # 尝试从缓存获取
+                cached_result = await cache.get(cache_key)
+                if cached_result is not None:
+                    logger.debug(f"缓存命中: {cache_key}")
+                    return cached_result
+                
+                # 执行查询
+                result = await func(self, *args, **kwargs)
+                
+                # 存入缓存
+                await cache.set(cache_key, result, expire=ttl)
+                logger.debug(f"缓存写入: {cache_key}, TTL={ttl}s")
+                
+                return result
+            except Exception as e:
+                # 缓存失败不影响主流程
+                logger.warning(f"查询缓存失败: {e}，继续执行查询")
+                return await func(self, *args, **kwargs)
+        
+        return wrapper
+    
+    return decorator
+
+
+def monitor_query(
+    slow_threshold: float = QUERY_SLOW_THRESHOLD,
+    enable_explain: bool = False,
+) -> Callable:
+    """查询性能监控装饰器。
+    
+    监控查询执行时间，记录慢查询日志。
+    支持 SQLAlchemy explain() 功能。
+    
+    Args:
+        slow_threshold: 慢查询阈值（秒），默认 1.0 秒
+        enable_explain: 是否启用查询计划分析
+    
+    用法:
+        class UserRepository(BaseRepository):
+            @monitor_query(slow_threshold=0.5)
+            async def list(self, **filters):
+                return await super().list(**filters)
+    """
+    
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(self, *args, **kwargs):
+            start_time = time.time()
+            
+            try:
+                # 执行查询
+                result = await func(self, *args, **kwargs)
+                
+                # 计算执行时间
+                duration = time.time() - start_time
+                
+                # 记录慢查询
+                if duration >= slow_threshold:
+                    logger.warning(
+                        f"慢查询检测: {func.__name__} 执行时间 {duration:.3f}s "
+                        f"(阈值: {slow_threshold}s)"
+                    )
+                    
+                    # 如果启用 explain，尝试获取查询计划
+                    if enable_explain and hasattr(self, "_last_query"):
+                        try:
+                            from sqlalchemy import text
+                            explain_result = await self._session.execute(
+                                text(f"EXPLAIN {self._last_query!s}")
+                            )
+                            explain_text = "\n".join(str(row) for row in explain_result)
+                            logger.debug(f"查询计划:\n{explain_text}")
+                        except Exception as e:
+                            logger.debug(f"无法获取查询计划: {e}")
+                
+                # 记录正常查询（调试级别）
+                else:
+                    logger.debug(
+                        f"查询执行: {func.__name__} 耗时 {duration:.3f}s"
+                    )
+                
+                return result
+            except Exception as e:
+                duration = time.time() - start_time
+                logger.error(
+                    f"查询失败: {func.__name__} 执行时间 {duration:.3f}s, 错误: {e}"
+                )
+                raise
+        
+        return wrapper
+    
+    return decorator
+
+
+__all__ = [
+    "cache_query",
+    "monitor_query",
+]
+
+
+

aury/boot/infrastructure/database/strategies/__init__.py

@@ -0,0 +1,198 @@
+"""UPSERT 策略实现。
+
+为不同数据库提供 UPSERT 操作的策略实现。
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, ClassVar
+
+from sqlalchemy import Table, text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from aury.boot.common.logging import logger
+
+
+class UpsertStrategy(ABC):
+    """UPSERT 策略抽象基类。
+    
+    为不同数据库提供 UPSERT 操作的统一接口。
+    """
+    
+    @abstractmethod
+    async def execute(
+        self,
+        session: AsyncSession,
+        table: Table,
+        data_list: list[dict[str, Any]],
+        index_elements: list[str],
+        update_columns: list[str],
+    ) -> None:
+        """执行 UPSERT 操作。
+        
+        Args:
+            session: 数据库会话
+            table: 表对象
+            data_list: 数据字典列表
+            index_elements: 索引字段列表
+            update_columns: 需要更新的字段列表
+        """
+        pass
+
+
+class PostgreSQLUpsertStrategy(UpsertStrategy):
+    """PostgreSQL UPSERT 策略。
+    
+    使用 ON CONFLICT DO UPDATE 语法。
+    """
+    
+    async def execute(
+        self,
+        session: AsyncSession,
+        table: Table,
+        data_list: list[dict[str, Any]],
+        index_elements: list[str],
+        update_columns: list[str],
+    ) -> None:
+        """执行 PostgreSQL UPSERT。"""
+        from sqlalchemy.dialects.postgresql import insert as pg_insert
+        
+        stmt = pg_insert(table).values(data_list)
+        stmt = stmt.on_conflict_do_update(
+            index_elements=index_elements,
+            set_={col: stmt.excluded[col] for col in update_columns}
+        )
+        
+        await session.execute(stmt)
+        await session.flush()
+        logger.debug(f"批量插入或更新 {len(data_list)} 条记录（PostgreSQL）")
+
+
+class SQLiteUpsertStrategy(UpsertStrategy):
+    """SQLite UPSERT 策略。
+    
+    使用 ON CONFLICT DO UPDATE 语法（SQLite 3.24.0+）。
+    """
+    
+    async def execute(
+        self,
+        session: AsyncSession,
+        table: Table,
+        data_list: list[dict[str, Any]],
+        index_elements: list[str],
+        update_columns: list[str],
+    ) -> None:
+        """执行 SQLite UPSERT。"""
+        from sqlalchemy.dialects.sqlite import insert as sqlite_insert
+        
+        stmt = sqlite_insert(table).values(data_list)
+        stmt = stmt.on_conflict_do_update(
+            index_elements=index_elements,
+            set_={col: stmt.excluded[col] for col in update_columns}
+        )
+        
+        await session.execute(stmt)
+        await session.flush()
+        logger.debug(f"批量插入或更新 {len(data_list)} 条记录（SQLite）")
+
+
+class MySQLUpsertStrategy(UpsertStrategy):
+    """MySQL UPSERT 策略。
+    
+    使用 ON DUPLICATE KEY UPDATE 语法。
+    """
+    
+    async def execute(
+        self,
+        session: AsyncSession,
+        table: Table,
+        data_list: list[dict[str, Any]],
+        index_elements: list[str],
+        update_columns: list[str],
+    ) -> None:
+        """执行 MySQL UPSERT。"""
+        # 构建批量 INSERT ... ON DUPLICATE KEY UPDATE 语句
+        columns = list(data_list[0].keys())
+        column_names = ", ".join(columns)
+        
+        # 构建 VALUES 子句（批量插入）
+        values_placeholders = []
+        params = {}
+        for idx, data in enumerate(data_list):
+            row_placeholders = []
+            for col in columns:
+                param_name = f"{col}_{idx}"
+                row_placeholders.append(f":{param_name}")
+                params[param_name] = data[col]
+            values_placeholders.append(f"({', '.join(row_placeholders)})")
+        
+        values_clause = ", ".join(values_placeholders)
+        
+        # 构建 ON DUPLICATE KEY UPDATE 子句
+        update_clauses = [f"{col} = VALUES({col})" for col in update_columns]
+        update_clause = ", ".join(update_clauses)
+        
+        # 执行 SQL
+        sql = f"INSERT INTO {table.name} ({column_names}) VALUES {values_clause} ON DUPLICATE KEY UPDATE {update_clause}"
+        await session.execute(text(sql), params)
+        await session.flush()
+        logger.debug(f"批量插入或更新 {len(data_list)} 条记录（MySQL）")
+
+
+class UpsertStrategyFactory:
+    """UPSERT 策略工厂。
+    
+    根据数据库方言创建相应的策略实例。
+    """
+    
+    _strategies: ClassVar[dict[str, type[UpsertStrategy]]] = {
+        "postgresql": PostgreSQLUpsertStrategy,
+        "sqlite": SQLiteUpsertStrategy,
+        "mysql": MySQLUpsertStrategy,
+    }
+    
+    @classmethod
+    def create(cls, dialect_name: str) -> UpsertStrategy:
+        """创建 UPSERT 策略实例。
+        
+        Args:
+            dialect_name: 数据库方言名称
+            
+        Returns:
+            UpsertStrategy: 策略实例
+            
+        Raises:
+            NotImplementedError: 如果数据库不支持 UPSERT 操作
+        """
+        strategy_class = cls._strategies.get(dialect_name)
+        if strategy_class is None:
+            raise NotImplementedError(
+                f"数据库 {dialect_name} 不支持 UPSERT 操作。"
+                "请使用 bulk_insert() 或实现自定义的插入/更新逻辑。"
+            )
+        
+        return strategy_class()
+    
+    @classmethod
+    def register(cls, dialect_name: str, strategy_class: type[UpsertStrategy]) -> None:
+        """注册自定义策略。
+        
+        Args:
+            dialect_name: 数据库方言名称
+            strategy_class: 策略类
+        """
+        cls._strategies[dialect_name] = strategy_class
+        logger.debug(f"注册 UPSERT 策略: {dialect_name} -> {strategy_class.__name__}")
+
+
+__all__ = [
+    "MySQLUpsertStrategy",
+    "PostgreSQLUpsertStrategy",
+    "SQLiteUpsertStrategy",
+    "UpsertStrategy",
+    "UpsertStrategyFactory",
+]
+
+
+

aury/boot/infrastructure/di/__init__.py

@@ -0,0 +1,15 @@
+"""依赖注入模块。
+
+提供依赖注入容器和相关功能。
+"""
+
+from .container import Container, Lifetime, Scope, ServiceDescriptor
+
+__all__ = [
+    "Container",
+    "Lifetime",
+    "Scope",
+    "ServiceDescriptor",
+]
+
+