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

aury/boot/application/app/components.py

@@ -0,0 +1,434 @@
+"""默认组件实现。
+
+提供所有内置基础设施组件的实现。
+"""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+from typing import ClassVar
+
+from aury.boot.application.app.base import Component, FoundationApp
+from aury.boot.application.config import BaseConfig
+from aury.boot.application.constants import ComponentName, ServiceType
+from aury.boot.application.migrations import MigrationManager
+from aury.boot.common.logging import logger
+from aury.boot.infrastructure.cache import CacheManager
+from aury.boot.infrastructure.database import DatabaseManager
+from aury.boot.infrastructure.scheduler import SchedulerManager
+from aury.boot.infrastructure.storage import StorageManager
+from aury.boot.infrastructure.tasks import TaskManager
+
+
+class DatabaseComponent(Component):
+    """数据库组件。"""
+
+    name = ComponentName.DATABASE
+    enabled = True
+    depends_on: ClassVar[list[str]] = []
+
+    def can_enable(self, config: BaseConfig) -> bool:
+        """仅当配置了数据库 URL 时启用。"""
+        return self.enabled and bool(config.database.url)
+
+    async def setup(self, app: FoundationApp, config: BaseConfig) -> None:
+        """初始化数据库。"""
+        try:
+            db_manager = DatabaseManager.get_instance()
+            if not db_manager._initialized:
+                await db_manager.initialize(
+                    url=config.database.url,
+                    echo=config.database.echo,
+                    pool_size=config.database.pool_size,
+                    max_overflow=config.database.max_overflow,
+                    pool_timeout=config.database.pool_timeout,
+                    pool_recycle=config.database.pool_recycle,
+                )
+        except Exception as e:
+            logger.error(f"数据库初始化失败: {e}")
+            raise
+
+    async def teardown(self, app: FoundationApp) -> None:
+        """关闭数据库。"""
+        try:
+            db_manager = DatabaseManager.get_instance()
+            if db_manager._initialized:
+                await db_manager.cleanup()
+        except Exception as e:
+            logger.error(f"数据库关闭失败: {e}")
+
+
+class CacheComponent(Component):
+    """缓存组件。"""
+
+    name = ComponentName.CACHE
+    enabled = True
+    depends_on: ClassVar[list[str]] = []
+
+    def can_enable(self, config: BaseConfig) -> bool:
+        """仅当配置了缓存类型时启用。"""
+        return self.enabled and bool(config.cache.cache_type)
+
+    async def setup(self, app: FoundationApp, config: BaseConfig) -> None:
+        """初始化缓存。"""
+        try:
+            cache_manager = CacheManager.get_instance()
+            if not cache_manager._backend:
+                await cache_manager.init_app({
+                    "CACHE_TYPE": config.cache.cache_type,
+                    "CACHE_URL": config.cache.url,
+                    "CACHE_MAX_SIZE": config.cache.max_size,
+                })
+        except Exception as e:
+            logger.warning(f"缓存初始化失败（非关键）: {e}")
+
+    async def teardown(self, app: FoundationApp) -> None:
+        """关闭缓存。"""
+        try:
+            cache_manager = CacheManager.get_instance()
+            if cache_manager._backend:
+                await cache_manager.cleanup()
+        except Exception as e:
+            logger.warning(f"缓存关闭失败: {e}")
+
+
+class StorageComponent(Component):
+    """对象存储组件。
+
+设计要点（解耦）：
+- 使用 aury-sdk-storage 的 StorageConfig/StorageBackend，Application 层仅做装配
+- 建议由应用的 `StorageSettings` 读取环境变量并构造 SDK 的 StorageConfig
+"""
+
+    name = ComponentName.STORAGE
+    enabled = True
+    depends_on: ClassVar[list[str]] = []
+
+    def can_enable(self, config: BaseConfig) -> bool:
+        st = getattr(config, "storage", None)
+        return self.enabled and bool(getattr(st, "enabled", True))
+
+    async def setup(self, app: FoundationApp, config: BaseConfig) -> None:
+        try:
+            from aury.boot.infrastructure.storage import StorageBackend, StorageConfig
+
+            storage_manager = StorageManager.get_instance()
+            st = config.storage
+            storage_config = StorageConfig(
+                backend=StorageBackend(st.type),
+                access_key_id=st.access_key_id,
+                access_key_secret=st.access_key_secret,
+                session_token=st.session_token,
+                endpoint=st.endpoint,
+                region=st.region,
+                bucket_name=st.bucket_name,
+                base_path=st.base_path,
+                addressing_style=st.addressing_style,
+                role_arn=st.role_arn,
+                role_session_name=st.role_session_name,
+                external_id=st.external_id,
+                sts_endpoint=st.sts_endpoint,
+                sts_region=st.sts_region,
+                sts_duration_seconds=st.sts_duration_seconds,
+            )
+            await storage_manager.init(storage_config)
+        except Exception as e:
+            logger.warning(f"存储初始化失败（非关键）: {e}")
+
+    async def teardown(self, app: FoundationApp) -> None:
+        try:
+            storage_manager = StorageManager.get_instance()
+            await storage_manager.cleanup()
+        except Exception as e:
+            logger.warning(f"存储关闭失败: {e}")
+
+
+class TaskComponent(Component):
+    """任务队列组件（Worker 模式）。"""
+
+    name = ComponentName.TASK_QUEUE
+    enabled = True
+    depends_on: ClassVar[list[str]] = []
+
+    def can_enable(self, config: BaseConfig) -> bool:
+        """仅当是 Worker 模式且配置了 broker URL 时启用。"""
+        return (
+            self.enabled
+            and config.service.service_type == ServiceType.WORKER.value
+            and bool(config.task.broker_url)
+        )
+
+    async def setup(self, app: FoundationApp, config: BaseConfig) -> None:
+        """初始化任务队列。"""
+        try:
+            from aury.boot.infrastructure.tasks.constants import TaskRunMode
+            
+            task_manager = TaskManager.get_instance()
+            # 将 application 层的 ServiceType.WORKER 转换为 infrastructure 层的 TaskRunMode.WORKER
+            # ServiceType.API 和 ServiceType.SCHEDULER 转换为 TaskRunMode.PRODUCER
+            if config.service.service_type == ServiceType.WORKER.value:
+                run_mode = TaskRunMode.WORKER
+            else:
+                run_mode = TaskRunMode.PRODUCER
+            
+            await task_manager.initialize(
+                run_mode=run_mode,
+                broker_url=config.task.broker_url,
+            )
+        except Exception as e:
+            logger.warning(f"任务队列初始化失败（非关键）: {e}")
+
+    async def teardown(self, app: FoundationApp) -> None:
+        """无需显式清理。"""
+        pass
+
+
+class SchedulerComponent(Component):
+    """调度器组件。
+    
+    支持两种任务发现方式：
+    1. 配置方式：通过 SCHEDULER_JOB_MODULES 指定要加载的模块
+    2. 自动感知：无配置时自动发现 schedules 模块
+    
+    @scheduler.scheduled_job() 装饰器可以在模块导入时使用，
+    任务会被收集到待注册列表，在 start() 时注册并启动。
+    """
+
+    name = ComponentName.SCHEDULER
+    enabled = True
+    depends_on: ClassVar[list[str]] = []
+
+    def can_enable(self, config: BaseConfig) -> bool:
+        """仅当是 API 服务且启用调度器时启用。"""
+        return (
+            self.enabled
+            and config.service.service_type == ServiceType.API.value
+            and config.scheduler.enabled
+        )
+
+    def _autodiscover_schedules(self, app: FoundationApp, config: BaseConfig) -> None:
+        """自动发现并加载定时任务模块。
+        
+        发现策略：
+        1. 如果配置了 schedule_modules，直接加载配置的模块
+        2. 优先尝试项目包名和服务名：
+           - {pyproject.tool.aury.package}.schedules
+           - {SERVICE_NAME}.schedules（当 SERVICE_NAME 不是默认值时）
+        3. 从 app._caller_module 推断：
+           - __main__ / main → 尝试 schedules
+           - myapp.main → 尝试 myapp.schedules
+        4. 回退：尝试导入 schedules
+        """
+        modules_to_load: list[str] = []
+        
+        # 策略 1：配置优先
+        if config.scheduler.schedule_modules:
+            modules_to_load = list(config.scheduler.schedule_modules)
+            logger.debug(f"使用配置的定时任务模块: {modules_to_load}")
+        else:
+            # 策略 2：项目包名与服务名
+            try:
+                from aury.boot.commands.config import get_project_config
+                cfg = get_project_config()
+                if cfg.has_package:
+                    modules_to_load.append(f"{cfg.package}.schedules")
+            except Exception:
+                pass
+            
+            service_name = (getattr(config.service, "name", None) or "").strip()
+            if service_name and service_name not in {"app", "main"}:
+                modules_to_load.append(f"{service_name}.schedules")
+            
+            # 策略 3：从调用者模块推断
+            caller = getattr(app, "_caller_module", "__main__")
+            if caller in ("__main__", "main"):
+                modules_to_load.append("schedules")
+            elif "." in caller:
+                package = caller.rsplit(".", 1)[0]
+                modules_to_load.extend([f"{package}.schedules", "schedules"])
+            else:
+                modules_to_load.extend([f"{caller}.schedules", "schedules"])
+        
+        # 去重，保持顺序
+        seen = set()
+        modules_to_load = [m for m in modules_to_load if not (m in seen or seen.add(m))]
+        
+        # 加载模块
+        for module_name in modules_to_load:
+            try:
+                module = importlib.import_module(module_name)
+                logger.info(f"已自动加载定时任务模块: {module_name}")
+                
+                # 递归加载包下所有子模块
+                if hasattr(module, "__path__"):
+                    for _, submodule_name, _ in pkgutil.walk_packages(
+                        module.__path__, prefix=f"{module_name}."
+                    ):
+                        try:
+                            importlib.import_module(submodule_name)
+                            logger.debug(f"已加载子模块: {submodule_name}")
+                        except Exception as e:
+                            logger.warning(f"加载子模块失败 ({submodule_name}): {e}")
+                
+                # 如果成功加载一个，且不是配置模式，就停止
+                if not config.scheduler.schedule_modules:
+                    break
+            except ImportError:
+                logger.debug(f"定时任务模块不存在: {module_name}")
+            except Exception as e:
+                logger.warning(f"加载定时任务模块失败 ({module_name}): {e}")
+
+    async def setup(self, app: FoundationApp, config: BaseConfig) -> None:
+        """启动调度器。
+        
+        1. 自动发现并加载定时任务模块
+        2. 启动调度器（注册装饰器收集的任务）
+        """
+        try:
+            # 自动发现并加载定时任务模块
+            self._autodiscover_schedules(app, config)
+            
+            # 启动调度器
+            scheduler = SchedulerManager.get_instance()
+            scheduler.start()
+        except Exception as e:
+            logger.warning(f"调度器启动失败（非关键）: {e}")
+
+    async def teardown(self, app: FoundationApp) -> None:
+        """关闭调度器。"""
+        try:
+            scheduler = SchedulerManager.get_instance()
+            if scheduler._scheduler and scheduler._scheduler.running:
+                scheduler.shutdown()
+        except Exception as e:
+            logger.warning(f"调度器关闭失败: {e}")
+
+
+class MigrationComponent(Component):
+    """数据库迁移组件。
+    
+    自动执行数据库迁移（升级到最新版本）。
+    
+    配置选项：
+    - `ENABLE_AUTO_MIGRATION`：是否启用自动迁移（默认：True）
+    - `ALEMBIC_CONFIG_PATH`：Alembic 配置文件路径（默认：alembic.ini）
+    - `AUTO_MIGRATE_ON_STARTUP`：应用启动时是否自动执行迁移（默认：True）
+    
+    使用示例：
+        # 在应用启动时自动执行迁移
+        app = FoundationApp()
+        # MigrationComponent 会在 DatabaseComponent 之后自动执行迁移
+    """
+
+    name = ComponentName.MIGRATIONS
+    enabled = True
+    depends_on: ClassVar[list[str]] = [ComponentName.DATABASE]
+
+    def can_enable(self, config: BaseConfig) -> bool:
+        """仅当配置了数据库 URL 时启用。"""
+        return self.enabled and bool(config.database.url)
+
+    async def setup(self, app: FoundationApp, config: BaseConfig) -> None:
+        """执行数据库迁移。
+        
+        在应用启动时自动执行所有待处理的迁移，升级数据库到最新版本。
+        """
+        try:
+            # 创建迁移管理器（从配置读取参数）
+            migration_settings = config.migration
+            migration_manager = MigrationManager(
+                database_url=config.database.url,
+                config_path=migration_settings.config_path,
+                script_location=migration_settings.script_location,
+                model_modules=migration_settings.model_modules,
+                auto_create=migration_settings.auto_create,
+            )
+            
+            # 检查是否有迁移需要执行
+            logger.info("🔄 检查数据库迁移...")
+            status = await migration_manager.status()
+            
+            pending = status.get("pending", [])
+            applied = status.get("applied", [])
+            
+            if pending:
+                logger.info("📊 数据库迁移状态：")
+                logger.info(f"   已执行: {len(applied)} 个迁移")
+                logger.info(f"   待执行: {len(pending)} 个迁移")
+                
+                # 执行迁移到最新版本
+                logger.info("⏳ 执行数据库迁移...")
+                await migration_manager.upgrade(revision="head")
+                
+                logger.info("✅ 数据库迁移完成")
+            else:
+                logger.info("✅ 数据库已是最新版本，无需迁移")
+        except Exception as e:
+            logger.error(f"❌ 数据库迁移失败: {e}", exc_info=True)
+            raise
+
+    async def teardown(self, app: FoundationApp) -> None:
+        """无需清理。"""
+        pass
+
+
+class AdminConsoleComponent(Component):
+    """管理后台组件（SQLAdmin Admin Console）。
+
+    配置选项（环境变量前缀 ADMIN_ / ADMIN_AUTH_）：
+    - ADMIN_ENABLED: 是否启用（默认 False）
+    - ADMIN_PATH: 后台路径（默认 /api/admin-console）
+    - ADMIN_DATABASE_URL: 同步数据库 URL（可选）
+    - ADMIN_AUTH_MODE: basic/bearer/none/custom/jwt
+    - ADMIN_AUTH_*: 认证参数
+
+    注意：sqladmin 通常要求同步 SQLAlchemy Engine。
+    """
+
+    name = ComponentName.ADMIN_CONSOLE
+    enabled = True
+    depends_on: ClassVar[list[str]] = [ComponentName.DATABASE]
+
+    def can_enable(self, config: BaseConfig) -> bool:
+        return self.enabled and bool(getattr(getattr(config, "admin", None), "enabled", False))
+
+    async def setup(self, app: FoundationApp, config: BaseConfig) -> None:
+        try:
+            from aury.boot.contrib.admin_console import install_admin_console
+
+            install_admin_console(app, config)
+        except ImportError as e:
+            logger.error(f"管理后台启用失败：缺少依赖（请安装 aury-boot[admin]）: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"管理后台初始化失败: {e}")
+            raise
+
+    async def teardown(self, app: FoundationApp) -> None:
+        # SQLAdmin 路由挂载后无需额外 teardown
+        pass
+
+
+# 设置默认组件
+FoundationApp.components = [
+    DatabaseComponent,
+    MigrationComponent,
+    AdminConsoleComponent,
+    CacheComponent,
+    StorageComponent,
+    TaskComponent,
+    SchedulerComponent,
+]
+
+
+__all__ = [
+    "AdminConsoleComponent",
+    "CacheComponent",
+    "DatabaseComponent",
+    "MigrationComponent",
+    "SchedulerComponent",
+    "StorageComponent",
+    "TaskComponent",
+]
+

aury/boot/application/app/middlewares.py

@@ -0,0 +1,101 @@
+"""默认中间件实现。
+
+提供所有内置 HTTP 中间件的实现。
+"""
+
+from __future__ import annotations
+
+from fastapi.middleware.cors import CORSMiddleware as FastAPICORSMiddleware
+from starlette.middleware import Middleware as StarletteMiddleware
+
+from aury.boot.application.app.base import FoundationApp, Middleware
+from aury.boot.application.config import BaseConfig
+from aury.boot.application.constants import MiddlewareName
+from aury.boot.application.middleware.logging import (
+    RequestLoggingMiddleware as StarletteRequestLoggingMiddleware,
+    WebSocketLoggingMiddleware as StarletteWebSocketLoggingMiddleware,
+)
+
+__all__ = [
+    "CORSMiddleware",
+    "RequestLoggingMiddleware",
+    "WebSocketLoggingMiddleware",
+]
+
+
+class RequestLoggingMiddleware(Middleware):
+    """请求日志中间件。
+
+    自动记录所有 HTTP 请求的详细信息，包括：
+    - 请求方法、路径、查询参数
+    - 客户端 IP、User-Agent
+    - 响应状态码、耗时
+    - 链路追踪 ID（X-Trace-ID / X-Request-ID）
+    """
+
+    name = MiddlewareName.REQUEST_LOGGING
+    enabled = True
+    order = 0  # 最先执行，确保日志记录所有请求
+
+    def build(self, config: BaseConfig) -> StarletteMiddleware:
+        """构建请求日志中间件实例。"""
+        return StarletteMiddleware(StarletteRequestLoggingMiddleware)
+
+
+class CORSMiddleware(Middleware):
+    """CORS 跨域处理中间件。
+
+    处理跨域资源共享（CORS）请求，允许配置：
+    - 允许的源（origins）
+    - 允许的方法（methods）
+    - 允许的头（headers）
+    - 凭证支持（credentials）
+    """
+
+    name = MiddlewareName.CORS
+    enabled = True
+    order = 10  # 在请求日志之后执行
+
+    def can_enable(self, config: BaseConfig) -> bool:
+        """仅当配置了 origins 时启用。"""
+        return self.enabled and bool(config.cors.origins)
+
+    def build(self, config: BaseConfig) -> StarletteMiddleware:
+        """构建 CORS 中间件实例。"""
+        return StarletteMiddleware(
+            FastAPICORSMiddleware,
+            allow_origins=config.cors.origins,
+            allow_credentials=config.cors.allow_credentials,
+            allow_methods=config.cors.allow_methods,
+            allow_headers=config.cors.allow_headers,
+        )
+
+
+class WebSocketLoggingMiddleware(Middleware):
+    """WebSocket 日志中间件。
+
+    记录 WebSocket 连接生命周期：
+    - 连接建立/断开
+    - 消息收发统计
+    - 异常断开
+    - 链路追踪 ID
+    """
+
+    name = MiddlewareName.WEBSOCKET_LOGGING
+    enabled = True
+    order = 1  # 紧随 HTTP 日志中间件
+
+    def build(self, config: BaseConfig) -> StarletteMiddleware:
+        """构建 WebSocket 日志中间件实例。"""
+        return StarletteMiddleware(
+            StarletteWebSocketLoggingMiddleware,
+            log_messages=config.log.websocket_log_messages,
+        )
+
+
+# 设置默认中间件
+FoundationApp.middlewares = [
+    RequestLoggingMiddleware,
+    WebSocketLoggingMiddleware,
+    CORSMiddleware,
+]

aury/boot/application/config/__init__.py

@@ -0,0 +1,44 @@
+"""配置模块。
+
+提供所有应用共享的基础配置结构。
+使用 pydantic-settings 进行分层分级配置管理。
+
+设计原则：
+- Application 层配置完全独立，不依赖 Infrastructure 层
+- 配置是纯粹的数据模型定义
+"""
+
+from .settings import (
+    BaseConfig,
+    CacheSettings,
+    CORSSettings,
+    DatabaseSettings,
+    EventSettings,
+    HealthCheckSettings,
+    LogSettings,
+    MigrationSettings,
+    RPCClientSettings,
+    RPCServiceSettings,
+    SchedulerSettings,
+    ServerSettings,
+    ServiceSettings,
+    TaskSettings,
+)
+
+__all__ = [
+    "BaseConfig",
+    "CacheSettings",
+    "CORSSettings",
+    "DatabaseSettings",
+    "EventSettings",
+    "HealthCheckSettings",
+    "LogSettings",
+    "MigrationSettings",
+    "RPCClientSettings",
+    "RPCServiceSettings",
+    "SchedulerSettings",
+    "ServerSettings",
+    "ServiceSettings",
+    "TaskSettings",
+]
+