elysia

Elysia 開発者ガイド

このスキルでは、このプロジェクトで Elysia フレームワークを使用するためのガイドライン、パターン、ベストプラクティスを紹介します。

クイックスタート

開発ガイドライン、インポート、パターンの詳細については、このスキルのディレクトリにある references/patterns.md を参照してください。

基本理念

• パターンに依存しない、機能ベースの構成を推奨します
• **「Elysia インスタンス 1 つ = コントローラー 1 つ」**の原則
• 実行時検証には TypeBox を使用し、強い型付けを実現します
• 一元化されたエラー処理と一貫性のあるレスポンス
• 本番環境に対応したデプロイ戦略

構成、ルーティング、コントローラー

基本的な構成パターン

• コントローラーとしてのアプリ：各 new Elysia({ prefix }) インスタンスを、その機能のコントローラーとして扱います。クラスのメソッド全体をハンドラーとして直接渡さないでください。代わりに、サービス関数を呼び出す小さなハンドラーをインラインで記述します。
• 機能別フォルダー：機能ベースの構成を使用します。
  • src/modules/<feature>/index.ts - Elysia コントローラー（ルート、ガード、Cookie）
  • src/modules/<feature>/service.ts - ビジネスロジック（HTTP コンテキストなし）
  • src/modules/<feature>/model.ts - t（TypeBox）を使ったスキーマと型
  • 共通ユーティリティは src/utils/* に配置します。
• メソッドチェーン：ルート、ガード、プラグインには、Elysia インスタンスでの流れるようなメソッドチェーンを優先します。
• プラグイン：.use() を使って、横断的な関心事（OpenAPI、JWT、CORS など）をプラグインにまとめます。
• コンテキストの適切な管理：サービスでリクエストデータが必要な場合は、コントローラー内に保持し、関連するフィールドだけをサービス関数に渡します。

機能のスキャフォールディングパターン

機能をスキャフォールディングする際は、以下を生成します。

1. t.Object(...) スキーマと、typeof schema.static を使用したエクスポート済みの type エイリアスを含む model.ts。
2. 純粋関数（インスタンスの状態が不要な場合は、静的メソッドのみを持つ abstract class）を含む service.ts。
3. Elysia のルートをマウントし、共通の検証を適用する guard() を使用して、型付きレスポンスを返す index.ts。

検証、スキーマ、型

実行時検証と静的型

• import { t } from 'elysia' を使って、Body、Query、Params、Headers、Cookie、Response のスキーマを定義します。
• typeof schema.static から TS 型を導出してエクスポートします（例：export type SignInBody = typeof signInBody.static）。
• .guard({ ... }) を使って共通の検証を適用します。ガードを組み合わせる場合は、独立性を保つために schema: 'standalone' の使用を検討してください。
• 標準的なスキーマシステムを使用する場合は、ファイルの内容を fileType（マジックナンバー）で検証します。
• エンドツーエンドで強い型付けを実現するため、2xx およびエラーの各バリエーションに対するレスポンススキーマを用意します。

ハンドラースキーマのガイドライン

ハンドラーを生成する際は、次の点に従います。

• body/query/params/headers/cookie/response を含む、3 番目の引数のスキーマオブジェクトを指定します。
• GET/HEAD ではボディを解析しないでください（Elysia は HTTP 仕様に準拠しています）。
• t.Object、t.Array、t.Union、t.Literal、ファイルスキーマの例を示し、共通の Query/Headers に対する guard() の使用方法も示します。

エラー処理とレスポンス形式

エラー管理の一元化

• アプリで .onError(({ code, error, path, request }) => { ... }) を使い、フレームワークのエラーとカスタムエラーを統一された JSON 形式（例：{ ok: false, error: { code, message, details } }）に変換します。
• onError で捕捉できるエラー制御フローには、throw status(code, messageOrPayload) を優先します。注意：return status(...) は onError で捕捉されません。
• 検証エラーは予測可能な JSON（問題の配列）に正規化し、本番環境では機密性の高い内部情報を隠します。
• 相関 ID（例：x-request-id）を含め、onError 内でログを記録します。本番環境ではスタックトレースを漏えいさせないでください。
• 成功レスポンスは、統一性を保つために { ok: true, data } でラップしてもかまいません。

エラープラグインの構成

コードを生成する際は、以下を作成します。

• .onError(...) を登録する src/plugins/error.ts。
• 必要に応じて、onResponse と onError でログを記録する src/plugins/logging.ts。

OpenAPI、認証、横断的な関心事

OpenAPI

• @elysiajs/openapi プラグインを追加し、ドキュメント用のルート（Scalar UI）を公開します。
• レスポンススキーマを正確に保ちます。OpenAPI はこれを基に生成されます。
• SDK を構築する場合は、ルートに完全な型を付け、例を用意してください。

認証

• JWT の署名と検証には @elysiajs/jwt を使用するか、任意の認証方式と連携します。
• 認証は、検証後にコンテキストへ user を追加するプラグインにまとめます。
• .guard({ headers: t.Object({ authorization: t.String() }) }) でルートを保護し、ハンドラーの実行前にベアラートークンを検証します。

横断的なプラグイン

• 必要に応じて @elysiajs/cors をインストールします。
• オブザーバビリティには @elysiajs/server-timing と @elysiajs/opentelemetry の使用を検討します。

スキャフォールドを生成する場合は、src/plugins/openapi.ts、src/plugins/auth.ts を生成し、src/app.ts で接続します。

デプロイ、パフォーマンス、Docker

本番環境へのデプロイ

• マルチコア向けにはクラスターモードを使用します。小さなランチャー（index.ts）でワーカーをフォークし、各ワーカーで server.ts をインポートします。
• 本番環境へのデプロイでは、Vite や esbuild などのバンドラーでビルドすることを推奨します。
• コンパイルによってトレーシング（OpenTelemetry）に支障が出る場合は、--minify を避けるか、計測対象のモジュールを --external として指定します。
• process.env.PORT（フォールバック付き）を受け付け、PaaS 向けに 0.0.0.0 にバインドします。

Docker

• ビルドステージでは、pnpm を使用する Node.js ベースイメージを使います。
• ランタイムにはdistrolessベースイメージを使用し、バイナリーをコピーして CMD ["./server"] を指定します。

デプロイ用スキャフォールド

デプロイ用のスキャフォールドを生成する場合は、次を含めます。

• src/index.ts（クラスタ―ランチャー）、src/server.ts（アプリ）、Dockerfile（マルチステージ）、およびビルドスクリプト。

テスト

単体テスト

• vitest を使用します。
• アプリをインポートし、app.handle(new Request(url, options)) を使ってステータス、本文、ヘッダーを検証します。
• サービスのテストでは、純粋関数を直接呼び出します。

含めるテスト例

• テキストを返すシンプルな GET テスト。
• body のバリデーションを行う POST（有効な場合と無効な場合の両方）。
• モックの Authorization ヘッダーを使用する認証済みルートの例。
• ルートごと、サービスごとに、小規模で焦点を絞ったテストを推奨します。

クイックユーティリティ

一般的なパターン

• アプリのコンテキスト：.state() と .decorate() を使って、バージョン情報やヘルパーなどを追加し、{ store, getDate } から読み取ります。
• シンプルなリアルタイム API には、.ws() で WebSocket エンドポイントを作成します。
• 特殊なコンテンツタイプには、.onParse() でカスタムボディーパーサーを作成します。

バリデーションチェックリスト

Elysia に関するタスクを完了する前に、次を確認します。

• 機能の構成が model.ts、service.ts、index.ts のパターンに従っている。
• すべてのハンドラーに適切なスキーマ（body/query/params/response）が定義されている。
• エラー処理に一元化された .onError() プラグインを使用している。
• OpenAPI の生成用にレスポンススキーマが定義されている。
• テストで app.handle(new Request(...)) のパターンを使用している。
• 型チェック（pnpm run typecheck）とテスト（pnpm run test）を実行している。

詳しいパターンとコード例については、references/patterns.md を参照してください。