Metadata-Version: 2.5
Name: apiboot
Version: 0.1.34
Summary: apiboot：为组件化构建 Api 服务而生
Project-URL: Homepage, https://github.com/yanyue/apiboot
Author: yayo
License: MIT
Keywords: api,boot,scaffolding,toolkit
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.7
Requires-Dist: apscheduler>=3.10.4
Requires-Dist: typing-extensions>=4.0; python_version < '3.10'
Description-Content-Type: text/markdown

<div align="center">

<a id="top"></a>

# 🐚 apiboot

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

<p>
  <a href="https://pypi.org/project/apiboot/"><img src="https://img.shields.io/pypi/v/apiboot?style=flat-square&color=blue" alt="PyPI"></a>
  <a href="https://pypi.org/project/apiboot/"><img src="https://img.shields.io/pypi/pyversions/apiboot?style=flat-square" alt="Python"></a>
  <a href="https://github.com/yanyue/apiboot/blob/master/LICENSE"><img src="https://img.shields.io/github/license/yanyue/apiboot?style=flat-square&color=green" alt="License"></a>
  <a href="https://github.com/yanyue/apiboot"><img src="https://img.shields.io/github/stars/yanyue/apiboot?style=flat-square" alt="Stars"></a>
</p>

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

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

[快速开始](#快速开始) · [模块一览](#模块一览) · [CLI 守护进程](#cli-守护进程管理) · [可选依赖](#可选依赖矩阵)

</div>

---

## ✨ 为什么选择 apiboot

```text
┌─────────────────────────────────────────────────────────────────┐
│ 你的项目                                                          │
│   ├── 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` 分支 |

---

## 📦 安装

```bash
pip install apiboot
```

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

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

```bash
# 最小起步: 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
```

---

<a id="快速开始"></a>

## 🚀 快速开始

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

### ① 一行启动:配置 + 日志

```python
from apiboot import config, logger

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

> 工具包内部读配置统一走 `apiboot.config.env` 的类型化访问器 (业务侧推荐) :
> ```python
> 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 统一响应

```python
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(...)`, 顺序写死,
业务侧只用记一个函数名。也可单独关闭某个中间件或自定义配置:

```python
# 只要响应包装, 不要日志
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`。

### ③ 统一错误体系

```python
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)

```python
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)
```

```python
# 异步版 (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` (异步) 配置覆盖:

```bash
# .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`:

```python
# .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` 内部 |

```python
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`)

```python
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`:

```python
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)`) |

**反模式** (禁止):

```python
# ❌ 自己写 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 风格)

```python
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 重复)

```python
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):

```python
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 接入

```python
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 轮询** (配额周期性耗尽的场景):

```bash
# .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 (交给上层重试)

---

<a id="cli-守护进程管理"></a>

## 🛡️ CLI 守护进程管理

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

```bash
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`。

### 常用参数

```bash
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 实现)。

---

<a id="模块一览"></a>

## 🧩 模块一览

```
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 (异常日志照打)

跳过某些路径:

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

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

```python
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 的日志规范输出:

```python
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 状态码:

```python
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`)

```text
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` 的代码, 改成:
> ```python
> 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` |

```python
# 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 目录扫描**

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

```python
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 支持**

```python
# 测试场景: 换 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`)

```python
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 模型对应表 (按主键覆盖写入, 跨方言) |

**两种工作模式**:

```python
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`。

```python
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

```text
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`)

```python
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):

```python
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`)**

```text
项目结构
├── tasks/
│   ├── sync_data.py    # def register(scheduler): scheduler.add_job(...)
│   └── report.py
└── .env  →  TASKS_DIR=tasks    # 默认值, 目录不存在静默跳过
```

```python
# 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 防重 (生产必备)**:

```python
# ✅ 生产环境必须带 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` |

```python
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`)

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

```python
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`)

```python
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`)

```python
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` 配置:

```bash
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` |

```python
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 ...` 无感知。

```python
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` |

```python
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` (常用于分词命中率评估) |

```python
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` |

```python
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 返回前端前解密**

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

### 日志 (`apiboot.log`)

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

或显式从模块导入:

```python
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`)

---

<a id="可选依赖矩阵"></a>

## 🔌 可选依赖矩阵

> **核心原则**: 运行时硬依赖只有 `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` 兜底:

```python
# ✅ 正确
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% 场景):

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

### 给贡献者的检测脚本

```bash
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 兼容性约束 (硬性)" 章节。

---

## 🛠️ 开发与测试

```bash
# 安装开发依赖 (含所有懒加载的第三方包, 让 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](LICENSE) © [yanyue](https://github.com/yanyue)

<div align="center">

Made with ❤️ for the Python backend community.

[⬆ 回到顶部](#top)

</div>
