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

aury/boot/application/adapter/http.py

@@ -0,0 +1,325 @@
+"""HTTP 类第三方接口适配器。
+
+本模块提供 HTTP REST API 类第三方接口的便捷基类，适用于大部分第三方服务
+（如支付接口、短信接口、地图API、云服务API等）。
+
+基于 toolkit.http.HttpClient 封装，核心功能：
+- 自动管理 HttpClient 生命周期（连接池、重试、超时）
+- 统一的请求头处理（认证、签名、trace-id）
+- 请求/响应日志和链路追踪
+- HTTP 错误转换为 AdapterError
+- 自动根据 mode 选择 base_url（生产）或 sandbox_url（沙箱）
+
+如果第三方提供的是 SDK 而非 HTTP API（如微信支付 SDK、阿里云 SDK），
+或者使用 gRPC 等非 HTTP 协议，请直接继承 BaseAdapter。
+
+典型第三方接口举例：
+- 支付：微信支付、支付宝、Stripe 等
+- 短信：阿里云短信、腾讯云短信、Twilio 等
+- 云存储：七牛、又拍云、AWS S3 等
+- 社交：微信开放平台、企业微信、钉钉等
+- 地图：高德、百度、Google Maps 等
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from aury.boot.common.logging import get_trace_id, logger
+from aury.boot.toolkit.http import HttpClient, RetryConfig
+
+from .base import BaseAdapter
+from .config import AdapterSettings
+from .exceptions import AdapterError, AdapterTimeoutError
+
+
+class HttpAdapter(BaseAdapter):
+    """HTTP 类第三方 Adapter 基类。
+    
+    封装 HttpClient，提供统一的 HTTP 请求方法和错误处理。
+    
+    核心功能：
+    - 自动根据 settings.mode 选择 base_url / sandbox_url
+    - 统一的请求头处理（认证、签名、trace-id）
+    - 请求/响应日志
+    - 超时和重试配置
+    - 错误转换为 AdapterError
+    
+    使用示例:
+        class PaymentAdapter(HttpAdapter):
+            @adapter_method("create")
+            async def create_order(self, amount: int, order_id: str) -> dict:
+                return await self._request(
+                    "POST", "/v1/charges",
+                    json={"amount": amount, "order_id": order_id}
+                )
+            
+            @create_order.mock
+            async def create_order_mock(self, amount: int, order_id: str) -> dict:
+                return {"success": True, "mock": True, "charge_id": "ch_mock_123"}
+            
+            # 自定义请求头（如签名）
+            def _prepare_headers(self, extra: dict | None = None) -> dict:
+                headers = super()._prepare_headers(extra)
+                headers["X-Signature"] = self._sign_request(...)
+                return headers
+    
+    Attributes:
+        _client: HttpClient 实例（mode 为 real/sandbox 时可用）
+    """
+    
+    def __init__(
+        self,
+        name: str,
+        settings: AdapterSettings,
+        *,
+        client: HttpClient | None = None,
+    ) -> None:
+        """初始化 HTTP Adapter。
+        
+        Args:
+            name: Adapter 名称
+            settings: 集成配置
+            client: 自定义 HttpClient（可选，默认根据配置自动创建）
+        """
+        super().__init__(name, settings)
+        self._client: HttpClient | None = client
+        self._owns_client = client is None  # 是否由本类创建（需要自己清理）
+    
+    # ========== 生命周期 ==========
+    
+    async def _on_initialize(self) -> None:
+        """初始化 HttpClient。"""
+        if self._client is not None:
+            return
+        
+        # 只有 real / sandbox 模式需要真实客户端
+        if self.settings.mode not in ("real", "sandbox"):
+            logger.debug(f"HttpAdapter {self.name} 处于 {self.settings.mode} 模式，跳过 HttpClient 初始化")
+            return
+        
+        effective_url = self.settings.get_effective_url()
+        if not effective_url:
+            logger.warning(
+                f"HttpAdapter {self.name} 未配置 base_url/sandbox_url，"
+                f"真实调用可能失败"
+            )
+            return
+        
+        # 创建 HttpClient
+        retry_config = RetryConfig(max_retries=self.settings.retry_times)
+        self._client = HttpClient(
+            base_url=effective_url,
+            timeout=float(self.settings.timeout),
+            retry_config=retry_config,
+        )
+        
+        logger.debug(
+            f"HttpAdapter {self.name} 初始化 HttpClient: "
+            f"url={effective_url}, timeout={self.settings.timeout}"
+        )
+    
+    async def _on_cleanup(self) -> None:
+        """清理 HttpClient。"""
+        if self._client and self._owns_client:
+            await self._client.close()
+            self._client = None
+            logger.debug(f"HttpAdapter {self.name} 关闭 HttpClient")
+    
+    # ========== 请求方法 ==========
+    
+    def _prepare_headers(self, extra: dict[str, str] | None = None) -> dict[str, str]:
+        """准备请求头。
+        
+        默认包含：
+        - Content-Type: application/json
+        - X-Trace-Id: 链路追踪 ID
+        - Authorization: Bearer {api_key}（如果配置了 api_key）
+        
+        子类可覆盖此方法添加自定义头（如签名）。
+        
+        Args:
+            extra: 额外的请求头
+            
+        Returns:
+            dict: 合并后的请求头
+        """
+        headers: dict[str, str] = {
+            "Content-Type": "application/json",
+            "X-Trace-Id": get_trace_id(),
+        }
+        
+        # 认证
+        if self.settings.api_key:
+            headers["Authorization"] = f"Bearer {self.settings.api_key}"
+        
+        # 合并额外头
+        if extra:
+            headers.update(extra)
+        
+        return headers
+    
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        headers: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        data: Any = None,
+        files: Any = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """发送 HTTP 请求。
+        
+        这是 HttpGateway 的核心方法，子类的 @operation 方法通常调用此方法。
+        
+        Args:
+            method: HTTP 方法（GET/POST/PUT/DELETE 等）
+            path: 请求路径（相对于 base_url）
+            headers: 额外请求头（会与默认头合并）
+            params: URL 查询参数
+            json: JSON 请求体
+            data: 表单数据
+            files: 上传文件
+            **kwargs: 其他 httpx 参数
+            
+        Returns:
+            dict: 响应 JSON
+            
+        Raises:
+            GatewayError: 请求失败
+            GatewayTimeoutError: 请求超时
+        """
+        if self._client is None:
+            # 尝试延迟初始化
+            await self.initialize()
+            if self._client is None:
+                raise AdapterError(
+                    f"HttpClient 未初始化，请检查 {self.name} 的 base_url 配置",
+                    adapter_name=self.name,
+                )
+        
+        merged_headers = self._prepare_headers(headers)
+        
+        try:
+            response = await self._client.request(
+                method=method,
+                url=path,
+                headers=merged_headers,
+                params=params,
+                json=json,
+                data=data,
+                files=files,
+                **kwargs,
+            )
+            
+            # 尝试解析 JSON
+            try:
+                return response.json()
+            except Exception:
+                # 非 JSON 响应，返回包装后的结果
+                return {
+                    "success": response.is_success,
+                    "status_code": response.status_code,
+                    "content": response.text,
+                }
+        
+        except httpx.TimeoutException as exc:
+            raise AdapterTimeoutError(
+                f"请求超时: {method} {path}",
+                adapter_name=self.name,
+                timeout_seconds=self.settings.timeout,
+                cause=exc,
+            ) from exc
+        
+        except httpx.HTTPStatusError as exc:
+            # HTTP 错误状态码
+            response = exc.response
+            try:
+                error_data = response.json()
+                third_party_code = error_data.get("code") or error_data.get("error_code")
+                third_party_message = error_data.get("message") or error_data.get("error")
+            except Exception:
+                third_party_code = None
+                third_party_message = response.text
+            
+            raise AdapterError(
+                f"HTTP 错误: {response.status_code} {method} {path}",
+                adapter_name=self.name,
+                third_party_code=third_party_code,
+                third_party_message=third_party_message,
+                cause=exc,
+            ) from exc
+        
+        except Exception as exc:
+            raise AdapterError(
+                f"请求失败: {method} {path} - {type(exc).__name__}: {exc}",
+                adapter_name=self.name,
+                cause=exc,
+            ) from exc
+    
+    # ========== 便捷方法 ==========
+    
+    async def _get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """GET 请求。"""
+        return await self._request("GET", path, params=params, headers=headers, **kwargs)
+    
+    async def _post(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        data: Any = None,
+        headers: dict[str, str] | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """POST 请求。"""
+        return await self._request("POST", path, json=json, data=data, headers=headers, **kwargs)
+    
+    async def _put(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        headers: dict[str, str] | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """PUT 请求。"""
+        return await self._request("PUT", path, json=json, headers=headers, **kwargs)
+    
+    async def _patch(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        headers: dict[str, str] | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """PATCH 请求。"""
+        return await self._request("PATCH", path, json=json, headers=headers, **kwargs)
+    
+    async def _delete(
+        self,
+        path: str,
+        *,
+        headers: dict[str, str] | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """DELETE 请求。"""
+        return await self._request("DELETE", path, headers=headers, **kwargs)
+
+
+__all__ = [
+    "HttpAdapter",
+]

aury/boot/application/app/__init__.py

@@ -8,6 +8,8 @@ from .components import (
     AdminConsoleComponent,
     CacheComponent,
     DatabaseComponent,
+    EventBusComponent,
+    MessageQueueComponent,
     MigrationComponent,
     SchedulerComponent,
     TaskComponent,
@@ -18,19 +20,21 @@ from .middlewares import (
 )
 
 __all__ = [
-    # 应用框架
-    "FoundationApp",
-    # 基类
-    "Component",
-    "Middleware",
-    # 中间件
-    "CORSMiddleware",
-    "RequestLoggingMiddleware",
     # 组件
     "AdminConsoleComponent",
+    # 中间件
+    "CORSMiddleware",
     "CacheComponent",
+    # 基类
+    "Component",
     "DatabaseComponent",
+    "EventBusComponent",
+    # 应用框架
+    "FoundationApp",
+    "MessageQueueComponent",
+    "Middleware",
     "MigrationComponent",
+    "RequestLoggingMiddleware",
     "SchedulerComponent",
     "TaskComponent",
 ]

aury/boot/application/app/base.py

@@ -349,6 +349,18 @@ class FoundationApp(FastAPI):
                     raise
 
             logger.info("应用启动完成")
+            
+            # 打印启动横幅和组件状态
+            from aury.boot.application.app.startup import (
+                collect_component_status,
+                print_startup_banner,
+            )
+            components = collect_component_status()
+            print_startup_banner(
+                app_name=self.title,
+                version=self.version,
+                components=components,
+            )
 
         except Exception as e:
             logger.error(f"应用启动异常: {e}")

aury/boot/application/app/components.py

@@ -16,6 +16,8 @@ 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.events import EventBusManager
+from aury.boot.infrastructure.mq import MQManager
 from aury.boot.infrastructure.scheduler import SchedulerManager
 from aury.boot.infrastructure.storage import StorageManager
 from aury.boot.infrastructure.tasks import TaskManager
@@ -74,12 +76,12 @@ class CacheComponent(Component):
         """初始化缓存。"""
         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,
-                })
+            if not cache_manager.is_initialized:
+                await cache_manager.initialize(
+                    backend=config.cache.cache_type,
+                    url=config.cache.url,
+                    max_size=config.cache.max_size,
+                )
         except Exception as e:
             logger.warning(f"缓存初始化失败（非关键）: {e}")
 
@@ -87,7 +89,7 @@ class CacheComponent(Component):
         """关闭缓存。"""
         try:
             cache_manager = CacheManager.get_instance()
-            if cache_manager._backend:
+            if cache_manager.is_initialized:
                 await cache_manager.cleanup()
         except Exception as e:
             logger.warning(f"缓存关闭失败: {e}")
@@ -95,53 +97,53 @@ class CacheComponent(Component):
 
 class StorageComponent(Component):
     """对象存储组件。
