roblox-luau-patterns

Luau パターン

読み込むタイミング

モジュールの構造、リソースの所有権、スケジューリング、失敗時の契約について確認するときに読み込みます。セマンティクスは roblox-luau-core、型は roblox-luau-types、起動処理は roblox-architecture を参照してください。

クイックリファレンス

構造を選ぶ

• 通常の関数： 状態を持たない変換や検証では、これをデフォルトにします。
• プライベート状態を持つモジュール： 明確な所有者を持つサブシステムが1つある場合に使います。関数を名前空間にまとめるだけの目的で、マネージャークラスを作らないでください。
• メタテーブルを持つオブジェクト： 複数の独立した値で、共通の振る舞いやライフサイクルが必要な場合に使います。
• 既存のライブラリ抽象化： プロジェクトですでに一貫して使われている場合は、それに従います。1つの呼び出し箇所のために、Promise、シグナル、クリーンアップ、フレームワークへの依存を追加しないでください。

コンストラクターには .、インスタンスメソッドには : を使い、変更可能なフィールドはクラステーブルではなくインスタンスに置きます。

所有権を明確にする

シグナル接続、インスタンス、タスクにはクリーンアップを担う所有者が必要です。終了処理時に切断またはキャンセルしてください。型付きのカスタムシグナルペイロード（Signal<T...>）をエクスポートします。

部分的な状態が見えないよう、親に設定する前に構成してください。祖先関係が必要な場合に限り、先に親に設定し、その理由を説明してください。これによってレプリケーションの順序が保証されるわけではありません。

失敗時のセマンティクスを保つ

local ok, value = pcall(dataStore.GetAsync, dataStore, key)
if not ok then
    return nil, `read failed: {value}`
end
return value, nil -- value may legitimately be nil

「呼び出しが成功し、nil を返した」状態を「呼び出しが失敗した」状態にまとめないでください。ドメイン操作を安全に繰り返せる場合に限り、再試行してください。永続化、HTTP、購入、リモート通信には、それぞれのドメインスキルを参照してください。

名前付けと戻り値の契約

実務上の慣例として、yield する関数には Async を付け、戻り値の数を一貫させ、名前付きのモジュールエクスポートを優先します。既存のプロジェクトの契約に従ってください。詳細は full.md を参照してください。

意図的にスケジュールする

task.defer、task.spawn、task.delay、task.cancel は意図を持って使います。旧式の wait() や、正当な理由のないポーリングは避けてください。実際の状態変化シグナルを優先し、それがない場合は明示的な間隔を選んで計測してください。

レビュー

所有者が明確であること、公開 API が絞られていること、循環 require がないこと、意図しない並行起動がないこと、成功状態とデータ欠損状態が区別されていること、接続やタスクがクリーンアップされていること、クライアント入力が roblox-networking にルーティングされていることを確認します。

詳細：references/full.md