fastapi-augment 0.1.0__py3-none-any.whl

fastapi_augment/__init__.py

@@ -0,0 +1,24 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/8/31
+@Description    : fastapi-augment — FastAPI 通用代码工具包，跨项目复用
+"""
+from .factory import create_app
+from .lifespan import (
+    HookFunc,
+    HookRegistry,
+    core_registry,
+    fastapi_lifespan,
+    clear_hooks
+)
+
+__all__ = [
+    # factory
+    'create_app',
+    # lifespan
+    'HookFunc',
+    'HookRegistry',
+    'core_registry',
+    'fastapi_lifespan',
+    'clear_hooks'
+]

fastapi_augment/common/__init__.py

@@ -0,0 +1,61 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/9/4
+@Description    : 通用模块 — 异常 / 异常处理器 / 常量
+"""
+from .constants import DEFAULT_ERR_MSG
+from .exceptions import (
+    BaseHttpError,
+    BadRequestError,
+    UnauthorizedError,
+    PaymentRequiredError,
+    ForbiddenError,
+    NotFoundError,
+    MethodNotAllowedError,
+    NotAcceptableError,
+    RequestTimeoutError,
+    ConflictError,
+    GoneError,
+    PreconditionFailedError,
+    PayloadTooLargeError,
+    URITooLongError,
+    UnsupportedMediaTypeError,
+    LockedError,
+    TooManyRequestsError
+)
+from .exception_handlers import (
+    base_http_error_handler,
+    http_exception_handler,
+    validation_exception_handler,
+    general_exception_handler,
+    register_exception_handlers
+)
+
+__all__ = [
+    # constants
+    'DEFAULT_ERR_MSG',
+    # exceptions
+    'BaseHttpError',
+    'BadRequestError',
+    'UnauthorizedError',
+    'PaymentRequiredError',
+    'ForbiddenError',
+    'NotFoundError',
+    'MethodNotAllowedError',
+    'NotAcceptableError',
+    'RequestTimeoutError',
+    'ConflictError',
+    'GoneError',
+    'PreconditionFailedError',
+    'PayloadTooLargeError',
+    'URITooLongError',
+    'UnsupportedMediaTypeError',
+    'LockedError',
+    'TooManyRequestsError',
+    # exception handlers
+    'base_http_error_handler',
+    'http_exception_handler',
+    'validation_exception_handler',
+    'general_exception_handler',
+    'register_exception_handlers'
+]

fastapi_augment/common/constants.py

