用途:为 Tortoise ORM(异步 Python ORM)代码库提供一套有主张的生产级开发规范,适用于新建项目(FastAPI、Starlette、Sanic、Quart、AIOHTTP、Nexios)、新增模型、把单文件 models.py 重构为子包、将迁移接入 CI,以及审查涉及 Tortoise 模型的 PR。规则优先级为:用户项目自身规则(如仓库 CLAUDE.md、对话内明确指示)最高,其次是官方文档与 Context7 来源的模式,再次为其他互联网共识。
主要能力与约定:模型放在子应用的 models/ 子包而非 models.py;一个文件一个模型;每个具体模型配有抽象 Base* 接口,用于测试 mock 与模式迁移过渡;class Meta 永远是类中第一个成员,成员顺序为 Meta→字段→类/私有方法→公有方法。跨切面 BaseModel 提供 UUID 主键、created_at、updated_at。配置集中在一处,TORTOISE_ORM 含 connections、apps(含 migrations 包键)、use_tz、timezone。查询强调 select_related/prefetch_related 避免 N+1、bulk_create/bulk_update、only()/values()、Q/F 过滤与 exists()/count()。事务使用 @atomic() 或 async with in_transaction(),行锁用 select_for_update(),避免在 asyncio.gather 中嵌套事务。信号仅用于审计日志、缓存失效等。
迁移:使用 Tortoise ≥1.1 内置的 tortoise CLI,不使用 Aerich。命令如 uv run tortoise -c config.tortoise.TORTOISE_ORM init / makemigrations / migrate / downgrade models / history / sqlmigrate models 0001_initial。准备前先核查已安装版本、PyPI 最新版与在线文档,文档与规范冲突时以在线文档为准。生产代码禁止调用 generate_schemas()。
部署集成:检测到 docker-compose、Helm、Kustomize、Procfile 或 CI 清单时,主动提议一次性迁移服务、Job、init container 或 release 进程,但生成文件前必须先征得用户同意。
限制:资料未提供具体定价、授权许可、支持平台范围与效果数据;部分引用文件(如 references/migra…)内容被截断,未展开部分暂无完整信息。