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

aury/boot/application/migrations/setup.py

@@ -0,0 +1,237 @@
+"""统一的迁移配置初始化模块。
+
+这个模块提供单一的数据源来创建迁移配置，被 init 命令和 MigrationManager 共同使用。
+"""
+
+from pathlib import Path
+
+
+def ensure_migration_setup(
+    base_path: Path,
+    config_path: str,
+    script_location: str,
+    model_modules: list[str],
+) -> None:
+    """确保迁移配置和目录存在，不存在则自动创建。
+    
+    Args:
+        base_path: 项目根目录
+        config_path: alembic.ini 路径
+        script_location: 迁移脚本目录名
+        model_modules: 模型模块列表
+    """
+    script_dir = base_path / script_location
+    config_file = base_path / config_path
+    
+    # 创建迁移脚本目录
+    if not script_dir.exists():
+        script_dir.mkdir(parents=True, exist_ok=True)
+        
+        # 创建 versions 目录
+        versions_dir = script_dir / "versions"
+        versions_dir.mkdir(exist_ok=True)
+        
+        # 创建 env.py
+        env_py = script_dir / "env.py"
+        if not env_py.exists():
+            env_content = _get_env_py_template(model_modules)
+            env_py.write_text(env_content, encoding="utf-8")
+        
+        # 创建 script.py.mako
+        mako_file = script_dir / "script.py.mako"
+        if not mako_file.exists():
+            mako_content = _get_script_mako_template()
+            mako_file.write_text(mako_content, encoding="utf-8")
+    
+    # 创建 alembic.ini
+    if not config_file.exists():
+        ini_content = _get_alembic_ini_template(script_location)
+        config_file.write_text(ini_content, encoding="utf-8")
+
+
+def _get_env_py_template(model_modules: list[str]) -> str:
+    """获取 env.py 模板（异步版本）。"""
+    model_modules_str = repr(model_modules)
+    
+    return f'''"""Alembic 环境配置（异步）。
+
+由 Aury Boot 自动生成，并改造为全异步模式，
+适配 sqlite+aiosqlite / postgresql+asyncpg / mysql+asyncmy 等异步驱动。
+"""
+
+from logging.config import fileConfig
+from pathlib import Path
+import os
+import sys
+
+from alembic import context
+from sqlalchemy import pool
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+# 导入模型基类
+from aury.boot.domain.models import Base
+
+# Alembic Config 对象
+config = context.config
+
+# 解析日志配置
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# === 模型加载（基于项目包名自动发现） ===
+# 确保项目根目录在 sys.path 中
+project_root = Path(__file__).resolve().parents[1]
+if str(project_root) not in sys.path:
+    sys.path.insert(0, str(project_root))
+
+from aury.boot.application.migrations import load_all_models
+try:
+    from aury.boot.commands.config import get_project_config
+    _cfg = get_project_config()
+    if _cfg.has_package:
+        _model_modules = [f"{{_cfg.package}}.models", f"{{_cfg.package}}.**.models"]
+    else:
+        _model_modules = ["models"]
+except Exception:
+    _model_modules = {model_modules_str}
+
+# 加载模型，确保 Base.metadata 完整
+load_all_models(_model_modules)
+
+# 目标元数据
+target_metadata = Base.metadata
+
+
+def get_url() -> str:
+    """获取数据库 URL（优先环境变量，其次 alembic.ini）。"""
+    return os.environ.get("DATABASE_URL") or config.get_main_option("sqlalchemy.url", "")
+
+
+def run_migrations_offline() -> None:
+    """离线模式运行迁移（不建立实际连接）。"""
+    url = get_url()
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={{"paramstyle": "named"}},
+        compare_type=True,
+        compare_server_default=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def _do_run_migrations(connection) -> None:
+    """在同步上下文里执行迁移（由 AsyncConnection.run_sync 调用）。"""
+    context.configure(
+        connection=connection,
+        target_metadata=target_metadata,
+        compare_type=True,
+        compare_server_default=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def _run_async_migrations() -> None:
+    configuration = config.get_section(config.config_ini_section, {{}})
+    configuration["sqlalchemy.url"] = get_url()
+
+    connectable = async_engine_from_config(
+        configuration,
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    async with connectable.connect() as connection:
+        await connection.run_sync(_do_run_migrations)
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    import asyncio
+    asyncio.run(_run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()
+'''
+
+
+def _get_script_mako_template() -> str:
+    """获取 script.py.mako 模板。"""
+    return '''"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}
+'''
+
+
+def _get_alembic_ini_template(script_location: str) -> str:
+    """获取 alembic.ini 模板。"""
+    return f'''[alembic]
+script_location = {script_location}
+file_template = %%(year)d%%(month).2d%%(day).2d_%%(hour).2d%%(minute).2d_%%(rev)s_%%(slug)s
+timezone = UTC
+truncate_slug_length = 40
+version_path_separator = os
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S
+'''
+
+
+__all__ = ["ensure_migration_setup"]

