Metadata-Version: 2.4
Name: toms-fast
Version: 0.6.0
Summary: 基于 FastAPI 的异步基础工具库，提供 Redis、SQLAlchemy、Celery、日志管理等企业级基础设施的统一封装，简化异步 API 与服务端应用开发（import 包名：tomskit）
Author-email: AllinOneAI Team <ai@aioai.cc>
Requires-Python: >=3.11
Requires-Dist: alembic>=1.13.0
Requires-Dist: celery>=5.5.2
Requires-Dist: fastapi>=0.115.12
Requires-Dist: orjson>=3.9.0
Requires-Dist: pydantic-settings>=2.9.1
Requires-Dist: redis>=6.0.0
Requires-Dist: sqlalchemy>=2.0.40
Description-Content-Type: text/markdown

# toms-fast

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

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

---

## 安装

```bash
# 使用 pip
pip install toms-fast

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

---

## 快速开始

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

生成的项目结构为：

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

#### 1. 安装 uv（如未安装）

```bash
# 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. 创建项目目录

```bash
mkdir my_project && cd my_project
```

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

```bash
# 创建临时虚拟环境用于运行 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. 使用脚手架生成项目

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

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

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

#### 5. 清理临时环境

```bash
# 退出虚拟环境
deactivate

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

#### 6. 初始化后端项目

```bash
# 进入后端目录
cd backend

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

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

#### 7. 数据库迁移（首次）

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

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

#### 8. 启动服务

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

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

### 数据库迁移（日常开发）

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

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

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

**其他常用迁移命令：**

```bash
# 查看当前迁移状态
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>
```

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

```bash
# === 完整流程 ===

# 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/`），可以进入该目录后执行：

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

```bash
# 创建新项目
tomskit init <project_name> [--type full|fastapi|celery]

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

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

# 创建扩展
tomskit add extension <name>

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

# 初始化 Claude Code 支持
tomskit claude init
```

---

## 开发应用的推荐顺序

使用 `tomskit add module` 命令可以快速生成完整的模块结构，包括 Model、Service、Schemas、Resources 和 Module。

### 1. 创建模块

```bash
# 创建 products 模块
tomskit add module products
```

该命令会自动生成以下文件：

```
app/
├── models/products.py           # 数据模型
├── services/products/           # 业务逻辑层
│   ├── __init__.py
│   └── service.py
└── controllers/products/        # API 控制器
    ├── __init__.py
    ├── module.py                # 模块初始化
    ├── resources.py             # API 资源
    └── schemas.py               # 数据验证
```

同时会自动更新 `extensions/ext_modules.py`，注册新模块。

### 2. 修改 Model（数据模型）

根据业务需求修改 `app/models/products.py`，添加需要的字段：

```python
# app/models/products.py
class Products(SQLAlchemy.Model):
    __tablename__ = "products"
    
    id: Mapped[str] = mapped_column(StringUUID, primary_key=True)
    name: Mapped[str] = mapped_column(String(255), nullable=False)
    price: Mapped[int] = mapped_column(Integer, nullable=False)  # 添加字段
    description: Mapped[str | None] = mapped_column(String(500), nullable=True)  # 添加字段
    # ...
```

### 3. 执行数据库迁移

```bash
uv run alembic -c migrations/alembic.ini revision --autogenerate -m 'Add products table'
uv run alembic -c migrations/alembic.ini upgrade head
```

### 4. 修改 Schemas（数据验证）

根据 Model 字段更新 `app/controllers/products/schemas.py`：

```python
class ProductsBase(BaseModel):
    name: str
    price: int
    description: Optional[str] = None
```

### 5. 实现业务逻辑

在 `app/services/products/service.py` 中添加业务逻辑（基础 CRUD 已自动生成）。

### 6. 添加 Tasks（异步任务，可选）

如果需要后台异步处理：

```bash
tomskit add task sync_products
```

### 目录结构参考

```
backend/
├── app/
│   ├── models/              # 数据模型
│   │   └── products.py
│   ├── services/            # 业务逻辑层
│   │   └── products/
│   │       ├── __init__.py
│   │       └── service.py
│   ├── controllers/         # API 控制器
│   │   └── products/
│   │       ├── __init__.py
│   │       ├── module.py
│   │       ├── resources.py
│   │       └── schemas.py
│   └── tasks/               # 异步任务
│       └── sync_products.py
├── extensions/
│   └── ext_modules.py       # 模块注册（自动更新）
├── migrations/              # 数据库迁移
└── main.py                  # 应用入口
```

### 开发流程总结

| 步骤 | 命令/操作 | 说明 |
|------|----------|------|
| 1 | `tomskit add module <name>` | 生成完整模块结构 |
| 2 | 修改 `app/models/<name>.py` | 根据业务需求调整字段 |
| 3 | 执行数据库迁移 | 同步表结构到数据库 |
| 4 | 修改 `schemas.py` | 更新请求/响应数据格式 |
| 5 | 修改 `service.py` | 添加业务逻辑（可选） |
| 6 | `tomskit add task <name>` | 添加异步任务（可选） |

---

## 内置模块

| 模块 | 说明 |
|------|------|
| `tomskit.server` | FastAPI 扩展：资源管理、异常处理、中间件 |
| `tomskit.sqlalchemy` | SQLAlchemy 异步数据库集成，连接池管理 |
| `tomskit.redis` | Redis 异步客户端（单机/Sentinel/Cluster） |
| `tomskit.celery` | Celery 异步任务封装 |
| `tomskit.logger` | 结构化日志，支持追踪 ID |
| `tomskit.task` | 异步任务管理器 |
| `tomskit.tools` | Worker 管理工具（Gunicorn/Uvicorn） |
| `tomskit.utils` | 数据序列化工具 |

详细文档请参考各模块的 README：

- [Server 模块](src/tomskit/server/)
- [SQLAlchemy 模块](src/tomskit/sqlalchemy/README.md)
- [Redis 模块](src/tomskit/redis/README.md)
- [Celery 模块](src/tomskit/celery/README.md)
- [Logger 模块](src/tomskit/logger/README.md)
- [Task 模块](src/tomskit/task/README.md)
- [Tools 模块](src/tomskit/tools/README.md)
- [Utils 模块](src/tomskit/utils/README.md)

---

## 项目结构

```
src/tomskit/
├── server/        # FastAPI 扩展
├── sqlalchemy/    # 数据库集成
├── redis/         # Redis 客户端
├── celery/        # Celery 封装
├── logger/        # 日志管理
├── task/          # 异步任务管理
├── tools/         # Worker 管理
├── utils/         # 工具函数
└── cli/           # 脚手架工具
```

---

## 开发

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

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

# 运行测试
pytest

# 代码检查
ruff check .
```

---

## 许可证

MIT License

---

## 相关链接

- [FastAPI](https://fastapi.tiangolo.com/)
- [SQLAlchemy](https://docs.sqlalchemy.org/)
- [Celery](https://docs.celeryq.dev/)
- [Redis](https://redis.io/docs/)
