Skip to main content

🐚 apiboot

为组件化构建 API 服务而生的 Python 底层工具包

PyPI Python License Stars

1 个硬依赖 · 全场景懒加载 · Python 3.7+ · 同步 + 异步双 API · 滚动重启守护

从配置加载到服务守护、从 MySQL/PostgreSQL/SQLite 到 LLM/MinerU/ML,一个包搞定所有后端底座。

快速开始 · 模块一览 · CLI 守护进程 · 可选依赖


✨ 为什么选择 apiboot

┌─────────────────────────────────────────────────────────────────┐
│ 你的项目                                                          │
│   ├── main.py        FastAPI 路由                                 │
│   ├── .env           配置 (DB / Redis / LLM / OCR ...)             │
│   ├── models/        ORM 模型 (apiboot 自动 import 建表)            │
│   ├── tasks/         cron 任务 (apiboot 自动 register)             │
│   └── requirements   你自己选的依赖版本                            │
│                                                                 │
│ apiboot  (pip install apiboot, 仅 apscheduler 一个运行时依赖)        │
│   ├── config / logger / middlewares / error / schemas             │
│   ├── db.sql (DB_MODELS_DIR 自动扫) / db.redis / redis.lock       │
│   ├── db.sql.models (加密列 + 复用列 + ORM Base)                  │
│   ├── cron (TASKS_DIR 自动扫 + Redis 分布式锁防 worker 重复)       │
│   ├── ocr / llm / torch / data / retry                            │
│   └── cli (abtstart/abtstop/abtrestart/abtstatus/... + 滚动重启)   │
└─────────────────────────────────────────────────────────────────┘
痛点 apiboot 的解法
装一个工具包拖一堆用不到的依赖 运行时硬依赖只有 apscheduler,业务侧第三方全部按需懒加载, 缺依赖时当场报错并给出 pip 命令
sync / async 数据库 API 风格不统一 统一前缀约定:sync 用裸函数名, async 加 a 前缀, 13 对 CRUD 一一对应
MySQL / PG / SQLite 切换时硬编码方言 走 apiboot.db.sql.backends Protocol, 切换 DB_TYPE 自动派发
数据库字段加密散落业务代码 apiboot.db.sql.models 提供 EncryptedString / EncryptedText / PydanticEncryptedJSON 加密列, 业务模型继承即用
多 worker 部署 cron 被执行 N 次 @async_scheduled_job(..., lock=True) 自动抢 Redis 分布式锁
项目里写一堆 start.sh / stop.sh abtstart / abtstop / abtstatus / abtlist / abtlog 一个命令搞定
多 worker 进程重启会中断服务 abtrestart 默认走滚动重启 (uvicorn workers 逐个 SIGTERM, 前端请求 0 中断)
服务被 OOM Killer 杀后无法自动恢复 CLI 内置 supervisor: fork-safe + OOM 自动重启 + 内存阈值预警 + 雪崩保护
业务 / 系统 / HTTP 三类异常混在一起 三个根异常 (ApiError / ApiSystemError / HttpError) + 统一错误码常量 + http_status 让业务异常正确映射 HTTP 状态码
FastAPI 全局异常一条日志都不打 include_global_exception=True 让 HTTPException / 参数校验失败 / 未预期异常全部输出错误日志
Pydantic 字段命名在前后端来回转换 BaseSchema 自动 snake_case ↔ camelCase
models/ / tasks/ 目录漏 import 漏建表 DB_MODELS_DIR / TASKS_DIR 配置驱动自动扫描, 业务零感知
对象 / dict / ORM / pydantic 互转散落 N 处 obj_to_dict / dict_to_obj 一行替代所有 isinstance 分支

📦 安装

pip install apiboot

默认硬依赖 apscheduler>=3.10.4;Python < 3.10 环境额外带 typing_extensions>=4.0。 其余可选依赖全部懒加载, pip install apiboot 后 import apiboot 永远不会因为缺失依赖而失败 —— 只有真正调用到那个能力时才会报错, 且错误信息里直接给出 pip install xxx 命令。

按需安装可选依赖 (只装你用得到的):

# 最小起步: FastAPI + ORM + Redis
pip install fastapi sqlalchemy pymysql redis httpx pydantic

# AI / OCR 全家桶
pip install langchain langchain-core httpx jieba

# 重试 / 加密 / 雪花 ID
pip install tenacity cryptography snowflake-id

# ML / 数据处理
pip install torch pandas numpy scikit-learn joblib

# 文档解析
pip install pymupdf python-docx python-pptx openpyxl xlrd

# 对象存储 (MinIO)
pip install minio

# CLI 内存监控 (Linux 用 /proc 不需要, macOS / Windows 必需)
pip install psutil

🚀 快速开始

下面七个例子覆盖 90% 的日常场景,每个都能独立运行。

① 一行启动:配置 + 日志

from apiboot import config, logger

logger.info("服务启动")
print(config.DB_HOST)     # 自动读取 .env
print(config.DEBUG)        # 自动类型转换: 'true' → True

工具包内部读配置统一走 apiboot.config.env 的类型化访问器 (业务侧推荐) :

from apiboot.config import env as _env

host = _env.get_db_host()          # str
port = _env.get_db_port()          # int
timeout = _env.get_db_socket_timeout()   # {"connect": 10, "read": 300, "write": 60}

② FastAPI 统一响应

from fastapi import FastAPI
from apiboot.middlewares import add_middlewares

app = FastAPI()
add_middlewares(app)   # 一行注册所有内置中间件, 按推荐顺序 (响应包装外层 / 日志内层)

@app.get("/users/{uid}")
def get_user(uid: str):
    return {"name": "张三", "age": 18}
    # → 自动包装: {"success": True, "code": 200, "message": "成功", "data": {...}}

add_middlewares 等价于手动写两行 add_middleware(...), 顺序写死, 业务侧只用记一个函数名。也可单独关闭某个中间件或自定义配置:

# 只要响应包装, 不要日志
add_middlewares(app, include_logging=False)

# 让 HTTPException / 参数校验失败 / 未预期异常也输出错误日志
add_middlewares(app, include_global_exception=True)

# SSE 接口排除
add_middlewares(app, json_response_exclude_paths=["/api/chat/stream"])

add_middlewares 全部参数:

参数 默认 说明
include_logging True 是否注册请求 / 响应日志中间件
include_json_response True 是否注册统一响应包装中间件
include_global_exception False 是否注册全局异常处理器 (opt-in, 见下方「全局异常日志」)
logging_exclude_paths None 日志中间件的排除路径 (精确 + 前缀匹配)
json_response_exclude_paths None 响应包装中间件的排除路径
json_response_datetime_format None datetime 序列化格式, None = 保留 FastAPI 默认
log_response_body True RESP 日志里是否打印 body
exc_info None 系统异常日志是否带 traceback, None = 带
log_max_chars None 已废弃 (2026-09-21), 不再截断日志, 仅保留兼容
logging_skip_header "X-Skip-Log" 「本次请求别打日志」的标记头名

响应里多出 success: true/false 字段, 前端可以直接 if (resp.success) 判断, 不用关心 SUCCESS_CODE 是 0 还是 200。

③ 统一错误体系

from apiboot.error import BusinessError
from apiboot.error.code import USER_NOT_FOUND

class UserNotFoundError(BusinessError):
    default_code = USER_NOT_FOUND.code      # 30001

raise UserNotFoundError("用户不存在")         # code=30001, HTTP 200

④ 通用 SQL CRUD (MySQL / PostgreSQL / SQLite)

from apiboot.db.sql import init_db, get_db_session, save, query_page

init_db()                                   # 启动时建表 + 自动 import models/ 目录
with get_db_session() as session:
    save(session, User(name="张三"))
    users, total = query_page(session, User, page_num=1, page_size=20)
# 异步版 (FastAPI async def 路由)
from apiboot.db.sql import ainit_db, aget_db_session, asave, aquery_page

async with aget_db_session() as session:
    await asave(session, User(name="张三"))
    users, total = await aquery_page(session, User, page_num=1, page_size=20)

在 .env 中通过 DB_TYPE 选择后端: mysql (默认) / postgresql / sqlite。 别名 postgres / pg / sqlite3 / mysql+mysqlclient 也都识别, 未知值会抛 ValueError。

各后端需要安装的驱动:

DB_TYPE 同步默认驱动 异步默认驱动
mysql pymysql aiomysql
postgresql psycopg2 asyncpg
sqlite sqlite (stdlib) sqlite+aiosqlite

换驱动通过 DB_DRIVER (同步) / DB_ASYNC_DRIVER (异步) 配置覆盖:

# .env: 用 mysqlclient 替代默认 pymysql
DB_DRIVER=mysqlclient

# 异步单独配 (fallback 到 DB_DRIVER, 不配就用异步默认)
DB_ASYNC_DRIVER=asyncpg

自动建表依赖 DB_MODELS_DIR (默认 "models"): 目录不存在时静默跳过, 走老的"用户自己 import model"逻辑; 也可通过 DB_MODELS_FALLBACK_SCAN_ROOT=false 关闭兜底扫描。

跨方言支持 (MySQL / PostgreSQL / SQLite)

apiboot.db.sql 在 3 个数据库后端都能跑通, 业务代码零感知切换 DB_TYPE:

# .env
# DB_TYPE=mysql         # 默认
# DB_TYPE=postgresql
DB_TYPE=sqlite

手写原生 SQL 时 (如 apiboot.db.sql.utils 里的批量加密脚本) 已自动跨方言, 通过 apiboot.db.sql.backends Protocol 实现:

方言差异 解决方式
标识符引用 `tbl` / "tbl" backend.quote_ident('tbl') (MySQL/SQLite 反引号, PG 双引号)
JSON 值写入 CAST(:v AS JSON) / :v::jsonb backend.json_value_expr('v') (各方言专属表达式)
UPSERT ON DUPLICATE KEY / ON CONFLICT / OR IGNORE backend.apply_upsert(...) (自动派发)
各 dialect 私有属性 / 函数 禁止跨方言污染, 全部封装在 backends/{mysql,postgresql,sqlite}.py 内部
from apiboot.db.sql.backends import get_backend

backend = get_backend()          # 按 DB_TYPE 自动派发
print(backend.name)              # "mysql" / "postgresql" / "sqlite"

业务侧需要写原生 SQL 时, 必须通过 backend.quote_ident(...) 和 backend.json_value_expr(...) 拼接, 详见 CLAUDE.md "SQL 跨方言规范" 章节。

新增方言 (如 Oracle / SQL Server) 只需在 apiboot/db/sql/backends/ 加一个实现 DatabaseBackend Protocol 的文件, 注册即可。

ORM Base + 加密列 (apiboot.db.sql.models)

