Cadence现为Temporal是一个开源的分布式工作流编排平台但需要注意pycadence 并非 Cadence 官方 SDK而是早期社区为 CadenceUber 开源版本2017–2020 年间开发的一个非官方 Python 客户端库。随着 Cadence 项目于 2020 年正式演进为Temporal官方全面转向支持 Temporal Python SDK而pycadence已停止维护、不再兼容现代 Cadence/Temporal 服务且不支持 gRPC v1.40、TLS、多命名空间、Worker 模型等关键特性。✅ 正确做法推荐使用官方Temporal Python SDKtemporalio包它提供完整的异步/同步 API、类型安全、Workflow/Activity 编程模型、测试工具temporalio.testing及生产级可靠性。安装方式pip install temporalio示例 Workflow 定义fromtemporalioimportworkflow,activityfromtemporalio.clientimportClientworkflow.defnclassGreetingWorkflow:workflow.runasyncdefrun(self,name:str)-str:returnfHello,{awaitself._greet(name)}!activity.methodasyncdef_greet(self,name:str)-str:returnf{name}!⚠️ 注意事项pycadence依赖已过时的thrift协议Cadence v2.x 之前而 Temporal/Cadence v3 全面采用 gRPC Protobufpycadence无活跃维护最后 commit 在 2018 年GitHub 仓库已归档https://github.com/uber/cadence-client-python → 重定向失效实际已弃用若需对接遗留 Cadence 集群v2.x 及更早应严格匹配对应 Thrift IDL 版本并自行维护 fork但强烈建议升级至 Temporal。综上请勿在新项目中使用pycadence统一迁移到temporalioSDK。将旧 CadenceThrift-basedWorkflow 迁移到 Temporal Python SDK 是一项涉及协议层、API 模型和运行时语义的系统性升级。以下是分步、可落地的迁移指南兼顾兼容性与最佳实践✅ 1. 理解核心差异迁移前提维度旧 CadenceThriftTemporalgRPC/Protobuf通信协议Thrift RPCcadence.thriftIDLgRPC Protobuftemporal/api/...v1SDK 架构pycadence同步/简单封装temporalio原生 async/await类型安全装饰器驱动编程模型手动注册 Workflow/Activity无强类型校验workflow.defn/activity.defn装饰器 dataclass 参数Worker 模型单一 Worker 进程管理所有任务显式Worker实例支持多 Workflow/Activity 类型注册、并发控制、心跳等错误处理基于 Thrift 异常码如BadRequestError标准 Python 异常 Temporal 特定异常ApplicationFailure,TemporalError✅ 2. 迁移步骤实操清单 步骤 1环境与依赖替换# 卸载已弃用组件pip uninstall pycadence cadence-python# 安装官方 Temporal SDK支持 Python 3.8pipinstalltemporalio# 可选安装测试工具用于本地模拟pipinstalltemporalio[testing] 步骤 2重写 Workflow 定义示例对比旧 Cadencepycadencefromcadenceimportworkflowfromcadence.activity_methodimportactivity_methodclassGreetingWorkflow:workflow.method(task_listhello-tasklist)defsay_hello(self,name):returnself._greet(name)activity_method(task_listhello-tasklist,schedule_to_close_timeout60)def_greet(self,name):pass→ 迁移为 Temporal SDKfromtemporalioimportworkflow,activityfromdataclassesimportdataclassfromtypingimportOptional# ✅ 类型安全输入/输出推荐dataclassclassGreetingInput:name:strdataclassclassGreetingOutput:message:str# ✅ Workflow 定义异步 装饰器workflow.defnclassGreetingWorkflow:workflow.runasyncdefrun(self,inp:GreetingInput)-GreetingOutput:# ✅ 调用 Activity自动重试、超时、重入等由 SDK 管理resultawaitworkflow.execute_activity(greet_activity,inp.name,start_to_close_timeouttimedelta(seconds60),retry_policyRetryPolicy(maximum_attempts3))returnGreetingOutput(messagefHello,{result}!)# ✅ Activity 定义独立函数或类方法activity.defnasyncdefgreet_activity(name:str)-str:returnf{name}! 步骤 3重构 Worker 启动逻辑# 旧 pycadence 启动方式已废弃# from cadence.worker import DefaultWorker# worker DefaultWorker(host:port, domain, tasklist)# worker.add_workflow(GreetingWorkflow)# worker.start()# ✅ 新 Temporal Worker支持多任务、健康检查、优雅关闭importasynciofromtemporalio.clientimportClientfromtemporalio.workerimportWorkerasyncdefmain():clientawaitClient.connect(localhost:7233,namespacedefault)workerWorker(client,task_queuehello-taskqueue,workflows[GreetingWorkflow],activities[greet_activity],# ✅ 可配置并发、心跳、日志等max_concurrent_workflow_tasks100,max_concurrent_activities50,)awaitworker.run()# 阻塞运行if__name____main__:asyncio.run(main()) 步骤 4适配客户端调用Start Query# 旧方式pycadence# client.start_workflow(GreetingWorkflow, John, task_listhello-tasklist)# ✅ 新方式类型安全 异步fromtemporalio.clientimportClientasyncdefstart_greeting():clientawaitClient.connect(localhost:7233,namespacedefault)handleawaitclient.start_workflow(GreetingWorkflow.run,GreetingInput(nameJohn),idgreeting-workflow-123,task_queuehello-taskqueue)# ✅ 等待完成 or 查询状态resultawaithandle.result()print(result.message)# Hello, John! 步骤 5关键注意事项Domain → NamespaceCadence 的domain在 Temporal 中称为namespace需提前通过 CLI 或 UI 创建Task List → Task Queue语义相同但 Temporal 更强调“队列”抽象支持多 Worker 共享同一队列重试与超时Temporal 使用RetryPolicy和timedelta非秒数整型需显式配置历史事件兼容性无法直接复用旧 Workflow Execution 历史迁移后需以新 Workflow Type 名称启动新执行旧执行仍可在旧集群查看但不可续跑本地开发使用temporalio-testing模块进行 determinism 测试避免非确定性错误。✅ 3. 自动化辅助建议使用temporalio-migrate社区工具非官方辅助生成基础模板对接 CI/CD在 GitHub Actions 中集成temporalio/testing进行 Workflow 单元测试日志与可观测性启用temporalio的 OpenTelemetry 集成opentelemetry-exporter-otlp对接 Jaeger/Prometheus。✅ 总结迁移本质是从协议绑定型 SDK 迈向声明式、类型驱动、云原生工作流框架。虽需重构代码但换来的是更强健性、可观测性、社区支持与长期演进保障。