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

aury/boot/testing/client.py

@@ -0,0 +1,163 @@
+"""测试客户端。
+
+封装 FastAPI TestClient，提供便捷的测试接口。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient as FastAPITestClient
+from httpx import Response
+
+from aury.boot.common.logging import logger
+
+
+class TestClient:
+    """测试客户端。
+    
+    封装 FastAPI TestClient，提供便捷的测试接口。
+    
+    使用示例:
+        app = FastAPI()
+        client = TestClient(app)
+        
+        # GET 请求
+        response = await client.get("/users", headers={"Authorization": "Bearer token"})
+        assert response.status_code == 200
+        
+        # POST 请求
+        response = await client.post("/users", json={"name": "张三"})
+        assert response.status_code == 201
+        assert response.json()["name"] == "张三"
+    """
+    
+    def __init__(
+        self,
+        app: FastAPI,
+        base_url: str = "http://test",
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        """初始化测试客户端。
+        
+        Args:
+            app: FastAPI 应用实例
+            base_url: 基础URL（默认 "http://test"）
+            headers: 默认请求头
+        """
+        self._client = FastAPITestClient(app, base_url=base_url)
+        self._default_headers = headers or {}
+        logger.debug("测试客户端已创建")
+    
+    def _prepare_headers(self, headers: dict[str, str] | None = None) -> dict[str, str]:
+        """准备请求头。
+        
+        Args:
+            headers: 额外的请求头
+            
+        Returns:
+            dict[str, str]: 合并后的请求头
+        """
+        merged_headers = self._default_headers.copy()
+        if headers:
+            merged_headers.update(headers)
+        return merged_headers
+    
+    def get(
+        self,
+        url: str,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Response:
+        """发送 GET 请求。
+        
+        Args:
+            url: 请求URL
+            params: URL参数
+            headers: 请求头
+            
+        Returns:
+            Response: HTTP响应
+        """
+        logger.debug(f"GET {url}")
+        return self._client.get(url, params=params, headers=self._prepare_headers(headers))
+    
+    def post(
+        self,
+        url: str,
+        json: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Response:
+        """发送 POST 请求。
+        
+        Args:
+            url: 请求URL
+            json: JSON数据
+            data: 表单数据
+            headers: 请求头
+            
+        Returns:
+            Response: HTTP响应
+        """
+        logger.debug(f"POST {url}")
+        if json:
+            return self._client.post(url, json=json, headers=self._prepare_headers(headers))
+        else:
+            return self._client.post(url, data=data, headers=self._prepare_headers(headers))
+    
+    def put(
+        self,
+        url: str,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Response:
+        """发送 PUT 请求。
+        
+        Args:
+            url: 请求URL
+            json: JSON数据
+            headers: 请求头
+            
+        Returns:
+            Response: HTTP响应
+        """
+        logger.debug(f"PUT {url}")
+        return self._client.put(url, json=json, headers=self._prepare_headers(headers))
+    
+    def delete(
+        self,
+        url: str,
+        headers: dict[str, str] | None = None,
+    ) -> Response:
+        """发送 DELETE 请求。
+        
+        Args:
+            url: 请求URL
+            headers: 请求头
+            
+        Returns:
+            Response: HTTP响应
+        """
+        logger.debug(f"DELETE {url}")
+        return self._client.delete(url, headers=self._prepare_headers(headers))
+    
+    def patch(
+        self,
+        url: str,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Response:
+        """发送 PATCH 请求。
+        
+        Args:
+            url: 请求URL
+            json: JSON数据
+            headers: 请求头
+            
+        Returns:
+            Response: HTTP响应
+        """
+        logger.debug(f"PATCH {url}")
+        return self._client.patch(url, json=json, headers=self._prepare_headers(headers))

aury/boot/testing/factory.py

@@ -0,0 +1,154 @@
+"""测试数据工厂。
+
+提供便捷的测试数据生成工具，类似 Django 的 Factory。
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+from faker import Faker
+
+from aury.boot.common.logging import logger
+from aury.boot.domain.models import Base
+
+ModelType = TypeVar("ModelType", bound=Base)
+
+# 全局 Faker 实例
+_faker = Faker(["zh_CN", "en_US"])
+
+
+class Factory:
+    """测试数据工厂。
+    
+    提供便捷的测试数据生成工具。
+    
+    使用示例:
+        # 创建工厂
+        user_factory = Factory(User)
+        
+        # 创建单个实例
+        user = await user_factory.create(name="张三", email="zhangsan@example.com")
+        
+        # 创建多个实例
+        users = await user_factory.create_batch(5, name="批量用户")
+        
+        # 使用 Faker 生成随机数据
+        user = await user_factory.create()  # 使用默认值或随机生成
+    """
+    
+    def __init__(self, model_class: type[ModelType], **defaults: Any) -> None:
+        """初始化工厂。
+        
+        Args:
+            model_class: 模型类
+            **defaults: 默认属性值
+        """
+        self._model_class = model_class
+        self._defaults = defaults
+        logger.debug(f"创建工厂: {model_class.__name__}")
+    
+    def _generate_field_value(self, field_name: str, field_type: Any) -> Any:
+        """生成字段值。
+        
+        Args:
+            field_name: 字段名
+            field_type: 字段类型
+            
+        Returns:
+            Any: 生成的字段值
+        """
+        # 根据字段名和类型生成合适的值
+        if "email" in field_name.lower():
+            return _faker.email()
+        elif "name" in field_name.lower() or "username" in field_name.lower():
+            return _faker.name()
+        elif "phone" in field_name.lower() or "mobile" in field_name.lower():
+            return _faker.phone_number()
+        elif "address" in field_name.lower():
+            return _faker.address()
+        elif "url" in field_name.lower():
+            return _faker.url()
+        elif "text" in field_name.lower() or "content" in field_name.lower():
+            return _faker.text()
+        elif "date" in field_name.lower() or "time" in field_name.lower():
+            return _faker.date_time()
+        elif "int" in str(field_type).lower() or "integer" in str(field_type).lower():
+            return _faker.random_int()
+        elif "float" in str(field_type).lower():
+            return _faker.pyfloat()
+        elif "bool" in str(field_type).lower() or "boolean" in str(field_type).lower():
+            return _faker.boolean()
+        else:
+            return _faker.word()
+    
+    def _build_attributes(self, **overrides: Any) -> dict[str, Any]:
+        """构建属性字典。
+        
+        Args:
+            **overrides: 覆盖的属性值
+            
+        Returns:
+            dict[str, Any]: 属性字典
+        """
+        attrs = self._defaults.copy()
+        
+        # 如果模型有字段定义，尝试生成缺失的字段
+        if hasattr(self._model_class, "__table__"):
+            table = self._model_class.__table__
+            for column in table.columns:
+                if column.name not in attrs and column.name not in overrides:
+                    # 跳过主键和自动生成的字段
+                    if column.primary_key or column.server_default:
+                        continue
+                    # 尝试生成值
+                    attrs[column.name] = self._generate_field_value(column.name, column.type)
+        
+        # 应用覆盖值
+        attrs.update(overrides)
+        return attrs
+    
+    async def create(self, **kwargs: Any) -> ModelType:
+        """创建单个实例。
+        
+        Args:
+            **kwargs: 属性值（覆盖默认值）
+            
+        Returns:
+            ModelType: 创建的模型实例
+        """
+        attrs = self._build_attributes(**kwargs)
+        instance = self._model_class(**attrs)
+        logger.debug(f"创建测试数据: {self._model_class.__name__}")
+        return instance
+    
+    async def create_batch(self, size: int, **kwargs: Any) -> list[ModelType]:
+        """批量创建实例。
+        
+        Args:
+            size: 创建数量
+            **kwargs: 属性值（覆盖默认值）
+            
+        Returns:
+            list[ModelType]: 创建的模型实例列表
+        """
+        instances = []
+        for _ in range(size):
+            instance = await self.create(**kwargs)
+            instances.append(instance)
+        logger.debug(f"批量创建 {size} 个测试数据: {self._model_class.__name__}")
+        return instances
+    
+    def build(self, **kwargs: Any) -> ModelType:
+        """构建实例（不保存到数据库）。
+        
+        Args:
+            **kwargs: 属性值（覆盖默认值）
+            
+        Returns:
+            ModelType: 构建的模型实例
+        """
+        attrs = self._build_attributes(**kwargs)
+        instance = self._model_class(**attrs)
+        logger.debug(f"构建测试数据（未保存）: {self._model_class.__name__}")
+        return instance