from sqlalchemy.orm import Mapped, mapped_column
from sqlalchemy import String
from apiboot.db.sql.models import (
    Base,                                  # 统一 ORM 基类 (DeclarativeBase)
    int_pk, str_pk,                        # 复用主键
    created_at, updated_at, deleted_at,    # 复用时间戳
    json_type,
    EncryptedString, EncryptedText,        # 字段加密列
    PydanticEncryptedJSON,                 # 整 JSON 加密
)

# .env: ENCRYPT_SECRET=<48字节高熵字符串>


class User(Base):
    __tablename__ = "user"
    id: Mapped[int] = int_pk
    name: Mapped[str] = mapped_column(String(64))
    phone: Mapped[str] = mapped_column(EncryptedString(32))    # VARCHAR 加密
    remark: Mapped[str] = mapped_column(EncryptedText)         # TEXT 加密
    status: Mapped[int] = status_int(default=1)
    created_at = created_at()
    updated_at = updated_at()
列类型 存储 用途 依赖
EncryptedString(N) VARCHAR 加密 短字段 (手机号 / 身份证 / 邮箱) pydantic + cryptography
EncryptedText TEXT 加密 长字段 (地址 / 备注) pydantic + cryptography
PydanticEncryptedJSON 整 JSON 加密 整个 Pydantic 模型加密 pydantic + cryptography
PydanticFieldEncryptedJSON JSON 内字段级加密 同 JSON 内只加密敏感字段 pydantic + cryptography
PydanticJSON MySQL 原生 JSON 结构化字段(非加密) pydantic
PydanticString VARCHAR 跨数据库 Pydantic 字段 pydantic
PydanticText TEXT 大 Pydantic 字段 pydantic

⚠️ 加密列要求 .env 配置 ENCRYPT_SECRET (建议 ≥ 32 字符, 丢失后历史加密数据无法解密)。 完整运维红线见 apiboot.utils.password_utils 文档 / CLAUDE.md。

⚠️ 懒加载分组 (PEP 562): apiboot.db.sql.models 顶部不 import 任何第三方包, import apiboot.db.sql.models 在没装 sqlalchemy / pydantic 的环境里照样成功; 只有真正取某个名字时才按需加载:

取的名字 需要装
Base sqlalchemy
int_pk / created_at / status_int / str_column / num_column / int_column / datetime_column 等复用列 SQLAlchemy 2.0+ (用的是 Annotated[Mapped[...], mapped_column(...)] 模式, 1.4 没有)
PydanticJSON / EncryptedString / get_encrypt_passphrase 等 Pydantic 类型 pydantic ≥ 1.10 + sqlalchemy

缺依赖时抛的是带安装命令的 ImportError (如 pip install 'sqlalchemy>=2.0'), 不是一头雾水的 ModuleNotFoundError。

对象 ↔ dict 互转规范

业务函数入参往往是"什么类型都行" (dict / SQLAlchemy ORM / Pydantic v1+v2 / SQLModel / dataclass / namedtuple ...), 禁止每个业务函数自己写 if/elif isinstance 分支判断。统一委托 apiboot.utils.obj_utils:

from apiboot.utils.obj_utils import obj_to_dict, dict_to_obj

def save(model: type, data) -> int:
    """data 可以是 dict / ORM / pydantic / dataclass / namedtuple, 都规范化成 dict."""
    data_dict = obj_to_dict(data)  # ← 一行替代所有 if/elif isinstance
    stmt = sql_insert(model).values(data_dict)
    return session.execute(stmt).rowcount or 0

def parse(raw: dict, cls: type):
    """把 dict 转回 Pydantic / dataclass 实例."""
    return dict_to_obj(raw, cls)
函数 方向 支持输入
obj_to_dict(obj, *, deep=False) 对象 → dict None / 基础类型 / dict / pydantic v1+v2 / SQLModel / SQLAlchemy ORM / dataclass / namedtuple / 普通对象 (vars() 兜底)
dict_to_obj(data, cls) dict → 类实例 已是 cls 实例原样返回; pydantic v1+v2 (model_validate / parse_obj); dataclass / namedtuple / 普通类 (cls(**data))

反模式 (禁止):

# ❌ 自己写 isinstance 分支
if isinstance(data, dict):
    return data
if hasattr(data, "__table__"):
    return {c.name: getattr(data, c.name) for c in data.__table__.columns}
if hasattr(data, "model_dump"):
    return data.model_dump()
raise TypeError(...)

# ❌ 字符串嗅探 __module__.startswith("pydantic")
model_module = type(data).__module__ or ""
if model_module.startswith("pydantic"):
    if hasattr(data, "model_dump"):
        return data.model_dump()

# ❌ 自己写 duck-typing 判 v1/v2
if hasattr(obj, "model_dump"):
    return obj.model_dump()
return obj.dict()  # v1

完整规范、检测命令、例外清单见 CLAUDE.md "对象 ↔ dict 互转规范" 章节。

⑤ Redis 分布式锁 (Redisson 风格)

from apiboot.db.redis import init_redis
from apiboot.db.redis.lock import with_lock, LockAcquireError

init_redis()
try:
    with with_lock("order:123", ttl=30, timeout=5) as lock:
        do_critical()                      # Lua CAS 释放 + watchdog 自动续期
except LockAcquireError:
    logger.warning("5 秒内没拿到锁, 跳过")

⚠️ 务必 release 或用上下文管理器: watchdog 后台线程会一直续期, 业务异常路径也要 finally 释放, 否则锁 key 长时间不被释放。

⑥ 定时任务 (装饰器自动注册 + 分布式锁防 worker 重复)

from apiboot.cron import scheduled_job, start_scheduler

@scheduled_job("cron", hour=6, minute=0, lock=True, lock_ttl=7200)
def _daily_pipeline_6am():
    """多 worker 部署时自动抢 Redis 锁, 只有 1 个 worker 真跑"""
    print("running daily pipeline")

if __name__ == "__main__":
    start_scheduler()    # 无需传扫描路径 —— 装饰器已自动注册

异步版 (FastAPI lifespan):

from apiboot.cron import async_scheduled_job, astart_scheduler, astop_scheduler

@async_scheduled_job("cron", hour=6, minute=0, lock=True)
async def _daily_pipeline_async():
    print("async 跑批")

@asynccontextmanager
async def lifespan(app):
    await astart_scheduler()
    yield
    await astop_scheduler()
装饰器参数 默认 作用
lock: bool False 是否启用 Redis 分布式锁。多 worker / K8s 多副本必须设 True, 否则任务会被触发 N 次
lock_ttl: int 7200 锁 TTL 秒, 建议 = "最长任务耗时 × 1.5"
lock_timeout: float 0.5 拿锁超时秒。cron 场景必须小, 不阻塞 scheduler
lock_key: Optional[str] None 自定义锁 key, 支持 {0} (位置参数) / {name} (关键字参数) 模板

降级行为: Redis 没装 → 警告日志 + 任务照常执行; 拿不到锁 → INFO + 跳过本轮; Redis 暂时不可用 → 警告 + 照常执行。生产 cron 必须带 lock=True, 否则 K8s 多副本或 uvicorn --workers N 会让任务被执行 N 次。

⑦ LLM 接入

from apiboot.llm import init_model
from apiboot.llm.agent import ChatAgent

llm = init_model()                          # 从 .env 读 LLM_MODEL / LLM_API_KEY / LLM_BASE_URL
agent = ChatAgent(llm)

多 API key 轮询 (配额周期性耗尽的场景):

# .env
LLM_API_KEYS = sk-a,sk-b,sk-c

配了 2 个以上 key 时 init_model() 自动返回"轮询模型":

  • 每个 key 轮流承接请求, 用量摊到多个 key 上
  • 某个 key 命中配额 / 鉴权错误 (401 / 402 / 403 / 429) → 隔离 该 key, 并在同一次请求内换下一个 key 重试 (调用方无感知)
  • 隔离到期后该 key 自动重新参与轮询 (探测一次成功即彻底恢复); 连续失败则冷却时间指数翻倍 (默认 60s 起, 上限 30min, init_model(key_cooldown=...) 可调)
  • 网络抖动 / 5xx 属于服务级错误, 不隔离 key (交给上层重试)

🛡️ CLI 守护进程管理

装上 apiboot 后, 7 个全局命令直接可用, 无需写 start.sh / stop.sh:

cd /path/to/your-project           # 有 main.py + .env 的目录

abtstart                            # 启动 (后台 + supervisor 守护)
abtstatus                           # 查看状态
abtstop                             # 停止
abtrestart                          # 重启 (默认走滚动重启)
abtlist                             # 列出所有 abtstart 启动的项目
abtlog                              # tail -f .abt.log

或子命令形式: abt start / stop / restart / status / list / log。

常用参数

abtstart --module api.main:app     # 自定义入口
abtstart --port 9000 --host 127.0.0.1
abtstart --workers 4                # 多 worker (uvicorn multiprocessing)
abtstart --reload                   # 开发模式
abtstart --env production           # 加载 .env.production
abtstart --clean                    # 端口被占时强杀

# Supervisor 内存 / 重启阈值
abtstart --mem-warn-ratio 0.80     # RSS 达到 80% 时 WARN
abtstart --mem-hard-ratio 0.95     # RSS 达到 95% 时主动 SIGTERM (防 OOM Killer)
abtstart --max-restarts 5           # 短窗口最大重启次数
abtstart --restart-window 300       # 统计窗口秒数
abtstart --no-supervisor            # 关闭 OOM 守护 (回到旧行为)

# 重启策略 (abtrestart)
abtrestart                          # workers>1 默认滚动重启 (前端请求 0 中断)
abtrestart --force-reload           # 强制 stop+start (改了代码后 reload master)
abtrestart --graceful-timeout 60    # 滚动重启每个 worker 最多等 60s
abtrestart --force                  # 滚动重启跳过 graceful, 直接 SIGKILL worker

# 全局查看
abt list --json                     # JSON 输出 (方便脚本处理)
abt list --prune                    # 清理 dead 状态的记录
abt log -n 500                      # tail -f 最后 500 行

关键能力

  • 🔍 自动发现 .env + main.py / app.py / server.py
  • 🌍 多环境 APP_ENV=production 自动加载 .env.production
  • 🚧 端口预检 启动前检测占用, --clean 可强杀
  • 🛡️ OOM 守护 (默认开启) 子进程被 OOM Killer 杀, 自动重启
  • 📊 内存阈值 RSS 达到 mem-hard-ratio 时主动 SIGTERM, 避免被 OOM Killer 突然终止
  • 🚨 雪崩保护 短窗口内重启次数超限, 自动放弃
  • 👷 多 worker --workers N 切到 uvicorn multiprocessing
  • 🔁 滚动重启 abtrestart 在 workers>1 时默认走滚动重启, worker 逐个 SIGTERM → uvicorn master 自动 fork 新 worker 顶上 → 验证就绪 → 处理下一个, 整组服务在滚动过程中始终有 N 个 worker 在跑, 前端请求 0 中断
  • 🧬 fork-safe 子进程标记 APIBOOT_FORKED=1, 业务代码可借此 dispose + 重建 SQLAlchemy engine, 避免多 worker 共享父进程 FD 导致 "MySQL server has gone away"
  • 📋 全局 registry abt list 一台机器混多个项目也清晰可查 (~/.abt/registry.json)
  • 🧹 残留进程清理 自动杀掉上次没杀干净的 uvicorn 孤儿 (用 psutil)

