using-backstage-backend-system

Backstage バックエンドのシステムパターン

このスキルを使用する場面

• 新しいバックエンドプラグイン（src/plugin.ts）を定義する場合
• 別のプラグインを拡張するバックエンドモジュール（src/module.ts）を定義する場合
• 完全なプラグインとモジュールのどちらを選ぶか判断する場合
• 他のモジュールがプラグインを拡張できるように、拡張ポイントを公開する場合

適切なパターンを選択する

構築するもの	パターン	リファレンス
プラグイン本体	createBackendPlugin({ pluginId, register })	references/plugin-definition.md
別のプラグインを拡張するモジュール	createBackendModule({ pluginId, moduleId, register })	references/modules.md
他のモジュールが拡張できる拡張ポイント	createExtensionPoint<T>({ id })	references/extension-points.md

2 つの呼び出しモード

• スタンドアロン：既存のバックエンドプラグイン／モジュールを編集します。
• スキャフォールド後（backend-plugin、backend-plugin-module、catalog-provider-module、scaffolder-backend-module に対して creating-backstage-plugin が呼び出す場合）：標準的な構成（src/plugin.ts または src/module.ts、および src/index.ts での再エクスポート）を設定します。

よくある注意点

• 配線に使用するインポートはすべて @backstage/backend-plugin-api から行います。@backstage/core-plugin-api はフロントエンド専用です。
• register(env) コールバックは、env.registerInit({ deps, async init }) と env.registerExtensionPoint(point, impl) を備えた環境オブジェクトを受け取ります。deps は init 関数が必要とするサービス参照のマップで、init は解決済みのインスタンスを受け取ります。
• registerInit はプラグイン／モジュールごとに 1 回だけ呼び出せます。registerExtensionPoint は registerInit より前に呼び出す必要があります。
• プラグインスコープとルートスコープのサービス：多くの参照（logger、httpRouter、database、scheduler、auth、httpAuth、userInfo、cache、discovery、urlReader、lifecycle、permissions）はプラグインスコープです。各プラグインは、プラグインを認識する動作（例：pluginId があらかじめタグ付けされた logger、プラグインごとのスキーマを提供する database）を備えた独自のインスタンスを取得します。6 つの参照（rootConfig、rootLogger、rootLifecycle、rootHealth、rootHttpRouter、rootInstanceMetadata）はルートスコープで、共有インスタンスは 1 つです。どちらもプラグインの register ブロックから依存先として指定できます。違いは動作に関するものであり、注入の構文には関係ありません。
• プラグインの pluginId とモジュールの moduleId は、パターン [a-z][a-z0-9-]*（文字、数字、ハイフン。先頭は英字）に一致する必要があります。
• モジュールは、対象プラグインのライブラリパッケージ（例：@backstage/plugin-catalog-node）からエクスポートされた拡張ポイントに依存します。プラグインのメインパッケージには依存しません。