temporal.io Python SDK 初体验分享

Temporal.io 的 Python SDK 入门看似简单，实则暗藏三大高频“踩坑点”：网络连接因 localhost 默认解析为 IPv6 地址（::1）而失败，需显式指定 service_host="127.0.0.1:7233" 并确认 Server 容器已运行；Workflow 执行卡住或无响应，往往源于 Worker 未提前启动并注册工作流、调用顺序错误或混淆同步/异步方法；而 workflow_id 重复、event loop 生命周期管理不当及 ID 复用导致的静默失败或报错，则进一步加剧调试难度——这些非显性约束不抛异常、不给提示，却让新手在首次跑通时频频受挫，掌握其底层设计逻辑才是平滑上手的关键。

temporalio 连不上 localhost:7233 怎么办

默认启动的 Temporal Server 监听 127.0.0.1:7233，但 Python SDK 默认尝试连 localhost:7233。在某些系统（尤其是 macOS 或启用了 IPv6 的环境）下，localhost 解析为 ::1，而 Server 并未监听 IPv6 地址，导致连接拒绝。

• 显式指定 host="127.0.0.1" 而非依赖默认值
• 初始化客户端时传入完整地址：service_host="127.0.0.1:7233"
• 检查 telnet 127.0.0.1 7233 是否通；不通就确认 Server 确实已运行（docker ps 看 temporalio/auto-setup 容器）
• 不要改 hosts 文件把 localhost 指向 127.0.0.1 —— 这治标不治本，且可能影响其他工具

workflow.run() 卡住没反应，也不报错

Workflow.run() 是同步阻塞调用，但它依赖 Worker 已注册对应 workflow 类型并正在运行。如果只跑了 client 代码、没起 Worker，它就会一直等——不是 bug，是设计如此。

• 确保你开了两个终端：一个跑 Worker（worker.py），一个跑 Client（client.py）
• Worker 必须提前注册 workflow 和 activity，例如：worker.add_workflow_type(YourWorkflow)
• 不要用 async def run() 混淆概念：Python SDK 的 run() 是同步的，execute_workflow() 才是异步的
• 常见误操作：在同一个脚本里先 run() 再 start() Worker —— 顺序反了，Worker 根本没机会注册

用 asyncio 时 workflow.execute_workflow() 报 “event loop is closed”

SDK 的异步方法（如 execute_workflow()）必须在 event loop 存活期间调用。如果你用 asyncio.run() 启动，然后在回调或子线程里再调用，loop 可能已被关闭。

• 所有 await 调用必须在同一个顶层 async def main() 里完成，不要跨函数泄露 loop
• 避免在 threading.Thread 里调用异步 SDK 方法
• 如果必须在非主协程中触发，用 asyncio.create_task() 而非直接 await
• 示例错误写法：

  asyncio.run(some_func())  # 然后在 some_func 里 await execute_workflow() —— OK
  asyncio.run(another_func())  # 但 another_func 里又开了新 loop —— 不 OK

workflow_id 重复导致 “WorkflowExecutionAlreadyStartedError”

Temporal 要求 workflow_id 在 namespace 内全局唯一。重跑同一段 client 代码时若没换 ID，就会撞上已有运行中的 workflow，抛出 WorkflowExecutionAlreadyStartedError。

• 开发时加时间戳或随机后缀：f"my-workflow-{int(time.time())}"
• 不要用固定字符串如 "test" 或 "main"
• 生产环境需业务侧保证幂等性，不能靠 SDK 自动覆盖
• 注意：即使 workflow 已完成，只要没过 retention period，ID 仍被占用 —— WorkflowExecutionAlreadyStartedError 不代表“还在跑”，也可能“刚结束不久”

Tempora.io 的 Python SDK 表面简单，但网络、生命周期、ID 管理这三块特别容易在第一次跑通时掉坑里。尤其是 workflow_id 和 event loop 的隐式约束，不报错、不提示，只静默失败或卡住。

今天关于《temporal.io Python SDK 初体验分享》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！