本文详解 Firestore Python SDK 中异步事务的正确用法，包括 @firestore.async_transactional 装饰器的调用规范、事务对象传递方式、避免常见 AttributeError 错误的关键实践，并提供可直接运行的完整示例。
本文详解 firestore python sdk 中异步事务的正确用法，包括 `@firestore.async_transactional` 装饰器的调用规范、事务对象传递方式、避免常见 attributeerror 错误的关键实践，并提供可直接运行的完整示例。
在 Firestore 中实现跨文档的原子性操作（如同时更新用户和项目记录）必须依赖事务（Transaction），但 Python SDK 的事务 API 与 JavaScript 或 Java 版本存在显著差异——尤其是异步事务的使用方式极易出错。你遇到的 AttributeError: 'str' object has no attribute '_read_only' 根源在于：将事务实例作为实例属性提前创建并复用，同时错误地将 @firestore.async_transactional 应用于类方法。这会导致装饰器接收到非事务对象（如字符串或 None），从而触发底层类型校验失败。
✅ 正确做法是：事务对象必须由 @firestore.async_transactional 自动注入，且被装饰函数必须是顶层函数（非绑定方法），接收 transaction 作为首个参数。事务生命周期应严格限定在该函数内，不可跨函数传递或复用已初始化的 self.transaction。
以下是符合最佳实践的重构代码：
import firebase_admin
from firebase_admin import credentials, firestore
import uuid
# 初始化 Firebase（仅需一次，建议在应用启动时执行）
if not firebase_admin._apps:
cred = credentials.ApplicationDefault()
firebase_admin.initialize_app(cred)
db = firestore.client()
users_ref = db.collection('users')
projects_ref = db.collection('projects')
@firestore.async_transactional
async def _create_project(transaction, user_id: str) -> dict:
"""事务内执行：读取用户、更新用户项目列表、创建新项目"""
# 1. 读取用户文档（必须在事务内调用 get()）
user_doc = users_ref.document(user_id).get(transaction=transaction)
if not user_doc.exists:
raise ValueError(f"User {user_id} not found")
# 2. 生成唯一项目 ID
project_id = str(uuid.uuid4())
# 3. 更新用户文档：追加 projectIds（注意：需先读取原值再合并，避免覆盖）
user_data = user_doc.to_dict()
current_projects = user_data.get("projectIds", [])
updated_projects = current_projects + [project_id]
transaction.update(user_doc.reference, {"projectIds": updated_projects})
# 4. 创建新项目文档
project_data = {
"id": project_id,
"userIds": [user_id],
"createdAt": firestore.SERVER_TIMESTAMP
}
projects_ref.document(project_id).set(project_data, transaction=transaction)
return {"projectId": project_id, "userId": user_id}
# 外层业务方法：不带装饰器，负责调用事务函数
class FirestoreApi:
async def create_project(self, user_id: str) -> dict:
# 直接调用被 @async_transactional 装饰的顶层函数
return await _create_project(user_id=user_id)
? 关键注意事项：
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- ❌ 禁止在 __init__ 中初始化 self.transaction —— 事务对象不能预先创建或跨调用复用；
- ✅ 事务函数必须为模块级顶层函数（非 self. 方法），且第一个参数必须是 transaction；
- ✅ 所有读写操作（.get()、.update()、.set()）都必须显式传入 transaction= 参数；
- ✅ 若需更新数组字段（如 projectIds），务必先 .get() 获取当前值，再合并更新，否则可能覆盖其他字段；
- ✅ 异步事务函数返回值会自动成为外层 await 的结果，无需手动 commit()。
调用方式：
api = FirestoreApi()
result = await api.create_project("robert")
print(result) # {'projectId': 'xxx', 'userId': 'robert'}
此模式确保了强一致性：若任一操作失败（如用户不存在、网络中断），整个事务自动回滚，数据库状态保持不变。这是构建可靠协作系统（如权限同步、计数器更新、订单-库存联动）的基石。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
