変更要約: 初版
3.4再利用とフレームワーク
ライブラリ/コンポーネント/フレームワークの呼び出し関係の違い（自コードが相手を呼ぶ vs 相手が自コードを呼ぶ制御の反転（IoC））、そしてREST API設計の原則（リソース指向・ステートレス・HTTPメソッドの意味論）とバージョニング戦略を、既存資産の再利用方式をどう選び、外部公開APIの互換性をどう維持するかという判断とともに学びます。
再利用可能な資産を導入する判断は「便利そうだから使う」ではなく、その資産が自コードとどちらの方向で制御を握るかを見極めることが本質です。システムアーキテクトにとって重要なのは、ライブラリ導入とフレームワーク導入の違いを見誤らないこと、そして外部公開するAPIを将来の変更に耐える形で設計・バージョニングできることです。
3.4.1ライブラリ・コンポーネント・フレームワークとIoC
- ライブラリ＝特定の機能（文字列処理・数値計算等）を提供する部品で、自コードが必要なタイミングでライブラリの関数を呼び出す。制御の主導権は常に自コード側にある。
- コンポーネント＝独立してデプロイ・交換可能な単位で、明確なインタフェースを介して他のコンポーネントと連携する再利用単位。ライブラリより粒度が大きく、単体で意味のある機能を完結させることが多い。
- フレームワーク＝アプリケーション全体の制御の流れ（骨格）をフレームワーク側が握り、開発者が書いたコード（フック/コールバック）をフレームワークが適切なタイミングで呼び出す。この「呼ばれる側が自コード」という主導権の逆転を制御の反転（Inversion of Control, IoC）と呼ぶ。
- 見分け方の実務的な問い：「誰がmain（起動と全体の流れの制御）を握っているか」。自コードが起動しライブラリを呼ぶならライブラリ、フレームワークが起動し自コードをフックとして呼ぶならフレームワーク（IoC）。この判断を誤ると、フレームワークの制御フローを無視した設計をしてしまい、フレームワークの恩恵（横断的関心事の一元管理等）を活かせない。
3.4.2API設計（REST）とバージョニング
- REST（Representational State Transfer）＝URIで資源（リソース）を表現し、その資源への操作をHTTPメソッドの意味論（
GET＝取得・副作用なし、POST＝新規作成、PUT＝全体更新（冪等）、DELETE＝削除）に沿って表現する設計原則。動詞をURIに含めない（/getUserではなくGET /users/{id}）ことが原則。 - ステートレス＝各リクエストはサーバ側にセッション状態を持たせず、リクエスト自体に処理に必要な情報を全て含める原則。サーバ側の水平スケールアウトを容易にする。
- バージョニング＝公開APIの破壊的変更（レスポンス形式の変更等）を既存クライアントに影響させずに導入する戦略。URIパス（
/v1/,/v2/）やHTTPヘッダでのバージョン指定が代表例。既存クライアントが使う旧バージョンのエンドポイントは、移行期間を設けて維持しながら新バージョンを並行提供するのが実務上の基本方針。
「フレームワークは制御の反転（IoC）＝フレームワークが自コードを呼ぶ、ライブラリは自コードがライブラリを呼ぶ」「RESTはURIでリソースを表現しHTTPメソッドの意味論に従う」「PUTは冪等な全体更新」「破壊的変更は旧バージョンを維持しつつ新バージョンを並行提供する」が最頻出です。ライブラリとフレームワークの主導権の向きを取り違えないことが急所です。
あるシステムアーキテクトが、社内向けに公開している注文管理APIを外部パートナー企業にも公開することになったとします。現行のAPIはPOST /processOrderという単一エンドポイントに注文処理の全ロジック（作成・更新・キャンセルを1つの巨大なリクエストボディで判別）が集約されており、動詞がURIに含まれ、操作の種類はリクエストボディ内のフラグで判別する設計でした。これはRESTの原則から外れています——リソース（注文）をURIで表現し、操作の種類はHTTPメソッドの意味論に委ねるべきです。改善策として、POST /orders（新規作成）・PUT /orders/{id}（全体更新・冪等）・DELETE /orders/{id}（キャンセル/削除）・GET /orders/{id}（参照・副作用なし）というリソース指向でHTTPメソッドの意味論に沿ったエンドポイントに再設計します。次に、パートナー企業に外部公開する以上、将来レスポンス形式を変更したくなったとき、既存パートナーの実装を壊さずに移行できるかという懸念が生じます。ここで無計画にレスポンス形式を直接書き換えると、既存パートナーの連携が即座に壊れます。適切な対応は、URIパスに/v1/ordersのようにバージョンを明示し、将来/v2/ordersで新形式を提供する際も、移行期間中は/v1/ordersを維持し並行稼働させるというバージョニング戦略を最初から組み込むことです。さらに、この注文管理システムの内部実装では、注文確定時のバリデーションロジックを外部のフレームワーク（Webアプリケーションフレームワーク）に委ねているとします。このフレームワークは「リクエスト受信→ルーティング→バリデーション→自コードのハンドラ呼び出し→レスポンス生成」という制御の流れそのものをフレームワーク側が握り、開発者が書いたハンドラ関数を適切なタイミングで呼び出す構造（制御の反転（IoC））になっています。これは「自コードがライブラリの関数を呼ぶ」ライブラリ利用とは主導権の向きが逆であり、フレームワークが提供する横断的関心事（認証・ロギング・エラーハンドリングの一元管化）を活かすにはフレームワークの制御フローに従ったハンドラ設計が必要になります。「誰が資源を表現し誰が操作の意味を決めるか（REST）」「既存クライアントを壊さず変更を導入できるか（バージョニング）」「制御の主導権がどちらにあるか（IoC）」の3点を状況ごとに判断するのがシステムアーキテクトの役割です。
| 種別 | 制御の主導権 | 例 |
|---|---|---|
| ライブラリ | 自コードがライブラリを呼ぶ | 文字列処理・数値計算関数群 |
| コンポーネント | 明確なインタフェースを介し対等に連携 | 独立デプロイ可能な業務機能単位 |
| フレームワーク | フレームワークが自コード（ハンドラ）を呼ぶ（IoC） | Webアプリケーションフレームワーク |
ひっかけ： 「フレームワークもライブラリも、自コードが相手を呼び出す点で本質的に同じである」は誤りです——フレームワークは制御の流れそのものを握り自コードを呼び出す（制御の反転）点がライブラリと根本的に異なります。また「外部公開APIのレスポンス形式は、必要になったタイミングで既存エンドポイントを直接書き換えればよい」も誤り＝既存クライアントを壊さないため、旧バージョンを維持しつつ新バージョンを並行提供するバージョニング戦略が必要です。
3.4.3この節のまとめ
- ライブラリは自コードが呼ぶ側、フレームワークはフレームワークが自コードを呼ぶ側（制御の反転(IoC)）で主導権の向きが逆
- RESTはリソースをURIで表現し操作の意味をHTTPメソッド（
GET/POST/PUTは冪等/DELETE）に委ねる - 公開APIの破壊的変更は、旧バージョンを移行期間維持しつつ新バージョンを並行提供するバージョニング戦略で既存クライアントを守る
進捗の記録にはログインが必要です。
理解度チェック
（軽い確認用）Q1. ある開発チームが導入を検討している外部ソフトウェアは、リクエスト受信からルーティング・バリデーション・自チームが書いたハンドラ呼び出し・レスポンス生成までの制御の流れ全体を外部ソフトウェア側が握り、適切なタイミングで自チームのコードを呼び出す構造になっている。この関係を最も適切に表すものはどれか。
Q2. 注文管理APIがPOST /processOrderという単一エンドポイントに作成・更新・キャンセルの全ロジックを集約し、操作の種類をリクエストボディ内のフラグで判別している。RESTの原則に沿った改善として最も適切なものはどれか。
Q3. 社内APIを外部パートナーに公開した後、将来レスポンス形式を変更したくなった場合、既存パートナーの実装を壊さずに移行するための最も適切な戦略はどれか。