toms-fast 0.8.0

FastAPI 全栈异步基础设施框架：Fastapi, Sqlalchemy, Redis, Celery，让你专注业务逻辑

toms-fast

toms-fast 是一个基于 FastAPI 的异步基础工具库（Async Infrastructure Toolkit），用于简化和规范企业级异步 API 与服务端应用的开发。

PyPI 名称：toms-fast Python import 包名：tomskit Python 版本要求：>=3.11

---

安装

# 使用 pip
pip install toms-fast

# 使用 uv（推荐）
uv pip install toms-fast

---

快速开始

从零开始创建新项目（推荐）

生成的项目结构为：

my_project/
├── backend/    # 后端代码（由 tomskit 生成）
├── web/        # 前端代码目录（由 tomskit 生成）
└── README.md   # 项目说明

1. 安装 uv（如未安装）

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或使用 Homebrew (macOS)
brew install uv

2. 创建项目目录

mkdir my_project && cd my_project

3. 创建临时虚拟环境并安装 toms-fast

# 创建临时虚拟环境用于运行 CLI
uv venv cli-env

# 激活临时环境
source cli-env/bin/activate  # Linux/macOS
# cli-env\Scripts\activate   # Windows

# 安装 toms-fast
uv pip install toms-fast

4. 使用脚手架生成项目

# 创建完整项目（FastAPI + Celery）
# 因为当前目录名与项目名一致，会直接在当前目录创建 backend/
tomskit init my_project

# 或仅创建 FastAPI 项目
# tomskit init my_project --type fastapi

# 或仅创建 Celery 项目
# tomskit init my_project --type celery

5. 清理临时环境

# 退出虚拟环境
deactivate

# 删除临时环境
rm -rf cli-env  # Linux/macOS
# rmdir /s /q cli-env  # Windows

6. 初始化后端项目

# 进入后端目录
cd backend

# 安装项目依赖（会自动创建 .venv）
uv sync

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置数据库和 Redis 连接信息

7. 数据库迁移（首次）

# 生成初始迁移文件
uv run alembic -c migrations/alembic.ini revision --autogenerate -m 'Initial migration'

# 执行迁移，将表结构同步到数据库
uv run alembic -c migrations/alembic.ini upgrade head

8. 启动服务

# 运行 FastAPI 开发服务器
uv run uvicorn main:app --reload

# 运行 Celery Worker（新终端）
uv run celery -A celery_app worker --loglevel=info

数据库迁移（日常开发）

当你修改了 Model 后，需要生成并执行迁移：

# 1. 生成迁移文件（根据 Model 变更自动生成）
uv run alembic -c migrations/alembic.ini revision --autogenerate -m '描述本次变更'

# 2. 执行迁移，将变更同步到数据库
uv run alembic -c migrations/alembic.ini upgrade head

其他常用迁移命令：

# 查看当前迁移状态
uv run alembic -c migrations/alembic.ini current

# 查看迁移历史
uv run alembic -c migrations/alembic.ini history

# 回滚到上一个版本
uv run alembic -c migrations/alembic.ini downgrade -1

# 回滚到指定版本
uv run alembic -c migrations/alembic.ini downgrade <revision_id>

完整命令速查（一键复制）

# === 完整流程 ===

# 1. 创建项目目录
mkdir my_project && cd my_project

# 2. 创建临时环境并生成项目
uv venv cli-env && source cli-env/bin/activate
uv pip install toms-fast
tomskit init my_project
deactivate && rm -rf cli-env

# 3. 初始化后端
cd backend
uv sync
cp .env.example .env
# 编辑 .env 配置数据库和 Redis

# 4. 数据库迁移
uv run alembic -c migrations/alembic.ini revision --autogenerate -m 'Initial migration'
uv run alembic -c migrations/alembic.ini upgrade head

# 5. 启动服务
uv run uvicorn main:app --reload

已有项目添加后端

如果你已有项目目录（如 existing_project/），可以进入该目录后执行：

cd existing_project

# 创建临时环境
uv venv cli-env && source cli-env/bin/activate
uv pip install toms-fast

# 生成项目（当前目录名与项目名一致，会直接创建 backend/）
tomskit init existing_project

# 清理并初始化
deactivate && rm -rf cli-env
cd backend && uv sync

---

CLI 命令

# 创建新项目
tomskit init <project_name> [-d "描述"] [-t full|fastapi|celery] [-o 目标目录]

# 创建模块（Model + Controller + Schema）
tomskit add module <name>

# 创建 Celery 任务
tomskit add task <name>

# 创建扩展
tomskit add extension <name>

# 初始化数据库迁移（已有项目）
tomskit migrations

# 初始化 Claude Code 支持
tomskit claude init

启用 Tab 自动补全（可选）

tomskit 支持命令行 Tab 自动补全，需要配置 shell：

# 1. 全局安装 argcomplete（如果尚未安装）
pip install argcomplete

# 2. 激活全局自动补全（推荐，一次配置所有支持的命令）
activate-global-python-argcomplete

或者手动配置单个命令：

Bash (添加到 ~/.bashrc):

eval "$(register-python-argcomplete tomskit)"

Zsh (添加到 ~/.zshrc):

autoload -U bashcompinit
bashcompinit
eval "$(register-python-argcomplete tomskit)"

配置后重启终端即可使用 Tab 补全。

---

内置模块

完整的应用开发指南（Model、Schema、Resource、序列化、分页、异常处理、数据库、Redis、Celery、日志等）请参考 APP_CLAUDE.md。

模块	说明	核心导出
tomskit.server	FastAPI 扩展	FastApp, FastModule, Resource, api_doc, register_resource, APIException
tomskit.sqlalchemy	异步数据库集成	SQLAlchemy, db, StringUUID, ModelSerializer, PaginationResponse, Pagination
tomskit.redis	异步 Redis 客户端	redis_client, RedisConfig
tomskit.celery	Celery 异步任务	AsyncCelery, async_shared_task, AsyncRuntime, CeleryConfig
tomskit.logger	结构化日志	configure_logging, LoggerConfig
tomskit.tools	工具模块	AsyncTaskManager
tomskit.utils	数据序列化（旧版）	marshal, marshal_with

---

项目结构

src/tomskit/
├── server/        # FastAPI 扩展（Resource、Module、异常处理、中间件）
├── sqlalchemy/    # 数据库集成（会话管理、分页、序列化）
├── redis/         # Redis 客户端
├── celery/        # Celery 封装
├── logger/        # 日志管理
├── task/          # 异步任务管理
├── tools/         # Worker 管理
├── utils/         # 工具函数
└── cli/           # 脚手架工具

---

开发

# 克隆仓库
git clone https://github.com/tomszhou/toms-fast.git
cd toms-fast

# 安装开发依赖
uv sync --group dev

# 运行测试
pytest

# 代码检查
ruff check .

---

许可证

MIT License

---

相关链接

• FastAPI
• SQLAlchemy
• Celery
• Redis