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

aury/boot/commands/templates/project/modules/exceptions.py.tpl

@@ -0,0 +1,84 @@
+"""自定义异常模块。
+
+在此文件中定义业务异常类，继承自 BaseError。
+框架的全局异常处理器会自动将这些异常转换为 HTTP 响应。
+
+============================================================
+框架已有的异常类（可直接使用）
+============================================================
+- BaseError: 异常基类
+- ValidationError: 验证失败 (400)
+- NotFoundError: 资源不存在 (404)
+- AlreadyExistsError: 资源已存在 (409)
+- UnauthorizedError: 未授权 (401)
+- ForbiddenError: 禁止访问 (403)
+- DatabaseError: 数据库错误 (500)
+- BusinessError: 业务错误 (400)
+- VersionConflictError: 乐观锁冲突 (409)
+
+============================================================
+框架预留错误码范围（ErrorCode 枚举）
+============================================================
+- 1xxx: 通用错误
+    1000: UNKNOWN_ERROR
+    1001: VALIDATION_ERROR
+    1002: NOT_FOUND
+    1003: ALREADY_EXISTS
+    1004: UNAUTHORIZED
+    1005: FORBIDDEN
+- 2xxx: 数据库错误
+    2000: DATABASE_ERROR
+    2001: DUPLICATE_KEY
+    2002: CONSTRAINT_VIOLATION
+    2003: VERSION_CONFLICT
+- 3xxx: 业务错误
+    3000: BUSINESS_ERROR
+    3001: INVALID_OPERATION
+    3002: INSUFFICIENT_PERMISSION
+- 4xxx: 外部服务错误
+    4000: EXTERNAL_SERVICE_ERROR
+    4001: TIMEOUT_ERROR
+    4002: NETWORK_ERROR
+
+============================================================
+自定义错误码建议从 5000 开始，使用字符串格式
+============================================================
+
+继承示例：
+    class OrderError(BaseError):
+        default_message = "订单错误"
+        default_code = "5001"  # 字符串格式
+        default_status_code = 400
+
+    class OrderNotPaidError(OrderError):
+        default_message = "订单未支付"
+        default_code = "5002"
+"""
+
+from fastapi import status
+
+from aury.boot.application.errors import BaseError
+
+# ============================================================
+# 在此定义业务异常类
+# ============================================================
+
+
+# class OrderError(BaseError):
+#     """订单相关异常基类。"""
+#     default_message = "订单错误"
+#     default_code = "ORDER_ERROR"
+#     default_status_code = status.HTTP_400_BAD_REQUEST
+#
+#
+# class OrderNotFoundError(OrderError):
+#     """订单不存在。"""
+#     default_message = "订单不存在"
+#     default_code = "ORDER_NOT_FOUND"
+#     default_status_code = status.HTTP_404_NOT_FOUND
+#
+#
+# class OrderNotPaidError(OrderError):
+#     """订单未支付。"""
+#     default_message = "订单未支付"
+#     default_code = "ORDER_NOT_PAID"

aury/boot/commands/templates/project/modules/schedules.py.tpl

@@ -0,0 +1,18 @@
+"""定时任务模块（Scheduler）。
+
+在此文件中定义定时任务，使用 @scheduler.scheduled_job() 装饰器。
+
+框架会自动发现并加载本模块，无需在 main.py 中手动导入。
+也可通过 SCHEDULER_SCHEDULE_MODULES 环境变量指定自定义模块。
+"""
+
+# from aury.boot.common.logging import logger
+# from aury.boot.infrastructure.scheduler import SchedulerManager
+#
+# scheduler = SchedulerManager.get_instance()
+#
+#
+# @scheduler.scheduled_job("interval", seconds=60)
+# async def example_job():
+#     """示例定时任务，每 60 秒执行一次。"""
+#     logger.info("定时任务执行中...")

aury/boot/commands/templates/project/modules/tasks.py.tpl

