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

aury/boot/application/constants/components.py

@@ -0,0 +1,50 @@
+"""中间件和组件名称常量。
+
+定义所有内置中间件和组件的标准命名。
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class MiddlewareName(str, Enum):
+    """中间件名称常量。
+
+    所有内置 HTTP 中间件的标准命名。
+    """
+
+    # HTTP 中间件
+    REQUEST_LOGGING = "request_logging"
+    WEBSOCKET_LOGGING = "websocket_logging"
+    CORS = "cors"
+
+
+class ComponentName(str, Enum):
+    """组件名称常量。
+
+    所有内置基础设施组件的标准命名。
+    """
+
+    # 基础设施组件
+    DATABASE = "database"
+    CACHE = "cache"
+    TASK_QUEUE = "task_queue"
+    SCHEDULER = "scheduler"
+
+    # 存储组件
+    STORAGE = "storage"
+
+    # 迁移组件
+    MIGRATIONS = "migrations"
+
+    # 管理后台（可选扩展）
+    ADMIN_CONSOLE = "admin_console"
+
+
+__all__ = [
+    "ComponentName",
+    "MiddlewareName",
+]
+
+

aury/boot/application/constants/scheduler.py

@@ -0,0 +1,28 @@
+"""调度器运行模式常量。
+
+定义调度器运行模式的枚举。
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class SchedulerMode(str, Enum):
+    """调度器运行模式枚举（应用层配置）。
+
+    - EMBEDDED: 伴随 API 运行（默认）
+    - STANDALONE: 独立运行
+    - DISABLED: 禁用调度器
+    """
+
+    EMBEDDED = "embedded"
+    STANDALONE = "standalone"
+    DISABLED = "disabled"
+
+
+__all__ = [
+    "SchedulerMode",
+]
+
+

aury/boot/application/constants/service.py

