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 を参照してください。

適用する場面

次のような場合に、これらのガイドラインを参照してください。

• 既存の TypeScript コードに DBOS を追加するとき
• ワークフローとステップを作成するとき
• 同時実行制御にキューを使用するとき
• ワークフロー間の通信（イベント、メッセージ、ストリーム）を実装するとき
• 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.registerQueue）の登録とスケジュール（DBOS.applySchedules/DBOS.createSchedule）の作成は、DBOS.launch() の後に行ってください。これらはシステムデータベースに保存されます
• ステップが永続化されるのは、ワークフローから呼び出された場合のみです。ワークフロー外では通常の関数呼び出しとして実行されます
• DBOS Conductor（conductorKey、または DBOS Cloud へのデプロイ）に接続するには、@dbos-inc/dbos-enterprise を @dbos-inc/dbos-sdk と同じマイナーバージョンでインストールする必要があります

使用方法

詳しい説明と例については、個別のルールファイルを参照してください。

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

複数のアプリケーションで 1 つのシステムデータベースを共有する場合は、必ず DBOSClient に applicationName を設定し、references/advanced-shared-database.md を参照してください。

参考資料

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