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 也已验证可用。
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:
import kksanic
kksanic.set_project_root('/path/to/your/project')
快速开始
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:
tortoise init # 生成 migrations/ 包
tortoise makemigrations
tortoise migrate
python main.py # 默认 0.0.0.0:8000
要显式指定配置就传 -c,但 必须写在子命令前面 —— 写在后面会报
tortoise: error: unrecognized arguments: -c:
tortoise -c settings.TORTOISE_ORM makemigrations # 对
tortoise makemigrations -c settings.TORTOISE_ORM # 错
生成的 main.py 长这样,块的顺序是有意义的,下面三个坑说的就是它:
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)
加一组增删改查:
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>
路由都注册完再挂文档页与后台站(两者都要扫路由表才知道有哪些页面):
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,就得自己补上:
@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 | add_restful_apis 全参数、方法级配置对象、事务与并发写 |
| docs/validator.md | Validator 与各类 Rule 的判定口径 |
| docs/serializer.md | ModelSerializer 的 include / exclude 与嵌套 |
| docs/admin.md | @admin 装饰器与后台站生成 |
| docs/doc.md | kksanic doc 导出 Markdown / OpenAPI |
| docs/swagger.md | 运行期把文档页挂成 /swagger |
| docs/shard.md | 分表两种用法、迁移行为、方言差异、m2m 的限制 |
| docs/i18n.md | settings.LANG 与译文表 |
| docs/access_log.md | 请求日志的口径与自定义字段 |
Metadata
Release files for kksanic 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kksanic-0.1.0.tar.gz | 561.2 kB | Without provenance | Details for kksanic-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kksanic-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for kksanic-0.1.0-py3-none-any.whl |
Total release size: 902.1 kB
Release files / kksanic-0.1.0.tar.gz
| Download URL | kksanic-0.1.0.tar.gz |
|---|---|
| Size | 561.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1cd4098381614a240adf576cf9476a893a0e14270e31eca2844e036d647e5ef5
|
|
BLAKE2b-256 checksum How to use checksums |
5c8f2cb557df5b757084b5e6554aebf81081da314116229f34ecf00d6691673a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.2
|
Release files / kksanic-0.1.0-py3-none-any.whl
| Download URL | kksanic-0.1.0-py3-none-any.whl |
|---|---|
| Size | 340.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
59b30909bd3c2f04bab4bb43e2634348c20106af2f07ce848cb19fb4cd35f154
|
|
BLAKE2b-256 checksum How to use checksums |
3621e16bc3d2b09ba66e8b03f6f0360c6ff4d9c9c9277113059228119d4b0979
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.2
|
Security for kksanic 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.