using-backstage-backend-services

Backstage バックエンドサービス

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

• プラグインまたはモジュールで、ロギング、設定、HTTP ルーティング、データベース、スケジューリング、キャッシュ、URL フェッチ、サービスディスカバリー、認証が必要な場合
• ユーザーが特定の coreServices.* 参照について言及した場合
• register({ deps: {...} }) ブロックに新しい依存関係を追加する場合

適切なサービスを選択する

必要な機能	サービス	リファレンス
ロギング	coreServices.logger（プラグイン単位で、あらかじめ pluginId のタグが付与されます）	references/logger-and-config.md
app-config.yaml の読み込み	coreServices.rootConfig	references/logger-and-config.md
HTTP ルートの登録	coreServices.httpRouter	references/http-router.md
Knex データベースへのアクセス	coreServices.database（プラグイン単位で、分離されたスキーマを使用します）	references/database.md
定期タスク／cron タスク	coreServices.scheduler	references/scheduler-and-lifecycle.md
起動／シャットダウン時のフック	coreServices.lifecycle（プラグイン）または coreServices.rootLifecycle（ルート）	references/scheduler-and-lifecycle.md
サービス間トークン	coreServices.auth	references/auth.md
受信リクエストの認証	coreServices.httpAuth	references/auth.md
認証情報から現在のユーザーを解決	coreServices.userInfo	references/auth.md
外部 URL の読み込み（GitHub、GitLab など）	coreServices.urlReader	references/urlReader-and-discovery.md
バックエンドプラグインのベース URL の解決	coreServices.discovery	references/urlReader-and-discovery.md
キーと値のキャッシュ	coreServices.cache	references/cache.md

2 つの呼び出しモード

• スタンドアロン：既存のプラグインまたはモジュールにサービス依存関係を追加します。
• スキャフォールド後（バックエンドテンプレート向けに creating-backstage-plugin から呼び出されます）：デフォルトとして coreServices.logger と coreServices.httpRouter を含めます。意図から必要性がうかがえる場合は、追加のサービスを提示します（例：「X を保存する」→ データベース、「N 分ごとにポーリングする」→ スケジューラー）。

よくある注意点

• すべての参照は @backstage/backend-plugin-api から取得します。実際の実装は @backstage/backend-defaults にありますが、プラグインが使用するのは参照のみです。
• プラグインスコープのサービスは、各プラグインに分離されたインスタンスを提供します。coreServices.database はプラグインごとのスキーマにスコープされた Knex クライアントを返し、coreServices.logger にはあらかじめ pluginId がタグ付けされています。Knex インスタンスを渡してプラグイン間で共有しようとしないでください。プラグイン間の呼び出しには、coreServices.discovery と HTTP を使用してください。
• auth、httpAuth、userInfo サービスは混同しやすいので注意してください。auth はサービス間呼び出し用のトークンを発行・検証し、httpAuth は受信した Express リクエストを認証し、userInfo は httpAuth から返された認証情報をもとにユーザー ID を解決します。
• coreServices.scheduler はレプリカ間で永続的なタスクをスケジュールします。本番タスクに setInterval を使用しないでください。
• テストでは、ユニットテスト用のインスタンスを取得する場合は mockServices.<name>(...) を使用し、startTestBackend({ features: [...] }) に渡す場合は mockServices.<name>.factory(...) を使用してください。すべてのサービスにファクトリーがあるわけではありません。通常、httpRouter、cache、urlReader、lifecycle はテストバックエンドのデフォルトで提供されます。
• discovery と auth を使って別の Backstage プラグインを呼び出す場合（プラグイン間 HTTP）、@backstage/errors の throw await ResponseError.fromResponse(response) を使って OK 以外のレスポンスを処理してください。レスポンス本文を解析して構造化されたエラー情報を取得し、他の Backstage レイヤー（ロギング、エラー報告、フロントエンドの <ResponseErrorPanel>）が理解できる型付きエラーを生成します。throw new Error(\Failed: ${response.status}`)` のように単純なエラーを投げないでください。
• ルートハンドラー内では、@backstage/errors の型付きエラー（NotFoundError、InputError、NotAllowedError、ConflictError、ServiceUnavailableError、ForwardedError など）を投げてください。デフォルトのバックエンドエラーミドルウェアが、適切にフォーマットされた HTTP レスポンスに変換します。エラーケースで res.status(...).json(...) を使用しないでください。references/http-router.md を参照してください。