dbos-java

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

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

適用する場面

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

• 既存の Java または Kotlin コードに DBOS を追加する場合
• ワークフローやステップを作成する場合
• 並行処理を制御するためにキューを使用する場合
• ワークフロー間の通信（イベント、メッセージ、ストリーム）を実装する場合
• Spring Boot を含む DBOS アプリケーションを設定して起動する場合
• 外部アプリケーションから DBOSClient を使用する場合
• DBOS アプリケーションをテストする場合

優先度別のルールカテゴリ

優先度	カテゴリ	影響	プレフィックス
1	ライフサイクル	重大	lifecycle-
2	ワークフロー	重大	workflow-
3	ステップ	高	step-
4	キュー	高	queue-
5	通信	中	comm-
6	パターン	中	pattern-
7	テスト	低〜中	test-
8	クライアント	中	client-
9	高度なトピック	低	advanced-

重要なルール

インストール

DBOS の依存関係を追加します（Java 17 以降、Gradle 8 以降を推奨します）。

dependencies {
    implementation("dev.dbos:transact:1.2.0")
    implementation("org.slf4j:slf4j-simple:2.0.17") // to see DBOS log messages
}

DBOS には PostgreSQL 互換のデータベースが必要です。接続設定は通常、DBOS_SYSTEM_JDBC_URL、PGUSER、PGPASSWORD を通じて指定します。

DBOS の設定と起動

DBOS アプリケーションでは、DBOS インスタンスを作成し、ワークフロークラスを登録してから起動する必要があります。

import dev.dbos.transact.DBOS;
import dev.dbos.transact.config.DBOSConfig;
import dev.dbos.transact.workflow.Workflow;

interface Example {
  String workflow(String input);
}

class ExampleImpl implements Example {
  private final DBOS dbos;

  ExampleImpl(DBOS dbos) {
    this.dbos = dbos;
  }

  @Override
  @Workflow
  public String workflow(String input) {
    return dbos.runStep(() -> fetchData(input), "fetchData");
  }

  private String fetchData(String input) { /* external call */ return input; }
}

public class App {
  public static void main(String[] args) {
    DBOSConfig config = DBOSConfig.defaultsFromEnv("my-app")
        .withAppVersion("0.1.0");
    DBOS dbos = new DBOS(config);

    Example proxy = dbos.registerProxy(Example.class, new ExampleImpl(dbos));

    dbos.launch();

    proxy.workflow("input"); // durable: called through the proxy
  }
}

新しいアプリケーションを作成する場合は、withAppVersion("0.1.0") を設定します。省略すると、DBOS はワークフローコード、SDK のバージョン、アプリケーション名から不透明なハッシュを生成します。既存のアプリケーションを編集する場合は、設定済みのバージョンを変更しないでください。変更はデプロイ上の判断です（references/advanced-versioning.md を参照）。バージョン名は共有システムデータベース全体で一意である必要があるため、同じデータベースを共有するアプリケーションには、それぞれ異なるバージョン文字列を指定してください（例："billing-0.1.0"。references/advanced-shared-database.md を参照）。

DBOSConfig.defaults(appName)／defaultsFromEnv(appName) に渡す名前はアプリケーションを識別し、そのアプリケーションが作成するすべてのものを管理します。複数のアプリケーション（言語は問いません）は、アプリケーション名によって分離したうえで、1 つのシステムデータベースを共有できます（1.1 以降。references/advanced-shared-database.md を参照）。

ワークフローとステップの構成

ワークフローは、registerProxy に登録されたクラス上の @Workflow アノテーション付きの通常のメソッドです。複雑な操作、非決定的な操作、または外部サービスを呼び出す操作は、dbos.runStep を使用するか、プロキシ経由で呼び出す @Step アノテーション付きメソッドとして、必ずステップ内で実行してください。

@Workflow
public String myWorkflow(String url) throws Exception {
  // Inline lambda step — use for one-off work
  String body = dbos.runStep(() -> httpGet(url), "httpGet");
  // Reusable step declared with @Step — MUST be invoked through the proxy (self)
  return self.parse(body);
}

@Step(maxAttempts = 3)
public String parse(String body) { /* ... */ }

主な制約

• ワークフローと @Step メソッドが耐久性を持つのは、registerProxy が返すプロキシ経由で呼び出された場合のみです（Spring Boot では、注入された自己参照経由で呼び出す場合も同様です）。this 経由の呼び出しでは DBOS を迂回します。
• すべてのワークフロークラスは launch() の前に登録する必要があります。データベースを使用するキューは launch() の後に登録します。
• ステップ内からワークフローを開始、キューに登録、または取得しないでください。また、ステップ内で send、recv、setEvent、getEvent を呼び出さないでください。
• ワークフローは決定的である必要があります。乱数、現在時刻、I/O、スレッド処理はステップ内で行ってください。
• ワークフローまたはステップから、ワークフロー自身のスコープ外の状態を変更しないでください。
• ワークフローの引数と、ステップ／ワークフローの戻り値は、Jackson で JSON にシリアライズできる必要があります。
• ワークフロー内では Thread.sleep ではなく dbos.sleep を使用してください。

使用方法

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

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

参考資料

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