dwyeapi 0.5.2__tar.gz → 0.7.0__tar.gz

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

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

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

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

dwyeapi-0.7.0/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.0/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.5.2 → dwyeapi-0.7.0}/src/dwyeapi/config.py

@@ -1,11 +1,12 @@
-"""Base Pydantic Settings class for FastAPI projects.
+"""FastAPI 项目通用 Pydantic Settings 基类。
 
-除基础字段外,还提供运行环境识别 API:
+除了 database_url / redis_url / secret_key 等基础字段外,还提供运行环境识别 API:
 
-- ``environment`` 字段: ``"dev"`` | ``"prod"``,默认 ``"prod"`` (误配置时保守)
-- ``get_environment()`` / ``is_dev()`` / ``is_prod()``: 业务代码读当前环境
+- ``environment`` 字段: ``"dev"`` | ``"prod"``,默认 ``"prod"``(误配置时偏保守)
+- ``get_environment()`` / ``is_dev()`` / ``is_prod()``:业务代码读取当前环境
 
-业务项目实例化 ``Settings()`` 时会自动把值写入模块级全局,之后任何地方 import 即可读。
+业务项目实例化 ``Settings()`` 时会自动把 environment 值写入模块级全局变量,
+之后任何地方 import 即可读,避免把 Settings 实例到处传递。
 """
 
 from typing import Literal
@@ -45,7 +46,12 @@ def set_current_environment(env: Environment) -> None:
 
 
 class BaseSettings(PydanticBaseSettings):
-    """Base settings — subclass and add project-specific fields."""
+    """FastAPI 项目共用的配置基类。
+
+    业务项目通过继承并追加项目专属字段使用,内置的 database_url / redis_url /
+    secret_key 等字段覆盖最常用的基础设施需求,不需要每个项目重复声明。
+    配置来源默认为 ``.env`` 文件,嵌套字段使用双下划线 ``__`` 分隔。
+    """
 
     database_url: str
     redis_url: str

dwyeapi-0.7.0/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.0/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.0/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.0/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

{dwyeapi-0.5.2 → dwyeapi-0.7.0}/src/dwyeapi/logger.py

@@ -1,17 +1,15 @@
-"""Loguru-based global logger with daily + size rotation and stdlib interception.
-
-Exposes a single lifecycle API (``configure``/``get_logger``/``close``) that mirrors
-the pattern used by ``cache.py``. A typical application calls ``configure`` once at
-startup (from ``lifespan``) and ``close`` once at shutdown.
-
-Features:
-    * Colored console output (stderr).
-    * File output with daily rollover (``{filename}_YYYY-MM-DD.log``) and a
-      configurable per-file size ceiling — whichever triggers first.
-    * Old log retention (default 30 days) with automatic cleanup.
-    * Optional JSON serialization for log aggregators.
-    * Optional interception of the standard ``logging`` module so libraries like
-      uvicorn, SQLAlchemy and third-party packages route through the same sinks.
+"""基于 loguru 的全局日志,支持按天 + 按大小轮转,并可拦截 stdlib logging。
+
+对外暴露一组生命周期 API(``configure`` / ``get_logger`` / ``close``),
+与 ``cache.py`` 保持一致的模式:应用启动阶段调用一次 ``configure``,关闭阶段调用 ``close``。
+
+特性:
+    * 彩色控制台输出(stderr)。
+    * 文件输出按天滚动(``{filename}_YYYY-MM-DD.log``),同时支持单文件大小上限,
+      两个条件任一触发即滚动。
+    * 自动清理过期日志(默认保留 30 天)。
+    * 可选 JSON 序列化,便于日志聚合系统解析。
+    * 可选拦截标准 ``logging`` 模块,让 uvicorn、SQLAlchemy 等三方库共享同一套输出 sink。
 """
 
 from __future__ import annotations
@@ -109,10 +107,10 @@ class Logger:
 
 
 class _InterceptHandler(logging.Handler):
-    """Route standard ``logging`` records into the loguru sink chain."""
+    """把标准 ``logging`` 记录转发到 loguru sink 链路的拦截 Handler。"""
 
     def emit(self, record: logging.LogRecord) -> None:
-        """Forward a stdlib record to loguru preserving level, exception and frame depth."""
+        """转发 stdlib 记录到 loguru,保留原始 level、异常信息以及调用栈深度。"""
         try:
             level: str | int = _logger.level(record.levelname).name
         except ValueError:
