dwyeapi 0.5.2__tar.gz → 0.7.1__tar.gz

{dwyeapi-0.5.2 → dwyeapi-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dwyeapi
-Version: 0.5.2
+Version: 0.7.1
 Summary: Lightweight FastAPI infrastructure — exceptions, database, config, security, cache, pagination, logger
 License: MIT
 Requires-Python: >=3.11

{dwyeapi-0.5.2 → dwyeapi-0.7.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dwyeapi"
-version = "0.5.2"
+version = "0.7.1"
 description = "Lightweight FastAPI infrastructure — exceptions, database, config, security, cache, pagination, logger"
 requires-python = ">=3.11"
 license = {text = "MIT"}

dwyeapi-0.7.1/src/dwyeapi/__init__.py

@@ -0,0 +1,35 @@
+"""dwyeapi — 轻量 FastAPI 基础设施包。
+
+业务项目只通过本包的公开 API 访问配置、数据库、缓存、安全等基础能力,
+避免在各项目中重复手写相同逻辑。
+
+Modules:
+    config        — BaseSettings + 运行环境识别 API(is_dev/is_prod/get_environment)
+    exceptions    — AppError 异常体系 + FastAPI 全局 handler 注册
+    database      — 异步 SQLAlchemy engine/session 工厂 + Base + TimestampMixin
+    dependencies  — FastAPI 依赖注入工厂(如 get_db)
+    security      — JWT 令牌与 bcrypt 密码哈希工具(无状态)
+    cache         — 异步 Redis 连接管理
+    response      — 统一 API 响应信封(ApiResponse[T] + PageData[T])
+    pagination    — 分页参数与 offset/limit 计算
+    logger        — 基于 loguru 的全局日志,支持按天与按大小轮转、stdlib 拦截
+    tasks         — 异步任务系统(基于 ARQ,需安装 [tasks] extra)
+    masking       — PII 数据脱敏工具
+    health        — 健康检查路由工厂(只探活,不探依赖)
+"""
+
+from . import health, logger
+from .config import BaseSettings, get_environment, is_dev, is_prod
+from .response import ApiResponse, PageData
+
+__all__ = [
+    "ApiResponse",
+    "BaseSettings",
+    "PageData",
+    "get_environment",
+    "health",
+    "is_dev",
+    "is_prod",
+    "logger",
+]
+__version__ = "0.7.0"

dwyeapi-0.7.1/src/dwyeapi/cache.py

@@ -0,0 +1,49 @@
+"""异步 Redis 连接管理。
+
+模块级单例的懒连接:``configure`` 阶段只记录 URL,首次 ``get_redis`` 调用才真正建立连接,
+``close_redis`` 负责在应用关闭时释放资源,避免连接泄漏。
+"""
+
+import redis.asyncio as aioredis
+
+_redis_url: str | None = None
+_redis: aioredis.Redis | None = None
+
+
+def configure(redis_url: str) -> None:
+    """设置全局 Redis 连接 URL。
+
+    通常在 FastAPI 的 ``lifespan`` 启动阶段调用一次。
+
+    Args:
+        redis_url: 标准 Redis 连接串,如 ``redis://localhost:6379/0``。
+    """
+    global _redis_url
+    _redis_url = redis_url
+
+
+async def get_redis() -> aioredis.Redis:
+    """获取共享的异步 Redis 连接,首次调用时懒创建。
+
+    ``decode_responses=True`` 让返回值直接为 ``str``,避免业务代码反复 decode。
+
+    Returns:
+        全局复用的 ``aioredis.Redis`` 实例。
+
+    Raises:
+        RuntimeError: 未先调用 ``configure`` 时抛出,提示装配缺失。
+    """
+    if _redis_url is None:
+        raise RuntimeError("dwyeapi.cache not configured — call cache.configure(redis_url) first")
+    global _redis
+    if _redis is None:
+        _redis = aioredis.from_url(_redis_url, decode_responses=True)
+    return _redis
+
+
+async def close_redis() -> None:
+    """关闭全局 Redis 连接,未连接时也可安全重复调用。"""
+    global _redis
+    if _redis is not None:
+        await _redis.close()
+        _redis = None

dwyeapi-0.7.1/src/dwyeapi/config.py

@@ -0,0 +1,141 @@
+"""FastAPI 项目通用 Pydantic Settings 基类。
+
+除了 database_url / redis_url / secret_key 等基础字段外,还提供运行环境识别 API:
+
+- ``environment`` 字段: ``"dev"`` | ``"prod"``,默认 ``"prod"``(误配置时偏保守)
+- ``get_environment()`` / ``is_dev()`` / ``is_prod()``:业务代码读取当前环境
+
+业务项目实例化 ``Settings()`` 时会自动把 environment 值写入模块级全局变量,
+之后任何地方 import 即可读,避免把 Settings 实例到处传递。
+"""
+
+from typing import Literal
+
+from pydantic import Field, model_validator
+from pydantic_settings import BaseSettings as PydanticBaseSettings
+from pydantic_settings import SettingsConfigDict
+
+Environment = Literal["dev", "prod"]
+
+_current_environment: Environment = "prod"
+
+
+def get_environment() -> Environment:
+    """返回当前运行环境。
+
+    未实例化 Settings 前默认返回 ``"prod"`` (保守),业务 ``Settings()`` 加载
+    后会同步为配置值。
+    """
+    return _current_environment
+
+
+def is_dev() -> bool:
+    """当前是否为开发环境。"""
+    return _current_environment == "dev"
+
+
+def is_prod() -> bool:
+    """当前是否为生产环境。"""
+    return _current_environment == "prod"
+
+
+def set_current_environment(env: Environment) -> None:
+    """内部使用: 由 BaseSettings 校验钩子或测试显式切换时调用。"""
+    global _current_environment
+    _current_environment = env
+
+
+class BaseSettings(PydanticBaseSettings):
+    """FastAPI 项目共用的配置基类。
+
+    业务项目通过继承并追加项目专属字段使用,内置的 database_url / redis_url /
+    secret_key 等字段覆盖最常用的基础设施需求,不需要每个项目重复声明。
+    配置来源默认为 ``.env`` 文件,嵌套字段使用双下划线 ``__`` 分隔。
+    """
+
+    database_url: str = Field(
+        description="数据库连接串(异步驱动),例 postgresql+asyncpg://user:pass@host:5432/db",
+    )
+    redis_url: str = Field(
+        description="Redis 连接串,例 redis://localhost:6379/0",
+    )
+    secret_key: str = Field(
+        description="应用密钥,用于 JWT 签名与敏感数据加密,至少 32 位随机字符串",
+    )
+    jwt_algorithm: str = Field(
+        default="HS256",
+        description="JWT 签名算法,默认 HS256",
+    )
+    access_token_expire_minutes: int = Field(
+        default=30,
+        description="JWT access token 有效期(分钟),默认 30 分钟",
+    )
+    environment: Environment = Field(
+        default="prod",
+        description='运行环境,"dev" 开启调试特性 / 允许 mock providers,"prod" 关闭调试并禁用 mock',
+    )
+    allowed_origins: list[str] = Field(
+        default_factory=list,
+        description="CORS 允许的来源域名列表,生产环境禁止使用 ['*']",
+    )
+
+    # ── 异步任务配置(task_ 前缀)──
+    task_max_jobs: int = Field(
+        default=5,
+        description="ARQ worker 并发执行的最大任务数",
+    )
+    task_job_timeout: int = Field(
+        default=3600,
+        description="单个任务执行超时(秒),超时后被中止,默认 1 小时",
+    )
+    task_failure_ttl: int = Field(
+        default=86400,
+        description="失败任务结果在 Redis 中的保留时长(秒),默认 1 天",
+    )
+
+    # ── 日志配置(log_ 前缀)──
+    log_level: str = Field(
+        default="INFO",
+        description="最低日志级别:DEBUG / INFO / WARNING / ERROR / CRITICAL",
+    )
+    log_dir: str | None = Field(
+        default=".",
+        description='日志文件目录,默认 "." 即进程当前目录;显式设为 None 可关闭文件输出(仅控制台)',
+    )
+    log_filename: str = Field(
+        default="app",
+        description="日志文件基础名,最终文件形如 {filename}_YYYY-MM-DD.log",
+    )
+    log_max_bytes: int = Field(
+        default=100 * 1024 * 1024,
+        description="单个日志文件大小上限(字节),超出后滚动,默认 100 MB",
+    )
+    log_retention: str = Field(
+        default="30 days",
+        description='日志保留策略,loguru 语法,例 "30 days" / "1 week" / 整数个数',
+    )
+    log_console: bool = Field(
+        default=True,
+        description="是否输出带颜色的日志到 stderr 控制台",
+    )
+    log_serialize: bool = Field(
+        default=False,
+        description="文件 sink 是否按 JSON Lines 序列化,便于日志聚合系统解析",
+    )
+    log_intercept_stdlib: bool = Field(
+        default=True,
+        description="是否拦截 stdlib logging,让 uvicorn / SQLAlchemy / httpx 等共享同一套 sink",
+    )
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        env_nested_delimiter="__",
+        extra="ignore",
+    )
+
+    @model_validator(mode="after")
+    def _sync_environment_to_module(self) -> "BaseSettings":
+        """把 ``environment`` 写入模块全局,让 ``is_dev()`` / ``is_prod()`` 跨模块可读。"""
+        set_current_environment(self.environment)
+        return self

dwyeapi-0.7.1/src/dwyeapi/database.py

@@ -0,0 +1,73 @@
+"""异步 SQLAlchemy 引擎/会话工厂、声明式 Base 与时间戳 Mixin。
+
+集中收敛异步数据库接入方式,业务项目通过 ``create_async_engine_factory``
+和 ``create_session_factory`` 装配引擎,继承 ``Base`` 与 ``TimestampMixin`` 写模型。
+"""
+
+from datetime import datetime
+
+from sqlalchemy import func
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    """全局 ORM 声明式基类,所有业务模型直接继承此类以共享元数据。"""
+
+    pass
+
+
+class TimestampMixin:
+    """为 ORM 模型补齐 ``created_at`` / ``updated_at`` 时间戳字段的 Mixin。
+
+    时间值由数据库层生成(``server_default`` + ``onupdate``),避免应用时钟漂移
+    影响排序,也保证事务回滚时时间戳与数据保持一致。
+    """
+
+    created_at: Mapped[datetime] = mapped_column(server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(server_default=func.now(), onupdate=func.now())
+
+
+def create_async_engine_factory(
+    database_url: str,
+    pool_size: int = 5,
+    max_overflow: int = 10,
+    echo: bool = False,
+) -> AsyncEngine:
+    """创建异步 SQLAlchemy 引擎。
+
+    SQLite 驱动不支持连接池参数,因此针对 ``sqlite`` 前缀 URL 单独走无池路径;
+    其他数据库统一按传入的 pool_size/max_overflow 构建连接池。
+
+    Args:
+        database_url: 异步驱动的连接串,例如 ``postgresql+asyncpg://...``。
+        pool_size: 常驻连接数(SQLite 忽略)。
+        max_overflow: 突发时允许的额外连接数(SQLite 忽略)。
+        echo: 是否把 SQL 语句打到日志,一般仅调试开启。
+
+    Returns:
+        构造好的 ``AsyncEngine`` 实例。
+    """
+    if database_url.startswith("sqlite"):
+        return create_async_engine(database_url, echo=echo)
+    return create_async_engine(
+        database_url,
+        pool_size=pool_size,
+        max_overflow=max_overflow,
+        echo=echo,
+    )
+
+
+def create_session_factory(engine: AsyncEngine) -> async_sessionmaker[AsyncSession]:
+    """基于引擎构造异步 Session 工厂。
+
+    ``expire_on_commit=False`` 让 commit 后仍可访问 ORM 对象的属性,
+    符合 FastAPI "请求内多次访问对象字段" 的典型用法。
+
+    Args:
+        engine: 已创建的 ``AsyncEngine``。
+
+    Returns:
+        绑定到该引擎的 ``async_sessionmaker``。
+    """
+    return async_sessionmaker(engine, expire_on_commit=False)

dwyeapi-0.7.1/src/dwyeapi/dependencies.py

@@ -0,0 +1,29 @@
+"""FastAPI 依赖注入工厂。
+
+基础设施不直接持有 session 工厂,而是通过工厂函数让业务项目装配,
+保证每个项目的 session_factory 由各自的 Settings/engine 决定。
+"""
+
+from collections.abc import AsyncGenerator
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+
+def create_get_db(session_factory: async_sessionmaker[AsyncSession]):
+    """基于 session 工厂创建 ``get_db`` FastAPI 依赖。
+
+    返回的闭包可直接用作 ``Depends(get_db)``,请求结束时自动关闭 session。
+
+    Args:
+        session_factory: 业务侧 ``async_sessionmaker`` 实例。
+
+    Returns:
+        一个可作为 FastAPI 依赖的异步生成器函数。
+    """
+
+    async def get_db() -> AsyncGenerator[AsyncSession]:
+        """产出一次请求期间使用的数据库会话,退出时自动关闭。"""
+        async with session_factory() as session:
+            yield session
+
+    return get_db

dwyeapi-0.7.1/src/dwyeapi/exceptions.py

@@ -0,0 +1,203 @@
+"""AppError 异常体系以及 FastAPI 全局 handler 注册。
+
+service 层统一抛业务异常(AppError 子类),不感知 HTTP 概念,
+由本模块注册的 handler 统一转换为 ``ApiResponse`` 信封格式的 JSON 响应,
+保持错误响应和成功响应的结构一致。
+
+本模块除了映射 AppError 子类外,还会接管 FastAPI 默认的非业务异常:
+
+- ``RequestValidationError`` — 请求参数校验失败,返回结构化字段错误列表。
+- ``HTTPException`` — 第三方库(如 OAuth2)主动抛出的 HTTP 异常,透传状态码与 headers。
+- 未捕获的 ``Exception`` — 兜底 500,堆栈打日志,生产脱敏、开发含详情。
+"""
+
+from typing import Any
+
+from fastapi import FastAPI, HTTPException, Request, status
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+from dwyeapi.config import is_dev
+from dwyeapi.logger import get_logger
+from dwyeapi.response import ApiResponse
+
+_logger = get_logger("dwyeapi.exceptions")
+
+
+class AppError(Exception):
+    """应用级异常基类。
+
+    所有业务异常都应直接或间接继承本类,便于 ``register_exception_handlers``
+    按类型统一捕获并返回规范的 ``ApiResponse`` 信封 JSON 响应。
+    """
+
+    def __init__(self, message: str, code: str = "UNKNOWN_ERROR") -> None:
+        """初始化异常。
+
+        Args:
+            message: 面向前端/调用方的提示信息,不得回显用户原始输入。
+            code: 机器可读的错误码,供前端做分支处理,默认 ``"UNKNOWN_ERROR"``。
+        """
+        self.message = message
+        self.code = code
+
+
+class NotFoundError(AppError):
+    """资源不存在异常,handler 会转换为 HTTP 404 响应。"""
+
+    def __init__(self, resource: str) -> None:
+        """初始化资源不存在异常。
+
+        Args:
+            resource: 资源名(如 "用户"、"任务"),会被拼接为"{resource}不存在"的消息。
+        """
+        super().__init__(message=f"{resource}不存在", code="NOT_FOUND")
+
+
+class BusinessError(AppError):
+    """业务规则校验失败异常,handler 会转换为 HTTP 422 响应。
+
+    调用方通常传入自定义 ``code``(如 ``INSUFFICIENT_BALANCE``)以便前端区分具体原因。
+    """
+
+    pass
+
+
+class PermissionDeniedError(AppError):
+    """权限不足异常,handler 会转换为 HTTP 403 响应。"""
+
+    def __init__(self) -> None:
+        """初始化权限不足异常,使用固定中文提示。"""
+        super().__init__(message="权限不足", code="PERMISSION_DENIED")
+
+
+class AuthenticationError(AppError):
+    """认证失败或缺失异常,handler 会转换为 HTTP 401 响应。"""
+
+    def __init__(self) -> None:
+        """初始化认证失败异常,使用固定中文提示。"""
+        super().__init__(message="认证失败", code="AUTHENTICATION_FAILED")
+
+
+def _error_response(
+    status_code: int,
+    code: str,
+    message: str,
+    data: Any | None = None,
+    headers: dict[str, str] | None = None,
+) -> JSONResponse:
+    """构造错误响应的 JSONResponse。
+
+    错误响应与 ``ApiResponse.ok()`` 结构对齐:``{code, message, data, timestamp}``,
+    仅 ``code`` 由业务错误码填入,``data`` 默认为 ``None``,特殊场景(如校验错误)
+    可携带结构化详情。
+
+    Args:
+        status_code: HTTP 状态码。
+        code: 业务错误码(字符串)。
+        message: 错误提示信息。
+        data: 可选的错误详情载荷,默认 ``None``。校验错误用它携带字段级错误列表。
+        headers: 可选的响应头。用于透传 ``HTTPException.headers`` (如 OAuth2 的
+            ``WWW-Authenticate``),避免客户端协商丢失。
+
+    Returns:
+        符合 ``ApiResponse`` 信封格式的 JSON 错误响应。
+    """
+    envelope = ApiResponse(code=code, message=message, data=data)
+    return JSONResponse(
+        status_code=status_code,
+        content=envelope.model_dump(),
+        headers=headers,
+    )
+
+
+def register_exception_handlers(app: FastAPI) -> None:
+    """为 FastAPI 应用注册异常到 ``ApiResponse`` 信封的统一 handler。
+
+    覆盖两类异常:
+
+    1. **业务异常**(AppError 子类):``NotFoundError`` / ``BusinessError`` /
+       ``PermissionDeniedError`` / ``AuthenticationError``,分别映射到 404/422/403/401。
+    2. **框架异常**:``RequestValidationError`` / ``HTTPException`` / 未捕获 ``Exception``,
+       避免 FastAPI 默认的 ``{"detail": ...}`` 格式绕过 ``ApiResponse`` 信封。
+
+    调用一次即可。FastAPI 按异常类型精确匹配,AppError 子类 handler 不会被 ``Exception``
+    fallback 截获。
+
+    Args:
+        app: 要挂载 handler 的 FastAPI 实例。
+    """
+
+    @app.exception_handler(NotFoundError)
+    async def not_found_handler(request: Request, exc: NotFoundError) -> JSONResponse:
+        """NotFoundError → 404 的 handler。"""
+        return _error_response(status.HTTP_404_NOT_FOUND, exc.code, exc.message)
+
+    @app.exception_handler(BusinessError)
+    async def business_error_handler(request: Request, exc: BusinessError) -> JSONResponse:
+        """BusinessError → 422 的 handler。"""
+        return _error_response(status.HTTP_422_UNPROCESSABLE_ENTITY, exc.code, exc.message)
+
+    @app.exception_handler(PermissionDeniedError)
+    async def permission_denied_handler(request: Request, exc: PermissionDeniedError) -> JSONResponse:
+        """PermissionDeniedError → 403 的 handler。"""
+        return _error_response(status.HTTP_403_FORBIDDEN, exc.code, exc.message)
+
+    @app.exception_handler(AuthenticationError)
+    async def auth_error_handler(request: Request, exc: AuthenticationError) -> JSONResponse:
+        """AuthenticationError → 401 的 handler。"""
+        return _error_response(status.HTTP_401_UNAUTHORIZED, exc.code, exc.message)
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_error_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
+        """RequestValidationError → 422 的 handler。
+
+        FastAPI 默认把 pydantic 错误原样塞进 ``{"detail": [...]}``,字段路径
+        是带 ``body`` / ``query`` / ``path`` 前缀的 tuple,对前端不友好。
+        这里把每条错误展平为 ``{field, message}``,field 保留完整路径
+        (包括 ``body`` / ``query`` 等段,便于前端精确定位来源)。
+        """
+        errors: list[dict[str, str]] = [
+            {
+                "field": ".".join(str(x) for x in e.get("loc", ())),
+                "message": e.get("msg", ""),
+            }
+            for e in exc.errors()
+        ]
+        return _error_response(
+            status.HTTP_422_UNPROCESSABLE_ENTITY,
+            "VALIDATION_ERROR",
+            "请求参数校验失败",
+            data={"errors": errors},
+        )
+
+    @app.exception_handler(HTTPException)
+    async def http_exception_handler(request: Request, exc: HTTPException) -> JSONResponse:
+        """HTTPException → 透传状态码 + headers 的 handler。
+
+        透传 ``exc.headers`` 是为了保留 OAuth2 的 ``WWW-Authenticate: Bearer`` 等
+        协商头,丢失会导致标准客户端无法按规范重试。
+        """
+        return _error_response(
+            exc.status_code,
+            f"HTTP_{exc.status_code}",
+            str(exc.detail),
+            data=None,
+            headers=exc.headers,
+        )
+
+    @app.exception_handler(Exception)
+    async def unhandled_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+        """未捕获 Exception → 500 的 fallback handler。
+
+        生产环境不暴露 ``str(exc)`` 以免泄露字段名、文件路径、SQL 片段等内部信息;
+        开发环境附带 ``str(exc)`` 方便定位。两种环境都通过 ``logger.exception``
+        把完整 traceback 写到日志,确保排障证据不丢失。
+        """
+        _logger.exception("未捕获异常")
+        message = f"服务器内部错误: {exc!s}" if is_dev() else "服务器内部错误"
+        return _error_response(
+            status.HTTP_500_INTERNAL_SERVER_ERROR,
+            "INTERNAL_ERROR",
+            message,
+        )

dwyeapi-0.7.1/src/dwyeapi/health.py

@@ -0,0 +1,56 @@
+"""健康检查路由工厂 — 只探活,不探依赖。
+
+设计取舍:
+    端点**只**报告进程是否存活(liveness),不连接 PostgreSQL / Redis 等依赖。
+    理由是健康端点通常对公网开放,若内置 readiness / dependency check,攻击者
+    可以用低频高并发请求放大到数据库/缓存层,变成 DoS 放大器。
+
+    需要 readiness 语义的业务(如 k8s readinessProbe)应在业务项目里自行实现,
+    并把该端点限制在内网或挂鉴权。
+"""
+
+from fastapi import APIRouter
+
+from dwyeapi.response import ApiResponse
+
+
+def create_health_router(
+    *,
+    service_name: str,
+    version: str,
+    path: str = "/health",
+    include_in_schema: bool = True,
+) -> APIRouter:
+    """构造只探活的健康检查路由。
+
+    返回的 router 仅挂 1 个 ``GET {path}`` 端点,响应 ``ApiResponse[dict]`` 信封,
+    载荷为 ``{"service": service_name, "version": version, "status": "alive"}``。
+
+    Args:
+        service_name: 服务名,通常取自业务 ``Settings.service_name``。
+        version: 服务版本号,通常取自业务包 ``__version__`` 或 ``pyproject.toml``。
+        path: 端点路径,默认 ``"/health"``。业务可改为 ``"/api/healthz"`` 等。
+        include_in_schema: 是否在 OpenAPI 文档暴露,默认 ``True``。内网专用时可设 ``False``。
+
+    Returns:
+        已挂载端点的 ``APIRouter`` 实例,业务项目 ``app.include_router(router)`` 即可。
+    """
+    router = APIRouter(tags=["health"])
+
+    @router.get(
+        path,
+        response_model=ApiResponse[dict],
+        include_in_schema=include_in_schema,
+        summary="进程存活检查",
+    )
+    async def liveness() -> ApiResponse[dict]:
+        """返回进程存活标志及服务元信息,不触达任何外部依赖。"""
+        return ApiResponse.ok(
+            {
+                "service": service_name,
+                "version": version,
+                "status": "alive",
+            }
+        )
+
+    return router