Metadata-Version: 2.4
Name: kksanic
Version: 0.1.0
Summary: 基于 Sanic + Tortoise 的后端小工具箱：统一响应、入参校验、出参序列化、RESTful 一键接口、后台管理站、接口文档、分表
Author: Python卡皮巴拉
License-Expression: MIT
Keywords: sanic,tortoise-orm,restful,validator,serializer,scaffold,async
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sanic<26,>=24.12
Requires-Dist: tortoise-orm<2,>=1.1
Requires-Dist: python-dateutil>=2.8
Requires-Dist: python-jose>=3.3
Requires-Dist: tzdata; sys_platform == "win32"
Provides-Extra: redis
Requires-Dist: redis>=4.0; extra == "redis"
Provides-Extra: mysql
Requires-Dist: aiomysql>=0.2; extra == "mysql"
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29; extra == "postgres"
Provides-Extra: all
Requires-Dist: redis>=4.0; extra == "all"
Requires-Dist: aiomysql>=0.2; extra == "all"
Requires-Dist: asyncpg>=0.29; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# kksanic

基于 Sanic + Tortoise 的小工具箱。写业务不用再拼那套骨架：请求对象、统一响应、
入参校验、出参序列化、RESTful 增删改查、后台管理站、接口文档、分表分库，
都在同一个包里，且互相接得上。

| 能力 | 入口 | 一行说明 |
|---|---|---|
| 统一响应 | `ApiException` / `get_response` | 状态码走 HTTP，body 只有 `msg` / `data` |
| 入参校验 | `Validator` + `Rule` 系列 | 按字段类型选规则，写错维度定义期就报 `TypeError` |
| 出参序列化 | `ModelSerializer` | 模型 → dict，`Meta.include` / `exclude` 收窄字段 |
| 一键增删改查 | `add_restful_apis` | 6 个接口（含 PATCH）一次注册，分页、软删、事务都带着 |
| 后台管理站 | `@admin` + `python -m kksanic admin` | 生成单文件管理页，挂成 `/admin` |
| 接口文档 | `python -m kksanic doc` / `add_swagger_ui` | Markdown + OpenAPI + 自带登录框的 Swagger UI |
| 分表 | `ShardRule` + `expand()` | 一表一类，两种用法（声明式 / 运行期给表名） |
| 请求日志 | `add_request_logging` | 一行一请求，慢请求与 5xx 升 WARNING |

## 环境要求

| 依赖 | 版本 | 说明 |
|---|---|---|
| Python | **>= 3.10** | `sanic` 25.12 与 `tortoise-orm` 1.1.8 都要求 >= 3.10 |
| `sanic` | `>=24.12,<26` | 24.12 与 25.12 实测全绿；26 起内部 API 有变动，未验证 |
| `tortoise-orm` | `>=1.1,<2`（实测 1.1.8） | 连接注册表在 1.1 改成了 contextvar |
| `python-dateutil` | 必需 | `DateRule` / `DateTimeRule` 的日期解析 |
| `python-jose` | 必需 | token 编解码 |
| `tzdata` | **Windows 自动装** | 缺了 `Asia/Shanghai` 会抛 `ZoneInfoNotFoundError` |
| `redis` | 可选（`kksanic[redis]`） | 缺了就 `ImportError` 兜住，退回进程内缓存 |
| `aiomysql` / `asyncpg` | 可选（`kksanic[mysql]` / `kksanic[postgres]`） | 用 MySQL / PostgreSQL 时才要 |

Python 3.10 及以上都能装；3.12 / 3.13 也已验证可用。

```bash
pip install kksanic                 # 装到环境里
pip install -e .                    # 在本仓库里改代码
pip install 'kksanic[mysql]'        # 顺带装 MySQL 驱动
```

没装进环境（只在 `PYTHONPATH` 里）就没有 `kksanic` 这个命令，此时 CLI 要写成
`python -m kksanic ...`；装过之后两种写法等价。

库被装进 `site-packages` 后无法从自身位置推断 **你的项目根**。探测链覆盖不到的
部署方式（典型是 `sanic server:app`），在启动代码里显式指定一次，或用环境变量
`KKSANIC_PROJECT_ROOT`：

```python
import kksanic
kksanic.set_project_root('/path/to/your/project')
```

## 快速开始

```bash
python -m kksanic init                 # 生成骨架，默认 sqlite
python -m kksanic init --db postgres   # 或 mysql / postgres
```

生成 `main.py` / `settings.py` / `models.py` / `serializers.py` / `validators.py`
与 `migrations/ static/ media/` 目录。同时会写一个 `pyproject.toml`，
里面只有一段 `[tool.tortoise]`（指向 `settings.TORTOISE_ORM`），
所以下面的 CLI 不用再传 `-c`：

