Metadata-Version: 2.4
Name: jalontsui-fastapi-kit
Version: 0.2.0
Summary: JalonTsui Fastapi Kit：FastAPI 服务公共基础设施包（配置、数据库、缓存、日志、错误体系、安全、中间件等）
Keywords: fastapi,toolkit,infrastructure,backend,jwt,sqlalchemy,redis
Author: JalonTsui
Author-email: JalonTsui <jalontsui@163.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Framework :: FastAPI
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: fastapi>=0.115.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pydantic-settings>=2.7.0
Requires-Dist: sqlalchemy[asyncio]>=2.0.40
Requires-Dist: passlib[bcrypt]>=1.7.4
Requires-Dist: bcrypt>=4.0.0,<4.1.0
Requires-Dist: pyjwt[crypto]>=2.10.0
Requires-Dist: redis>=5.0.0,<6.0
Requires-Dist: tzlocal>=5.0
Requires-Dist: pillow>=10.0.0 ; extra == 'captcha'
Requires-Dist: asyncmy>=0.2.10 ; extra == 'mysql'
Requires-Dist: pymysql>=1.1.1 ; extra == 'mysql'
Requires-Dist: aioboto3>=15.5.0 ; extra == 'storage'
Requires-Python: >=3.11
Project-URL: Homepage, https://gitee.com/jalontsui/jalontsui-py-magic/tree/main/packages/jalontsui-fastapi-kit
Project-URL: Repository, https://gitee.com/jalontsui/jalontsui-py-magic
Provides-Extra: captcha
Provides-Extra: mysql
Provides-Extra: storage
Description-Content-Type: text/markdown

# JalonTsui Fastapi Kit

面向 FastAPI 服务的公共基础设施包：配置、数据库、缓存、日志、错误体系、安全、中间件等通用能力一次装齐，业务包只做业务语义薄封装。

| 项 | 值 |
|----|----|
| 发行名（安装名） | `jalontsui-fastapi-kit` |
| import 名 | `jalontsui_fastapi_kit` |
| Python 要求 | `>=3.11` |
| 许可证 | MIT |

## 安装

```bash
uv add jalontsui-fastapi-kit
```

按实际需要选装 extras（可组合，如 `[mysql,storage]`）：

```bash
uv add "jalontsui-fastapi-kit[mysql]"     # MySQL 驱动：asyncmy（异步）+ pymysql（同步 / Alembic 迁移）
uv add "jalontsui-fastapi-kit[captcha]"   # 图形验证码：Pillow
uv add "jalontsui-fastapi-kit[storage]"   # S3 协议对象存储：aioboto3
```

核心依赖只包含 FastAPI / Pydantic / SQLAlchemy / Redis 等基础库；数据库驱动与 Pillow 均为可选，纯工具脚本不会被强迫安装 MySQL 驱动。驱动缺失时，创建数据库引擎会抛出带安装提示的中文报错。

发布前也可从 Git 直装（monorepo subdirectory 方式）：

```bash
uv add "git+https://gitee.com/jalontsui/jalontsui-py-magic.git@jalontsui-fastapi-kit-v0.1.0#subdirectory=packages/jalontsui-fastapi-kit"
```

## 快速上手

```python
from jalontsui_fastapi_kit.config import BaseAppSettings
from jalontsui_fastapi_kit.response import ApiResponse


class Settings(BaseAppSettings):
    """业务配置继承基类，即获得全部通用配置字段."""

    app_name: str = "my-service"
    db_name: str = "my_db"


settings = Settings()

# 统一响应结构
content = ApiResponse.success(data={"id": 1})
```

创建数据库引擎（`mysql+asyncmy` 等驱动需先安装 `[mysql]` extra）：

```python
from jalontsui_fastapi_kit.db import create_async_engine_from_url

engine = create_async_engine_from_url(settings.build_db_async_url())
```

## 能力清单