⚠️ --workers N 与 OOM 边界: supervisor 的 RSS 防御只对 uvicorn master 可见, 看不到后代 worker 的内存。单个 worker 被 OOM Killer 杀由 uvicorn master 自己重启; 整套同归于尽才由 supervisor 重启。要管每个 worker 内存, 用 systemd MemoryMax= 或 K8s resources.limits.memory, 不要指望 supervisor。

⚠️ 滚动重启不 reload 代码: uvicorn worker 是 master 的 fork, 继承 master 的代码映像。改了 main.py 等业务文件必须用 --force-reload 走 stop+start 让 master 重启, 新 worker 才会 fork 自新 master。滚动重启只 graceful 重启 worker (重置进程内状态、重读 .env 等)。

abtrestart 行为矩阵

场景 路径 中断窗口
workers > 1 (默认) 滚动重启 worker 0 (整组滚动, 服务始终可用)
workers > 1 + 改模块 / env stop + start 几秒 ~ 30s (不可避免)
workers == 1 stop + start 几秒 ~ 30s (不可避免)
任何场景 + --force-reload stop + start 几秒 ~ 30s

滚动重启需要项目装 psutil, Linux 用 /proc 也可不装 (走 stdlib 实现)。


🧩 模块一览

apiboot/
├── __init__.py            # 顶层导出: config / logger / __version__
├── config/                # .env 加载器 + 类型化访问器
│   ├── config.py          #   Config 对象 (属性式读取 + path())
│   ├── env.py             #   72 个类型化访问器 (工具包内统一读配置的入口)
│   └── path.py            #   路径锚点策略
├── log/
│   └── logger.py          # 控制台 + 文件双输出 logger (Surrogate 安全)
├── middlewares/           # FastAPI 中间件
│   ├── _base.py           #   共用常量 + add_middlewares
│   ├── json_response.py   #   统一响应包装 + 异常捕获
│   ├── req_res.py         #   请求 / 响应日志 (敏感字段脱敏)
│   └── global_exception.py#   全局异常处理器 (补 FastAPI 缺失的错误日志)
├── error/                 # 三个根异常 + 错误码常量 + http_status 支持
├── schemas/               # BaseSchema (驼峰) / JsonResult / PageReq
├── db/
│   ├── sql/               # 通用 SQL backend (MySQL / PostgreSQL / SQLite)
│   │   ├── backends/      #   各方言 Protocol 实现 + quote_ident / json_value_expr
│   │   ├── models/        #   ORM Base + 加密列 + 复用列定义 + soft_delete filter
│   │   └── utils/         #   字段加解密 + CSV 导入导出
│   ├── redis/             # sync + async KV (含 REDIS_MAX_CONNECTIONS)
│   └── redis/lock/        # Redisson 风格分布式锁 (Lua CAS + watchdog)
├── cron/                  # 定时任务 (装饰器自动注册 + Redis 分布式锁 + TASKS_DIR 自动扫)
├── llm/                   # LangChain chat model + Agent + HuggingFace 下载
│   ├── model/             #   init_model / ChatModel + 多 key 轮询
│   ├── agent/             #   ChatAgent 流式封装
│   └── huggingface/       #   模型下载 (download_models 统一入口)
├── torch/                 # get_torch_device (cuda > mps > cpu)
├── data/                  # pandas / sklearn / jieba 常用工具
│   └── utils/             #   pd_utils / sklean_utils / jieba_utils
├── retry/                 # tenacity 懒加载透传 (PEP 562 lazy module, 44 个符号)
├── ocr/                   # MinerU API 异步客户端 (PDF / 图片 / Office → markdown)
├── oss/                   # 对象存储
│   ├── common.py          #   公共常量 / 异常 / 请求体 / 响应体 / 公共方法
│   └── minio/             #   MinIO 后端 (官方 minio SDK)
└── cli/                   # abtstart / abtstop / abtrestart / ... (+ supervisor + 滚动重启)

apiboot.schemas 与 apiboot.log 是命名空间包 (没有 __init__.py), 所以只能从子模块导入: from apiboot.schemas.base import BaseSchema / from apiboot.schemas.json_result import JsonResult / from apiboot.schemas.page import PageReq / from apiboot.log.logger import logger。 顶层 from apiboot import config, logger 照常可用。

顶层入口

符号 作用
apiboot.config 一行拿到 .env 配置 (自动类型转换)
apiboot.logger 一行拿到 logger (控制台 + 文件双输出)
apiboot.__version__ 当前版本 (打包时写入 _version.py)

FastAPI 中间件 (apiboot.middlewares)

组件 功能
JsonResponseMiddleware 路由返回值 + 异常统一包装成 {success, code, message, data}
ReqResLoggingMiddleware 请求 / 响应日志 (每请求两行, 含敏感字段脱敏)
add_middlewares(app) 一行注册所有内置中间件, 按推荐顺序 (响应包装外层 / 日志内层)
apiboot.middlewares.global_exception.register_global_exception_handler(app) 全局异常处理器: 让 HTTPException / 参数校验失败 / 未预期异常也输出错误日志

特性:

  • 路由返回值 / ApiError / HTTPException / 未预期异常 → 自动包装
  • HTTP 状态码映射: 业务异常走异常自身的 http_status 类属性 (默认 200), 系统异常默认 500; 子类可声明 http_status = 401 把 401 业务异常正确返回
  • SSE / 流式接口自动跳过 (识别 StreamingResponse)
  • 非 JSON 响应 (文件下载、HTML 页面) 原样放行
  • 已包装过的响应 (顶层已有 code/message/data) 原样放行
  • 大响应体保护: 响应超过 MAX_BODY_SIZE (默认 10MB) 直接 pass-through, 避免 OOM + 不必要的 body 解析
  • 双层 try-except: 异常路径里中间件自身处理失败会用 INTERNAL_ERROR_CODE 兜底, 永远不会让"框架崩了"代替"业务异常"
  • Datetime 自动格式化为 "%Y-%m-%d %H:%M:%S" (可配置)
  • 敏感字段 (password / token / secret / api_key 等) 在 body / query / form 里自动脱敏
  • 「别打日志」标记头 X-Skip-Log: 1 → 本次请求不打 REQ/RESP (异常日志照打)

跳过某些路径:

app.add_middleware(JsonResponseMiddleware, exclude_paths=["/api/chat/stream"])
# 精确匹配 + 前缀匹配: "/api/llm" → 匹配 /api/llm, /api/llm/chat

或者用 add_middlewares 一行注册 (自动按推荐顺序, 顺序写错也不会出错):

from apiboot.middlewares import add_middlewares

app = FastAPI()
add_middlewares(app)
# 等价于:
#   app.add_middleware(ReqResLoggingMiddleware)   # 内层 (先注册)
#   app.add_middleware(JsonResponseMiddleware)    # 外层 (后注册)

# 可选: SSE 排除 + 关闭 RESP body 日志
add_middlewares(
    app,
    json_response_exclude_paths=["/api/chat/stream"],
    log_response_body=False,
)

中间件顺序由 Starlette 的 add_middleware 决定 (内部是 insert(0, ...)): 后 add 的在外层 (先被调用)。 本函数内 add 顺序固定为 日志 → 响应包装, 即响应包装在外层、日志在内层, 用户不用关心。

全局异常日志

FastAPI 自带的全局异常处理只回响应, 一条日志都不打 —— raise HTTPException(404)、请求参数校验失败, 日志里都查不到。 打开全局异常处理器后, 这些异常按 apiboot 的日志规范输出:

from apiboot.middlewares import add_middlewares

add_middlewares(app, include_global_exception=True)

# 或者只要全局异常、不要内置中间件:
from apiboot.middlewares.global_exception import register_global_exception_handler

register_global_exception_handler(app)
异常 日志 级别
HTTPException (>= 500) 系统异常 | GET /x | HTTPException(500): ... ERROR (带 traceback)
HTTPException (< 500) 业务异常 | GET /x | code=404 | ... WARNING
RequestValidationError 业务异常 | GET /x | code=422 | 请求参数校验失败: ... WARNING
ApiError (业务异常) 业务异常 | GET /x | code=20000 | ... WARNING
其他未预期异常 系统异常 | GET /x | ValueError: ... ERROR (带 traceback)
  • 响应体跟 FastAPI 默认处理一致 ({"detail": ...}), 不改前端契约
  • 未预期异常返回标准 {success, code, message, data} + HTTP 500, 不暴露内部细节
  • ⚠️ 必须在 app 启动前注册 (异常处理器在中间件栈构建时挂进去)

业务异常映射 HTTP 状态码:

from apiboot.error import BusinessError
from apiboot.error.code import UNAUTHORIZED

class UnauthorizedError(BusinessError):
    default_code = UNAUTHORIZED.code   # 11001
    http_status = 401                  # 同时覆盖 HTTP 状态码 (默认 200)

@app.get("/me")
def me():
    raise UnauthorizedError("登录已过期")
    # → HTTP 401 + {"code": 11001, "message": "登录已过期", "data": null}

错误体系 (apiboot.error)

Exception
└─── ApiError ─────────── BusinessError (别名)
    ├── HttpError       # 外部 HTTP 调用失败
    └── ApiSystemError  # 系统异常 (HTTP 500, 业务侧一般不直接抛)

为什么没有 SystemError 别名: Python 内建 SystemError (解释器内部错误用) 如果被遮蔽, 用户的 except SystemError: 会永远捕获不到真正的解释器内部错误。本模块只导出 ApiSystemError, 历史用了 from apiboot.error import SystemError 的请改 ApiSystemError。

根类 默认 code 默认 HTTP 用途
ApiError / BusinessError 20000 200 业务侧异常
HttpError 20000 200 外部 HTTP 调用失败
ApiSystemError 10099 500 系统侧异常

子类可同时覆盖 default_code 和 http_status, 让业务异常正确映射到 HTTP 状态码 (如 UnauthorizedError.default_code=11001, http_status=401)。 没声明 http_status 时, 业务异常一律 200, 系统异常一律 500。

错误码常量 (apiboot.error.code, 22 个常量 + 1 个 ErrorCode 类):