-
-设计要点（解耦）：
-- 使用 aury-sdk-storage 的 StorageConfig/StorageBackend，Application 层仅做装配
-- 建议由应用的 `StorageSettings` 读取环境变量并构造 SDK 的 StorageConfig
-"""
+    
+    支持多实例配置，通过环境变量 STORAGE_{INSTANCE}_{FIELD} 配置。
+    """
 
     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))
+        """当配置了 Storage 实例时启用。"""
+        return self.enabled and bool(config.get_storages())
 
     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}")
+        """初始化存储。"""
+        from aury.boot.infrastructure.storage import StorageBackend, StorageConfig
+        
+        storage_configs = config.get_storages()
+        if not storage_configs:
+            logger.debug("未配置 Storage 实例，跳过存储初始化")
+            return
+        
+        for name, st_config in storage_configs.items():
+            try:
+                storage_manager = StorageManager.get_instance(name)
+                if not storage_manager.is_initialized:
+                    storage_config = StorageConfig(
+                        backend=StorageBackend(st_config.backend),
+                        access_key_id=st_config.access_key_id,
+                        access_key_secret=st_config.access_key_secret,
+                        endpoint=st_config.endpoint,
+                        region=st_config.region,
+                        bucket_name=st_config.bucket_name,
+                        base_path=st_config.base_path,
+                    )
+                    await storage_manager.initialize(storage_config)
+            except Exception as e:
+                logger.warning(f"存储 [{name}] 初始化失败（非关键）: {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}")
+        """关闭所有存储实例。"""
+        for name in list(StorageManager._instances.keys()):
+            try:
+                storage_manager = StorageManager.get_instance(name)
+                if storage_manager.is_initialized:
+                    await storage_manager.cleanup()
+            except Exception as e:
+                logger.warning(f"存储 [{name}] 关闭失败: {e}")
 
 
 class TaskComponent(Component):