@@ -0,0 +1,26 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/9/4
+@Description    :
+"""
+from starlette import status
+
+# ===================== 统一默认文案常量（便于统一修改/国际化） =====================
+DEFAULT_ERR_MSG: dict[int, str] = {
+    status.HTTP_400_BAD_REQUEST: 'Bad request',
+    status.HTTP_401_UNAUTHORIZED: 'Unauthorized',
+    status.HTTP_402_PAYMENT_REQUIRED: 'Payment required',
+    status.HTTP_403_FORBIDDEN: 'Forbidden',
+    status.HTTP_404_NOT_FOUND: 'Not found',
+    status.HTTP_405_METHOD_NOT_ALLOWED: 'Method not allowed',
+    status.HTTP_406_NOT_ACCEPTABLE: 'Not acceptable',
+    status.HTTP_408_REQUEST_TIMEOUT: 'Request timeout',
+    status.HTTP_409_CONFLICT: 'Conflict',
+    status.HTTP_410_GONE: 'Gone',
+    status.HTTP_412_PRECONDITION_FAILED: 'Precondition failed',
+    status.HTTP_413_CONTENT_TOO_LARGE: 'Payload too large',
+    status.HTTP_414_URI_TOO_LONG: 'URI too long',
+    status.HTTP_415_UNSUPPORTED_MEDIA_TYPE: 'Unsupported media type',
+    status.HTTP_423_LOCKED: 'Locked',
+    status.HTTP_429_TOO_MANY_REQUESTS: 'Too many requests',
+}

fastapi_augment/common/exception_handlers.py

@@ -0,0 +1,178 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/9/4
+@Description    : 全局统一异常处理器
+                  - 将各类异常转换为统一的 APIResponse JSON 格式
+                  - 提供 register_exception_handlers 一键注册到 FastAPI 应用
+"""
+from __future__ import annotations
+
+from logging import getLogger
+
+from fastapi import FastAPI
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException
+from starlette.requests import Request
+
+from .exceptions import BaseHttpError
+from ..schemas.response import response_fail
+
+_logger = getLogger(__name__)
+
+
+# ===================== 业务异常处理器 =====================
+
+async def base_http_error_handler(
+        _request: Request,
+        exc: BaseHttpError,
+) -> JSONResponse:
+    """处理 BaseHttpError 及其所有子类（统一业务异常）。
+
+    将业务异常转换为统一 APIResponse 格式，
+    HTTP 状态码与 exc.status_code 一致，
+    body.code 同样使用 HTTP 状态码，body.message 使用 exc.detail。
+
+    Args:
+        _request: Starlette Request 对象
+        exc: 业务异常实例
+
+    Returns:
+        统一格式的 JSON 响应
+    """
+    body = response_fail(code=exc.status_code, message=exc.detail or '请求错误')
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=body.model_dump(mode='json', by_alias=True),
+        headers=exc.headers,
+    )
+
+
+# ===================== 通用 HTTP 异常处理器 =====================
+
+async def http_exception_handler(
+        _request: Request,
+        exc: HTTPException,
+) -> JSONResponse:
+    """处理 Starlette/FastAPI 原生 HTTPException。
+
+    覆盖 FastAPI 默认处理器，将响应格式统一为 APIResponse。
+    注意：BaseHttpError 继承自 HTTPException，但 FastAPI 会优先匹配
+    更具体的处理器（base_http_error_handler），所以此处不会拦截业务异常。
+
+    Args:
+        _request: Starlette Request 对象
+        exc: HTTPException 实例
+
+    Returns:
+        统一格式的 JSON 响应
+    """
+    body = response_fail(
+        code=exc.status_code,
+        message=exc.detail if isinstance(exc.detail, str) else str(exc.detail or ''),
+    )
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=body.model_dump(mode='json', by_alias=True),
+        headers=getattr(exc, 'headers', None),
+    )
+
+
+# ===================== 请求校验异常处理器 =====================
+
+async def validation_exception_handler(
+        _request: Request,
+        exc: RequestValidationError,
+) -> JSONResponse:
+    """处理 Pydantic 请求参数校验异常（422）。
+
+    将校验错误详情提取到 extra.errors 中，方便前端定位具体字段。
+
+    Args:
+        _request: Starlette Request 对象
+        exc: RequestValidationError 实例
+
+    Returns:
+        统一格式的 JSON 响应（HTTP 422）
+    """
+    errors = []
+    for error in exc.errors():
+        field = ' -> '.join(str(loc) for loc in error['loc'])
+        errors.append({
+            'field': field,
+            'message': error['msg'],
+            'type': error['type'],
+        })
+
+    body = response_fail(
+        code=422,
+        message='请求参数校验失败',
+        extra={'errors': errors},
+    )
+    return JSONResponse(
+        status_code=422,
+        content=body.model_dump(mode='json', by_alias=True),
+    )
+
+
+# ===================== 未知异常处理器 =====================
+
+async def general_exception_handler(
+        _request: Request,
+        exc: Exception,
+) -> JSONResponse:
+    """处理所有未被捕获的异常（兜底）。
+
+    记录完整异常日志（含堆栈），但响应体只返回通用提示，
+    避免将内部实现细节（堆栈、SQL 等）暴露给客户端。
+
+    Args:
+        _request: Starlette Request 对象
+        exc: 未捕获的异常实例
+
+    Returns:
+        统一格式的 JSON 响应（HTTP 500）
+    """
+    _logger.exception(f'[未捕获异常] {type(exc).__name__}: {exc}')
+    body = response_fail(code=500, message='服务器内部错误')
+    return JSONResponse(
+        status_code=500,
+        content=body.model_dump(mode='json', by_alias=True),
+    )
+
+
+# ===================== 一键注册 =====================
+
+def register_exception_handlers(app: FastAPI) -> None:
+    """将全部统一异常处理器注册到 FastAPI 应用。
+
+    注册后，以下异常会被转换为统一的 APIResponse 格式：
+        - BaseHttpError 及子类 → 对应 HTTP 状态码
+        - Starlette HTTPException → 对应 HTTP 状态码
+        - RequestValidationError → HTTP 422 + 字段级错误详情
+        - Exception（兜底） → HTTP 500
+
+    注意：create_app 工厂默认自动调用本函数（register_exceptions=True），
+    通常无需手动注册。仅在以下场景需要手动调用：
+        - 未使用 create_app 工厂，自行构建 FastAPI 实例时
+        - 传入 register_exceptions=False 禁用后，想选择性注册时
+
+    Example::
+
+        # 方式一：工厂自动注册（推荐）
+        app = create_app(title='My Service')
+
+        # 方式二：手动注册（未使用工厂时）
+        from fastapi import FastAPI
+        app = FastAPI()
+        register_exception_handlers(app)
+
+    Args:
+        app: FastAPI 应用实例
+    """
+    # 注意注册顺序：BaseHttpError 必须在 HTTPException 之前注册，
+    # 因为 BaseHttpError 继承自 HTTPException，FastAPI 优先匹配更具体的异常类型
+    app.add_exception_handler(BaseHttpError, base_http_error_handler)  # type: ignore
+    app.add_exception_handler(HTTPException, http_exception_handler)  # type: ignore
+    app.add_exception_handler(RequestValidationError, validation_exception_handler)  # type: ignore
+    app.add_exception_handler(Exception, general_exception_handler)  # type: ignore