@@ -0,0 +1,20 @@
+"""异步任务模块（Dramatiq Worker）。
+
+取消注释下面的示例代码即可启用异步任务。
+
+使用方式：
+    1. 配置 TASK_BROKER_URL 环境变量
+    2. 取消注释下面的代码
+    3. 运行 Worker：aury worker
+    4. 在代码中调用：example_task.send()
+"""
+
+# from aury.boot.common.logging import logger
+# from aury.boot.infrastructure.tasks import conditional_task
+#
+#
+# @conditional_task
+# def example_task():
+#     """示例异步任务。"""
+#     logger.info("异步任务执行中...")
+#     return {"status": "completed"}

aury/boot/commands/worker.py

@@ -0,0 +1,143 @@
+"""Worker 命令 - 运行任务队列 Worker。
+
+使用示例：
+    aury worker                  # 运行 worker
+    aury worker --app main:app   # 指定应用模块
+    aury worker -c 4             # 指定并发数
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+
+from rich.console import Console
+import typer
+
+console = Console()
+
+app = typer.Typer(
+    name="worker",
+    help="⚙️  运行任务队列 Worker",
+    no_args_is_help=False,
+)
+
+
+def _detect_app_module() -> str:
+    """自动检测应用模块路径。"""
+    import os
+
+    # 1. 环境变量
+    if app_module := os.environ.get("APP_MODULE"):
+        return app_module
+
+    # 2. pyproject.toml 中的 [tool.aury] 配置
+    pyproject_path = Path.cwd() / "pyproject.toml"
+    if pyproject_path.exists():
+        try:
+            import tomllib
+            with open(pyproject_path, "rb") as f:
+                data = tomllib.load(f)
+            if package := data.get("tool", {}).get("aury", {}).get("package"):
+                return f"{package}.main:app"
+        except Exception:
+            pass
+
+    # 3. 默认
+    return "main:app"
+
+
+@app.callback(invoke_without_command=True)
+def run_worker(
+    ctx: typer.Context,
+    app_path: str | None = typer.Option(
+        None,
+        "--app",
+        "-a",
+        help="应用模块路径（默认自动检测，如 main:app）",
+    ),
+    concurrency: int = typer.Option(
+        4,
+        "--concurrency",
+        "-c",
+        help="并发 worker 数量",
+    ),
+    queues: str | None = typer.Option(
+        None,
+        "--queues",
+        "-q",
+        help="要处理的队列名称（逗号分隔）",
+    ),
+) -> None:
+    """运行任务队列 Worker 进程。
+
+    Worker 会消费任务队列中的异步任务并执行。
+
+    示例：
+        aury worker                       # 默认配置
+        aury worker --app main:app        # 指定应用模块
+        aury worker -c 8                  # 8 个并发
+        aury worker -q high,default       # 只处理指定队列
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+
+    # 确保当前目录在 Python 路径中
+    cwd = str(Path.cwd())
+    if cwd not in sys.path:
+        sys.path.insert(0, cwd)
+
+    app_module = app_path or _detect_app_module()
+    console.print("[bold cyan]⚙️  启动 Worker[/bold cyan]")
+    console.print(f"   应用: [green]{app_module}[/green]")
+    console.print(f"   并发: [green]{concurrency}[/green]")
+    if queues:
+        console.print(f"   队列: [green]{queues}[/green]")
+
+    try:
+        # 导入应用（确保任务被注册）
+        module_path, app_name = app_module.rsplit(":", 1)
+        module = __import__(module_path, fromlist=[app_name])
+        application = getattr(module, app_name)
+
+        # 设置日志上下文
+        from aury.boot.common.logging import set_service_context
+        set_service_context("worker")
+
+        # 尝试导入 dramatiq
+        try:
+            import dramatiq
+            from dramatiq.cli import main as dramatiq_main
+        except ImportError:
+            console.print("[red]❌ dramatiq 未安装[/red]")
+            console.print("[dim]请安装: uv add 'aury-boot[tasks]'[/dim]")
+            raise typer.Exit(1)
+
+        console.print("[bold green]✅ Worker 启动中...[/bold green]")
+        console.print("[dim]按 Ctrl+C 停止[/dim]")
+
+        # 构建 dramatiq 参数
+        args = [
+            module_path,  # 模块路径
+            "--processes", "1",
+            "--threads", str(concurrency),
+        ]
+        if queues:
+            args.extend(["--queues", queues])
+
+        # 运行 dramatiq worker
+        sys.argv = ["dramatiq", *args]
+        dramatiq_main()
+
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Worker 已停止[/yellow]")
+    except ImportError as e:
+        console.print(f"[red]❌ 无法导入应用: {e}[/red]")
+        console.print("[dim]请确保应用模块路径正确，如 main:app[/dim]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]❌ 启动失败: {e}[/red]")
+        raise typer.Exit(1)
+
+
+__all__ = ["app"]

