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

aury/boot/application/adapter/config.py

@@ -0,0 +1,242 @@
+"""第三方接口适配器配置模型。
+
+提供统一的配置结构，支持：
+- 多模式切换（real/sandbox/mock/disabled）
+- 按方法级别的模式覆盖
+- 通用连接参数（URL、认证、超时等）
+- 挡板（Mock）策略配置
+
+模式说明:
+- real: 调用真实第三方接口（生产环境）
+- sandbox: 调用第三方提供的沙箱环境
+- mock: 使用本地挡板实现，不发出真实请求（测试/开发环境）
+- disabled: 禁用该接口，调用时抛出 AdapterDisabledError
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+# 适配器模式类型
+# - real: 真实调用第三方接口
+# - sandbox: 调用第三方沙箱环境
+# - mock: 使用本地挡板实现
+# - disabled: 禁用，调用时抛出异常
+AdapterMode = Literal["real", "sandbox", "mock", "disabled"]
+
+# 挡板（Mock）策略类型
+# - success: 返回成功响应
+# - failure: 返回失败响应
+# - echo: 回显请求参数
+# - noop: 空操作，返回空结果
+# - custom: 自定义，使用 @method.mock 定义的处理函数
+MockStrategy = Literal["success", "failure", "echo", "noop", "custom"]
+
+
+class AdapterSettings(BaseModel):
+    """第三方接口适配器配置。
+    
+    通用的第三方服务配置模型，支持多模式切换和按方法覆盖。
+    
+    配置项分类:
+    1. 基础配置: enabled, mode
+    2. 连接配置: base_url, sandbox_url, api_key, api_secret, timeout, retry_times
+    3. 模式覆盖: method_modes - 按方法名覆盖全局模式
+    4. 挡板配置: mock_strategy, mock_default_response, mock_delay, mock_method_responses
+    
+    环境变量配置示例:
+        # 基础配置
+        THIRD_PARTY_PAYMENT_ENABLED=true
+        THIRD_PARTY_PAYMENT_MODE=mock          # 测试环境用挡板
+        
+        # 连接配置
+        THIRD_PARTY_PAYMENT_BASE_URL=https://api.payment.com
+        THIRD_PARTY_PAYMENT_SANDBOX_URL=https://sandbox.payment.com
+        THIRD_PARTY_PAYMENT_API_KEY=sk_live_xxx
+        THIRD_PARTY_PAYMENT_TIMEOUT=30
+        
+        # 方法级模式覆盖（JSON 格式）
+        # query 走真实接口，refund 禁用
+        THIRD_PARTY_PAYMENT_METHOD_MODES={"query": "real", "refund": "disabled"}
+        
+        # 挡板配置
+        THIRD_PARTY_PAYMENT_MOCK_DELAY=0.1     # 模拟网络延迟 100ms
+    """
+    
+    # ========== 基础配置 ==========
+    enabled: bool = Field(
+        default=True,
+        description="是否启用此集成",
+    )
+    mode: AdapterMode = Field(
+        default="real",
+        description="当前模式：real(生产)/sandbox(沙箱)/mock(挡板)/disabled(禁用)",
+    )
+    
+    # ========== 连接配置 ==========
+    base_url: str | None = Field(
+        default=None,
+        description="服务基础 URL（生产环境）",
+    )
+    sandbox_url: str | None = Field(
+        default=None,
+        description="沙箱环境 URL（sandbox 模式时优先使用）",
+    )
+    api_key: str | None = Field(
+        default=None,
+        description="API 密钥（如 Authorization header）",
+    )
+    api_secret: str | None = Field(
+        default=None,
+        description="API 密钥（用于签名等）",
+    )
+    timeout: int = Field(
+        default=30,
+        description="请求超时（秒）",
+    )
+    retry_times: int = Field(
+        default=3,
+        description="重试次数",
+    )
+    
+    # ========== 模式覆盖 ==========
+    method_modes: dict[str, AdapterMode] = Field(
+        default_factory=dict,
+        description="按方法覆盖模式，如 {'refund': 'disabled', 'query': 'real'}",
+    )
+    
+    # ========== Mock 配置 ==========
+    mock_strategy: MockStrategy = Field(
+        default="success",
+        description="默认 mock 策略：success(成功)/failure(失败)/echo(回显)/noop(空操作)/custom(自定义)",
+    )
+    mock_default_response: dict[str, Any] | None = Field(
+        default=None,
+        description="默认 mock 响应（当没有自定义 mock handler 时使用）",
+    )
+    mock_delay: float = Field(
+        default=0.0,
+        description="mock 模拟延迟（秒），用于模拟网络延迟",
+    )
+    mock_method_responses: dict[str, dict[str, Any]] = Field(
+        default_factory=dict,
+        description="按方法的 mock 响应，如 {'create': {'success': True, 'id': 'mock-123'}}",
+    )
+    
+    # ========== 扩展配置 ==========
+    extra: dict[str, Any] = Field(
+        default_factory=dict,
+        description="额外配置（供子类或特定第三方使用）",
+    )
+    
+    def get_effective_url(self) -> str | None:
+        """获取当前模式下的有效 URL。
+        
+        sandbox 模式优先使用 sandbox_url，否则使用 base_url。
+        """
+        if self.mode == "sandbox" and self.sandbox_url:
+            return self.sandbox_url
+        return self.base_url
+    
+    def get_method_mode(self, method_name: str) -> AdapterMode:
+        """获取指定方法的有效模式。
+        
+        优先使用 method_modes 中的配置，否则使用全局 mode。
+        
+        Args:
+            method_name: 方法名称
+            
+        Returns:
+            AdapterMode: 有效模式
+        """
+        return self.method_modes.get(method_name, self.mode)
+    
+    def is_method_enabled(self, method_name: str) -> bool:
+        """检查指定方法是否启用。
+        
+        Args:
+            method_name: 方法名称
+            
+        Returns:
+            bool: 是否启用
+        """
+        if not self.enabled:
+            return False
+        return self.get_method_mode(method_name) != "disabled"
+    
+    def get_mock_response(self, method_name: str) -> dict[str, Any] | None:
+        """获取指定方法的 mock 响应。
+        
+        优先使用 mock_method_responses，否则使用 mock_default_response。
+        
+        Args:
+            method_name: 方法名称
+            
+        Returns:
+            dict | None: mock 响应
+        """
+        return self.mock_method_responses.get(method_name, self.mock_default_response)
+
+
+class ThirdPartySettings(BaseSettings):
+    """第三方服务配置聚合。
+    
+    将所有第三方服务的配置聚合到一个类中，便于统一管理。
+    项目可以继承此类添加更多第三方服务。
+    
+    环境变量前缀: THIRD_PARTY_
+    
+    使用示例:
+        class MyThirdPartySettings(ThirdPartySettings):
+            wechat: AdapterSettings = Field(default_factory=AdapterSettings)
+            alipay: AdapterSettings = Field(default_factory=AdapterSettings)
+        
+        # 环境变量
+        THIRD_PARTY_WECHAT_MODE=sandbox
+        THIRD_PARTY_ALIPAY_MODE=mock
+    """
+    
+    # 示例：常见第三方服务（项目可以继承并添加）
+    # payment: AdapterSettings = Field(default_factory=AdapterSettings)
+    # sms: AdapterSettings = Field(default_factory=AdapterSettings)
+    # oss: AdapterSettings = Field(default_factory=AdapterSettings)
+    # email: AdapterSettings = Field(default_factory=AdapterSettings)
+    
+    model_config = SettingsConfigDict(
+        env_prefix="THIRD_PARTY_",
+        env_nested_delimiter="__",
+        case_sensitive=False,
+        extra="ignore",
+    )
+    
+    def set_all_mode(self, mode: AdapterMode) -> None:
+        """将所有第三方服务设置为指定模式。
+        
+        便捷方法，用于测试环境一键切换所有服务到 mock 模式。
+        
+        Args:
+            mode: 目标模式
+        """
+        for field_name in self.model_fields:
+            field_value = getattr(self, field_name, None)
+            if isinstance(field_value, AdapterSettings):
+                field_value.mode = mode
+    
+    def disable_all(self) -> None:
+        """禁用所有第三方服务。"""
+        self.set_all_mode("disabled")
+    
+    def mock_all(self) -> None:
+        """将所有第三方服务设置为 mock 模式。"""
+        self.set_all_mode("mock")
+
+
+__all__ = [
+    "AdapterMode",
+    "AdapterSettings",
+    "MockStrategy",
+    "ThirdPartySettings",
+]

aury/boot/application/adapter/decorators.py

@@ -0,0 +1,259 @@
+"""第三方接口适配器装饰器。
+
+提供 @adapter_method 装饰器，用于声明式定义 Adapter 方法和挡板（Mock）逻辑。
+
+核心特性：
+- 声明方法名称，用于配置层按方法覆盖模式（method_modes）
+- 支持链式 .mock 注册挡板处理函数
+- 自动根据 settings.mode 路由到真实调用或挡板逻辑
+- 记录调用历史，便于测试断言
+
+挡板定义方式：
+1. @method.mock 装饰器：定义带逻辑的挡板函数，可以根据参数返回不同结果
+2. mock_response 参数：简单场景直接指定固定响应值
+3. 配置 mock_method_responses：按方法名配置固定响应
+4. 配置 mock_default_response：全局默认响应
+
+使用示例:
+    class PaymentAdapter(HttpAdapter):
+        # 方法 1：使用 @method.mock 定义挡板逻辑
+        @adapter_method("create")
+        async def create_order(self, amount: int, order_id: str) -> dict:
+            # 真实调用逻辑
+            return await self._request("POST", "/charge", json={...})
+        
+        @create_order.mock
+        async def create_order_mock(self, amount: int, order_id: str) -> dict:
+            # 挡板逻辑，可以模拟各种场景
+            if amount > 10000:
+                return {"success": False, "error": "金额超限"}  # 模拟失败
+            return {"success": True, "mock": True}  # 模拟成功
+        
+        # 方法 2：简单场景直接指定固定响应
+        @adapter_method("query", mock_response={"status": "paid", "mock": True})
+        async def query_order(self, order_id: str) -> dict:
+            return await self._request("GET", f"/orders/{order_id}")
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, TypeVar
+
+from aury.boot.common.logging import logger
+
+from .config import AdapterMode
+from .exceptions import AdapterDisabledError
+
+if TYPE_CHECKING:
+    from .base import BaseAdapter
+
+T = TypeVar("T")
+F = TypeVar("F", bound=Callable[..., Awaitable[Any]])
+
+
+@dataclass
+class AdapterMethodMeta:
+    """适配器方法元信息。
+    
+    存储 @adapter_method 装饰器声明的信息，包括：
+    - 方法名称
+    - mock 处理函数
+    - 固定 mock 响应
+    - 模式覆盖
+    """
+    
+    name: str
+    mock_handler: Callable[..., Awaitable[Any]] | None = None
+    mock_response: Any = None
+    mode_override: AdapterMode | None = None
+    
+    # 内部使用：原始真实方法
+    _real_method: Callable[..., Awaitable[Any]] | None = field(default=None, repr=False)
+
+
+class AdapterMethodDescriptor:
+    """适配器方法描述符。
+    
+    实现类似 @property 的描述符协议，支持链式 .mock 注册。
+    
+    使用示例:
+        class PaymentAdapter(HttpAdapter):
+            @adapter_method("create")
+            async def create_order(self, ...): ...
+            
+            @create_order.mock
+            async def create_order_mock(self, ...): ...
+    """
+    
+    def __init__(
+        self,
+        real_method: Callable[..., Awaitable[Any]],
+        meta: AdapterMethodMeta,
+    ) -> None:
+        """初始化描述符。
+        
+        Args:
+            real_method: 真实调用方法
+            meta: 方法元信息
+        """
+        self._real_method = real_method
+        self._meta = meta
+        self._meta._real_method = real_method
+        
+        # 复制原方法的文档和名称
+        self.__name__ = real_method.__name__
+        self.__doc__ = real_method.__doc__
+        self.__module__ = real_method.__module__
+        self.__qualname__ = getattr(real_method, "__qualname__", real_method.__name__)
+    
+    def __get__(self, obj: BaseAdapter | None, objtype: type | None = None) -> Any:
+        """描述符协议：获取绑定方法。"""
+        if obj is None:
+            # 类访问，返回描述符本身（用于 .mock 链式调用）
+            return self
+        
+        # 实例访问，返回包装后的绑定方法
+        return self._create_bound_method(obj)
+    
+    def __set_name__(self, owner: type, name: str) -> None:
+        """描述符协议：设置属性名。"""
+        self._attr_name = name
+    
+    def _create_bound_method(self, adapter: BaseAdapter) -> Callable[..., Awaitable[Any]]:
+        """创建绑定到实例的方法。"""
+        meta = self._meta
+        real_method = self._real_method
+        
+        @wraps(real_method)
+        async def bound_method(*args: Any, **kwargs: Any) -> Any:
+            # 解析当前操作的有效模式
+            mode = adapter._resolve_mode(meta)
+            
+            # 记录调用
+            adapter._record_call(
+                operation=meta.name,
+                args=args,
+                kwargs=kwargs,
+                mode=mode,
+            )
+            
+            # 检查是否禁用
+            if not adapter.settings.enabled or mode == "disabled":
+                raise AdapterDisabledError(
+                    f"{adapter.name}.{meta.name} is disabled in current environment",
+                    adapter_name=adapter.name,
+                    operation=meta.name,
+                )
+            
+            # mock 模式
+            if mode == "mock":
+                return await adapter._invoke_mock(meta, args, kwargs)
+            
+            # real / sandbox 模式：调用原始方法
+            # 触发钩子
+            await adapter._on_before_call(meta.name, args, kwargs)
+            
+            try:
+                result = await real_method(adapter, *args, **kwargs)
+                await adapter._on_after_call(meta.name, args, kwargs, result)
+                return result
+            except Exception as exc:
+                await adapter._on_call_error(meta.name, args, kwargs, exc)
+                raise
+        
+        return bound_method
+    
+    def mock(self, mock_method: F) -> F:
+        """注册 mock 处理函数（链式装饰器）。
+        
+        使用示例:
+            @adapter_method("create")
+            async def create_order(self, ...): ...
+            
+            @create_order.mock
+            async def create_order_mock(self, ...): ...
+        
+        Args:
+            mock_method: mock 处理函数
+            
+        Returns:
+            原始 mock 方法（保持可调用）
+        """
+        self._meta.mock_handler = mock_method
+        logger.debug(f"Adapter 注册 mock handler: {self.__name__} -> {mock_method.__name__}")
+        
+        # 返回原方法，使其可以作为独立方法调用（如果需要）
+        return mock_method
+
+
+def adapter_method(
+    name: str,
+    *,
+    mock_response: Any = None,
+    mode_override: AdapterMode | None = None,
+) -> Callable[[F], AdapterMethodDescriptor]:
+    """适配器方法装饰器。
+    
+    声明一个 Adapter 方法，支持：
+    - 根据配置自动切换 real/mock 模式
+    - 链式 .mock 注册 mock 处理函数
+    - 调用历史记录
+    
+    Args:
+        name: 方法名称，用于配置层按方法覆盖模式
+        mock_response: 简单 mock 场景的固定响应（可选）
+        mode_override: 强制覆盖模式，不走配置（可选，用于某些方法必须真实调用的场景）
+    
+    使用示例:
+        # 基础用法
+        @adapter_method("create")
+        async def create_order(self, amount: int) -> dict:
+            return await self._request("POST", "/charge", json={"amount": amount})
+        
+        # 带固定 mock 响应
+        @adapter_method("query", mock_response={"status": "paid", "mock": True})
+        async def query_order(self, order_id: str) -> dict:
+            return await self._request("GET", f"/orders/{order_id}")
+        
+        # 强制走真实（无论配置如何）
+        @adapter_method("health", mode_override="real")
+        async def health_check(self) -> dict:
+            return await self._request("GET", "/health")
+        
+        # 链式 mock
+        @adapter_method("create")
+        async def create_order(self, amount: int) -> dict:
+            return await self._request("POST", "/charge", json={"amount": amount})
+        
+        @create_order.mock
+        async def create_order_mock(self, amount: int) -> dict:
+            if amount > 10000:
+                return {"success": False, "error": "超限"}
+            return {"success": True, "mock": True, "amount": amount}
+    
+    Returns:
+        装饰器函数
+    """
+    def decorator(fn: F) -> AdapterMethodDescriptor:
+        meta = AdapterMethodMeta(
+            name=name,
+            mock_response=mock_response,
+            mode_override=mode_override,
+        )
+        
+        descriptor = AdapterMethodDescriptor(fn, meta)
+        logger.debug(f"Adapter 注册方法: {fn.__name__} -> {name}")
+        
+        return descriptor
+    
+    return decorator
+
+
+__all__ = [
+    "AdapterMethodDescriptor",
+    "AdapterMethodMeta",
+    "adapter_method",
+]