码段 常量 (code)
成功 SUCCESS (200, .env 配 SUCCESS_CODE 可改成 0 等)
系统 10xxx UNKNOWN_ERROR (10000) / PARAM_ERROR (10001) / INTERNAL_ERROR (10005) / SYSTEM_ERROR (10099)
认证 11xxx UNAUTHORIZED (11001) / TOKEN_INVALID (11002) / PERMISSION_DENIED (11004)
数据 12xxx NOT_FOUND (12001) / DATA_EXISTS (12002) / DATA_VALIDATION_FAILED (12003)
业务 2xxxx BUSINESS_ERROR (20000) / OPERATION_FAILED (20001) / STATE_ILLEGAL (20002)
用户 30xxx USER_NOT_FOUND (30001) / USER_PASSWORD_ERROR (30003)
对象存储 40xxx OSS_ERROR (40000) / OSS_CONFIG_ERROR (40001) / OSS_FILE_NOT_FOUND (40002) / OSS_FILE_EXISTS (40003) / OSS_BUCKET_NOT_FOUND (40004) / OSS_OPERATION_FAILED (40005)

apiboot.error 另导出 SYSTEM_ERROR_CODE (10099) / SYSTEM_ERROR_MESSAGE / SYSTEM_ERROR_HTTP_STATUS (500) / INTERNAL_ERROR_CODE (10005), 供中间件与全局异常处理器直接引用。

升级注意: 本模块移除了 SystemError 别名 (避免遮蔽 Python 内建 SystemError)。 历史用了 from apiboot.error import SystemError 的代码, 改成:

from apiboot.error import ApiSystemError

类实例化和抛异常的语法完全不变 (raise ApiSystemError("...")), isinstance 判断也兼容 (因为 ApiSystemError 是类本身, 不是别名)。

Schema (apiboot.schemas)

类 模块 功能 依赖
BaseSchema apiboot.schemas.base pydantic Schema 基类, 自动 snake_case ↔ camelCase pydantic ≥ 2.0
JsonResult[T] apiboot.schemas.json_result dataclass 实现的统一响应 {success, code, message, data}, success 是 boolean 字段, 前端可 if (resp.success) 直判 stdlib
PageReq apiboot.schemas.page 分页请求基类 (page_num ≥ 1, page_size 1–500) pydantic
# BaseSchema 自动驼峰
from apiboot.schemas.base import BaseSchema

class UserSchema(BaseSchema):
    user_id: int
    user_name: str

u = UserSchema(user_id=1, user_name="alice")
u.model_dump(by_alias=True)    # → {"userId": 1, "userName": "alice"}

# JsonResult 统一响应 (含 success 字段, 前端 boolean 判断)
from apiboot.schemas.json_result import JsonResult
from apiboot.error.code import NOT_FOUND

# 成功 (success=True, code=SUCCESS.code)
JsonResult.success(data={"id": 1}).to_dict()
# → {"success": True, "code": 200, "message": "成功", "data": {"id": 1}}

# 失败 (success=False, code=12001)
JsonResult.fail(code=NOT_FOUND).to_dict()
# → {"success": False, "code": 12001, "message": "资源不存在", "data": None}

JsonResult 的字段是 is_ok / code / message / data, to_dict() 输出时才把 is_ok 转成 JSON 里的 success。构造一律用类方法 JsonResult.success(...) / JsonResult.fail(...)。 SUCCESS.code 默认 200, 在 .env 配 SUCCESS_CODE=0 可改成 0 等其他值。 前端只需用 resp.success 字段判断, 不用关心 SUCCESS_CODE 是 0 还是 200。

数据库 (apiboot.db)

通用 SQL CRUD (13 对, sync + async 共 26 个函数)

类别 同步 异步
增 save / save_batch asave / asave_batch
改 update / update_batch / save_or_update / save_or_update_batch (各后端原生 UPSERT) aupdate / aupdate_batch / asave_or_update / asave_or_update_batch
查 query / query_primary_key / query_page (rows + total) — 均支持 fields=[...] aquery / aquery_primary_key / aquery_page
删 delete / delete_batch / soft_delete / soft_delete_batch (UPDATE deleted_at = NOW()) adelete / adelete_batch / asoft_delete / asoft_delete_batch

另有连接 / 会话层辅助 (sync 5 + async 5): get_engine / init_db / close_db / get_db_session / get_db 和 aget_engine / ainit_db / aclose_db / aget_db_session / aget_db。

自动建表 + models 目录扫描

项目结构
├── models/
│   ├── __init__.py
│   ├── user.py          # class User(Base): ...
│   └── order.py         # class Order(Base): ...
└── .env  →  DB_MODELS_DIR=models   # 默认值, 目录不存在静默跳过
from apiboot.db.sql import init_db
from apiboot.db.sql.models import Base

init_db(Base)      # 启动时自动 import models/ 下所有 .py + create_all
  • 每个 engine 独立标记 lazy 建表状态 (WeakKeyDictionary), 多 engine 场景互不干扰
  • DB_MODELS_DIR= 显式禁用扫描
  • 单个 model 文件 import 失败仅 WARN, 不阻断其他文件
  • 多 Base 自动发现: 即使业务传了自己的 DeclarativeBase, init_db 也会扫 sys.modules 中所有 DeclarativeBase 子类的 metadata
  • SQLModel 兼容: 装了 sqlmodel 时同时扫 SQLModel.metadata

多 engine 支持

# 测试场景: 换 engine 后, 期望重新跑 lazy 建表 —— 现在做到了
engine_a = create_engine("mysql://a")
engine_b = create_engine("mysql://b")
lazy_ensure_tables_sync(engine_a, Base)   # 跑
lazy_ensure_tables_sync(engine_b, Base)   # 也跑 (之前 process-global bool 会跳过)

数据库配置项 (.env)

通过 :mod:apiboot.config.env 里的类型化访问器读取, 常用配置如下:

Key 默认值 适用
DB_ENABLE true 通用 SQL 子系统总开关。CI / 单元测试无 DB 时显式设 false
DB_TYPE mysql 数据库后端: mysql / mysql+mysqlclient / postgresql / postgres / pg / sqlite / sqlite3。未知值会在 get_engine() 时直接 ValueError
DB_DRIVER 后端默认 同步数据库驱动 (覆盖 backend 类属性)。MySQL 默认 pymysql, PG 默认 psycopg2, SQLite 默认 sqlite
DB_ASYNC_DRIVER 异步默认 异步数据库驱动, 默认按后端: aiomysql / asyncpg / sqlite+aiosqlite。未配时 fallback 到 DB_DRIVER
DB_HOST localhost 数据库主机; SQLite 下表示文件路径 (可相对 CWD)
DB_PORT 按 DB_TYPE 推断 mysql=3306 / postgresql=5432 / sqlite=0
DB_USERNAME root 数据库用户名, SQLite 不使用
DB_PASSWORD "" 数据库密码 (⚠️ 敏感)。包含 @/: 等特殊字符时 SQLAlchemy URL 会自动 quote
DB_NAME "" MySQL/PostgreSQL 表示逻辑库; SQLite 下表示数据库文件路径, 留空走 :memory:
DB_CHARSET utf8mb4 MySQL/PostgreSQL 客户端编码; SQLite 不使用
DB_PREFIX APP_NAME + "_" SQL 表名前缀, 字符规则 [A-Za-z][A-Za-z0-9_]*, 多环境共享 DB 强烈建议设置
DB_MODELS_DIR models init_db / ainit_db 启动时自动 import 的 ORM 文件目录 (不存在静默跳过)
DB_MODELS_FALLBACK_SCAN_ROOT true models/ 不存在时是否兜底扫描项目根目录的 .py
DB_USE_MODERN_UPSERT false MySQL 专属, 只有确认用现代别名语法 (> 8.0.20) 才设为 true
DB_POOL_SIZE 10 SQLAlchemy 连接池常驻连接数
DB_MAX_OVERFLOW 20 连接池溢出上限 (总连接数 = size + overflow)
DB_POOL_RECYCLE 3600 连接回收秒数, 防 MySQL wait_timeout 断连
DB_POOL_PRE_PING true 取连接前先 ping 一遍, 坏连接自动丢弃
DB_POOL_TIMEOUT 30 等"池里有没有空闲连接"的秒数
DB_CONNECT_TIMEOUT / DB_READ_TIMEOUT / DB_WRITE_TIMEOUT 10 / 300 / 60 驱动层 socket 超时 (三选一别混): 与 DB_POOL_TIMEOUT 缺一不可, 否则数据库半死时请求线程会永久卡死

完整配置项和默认值见 apiboot/config/env.py 顶部 docstring。

ORM Base + 加密列 (apiboot.db.sql.models)

from apiboot.db.sql.models import (
    Base,                                  # 统一 ORM 基类
    int_pk, str_pk,                        # 复用主键
    created_at, updated_at, deleted_at,    # 复用时间戳
    json_type,
    EncryptedString, EncryptedText,        # 字段加密列
    PydanticEncryptedJSON,
)
组件 说明
Base apiboot 生态唯一 DeclarativeBase, 支持 Mapped[T] 类型注解
int_pk / str_pk / str_short_pk / str_long_pk 复用主键 (Annotated[Mapped[int/str]])
created_at / updated_at / deleted_at 复用时间戳 (DB 侧默认 + onupdate 自动维护)
json_type 通用 JSON 列
status_int 状态枚举 (int)
str_column / str_short_column / str_long_column 字符串列 (长度分档)
num_column / int_column / datetime_column 数值 / 整型 / 日期时间列
EncryptedString / EncryptedText VARCHAR / TEXT 字段加密
PydanticEncryptedJSON 整 JSON 加密
PydanticFieldEncryptedJSON JSON 内字段级加密
PydanticJSON / PydanticString / PydanticText 非加密的 Pydantic JSON 列
get_encrypt_passphrase / decrypt_field 加密口令读取 + 单字段解密
soft_delete filter 自动给含 deleted_at 列的 model 加 WHERE deleted_at IS NULL (可用 with_deleted() 逃逸)

⚠️ 必须用 apiboot.db.sql.models.Base, 业务代码禁止自己 Base = declarative_base(), 否则多 Base 的 metadata 互不相通, init_db 扫不到表。

字段加解密 + CSV 工具 (apiboot.db.sql.utils)

函数 作用
encrypt 递归加密对象里所有带 __encrypted_fields__ 的字段。传实例 → 加密单个对象; 传 SQLModel table 类 → 查表批量加密并写回
decrypt 解密 __encrypted_fields__ 当前列表里的字段 (单对象 / 查表批量, 同上两种模式)
decrypt_encrypt 孤儿密文还原: 把"已从 __encrypted_fields__ 移除"的字段还原成明文 (自动检测模式 / 显式 fields 模式)
is_encrypted 判断字符串是不是字段密文 (认 v1$ 老 Fernet / c1: 新 AES-GCM)
orm_table_field_names ORM 模型 → 该表字段名集合 (纯反射, 不连数据库)
export_to_csv ORM 模型对应表 → CSV (默认最多 10000 行, 支持 keyset 流式 / 字段完整度优先两种模式)
import_from_csv CSV → ORM 模型对应表 (按主键覆盖写入, 跨方言)

