Skip to main content

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)

Source distribution for kksanic 0.1.0
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)

Table of built distributions (wheels) for kksanic 0.1.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page