@@ -0,0 +1,29 @@
+"""服务类型常量。
+
+定义服务运行模式的枚举。
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ServiceType(str, Enum):
+    """服务类型枚举（应用层配置）。
+
+    用于区分不同的服务运行模式：
+    - API: 运行 API 服务（可伴随调度器）
+    - WORKER: 运行任务队列 Worker
+    - SCHEDULER: 仅运行调度器（独立 pod）
+    """
+
+    API = "api"
+    WORKER = "worker"
+    SCHEDULER = "scheduler"
+
+
+__all__ = [
+    "ServiceType",
+]
+
+

aury/boot/application/errors/__init__.py

@@ -0,0 +1,55 @@
+"""错误处理系统 - 责任链模式 + Pydantic。
+
+提供统一的异常类和错误处理链。
+"""
+
+from .chain import ErrorHandlerChain, error_handler_chain, global_exception_handler
+from .codes import ErrorCode
+from .exceptions import (
+    AlreadyExistsError,
+    BaseError,
+    BusinessError,
+    DatabaseError,
+    ForbiddenError,
+    NotFoundError,
+    UnauthorizedError,
+    ValidationError,
+    VersionConflictError,
+)
+from .handlers import (
+    BaseErrorHandler,
+    DatabaseErrorHandler,
+    ErrorHandler,
+    HTTPExceptionHandler,
+    ServiceErrorHandler,
+    ValidationErrorHandler,
+)
+from .response import ErrorDetail
+
+__all__ = [
+    "AlreadyExistsError",
+    "BaseError",
+    "BaseErrorHandler",
+    "BusinessError",
+    "DatabaseError",
+    "DatabaseErrorHandler",
+    # 错误代码
+    "ErrorCode",
+    # 错误模型
+    "ErrorDetail",
+    # 错误处理器
+    "ErrorHandler",
+    # 错误处理链
+    "ErrorHandlerChain",
+    "ForbiddenError",
+    "HTTPExceptionHandler",
+    "NotFoundError",
+    "ServiceErrorHandler",
+    "UnauthorizedError",
+    "ValidationError",
+    "ValidationErrorHandler",
+    "VersionConflictError",
+    "error_handler_chain",
+    "global_exception_handler",
+]
+

aury/boot/application/errors/chain.py

@@ -0,0 +1,80 @@
+"""错误处理链管理器。
+
+提供错误处理链的构建和管理。
+"""
+
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+from .handlers import (
+    BaseErrorHandler,
+    DatabaseErrorHandler,
+    ErrorHandler,
+    HTTPExceptionHandler,
+    ServiceErrorHandler,
+    ValidationErrorHandler,
+)
+
+
+class ErrorHandlerChain:
+    """错误处理链管理器。"""
+    
+    def __init__(self) -> None:
+        """初始化处理链。"""
+        self._chain = self._build_chain()
+    
+    def _build_chain(self) -> ErrorHandler:
+        """构建处理链。
+        
+        Returns:
+            ErrorHandler: 处理链头部
+        """
+        # 按优先级顺序构建处理链
+        # 1. BaseErrorHandler - 处理应用层自定义异常
+        # 2. ServiceErrorHandler - 处理 Domain 层 ServiceException（业务异常）
+        # 3. HTTPExceptionHandler - 处理 FastAPI HTTP 异常
+        # 4. ValidationErrorHandler - 处理 Pydantic 验证异常
+        # 5. DatabaseErrorHandler - 处理数据库异常（包括 Domain 层其他异常）
+        base_handler = BaseErrorHandler()
+        service_handler = ServiceErrorHandler()
+        http_handler = HTTPExceptionHandler()
+        validation_handler = ValidationErrorHandler()
+        db_handler = DatabaseErrorHandler()
+        
+        base_handler.set_next(service_handler).set_next(http_handler).set_next(validation_handler).set_next(db_handler)
+        
+        return base_handler
+    
+    async def handle(self, exception: Exception, request: Request) -> JSONResponse:
+        """处理异常。
+        
+        Args:
+            exception: 异常对象
+            request: 请求对象
+            
+        Returns:
+            JSONResponse: 响应对象
+        """
+        return await self._chain.process(exception, request)
+
+
+# 全局异常处理器实例
+error_handler_chain = ErrorHandlerChain()
+
+
+async def global_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    """全局异常处理器（FastAPI集成）。
+    
+    使用方式:
+        app.add_exception_handler(Exception, global_exception_handler)
+    """
+    return await error_handler_chain.handle(exc, request)
+
+
+__all__ = [
+    "ErrorHandlerChain",
+    "error_handler_chain",
+    "global_exception_handler",
+]
+
+

aury/boot/application/errors/codes.py

@@ -0,0 +1,67 @@
+"""错误代码定义。
+
+提供统一的错误代码枚举。
+
+**重要提示**：
+Python 的 Enum 不支持继承已有成员的枚举。
+如果你需要扩展错误代码，请使用以下方式之一：
+
+方式 1（推荐）：创建独立的枚举类
+```python
+class ServiceErrorCode(str, Enum):
+    # 服务特定错误代码（5xxx）
+    CUSTOM_ERROR = "5000"
+```
+
+方式 2：使用联合类型
+```python
+ErrorCodeType = ErrorCode | ServiceErrorCode
+```
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ErrorCode(str, Enum):
+    """Foundation Kit 基础错误代码。
+    
+    预留范围：
+    - 1xxx: 通用错误
+    - 2xxx: 数据库错误
+    - 3xxx: 业务错误
+    - 4xxx: 外部服务错误
+    - 5xxx+: 留给各个服务自定义
+    """
+    
+    # 通用错误 (1xxx)
+    UNKNOWN_ERROR = "1000"
+    VALIDATION_ERROR = "1001"
+    NOT_FOUND = "1002"
+    ALREADY_EXISTS = "1003"
+    UNAUTHORIZED = "1004"
+    FORBIDDEN = "1005"
+    
+    # 数据库错误 (2xxx)
+    DATABASE_ERROR = "2000"
+    DUPLICATE_KEY = "2001"
+    CONSTRAINT_VIOLATION = "2002"
+    VERSION_CONFLICT = "2003"  # 乐观锁冲突
+    
+    # 业务错误 (3xxx)
+    BUSINESS_ERROR = "3000"
+    INVALID_OPERATION = "3001"
+    INSUFFICIENT_PERMISSION = "3002"
+    
+    # 外部服务错误 (4xxx)
+    EXTERNAL_SERVICE_ERROR = "4000"
+    TIMEOUT_ERROR = "4001"
+    NETWORK_ERROR = "4002"
+
+
+__all__ = [
+    "ErrorCode",
+]
+
+

