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

aury/boot/application/errors/handlers.py

@@ -0,0 +1,320 @@
+"""错误处理器实现。
+
+提供责任链模式的错误处理器。
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from fastapi import HTTPException, Request, status
+from fastapi.responses import JSONResponse
+from pydantic import ValidationError
+from sqlalchemy.exc import IntegrityError, SQLAlchemyError
+
+from aury.boot.common.exceptions import FoundationError
+from aury.boot.common.logging import logger
+from aury.boot.domain.exceptions import (
+    ModelError,
+    ServiceException,
+)
+from aury.boot.domain.exceptions import (
+    VersionConflictError as DomainVersionConflictError,
+)
+from aury.boot.infrastructure.database.exceptions import (
+    DatabaseError as InfraDatabaseError,
+)
+
+from ..interfaces.egress import ResponseBuilder
+from .exceptions import BaseError, BusinessError, VersionConflictError
+from .response import ErrorDetail
+
+
+class ErrorHandler(ABC):
+    """错误处理器抽象基类 - 责任链模式。"""
+    
+    def __init__(self) -> None:
+        """初始化处理器。"""
+        self._next_handler: ErrorHandler | None = None
+    
+    def set_next(self, handler: ErrorHandler) -> ErrorHandler:
+        """设置下一个处理器。
+        
+        Args:
+            handler: 下一个处理器
+            
+        Returns:
+            ErrorHandler: 下一个处理器（支持链式调用）
+        """
+        self._next_handler = handler
+        return handler
+    
+    @abstractmethod
+    def can_handle(self, exception: Exception) -> bool:
+        """判断是否可以处理该异常。
+        
+        Args:
+            exception: 异常对象
+            
+        Returns:
+            bool: 是否可以处理
+        """
+        pass
+    
+    @abstractmethod
+    async def handle(self, exception: Exception, request: Request) -> JSONResponse:
+        """处理异常。
+        
+        Args:
+            exception: 异常对象
+            request: 请求对象
+            
+        Returns:
+            JSONResponse: 响应对象
+        """
+        pass
+    
+    async def process(self, exception: Exception, request: Request) -> JSONResponse:
+        """处理异常（责任链入口）。
+        
+        Args:
+            exception: 异常对象
+            request: 请求对象
+            
+        Returns:
+            JSONResponse: 响应对象
+        """
+        if self.can_handle(exception):
+            return await self.handle(exception, request)
+        
+        if self._next_handler:
+            return await self._next_handler.process(exception, request)
+        
+        # 默认处理
+        return await self._default_handle(exception, request)
+    
+    async def _default_handle(self, exception: Exception, request: Request) -> JSONResponse:
+        """默认异常处理。"""
+        logger.exception(f"未处理的异常: {request.method} {request.url.path}")
+        
+        response = ResponseBuilder.fail(
+            message="服务器内部错误",
+            code=-1,
+        )
+        return JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content=response.model_dump(mode="json"),
+        )
+
+
+class BaseErrorHandler(ErrorHandler):
+    """自定义基础异常处理器。"""
+    
+    def can_handle(self, exception: Exception) -> bool:
+        """判断是否为自定义异常。"""
+        return isinstance(exception, BaseError)
+    
+    async def handle(self, exception: BaseError, request: Request) -> JSONResponse:
+        """处理自定义异常。"""
+        logger.warning(f"业务异常: {exception}")
+        
+        errors = [detail.model_dump() for detail in exception.details] if exception.details else None
+        
+        response = ResponseBuilder.fail(
+            message=exception.message,
+            code=int(exception.code.value),
+            errors=errors,
+        )
+        
+        # metadata 放入 details 字段
+        if exception.metadata:
+            response.details = exception.metadata
+        
+        return JSONResponse(
+            status_code=exception.status_code,
+            content=response.model_dump(mode="json"),
+        )
+
+
+class HTTPExceptionHandler(ErrorHandler):
+    """FastAPI HTTP异常处理器。"""
+    
+    def can_handle(self, exception: Exception) -> bool:
+        """判断是否为HTTP异常。"""
+        return isinstance(exception, HTTPException)
+    
+    async def handle(self, exception: HTTPException, request: Request) -> JSONResponse:
+        """处理HTTP异常。"""
+        logger.warning(f"HTTP异常: {exception.status_code} - {exception.detail}")
+        
+        response = ResponseBuilder.fail(
+            message=exception.detail,
+            code=exception.status_code,
+        )
+        
+        return JSONResponse(
+            status_code=exception.status_code,
+            content=response.model_dump(mode="json"),
+        )
+
+
+class ValidationErrorHandler(ErrorHandler):
+    """Pydantic验证异常处理器。"""
+    
+    def can_handle(self, exception: Exception) -> bool:
+        """判断是否为验证异常。"""
+        return isinstance(exception, ValidationError)
+    
+    async def handle(self, exception: Exception, request: Request) -> JSONResponse:
+        """处理验证异常。"""
+        logger.warning(f"数据验证失败: {exception}")
+        
+        errors = []
+        for error in exception.errors():
+            errors.append({
+                "field": ".".join(str(loc) for loc in error["loc"]),
+                "message": error["msg"],
+                "type": error["type"],
+            })
+        
+        response = ResponseBuilder.fail(
+            message="数据验证失败",
+            code=400,
+            errors=errors,
+        )
+        
+        return JSONResponse(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            content=response.model_dump(mode="json"),
+        )
+
+
+class ServiceErrorHandler(ErrorHandler):
+    """服务层异常处理器。
+    
+    处理 Domain 层的 ServiceException。
+    """
+    
+    def can_handle(self, exception: Exception) -> bool:
+        """判断是否为服务层异常。"""
+        return isinstance(exception, ServiceException)
+    
+    async def handle(self, exception: Exception, request: Request) -> JSONResponse:
+        """处理服务层异常。"""
+        if not isinstance(exception, ServiceException):
+            return await self._default_handle(exception, request)
+        
+        logger.warning(f"服务层异常: {exception}")
+        
+        # 直接使用 ServiceException 的信息
+        response = ResponseBuilder.fail(
+            message=exception.message,
+            code=400,  # 服务层异常默认 400
+        )
+        
+        # 构建 details
+        details: dict = {}
+        if exception.code:
+            details["code"] = exception.code
+        if exception.metadata:
+            details.update(exception.metadata)
+        if details:
+            response.details = details
+        
+        return JSONResponse(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            content=response.model_dump(mode="json"),
+        )
+
+
+class DatabaseErrorHandler(ErrorHandler):
+    """数据库异常处理器。
+    
+    处理数据库相关错误，包括 Domain 层的异常。
+    """
+    
+    def can_handle(self, exception: Exception) -> bool:
+        """判断是否为数据库异常。"""
+        return isinstance(exception, SQLAlchemyError | ModelError | InfraDatabaseError | FoundationError)
+    
+    async def handle(self, exception: Exception, request: Request) -> JSONResponse:
+        """处理数据库异常。"""
+        # 处理 Domain 层的 VersionConflictError
+        if isinstance(exception, DomainVersionConflictError):
+            # 转换为应用层异常
+            app_error = VersionConflictError.from_domain_exception(exception)
+            response = ResponseBuilder.fail(
+                message=app_error.message,
+                code=app_error.status_code,
+                details=[ErrorDetail(
+                    message=app_error.message,
+                    code=app_error.code.value,
+                )],
+            )
+            return JSONResponse(
+                status_code=app_error.status_code,
+                content=response.model_dump(mode="json"),
+            )
+        
+        # 处理唯一约束冲突（如重复的 email、username 等）
+        if isinstance(exception, IntegrityError):
+            logger.warning(f"数据库完整性约束冲突: {exception}")
+            
+            # 解析错误信息，提取字段名
+            error_msg = str(exception.orig) if exception.orig else str(exception)
+            field_name = None
+            
+            # 尝试从错误信息中提取字段名
+            if "unique constraint" in error_msg.lower() or "duplicate key" in error_msg.lower():
+                # PostgreSQL: Key (email)=(xxx) already exists
+                # MySQL: Duplicate entry 'xxx' for key 'users.email'
+                import re
+                # PostgreSQL 格式
+                match = re.search(r"Key \((\w+)\)", error_msg)
+                if match:
+                    field_name = match.group(1)
+                else:
+                    # MySQL 格式
+                    match = re.search(r"for key ['\"]?\w+\.(\w+)['\"]?", error_msg, re.IGNORECASE)
+                    if match:
+                        field_name = match.group(1)
+            
+            if field_name:
+                message = f"{field_name} 已存在"
+            else:
+                message = "数据已存在，请检查唯一字段"
+            
+            response = ResponseBuilder.fail(
+                message=message,
+                code=409,
+            )
+            
+            return JSONResponse(
+                status_code=status.HTTP_409_CONFLICT,
+                content=response.model_dump(mode="json"),
+            )
+        
+        # 处理其他数据库错误
+        logger.exception(f"数据库错误: {request.method} {request.url.path}")
+        
+        response = ResponseBuilder.fail(
+            message="数据库操作失败",
+            code=500,
+        )
+        
+        return JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content=response.model_dump(mode="json"),
+        )
+
+
+__all__ = [
+    "BaseErrorHandler",
+    "DatabaseErrorHandler",
+    "ErrorHandler",
+    "HTTPExceptionHandler",
+    "ServiceErrorHandler",
+    "ValidationErrorHandler",
+]
+

aury/boot/application/errors/response.py

@@ -0,0 +1,120 @@
+"""错误响应模型（接口层）。
+
+提供用于 HTTP API 响应的错误详情模型。
+这是接口层的数据模型，用于序列化和传输。
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ErrorDetail(BaseModel):
+    """错误详情模型（Pydantic）。
+    
+    支持两种错误类型：
+    1. 字段错误：field不为空，表示特定字段的验证错误
+    2. 通用错误：field为空，表示系统级或业务级错误
+    
+    使用示例:
+        # 字段验证错误
+        ErrorDetail(
+            field="username",
+            message="用户名格式不正确",
+            code="INVALID_FORMAT",
+            location="body"
+        )
+        
+        # 通用业务错误
+        ErrorDetail(
+            message="库存不足",
+            code="INSUFFICIENT_STOCK"
+        )
+        
+        # 系统错误
+        ErrorDetail(
+            message="数据库连接失败",
+            code="DB_CONNECTION_ERROR"
+        )
+    """
+    
+    message: str = Field(..., description="错误消息")
+    code: str | None = Field(None, description="错误代码")
+    field: str | None = Field(None, description="错误字段（仅字段验证错误）")
+    location: str | None = Field(None, description="错误位置（如：body, query, path）")
+    value: Any | None = Field(None, description="导致错误的值")
+    
+    @classmethod
+    def field_error(
+        cls,
+        field: str,
+        message: str,
+        code: str | None = None,
+        location: str = "body",
+        value: Any | None = None,
+    ) -> "ErrorDetail":
+        """创建字段验证错误。
+        
+        Args:
+            field: 字段名
+            message: 错误消息
+            code: 错误代码
+            location: 错误位置
+            value: 错误值
+            
+        Returns:
+            ErrorDetail: 错误详情对象
+        """
+        return cls(
+            message=message,
+            code=code,
+            field=field,
+            location=location,
+            value=value,
+        )
+    
+    @classmethod
+    def generic_error(
+        cls,
+        message: str,
+        code: str | None = None,
+    ) -> "ErrorDetail":
+        """创建通用错误。
+        
+        Args:
+            message: 错误消息
+            code: 错误代码
+            
+        Returns:
+            ErrorDetail: 错误详情对象
+        """
+        return cls(
+            message=message,
+            code=code,
+        )
+    
+    model_config = ConfigDict(
+        json_schema_extra={
+            "examples": [
+                {
+                    "message": "用户名格式不正确",
+                    "code": "INVALID_FORMAT",
+                    "field": "username",
+                    "location": "body",
+                    "value": "user@123"
+                },
+                {
+                    "message": "库存不足",
+                    "code": "INSUFFICIENT_STOCK"
+                }
+            ]
+        }
+    )
+
+
+__all__ = [
+    "ErrorDetail",
+]
+