aury/boot/application/rpc/__init__.py

@@ -0,0 +1,63 @@
+"""RPC调用框架。
+
+提供统一的微服务RPC调用接口。
+
+基于 toolkit/http 的 HttpClient，提供 RPC 调用封装。
+支持多种服务发现方式（通过 BaseConfig.rpc_client 配置）：
+- 配置文件（BaseConfig.rpc_client.services，优先级最高）
+- DNS 解析（统一处理 K8s/Docker Compose，自动使用服务名）
+
+注意：负载均衡由基础设施层（K8s Service、Docker Compose）自动处理，
+应用层仅负责服务发现和调用，不实现负载均衡策略。
+
+使用示例:
+    # 方式1：使用服务发现（推荐）
+    from aury.boot.application.config import BaseConfig
+    from aury.boot.application.rpc import create_rpc_client
+    
+    config = BaseConfig()  # 从环境变量和 .env 文件加载配置
+    client = create_rpc_client(service_name="user-service", config=config)
+    response = await client.get("/api/v1/users/1")
+    
+    # 方式2：直接指定 URL（不使用服务发现）
+    from aury.boot.application.rpc import RPCClient
+    
+    client = RPCClient(base_url="http://user-service:8000")
+    response = await client.get("/api/v1/users/1")
+    
+    配置方式（通过环境变量或 .env 文件）:
+    # 调用配置（RPC_CLIENT_ 前缀）
+    RPC_CLIENT_SERVICES={"user-service": "http://user-service:8000"}
+    RPC_CLIENT_DNS_SCHEME=http
+    RPC_CLIENT_DNS_PORT=80
+    
+    # 注册配置（RPC_SERVICE_ 前缀）
+    RPC_SERVICE_NAME=my-service
+    RPC_SERVICE_URL=http://my-service:8000
+"""
+
+from .base import BaseRPCClient, RPCError, RPCResponse
+from .client import RPCClient, create_rpc_client
+from .discovery import (
+    CompositeServiceDiscovery,
+    ConfigServiceDiscovery,
+    DNSServiceDiscovery,
+    ServiceDiscovery,
+    get_service_discovery,
+    set_service_discovery,
+)
+
+__all__ = [
+    "BaseRPCClient",
+    "CompositeServiceDiscovery",
+    "ConfigServiceDiscovery",
+    "create_rpc_client",
+    "DNSServiceDiscovery",
+    "get_service_discovery",
+    "RPCClient",
+    "RPCError",
+    "RPCResponse",
+    "ServiceDiscovery",
+    "set_service_discovery",
+]
+

aury/boot/application/rpc/base.py

@@ -0,0 +1,108 @@
+"""RPC基类和异常定义。"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel
+
+
+class RPCError(Exception):
+    """RPC调用异常。"""
+
+    def __init__(
+        self,
+        message: str,
+        code: str = "RPC_ERROR",
+        status_code: int = 500,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        """初始化RPC异常。
+
+        Args:
+            message: 错误消息
+            code: 错误代码
+            status_code: HTTP状态码
+            details: 错误详情
+        """
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.details = details or {}
+
+    def __str__(self) -> str:
+        return f"[{self.code}] {self.message} (status: {self.status_code})"
+
+
+class RPCResponse(BaseModel):
+    """RPC响应模型。"""
+
+    success: bool = True
+    data: Any | None = None
+    message: str = ""
+    code: str = "0000"
+    status_code: int = 200
+
+    def raise_for_status(self) -> None:
+        """如果响应失败，抛出异常。"""
+        if not self.success:
+            raise RPCError(
+                message=self.message,
+                code=self.code,
+                status_code=self.status_code,
+            )
+
+
+class BaseRPCClient:
+    """RPC客户端基类。
+
+    提供统一的RPC调用接口和错误处理。
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        timeout: int = 30,
+        retry_times: int = 3,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        """初始化RPC客户端。
+
+        Args:
+            base_url: 服务基础URL
+            timeout: 超时时间（秒）
+            retry_times: 重试次数
+            headers: 默认请求头
+        """
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.retry_times = retry_times
+        self.headers = headers or {}
+
+    def _build_url(self, path: str) -> str:
+        """构建完整URL。
+
+        Args:
+            path: API路径
+
+        Returns:
+            str: 完整URL
+        """
+        path = path.lstrip("/")
+        return f"{self.base_url}/{path}"
+
+    def _prepare_headers(self, extra_headers: dict[str, str] | None = None) -> dict[str, str]:
+        """准备请求头。
+
+        Args:
+            extra_headers: 额外的请求头
+
+        Returns:
+            dict[str, str]: 合并后的请求头
+        """
+        headers = self.headers.copy()
+        if extra_headers:
+            headers.update(extra_headers)
+        return headers
+

