From 85439d3f9c9569550ab2139a20756b9ae27fb165 Mon Sep 17 00:00:00 2001 From: jxxghp Date: Sun, 23 Aug 2026 23:35:17 +0800 Subject: [PATCH] docs(db): clarify plugin-owned decorators --- app/db/decorators.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/app/db/decorators.py b/app/db/decorators.py index 33f3bd0c7..a89799efc 100644 --- a/app/db/decorators.py +++ b/app/db/decorators.py @@ -1,10 +1,13 @@ """ -数据库事务装饰器。 +插件自有数据库函数使用的公共事务装饰器。 同步/异步各一对：查询装饰器负责会话的获取与释放，更新装饰器额外负责提交与回滚。 未显式传入会话时自动创建，并在结束时归还——异步路径经 async_session_scope 收口， 连接池与配额都在那里生效。 +宿主 Model、Base 与 Oper 不使用这些装饰器；它们通过显式 Session、事务执行器或 UoW +管理事务。这里保留的四个入口只供插件操作插件自有表，不能用于访问宿主 Model。 + 收尾故障（rollback / close / __aexit__ 自身抛异常）一律只记日志、不上抛。理由与代价 都要写明，别当成漏写的 raise： @@ -26,10 +29,9 @@ from app.runtime.log import logger _R = TypeVar("_R") -# 正式装饰器会重写实参列表：未传会话时自行创建一个并塞回 db 位置。因此包装后的可调用 +# 公共装饰器会重写实参列表：未传会话时自行创建一个并塞回 db 位置。因此包装后的可调用 # 对象接受的实参与被包装函数的签名并不一致——用 Callable[..., _R] 如实表达「参数由装饰器 -# 接管、返回值原样透传」。否则调用方传 None 或传异步会话都会被判成类型不符，而这恰恰是 -# 装饰器存在的理由（各 Oper 的 self._db 常态就是 None）。 +# 接管、返回值原样透传」。否则插件自有数据库函数传 None 或传异步会话时会被判成类型不符。 def _get_args_db(