fastapi_augment/common/exceptions.py

@@ -0,0 +1,162 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/9/4
+@Description    : 统一业务异常
+"""
+from typing import Any
+
+from starlette import status
+from starlette.exceptions import HTTPException
+
+from .constants import DEFAULT_ERR_MSG
+
+
+# ===================== 通用基类：统一封装 detail + headers 逻辑 =====================
+class BaseHttpError(HTTPException):
+    """统一HTTP异常基类，所有4xx异常继承此类，原生兼容starlette.HTTPException.
+
+    子类只需声明 ``_status_code`` 类变量，无需重写 __init__::
+
+        class NotFoundError(BaseHttpError):
+            _status_code = 404
+
+        raise NotFoundError()                        # 使用默认文案
+        raise NotFoundError(detail='用户不存在')       # 自定义提示
+
+    Attributes:
+        _status_code: 子类声明的HTTP状态码
+        status_code: HTTP状态码（继承自HTTPException）
+        detail: 异常提示文案
+        headers: 响应附加http头
+    """
+    __slots__ = ()
+    _status_code: int | None = None
+
+    def __init__(
+            self,
+            status_code: int | None = None,
+            detail: str | None = None,
+            headers: dict[str, Any] | None = None,
+    ):
+        """初始化http业务异常.
+
+        Args:
+            status_code: http响应状态码，不传则读取子类的 _status_code 类变量
+            detail: 自定义错误提示，不传使用内置默认文案
+            headers: 附加响应头
+
+        Raises:
+            KeyError: 传入未在DEFAULT_ERR_MSG定义的status_code
+        """
+        code = status_code if status_code is not None else self._status_code
+        if code is None:
+            raise TypeError(
+                f'{type(self).__name__} 必须声明 _status_code 类变量或传入 status_code 参数'
+            )
+        if code not in DEFAULT_ERR_MSG:
+            raise KeyError(f'status_code {code} not defined in DEFAULT_ERR_MSG')
+        msg = detail or DEFAULT_ERR_MSG[code]
+        super().__init__(status_code=code, detail=msg, headers=headers)
+
+
+# ===================== 各类4xx异常子类（极简声明，无重复__init__） =====================
+# 子类只需声明 _status_code 类变量，__init__ 由基类统一处理
+class BadRequestError(BaseHttpError):
+    """400 请求错误."""
+    _status_code = status.HTTP_400_BAD_REQUEST
+
+
+class UnauthorizedError(BaseHttpError):
+    """401 未授权错误."""
+    _status_code = status.HTTP_401_UNAUTHORIZED
+
+
+class PaymentRequiredError(BaseHttpError):
+    """402 需要付费错误."""
+    _status_code = status.HTTP_402_PAYMENT_REQUIRED
+
+
+class ForbiddenError(BaseHttpError):
+    """403 禁止访问错误."""
+    _status_code = status.HTTP_403_FORBIDDEN
+
+
+class NotFoundError(BaseHttpError):
+    """404 未找到资源."""
+    _status_code = status.HTTP_404_NOT_FOUND
+
+
+class MethodNotAllowedError(BaseHttpError):
+    """405 请求方法不允许."""
+    _status_code = status.HTTP_405_METHOD_NOT_ALLOWED
+
+
+class NotAcceptableError(BaseHttpError):
+    """406 客户端不支持返回格式."""
+    _status_code = status.HTTP_406_NOT_ACCEPTABLE
+
+
+class RequestTimeoutError(BaseHttpError):
+    """408 请求超时."""
+    _status_code = status.HTTP_408_REQUEST_TIMEOUT
+
+
+class ConflictError(BaseHttpError):
+    """409 资源冲突."""
+    _status_code = status.HTTP_409_CONFLICT
+
+
+class GoneError(BaseHttpError):
+    """410 资源已永久删除."""
+    _status_code = status.HTTP_410_GONE
+
+
+class PreconditionFailedError(BaseHttpError):
+    """412 前置校验失败."""
+    _status_code = status.HTTP_412_PRECONDITION_FAILED
+
+
+class PayloadTooLargeError(BaseHttpError):
+    """413 请求体过大."""
+    _status_code = status.HTTP_413_CONTENT_TOO_LARGE
+
+
+class URITooLongError(BaseHttpError):
+    """414 URI链接过长."""
+    _status_code = status.HTTP_414_URI_TOO_LONG
+
+
+class UnsupportedMediaTypeError(BaseHttpError):
+    """415 不支持的请求媒体类型."""
+    _status_code = status.HTTP_415_UNSUPPORTED_MEDIA_TYPE
+
+
+class LockedError(BaseHttpError):
+    """423 资源锁定."""
+    _status_code = status.HTTP_423_LOCKED
+
+
+class TooManyRequestsError(BaseHttpError):
+    """429 请求过于频繁（限流专用，支持retry_after快捷参数）."""
+    _status_code = status.HTTP_429_TOO_MANY_REQUESTS
+
+    def __init__(
+            self,
+            detail: str | None = None,
+            retry_after: int | None = None,
+            headers: dict[str, Any] | None = None,
+    ):
+        """
+
+        Args:
+            detail: 自定义错误提示
+            retry_after: 设置 Retry‑After 响应头，单位秒
+            headers: 自定义附加响应头
+        """
+        final_headers: dict[str, Any] = dict(headers) if headers is not None else {}
+        if retry_after is not None:
+            final_headers['Retry-After'] = str(retry_after)
+        super().__init__(
+            detail=detail,
+            headers=final_headers if final_headers else None,
+        )

fastapi_augment/common/utils/__init__.py

@@ -0,0 +1,5 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/9/4
+@Description    :
+"""