@@ -128,13 +126,13 @@ class _InterceptHandler(logging.Handler):
 
 
 def _make_rotator(max_bytes: int) -> Any:
-    """Build a loguru ``rotation`` callable that rolls on date change or size cap.
+    """构造 loguru ``rotation`` 回调,按日期变更或大小超限触发滚动。
 
     Args:
-        max_bytes: Maximum bytes per file before a new file is created.
+        max_bytes: 单文件最大字节数,超出后新开文件。
 
     Returns:
-        A function matching the loguru ``rotation`` callable signature.
+        符合 loguru ``rotation`` 协议的回调函数。
     """
     state: dict[str, date | None] = {"date": None}
 
@@ -166,22 +164,22 @@ def configure(
     intercept_stdlib: bool = True,
     intercept_loggers: list[str] | None = None,
 ) -> None:
-    """Configure the global logger. Call once at application startup.
+    """配置全局日志,应用启动时调用一次即可。
 
     Args:
-        level: Minimum log level (``DEBUG``/``INFO``/``WARNING``/``ERROR``/``CRITICAL``).
-        log_dir: Directory for log files. ``None`` disables file output.
-        filename: Base filename; final files look like ``{filename}_YYYY-MM-DD.log``.
-        max_bytes: Per-file size cap before rotation (default 100 MB).
-        retention: Loguru retention spec (``"30 days"``, ``"1 week"``, int count, ...).
-        console: Whether to write colored logs to stderr.
-        console_format: Override for the console format string.
-        file_format: Override for the file format string.
-        serialize: Emit JSON lines to the file sink for log aggregators.
-        enqueue: Write asynchronously via a queue — non-blocking and multi-process safe.
-        intercept_stdlib: Route stdlib ``logging`` records through loguru.
-        intercept_loggers: When intercepting, scope to these logger name prefixes
-            (e.g. ``["uvicorn", "sqlalchemy"]``). ``None`` means root (catch-all).
+        level: 最低日志级别(``DEBUG``/``INFO``/``WARNING``/``ERROR``/``CRITICAL``)。
+        log_dir: 日志文件目录,``None`` 表示关闭文件输出。
+        filename: 文件基础名,最终文件形如 ``{filename}_YYYY-MM-DD.log``。
+        max_bytes: 单文件大小上限(字节),默认 100 MB。
+        retention: loguru 保留策略(``"30 days"``、``"1 week"``、整数个数等)。
+        console: 是否输出带颜色的日志到 stderr。
+        console_format: 自定义控制台格式字符串。
+        file_format: 自定义文件格式字符串。
+        serialize: 文件 sink 是否按 JSON Lines 序列化,便于日志聚合系统使用。
+        enqueue: 是否通过队列异步写入,非阻塞且多进程安全。
+        intercept_stdlib: 是否把 stdlib ``logging`` 的日志重定向到 loguru。
+        intercept_loggers: 拦截时限定的 logger 名前缀(如 ``["uvicorn", "sqlalchemy"]``),
+            ``None`` 表示拦截 root logger(捕获全部)。
     """
     close()
 
@@ -223,7 +221,7 @@ def configure(
 
 
 def _install_stdlib_intercept(level: str, targets: list[str] | None) -> None:
-    """Replace handlers on stdlib loggers with ``_InterceptHandler``, remembering originals."""
+    """把 stdlib logger 的 handlers 替换为 ``_InterceptHandler``,并记住原始 handlers 以便恢复。"""
     handler = _InterceptHandler()
     roots = targets or [""]
 
@@ -251,12 +249,12 @@ def get_logger(name: str | None = None) -> Logger:
 
 
 def close() -> None:
-    """Remove all handlers, restore stdlib loggers, and flush pending records.
+    """移除全部 handlers、恢复 stdlib logger 原状并 flush 未落盘日志。
 
-    Safe to call repeatedly. After ``close`` the module can be reconfigured.
+    可重复调用,调用后可再次 ``configure`` 重新装配。
     """
     for handler_id in _handler_ids:
-        # Handler already removed — benign.
+        # Handler 已被移除的情况为正常情形,忽略即可。
         with contextlib.suppress(ValueError):
             _logger.remove(handler_id)
     _handler_ids.clear()