aury/boot/application/errors/exceptions.py

@@ -0,0 +1,238 @@
+"""应用层异常类定义。
+
+提供应用层业务异常类，用于业务逻辑中抛出异常。
+这些异常会被错误处理器转换为 HTTP 响应。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from fastapi import status
+
+from aury.boot.common.exceptions import FoundationError
+
+from .codes import ErrorCode
+from .response import ErrorDetail
+
+if TYPE_CHECKING:
+    from aury.boot.domain.exceptions import VersionConflictError as DomainVersionConflictError
+
+
+class BaseError(FoundationError):
+    """应用层异常基类（用于 HTTP 响应）。
+    
+    所有应用层的异常应继承此类。
+    用于 HTTP API 响应，包含错误代码和状态码。
+    
+    继承示例：
+        class OrderError(BaseError):
+            default_message = "订单错误"
+            default_code = "5001"  # 自定义错误码
+            default_status_code = 400
+        
+        class OrderNotPaidError(OrderError):
+            default_message = "订单未支付"
+            default_code = "5002"
+    
+    Attributes:
+        message: 错误消息
+        code: 错误代码（字符串或 ErrorCode 枚举）
+        status_code: HTTP状态码
+        details: 错误详情列表
+        metadata: 元数据
+    """
+    
+    # 类级别默认值，子类可覆盖
+    default_message: str = "未知错误"
+    default_code: str | ErrorCode = ErrorCode.UNKNOWN_ERROR
+    default_status_code: int = status.HTTP_500_INTERNAL_SERVER_ERROR
+    
+    def __init__(
+        self,
+        message: str | None = None,
+        code: str | ErrorCode | None = None,
+        status_code: int | None = None,
+        details: list[ErrorDetail] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """初始化异常。
+        
+        Args:
+            message: 错误消息（默认使用类的 default_message）
+            code: 错误代码（默认使用类的 default_code）
+            status_code: HTTP状态码（默认使用类的 default_status_code）
+            details: 错误详情
+            metadata: 元数据
+        """
+        self.message = message or self.default_message
+        self.code = code or self.default_code
+        self.status_code = status_code or self.default_status_code
+        self.details = details or []
+        self.metadata = metadata or {}
+        super().__init__(self.message)
+    
+    def to_dict(self) -> dict[str, Any]:
+        """转换为字典。"""
+        code_value = self.code.value if isinstance(self.code, ErrorCode) else self.code
+        return {
+            "message": self.message,
+            "code": code_value,
+            "status_code": self.status_code,
+            "details": [detail.model_dump() for detail in self.details],
+            "metadata": self.metadata,
+        }
+    
+    def __repr__(self) -> str:
+        """字符串表示。"""
+        code_value = self.code.value if isinstance(self.code, ErrorCode) else self.code
+        return f"<{self.__class__.__name__} code={code_value} message={self.message}>"
+
+
+class ValidationError(BaseError):
+    """验证异常。"""
+    
+    default_message = "数据验证失败"
+    default_code = ErrorCode.VALIDATION_ERROR
+    default_status_code = status.HTTP_400_BAD_REQUEST
+
+
+class NotFoundError(BaseError):
+    """资源不存在异常。"""
+    
+    default_message = "资源不存在"
+    default_code = ErrorCode.NOT_FOUND
+    default_status_code = status.HTTP_404_NOT_FOUND
+    
+    def __init__(
+        self,
+        message: str | None = None,
+        resource: Any = None,
+        **kwargs
+    ) -> None:
+        if resource:
+            metadata = kwargs.get("metadata", {})
+            metadata["resource"] = str(resource)
+            kwargs["metadata"] = metadata
+        super().__init__(message=message, **kwargs)
+
+
+class AlreadyExistsError(BaseError):
+    """资源已存在异常。"""
+    
+    default_message = "资源已存在"
+    default_code = ErrorCode.ALREADY_EXISTS
+    default_status_code = status.HTTP_409_CONFLICT
+    
+    def __init__(
+        self,
+        message: str | None = None,
+        resource: Any = None,
+        **kwargs
+    ) -> None:
+        if resource:
+            metadata = kwargs.get("metadata", {})
+            metadata["resource"] = str(resource)
+            kwargs["metadata"] = metadata
+        super().__init__(message=message, **kwargs)
+
+
+class VersionConflictError(BaseError):
+    """版本冲突异常（乐观锁）。
+    
+    当使用 VersionedModel 时，如果更新时版本号不匹配，抛出此异常。
+    
+    注意：此异常继承自 BaseError，用于应用层（HTTP 响应）。
+        Domain 层的 VersionConflictError 在 domain.exceptions 中定义。
+    """
+    
+    def __init__(
+        self,
+        message: str = "数据已被其他操作修改，请刷新后重试",
+        current_version: int | None = None,
+        expected_version: int | None = None,
+        **kwargs
+    ) -> None:
+        metadata = kwargs.pop("metadata", {})
+        if current_version is not None:
+            metadata["current_version"] = current_version
+        if expected_version is not None:
+            metadata["expected_version"] = expected_version
+        
+        super().__init__(
+            message=message,
+            code=ErrorCode.VERSION_CONFLICT,
+            status_code=status.HTTP_409_CONFLICT,
+            metadata=metadata,
+            **kwargs
+        )
+    
+    @classmethod
+    def from_domain_exception(
+        cls,
+        exc: DomainVersionConflictError,
+    ) -> VersionConflictError:
+        """从 Domain 层的 VersionConflictError 创建应用层异常。
+        
+        Args:
+            exc: Domain 层的 VersionConflictError 异常
+            
+        Returns:
+            VersionConflictError: 应用层的异常对象
+        """
+        from aury.boot.domain.exceptions import VersionConflictError as DomainVersionConflictError
+        
+        if isinstance(exc, DomainVersionConflictError):
+            return cls(
+                message=exc.message,
+                current_version=exc.current_version,
+                expected_version=exc.expected_version,
+            )
+        # 不应该到达这里
+        return cls(message=str(exc))
+
+
+class UnauthorizedError(BaseError):
+    """未授权异常。"""
+    
+    default_message = "未授权访问"
+    default_code = ErrorCode.UNAUTHORIZED
+    default_status_code = status.HTTP_401_UNAUTHORIZED
+
+
+class ForbiddenError(BaseError):
+    """禁止访问异常。"""
+    
+    default_message = "禁止访问"
+    default_code = ErrorCode.FORBIDDEN
+    default_status_code = status.HTTP_403_FORBIDDEN
+
+
+class DatabaseError(BaseError):
+    """数据库异常。"""
+    
+    default_message = "数据库错误"
+    default_code = ErrorCode.DATABASE_ERROR
+    default_status_code = status.HTTP_500_INTERNAL_SERVER_ERROR
+
+
+class BusinessError(BaseError):
+    """业务逻辑异常。"""
+    
+    default_message = "业务错误"
+    default_code = ErrorCode.BUSINESS_ERROR
+    default_status_code = status.HTTP_400_BAD_REQUEST
+
+
+__all__ = [
+    "AlreadyExistsError",
+    "BaseError",
+    "BusinessError",
+    "DatabaseError",
+    "ForbiddenError",
+    "NotFoundError",
+    "UnauthorizedError",
+    "ValidationError",
+    "VersionConflictError",
+]
+