两种工作模式:

from apiboot.db.sql.utils import encrypt, decrypt, decrypt_encrypt

# 1) 实例模式: 递归加密单个对象 / dict
encrypt(record)                          # 自动读 __encrypted_fields__
encrypt({"mob_no": "138..."}, fields=["mob_no"])

# 2) 查表模式: 传 SQLModel table 类 → 查表批量处理并写回
encrypt(UserMonitorModel, dry_run=True)          # 只统计不写库
encrypt(UserMonitorModel, pk_value="abc123")     # 只处理指定主键
decrypt(UserMonitorModel)                        # 批量解密当前加密字段
decrypt_encrypt(UserMonitorModel)                # 批量还原"已移除字段"的孤儿密文

passphrase 留空 = 自动从 .env 读 ENCRYPT_SECRET; workers>0 走多进程并行 (上限 4)。 decrypt_encrypt 解决的是"业务把某个字段从 __encrypted_fields__ 移除了, 但 DB 里还是密文"的场景 —— 用 decrypt 解不掉 (它只管当前列表里的字段), 必须用 decrypt_encrypt。

from apiboot.db.sql.utils import export_to_csv, import_from_csv, is_encrypted

path = export_to_csv(UserModel, max_rows=5000)     # 返回 csv 路径
rows = import_from_csv(UserModel, path, batch_size=1000)   # 返回处理行数

Redis KV

init_redis / close_redis / get_redis
set_value / get_value / delete / exists / expire / mget / set_json / get_json / ping
get_value_raw / read_json / scanned_keys / prefixed_pattern / get_redis_prefix
ainit_redis / aclose_redis / aget_redis / aget_redis_session
aset_value / aget_value / adelete / aexists / aexpire / amget / aset_json / aget_json / aping
aget_value_raw / aread_json / ascanned_keys

支持 redis 3.5+ (仅 sync), 4.2+ (sync + async), 5.0+ / 6.0+ 推荐。

集群模式: REDIS_CLUSTER_NODES=host1:port,host2:port,host3:port (自动启用)。

连接池大小: REDIS_MAX_CONNECTIONS=N (高并发 FastAPI 建议 100~200, 默认 redis-py 自定)。 Key 前缀: REDIS_KEY_PREFIX=xxx: (自动加到所有 key 上)。

Redis 分布式锁 (apiboot.db.redis.lock)

类型 API
同步 RedisLock / LockAcquireError / acquire_lock / with_lock / locked
异步 AsyncRedisLock / AsyncLockAcquireError / aacquire_lock / awith_lock / alocked
常量 DEFAULT_TTL=30 / DEFAULT_RETRY_INTERVAL=0.1 / DEFAULT_RENEW_RATIO=1/3

Redisson 风格保证:

  • 🛡️ Lua compare-and-delete — 只删自己 token 的锁, 防止误删别人的锁
  • 🔄 watchdog 自动续期 — 后台线程 (sync) / asyncio.Task (async), 默认开启
  • ⏳ 阻塞等锁 — spin 循环 + 超时控制

定时任务 (apiboot.cron)

from apiboot.cron import scheduled_job, start_scheduler

@scheduled_job("cron", hour=6, minute=0, lock=True, lock_ttl=7200)
def _daily_pipeline_6am():
    print("早上 6 点跑批")

if __name__ == "__main__":
    start_scheduler()    # 无需传扫描路径 —— 装饰器已自动注册

异步版 (FastAPI lifespan):

from apiboot.cron import async_scheduled_job, astart_scheduler, astop_scheduler

@async_scheduled_job("cron", hour=6, minute=0, lock=True)
async def _daily_pipeline_async():
    print("async 跑批")

@asynccontextmanager
async def lifespan(app):
    await astart_scheduler()
    yield
    await astop_scheduler()

约定目录自动扫描 (TASKS_DIR)

项目结构
├── tasks/
│   ├── sync_data.py    # def register(scheduler): scheduler.add_job(...)
│   └── report.py
└── .env  →  TASKS_DIR=tasks    # 默认值, 目录不存在静默跳过
# start_scheduler 启动时会自动调 register_jobs_from_dir(tasks_dir)
# 等价于在 main.py 里手动写 register_jobs_from_dir("tasks", scheduler_obj)
API 说明
同步 scheduled_job / start_scheduler / stop_scheduler / get_scheduler / scheduler
异步 async_scheduled_job / ainit_scheduler / astart_scheduler / astop_scheduler / scheduler_async
约定扫描 register_jobs_from_dir / register_jobs_from_files (与传统 def register(scheduler) 风格兼容)
配置 helper build_job_defaults / default_timezone / is_scheduler_enabled
版本探测 HAS_APSCHEDULER / APSCHEDULER_VERSION_STR

多 worker 防重 (生产必备):

# ✅ 生产环境必须带 lock=True, 否则 K8s 多副本或 --workers N 会让任务被执行 N 次
@async_scheduled_job("cron", hour=3, minute=0, lock=True, lock_ttl=7200)
async def _daily_pipeline():
    ...

# 锁 key 自定义 (任务函数接收参数)
@async_scheduled_job("cron", hour=3, minute=0, lock=True,
                     lock_key="aml:pipeline:{part_dt}")
async def _task(part_dt: str):
    ...

降级: Redis 没装 → 警告日志 + 任务照常执行; 拿不到锁 → INFO + 跳过本轮。

LLM / Agent (apiboot.llm)

模块 功能 依赖
llm.init_model LangChain chat model 一键构造 (自动派发 provider) langchain ≥ 1.0
llm.agent.ChatAgent 流式聊天 Agent 封装 (适配 FastAPI StreamingResponse) langchain
llm.model.ChatModel 面向对象的 lazy 构造版本 (ChatModel()()) langchain
apiboot.torch.get_torch_device CUDA / MPS / CPU 设备探测 torch
llm.huggingface.download_models HuggingFace 模型下载 (统一入口) huggingface-hub
data.utils.jieba_utils jieba 中文分词懒加载封装 jieba
from apiboot.data.utils.jieba_utils import lcut, load_userdict

load_userdict("./jieba自定义词典.txt")
words = lcut("小明毕业于北京大学计算机系")
# → ['小明', '毕业', '于', '北京大学', '计算机系']

迁移说明: 原 apiboot.llm.utils.jieba_utils 已迁移到 apiboot.data.utils.jieba_utils。 旧路径下不再保留兼容 shim, 项目内无外部引用, 直接迁移。

📦 模块组织: init_model 的实现拆到 apiboot.llm.model.base, apiboot.llm.model.__init__ 仅做导出。业务方 from apiboot.llm import init_model 不受影响。

模型下载 (apiboot.llm.huggingface)

业务侧只调一个方法, 别自己写下载逻辑:

from apiboot.llm.huggingface import download_models

download_models("bert-base-uncased")                          # 小模型 → HF 默认缓存
download_models(["org/repo-a", "org/repo-b"])                 # 多个模型
download_models({"org/a": ["model.safetensors"], "org/b": None})  # 多个 + 每个的文件白名单
download_models("org/repo", target="ml_models")               # 下到 ml_models/repo/
download_models("org/repo", dry_run=True)                     # 只看要下什么, 不下载

第一个参数三种写法: "repo" / ["repo1", "repo2"] / {"repo": [白名单], ...} (白名单 None = 全要)。

它自己判断的事 (业务侧不用传参):

判断的东西 规则 后果
模型多大 查远端清单求和 ≤ 1 GiB 走 snapshot_download, 更大走 curl 批量下载
单文件还是多文件 数文件个数 单文件 → 单线程, 多文件 → 最多 4 线程并行
有没有鉴权 传了 token 或环境变量里有 HF_TOKEN 走 snapshot_download (只有它能带 token)
要不要精确白名单 给了文件名单 走 curl 批量下载 (snapshot_download 只认 glob)
  • 落哪: target=None → HuggingFace 标准缓存 (~/.cache/huggingface/hub), 之后 from_pretrained(repo_id) 直接命中; 传路径 → 当基础目录, 模型落 <target>/<repo 后段>/; 传 dict → 每个模型精确指定目录。
  • 日志全在里面: 计划 / 磁盘预检 / 下载过程 / 汇总 都由 download_models 打印, 调用方不用写 print。
  • 空间预检: check_free_space(needed_bytes) → (够不够, 剩余字节)。
  • 底层两套实现都在同一个文件 apiboot/llm/huggingface/download_model.py 里: download_repo (curl 断点续传 + 文件白名单 + 总量进度条 + 磁盘预检 + 按文件并行) 和 snapshot_download (huggingface_hub 官方, 小模型够用)。
  • ⚠️ 包 __init__ 里把函数 download_model 导出成了包属性, 而包内又有个 同名子模块 apiboot/llm/huggingface/download_model.py —— 两者撞名。 由 _DownloadModelCompat 外观对象调和: download_model 既能当函数调 (转发旧接口), 又能当子模块取属性 (转发给同名模块)。

OCR (apiboot.ocr)

import asyncio
from apiboot.ocr import MinerU

client = MinerU()                                       # 从 .env 读 MINERU_URL
md = asyncio.run(client.parse_file("/path/to/report.pdf"))
类 / 函数 功能
MinerU MinerU API 异步客户端 (PDF / 图片 / Office → markdown)
MinerUAPIError MinerU 调用失败的异常 (含 status_code / url / method)
mineru_is_supported 判断文件扩展名是否被 MinerU 支持
SUPPORTED_EXTENSIONS / UNSUPPORTED_EXTENSIONS 支持 / 不支持的扩展名常量

支持格式: .pdf / .jpg / .jpeg / .png / .gif / .bmp / .webp / .tiff / .tif / .xlsx / .docx / .pptx / .ofd (.xls 不支持)。

后端可配: MINERU_BACKEND=hybrid-engine (默认, 平衡) / vlm-engine (精度高, 速度慢); MINERU_EFFORT=medium / high。

对象存储 (apiboot.oss)

from apiboot.oss.minio import MinioClient
from apiboot.oss.common import OSSUploadRequest, OSSQueryRequest

client = MinioClient()                        # 从 .env 读 MINIO_* 配置
resp = client.upload(OSSUploadRequest(
    file_path="/path/to/report.pdf",
    object_name="2026/10/report.pdf",
))
print(resp.data.url)                          # 公网可下载地址 (预签名 URL)
方法 功能
upload / upload_many 新增: 单个 / 批量上传
delete / delete_many 删除: 单个 / 批量删除
update / update_many 修改: 单个 / 批量 (覆盖内容 / 改元数据 / 改名)
stat / stat_many 查询: 单个 / 批量 (按对象名列表 或 按前缀列举)
list_objects 按前缀列举 bucket 内容 (返回 OSSListResponse)
download / download_many 下载: 单个 / 批量 (支持 offset / length 断点续传区间)
presigned_url 生成单个文件的预签名下载 URL
bucket_exists / make_bucket bucket 检查 / 创建

