【ITニュース解説】Managing HTTP Requests as Type-Safe TypeScript Classes

システムエンジニアを目指す上で、Webアプリケーション開発は避けて通れない道だ。Webアプリケーションは、クライアント（Webブラウザやモバイルアプリなど）とサーバーが情報をやり取りすることで成り立っており、この情報のやり取りにはHTTPリクエストが使われる。TypeScriptを使ってこれらのHTTPリクエストを記述する際、多くの開発者が共通の課題に直面することがある。

まず、「コードの散在」という問題がある。Web APIへのリクエストには、アクセス先のURL、認証情報やデータ形式を指定するヘッダー、検索条件などを渡すクエリ文字列といった情報が必要だ。これらがプロジェクトの様々な場所にバラバラに記述されていると、必要な情報を見つけるのが難しくなり、全体像を把握しにくくなる。次に、「スタイルの不統一」も大きな課題だ。開発者ごとにHTTPリクエストを記述する方法が異なると、ある人は関数内で直接値を操作し、別の人は外部のユーティリティ関数を使う、といった状況が生まれる。これにより、コードの再利用が難しくなり、後から別の開発者がコードを修正しようとした際に理解に時間がかかり、メンテナンスの負担が増大する。

さらに、様々な外部サービスや自社APIと連携する場合、「運用ポリシーの違い」が問題になることもある。APIによっては、リクエストの応答を待つ時間（タイムアウト）や、エラーが発生した場合に何回か再試行する（リトライ）といったルールが定められている。これらのポリシーを個々のリクエスト関数に直接書き込んでしまうと、ポリシーに変更があった場合に多くの箇所を修正しなければならず、管理が複雑化し、ミスも発生しやすくなる。また、「可読性の問題」も重要だ。HTTPリクエストでサーバーに送るデータは、URLの一部として渡すパスパラメータ、URLの末尾に付加するクエリ文字列、リクエストのヘッダー、リクエストの本体（ボディ）など、様々な種類がある。これらがコード上で明確に区別されていないと、ある値がどの部分に渡されるデータなのかがすぐに判別できず、コードを読んだり修正したりする際の混乱を招き、長期的なプロジェクトのメンテナンスを困難にする。

これらの課題を解決し、より効率的な開発を実現するためには、「一貫性」と「宣言的な定義」が必要になる。具体的には、チーム全体でHTTPリクエストの構造を定義する共通のパターンを確立すること。また、タイムアウトやリトライといった運用ポリシーを、リクエストごとに明確かつ簡潔に指定できるようにすること。そして、リクエストを構成する各値が、パス、クエリ、ヘッダー、ボディのどれに属するのかを一目でわかるようにすることだ。

このような目標を達成するために有効なアプローチとして提案されているのが、「HTTPリクエストをTypeScriptのクラスとして定義し、デコレーターという特殊な機能を使ってその構造やポリシーを明確に記述する」という方法だ。デコレーターは、クラスやそのメンバー（プロパティやメソッド）に対して追加のメタデータを付与したり、その動作を変更したりするために使われる機能だ。この方法では、@Getや@Postといったデコレーターを使って、そのクラスがGETリクエストなのかPOSTリクエストなのかを宣言し、アクセス先のホスト名やパスも指定する。さらに、@Param、@Query、@Header、@Bodyといったデコレーターをクラスのプロパティに適用することで、そのプロパティの値がそれぞれパスパラメータ、クエリ文字列、ヘッダー、リクエストボディのどの部分にマッピングされるのかを明示的に示す。

例えば、@Param()デコレーターが付いたプロパティはURLのパスの一部として扱われ、:nameのようなプレースホルダーにその値が埋め込まれる。@Query()デコレーターが付いたプロパティは、URLの末尾に?key=valueの形式で追加される。このように定義することで、クラスのコードを読んだだけで、そのHTTPリクエストがどのような形式で、どのようなデータを含んでいるのかが、誰にでも直感的に理解できるようになる。また、タイムアウトやリトライといった運用ポリシーも、それぞれのHTTPリクエストクラスに直接記述できるようになるため、一元的に管理でき、変更も容易になる。

このアプローチを具体的に実現するライブラリが「jin-frame」だ。jin-frameは、データベースのテーブルやレコードをTypeScriptのクラスとして扱うORM（Object-Relational Mapping）ライブラリ（TypeORMやMikroORMなど）と似た考え方に基づいている。ORMがデータベースの「エンティティ」をクラスとして設計するのと同じように、jin-frameはHTTPリクエストをTypeScriptの「フレーム」（Frame）というクラスとして設計できる。

具体的な使用例を見てみよう。PokemonFrameというクラスが定義されている。このクラスはJinFrameを継承しており、@Getデコレーターを使って、https://pokeapi.co/api/v2/pokemon/:nameというURLへのGETリクエストを表現している。クラス内には@Param()デコレーターが付いたnameプロパティと、@Query()デコレーターが付いたtidプロパティがある。これは、nameの値がURLの:nameの部分に、tidの値がクエリ文字列として埋め込まれることを意味する。

実際にこのリクエストを実行するには、PokemonFrame.of({ name: 'pikachu', tid: randomUUID(), })のようにしてクラスのインスタンスを作成し、必要な値を設定する。そして、そのインスタンスに対してexecute()メソッドを呼び出すだけで、定義されたHTTPリクエストが実行され、JSON形式のレスポンスが返される。この一連の流れは非常に簡潔で、必要な情報がすべてクラス定義の中に集約されているため、コードの可読性とメンテナンス性が飛躍的に向上する。

この手法を用いることで、HTTPリクエストに関するコードが整理され、プロジェクト全体で一貫した開発スタイルを維持できる。新しい開発者がプロジェクトに参加した際も、既存のクラス定義を見れば、どのようにリクエストを構成し、実行すれば良いかがすぐに理解できるため、学習コストを低減できる。また、リクエストの定義が明確になることで、誤ったパラメータの渡し方やポリシーの適用ミスを防ぎやすくなる。このようなメリットから、jin-frameのようなライブラリやその思想は、大規模なTypeScriptプロジェクトにおいて、HTTPリクエストの管理をより効率的かつ堅牢にするための強力なツールとなり得る。このライブラリは開発者の個人的なプロジェクトで効果が実証されており、今後もフィードバックを受けながら改善されていくことが期待されている。