aury/boot/common/__init__.py

@@ -0,0 +1,35 @@
+"""Common 层模块。
+
+最基础层，提供：
+- 异常基类
+- 日志系统
+- 国际化（i18n）
+"""
+
+from .exceptions import FoundationError
+from .i18n import Translator, get_locale, load_translations, set_locale, translate
+from .logging import (
+    get_class_logger,
+    log_exceptions,
+    log_performance,
+    logger,
+    setup_logging,
+)
+
+__all__ = [
+    # 异常
+    "FoundationError",
+    # 国际化
+    "Translator",
+    "get_class_logger",
+    "get_locale",
+    "load_translations",
+    "log_exceptions",
+    "log_performance",
+    # 日志
+    "logger",
+    "set_locale",
+    "setup_logging",
+    "translate",
+]
+

aury/boot/common/exceptions/__init__.py

@@ -0,0 +1,114 @@
+"""基础异常定义。
+
+Common 层是最底层，不依赖任何业务层。
+所有框架异常都应该继承 FoundationError。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class FoundationError(Exception):
+    """基础异常类（最底层）。
+    
+    所有框架异常都应该继承此类。
+    这是整个异常体系的根类。
+    
+    提供可选的元数据和原因链支持，方便调试和异常包装。
+    
+    注意：虽然命名为 FoundationError，但它是异常体系的根类，
+    所有其他异常都继承它。
+    
+    Attributes:
+        message: 错误消息
+        metadata: 可选的元数据字典，用于存储额外的上下文信息
+        cause: 可选的原始异常，用于异常链
+    
+    使用示例:
+        # 基本用法
+        raise FoundationError("操作失败")
+        
+        # 带元数据
+        raise FoundationError(
+            "操作失败",
+            metadata={"user_id": 123, "operation": "update"}
+        )
+        
+        # 包装其他异常
+        try:
+            risky_operation()
+        except ValueError as e:
+            raise FoundationError(
+                "操作失败",
+                cause=e,
+                metadata={"context": "data_processing"}
+            ) from e
+    """
+    
+    def __init__(
+        self,
+        message: str,
+        *args: object,
+        metadata: dict[str, Any] | None = None,
+        cause: Exception | None = None,
+    ) -> None:
+        """初始化异常。
+        
+        Args:
+            message: 错误消息
+            *args: 其他参数（传递给父类）
+            metadata: 可选的元数据字典，用于存储额外的上下文信息
+            cause: 可选的原始异常，用于异常链
+        """
+        self.message = message
+        self.metadata = metadata or {}
+        self.cause = cause
+        
+        super().__init__(message, *args)
+        
+        # 如果提供了 cause，设置异常链
+        if cause is not None:
+            self.__cause__ = cause
+    
+    def __str__(self) -> str:
+        """返回异常字符串表示。"""
+        return self.message
+    
+    def __repr__(self) -> str:
+        """返回异常的详细表示，包含元数据信息。"""
+        parts = [f"{self.__class__.__name__}(message={self.message!r}"]
+        
+        if self.metadata:
+            parts.append(f", metadata={self.metadata}")
+        
+        if self.cause:
+            parts.append(f", cause={self.cause.__class__.__name__}")
+        
+        parts.append(")")
+        return "".join(parts)
+    
+    def with_metadata(self, **kwargs: Any) -> FoundationError:
+        """添加或更新元数据（链式调用）。
+        
+        Args:
+            **kwargs: 要添加的元数据键值对
+        
+        Returns:
+            FoundationError: 返回自身，支持链式调用
+        
+        使用示例:
+            raise FoundationError("操作失败").with_metadata(
+                user_id=123,
+                operation="update"
+            )
+        """
+        self.metadata.update(kwargs)
+        return self
+
+
+__all__ = [
+    "FoundationError",
+]
+
+

aury/boot/common/i18n/__init__.py

@@ -0,0 +1,16 @@
+"""国际化模块。
+
+提供多语言翻译、日期/数字本地化等功能。
+
+注意：框架不提供默认翻译字典，用户需要调用 load_translations() 加载翻译资源。
+"""
+
+from .translator import Translator, get_locale, load_translations, set_locale, translate
+
+__all__ = [
+    "Translator",
+    "get_locale",
+    "load_translations",
+    "set_locale",
+    "translate",
+]

aury/boot/common/i18n/translator.py

@@ -0,0 +1,272 @@
+"""翻译器。
+
+提供多语言翻译和本地化功能。
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+import os
+from typing import Any
+
+from babel import Locale, dates, numbers
+from babel.support import Format
+
+from aury.boot.common.logging import logger
+
+# 全局语言环境
+_current_locale: str | None = None
+
+# 翻译字典（由用户提供，框架不提供默认翻译）
+_translations: dict[str, dict[str, str]] = {}
+
+
+def get_locale() -> str:
+    """获取当前语言环境。
+    
+    Returns:
+        str: 当前语言环境代码（如 "zh_CN"）
+    """
+    global _current_locale
+    if _current_locale is None:
+        # 从环境变量获取，默认为中文
+        _current_locale = os.getenv("LANG", "zh_CN").split(".")[0] or "zh_CN"
+    return _current_locale
+
+
+def set_locale(locale: str) -> None:
+    """设置当前语言环境。
+    
+    Args:
+        locale: 语言环境代码（如 "zh_CN", "en_US"）
+    """
+    global _current_locale
+    _current_locale = locale
+    logger.debug(f"语言环境已设置为: {locale}")
+
+
+class Translator:
+    """翻译器。
+    
+    提供多语言翻译和本地化功能。
+    
+    注意：框架不提供默认翻译字典，用户需要自行加载翻译资源。
+    
+    使用示例:
+        # 加载翻译字典
+        from aury.boot.common.i18n.translator import Translator, load_translations
+        
+        load_translations({
+            "zh_CN": {
+                "user.created": "用户 {name} 创建成功",
+                "welcome": "欢迎",
+            },
+            "en_US": {
+                "user.created": "User {name} created successfully",
+                "welcome": "Welcome",
+            },
+        })
+        
+        # 使用翻译器
+        translator = Translator(locale="zh_CN")
+        message = translator.translate("user.created", name="张三")
+        # "用户 张三 创建成功"
+        
+        # 日期本地化
+        date_str = translator.format_date(datetime.now())
+        
+        # 数字本地化
+        number_str = translator.format_number(1234.56)
+    """
+    
+    def __init__(self, locale: str | None = None) -> None:
+        """初始化翻译器。
+        
+        Args:
+            locale: 语言环境代码（如 "zh_CN"），如果为 None 则使用全局设置
+        """
+        self._locale_str = locale or get_locale()
+        try:
+            self._locale = Locale.parse(self._locale_str)
+        except Exception:
+            # 如果解析失败，使用默认值
+            logger.warning(f"无法解析语言环境 {self._locale_str}，使用默认值 zh_CN")
+            self._locale = Locale.parse("zh_CN")
+            self._locale_str = "zh_CN"
+        
+        self._formatter = Format(self._locale)
+        logger.debug(f"翻译器已初始化: {self._locale_str}")
+    
+    @property
+    def locale(self) -> str:
+        """获取语言环境代码。"""
+        return self._locale_str
+    
+    def translate(self, key: str, default: str | None = None, **kwargs: Any) -> str:
+        """翻译文本。
+        
+        Args:
+            key: 翻译键
+            default: 默认值（如果找不到翻译）
+            **kwargs: 格式化参数
+            
+        Returns:
+            str: 翻译后的文本
+        """
+        translations = _translations.get(self._locale_str, {})
+        template = translations.get(key, default)
+        
+        if template is None:
+            logger.warning(f"翻译键未找到: {key} (locale: {self._locale_str})")
+            return key
+        
+        try:
+            return template.format(**kwargs)
+        except KeyError as e:
+            logger.error(f"翻译格式化失败: {key}, 缺少参数: {e}")
+            return template
+    
+    def format_date(
+        self,
+        date: datetime,
+        format: str = "medium",
+        timezone: str | None = None,
+    ) -> str:
+        """格式化日期。
+        
+        Args:
+            date: 日期时间对象
+            format: 格式（"short", "medium", "long", "full" 或自定义格式）
+            timezone: 时区（可选）
+            
+        Returns:
+            str: 格式化后的日期字符串
+        """
+        try:
+            if format in ("short", "medium", "long", "full"):
+                return dates.format_date(date, format=format, locale=self._locale)
+            else:
+                return dates.format_date(date, format=format, locale=self._locale)
+        except Exception as e:
+            logger.error(f"日期格式化失败: {e}")
+            return str(date)
+    
+    def format_datetime(
+        self,
+        dt: datetime,
+        format: str = "medium",
+        timezone: str | None = None,
+    ) -> str:
+        """格式化日期时间。
+        
+        Args:
+            dt: 日期时间对象
+            format: 格式（"short", "medium", "long", "full" 或自定义格式）
+            timezone: 时区（可选）
+            
+        Returns:
+            str: 格式化后的日期时间字符串
+        """
+        try:
+            if format in ("short", "medium", "long", "full"):
+                return dates.format_datetime(dt, format=format, locale=self._locale)
+            else:
+                return dates.format_datetime(dt, format=format, locale=self._locale)
+        except Exception as e:
+            logger.error(f"日期时间格式化失败: {e}")
+            return str(dt)
+    
+    def format_number(self, number: float, format: str | None = None) -> str:
+        """格式化数字。
+        
+        Args:
+            number: 数字
+            format: 格式（可选，如 "#,##0.00"）
+            
+        Returns:
+            str: 格式化后的数字字符串
+        """
+        try:
+            if format:
+                return numbers.format_number(number, format=format, locale=self._locale)
+            else:
+                return numbers.format_number(number, locale=self._locale)
+        except Exception as e:
+            logger.error(f"数字格式化失败: {e}")
+            return str(number)
+    
+    def format_currency(self, amount: float, currency: str = "CNY") -> str:
+        """格式化货币。
+        
+        Args:
+            amount: 金额
+            currency: 货币代码（如 "CNY", "USD"）
+            
+        Returns:
+            str: 格式化后的货币字符串
+        """
+        try:
+            return numbers.format_currency(amount, currency, locale=self._locale)
+        except Exception as e:
+            logger.error(f"货币格式化失败: {e}")
+            return f"{currency} {amount}"
+
+
+def load_translations(translations: dict[str, dict[str, str]]) -> None:
+    """加载翻译字典。
+    
+    此函数用于加载用户提供的翻译资源。框架本身不提供默认翻译。
+    
+    Args:
+        translations: 翻译字典，格式为 {locale: {key: message}}
+        
+    使用示例:
+        load_translations({
+            "zh_CN": {
+                "user.created": "用户 {name} 创建成功",
+                "welcome": "欢迎",
+            },
+            "en_US": {
+                "user.created": "User {name} created successfully",
+                "welcome": "Welcome",
+            },
+        })
+    """
+    global _translations
+    _translations = translations
+    logger.info(f"翻译字典已加载，支持语言: {', '.join(translations.keys())}")
+
+
+def translate(key: str, default: str | None = None, locale: str | None = None, **kwargs: Any) -> str:
+    """翻译文本（便捷函数）。
+    
+    Args:
+        key: 翻译键
+        default: 默认值
+        locale: 语言环境（可选，默认使用全局设置）
+        **kwargs: 格式化参数
+        
+    Returns:
+        str: 翻译后的文本
+    """
+    translator = Translator(locale=locale)
+    return translator.translate(key, default=default, **kwargs)
+
+
+# 装饰器支持
+def translate_decorator(locale: str | None = None):
+    """翻译装饰器。
+    
+    使用示例:
+        @translate_decorator("zh_CN")
+        def get_message():
+            return _("Welcome")  # 会被翻译
+    """
+    def decorator(func):
+        def wrapper(*args, **kwargs):
+            result = func(*args, **kwargs)
+            if isinstance(result, str):
+                return translate(result, locale=locale)
+            return result
+        return wrapper
+    return decorator