HTTPクライアント

createHttpClient<Paths>() に注入する Paths がリクエスト契約です。url と method は Paths のキーから、queryString と pathVariable は parameters から、body は requestBody でタイプが決まります。

応答タイプは callApi<R>() の R を呼び出し元が指定します。Core は OpenAPI responses から応答タイプを自動推論しません。

typed-rx-http は ResponseWrapper を強制しません。サーバー応答がラッパーであればラッパータイプを R に指定し、そうでなければ実際の応答タイプをそのまま指定します。

commonServiceは@byeolnaerim/typed-rx-httpが提供する特別なクラス名ではなく、プロジェクトで共通HTTPポリシーを一箇所に集めるために使用するユーザー所有ファイルを指します。ファイル名は自由で、以下の例では実際のプロジェクト名であるrxjsHttpService.tsを使用します。

画面と自動生成サービスごとにcreateHttpClientを繰り返さず、このファイルが生成したcallApiとcallApiStreamを共通エントリーポイントとして使用します。したがって、認証更新、SSR headerの伝達、キャッシュとエラー処理のルールを一度修正すれば、すべての生成サービスに同様に適用されます。

1. 最小完成形

commonServiceの本質は以下のコードです。headerStoreとtyped HTTP clientを一度作成し、generated serviceが共通で使用するcallApi/callApiStreamをexportします。uploadFileとcreateSSEObservableも同じclientでそのまま公開できます。

2. Next.js + セッション認証 + CSR/SSRキャッシュを含む拡張型

以下は同じ共用アダプタにセッション認証、SSRヘッダー、CSR/SSRキャッシュを追加した全体プロジェクトの例です。generated serviceがキャッシュラッパーまでimportするプロジェクトであれば、この形が基準となります。そのままコピーした後、setLogin import、ApiTypesとCacheNamesの位置、認証APIパス、環境変数とunauthorizedパスを自分のプロジェクトに合わせて調整すればよいです。

ジェネレーターはcommonServiceFileの相対パスを計算し、各サービスにインポートを追加します。画面は共通ファイルを直接呼び出さず、生成された関数をインポートし、生成関数がパス、パラメータ、ボディをServiceArgumentsのpathVariable、queryString、bodyに変換してcallApiに渡します。

検索、保存、削除のように一度応答して終わるREST APIは生成されたObservableをfirstValueFromで受け取ると既存のasync関数内でも自然に使用できます。

画面では paramsのみ表示されますが、生成されたサービス内にはURL、HTTPメソッドと応答タイプが含まれています。クエリパラメータは常に{ params: { ... } }で渡します。

作業進捗やRSocketストリームのように複数の値が到着するリクエストはsubscribeで受け取り、コンポーネントが消えるときに購読を解除します。

サービスジェネレーターを使用しないプロジェクトや生成前に一時エンドポイントを確認する場合は、共通サービスのcallApiを直接呼び出すことができます。リクエストタイプはpathsで検査し、レスポンスタイプは呼び出し元がジェネリックで指定します。