dbos-typescript
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDBOS TypeScript Best Practices
DBOS TypeScript 最佳实践
Guide for building reliable, fault-tolerant TypeScript applications with DBOS durable workflows.
本指南介绍如何使用 DBOS 持久化工作流构建可靠、容错的 TypeScript 应用。
When to Apply
适用场景
Reference these guidelines when:
- Adding DBOS to existing TypeScript code
- Creating workflows and steps
- Using queues for concurrency control
- Implementing workflow communication (events, messages, streams)
- Configuring and launching DBOS applications
- Using DBOSClient from external applications
- Testing DBOS applications
在以下场景中可参考本指南：
- 为现有 TypeScript 代码集成 DBOS
- 创建工作流与步骤
- 使用队列进行并发控制
- 实现工作流通信（事件、消息、流）
- 配置与启动 DBOS 应用
- 从外部应用调用 DBOSClient
- 测试 DBOS 应用
Rule Categories by Priority
按优先级划分的规则类别
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Lifecycle | CRITICAL | |
| 2 | Workflow | CRITICAL | |
| 3 | Step | HIGH | |
| 4 | Queue | HIGH | |
| 5 | Communication | MEDIUM | |
| 6 | Pattern | MEDIUM | |
| 7 | Testing | LOW-MEDIUM | |
| 8 | Client | MEDIUM | |
| 9 | Advanced | LOW | |
| 优先级 | 类别 | 影响程度 | 前缀 |
|---|---|---|---|
| 1 | 生命周期 | 严重（CRITICAL） | |
| 2 | 工作流 | 严重（CRITICAL） | |
| 3 | 步骤 | 高（HIGH） | |
| 4 | 队列 | 高（HIGH） | |
| 5 | 通信 | 中（MEDIUM） | |
| 6 | 模式 | 中（MEDIUM） | |
| 7 | 测试 | 中低（LOW-MEDIUM） | |
| 8 | 客户端 | 中（MEDIUM） | |
| 9 | 高级特性 | 低（LOW） | |
Critical Rules
核心规则
Installation
安装
Always install the latest version of DBOS:
bash
npm install @dbos-inc/dbos-sdk@latest请始终安装最新版本的 DBOS：
bash
npm install @dbos-inc/dbos-sdk@latestDBOS Configuration and Launch
DBOS 配置与启动
A DBOS application MUST configure and launch DBOS before running any workflows:
typescript
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(console.log);DBOS 应用必须在运行任何工作流之前完成配置与启动：
typescript
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(console.log);Workflow and Step Structure
工作流与步骤结构
Workflows are comprised of steps. Any function performing complex operations or accessing external services must be run as a step using :
DBOS.runSteptypescript
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.runSteptypescript
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);Key Constraints
关键约束
- Do NOT call, start, or enqueue workflows from within steps
- Do NOT use threads or uncontrolled concurrency to start workflows - use or queues
DBOS.startWorkflow - Workflows MUST be deterministic - non-deterministic operations go in steps
- Do NOT modify global variables from workflows or steps
- 请勿在步骤内部调用、启动或入队工作流
- 请勿使用线程或无控制的并发来启动工作流 - 请使用 或队列
DBOS.startWorkflow - 工作流必须是确定性的 - 非确定性操作应放在步骤中
- 请勿在工作流或步骤中修改全局变量
How to Use
使用方法
Read individual rule files for detailed explanations and examples:
references/lifecycle-config.md
references/workflow-determinism.md
references/queue-concurrency.md请阅读单个规则文件以获取详细说明与示例：
references/lifecycle-config.md
references/workflow-determinism.md
references/queue-concurrency.md