fastapi_augment/common/utils/strings.py

@@ -0,0 +1,175 @@
+"""
+@Author         : hangu
+@CreateDate     : 2026/9/4
+@Description    :
+"""
+import json
+import random
+import string
+from typing import Any, Protocol
+
+
+# ── 类型定义 ──
+class SupportsWriteStr(Protocol):
+    def write(self, s: str) -> object: ...
+
+
+class SupportsReadBytes(Protocol):
+    def read(self) -> bytes: ...
+
+
+# ── orjson 可选加载 ──
+ORJSON_INSTALLED: bool = False
+ORJSON_DEFAULT_OPTS: int = 0
+_oj_dumps: Any = None
+_oj_loads: Any = None
+
+try:
+    import orjson as _orjson  # type: ignore[import-untyped]
+    ORJSON_INSTALLED = True
+    ORJSON_DEFAULT_OPTS = _orjson.OPT_SERIALIZE_NUMPY | _orjson.OPT_UTC_Z
+    _oj_dumps = _orjson.dumps
+    _oj_loads = _orjson.loads
+except ImportError:
+    pass
+
+
+# orjson OPT_INDENT_2 的常量值，避免直接依赖 orjson 安装
+_ORJSON_OPT_INDENT_2 = 0x04
+
+
+# ── 字符串转换 ──
+def camel_to_snake(s: str) -> str:
+    """驼峰转下划线（支持连续大写）"""
+    if not s:
+        return s
+    result: list[str] = []
+    prev_lower = False
+    for i, c in enumerate(s):
+        if c.isupper():
+            if i > 0 and (prev_lower or (i + 1 < len(s) and s[i + 1].islower())):
+                result.append('_')
+            result.append(c.lower())
+            prev_lower = False
+        else:
+            result.append(c)
+            prev_lower = c.islower()
+    return ''.join(result)
+
+
+def snake_to_camel(s: str) -> str:
+    """下划线转驼峰（首字母大写）"""
+    if not s:
+        return s
+    return ''.join(part.capitalize() for part in s.split('_'))
+
+
+# ── 随机字符串 ──
+def random_string(
+        length: int = 16,
+        chars: str | None = None,
+        exclude: str | None = None,
+) -> str:
+    """生成随机字符串，支持自定义字符集
+
+    Raises:
+        ValueError: 字符集为空时（exclude 排除了所有字符）
+    """
+    if chars is None:
+        chars = string.ascii_letters + string.digits
+    if exclude:
+        chars = ''.join(c for c in chars if c not in exclude)
+    if not chars:
+        raise ValueError('字符集为空，无法生成随机字符串（exclude 排除了所有字符）')
+    return ''.join(random.choices(chars, k=length))
+
+
+# ── JSON 序列化 ──
+def json_dumps(obj: Any, compact: bool = True) -> str:
+    """高性能 JSON 序列化
+
+    Args:
+        obj: 要序列化的对象
+        compact: 是否压缩输出（去除空格）
+
+    Returns:
+        JSON 字符串
+
+    Raises:
+        TypeError: 当对象不可序列化时
+    """
+    if ORJSON_INSTALLED:
+        try:
+            opts = ORJSON_DEFAULT_OPTS
+            if not compact:
+                opts |= _ORJSON_OPT_INDENT_2
+            return _oj_dumps(obj, option=opts).decode('utf-8')
+        except (TypeError, ValueError) as e:
+            raise TypeError(f'JSON 序列化失败: {e}') from e
+    if compact:
+        return json.dumps(obj, ensure_ascii=False, separators=(',', ':'))
+    return json.dumps(obj, ensure_ascii=False, indent=2)
+
+
+def json_dump(obj: Any, fp: SupportsWriteStr, compact: bool = True) -> None:
+    """高性能 JSON 写入文件
+
+    Args:
+        obj: 要序列化的对象
+        fp: 可写文件对象
+        compact: 是否压缩输出
+    """
+    fp.write(json_dumps(obj, compact=compact))
+
+
+def json_loads(s: str | bytes) -> Any:
+    """高性能 JSON 反序列化
+
+    Args:
+        s: JSON 字符串或字节
+
+    Returns:
+        反序列化后的 Python 对象
+
+    Raises:
+        json.JSONDecodeError: JSON 解析失败时
+    """
+    if ORJSON_INSTALLED:
+        try:
+            return _oj_loads(s)
+        except (TypeError, ValueError) as e:
+            text = s.decode('utf-8', errors='replace') if isinstance(s, bytes) else s
+            raise json.JSONDecodeError(str(e), text, 0) from e
+    if isinstance(s, bytes):
+        s = s.decode('utf-8')
+    try:
+        return json.loads(s)
+    except json.JSONDecodeError:
+        raise
+    except (TypeError, ValueError) as e:
+        raise json.JSONDecodeError(str(e), s, 0) from e
+
+
+def json_load(fp: SupportsReadBytes) -> Any:
+    """从文件读取 JSON
+
+    Args:
+        fp: 可读字节文件对象
+
+    Returns:
+        反序列化后的 Python 对象
+
+    Raises:
+        json.JSONDecodeError: JSON 解析失败时
+        OSError: 文件读取失败时
+    """
+    try:
+        raw = fp.read()
+    except (OSError, IOError) as e:
+        raise OSError(f'文件读取失败: {e}') from e
+    if ORJSON_INSTALLED:
+        try:
+            return _oj_loads(raw)
+        except (TypeError, ValueError) as e:
+            raise json.JSONDecodeError(str(e), raw.decode('utf-8', errors='replace'), 0) from e
+    return json.loads(raw.decode('utf-8') if isinstance(raw, bytes) else raw)

fastapi_augment/config/__init__.py

@@ -0,0 +1,8 @@
+"""
+@Author     : zarkhan
+@CreateDate : 2026/9/6
+@Description: 配置管理模块
+"""
+from .settings import EnvSettings
+
+__all__ = ['EnvSettings']