aury/boot/application/rpc/client.py

@@ -0,0 +1,294 @@
+"""RPC客户端实现。
+
+基于 toolkit/http 的 HttpClient，提供 RPC 调用封装。
+支持链路追踪（Distributed Tracing）。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from aury.boot.application.rpc.base import BaseRPCClient, RPCError, RPCResponse
+from aury.boot.application.rpc.discovery import get_service_discovery
+from aury.boot.common.logging import get_trace_id, logger
+from aury.boot.toolkit.http import HttpClient
+
+if TYPE_CHECKING:
+    from aury.boot.application.config import BaseConfig
+
+
+class RPCClient(BaseRPCClient):
+    """RPC客户端实现（支持链路追踪）。
+
+    基于 toolkit/http 的 HttpClient，提供 RPC 调用封装。
+    支持自动重试、错误处理和链路追踪（自动传递追踪ID）。
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        timeout: int = 30,
+        retry_times: int = 3,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        """初始化RPC客户端。
+
+        Args:
+            base_url: 服务基础URL
+            timeout: 超时时间（秒）
+            retry_times: 重试次数
+            headers: 默认请求头
+        """
+        super().__init__(base_url, timeout, retry_times, headers)
+        # 使用 toolkit/http 的 HttpClient
+        from aury.boot.toolkit.http import RetryConfig
+        
+        retry_config = RetryConfig(max_retries=retry_times)
+        self._http_client = HttpClient(
+            base_url=base_url,
+            timeout=float(timeout),
+            retry_config=retry_config,
+        )
+        # 添加默认请求头
+        if headers:
+            # HttpClient 不支持直接设置默认 headers，需要在每次请求时传递
+            self._default_headers = headers
+        else:
+            self._default_headers = {}
+
+    async def close(self) -> None:
+        """关闭HTTP客户端。"""
+        await self._http_client.close()
+
+    async def _call(
+        self,
+        method: str,
+        path: str,
+        data: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> RPCResponse:
+        """执行RPC调用。
+
+        Args:
+            method: HTTP方法（GET, POST, PUT, DELETE）
+            path: API路径
+            data: 请求体数据
+            params: URL参数
+            headers: 请求头
+
+        Returns:
+            RPCResponse: RPC响应
+
+        Raises:
+            RPCError: RPC调用失败
+        """
+        # 合并请求头
+        request_headers = self._prepare_headers(headers)
+        
+        # 添加链路追踪 ID
+        trace_id = get_trace_id()
+        request_headers["x-trace-id"] = trace_id
+        request_headers["x-request-id"] = trace_id
+        
+        logger.debug(
+            f"RPC调用开始: {method} {path} | "
+            f"Trace-ID: {trace_id}"
+        )
+
+        try:
+            # 使用 toolkit/http 的 HttpClient
+            response = await self._http_client.request(
+                method=method,
+                url=path,
+                json=data,
+                params=params,
+                headers=request_headers,
+            )
+
+            # 解析响应
+            result = response.json()
+            rpc_response = RPCResponse(
+                success=result.get("success", True),
+                data=result.get("data"),
+                message=result.get("message", ""),
+                code=result.get("code", "0000"),
+                status_code=response.status_code,
+            )
+
+            rpc_response.raise_for_status()
+            
+            logger.debug(
+                f"RPC调用成功: {method} {path} | "
+                f"状态: {response.status_code} | "
+                f"Trace-ID: {trace_id}"
+            )
+            
+            return rpc_response
+
+        except Exception as e:
+            # HttpClient 已经处理了 HTTP 错误，这里只需要转换为 RPCError
+            status_code = getattr(e, "response", None)
+            if status_code and hasattr(status_code, "status_code"):
+                status_code = status_code.status_code
+            else:
+                status_code = 500
+            
+            logger.error(
+                f"RPC调用失败: {method} {path} | "
+                f"错误: {e!s} | "
+                f"Trace-ID: {trace_id}"
+            )
+            raise RPCError(
+                message=f"RPC调用失败: {e!s}",
+                code="RPC_ERROR",
+                status_code=status_code,
+            ) from e
+
+    async def get(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> RPCResponse:
+        """GET请求。
+
+        Args:
+            path: API路径
+            params: URL参数
+            headers: 请求头
+
+        Returns:
+            RPCResponse: RPC响应
+        """
+        return await self._call("GET", path, params=params, headers=headers)
+
+    async def post(
+        self,
+        path: str,
+        data: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> RPCResponse:
+        """POST请求。
+
+        Args:
+            path: API路径
+            data: 请求体数据
+            headers: 请求头
+
+        Returns:
+            RPCResponse: RPC响应
+        """
+        return await self._call("POST", path, data=data, headers=headers)
+
+    async def put(
+        self,
+        path: str,
+        data: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> RPCResponse:
+        """PUT请求。
+
+        Args:
+            path: API路径
+            data: 请求体数据
+            headers: 请求头
+
+        Returns:
+            RPCResponse: RPC响应
+        """
+        return await self._call("PUT", path, data=data, headers=headers)
+
+    async def delete(
+        self,
+        path: str,
+        headers: dict[str, str] | None = None,
+    ) -> RPCResponse:
+        """DELETE请求。
+
+        Args:
+            path: API路径
+            headers: 请求头
+
+        Returns:
+            RPCResponse: RPC响应
+        """
+        return await self._call("DELETE", path, headers=headers)
+
+
+def create_rpc_client(
+    service_name: str | None = None,
+    base_url: str | None = None,
+    timeout: int | None = None,
+    retry_times: int | None = None,
+    headers: dict[str, str] | None = None,
+    config: "BaseConfig | None" = None,
+) -> RPCClient:
+    """创建 RPC 客户端（支持服务发现）。
+
+    优先使用服务发现解析服务地址，如果未提供 service_name 或 base_url，则使用 base_url。
+
+    Args:
+        service_name: 服务名称（用于服务发现）
+        base_url: 服务基础URL（如果提供，直接使用，不进行服务发现）
+        timeout: 超时时间（秒），如果为 None 则使用配置中的默认值
+        retry_times: 重试次数，如果为 None 则使用配置中的默认值
+        headers: 默认请求头
+        config: 应用配置（可选），用于服务发现和获取默认配置
+
+    Returns:
+        RPCClient: RPC 客户端实例
+
+    Raises:
+        ValueError: 如果既未提供 service_name 也未提供 base_url
+
+    示例:
+        # 使用服务发现（自动从配置/DNS 解析）
+        from aury.boot.application.config import BaseConfig
+        
+        config = BaseConfig()
+        client = create_rpc_client(service_name="user-service", config=config)
+        response = await client.get("/api/v1/users/1")
+
+        # 直接指定 URL（不使用服务发现）
+        client = create_rpc_client(base_url="http://user-service:8000")
+        response = await client.get("/api/v1/users/1")
+    """
+    # 从配置中获取默认值
+    if config:
+        rpc_client_settings = config.rpc_client
+        default_timeout = timeout if timeout is not None else rpc_client_settings.default_timeout
+        default_retry_times = retry_times if retry_times is not None else rpc_client_settings.default_retry_times
+    else:
+        default_timeout = timeout if timeout is not None else 30
+        default_retry_times = retry_times if retry_times is not None else 3
+    
+    if base_url:
+        # 直接使用提供的 URL
+        return RPCClient(
+            base_url=base_url,
+            timeout=default_timeout,
+            retry_times=default_retry_times,
+            headers=headers,
+        )
+    
+    if service_name:
+        # 使用服务发现解析
+        discovery = get_service_discovery(config)
+        resolved_url = discovery.resolve(service_name)
+        
+        if not resolved_url:
+            raise ValueError(
+                f"无法解析服务地址: {service_name}。"
+                "请检查配置（BaseConfig.rpc_client.services）或确保 DNS 服务发现已启用。"
+            )
+        
+        return RPCClient(
+            base_url=resolved_url,
+            timeout=default_timeout,
+            retry_times=default_retry_times,
+            headers=headers,
+        )
+    
+    raise ValueError("必须提供 service_name 或 base_url")
+