【実務・中級編】大規模プロジェクトにおける『Type Alias』の階層化と名前空間の管理 – Hack言語コア・静的型システムとHHVMのアーキテクチャ解析バイブル

大規模Hackプロジェクトにおける『Type Alias』階層化設計：型チェッカーを味方につける極限のアーキテクチャ

コードレビューをしていて、次のようなコードに出くわしたことはないか？

<<__Strict>>
namespace App\Service;

use namespace App\Model\{User, Order};

class CheckoutService {
public function processCheckout(
User $user,
shape(‘id’ => int, ‘items’ => vec int, ‘qty’ => int, ‘price’ => float)>, ‘total’ => float) $cart,
): Awaitable bool, ‘transaction_id’ ?string, ‘error’ => ?string)> {
// … 処理が延々と続く
}
}

言語道断だ。
このようなインラインの `shape` 定義やプリミティブの野放しは、コードベースが数十万行を超えた瞬間におぞましい技術的負債へと変貌する。型チェッカー（hhvm）のCPUサイクルを無駄に消費し、何より人間の認知負荷が高すぎて誰も全体像を追えなくなる。

今回は、Hackの厳格な静的型付け（`<<__Strict>>`）とHHVMのアーキテクチャの特性を極限まで引き出し、大規模プロジェクトにおける型エイリアス（Type Alias）の階層化と名前空間管理のベストプラクティスを伝授する。

—

1. なぜ「野良shape」と「フラットな型定義」は破滅を招くのか

Hackの型チェッカーは、型定義を効率的に解決するために最適化されている。しかし、開発者が場当たり的にファイル単位で `type` や `newtype` を乱立させると、以下の問題が発生する。

1. 循環参照とオートローディングの破綻: HHVMのバイトコード生成フェーズにおいて、解決不能な型依存グラフが生まれると、型チェックのスループットが劇的に低下する。
2. 意味論の欠落（Primitive Obsession）: 単なる `int` や `string` でドメインモデルを表現すると、IDの渡し間違い（例: `UserId` を `OrderId` の引数に渡す）を型チェッカーが検知できなくなる。
3. 名前空間の汚染: グローバル、あるいは適当な名前空間にすべての型が集約され、コンフリクトと可読性の低下を招く。

これを防ぐ唯一の解が、「ドメイン駆動型エイリアス階層（Domain-Driven Type Aliasing）」である。

—

2. 型エイリアスの階層化アーキテクチャ

大規模システムでは、型エイリアスを以下の3層に厳格に分離・階層化する。

Layer 1: Primitives & Branded Types（底層・プリミティブのラップ）
生の `int` や `string` を隠蔽し、ドメイン固有の型安全性を担保する。ここでは `newtype`（不透明型）を多用する。
Layer 2: Domain Shapes & Collections（中層・構造体の合成）
レコードやエンティティを表現する `shape`。Layer 1の型を組み合わせて構築する。
Layer 3: API & Service Contracts（表層・入出力コントラクト）
コントローラーや非同期API（Async API）の境界で使用されるトランスファーオブジェクト。

—

3. 実践：プロダクションコードで見る型階層デザイン

実際に、ECシステムのチェックアウト機能を題材にしたプロダクションコードを見てみよう。モジュール境界と名前空間が美しく整理された実装だ。

Layer 1: App\Type\Primitive
プリミティブな値に型としての「意味」を与える。
newtypeを使うことで、int同士の誤った代入をコンパイル時に完全に阻止する。

/
<<__Strict>>
namespace App\Type\Primitive {

// ユーザーIDは単なるintではない。App\Type\Primitive\UserIdである。
newtype UserId = int;
newtype OrderId = int;
newtype MoneyAmount = float;
}

Layer 2: App\Type\Domain
Layer 1を組み合わせて、ビジネスドメインの構造体を定義する。

/
<<__Strict>>
namespace App\Type\Domain {

use namespace App\Type\Primitive;

type CartItem = shape(
‘item_id’ => int,
‘quantity’ => int,
‘unit_price’ => Primitive\MoneyAmount,
);

type Cart = shape(
‘user_id’ => Primitive\UserId,
‘items’ => vec,
‘total_amount’ => Primitive\MoneyAmount,
);
}

