Optimize transaction related documents

Author: wu-clan

docs/advanced/transaction.md

@@ -10,7 +10,7 @@ SQLAlchemy CRUD Plus 基于 SQLAlchemy 2.0 的现代事务管理模式，提供
 # 推荐的事务模式
 async with async_db_session.begin() as session:
     # 在这个块中的所有操作都在同一个事务中
-    user_data = {"name": "张三", "email": "zhangsan@example.com"}
+    user_data = UserCreate(name="张三", email="zhangsan@example.com")
     user = await user_crud.create_model(session, user_data)
 
     # 如果没有异常，事务会自动提交
@@ -25,7 +25,7 @@ async with async_db_session() as session:
         # 开始事务
         await session.begin()
 
-        user_data = {"name": "李四", "email": "lisi@example.com"}
+        user_data = UserCreate(name="李四", email="lisi@example.com")
         user = await user_crud.create_model(session, user_data)
 
         # 手动提交
@@ -37,17 +37,27 @@ async with async_db_session() as session:
         raise e
 ```
 
-### 使用 commit 参数
+### 使用 flush 和 commit 参数
+
+**flush**：将更改刷新到数据库但不提交事务，用于获取自动生成的主键或在同一事务中使用新创建的记录。
+
+**commit**：立即提交事务，适用于独立的单个操作。
 
 ```python
+# 使用 flush 获取自动生成的主键
+user_data = UserCreate(name="张三", email="zhangsan@example.com")
+user = await user_crud.create_model(session, user_data, flush=True)
+# 此时 user.id 已可用，但事务未提交
+
 # 自动提交单个操作
+user_data = UserCreate(name="李四", email="lisi@example.com")
 user = await user_crud.create_model(session, user_data, commit=True)
 
 # 自动提交更新操作
-await user_crud.update_model(session, user_id, update_data, commit=True)
+await user_crud.update_model(session, pk=user_id, obj=update_data, commit=True)
 
 # 自动提交删除操作
-await user_crud.delete_model(session, user_id, commit=True)
+await user_crud.delete_model(session, pk=user_id, commit=True)
 ```
 
 ## 复杂事务场景
@@ -56,20 +66,20 @@ await user_crud.delete_model(session, user_id, commit=True)
 
 ```python
 async with async_db_session.begin() as session:
-    # 创建用户
-    user_data = {"name": "王五", "email": "wangwu@example.com"}
+    # 创建用户（使用 flush 获取主键）
+    user_data = UserCreate(name="王五", email="wangwu@example.com")
     user = await user_crud.create_model(session, user_data, flush=True)
 
-    # 创建个人资料
-    profile_data = {"user_id": user.id, "bio": "个人简介"}
+    # 创建个人资料（使用获取到的用户主键）
+    profile_data = ProfileCreate(user_id=user.id, bio="个人简介")
     profile = await profile_crud.create_model(session, profile_data)
 
     # 创建文章
-    post_data = {
-        "title": "我的第一篇文章",
-        "content": "文章内容...",
-        "author_id": user.id
-    }
+    post_data = PostCreate(
+        title="我的第一篇文章",
+        content="文章内容...",
+        author_id=user.id
+    )
     post = await post_crud.create_model(session, post_data)
 
     # 所有操作要么全部成功，要么全部回滚
@@ -86,16 +96,17 @@ async with async_db_session.begin() as session:
 
     if existing_user:
         # 更新现有用户