aury/boot/application/adapter/exceptions.py

@@ -0,0 +1,202 @@
+"""第三方接口适配器异常定义。
+
+用于第三方接口调用过程中的各类异常场景，所有异常都继承自 FoundationError。
+
+异常类型：
+- AdapterError: 通用错误（调用失败、第三方返回错误码等）
+- AdapterDisabledError: 接口被禁用（mode=disabled 或 enabled=False）
+- AdapterTimeoutError: 调用超时
+- AdapterValidationError: 响应数据格式验证失败
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from aury.boot.common.exceptions import FoundationError
+
+
+class AdapterError(FoundationError):
+    """第三方适配器通用错误。
+    
+    当第三方调用失败、返回错误码、数据解析异常等情况时抛出。
+    
+    Attributes:
+        adapter_name: 适配器名称
+        operation: 操作名称
+        third_party_code: 第三方返回的错误码（如有）
+        third_party_message: 第三方返回的错误消息（如有）
+    
+    使用示例:
+        raise AdapterError(
+            "支付失败",
+            adapter_name="payment",
+            operation="charge",
+            third_party_code="INSUFFICIENT_FUNDS",
+            third_party_message="余额不足",
+        )
+    """
+    
+    def __init__(
+        self,
+        message: str,
+        *args: object,
+        adapter_name: str | None = None,
+        operation: str | None = None,
+        third_party_code: str | None = None,
+        third_party_message: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        cause: Exception | None = None,
+    ) -> None:
+        """初始化集成异常。
+        
+        Args:
+            message: 错误消息
+            adapter_name: 适配器名称
+            operation: 操作名称
+            third_party_code: 第三方错误码
+            third_party_message: 第三方错误消息
+            metadata: 额外元数据
+            cause: 原始异常
+        """
+        self.adapter_name = adapter_name
+        self.operation = operation
+        self.third_party_code = third_party_code
+        self.third_party_message = third_party_message
+        
+        # 构建完整的元数据
+        full_metadata = metadata or {}
+        if adapter_name:
+            full_metadata["adapter_name"] = adapter_name
+        if operation:
+            full_metadata["operation"] = operation
+        if third_party_code:
+            full_metadata["third_party_code"] = third_party_code
+        if third_party_message:
+            full_metadata["third_party_message"] = third_party_message
+        
+        super().__init__(message, *args, metadata=full_metadata, cause=cause)
+    
+    def __str__(self) -> str:
+        """返回异常字符串表示。"""
+        parts = [self.message]
+        if self.adapter_name:
+            parts.append(f"adapter={self.adapter_name}")
+        if self.operation:
+            parts.append(f"operation={self.operation}")
+        if self.third_party_code:
+            parts.append(f"code={self.third_party_code}")
+        return " | ".join(parts)
+
+
+class AdapterDisabledError(AdapterError):
+    """当前环境禁用了某个第三方功能。
+    
+    当 mode=disabled 或 enabled=False 时，调用任何操作都会抛出此异常。
+    
+    使用示例:
+        # 在测试环境禁用支付功能
+        settings = AdapterSettings(mode="disabled")
+        adapter = PaymentAdapter("payment", settings)
+        
+        await adapter.charge(100)  # 抛出 AdapterDisabledError
+    """
+    
+    def __init__(
+        self,
+        message: str,
+        *args: object,
+        adapter_name: str | None = None,
+        operation: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """初始化禁用异常。"""
+        super().__init__(
+            message,
+            *args,
+            adapter_name=adapter_name,
+            operation=operation,
+            metadata=metadata,
+        )
+
+
+class AdapterTimeoutError(AdapterError):
+    """第三方调用超时。
+    
+    当调用第三方接口超过配置的超时时间时抛出。
+    
+    Attributes:
+        timeout_seconds: 超时时间（秒）
+    """
+    
+    def __init__(
+        self,
+        message: str,
+        *args: object,
+        adapter_name: str | None = None,
+        operation: str | None = None,
+        timeout_seconds: float | None = None,
+        metadata: dict[str, Any] | None = None,
+        cause: Exception | None = None,
+    ) -> None:
+        """初始化超时异常。"""
+        self.timeout_seconds = timeout_seconds
+        
+        full_metadata = metadata or {}
+        if timeout_seconds is not None:
+            full_metadata["timeout_seconds"] = timeout_seconds
+        
+        super().__init__(
+            message,
+            *args,
+            adapter_name=adapter_name,
+            operation=operation,
+            metadata=full_metadata,
+            cause=cause,
+        )
+
+
+class AdapterValidationError(AdapterError):
+    """第三方响应数据验证失败。
+    
+    当第三方返回的数据格式不符合预期时抛出。
+    """
+    
+    def __init__(
+        self,
+        message: str,
+        *args: object,
+        adapter_name: str | None = None,
+        operation: str | None = None,
+        expected_format: str | None = None,
+        actual_data: Any | None = None,
+        metadata: dict[str, Any] | None = None,
+        cause: Exception | None = None,
+    ) -> None:
+        """初始化验证异常。"""
+        full_metadata = metadata or {}
+        if expected_format:
+            full_metadata["expected_format"] = expected_format
+        if actual_data is not None:
+            # 截断过长的数据
+            actual_str = str(actual_data)
+            if len(actual_str) > 200:
+                actual_str = actual_str[:200] + "..."
+            full_metadata["actual_data"] = actual_str
+        
+        super().__init__(
+            message,
+            *args,
+            adapter_name=adapter_name,
+            operation=operation,
+            metadata=full_metadata,
+            cause=cause,
+        )
+
+
+__all__ = [
+    "AdapterError",
+    "AdapterDisabledError",
+    "AdapterTimeoutError",
+    "AdapterValidationError",
+]