请求体 / 响应体可直接当 FastAPI 的 request_body / response_model:

  • apiboot.oss 包导出 42 个公开符号 (from apiboot.oss import OSSUploadRequest, OSSListRequest, ...)
  • apiboot.oss.common 的 __all__ 有 39 个 (公共常量 / 异常 / 请求体 / 响应体 / 公共方法, 无第三方依赖)
  • OSSListRequest / OSSListResponse / OSSObjectInfo 定义在 common.py 里, 但由 apiboot.oss 包导出 (不在 common.__all__ 中)
分类 类型
请求体 OSSUploadRequest / OSSBatchUploadRequest / OSSDeleteRequest / OSSBatchDeleteRequest / OSSUpdateRequest / OSSBatchUpdateRequest / OSSQueryRequest / OSSBatchQueryRequest / OSSDownloadRequest / OSSBatchDownloadRequest / OSSListRequest
响应体 OSSUploadResponse / OSSDeleteResponse / OSSUpdateResponse / OSSQueryResponse / OSSDownloadResponse / OSSListResponse / OSSBatchResponse (+ OSSFileInfo / OSSObjectInfo / OSSBatchItem)
载荷 OSSFilePayload (批量上传的单文件描述)
异常 OSSError (基类) / OSSConfigError / OSSFileNotFoundError / OSSFileExistsError / OSSBucketNotFoundError / OSSUploadError / OSSDeleteError / OSSQueryError / OSSUpdateError
工具 parse_endpoint / build_public_url / guess_content_type / normalize_object_name / join_object_name / clamp_presign_expire
常量 OSS_DEFAULT_CONTENT_TYPE / OSS_MAX_BATCH_SIZE=1000 / OSS_MAX_PRESIGN_EXPIRE=7d / OSS_DEFAULT_PRESIGN_EXPIRE / OSS_CHUNK_SIZE (仅 common)

查询响应里的 OSSFileInfo 带两个地址:

  • url —— 预签名 URL, 带签名与有效期, 无需凭证即可公网下载 (有效期由 MINIO_PRESIGN_EXPIRE 控制, 默认 7 天)
  • public_url —— 直链, 仅当 bucket 开放了匿名读策略时才能直接访问

批量方法默认逐条收集错误 (strict=False); 传 strict=True 则任一失败立即抛异常。

bucket 自动创建: 写操作 (upload / upload_many / update / update_many) 在发现 bucket 不存在时会自动创建, 不用先手动调 make_bucket()。删除和查询不会触发创建 —— bucket 不存在时直接报 OSSBucketNotFoundError。想关掉在 .env 写 MINIO_AUTO_CREATE_BUCKET=false。

.env 配置:

MINIO_URL=http://127.0.0.1:9000     # 也支持 https:// 或不带 scheme
MINIO_USERNAME=minioadmin
MINIO_PASSWORD=minioadmin
MINIO_BUCKET=myapp-oss
MINIO_AUTO_CREATE_BUCKET=true      # 默认 true, 写操作自动建桶

需要 pip install minio (官方 Python SDK)。批量删除走 S3 DeleteObjects API, 单批最多 1000, 超出自动分批。

数据 / ML 工具

apiboot.torch

函数 功能 依赖
get_torch_device() 返回当前最优 torch.device (cuda > mps > cpu) torch
get_device_info() 返回详细探测 dict (含设备名 / 显存等) torch

⚠️ 唯一位置: 原 apiboot.llm.torch 已于 2026-11 物理删除, 只保留 apiboot.torch。 旧代码请改成 from apiboot.torch import get_torch_device。

apiboot.data.utils.pd_utils (39 个)

分类 函数
空值处理 drop_empty_rows / fill_empty / fillna_with_strategy / ffill_column / bfill_column / missing_summary
类型转换 safe_to_numeric / safe_to_datetime / safe_to_categorical
去重 drop_duplicate_rows
字符串 normalize_string_column / truncate_string_column / extract_numbers_from_string / split_column / contains_pattern
列操作 select_columns / rename_columns / drop_columns / reorder_columns / cast_columns / move_column
日期处理 extract_date_parts / fill_missing_dates
数值处理 clip_outliers_iqr / bin_numeric_column
断言 assert_columns_exist / assert_no_nulls / assert_unique
报告 / 统计 value_counts_pct / describe_extended
重塑 / 抽样 melt_to_long / pivot_to_wide / stratified_sample / groupby_agg
分块 / I/O chunk_dataframe / safe_read_csv
通用 df_to_dict / sanitize_for_sql / sanitize_records

apiboot.data.utils.sklean_utils (20 个)

分类 函数
数据缩放 standard_scale / minmax_scale / robust_scale / maxabs_scale
编码 label_encode / onehot_encode
填充缺失 simple_impute
模型评估 classification_metrics / regression_metrics / confusion_matrix_df / cross_validate
特征 polynomial_features
数据切分 train_test_split / train_val_test_split / kfold_split / stratified_kfold_split
模型持久化 save_model / load_model (用 joblib)
重采样 oversample_minority / undersample_majority
from apiboot.torch import get_torch_device, get_device_info
from apiboot.data.utils.sklean_utils import train_test_split, standard_scale
from apiboot.data.utils.pd_utils import drop_empty_rows, missing_summary

device = get_torch_device()               # torch.device("mps") / "cuda" / "cpu"
model.to(device)

X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

# sklearn 工具 (走 joblib 持久化, 不要用 pickle)
from apiboot.data.utils.sklean_utils import save_model, load_model
save_model(model, "model.joblib")
model = load_model("model.joblib")

⚠️ apiboot.data.utils 顶层只 re-export 10 个 (train_test_split + 7 个 jieba + 2 个 sql 清洗), 其余函数请从子模块显式 import: from apiboot.data.utils.sklean_utils import standard_scale。

重试 (apiboot.retry)

Tenacity 的懒加载透传 (44 个符号), 行为完全等价:

分类 符号
核心 retry / Retrying / AsyncRetrying / RetryError / TryAgain / NO_RESULT
停止策略 stop_after_attempt / stop_after_delay / stop_before_delay / stop_any / stop_all / stop_never / stop_when_event_set
等待策略 wait_fixed / wait_random / wait_random_exponential / wait_incrementing / wait_exponential / wait_exponential_jitter / wait_full_jitter / wait_combine / wait_chain / wait_none / wait_exception
重试条件 retry_if_result / retry_if_not_result / retry_if_exception / retry_if_exception_type / retry_if_not_exception_type / retry_if_exception_cause_type / retry_if_exception_message / retry_if_not_exception_message / retry_unless_exception_type / retry_any / retry_all / retry_always / retry_never
回调钩子 before_log / after_log / before_sleep / before_sleep_log / before_nothing / after_nothing / before_sleep_nothing

📦 实现: 本模块用 PEP 562 lazy module (__getattr__ + __dir__) 实现按需导出, Python 3.7+ 标准 pattern。业务方 from apiboot.retry import ... 无感知。

from apiboot.retry import retry, stop_after_attempt, wait_fixed, retry_if_exception_type

@retry(stop=stop_after_attempt(3), wait=wait_fixed(1), retry=retry_if_exception_type(ConnectionError))
def fetch():
    ...

工具集合 (apiboot.utils)

顶层 from apiboot.utils import ... 一行可用 201 个纯 stdlib 函数 (不需要装任何第三方包):

分类 函数
路径 (12) get_project_root / get_parent_path / ensure_dir / path_join / normalize_path / get_path_segments / to_relative_path / to_absolute_path / is_relative_to / change_extension / safe_join / find_executable
文件 (26) get_file_type / get_file_name / get_file_stem / get_newname / get_file_dir / get_file_size / human_bytes / get_modified_time / get_created_time / file_exists / is_file / is_directory / read_text / read_text_safe / write_text / read_bytes / write_bytes / read_lines / write_lines / delete_file / copy_file / move_file / rename / touch / list_files / list_dirs
对象 / 字典 (21) obj_to_dict / dict_to_obj / obj_is_null / obj_is_not_null / obj_get_or_null / obj_to_str / obj_get_attr / obj_filter_none / obj_pick / obj_omit / obj_merge / obj_deep_copy / obj_shallow_copy / is_dataclass / is_pydantic_model / has_sqlalchemy_table / model_field_names / model_validate / model_dump / strip_none_values / normalize_pydantic_json
字符串 (41) str_len / str_is_empty / str_is_not_empty / str_is_blank / str_is_not_blank / str_preview / to_snake_case / to_camel_case / to_pascal_case / to_kebab_case / truncate / truncate_middle / pad_left / pad_right / pad_center / collapse_whitespace / strip_chars / remove_all_whitespace / mask_email / mask_phone / mask_id_card / is_chinese / contains_chinese / contains_cjk / is_digits / is_ascii / is_uuid / contains_any / contains_all / default_if_empty / default_if_blank / slugify / reverse_str / repeat_str / remove_prefix / remove_suffix / generate_uuid / to_str / render_template / content_tokens / token_coverage
日期时间 (35) now / today / yesterday / timestamp / timestamp_ms / timestamp_us / now_utc / timestamp_to_datetime / timestamp_to_str / format_time / parse_time / try_parse_datetime / parse_to_timestamp / start_of_day / end_of_day / start_of_month / end_of_month / add_days / add_hours / add_minutes / add_seconds / add_months / add_years / is_same_day / is_today / is_yesterday / days_between / hours_between / format_iso / parse_iso / to_utc / to_local / humanize_duration / is_leap_year / days_in_month
JSON (6) to_json_str / from_json_str / safe_from_json / load_json_file / save_json_file / json_equal
数值 (4) to_int / to_float / to_bool / to_int_list
列表 (33) list_len / list_is_empty / list_is_not_empty / list_is_blank / list_union / list_intersection / list_difference / list_symmetric_difference / list_contains / list_contains_any / list_contains_all / list_contains_none / list_index_of / list_distinct / list_reverse / list_sort / list_flatten / list_chunk / list_partition / list_take / list_skip / list_concat / list_push / list_compact / list_remove / list_remove_blank / list_first / list_last / list_get / list_safe / list_join / list_to_tuple / list_count
数学 (22) add / sub / mul / div / round_to / percent / change_percent / random_int / random_float / random_choice / random_sample / random_seed / clamp / lerp / is_close / gcd / lcm / is_prime / sum_safe / mean / median / stdev
依赖探测 (1) get_installed_version

需要第三方包的子模块

