⚒️ 重大重构 LoveACE V2

引入了 mongodb
对数据库进行了一定程度的数据加密
性能改善
代码简化
统一错误模型和响应
使用 apifox 作为文档

loveace/router/schemas/__init__.py

@@ -0,0 +1,15 @@
+"""Router schemas module"""
+
+from loveace.router.schemas.base import (
+    ErrorModel,
+    ErrorToCode,
+    ErrorToCodeNode,
+)
+from loveace.router.schemas.error import ProtectRouterErrorToCode
+
+__all__ = [
+    "ErrorModel",
+    "ErrorToCodeNode",
+    "ErrorToCode",
+    "ProtectRouterErrorToCode",
+]

loveace/router/schemas/base.py

@@ -0,0 +1,178 @@
+"""
+定义请求和响应的基础模型，以及错误处理模型
+"""
+
+from typing import Annotated, Any, Dict
+
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
+
+from loveace.router.schemas.exception import UniResponseHTTPException
+from loveace.router.schemas.model import (
+    ErrorModel,
+    ValidationErrorDetail,
+    ValidationErrorModel,
+)
+from loveace.router.schemas.uniresponse import UniResponseModel
+
+
+class ErrorToCodeNode(BaseModel):
+    message: str = Field(..., description="错误信息")
+    error_code: int = Field(..., description="错误代码")
+    code: str = Field(..., description="错误短ID")
+
+    def to_http_exception(
+        self, trace_id: str, message: str | None = None
+    ) -> UniResponseHTTPException:
+        """
+        将错误信息转换为HTTPException，次方法使用于 依赖注入 | 中间件 | 抛出异常 的情况，请 raise 此异常。
+        """
+        return UniResponseHTTPException(
+            status_code=self.error_code,
+            uni_response=UniResponseModel(
+                success=False,
+                data=None,
+                error=ErrorModel(
+                    message=message if message else self.message,
+                    code=self.code,
+                    trace_id=trace_id,
+                ),
+                message=None,
+            ),
+        )
+
+    def to_json_response(
+        self, trace_id: str, message: str | None = None
+    ) -> JSONResponse:
+        """
+        将错误信息转换为JSONResponse，适用于一个标准 Router 的返回。
+        """
+        return JSONResponse(
+            status_code=self.error_code,
+            content=UniResponseModel(
+                success=False,
+                data=None,
+                error=ErrorModel(
+                    message=message if message else self.message,
+                    code=self.code,
+                    trace_id=trace_id,
+                ),
+                message=None,
+            ).model_dump(),
+        )
+
+
+class ErrorToCode(BaseModel):
+
+    VALIDATION_ERROR: ErrorToCodeNode = ErrorToCodeNode(
+        message="请求参数验证错误",
+        error_code=422,
+        code="VALIDATION_ERROR",
+    )
+
+    @classmethod
+    def gen_code_table(cls) -> Dict[str | int, Dict[str, Any]]:
+        """
+        生成FastAPI兼容的响应文档格式
+        支持同一状态码下的多个模型示例
+        对 422 状态码进行特殊处理，使用 ValidationErrorDetail
+        """
+        data = cls().model_dump()
+        status_info = {}
+
+        # 按状态码分组错误信息
+        for k, v in data.items():
+            status_code = str(v["error_code"])
+            if status_code not in status_info:
+                status_info[status_code] = {"descriptions": [], "examples": []}
+
+            # 添加描述
+            status_info[status_code]["descriptions"].append(v["message"])
+
+            # 对 422 状态码进行特殊处理
+            if v["error_code"] == 422:
+                # 使用 ValidationErrorDetail 作为示例
+                example_detail = ValidationErrorModel(
+                    message="请求参数验证失败",
+                    code=v["code"],
+                    trace_id="",
+                    details=[
+                        ValidationErrorDetail(
+                            loc=["body", "field_name"],
+                            msg="field required",
+                            type="value_error.missing",
+                        )
+                    ],
+                )
+            else:
+                # 其他状态码使用 ErrorModel
+                example_detail = ErrorModel(
+                    message=v["message"],
+                    code=v["code"],
+                    trace_id="",
+                )
+
+            status_info[status_code]["examples"].append(
+                {
+                    "summary": f"{v['code']} 错误",
+                    "description": v["message"],
+                    "value": UniResponseModel(
+                        success=False,
+                        message=None,
+                        data=None,
+                        error=example_detail,
+                    ).model_dump(),
+                }
+            )
+
+        # 构建FastAPI响应格式
+        responses = {}
+        for status_code, info in status_info.items():
+            descriptions = info["descriptions"]
+            examples = info["examples"]
+
+            # 合并描述
+            if len(descriptions) == 1:
+                combined_description = descriptions[0]
+            else:
+                combined_description = "; ".join(descriptions)
+
+            # 对 422 状态码进行特殊处理
+            if status_code == "422":
+                # 为 422 创建专门的响应模型
+                response_def = {
+                    "model": Annotated[
+                        UniResponseModel,
+                        Field(
+                            description=combined_description,
+                            examples=[example["value"] for example in examples],
+                        ),
+                    ],
+                    "description": combined_description,
+                }
+            else:
+                # 其他状态码使用通用模型
+                response_def = {
+                    "model": UniResponseModel,
+                    "description": combined_description,
+                }
+
+            # 如果有示例，添加content字段
+            if examples:
+                # 创建examples字典
+                examples_dict = {}
+                for i, example in enumerate(examples):
+                    key = f"example_{i + 1}_{example['summary'].lower().replace(' ', '_').replace('错误', 'error')}"
+                    examples_dict[key] = {
+                        "summary": example["summary"],
+                        "description": example["description"],
+                        "value": example["value"],
+                    }
+
+                response_def["content"] = {
+                    "application/json": {"examples": examples_dict}
+                }
+
+            responses[status_code] = response_def
+
+        return responses

