dbos-golang

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

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

使用する場面

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

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

信頼性とバージョンの境界

これらの例示的な断片を利用する前に、DBOS Go SDK のバージョンを固定して確認してください。現在の SDK ドキュメントでは dbos.Context が使用されていますが、このスナップショットでは dbos.DBOSContext が使用されています。ヘルパー、インポート、登録処理、アプリケーション固有の関数は省略されています。スニペットが完全なアプリとしてコンパイルできると主張しないでください。ハンドルや結果を使用する前に、返されたエラーをすべて確認してください。ワークフロー ID やチェックポイント付きステップを使っても、外部の決済や API の副作用が厳密に 1 回だけ実行されるわけではありません。リモート処理の実行後、チェックポイントの記録前にクラッシュすると、その処理が再実行される可能性があります。プロバイダーの冪等性キーを使用し、照合してください。Send の前に Webhook メッセージを認証して重複排除し、ワークフローへのアクセスを呼び出し元の範囲に限定してください。キューの上限が制御するのはワークフローの開始であり、ワークフロー内のすべてのリクエストや再試行ではありません。キャンセルしても、確定済みの副作用は取り消せません。ワークフローの入力、出力、エラーペイロードに、秘密情報や不要な個人データを含めないでください。認可なしに管理エンドポイント、スケジュール、有料 API 呼び出し、管理用の変更処理を有効にしないでください。

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

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

重要なルール

インストール

DBOS Go モジュールをインストールします。

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

DBOS の設定と起動

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

package main

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

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

func main() {
	ctx, err := dbos.NewDBOSContext(context.Background(), dbos.Config{
		AppName:     "my-app",
		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)
	}
}

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

ワークフローはステップで構成されます。複雑な処理を行う関数や外部サービスにアクセスする関数は、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.DBOSContext, input string) (string, error) {
	result, err := dbos.RunAsStep(ctx, fetchData, dbos.WithStepName("fetchData"))
	if err != nil {
		return "", err
	}
	return result, nil
}

主な制約

• ステップ内からワークフローを開始したり、キューに追加したりしないでください
• ワークフローの開始に、制御されていない goroutine を使用しないでください。並行ステップには、キューを使った dbos.RunWorkflow または dbos.Go／dbos.Select を使用してください
• ワークフローは決定的でなければなりません。非決定的な処理はステップ内で行ってください
• ワークフローやステップからグローバル変数を変更しないでください
• Launch() を呼び出す前に、すべてのワークフローとキューを登録する必要があります

使用方法

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

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

参考資料

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

制限事項

• タスクが上記の説明の範囲に明確に該当する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、成功基準が不足している場合は、作業を中断して確認してください。