dbos-golang

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

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

適用するタイミング

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

• 既存の Go コードに DBOS を追加するとき
• ワークフローとステップを作成するとき
• データソースを介してデータベーストランザクションを耐久性のある形で実行するとき
• 同時実行制御にキューを使用するとき
• ワークフロー間の通信（イベント、メッセージ、ストリーム）を実装するとき
• DBOS アプリケーションを設定して起動するとき
• 外部アプリケーションから DBOS クライアントを使用するとき
• 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 Go モジュール（v1）をインストールします。

go get github.com/dbos-inc/dbos-transact-golang/dbos@latest

DBOS Conductor に接続するには（ConductorAPIKey を設定するか、DBOS Cloud で実行する場合）、go.dbos.dev/dbos-enterprise-go をインポートする必要があります（go get go.dbos.dev/dbos-enterprise-go）。また、プログラム内のいずれかの場所でブランクインポートを行う必要があります。そうしないと、dbos.NewContext は初期化エラーで失敗します。

import _ "go.dbos.dev/dbos-enterprise-go"

DBOS の設定と起動

DBOS アプリケーションでは、ワークフローを実行する前にコンテキストを作成し、ワークフローを登録して起動する必要があります。

package main

import (
	"context"
	"log"
	"os"
	"time"

	"github.com/dbos-inc/dbos-transact-golang/dbos"
)

func main() {
	ctx, err := dbos.NewContext(context.Background(), dbos.Config{
		AppName:            "my-app",
		ApplicationVersion: "0.1.0",
		DatabaseURL:        os.Getenv("DBOS_SYSTEM_DATABASE_URL"),
	})
	if err != nil {
		log.Fatal(err)
	}
	defer dbos.Shutdown(ctx, 30*time.Second)

	dbos.RegisterWorkflow(ctx, myWorkflow)

	if err := dbos.Launch(ctx); err != nil {
		log.Fatal(err)
	}
}

新しいアプリケーションを作成するときは、ApplicationVersion を "0.1.0" に設定します。省略すると、DBOS はバイナリから不透明なハッシュを生成します。既存のアプリケーションを編集する場合は、設定済みのバージョンを変更しないでください。変更はデプロイに関する判断です（references/advanced-application-versions.md を参照）。

DatabaseURL には、Postgres／CockroachDB の URL または SQLite の URL（sqlite:/path/to.db、sqlite::memory:）を指定できます。SQLite を使用するには、github.com/dbos-inc/dbos-transact-golang/dbos/driver/sqlite のブランクインポートが必要です。Conductor の設定や、アプリケーションとは別にスキーマをマイグレーションする方法を含むすべての設定オプションについては、references/lifecycle-config.md を参照してください。

dbos.Context は dbos.Client を拡張したものです。管理関数（Enqueue、ListWorkflows、CancelWorkflow、キューおよびスケジュールの管理など）は dbos.Client を受け取り、Context と dbos.NewClient から作成したスタンドアロンクライアントのどちらも使用できます（references/client-setup.md を参照）。

AppName はアプリケーションを識別し、そのアプリケーションが作成するすべてのものを管理します。複数のアプリケーション（言語は問いません）で、アプリケーション名によって分離しながら、1 つのシステムデータベースを共有できます（v1.2.0 以降。references/advanced-shared-database.md を参照）。

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

ワークフローはステップで構成されます。複雑な処理を実行する関数や外部サービスにアクセスする関数は、dbos.RunAsStep を使用してステップとして実行する必要があります。

func fetchData(ctx context.Context) (string, error) {
	resp, err := http.Get("https://api.example.com/data")
	if err != nil {
		return "", err
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	return string(body), nil
}

func myWorkflow(ctx dbos.Context, input string) (string, error) {
	result, err := dbos.RunAsStep(ctx, fetchData, dbos.WithStepName("fetchData"))
	if err != nil {
		return "", err
	}
	return result, nil
}

必ず一度だけ実行する必要があるデータベースへの書き込みは、ステップではなく、データソースのトランザクション（dbos.RunAsTransaction）に含めます（references/step-transactions.md を参照）。

主な制約事項

• ステップ内からワークフローを開始したり、キューに追加したりしないでください
• ステップ内から dbos.RunAsTransaction、handle.GetResult、または dbos.CloseStream を呼び出さないでください（読み取り、dbos.SetEvent、dbos.WriteStream は可能です）
• ワークフローの開始に、制御されていないゴルーチンを使用しないでください。並行ステップには、キューを使った dbos.RunWorkflow または dbos.Go／dbos.Select を使用してください
• ワークフローは決定論的でなければなりません。非決定的な操作はステップ内で行ってください
• ワークフローやステップからグローバル変数を変更しないでください
• Launch() を呼び出す前に、すべてのワークフローを登録し、dbos.NewDataSource でデータソースを作成してください。キューは dbos.RegisterQueue で登録し、データベースに永続化されます
• すでに使用中の ID でワークフローを開始すると、デフォルトでは既存のワークフローが返されます。代わりに dbos.ErrWorkflowIDInUse を返すには、dbos.WithWorkflowIDReusePolicy(dbos.WorkflowIDReusePolicyReject) を渡してください（references/pattern-idempotency.md を参照）
• ワークフロー内のパニックがプロセスをクラッシュさせることはありません。DBOS はそのパニックをワークフローのエラー（dbos.ErrWorkflowPanic）として記録します

使用方法

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

references/lifecycle-config.md
references/workflow-determinism.md
references/step-transactions.md
references/queue-concurrency.md
references/workflow-control.md

参考資料

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