loveace/router/schemas/error.py

@@ -0,0 +1,65 @@
+"""
+经过一层封装的错误代码映射，专用于保护路由
+"""
+
+from fastapi import status
+
+from loveace.router.schemas.base import ErrorToCode, ErrorToCodeNode
+
+
+class ProtectRouterErrorToCode(ErrorToCode):
+    invalid_authentication: ErrorToCodeNode = ErrorToCodeNode(
+        message="无效的认证信息",
+        error_code=status.HTTP_401_UNAUTHORIZED,
+        code="INVALID_AUTHENTICATION",
+    )
+    forbidden: ErrorToCodeNode = ErrorToCodeNode(
+        message="禁止访问",
+        error_code=status.HTTP_403_FORBIDDEN,
+        code="FORBIDDEN",
+    )
+    cooldown: ErrorToCodeNode = ErrorToCodeNode(
+        message="请求过于频繁，请稍后再试",
+        error_code=status.HTTP_429_TOO_MANY_REQUESTS,
+        code="COOLDOWN",
+    )
+    user_need_reset_password: ErrorToCodeNode = ErrorToCodeNode(
+        message="用户需要重置密码",
+        error_code=status.HTTP_403_FORBIDDEN,
+        code="USER_NEED_RESET_PASSWORD",
+    )
+    remote_service_error: ErrorToCodeNode = ErrorToCodeNode(
+        message="远程服务错误",
+        error_code=status.HTTP_502_BAD_GATEWAY,
+        code="REMOTE_SERVICE_ERROR",
+    )
+    validation_error: ErrorToCodeNode = ErrorToCodeNode(
+        message="数据验证失败",
+        error_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        code="VALIDATION_ERROR",
+    )
+    server_error: ErrorToCodeNode = ErrorToCodeNode(
+        message="服务器错误",
+        error_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        code="SERVER_ERROR",
+    )
+    null_response: ErrorToCodeNode = ErrorToCodeNode(
+        message="远程服务返回空响应",
+        error_code=status.HTTP_502_BAD_GATEWAY,
+        code="NULL_RESPONSE",
+    )
+    timeout: ErrorToCodeNode = ErrorToCodeNode(
+        message="请求远程服务超时",
+        error_code=status.HTTP_504_GATEWAY_TIMEOUT,
+        code="TIMEOUT",
+    )
+    unknown_error: ErrorToCodeNode = ErrorToCodeNode(
+        message="未知错误",
+        error_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        code="UNKNOWN",
+    )
+    empty_path: ErrorToCodeNode = ErrorToCodeNode(
+        message="请求路径不能为空",
+        error_code=status.HTTP_400_BAD_REQUEST,
+        code="EMPTY_PATH",
+    )

loveace/router/schemas/exception.py

@@ -0,0 +1,11 @@
+from loveace.router.schemas.uniresponse import UniResponseModel
+
+
+class UniResponseHTTPException(Exception):
+    """
+    统一响应格式的 HTTP 异常，用于在路由中直接抛出异常时使用。
+    """
+
+    def __init__(self, status_code: int, uni_response: UniResponseModel):
+        self.status_code = status_code
+        self.uni_response = uni_response

loveace/router/schemas/model.py

@@ -0,0 +1,19 @@
+from typing import Any, List
+
+from pydantic import BaseModel, Field
+
+
+class ErrorModel(BaseModel):
+    message: str = Field(..., description="详细信息")
+    code: str = Field(..., description="错误短ID")
+    trace_id: str = Field(..., description="trace_id")
+
+
+class ValidationErrorDetail(BaseModel):
+    loc: List[Any] = Field(..., description="错误位置")
+    msg: str = Field(..., description="错误信息")
+    type: str = Field(..., description="错误类型")
+
+
+class ValidationErrorModel(ErrorModel):
+    details: List[ValidationErrorDetail] = Field(..., description="验证错误详情")

loveace/router/schemas/uniresponse.py

@@ -0,0 +1,45 @@
+import time
+from typing import Generic, TypeVar, Union
+
+from pydantic import BaseModel, Field
+
+from loveace.router.schemas.model import ErrorModel, ValidationErrorModel
+
+T = TypeVar("T")
+
+
+class UniResponseModel(BaseModel, Generic[T]):
+    """
+    统一响应模型，适用于所有API响应。
+    Attributes:
+        success (bool): 操作是否成功。
+        message (str | None): 操作的详细信息。
+        data (ResponseModel | None): 操作返回的数据。
+        error (DetailModel | None): 操作错误信息，支持 ErrorModel 或 ValidationErrorDetail。
+        timestamp (str): 响应生成的时间戳，格式为 "YYYY-MM-DD HH:MM:SS"。
+    """
+
+    success: bool = Field(..., description="操作是否成功")
+    message: str | None = Field(..., description="操作的详细信息")
+    data: T | None = Field(..., description="操作返回的数据")
+    error: Union[ErrorModel, ValidationErrorModel] | None = Field(
+        None, description="操作错误信息"
+    )
+    timestamp: str = Field(
+        default_factory=lambda: time.strftime("%Y-%m-%d %H:%M:%S", time.localtime()),
+        description="响应生成的时间戳",
+    )
+
+    @classmethod
+    def from_response(
+        cls,
+        success: bool,
+        message: str,
+        data: T | None = None,
+    ) -> "UniResponseModel":
+        return cls(
+            success=success,
+            message=message,
+            data=data,
+            error=None,
+        )