aury/boot/application/interfaces/__init__.py

@@ -0,0 +1,76 @@
+"""接口层模块。
+
+提供API定义，包括：
+- 错误处理
+- 请求模型（Ingress）
+- 响应模型（Egress）
+"""
+
+# 错误处理已移至 application.errors
+from ..errors import (
+    AlreadyExistsError,
+    BaseError,
+    BusinessError,
+    DatabaseError,
+    ErrorCode,
+    ErrorDetail,
+    ErrorHandler,
+    ErrorHandlerChain,
+    ForbiddenError,
+    NotFoundError,
+    UnauthorizedError,
+    ValidationError,
+    VersionConflictError,
+    global_exception_handler,
+)
+from .egress import (
+    BaseResponse,
+    CountResponse,
+    ErrorResponse,
+    IDResponse,
+    Pagination,
+    PaginationResponse,
+    ResponseBuilder,
+    SuccessResponse,
+)
+from .ingress import (
+    BaseRequest,
+    FilterRequest,
+    ListRequest,
+    PaginationRequest,
+    SortOrder,
+)
+
+__all__ = [
+    "AlreadyExistsError",
+    "BaseError",
+    # 请求模型
+    "BaseRequest",
+    # 响应模型
+    "BaseResponse",
+    "BusinessError",
+    "CountResponse",
+    "DatabaseError",
+    # 错误处理
+    "ErrorCode",
+    "ErrorDetail",
+    "ErrorHandler",
+    "ErrorHandlerChain",
+    "ErrorResponse",
+    "FilterRequest",
+    "ForbiddenError",
+    "IDResponse",
+    "ListRequest",
+    "NotFoundError",
+    "Pagination",
+    "PaginationRequest",
+    "PaginationResponse",
+    "ResponseBuilder",
+    "SortOrder",
+    "SuccessResponse",
+    "UnauthorizedError",
+    "ValidationError",
+    "VersionConflictError",
+    "global_exception_handler",
+]
+