dbos-typescript

DBOS TypeScript 最佳实践

使用 DBOS 持久化工作流构建可靠、容错的 TypeScript 应用程序指南。适用于 DBOS TypeScript 5.x（@dbos-inc/dbos-sdk）。如果项目使用 4.x，或使用了已移除的 API（new WorkflowQueue、@DBOS.scheduled/DBOS.registerScheduled、partitionQueue、priorityEnabled、@DBOS.requiredRole、基于 dbos-config.yaml 的配置），请参阅 references/advanced-upgrading.md。

适用场景

在以下情况下参考这些准则：

• 将 DBOS 添加到现有 TypeScript 代码中
• 创建工作流和步骤
• 使用队列控制并发
• 实现工作流通信（事件、消息、流）
• 配置并启动 DBOS 应用程序
• 在外部应用程序中使用 DBOSClient
• 测试 DBOS 应用程序

按优先级划分的规则类别

优先级	类别	影响	前缀
1	生命周期	CRITICAL	lifecycle-
2	工作流	CRITICAL	workflow-
3	步骤	HIGH	step-
4	队列	HIGH	queue-
5	通信	MEDIUM	comm-
6	模式	MEDIUM	pattern-
7	测试	LOW-MEDIUM	test-
8	客户端	MEDIUM	client-
9	高级	LOW	advanced-

关键规则

安装

始终安装最新版本的 DBOS：

npm install @dbos-inc/dbos-sdk@latest

DBOS 配置与启动

DBOS 应用程序在运行任何工作流之前，必须配置并启动 DBOS：

import { DBOS } from "@dbos-inc/dbos-sdk";

async function main() {
  DBOS.setConfig({
    name: "my-app",
    applicationVersion: "0.1.0",
    systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL,
  });
  await DBOS.launch();
  await myWorkflow();
}

main().catch(console.log);

创建新应用程序时，将 applicationVersion 设为 "0.1.0"。如果省略，DBOS 会根据工作流源代码生成一个不透明的哈希值。编辑现有应用程序时，保留已配置的版本不变——更改版本属于部署决策（参见 references/advanced-versioning.md）。

工作流与步骤结构

工作流由多个步骤组成。任何执行复杂操作或访问外部服务的函数，都必须通过 DBOS.runStep 作为步骤运行：

import { DBOS } from "@dbos-inc/dbos-sdk";

async function fetchData() {
  return await fetch("https://api.example.com").then(r => r.json());
}

async function myWorkflowFn() {
  const result = await DBOS.runStep(fetchData, { name: "fetchData" });
  return result;
}
const myWorkflow = DBOS.registerWorkflow(myWorkflowFn);

关键约束

• 不要在步骤中调用、启动或排入工作流
• 不要使用线程或不受控的并发来启动工作流——请使用 DBOS.startWorkflow 或队列
• 工作流必须具有确定性——非确定性操作应放在步骤中
• 不要在工作流或步骤中修改全局变量
• 在 DBOS.launch() 之后注册队列（DBOS.registerQueue）并创建计划任务（DBOS.applySchedules/DBOS.createSchedule）——它们存储在系统数据库中
• 只有从工作流中调用步骤时，步骤才具有持久性；在工作流之外调用时，它们会作为普通函数调用运行
• 连接到 DBOS Conductor（conductorKey，或部署到 DBOS Cloud）需要安装与 @dbos-inc/dbos-sdk 次要版本相同的 @dbos-inc/dbos-enterprise

使用方法

阅读各个规则文件，了解详细说明和示例：

references/lifecycle-config.md
references/workflow-determinism.md
references/queue-concurrency.md
references/advanced-upgrading.md
references/advanced-shared-database.md

如果多个应用程序共用一个系统数据库，请始终在 DBOSClient 上设置 applicationName，并参阅 references/advanced-shared-database.md。

参考资料

• https://docs.dbos.dev/
• https://github.com/dbos-inc/dbos-transact-ts