子模块 功能 可选依赖
utils.base_utils 懒加载工具: require_module (强制模式, 缺依赖报错带 pip 命令) / get_installed_version stdlib
utils.http_utils 同步 + 异步 HTTP 客户端 (HttpClient: 连接池复用 / 指数退避自动重试 / 流式下载 / on_retry on_progress 回调) + is_safe_url / redact_headers / HttpError requests / httpx / aiohttp
utils.queue_utils.StreamQueue 异步流式队列 (SSE / WebSocket 哨兵结束) stdlib
utils.obj_utils 对象 ↔ dict 互转 (pydantic / SQLAlchemy / dataclass 自动识别) pydantic / sqlalchemy / sqlmodel (可选)
utils.json_utils JSON 序列化 + pydantic 兼容 (pydantic_to_json / pydantic_from_json / get_pydantic_major_version) pydantic (可选)
utils.jsonl_utils JSON Lines 行式读写 (jsonl_iter 流式读 / jsonl_save 写) stdlib
utils.num_utils 数值转换 (to_int / to_float / to_bool / to_int_list) stdlib
utils.file_utils 文件读写 (比顶层多 append_text / read_file_as_base64 / write_file_from_base64 / is_absolute_path / ensure_parent_dir) stdlib
utils.datetime_utils 时间工具 (比顶层多 to_datetime + 4 个格式常量) stdlib
utils.image_utils PDF / PPTX → 图片 (PyMuPDF + LibreOffice), 含单页 / 缩略图 / base64 pymupdf + 系统 LibreOffice
utils.poi_utils 文档转文本: file_to_text (按扩展名自动分发) / pdf_to_text / pptx_to_text / word_to_text / excel_to_text / excel_to_dicts / excel_sheet_names + pdf_metadata / pptx_metadata / docx_metadata pymupdf / python-docx / python-pptx / openpyxl / xlrd / pandas
utils.ip_utils 纯离线 IP → 省/市/区/ISP 查询 (ip2region 数据, IPv4 + IPv6) stdlib
utils.phone_utils 纯离线 手机号 → 归属地 / 运营商 查询 (463k 号段) stdlib
utils.snowflake_utils 雪花 ID 生成器 (线程安全全局单例 + 反解) snowflake-id
utils.password_utils 用户密码哈希 (PBKDF2) + 字段加密 (Fernet) + HMAC + 随机 token + 强度评估 stdlib + cryptography
from apiboot.utils.base_utils import require_module

# 强制模式: 没装就报错, 消息里带 pip install 命令
sa = require_module("sqlalchemy", purpose="MySQL 同步功能")
fitz = require_module("fitz", purpose="pdf_to_text", pip_name="pymupdf")

已废弃的 JSON 别名 (apiboot.utils.json_utils)

历史 API 仍能 import (PEP 562 __getattr__ + DeprecationWarning), 但已不推荐新代码使用:

废弃别名 替代
to_json_bytes to_json_str(obj).encode("utf-8")
from_json_bytes from_json_str(data.decode("utf-8"))
pretty_json to_json_str(obj, indent=2)
minify_json to_json_str(obj, separators=(",", ":"))
validate_json from_json_str(text) 并捕获 json.JSONDecodeError
jsonl_iter apiboot.utils.jsonl_utils.jsonl_iter
jsonl_save apiboot.utils.jsonl_utils.jsonl_save
strip_none_values apiboot.utils.obj_utils.strip_none_values
normalize_pydantic_json apiboot.utils.obj_utils.normalize_pydantic_json
load_pydantic_file dict_to_obj(load_json_file(path), cls) / model_validate
save_pydantic_file save_json_file(path, obj)

顶层 apiboot.utils 只导出 6 个 JSON 名字 (to_json_str / from_json_str / safe_from_json / load_json_file / save_json_file / json_equal), 废弃别名只在 apiboot.utils.json_utils 里能 import。

字符串工具 (apiboot.utils.str_utils)

参考 hutool (Java) 的 :class:StringUtil 思路, 按场景分组, 全部 None 安全 (判空 / 默认值 / 搜索), 类型严格 (大小写转换 / 校验遇到非 str 抛 TypeError):

分类 函数
长度 / 判空 str_len / str_is_empty / str_is_not_empty / str_is_blank / str_is_not_blank / str_preview
大小写转换 to_snake_case / to_camel_case / to_pascal_case / to_kebab_case
截断 truncate / truncate_middle (中间省略, 适合长 ID/Hash 显示)
填充 pad_left / pad_right / pad_center
空白归一化 collapse_whitespace / strip_chars / remove_all_whitespace
掩码 (日志脱敏) mask_email / mask_phone / mask_id_card
校验 is_chinese / contains_chinese / contains_cjk / is_digits / is_ascii / is_uuid
搜索 contains_any / contains_all
默认值 default_if_empty / default_if_blank
URL slug slugify (NFKC 归一化 + ASCII-only, 中文会被 drop, 需拼音接 pypinyin)
反转 / 重复 reverse_str / repeat_str
前后缀移除 remove_prefix / remove_suffix (兼容 3.7+)
UUID generate_uuid
转换 / 模板 to_str / render_template
分词 / 覆盖 content_tokens / token_coverage (常用于分词命中率评估)
from apiboot.utils import (
    to_snake_case, mask_phone, slugify,
    contains_any, default_if_blank, repeat_str,
)

to_snake_case("HelloWorld")          # → "hello_world"
mask_phone("13800138000")            # → "138****8000"
slugify("Hello World! 你好")           # → "hello-world"  (中文 drop)
contains_any("error.log", ".log", ".err")  # → True
default_if_blank(None, "N/A")        # → "N/A"
repeat_str("-", 30)                  # → "------------------------------"

列表工具 (apiboot.utils.list_utils)

参考 hutool (Java) 的 :class:CollUtil 思路, 按场景分组, 全部 None 安全 / 不可变优先 (排序 / 反转 / 去重 / 移除 都返回新列表, 不修改原列表):

分类 函数
长度 / 判空 list_len / list_is_empty / list_is_not_empty / list_is_blank
集合运算 list_union / list_intersection / list_difference / list_symmetric_difference (元素需可哈希)
包含 / 搜索 list_contains / list_contains_any / list_contains_all / list_contains_none / list_index_of
排序 / 反转 / 去重 / 扁平 list_distinct (保序) / list_reverse / list_sort (不修改原列表) / list_flatten (支持 depth)
分块 / 切片 / 拆分 list_chunk / list_partition / list_take / list_skip
添加 / 删除 / 合并 list_concat / list_push / list_compact / list_remove / list_remove_blank
安全访问 list_first / list_last / list_get / list_safe
转换 / 实用 list_join / list_to_tuple / list_count
from apiboot.utils import (
    list_distinct, list_chunk, list_partition,
    list_remove_blank, list_compact, list_get,
)

list_distinct([1, 2, 2, 3, 1])              # → [1, 2, 3]  (保序)
list_chunk([1, 2, 3, 4, 5], 2)              # → [[1, 2], [3, 4], [5]]
list_partition([1,2,3,4], lambda x: x%2==0) # → ([2, 4], [1, 3])
list_remove_blank([None, "", "x", 0])       # → ["x", 0]   (None 和空白都去, 但保留 0)
list_compact([1, None, 2])                  # → [1, 2]     (只去 None)
list_get([1, 2, 3], 10, default="X")        # → "X"        (越界返回 default)

加密 / 密码工具 (apiboot.utils.password_utils)

术语区分 (代码里这 3 个词含义完全不同, 别混用):

中文 参数名 用途 用在
用户密码 password 登录认证, 单向哈希 hash_password / verify_password
加密口令 passphrase 派生 Fernet key 的种子 encrypt / decrypt 系列
共享密钥 key HMAC 签名的对称密钥 hmac_sign / hmac_verify
分类 函数 依赖
用户密码哈希 hash_password / verify_password (PBKDF2-HMAC-SHA256, 200k 轮) stdlib
密码强度 password_entropy / password_strength_score / check_password_needs_rehash stdlib
字段对称加密 encrypt / decrypt (Fernet, AES-128-CBC + HMAC-SHA256) cryptography
NULL 友好版 encrypt_or_none / decrypt_or_none (None/空串直接透传) cryptography
批量加解密 encrypt_dict / decrypt_dict (dict 指定字段批量加解密) cryptography
密文识别 is_fernet_encrypted (判断是不是 Fernet 密文) stdlib
HMAC 签名 hmac_sign / hmac_verify (HMAC-SHA256, 常数时间比较) stdlib
随机 token generate_token (URL-safe base64) stdlib

典型场景: 数据库字段加密 → API 返回前端前解密

# .env
ENCRYPT_SECRET=<48 字节高熵字符串>

# 业务代码
from apiboot.config import env as _env
from apiboot.utils.password_utils import encrypt_dict, decrypt_dict

PASSPHRASE = _env.get_encrypt_secret()
ENCRYPT_FIELDS = ["phone", "id_card", "address"]

# 写库前 (model → dict 后批量加密)
db.execute(
    "INSERT INTO users ...",
    encrypt_dict(
        {"name": "张三", "phone": "13800138000", "address": "北京市..."},
        fields=ENCRYPT_FIELDS,
        passphrase=PASSPHRASE,
    ),
)

# 读出后 (DB row → dict → 批量解密 → 返回前端)
row = db.fetchone("SELECT * FROM users WHERE id = %s", uid)
return decrypt_dict(dict(row), fields=ENCRYPT_FIELDS, passphrase=PASSPHRASE)

⚠️ 运维红线:

  • 长度建议 ≥ 32 字符; 生成命令:
    ENCRYPT_SECRET=$(python -c "from apiboot.utils.password_utils import generate_token; print(generate_token(48))")
    
  • ⚠️ 丢失 = 历史加密数据永久无法恢复, 务必多处离线备份 (密码管理工具 / 加密保险柜)
  • ⚠️ 更换密钥需要批量重新加密存量数据, 务必先做灰度
  • 敏感度: ⚠️ 高 (supervisor 子进程环境变量白名单不会透传)

日志 (apiboot.log)

from apiboot import logger
logger.info("hello")

或显式从模块导入:

from apiboot.log.logger import setup_logger, get_logger, capture_apiboot_logs

logger = setup_logger("myapp", log_dir="./logs", level=logging.INFO)

特性一览:

  • 📁 默认 ./logs/<name>.log, 按天切割, 保留 7 天
  • 🖥️ 控制台 (stdout) + 文件双输出
  • 🔒 同名 logger 幂等 (多次 setup 不会重复挂 handler)
  • 📍 智能锚定日志目录: 显式 log_dir > .env LOG_DIR > <项目根>/logs > ./logs
  • 🏷️ 智能解析 logger 名: 显式 name > .env LOG_NAME > .env APP_NAME > "app"
  • ⚙️ .env 中 LOG_LEVEL 配置级别 (默认 INFO)
  • 🚫 .env 中 LOG_ENABLE=false 关闭文件日志
  • 🛡️ Surrogate 安全 — 自动清洗 LLM 流式输出里偶发的未配对 UTF-16 代理对
  • 🪝 自动接管 apiboot 内部 logger — capture_internal=True 让 apiboot.config.config 等子模块的日志也走统一 handler
  • 🐢 目录创建推迟到首次写入 (delay=True + _LazyDirTimedRotatingFileHandler)

