dbos-typescript

DBOS TypeScript のベストプラクティス

DBOS の永続ワークフローを使用して、信頼性と耐障害性に優れた TypeScript アプリケーションを構築するためのガイドです。

使用するタイミング

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

• 既存の 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-

重要なルール

インストール

既存のアプリケーションと互換性のある、サポート対象の 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 だけでは、カードへの請求が一度しか行われないことは保証されません。
• データベースのリセット、キャンセル、再開、フォークの例では、対象と認可を明示する必要があります。これらの操作により、データが破壊されたり、キューの制限が回避されたり、副作用が繰り返されたりするおそれがあります。
• このスキルは、タスクが上記の説明にある範囲に明確に該当する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中止して確認を求めてください。