```bash
tortoise init            # 生成 migrations/ 包
tortoise makemigrations
tortoise migrate
python main.py           # 默认 0.0.0.0:8000
```

要显式指定配置就传 `-c`，但 **必须写在子命令前面** —— 写在后面会报
`tortoise: error: unrecognized arguments: -c`：

```bash
tortoise -c settings.TORTOISE_ORM makemigrations   # 对
tortoise makemigrations -c settings.TORTOISE_ORM   # 错
```

生成的 `main.py` 长这样，**块的顺序是有意义的**，下面三个坑说的就是它：

```python
from sanic import Sanic
from tortoise.contrib.sanic import register_tortoise

import settings
from kksanic import Request, add_request_logging, register_exception_handler

app = Sanic('App', request_class=Request)      # request_class 必须换，否则 Request 用不上

register_exception_handler(app)                # ① 统一异常响应
add_request_logging(app)                       # ② 请求日志：排在鉴权中间件之前
register_tortoise(app, config=settings.TORTOISE_ORM)

if __name__ == '__main__':
    app.run(host=settings.HOST, port=settings.PORT, workers=settings.WORKERS)
```

加一组增删改查：

```python
from kksanic import add_restful_apis
from models import Article

add_restful_apis(app, Article, base_path='/api/article')
# GET/POST /api/article，GET/PUT/PATCH/DELETE /api/article/<pk>
```

路由都注册完再挂文档页与后台站（两者都要扫路由表才知道有哪些页面）：

```python
from kksanic import add_admin_site, add_swagger_ui

add_swagger_ui(app)           # GET /swagger
add_admin_site(app, 'admin')  # GET /admin，软删开着时自带回收站接口
```

到这里跑起来就是能用的：`POST` 返回 200 + 新行，`GET` 返回分页结构
（`current_page` / `total` / `list`），`title` 超长返回 400 +
`title长度不能超过50`，`DELETE` 走软删所以之后 `GET /api/article/1` 是 404
`Article不存在`。

## 三个必踩的坑

### 1. 手写 `Tortoise.init()` 必须传 `_enable_global_fallback=True`

Tortoise 1.1 把连接注册表换成了 contextvar。Sanic 的 `before_server_start`
和请求处理不在同一个 task，于是请求里取连接直接抛：

```
RuntimeError: No TortoiseContext is currently active.
```

两条路的默认值 **不一样**，这是最容易踩的地方：

| 写法 | `_enable_global_fallback` | 结果 |
|---|---|---|
| `register_tortoise(app, config=...)`（`tortoise.contrib.sanic`） | 默认 `True`，框架已替你传 | 正常 |
| 自己 `await Tortoise.init(config=...)` | 默认 **`False`** | 请求里取连接就抛 RuntimeError |

所以只要不走 `register_tortoise`，就得自己补上：

```python
@app.before_server_start
async def init_orm(app, _):
    # Sanic 的 startup 与请求处理不在同一个 task，1.1 起必须开全局兜底
    await Tortoise.init(config=settings.TORTOISE_ORM, _enable_global_fallback=True)
```

### 2. `register_exception_handler(app)` 要自己调一次

Sanic 对没有注册处理器的异常一律 500 + 纯文本 `Internal Server Error`。
库里每一处 `raise ApiException(status_code=400, msg='手机号已注册')`，
不注册处理器就全变成「服务器错误」，前端既拿不到状态码也拿不到提示。

`add_restful_apis` **刻意不替你注册**：它一注册，你在后面写的
`@app.exception(ApiException)` 就会在启动期撞成 `ServerError`。
调用本身是幂等的，重复调不会覆盖你写得更精细的那份。

### 3. `add_request_logging(app)` 必须排在鉴权中间件之前

中间件按注册顺序执行。排在后面时，被 401 挡下的请求拿不到开始时间，
日志里耗时那一栏只剩一个 `-`（行还是会记）。

## 文档

| 文档 | 讲什么 |
|---|---|
| [docs/restful.md](docs/restful.md) | `add_restful_apis` 全参数、方法级配置对象、事务与并发写 |
| [docs/validator.md](docs/validator.md) | `Validator` 与各类 `Rule` 的判定口径 |
| [docs/serializer.md](docs/serializer.md) | `ModelSerializer` 的 include / exclude 与嵌套 |
| [docs/admin.md](docs/admin.md) | `@admin` 装饰器与后台站生成 |
| [docs/doc.md](docs/doc.md) | `kksanic doc` 导出 Markdown / OpenAPI |
| [docs/swagger.md](docs/swagger.md) | 运行期把文档页挂成 `/swagger` |
| [docs/shard.md](docs/shard.md) | 分表两种用法、迁移行为、方言差异、m2m 的限制 |
| [docs/i18n.md](docs/i18n.md) | `settings.LANG` 与译文表 |
| [docs/access_log.md](docs/access_log.md) | 请求日志的口径与自定义字段 |
