dbos-typescript

DBOS TypeScript 最佳实践

使用 DBOS 持久化工作流构建可靠、容错的 TypeScript 应用的指南。

适用场景

在以下情况下参考这些指南：

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

按优先级划分的规则类别

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

关键规则

安装

安装与现有应用兼容的受支持 SDK 版本，并将其固定在锁文件中。对于新项目，请先确认当前官方版本：

npm install @dbos-inc/dbos-sdk@<verified-version>

DBOS 配置与启动

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

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

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

main().catch(error => { console.error(error); process.exitCode = 1; });

工作流与步骤结构

工作流由步骤组成。任何执行复杂操作或访问外部服务的函数，都必须通过 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 或队列
• 工作流必须具有确定性；非确定性操作应放在步骤中
• 不要从工作流或步骤中修改全局变量

使用方法

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

references/lifecycle-config.md
references/workflow-determinism.md
references/queue-concurrency.md

参考资料

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

限制

• 示例是特定版本的示意代码；请根据已安装的 SDK 核实函数签名和迁移指南。启动前注册工作流和步骤。妥善保管数据库凭据。
• 步骤重放和重试可能会重复产生外部影响。请使用服务提供方稳定的幂等键和应用事务；仅凭工作流 ID 并不能保证卡片只扣款一次。
• 数据库重置、取消、恢复和分叉示例都需要明确的目标和授权；它们可能会销毁数据、绕过队列限制或重复产生影响。
• 仅当任务明显符合上述范围时，才使用此技能。
• 不要将输出视为可替代特定环境验证、测试或专家审查的内容。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。