| 能力 | 导入路径 | 使用文档 |
|------|----------|----------|
| 统一响应结构 | `jalontsui_fastapi_kit.response.ApiResponse` | — |
| 业务异常体系与错误码 | `jalontsui_fastapi_kit.errors` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/errors/README.md) |
| 全局异常处理器 | `jalontsui_fastapi_kit.errors.handlers` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/errors/README.md) |
| 应用配置基类与配置分块 | `jalontsui_fastapi_kit.config.BaseAppSettings` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/config/README.md) |
| 数据库基类与异步引擎工厂 | `jalontsui_fastapi_kit.db` / `create_async_engine_from_url` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/db/README.md) |
| 可嵌套事务上下文 | `jalontsui_fastapi_kit.db.transaction` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/db/README.md) |
| 通用 Repository | `jalontsui_fastapi_kit.repositories.base.BaseRepository` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/repositories/README.md) |
| Service 基类 | `jalontsui_fastapi_kit.services.base.BaseService` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/services/README.md) |
| Redis 客户端 | `jalontsui_fastapi_kit.cache` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/cache/README.md) |
| 健康检查框架 | `jalontsui_fastapi_kit.health` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/health/README.md) |
| 请求追踪 / CORS / 语言中间件 | `jalontsui_fastapi_kit.middleware` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/middleware/README.md) |
| 结构化日志 | `jalontsui_fastapi_kit.logging` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/logging/README.md) |
| 密码哈希 / JWT / 图形验证码 | `jalontsui_fastapi_kit.security` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/security/README.md) |
| 分页 Schema | `jalontsui_fastapi_kit.schemas.common` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/schemas/README.md) |
| 参数校验格式化 | `jalontsui_fastapi_kit.validation` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/validation/README.md) |
| 搜索引擎扩展位 | `jalontsui_fastapi_kit.search` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/search/README.md) |
| AI 助手接入（llms.txt / 规则生成） | `jalontsui_fastapi_kit.ai` / `jalontsui-fastapi-kit` CLI | — |
| 服务脚手架生成（standalone） | `jalontsui_fastapi_kit.scaffolding` / `jalontsui-fastapi-kit new-service` | — |

## AI 助手接入

包内置面向 AI 编码助手的两类资产，规则文本随包维护，升级包即同步最新约定：

- **llms.txt**：随 wheel 分发的浓缩速览（关键约定 + 模块地图），位于 `jalontsui_fastapi_kit/ai/llms.txt`；`jalontsui-fastapi-kit generate-ai-llms` 可打印或导出。
- **使用规则生成**：`jalontsui-fastapi-kit generate-ai-skill` 把包维护的规则文本写入消费方项目，让项目内的 AI 助手按统一约定使用本包。
- **风格指南生成**：`jalontsui-fastapi-kit generate-ai-style` 把 jalontsui 风格全量指南（垂直模块骨架、零镜像 DTO、事务三场景、归属规则、main 启动仪式）以 skill 形态写入消费方项目，AI 直接加载，生成业务代码风格可控。
- **服务脚手架生成**：`jalontsui-fastapi-kit new-service --name <服务名> [--db mysql|postgresql|none] [--redis] [--celery] [--auth header|none]` 一键生成 standalone FastAPI 服务骨架（垂直模块结构 + Alembic 随 db 集成，模板内置 wheel），AI 可非交互驱动：

```bash
jalontsui-fastapi-kit generate-ai-skill                          # 默认写入当前目录 AGENTS.md
jalontsui-fastapi-kit generate-ai-skill -d . --tool cursor       # .cursor/rules/jalontsui-fastapi-kit.mdc
jalontsui-fastapi-kit generate-ai-skill --tool kimi              # .kimi-code/skills/jalontsui-fastapi-kit/SKILL.md
jalontsui-fastapi-kit generate-ai-skill --tool claude            # .claude/skills/jalontsui-fastapi-kit/SKILL.md
jalontsui-fastapi-kit generate-ai-llms -o llms.txt               # 导出内置 llms.txt
jalontsui-fastapi-kit generate-ai-style                          # 生成风格指南 SKILL.md（默认 kimi）
jalontsui-fastapi-kit new-service --name my-service              # 生成服务骨架（默认 mysql + header 认证）
```

已生成的文件默认拒绝覆盖（保护手动修改），需加 `--force` 才会重写。

## 设计原则

- **零业务依赖**：本包只允许依赖通用第三方库，禁止依赖任何业务包。
- **业务包优先复用**：新增通用能力先在本包实现，业务侧做薄层封装或直接导入。
- **业务专属留在业务包**：业务错误码、业务 Service / Repository、业务配置不进入本包。

## 边界

- 不包含 MinIO / Qdrant / Celery 等业务中间件。
- 数据库驱动（asyncmy / pymysql）与 Pillow 为可选依赖，见上文 extras。

## 版本与协议

- 版本记录：[CHANGELOG.md](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/CHANGELOG.md)。
- 许可证：[MIT](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/LICENSE)。