-        user_update = {"last_login": datetime.now()}
-        user = await user_crud.update_model(
-            session, existing_user.id, user_update
+        user_update = UserUpdate(last_login=datetime.now())
+        await user_crud.update_model(
+            session, pk=existing_user.id, obj=user_update
         )
+        user = existing_user
     else:
         # 创建新用户
-        user_data = {
-            "name": "新用户",
-            "email": "test@example.com"
-        }
+        user_data = UserCreate(
+            name="新用户",
+            email="test@example.com"
+        )
         user = await user_crud.create_model(session, user_data)
 
     return user
@@ -107,15 +118,15 @@ async with async_db_session.begin() as session:
 async with async_db_session.begin() as session:
     # 批量创建用户
     users_data = [
-        {"name": f"用户{i}", "email": f"user{i}@example.com"}
+        UserCreate(name=f"用户{i}", email=f"user{i}@example.com")
         for i in range(100)
     ]
     users = await user_crud.create_models(session, users_data)
 
     # 批量更新
     for user in users:
         await user_crud.update_model(
-            session, user.id, {"is_active": True}
+            session, pk=user.id, obj={"is_active": True}
         )
 ```
 
@@ -126,15 +137,15 @@ async with async_db_session.begin() as session:
 ```python
 async with async_db_session.begin() as session:
     # 主事务
-    user_data = {"name": "主用户", "email": "main@example.com"}
+    user_data = UserCreate(name="主用户", email="main@example.com")
     user = await user_crud.create_model(session, user_data, flush=True)
 
     # 创建保存点
     savepoint = await session.begin_nested()
 
     try:
         # 嵌套事务
-        profile_data = {"user_id": user.id, "bio": "可能失败的操作"}
+        profile_data = ProfileCreate(user_id=user.id, bio="可能失败的操作")
         profile = await profile_crud.create_model(session, profile_data)
 
         # 提交保存点
@@ -186,32 +197,93 @@ async def concurrent_transactions():
     # 并发处理
     tasks = []
     for i in range(10):
-        user_data = {"name": f"用户{i}", "email": f"user{i}@example.com"}
+        user_data = UserCreate(name=f"用户{i}", email=f"user{i}@example.com")
         task = process_user(user_data)
         tasks.append(task)
 
     results = await asyncio.gather(*tasks, return_exceptions=True)
     return results
 ```
 
+## flush 和 commit 参数详解
+
+### flush 参数
+
+`flush=True` 将更改发送到数据库但不提交事务：
+
+```python
+async with async_db_session.begin() as session:
+    # 创建用户并立即获取主键
+    user_data = UserCreate(name="张三", email="zhangsan@example.com")
+    user = await user_crud.create_model(session, user_data, flush=True)
+
+    # 此时 user.id 已可用，可用于关联操作
+    profile_data = ProfileCreate(user_id=user.id, bio="用户简介")
+    profile = await profile_crud.create_model(session, profile_data)
+
+    # 事务在 with 块结束时自动提交
+```
+
+**使用场景：**
+
+- 需要获取自动生成的主键
+- 在同一事务中创建关联记录
+- 确保数据一致性检查
+
+### commit 参数
+
+`commit=True` 立即提交事务：
+
+```python
+# 独立操作，立即提交
+user_data = UserCreate(name="李四", email="lisi@example.com")
+user = await user_crud.create_model(session, user_data, commit=True)
+
+# 适用于单个操作
+await user_crud.update_model(session, pk=1, obj={"name": "新名称"}, commit=True)
+await user_crud.delete_model(session, pk=1, commit=True)
+```
+
+**使用场景：**
+
+- 独立的单个操作
+- 不需要与其他操作组合
+- 简化代码结构
+
+### 参数组合使用
+
+```python
+# ❌ 错误：不要同时使用 flush 和 commit
+user = await user_crud.create_model(session, user_data, flush=True, commit=True)
+
+# ✅ 正确：根据需要选择其一
+user = await user_crud.create_model(session, user_data, flush=True)  # 获取主键
+user = await user_crud.create_model(session, user_data, commit=True)  # 立即提交
+```
+
 ## 最佳实践
 
 1. **优先使用自动事务管理**
     - 使用 `async with session.begin()` 模式
     - 让异常自然传播以触发回滚
     - 避免手动管理事务状态
 
-2. **合理控制事务范围**
+2. **合理使用 flush 和 commit**
+    - 需要主键时使用 `flush=True`
+    - 独立操作时使用 `commit=True`
+    - 避免在事务块中使用 `commit=True`
+
+3. **合理控制事务范围**
     - 保持事务尽可能短小
     - 避免在事务中执行耗时操作
     - 考虑使用分批处理
 
-3. **错误处理**
+4. **错误处理**
     - 在事务外部处理业务逻辑错误
     - 使用保存点处理部分失败场景
     - 记录事务失败的详细信息
 
-4. **性能优化**
+5. **性能优化**
     - 合理设置事务隔离级别
     - 使用并发处理独立事务
     - 避免不必要的事务嵌套