Layer 3: App\Contract\Api
外部境界（HTTPリクエストや非同期RPC）との入出力コントラクト。

/
<<__Strict>>
namespace App\Contract\Api {

use namespace App\Type\Domain;
use namespace App\Type\Primitive;

type CheckoutRequest = shape(
‘cart’ => Domain\Cart,
‘idempotency_key’ => string,
);

type CheckoutResponse = shape(
‘success’ => bool,
‘order_id’ => ?Primitive\OrderId,
‘error_message’ => ?string,
);
}

Application Service Implementation
階層化された型を用いた、堅牢かつクリーンなビジネスロジック。

/
<<__Strict>>
namespace App\Service {

use namespace App\Contract\Api;
use namespace App\Type\Domain;
use namespace App\Type\Primitive;

class CheckoutService {

非同期API連携を想定したAwaiting処理

/
public async function process(
Api\CheckoutRequest $request,
): Awaitable {
$cart = $request[‘cart’];

// 型チェッカーはここで $cart[‘user_id’] が Primitive\UserId であることを保証している
$orderId = await $this->persistOrderAsync($cart);

return shape(
‘success’ => true,
‘order_id’ => $orderId,
‘error_message’ => null,
);
}

private async function persistOrderAsync(
Domain\Cart $cart,
): Awaitable {
// DBレイヤーとの非同期I/Oシミュレーション
await \HH\Asio\usleep(10000);

// 型キャストではなく、ドメインロジックを通じた生成（ここでは簡略化のため直接返す）
return 42; // 実運用では Primitive\OrderId 型として安全に扱われる
}
}
}

—

4. なぜ `type` と `newtype` を使い分けるべきか？

Hackの型システムにおいて、ここを見誤るとアーキテクチャが崩壊する。

| 宣言 | 特徴 | 用途・適用レイヤー |
| :— | :— | :— |
| `type` (Transparent) | エイリアス元の型と完全に互換性がある。構造が透過的。 | Layer 2 (`shape` や `vec` などの構造定義) |
| `newtype` (Opaque) | 定義されたファイルの外側からは「別個の型」として扱われる。 | Layer 1 (プリミティブのラップ。強固な型安全性の担保) |

特に `newtype` を用いることで、「単なる数値の渡し間違いによるバグ」を宇宙から根絶できる。 `UserId` を要求されている場所に、誤って `OrderId` や生のカレントIDを渡すと、型チェッカーが即座にレッドフラグを立てる。これがHackの厳格モード（Strict Mode）の真骨頂だ。

—

5. HHVMアーキテクチャの観点：パフォーマンスとオートローディングの極意

「型を細かく分割すると、オートローディングやHHVMのバイトコードキャッシュ（RepoAuthoritativeモード）に悪影響があるのではないか？」

鋭いエンジニアならそう懸念するだろう。答えは「否、むしろ逆である」。

1. 型エイリアスはランタイムコストゼロ: Hackの型エイリアス（`type` および `newtype`）は、コンパイル時（hh_serverの静的解析時）にのみ評価される。HHVMがJITコンパイルし、マシン語を生成する際には、すべてのエイリアスは実体（原初のエディット型、あるいはプリミティブ）に完全にインライン展開・置換される。つまり、実行時オーバーヘッドは一切ない。
2. 依存関係の明確化によるインクリメンタルコンパイルの高速化: 名前空間ごとに型ファイルを綺麗に分離しておくと、`hh_server` のインクリメンタルチェックが正確に働く。変更された差分ファイルがどのモジュールに影響するかを型チェッカーが瞬時に把握するため、開発中のフィードバックループが極限まで高速化される。

—

テクニカルリードからの総括

大規模開発における最大の敵は複雑性であり、その複雑性の大部分は「曖昧なデータ構造」から生まれる。

「とりあえず `shape` で受け取る」「とりあえず `int` で持たせる」という惰性を断ち切れ。今回解説した型エイリアスの階層化と `newtype` によるプリミティブのラップを導入すれば、あなたの書くコードは圧倒的に堅牢になり、型チェッカーは最強の相棒へと昇華する。

コードレビューでこの設計思想が見られないコードが来たら、迷わずこう言えばいい。
「おい、型エイリアスが泣いているぞ」と。