dbos-python

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

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

使用する場面

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

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

ランタイムの境界

サンプルはバージョンに依存する断片であり、アプリのセットアップ、インポート、ハンドラーは省略されています。インストール済みの DBOS API を確認してください。永続ワークフローの ID によって、任意の外部副作用が厳密に 1 回だけ実行されるわけではありません。チェックポイントの記録前にクラッシュすると、ステップが再実行されることがあります。支払いやメッセージには、プロバイダーの冪等性キーを使用し、照合処理を行ってください。データベースの対象と書き込みを認可し、シリアル化された入力と結果を保護してください。信頼できない pickle データは決してデシリアライズしないでください。API ルートには、認証、テナントの所有権確認、Webhook の署名検証とリプレイ検証、上限付きの待機時間が必要です。破壊的なテストのリセットには、専用の使い捨てシステムデータベースを使用してください。変数名だけでは、対象が正しいことの証明にはなりません。

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

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

重要なルール

DBOS の設定と起動

DBOS アプリケーションでは、メイン関数内で DBOS を設定して起動する必要があります。

import os
from dbos import DBOS, DBOSConfig

@DBOS.workflow()
def my_workflow():
    pass

if __name__ == "__main__":
    config: DBOSConfig = {
        "name": "my-app",
        "system_database_url": os.environ.get("DBOS_SYSTEM_DATABASE_URL"),
    }
    DBOS(config=config)
    DBOS.launch()

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

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

@DBOS.step()
def call_external_api():
    return requests.get("https://api.example.com").json()

@DBOS.workflow()
def my_workflow():
    result = call_external_api()
    return result

主な制約

• ステップから DBOS.start_workflow または DBOS.recv を呼び出さないでください
• ワークフローを開始するためにスレッドを使用しないでください。DBOS.start_workflow またはキューを使用してください
• ワークフローは決定論的でなければなりません。非決定論的な処理はステップに含めてください
• ワークフローやステップからグローバル変数を作成または更新しないでください

使用方法

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

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

参考資料

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

制限事項

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