temporal.io Python SDK 初体验报告

Temporal.io Python SDK 初上手看似简单，实则暗藏三大典型“踩坑区”：网络连接因 localhost 默认解析为 IPv6 的 ::1 而失败，需显式指定 service_host="127.0.0.1:7233" 并确认 Server 已通过 Docker 正常运行；Workflow 执行卡住不报错，本质是同步 run() 严格依赖 Worker 提前注册并持续运行，必须分离 client 与 worker 进程、注意调用顺序；异步方法如 execute_workflow() 易触发 event loop 关闭错误，需严格在同一个顶层 async main 中组织 await 调用，避免跨协程或线程误用；此外 workflow_id 全局唯一性极易被忽视——重复 ID 不仅导致 WorkflowExecutionAlreadyStartedError，还可能因保留期未过而让“已完成”的流程仍占用 ID。这些非显性约束不抛异常、不给提示，却让首次集成陷入静默失败的困境，掌握它们才是跑通 Temporal 的真正门槛。

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 的隐式约束，不报错、不提示，只静默失败或卡住。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。