aury/boot/toolkit/__init__.py

@@ -0,0 +1,21 @@
+"""工具包模块。
+
+提供各种实用工具，如 HTTP 客户端等。
+"""
+
+from .http import (
+    HttpClient,
+    HttpClientConfig,
+    LoggingInterceptor,
+    RequestInterceptor,
+    RetryConfig,
+)
+
+__all__ = [
+    "HttpClient",
+    "HttpClientConfig",
+    "LoggingInterceptor",
+    "RequestInterceptor",
+    "RetryConfig",
+]
+

aury/boot/toolkit/http/__init__.py

@@ -0,0 +1,367 @@
+"""HTTP客户端 - 企业级HTTP请求工具。
+
+特性：
+- 连接池管理
+- 自动重试机制（使用tenacity）
+- 请求/响应拦截器
+- 超时控制
+- 错误处理
+- 请求日志
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Optional, TypeVar
+
+import httpx
+from pydantic import BaseModel
+from tenacity import (
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from aury.boot.common.logging import logger
+
+T = TypeVar("T")
+
+
+class RetryConfig(BaseModel):
+    """重试配置（Pydantic）。"""
+    
+    max_retries: int = 3
+    retry_delay: float = 1.0
+    backoff_factor: float = 2.0
+    retry_on_status: list[int] = [500, 502, 503, 504]
+    retry_on_exceptions: tuple = (httpx.TimeoutException, httpx.NetworkError)
+
+
+class HttpClientConfig(BaseModel):
+    """HTTP客户端配置（Pydantic）。"""
+    
+    base_url: str = ""
+    timeout: float = 30.0
+    follow_redirects: bool = True
+    max_connections: int = 100
+    max_keepalive_connections: int = 20
+    keepalive_expiry: float = 5.0
+    retry: RetryConfig | None = None
+
+
+class RequestInterceptor(ABC):
+    """请求拦截器接口。"""
+    
+    @abstractmethod
+    async def before_request(self, request: httpx.Request) -> httpx.Request:
+        """请求前处理。"""
+        pass
+    
+    @abstractmethod
+    async def after_response(self, response: httpx.Response) -> httpx.Response:
+        """响应后处理。"""
+        pass
+
+
+class LoggingInterceptor(RequestInterceptor):
+    """日志拦截器。"""
+    
+    async def before_request(self, request: httpx.Request) -> httpx.Request:
+        """记录请求日志。"""
+        logger.debug(
+            f"HTTP请求: {request.method} {request.url} | "
+            f"Headers: {dict(request.headers)}"
+        )
+        return request
+    
+    async def after_response(self, response: httpx.Response) -> httpx.Response:
+        """记录响应日志。"""
+        logger.debug(
+            f"HTTP响应: {response.status_code} {response.url} | "
+            f"耗时: {response.elapsed.total_seconds():.3f}s"
+        )
+        return response
+
+
+class HttpClient:
+    """企业级HTTP客户端。
+    
+    特性：
+    - 连接池管理
+    - 自动重试（使用tenacity）
+    - 拦截器支持
+    - 超时控制
+    - 错误处理
+    
+    使用示例:
+        # 基础使用
+        client = HttpClient(base_url="https://api.example.com")
+        response = await client.get("/users")
+        
+        # 带重试
+        config = HttpClientConfig(
+            base_url="https://api.example.com",
+            retry=RetryConfig(max_retries=3)
+        )
+        client = HttpClient.from_config(config)
+        response = await client.get("/users")
+        
+        # 添加拦截器
+        client.add_interceptor(LoggingInterceptor())
+    """
+    
+    def __init__(
+        self,
+        base_url: str = "",
+        *,
+        timeout: float = 30.0,
+        follow_redirects: bool = True,
+        max_connections: int = 100,
+        retry_config: RetryConfig | None = None,
+    ) -> None:
+        """初始化HTTP客户端。
+        
+        Args:
+            base_url: 基础URL
+            timeout: 超时时间（秒）
+            follow_redirects: 是否跟随重定向
+            max_connections: 最大连接数
+            retry_config: 重试配置
+        """
+        self._base_url = base_url
+        self._timeout = timeout
+        self._follow_redirects = follow_redirects
+        self._max_connections = max_connections
+        self._retry_config = retry_config or RetryConfig()
+        self._interceptors: list[RequestInterceptor] = []
+        
+        # 创建HTTP客户端（使用连接池）
+        limits = httpx.Limits(
+            max_connections=max_connections,
+            max_keepalive_connections=20,
+            keepalive_expiry=5.0,
+        )
+        
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            timeout=timeout,
+            follow_redirects=follow_redirects,
+            limits=limits,
+        )
+        
+        logger.debug(f"HTTP客户端初始化: base_url={base_url}, timeout={timeout}")
+    
+    @classmethod
+    def from_config(cls, config: HttpClientConfig) -> HttpClient:
+        """从配置创建客户端。
+        
+        Args:
+            config: 客户端配置
+            
+        Returns:
+            HttpClient: HTTP客户端实例
+        """
+        return cls(
+            base_url=config.base_url,
+            timeout=config.timeout,
+            follow_redirects=config.follow_redirects,
+            max_connections=config.max_connections,
+            retry_config=config.retry,
+        )
+    
+    def add_interceptor(self, interceptor: RequestInterceptor) -> None:
+        """添加拦截器。
+        
+        Args:
+            interceptor: 拦截器实例
+        """
+        self._interceptors.append(interceptor)
+        logger.debug(f"添加拦截器: {interceptor.__class__.__name__}")
+    
+    async def _apply_interceptors(
+        self,
+        request: httpx.Request,
+        response: httpx.Response | None = None,
+    ) -> tuple[httpx.Request, httpx.Response | None]:
+        """应用拦截器。"""
+        # 请求前拦截
+        for interceptor in self._interceptors:
+            request = await interceptor.before_request(request)
+        
+        # 响应后拦截
+        if response:
+            for interceptor in self._interceptors:
+                response = await interceptor.after_response(response)
+        
+        return request, response
+    
+    async def _make_request(
+        self,
+        method: str,
+        url: str,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """执行HTTP请求（内部方法，使用tenacity重试）。"""
+        response = await self._client.request(method, url, **kwargs)
+        
+        # 检查状态码是否需要重试
+        if response.status_code in self._retry_config.retry_on_status:
+            logger.warning(
+                f"请求失败，状态码: {response.status_code}, 将重试"
+            )
+            raise httpx.HTTPStatusError(
+                f"HTTP {response.status_code}",
+                request=response.request,
+                response=response,
+            )
+        
+        return response
+    
+    def _get_retry_decorator(self):
+        """动态构建重试装饰器。"""
+        return retry(
+            stop=stop_after_attempt(self._retry_config.max_retries + 1),
+            wait=wait_exponential(
+                multiplier=self._retry_config.retry_delay,
+                min=self._retry_config.retry_delay,
+                max=self._retry_config.retry_delay * (self._retry_config.backoff_factor ** self._retry_config.max_retries),
+            ),
+            retry=retry_if_exception_type(*self._retry_config.retry_on_exceptions),
+            reraise=True,
+        )
+    
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        data: Any = None,
+        files: Any = None,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """发送HTTP请求。
+        
+        Args:
+            method: HTTP方法
+            url: 请求URL
+            headers: 请求头
+            params: 查询参数
+            json: JSON数据
+            data: 表单数据
+            files: 文件
+            **kwargs: 其他参数
+            
+        Returns:
+            httpx.Response: 响应对象
+            
+        Raises:
+            httpx.HTTPError: 请求失败
+        """
+        # 构建完整URL
+        full_url = f"{self._base_url}{url}" if self._base_url else url
+        
+        # 创建请求对象
+        request = self._client.build_request(
+            method=method,
+            url=full_url,
+            headers=headers,
+            params=params,
+            json=json,
+            data=data,
+            files=files,
+            **kwargs,
+        )
+        
+        # 应用拦截器（请求前）
+        request, _ = await self._apply_interceptors(request)
+        
+        try:
+            # 使用tenacity重试装饰器
+            retry_decorator = self._get_retry_decorator()
+            
+            @retry_decorator
+            async def _execute_request():
+                return await self._make_request(
+                    method=request.method,
+                    url=str(request.url),
+                    headers=request.headers,
+                    content=request.content,
+                    **kwargs,
+                )
+            
+            response = await _execute_request()
+            
+            # 应用拦截器（响应后）
+            _, response = await self._apply_interceptors(request, response)
+            
+            # 检查状态码
+            response.raise_for_status()
+            
+            return response
+        
+        except httpx.HTTPError as exc:
+            logger.error(
+                f"HTTP请求失败: {method} {full_url} | "
+                f"错误: {type(exc).__name__}: {exc}"
+            )
+            raise
+    
+    async def get(self, url: str, **kwargs: Any) -> httpx.Response:
+        """GET请求。"""
+        return await self.request("GET", url, **kwargs)
+    
+    async def post(self, url: str, **kwargs: Any) -> httpx.Response:
+        """POST请求。"""
+        return await self.request("POST", url, **kwargs)
+    
+    async def put(self, url: str, **kwargs: Any) -> httpx.Response:
+        """PUT请求。"""
+        return await self.request("PUT", url, **kwargs)
+    
+    async def patch(self, url: str, **kwargs: Any) -> httpx.Response:
+        """PATCH请求。"""
+        return await self.request("PATCH", url, **kwargs)
+    
+    async def delete(self, url: str, **kwargs: Any) -> httpx.Response:
+        """DELETE请求。"""
+        return await self.request("DELETE", url, **kwargs)
+    
+    async def head(self, url: str, **kwargs: Any) -> httpx.Response:
+        """HEAD请求。"""
+        return await self.request("HEAD", url, **kwargs)
+    
+    async def options(self, url: str, **kwargs: Any) -> httpx.Response:
+        """OPTIONS请求。"""
+        return await self.request("OPTIONS", url, **kwargs)
+    
+    async def close(self) -> None:
+        """关闭客户端。"""
+        await self._client.aclose()
+        logger.debug("HTTP客户端已关闭")
+    
+    async def __aenter__(self) -> HttpClient:
+        """异步上下文管理器入口。"""
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """异步上下文管理器出口。"""
+        await self.close()
+    
+    def __repr__(self) -> str:
+        """字符串表示。"""
+        return f"<HttpClient base_url={self._base_url} timeout={self._timeout}>"
+
+
+__all__ = [
+    "HttpClient",
+    "HttpClientConfig",
+    "LoggingInterceptor",
+    "RequestInterceptor",
+    "RetryConfig",
+]
+
+