fastapi-augment 0.1.0__py3-none-any.whl

fastapi_augment/schemas/pagination.py

@@ -0,0 +1,46 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/9/1
+@Description    : 分页响应模型 PageData，对外输出，继承APISchemaBase
+"""
+from __future__ import annotations
+
+from math import ceil
+from typing import Generic, Sequence
+
+from pydantic import Field
+
+from .base import SchemaBase
+from .types import T
+
+
+class PageData(SchemaBase, Generic[T]):
+    """通用分页返回体"""
+    items: Sequence[T] = Field(default_factory=list, description='当前页数据列表')
+    page: int = Field(default=1, description='当前页码')
+    size: int = Field(default=10, description='每页数量')
+    pages: int = Field(default=0, description='总页数')
+    total: int = Field(default=0, description='总记录数')
+
+    @classmethod
+    def build(
+            cls,
+            items: list[T] | Sequence[T],
+            *,
+            page: int,
+            size: int,
+            total: int
+    ) -> 'PageData[T]':
+        """构建分页对象，自动计算总页数
+
+        Args:
+            items: 当前页数据列表
+            page: 当前页码
+            size: 每页数量
+            total: 总记录数
+
+        Returns:
+            分页对象
+        """
+        pages = ceil(total / size) if size > 0 else 0
+        return cls(items=items, page=page, size=size, pages=pages, total=total)

fastapi_augment/schemas/request.py

@@ -0,0 +1,28 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/9/1
+@Description    : 请求参数定义
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from pydantic import Field
+
+from .base import SchemaBase
+
+
+class PageParams(SchemaBase):
+    """通用分页请求参数"""
+    page: int = Field(default=1, description='当前页码', ge=1)
+    size: int = Field(default=100, description='每页数量', ge=1, le=1000)
+
+
+class TimeRangeParams(SchemaBase):
+    """通用时间范围查询参数"""
+    start_time: datetime | None = Field(default=None, description='开始时间')
+    end_time: datetime | None = Field(default=None, description='结束时间')
+
+
+class KeywordParams(SchemaBase):
+    """通用关键字搜索参数"""
+    keyword: str | None = Field(default=None, description='搜索关键字', max_length=100)

fastapi_augment/schemas/response.py

@@ -0,0 +1,139 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/9/1
+@Description    : 统一API响应模型与工厂函数
+"""
+from __future__ import annotations
+
+from typing import Generic, overload
+
+from pydantic import Field
+
+from .base import SchemaBase
+from .types import T, E
+
+CODE_SUCCESS = 0
+
+# ====================== request_id 默认值 ======================
+def _default_request_id() -> str:
+    """获取当前请求ID，无请求上下文返回空字符串
+
+    Returns:
+        请求ID
+    """
+    # 延迟导入，避免循环依赖
+    from ..middlewares import get_request_id
+    return get_request_id() or ''
+
+
+# ====================== API响应模型 ======================
+class APIResponse(SchemaBase, Generic[T, E]):
+    """全局统一返回格式
+
+    request_id: 自动从 ContextVar 获取当前请求ID；无请求上下文返回空字符串
+    """
+    request_id: str = Field(default_factory=_default_request_id, description='请求唯一追踪ID')
+    code: int = Field(default=CODE_SUCCESS, description='业务码，0代表成功')
+    message: str = Field(default='操作成功', description='提示文案')
+    data: T | None = Field(default=None, description='业务主体数据')
+    extra: E | None = Field(default=None, description='扩展附加信息')
+
+
+# ====================== 工厂函数 overload 重载，优化IDE泛型推导 ======================
+@overload
+def build_response(*, code: int = CODE_SUCCESS, message: str = '操作成功') -> APIResponse[None, None]: ...
+
+
+@overload
+def build_response(*, code: int = CODE_SUCCESS, message: str = '操作成功', data: T) -> APIResponse[T, None]: ...
+
+
+@overload
+def build_response(*, code: int = CODE_SUCCESS, message: str = '操作成功', extra: E) -> APIResponse[None, E]: ...
+
+
+@overload
+def build_response(*, code: int = CODE_SUCCESS, message: str = '操作成功', data: T, extra: E) -> APIResponse[T, E]: ...
+
+
+def build_response(
+        *,
+        code: int = CODE_SUCCESS,
+        message: str = '操作成功',
+        data: T | None = None,
+        extra: E | None = None,
+) -> APIResponse[T, E]:
+    """底层构建响应，优先使用 response_success / response_fail
+
+    Args:
+        code: 业务码，0代表成功
+        message: 提示文案
+        data: 业务主体数据
+        extra: 扩展附加信息
+
+    Returns:
+        APIResponse[T, E]
+    """
+    return APIResponse(code=code, message=message, data=data, extra=extra)
+
+
+@overload
+def response_success(*, message: str = '操作成功') -> APIResponse[None, None]: ...
+
+
+@overload
+def response_success(*, message: str = '操作成功', data: T) -> APIResponse[T, None]: ...
+
+
+@overload
+def response_success(*, message: str = '操作成功', extra: E) -> APIResponse[None, E]: ...
+
+
+@overload
+def response_success(*, message: str = '操作成功', data: T, extra: E) -> APIResponse[T, E]: ...
+
+
+def response_success(
+        *,
+        message: str = '操作成功',
+        data: T | None = None,
+        extra: E | None = None,
+) -> APIResponse[T, E]:
+    """构造成功响应
+
+    Args:
+        message: 提示文案
+        data: 业务主体数据
+        extra: 扩展附加信息
+
+    Returns:
+        APIResponse[T, E]
+    """
+    return build_response(code=CODE_SUCCESS, message=message, data=data, extra=extra)
+
+
+@overload
+def response_fail(*, code: int, message: str = '操作失败') -> APIResponse[None, None]: ...
+
+
+@overload
+def response_fail(*, code: int, message: str = '操作失败', extra: E) -> APIResponse[None, E]: ...
+
+
+def response_fail(
+        *,
+        code: int,
+        message: str = '操作失败',
+        extra: E | None = None,
+) -> APIResponse[None, E]:
+    """构造失败响应，给业务代码 & fastapi_handlers异常处理器使用
+
+    Args:
+        code: 业务码，0代表成功
+        message: 提示文案
+        extra: 扩展附加信息
+
+    Returns:
+        APIResponse[None, E]
+    """
+    return build_response(code=code, message=message, extra=extra)

fastapi_augment/schemas/types.py

@@ -0,0 +1,11 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/9/1
+@Description    : 泛型类型变量定义
+"""
+from __future__ import annotations
+
+from typing import TypeVar
+
+T = TypeVar('T')
+E = TypeVar('E')  # 扩展结构体