@@ -410,6 +412,93 @@ class AdminConsoleComponent(Component):
         pass
 
 
+class MessageQueueComponent(Component):
+    """消息队列组件。
+    
+    提供统一的消息队列接口，支持多种后端（Redis、RabbitMQ）。
+    与 TaskComponent（基于 Dramatiq）的区别：
+    - Task: 异步任务处理（API 发送，Worker 执行）
+    - MQ: 通用消息队列（生产者/消费者模式，服务间通信）
+    """
+
+    name = ComponentName.MESSAGE_QUEUE
+    enabled = True
+    depends_on: ClassVar[list[str]] = []
+
+    def can_enable(self, config: BaseConfig) -> bool:
+        """当配置了 MQ 实例时启用。"""
+        return self.enabled and bool(config.get_mqs())
+
+    async def setup(self, app: FoundationApp, config: BaseConfig) -> None:
+        """初始化消息队列。"""
+        from aury.boot.application.config import MQInstanceConfig
+        
+        # 从多实例配置加载
+        mq_configs = config.get_mqs()
+        if not mq_configs:
+            logger.debug("未配置 MQ 实例，跳过消息队列初始化")
+            return
+        
+        for name, mq_config in mq_configs.items():
+            try:
+                mq_manager = MQManager.get_instance(name)
+                if not mq_manager.is_initialized:
+                    await mq_manager.initialize(config=mq_config)
+            except Exception as e:
+                logger.warning(f"消息队列 [{name}] 初始化失败（非关键）: {e}")
+
+    async def teardown(self, app: FoundationApp) -> None:
+        """关闭所有消息队列实例。"""
+        for name in list(MQManager._instances.keys()):
+            try:
+                mq_manager = MQManager.get_instance(name)
+                if mq_manager.is_initialized:
+                    await mq_manager.cleanup()
+            except Exception as e:
+                logger.warning(f"消息队列 [{name}] 关闭失败: {e}")
+
+
+class EventBusComponent(Component):
+    """事件总线组件。
+    
+    提供发布/订阅模式的事件总线功能，支持多种后端（memory、Redis、RabbitMQ）。
+    """
+
+    name = ComponentName.EVENT_BUS
+    enabled = True
+    depends_on: ClassVar[list[str]] = []
+
+    def can_enable(self, config: BaseConfig) -> bool:
+        """当配置了 Event 实例时启用。"""
+        return self.enabled and bool(config.get_events())
+
+    async def setup(self, app: FoundationApp, config: BaseConfig) -> None:
+        """初始化事件总线。"""
+        # 从多实例配置加载
+        event_configs = config.get_events()
+        if not event_configs:
+            logger.debug("未配置 Event 实例，跳过事件总线初始化")
+            return
+        
+        for name, event_config in event_configs.items():
+            try:
+                event_manager = EventBusManager.get_instance(name)
+                if not event_manager.is_initialized:
+                    await event_manager.initialize(config=event_config)
+            except Exception as e:
+                logger.warning(f"事件总线 [{name}] 初始化失败（非关键）: {e}")
+
+    async def teardown(self, app: FoundationApp) -> None:
+        """关闭所有事件总线实例。"""
+        for name in list(EventBusManager._instances.keys()):
+            try:
+                event_manager = EventBusManager.get_instance(name)
+                if event_manager.is_initialized:
+                    await event_manager.cleanup()
+            except Exception as e:
+                logger.warning(f"事件总线 [{name}] 关闭失败: {e}")
+
+
 # 设置默认组件
 FoundationApp.components = [
     DatabaseComponent,
@@ -418,6 +507,8 @@ FoundationApp.components = [
     CacheComponent,
     StorageComponent,
     TaskComponent,
+    MessageQueueComponent,
+    EventBusComponent,
     SchedulerComponent,
 ]
 
@@ -426,6 +517,8 @@ __all__ = [
     "AdminConsoleComponent",
     "CacheComponent",
     "DatabaseComponent",
+    "EventBusComponent",
+    "MessageQueueComponent",
     "MigrationComponent",
     "SchedulerComponent",
     "StorageComponent",

aury/boot/application/app/middlewares.py

@@ -13,6 +13,8 @@ from aury.boot.application.config import BaseConfig
 from aury.boot.application.constants import MiddlewareName
 from aury.boot.application.middleware.logging import (
     RequestLoggingMiddleware as StarletteRequestLoggingMiddleware,
+)
+from aury.boot.application.middleware.logging import (
     WebSocketLoggingMiddleware as StarletteWebSocketLoggingMiddleware,
 )
 
@@ -28,14 +30,17 @@ class RequestLoggingMiddleware(Middleware):
 
     自动记录所有 HTTP 请求的详细信息，包括：
     - 请求方法、路径、查询参数
-    - 客户端 IP、User-Agent
+    - 客户端IP、User-Agent
     - 响应状态码、耗时
     - 链路追踪 ID（X-Trace-ID / X-Request-ID）
+    - 请求上下文（user_id, tenant_id 等用户注册的字段）
+    
+    注意：用户的认证中间件应设置 order < 100，以便在日志记录前设置用户信息。
     """
 
     name = MiddlewareName.REQUEST_LOGGING
     enabled = True
-    order = 0  # 最先执行，确保日志记录所有请求
+    order = 100  # 用户中间件可使用 0-99 在此之前执行
 
     def build(self, config: BaseConfig) -> StarletteMiddleware:
         """构建请求日志中间件实例。"""
@@ -54,7 +59,7 @@ class CORSMiddleware(Middleware):
 
     name = MiddlewareName.CORS
     enabled = True
-    order = 10  # 在请求日志之后执行
+    order = 110  # 在日志中间件之后执行
 
     def can_enable(self, config: BaseConfig) -> bool:
         """仅当配置了 origins 时启用。"""
@@ -83,7 +88,7 @@ class WebSocketLoggingMiddleware(Middleware):
 
     name = MiddlewareName.WEBSOCKET_LOGGING
     enabled = True
-    order = 1  # 紧随 HTTP 日志中间件
+    order = 101  # 紧随 HTTP 日志中间件
 
     def build(self, config: BaseConfig) -> StarletteMiddleware:
         """构建 WebSocket 日志中间件实例。"""