🔌 可选依赖矩阵

核心原则: 运行时硬依赖只有 apscheduler>=3.10.4 (Python < 3.10 额外带 typing_extensions)。 业务侧任何 import 第三方包的代码都走懒加载, 用户项目自己装什么版本, apiboot 就用什么版本。 pip install apiboot 之后 import apiboot 永远不会因为缺失依赖而失败。

业务需求 需要装的可选依赖
HTTP 客户端 (同步) requests 或 httpx
HTTP 客户端 (异步) httpx 或 aiohttp
通用 SQL 数据库 sqlalchemy + pymysql/aiomysql (MySQL)、psycopg2-binary/asyncpg (PostgreSQL)、aiosqlite (SQLite 异步)
SQLModel 兼容 (旧项目) sqlmodel
字段加密列 cryptography (Fernet) + pydantic (JSON 列)
Redis redis (3.5+ 同步 / 4.2+ 异步)
定时任务 已自带 apscheduler (硬依赖)
重试 tenacity
FastAPI 中间件 fastapi + httpx
Pydantic Schema (BaseSchema) pydantic ≥ 2.0
Pydantic 分页 (PageReq) pydantic ≥ 1.x
LLM langchain + langchain-core (≥ 1.0)
中文分词 jieba
OCR (MinerU) httpx
文档解析 (PDF / Office) pymupdf / python-docx / python-pptx / openpyxl / xlrd / pandas
图片转换 (PDF / PPTX → 图片) pymupdf + 系统 LibreOffice
雪花 ID snowflake-id
Fernet 对称加密 cryptography
深度学习 (torch 设备探测) torch
数据处理 (pandas) pandas + numpy
sklearn 工具 scikit-learn + joblib
模型下载 (HuggingFace) huggingface-hub
对象存储 (MinIO) minio (官方 Python SDK)
CLI 内存检测 psutil (macOS / Windows 必需, Linux 用 /proc 不需要)

新增配置项 (.env)

Key 默认 用途
APP_ENV (空) 环境名; 配了会自动加载 .env.<APP_ENV> (再回退 .env)
APP_NAME (空) 应用名 (同时是 logger 名 / 表名前缀的默认值)
DEBUG false 调试开关
SUCCESS_CODE 200 业务成功状态码 (SUCCESS.code), 前端用 resp.success 判断时可不关心此值
SUCCESS_MESSAGE 成功 业务成功默认文案 (SUCCESS.message)
DB_MODELS_DIR models init_db 启动时自动 import 的模型目录 (不存在静默跳过)
DB_MODELS_FALLBACK_SCAN_ROOT true models/ 不存在时是否兜底扫描项目根目录的 .py
DB_DRIVER 后端默认 同步数据库驱动覆盖; MySQL 默认 pymysql, PG psycopg2, SQLite sqlite
DB_ASYNC_DRIVER 异步默认 异步数据库驱动; fallback 到 DB_DRIVER
DB_POOL_SIZE / DB_MAX_OVERFLOW 10 / 20 SQLAlchemy 连接池常驻 / 溢出连接数
DB_POOL_RECYCLE 3600 连接回收秒数
DB_POOL_PRE_PING true 取连接前 ping 一遍
DB_POOL_TIMEOUT 30 等空闲连接的秒数
DB_CONNECT_TIMEOUT / DB_READ_TIMEOUT / DB_WRITE_TIMEOUT 10 / 300 / 60 驱动层 socket 超时 (秒)
TASKS_DIR tasks start_scheduler 启动时自动 register 的任务目录 (不存在静默跳过)
REDIS_DB 0 Redis 逻辑库编号
REDIS_KEY_PREFIX (空) 所有 key 的统一前缀 (如 myapp:)
REDIS_MAX_CONNECTIONS (redis-py 默认) Redis 连接池大小; 高并发 FastAPI 建议 100~200
SCHEDULER_ENABLE true 定时任务总开关
SCHEDULER_TIMEZONE Asia/Shanghai 调度器时区
SCHEDULER_MISFIRE_GRACE_TIME 60 任务延迟多少秒内仍允许补跑
SCHEDULER_MAX_WORKERS 8 调度器线程池大小
SNOWFLAKE_INSTANCE_ID 0 雪花 ID 的实例号 (多进程部署必须各不相同)
ENCRYPT_SECRET (空) 数据库字段加密口令 (Fernet 派生种子); 通过 get_encrypt_secret() 读取, 建议长度 ≥ 32 字符
LLM_MODEL / LLM_API_KEY / LLM_API_KEYS / LLM_BASE_URL (空) LLM 模型 / 单 key / 多 key 轮询列表 / base url
MINIO_URL (空) MinIO 服务地址; 带 scheme (http:// / https://) 或不带均可
MINIO_USERNAME (空) MinIO 访问用户名
MINIO_PASSWORD (空) MinIO 访问密码 (兼容 MINIO_PASSSWORD 笔误写法)
MINIO_BUCKET (空) 默认存储桶名; 所有 OSS 请求体可用 bucket 字段临时覆盖
MINIO_REGION (空) MinIO 区域 (本地部署一般不用配)
MINIO_PRESIGN_EXPIRE 604800 预签名 URL 有效期 (秒), 上限 7 天 (官方 SDK 硬限制), 越界自动夹紧
MINIO_AUTO_CREATE_BUCKET true 写操作时 bucket 不存在是否自动创建 (只对 upload / update 生效, delete / stat 不建桶)
APIBOOT_PATH_ANCHOR project_root config.path() 的默认锚点策略; 推荐嵌套 monorepo 子项目用 env

🐍 Python 3.7 兼容性

apiboot 承诺在 Python 3.7+ 上可用 (pyproject.toml 中 requires-python = ">=3.7")。 包内部代码禁止使用 3.8+ 才引入的语法。

工具包内禁止的语法

语法 引入版本 替代写法
:= 海象 3.8 (PEP 572) 拆成普通赋值 + 判断
f"{x=}" debug 3.8 (PEP 498) f"{x}={x}"
def f(a, /, b) positional-only 3.8 (PEP 570) 用 keyword-only def f(a, *, b)
dict[str, int] / list[int] 3.9 (PEP 585) Dict[K, V] / List[T] (从 typing 导入)
str | None / int | str 3.10 (PEP 604) Optional[T] / Union[T, U] (从 typing 导入)
match / case 3.10 (PEP 634) if / elif / else
@functools.cache 3.9 @functools.lru_cache(maxsize=None)
importlib.metadata 3.8 3.7 用 pkg_resources 或 importlib_metadata 第三方包

typing.Protocol / typing.Annotated / typing.get_args 在 3.7–3.9 走 typing_extensions 兜底分支 (typing_extensions>=4.0; python_version < '3.10' 已经是运行时依赖, 不用额外装)。

typing 导入完整性 (硬性)

用到的 typing 名必须显式 import, 不能依赖 from __future__ import annotations 兜底:

# ✅ 正确
from typing import Any, List, Optional
def obj_pick(obj: Any, keys: List[str]) -> Any:
    ...

# ❌ 错误 (IDE 报红, 去掉 future 就 NameError)
from typing import Any
def obj_pick(obj: Any, keys: List[str]) -> Any:
    ...

通用 import 模板 (满足 95% 场景):

from typing import (
    Any, Callable, Dict, List, Optional, Tuple, Type, Union,
)

给贡献者的检测脚本

python -c "
import ast, pathlib
TYPING_NAMES = {
    'Any','Callable','ClassVar','Dict','FrozenSet','Generic','Iterable',
    'Iterator','List','Literal','Mapping','NoReturn','Optional','Sequence',
    'Set','Tuple','TYPE_CHECKING','Type','TypeVar','TypedDict','Union',
    'cast','Protocol',
}
for py in pathlib.Path('apiboot').rglob('*.py'):
    if '__pycache__' in str(py): continue
    src = py.read_text()
    tree = ast.parse(src)
    imported = set()
    for n in ast.walk(tree):
        if isinstance(n, ast.ImportFrom) and n.module == 'typing':
            imported |= {a.name for a in n.names}
    used = set()
    for n in ast.walk(tree):
        if isinstance(n, ast.Name) and n.id in TYPING_NAMES: used.add(n.id)
        if isinstance(n, ast.Attribute) and isinstance(n.value, ast.Name) and n.value.id == 'typing':
            used.add(n.attr)
    missing = used - imported
    if missing: print(f'{py}: 缺失 {sorted(missing)}')
"

期望输出: 空。

完整规范 (包括 from __future__ 的副作用分析、Literal / TypedDict / Protocol 等 3.7 可放心用的现代语法) 见 CLAUDE.md "Python 兼容性约束 (硬性)" 章节。


🛠️ 开发与测试

# 安装开发依赖 (含所有懒加载的第三方包, 让 IDE 全绿)
uv sync

# 跑测试
uv run pytest tests/ -v

# API 表面积门禁 (公开函数数不得增长)
uv run python scripts/api_audit.py --check

# 发版流程
uv run python scripts/upload_pypi.py --repository testpypi  # 先 Test PyPI
uv run python scripts/upload_pypi.py                          # 正式 PyPI

📄 License

MIT © yanyue

Made with ❤️ for the Python backend community.

⬆ 回到顶部

Metadata

Release files for apiboot 0.1.34

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for apiboot 0.1.34
File Size Uploaded Provenance Actions
apiboot-0.1.34.tar.gz 13.6 MB Without provenance Details for apiboot-0.1.34.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for apiboot 0.1.34
File Interpreter ABI Platform Actions
apiboot-0.1.34-py3-none-any.whl Python 3 none any Details for apiboot-0.1.34-py3-none-any.whl

Total release size: 27.8 MB

Release files / apiboot-0.1.34.tar.gz

Download URL apiboot-0.1.34.tar.gz
Size 13.6 MB
Tags Source
SHA-256 checksum
How to use checksums
166aa7fd6341899eb74b81689dfd67dc116fa18400ba66c8dee82f2a4569c985
BLAKE2b-256 checksum
How to use checksums
93dc8da1307903ea85ad2231091472d1de5978dd773518a51539a3ad79b8009c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / apiboot-0.1.34-py3-none-any.whl

Download URL apiboot-0.1.34-py3-none-any.whl
Size 14.2 MB
Tags Python 3
SHA-256 checksum
How to use checksums
724c666af4770608b043d6b5368a5f1970f00acc0329272797c711103a8410a8
BLAKE2b-256 checksum
How to use checksums
b374b511069f6796b9df9627b792d7694c5433982f7523805708e52781fb71f3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for apiboot 0.1.34

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.34 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page