フロントエンドAPIクライアント(JWTスキル)
このスキルを使用するタイミング
この概念スキルは、Next.jsでJWTトークンを適切に処理する堅牢なAPIクライアントを実装する必要がある場合に使用します。このスキルは以下の場面に適しています:
- Next.jsアプリケーションでの集中型API通信レイヤーの作成
- 複数のAPIエンドポイントにわたるJWTベース認証の管理
- トークンの有効期限切れとリフレッシュシナリオの処理
- エラーレスポンス解析と処理の標準化
- セキュアなAPI通信パターンの実装
このスキルは以下の場面では使用しないでください:
- JWTベース認証を使用しないアプリケーション
- API通信が必要ない静的サイト
- 代替認証方式(APIキー、OAuth 2.0クライアントクレデンシャルなど)を使用するアプリケーション
- シンプルなAPIインタラクションしかないアプリケーション
前提条件
- Next.jsアプリケーション(App RouterまたはPages Router)
- JWT(JSON Web Token)の概念の理解
- HTTPヘッダーと認証メカニズムの知識
- 非同期JavaScript処理の基本的な理解
- クライアントサイドとサーバーサイドの実行コンテキストの認識
概念実装フレームワーク
Authorizationヘッダー添付機能
- APIリクエストへのJWTトークンの自動Authorizationヘッダーとしての添付
- リクエストタイプとエンドポイントに基づくトークン添付の判断
- クライアントサイドとサーバーサイド両方のリクエストでのトークン添付処理
- クロスオリジンリクエストにおけるトークン添付の適切な管理
- 正しいヘッダー形式("Bearer ")の保証
トークン有効期限処理機能
- APIリクエストを行う前のJWTトークン有効期限の検出
- 自動トークンリフレッシュメカニズムの実装
- トークンリフレッシュ失敗のグレースフルな処理
- トークンリフレッシュ中のセッション維持
- 複数の同時リクエストにわたるトークンリフレッシュの調整
- リフレッシュ後の更新トークンの安全な保存
エラーレスポンス解析機能
- APIエンドポイントからの構造化エラーレスポンスの解析
- 特別処理のための認証関連エラー(401, 403)の特定
- ユーザーフィードバックのための意味のあるエラーメッセージの抽出
- 異なるエラーレスポンス形式の一貫した処理
- クライアントエラー、サーバーエラー、ネットワーク問題の区別
- エラータイプに基づく適切なユーザーフィードバックの提供
API呼び出し一元化機能
- すべてのAPI通信用の統一インターフェースの作成
- アプリケーション全体でのリクエスト/レスポンス処理の標準化
- 一貫したエラーハンドリングとログ記録の実装
- 横断的関心事へのリクエスト/レスポンスインターセプターの管理
- タイプセーフなAPI呼び出しパターンの提供(TypeScript使用時)
- 該当する場合のリクエストキャッシュと重複排除の有効化
期待される入出力
入力要件:
-
JWTトークン管理:
- 認証用の有効なJWTトークン
- トークンリフレッシュエンドポイントの設定
- トークン保存メカニズム(localStorage、cookiesなど)
- トークンの有効期限とリフレッシュタイミング
-
API設定:
- リクエスト用のベースAPI URL
- リクエストタイムアウト設定
- カスタムヘッダーとリクエストオプション
- エンドポイント固有の設定
-
リクエストパラメータ:
- HTTPメソッド(GET、POST、PUT、DELETEなど)
- リクエストURLまたはエンドポイント識別子
- POST/PUT操作用のリクエストボディ
- クエリパラメータとパス変数
出力形式:
-
成功時のAPIレスポンス:
- HTTP 200-299ステータスコード
- 期待される形式の解析済みレスポンスデータ
- 該当する場合の更新されたトークン情報
- 全エンドポイントで一貫したレスポンス構造
-
認証エラーレスポンス:
- 期限切れ/無効なトークンの場合はHTTP 401 Unauthorized
- 自動トークンリフレッシュ試行
- リフレッシュ失敗後のログインページへのリダイレクト
- 認証問題に対する明確なエラーメッセージ
-
認可エラーレスポンス:
- 権限不足の場合はHTTP 403 Forbidden
- 権限レベルに基づく適切なエラーハンドリング
- アクセス制限に対するユーザーフィードバック
-
一般的なエラーレスポンス:
- メッセージとコードを含む構造化エラーオブジェクト
- 適切なHTTPステータスコード
- デバッグ用の詳細エラー情報
- UI表示用のユーザーフレンドリーなエラーメッセージ
統合パターン
クライアントサイド統合
- クライアントコンポーネントとクライアントサイドレンダリングからのAPI呼び出し処理
- ブラウザコンテキストでのトークン保存と取得の管理
- ヘッダー添付用のリクエストインターセプターの実装
- 認証状態管理との調整
サーバーサイド統合(該当する場合)
- サーバーコンポーネントからのAPI呼び出し処理
- サーバーとクライアント間での安全なトークン送信管理
- サーバーサイドでのトークン検証の実装
- サーバーサイドエラーレスポンスの適切な処理
Reactコンポーネント統合
- 関数コンポーネントでのAPI通信用フックの提供
- コンテキストベースのAPIクライアントアクセスの有効化
- 関数コンポーネントとクラスコンポーネント両方のパターンサポート
- 適切なクリーンアップとキャンセルメカニズムの実装
セキュリティ考慮事項
- トークン保存: XSS攻撃を防ぐための安全なJWTトークン保存
- ヘッダー送信: すべてのAPI通信にHTTPSを使用
- トークンリフレッシュ: 安全なトークンリフレッシュメカニズムの実装
- エラー情報: エラーメッセージに機密情報を公開しない
- リクエスト検証: 送信前のリクエストパラメータの検証
- レスポンス検証: レスポンスの整合性と形式の検証
- クロスサイトリクエスト: 適切なCORS処理の実装
パフォーマンスへの影響
- 最小オーバーヘッドのためのトークン取得と添付の最適化
- リクエストをブロックしないための効率的なトークンリフレッシュの実装
- パフォーマンス向上のためのリクエストキャッシュ戦略の検討
- 適切な状態管理による冗長なAPI呼び出しの最小化
- 該当する場合のリクエストバッチ処理の実装
- ネットワークリクエストタイミングの監視と最適化
エラーハンドリングと検証
- リクエスト前のJWTトークンの形式と有効期限の検証
- ネットワーク接続問題のグレースフルな処理
- 一時的な障害に対するリトライメカニズムの実装
- 重要なAPI障害に対するフォールバック動作の提供
- 機密情報を露出せずに適切なデバッグ用エラーログ記録
- サービス回復力のためのサーキットブレーカーパターンの実装
テストの考慮事項
- 有効/無効なトークンを使用したトークン添付機能のテスト
- トークンリフレッシュメカニズムの正しい動作の検証
- さまざまなエラータイプにわたるエラーレスポンス解析の検証
- クライアントとサーバー両方のコンテキストでのAPIクライアント動作のテスト
- 適切なクリーンアップとリクエストキャンセルの検証
- 同時リクエスト処理とトークンリフレッシュ調整のテスト