Hackの『Shape』型を用いたAPIレスポンスの型安全なマッピング戦略
HHVM（HipHop Virtual Machine）のアーキテクチャ、そしてHack言語の静的型システムを極限まで追求する者にとって、外部境界からのデータ流入は常に最大のセキュリティ・アタックサーフェスであり、同時に最適化のボトルネックである。
動的言語の亡霊であるPHPの泥臭い配列（`array`）操作から脱却し、コンパイル時型安全性（Compile-time Type Safety）を担保するために、Hackには `shape` 型が存在する。だが、多くのエンジニアはこれを単なる「キー名が固定された連想配列のエイリアス」程度にしか捉えていない。
本稿では、HHVMの型チェッカー（hh_client）の挙動、バイトコード生成、そしてメモリ効率を最大化しながら外部APIレスポンスをドメインモデルへ安全にマッピングする、極限のアーキテクチャ戦略を解説する。
—
1. なぜ「動的JSONパース」は悪なのか：HHVMランタイムの視点
外部APIから取得したJSONを `json_decode($json, true)` でデコードした瞬間、HHVMの内部では何が起きているか。
それは、型情報が完全に剥ぎ取られた `Map
HHVMのJITコンパイラ（Region JIT）は、変数の型が静的に確定している場合に最も効率的なネイティブコード（x86-64アセンブリ）を生成する。しかし、`mixed` や動的な配列アクセスが混入した途端、型ガード（Type Guard）の失敗、ボックス化（Boxing）された値のアンボックス化のオーバーヘッド、さらにはRuntime Type Information (RTTI) のチェックによる深刻なCPUサイクルの浪費が発生する。
Strictモード（`<<__Strict>>`）下において、`shape` は単なる開発時の気休めではない。これはコンパイラに対する強烈な最適化ヒントであり、メモリレイアウトの固定化を促す契約である。
—
2. Shape型による境界防御の設計
APIレスポンスをマッピングする際、我々は2つの課題に直面する。
1. 構造の保証: 外部から来るJSONが期待通りのスキーマを持っているか。
2. 型の伝播: 取得したデータが、コードベース全体で厳格に型安全に扱われているか。
以下のコードは、単にshapeを定義するだけでなく、ランタイムの境界チェック（Boundary Validation）とコンパイル時の型安全性を両立させる実戦的なアーキテクチャパターンである。
<<__Strict>>
namespace Enterprise\API;
use type HH\Lib\{C, Dict, Str, Vec};
/
- 外部APIレスポンスの物理構造を定義するShape。
- 必須フィールドのみならず、オプショナルフィールド（?）の境界も明確化する。
/
type RawUserShape = shape(
‘id’ => int,
‘username’ => string,
‘email’ => ?string,
‘metadata’ => shape(
‘login_count’ => int,
‘last_active_at’ => string,
),
);
/
- ドメイン層で利用するイミュータブルなreadonlyクラス。
- Shapeから安全にトランスレートされる。
/
<<__Rx, __NoDynamicProperties>>
final class UserDomainModel {
public function __construct(
public int $id,
public string $username,
public string $email,
public int $loginCount,
public \DateTimeImmutable $lastActiveAt,
) {}
}
final class UserApiResponseMapper {
/
- 外部の不確実な入力を受け取り、StrictなShapeへ安全に昇格させる。
- ここでランタイムの型アサーションと構造検証を行う。
/
public static function mapFromJson(string $jsonString): UserDomainModel {
$decoded = \json_decode($jsonString, true);
if (!\is_array($decoded)) {
throw new \InvalidArgumentException(“Invalid JSON payload: root must be an object.”);
}
// HHVMのTypehintと連携するための境界バリデーション
// ※ 本番環境では Shape::class やカスタムガード関数を使用
$validatedShape = self::validateAndCast($decoded);
return self::toDomain($validatedShape);
}
private static untaint-ish function validateAndCast(array
// 厳密なキー存在確認と型チェック
// Hackの型チェッカーはここからの戻り値を RawUserShape として完全に追跡する
invariant(
\array_key_exists(‘id’, $data) && \is_int($data[‘id’]),
‘Missing or invalid type for “id”‘
);
invariant(
\array_key_exists(‘username’, $data) && \is_string($data[‘username’]),
‘Missing or invalid type for “username”‘
);
invariant(
\array_key_exists(‘email’, $data) && (\is_string($data[‘email’]) || $data[‘email’] === null),
‘Missing or invalid type for “email”‘
);
// ネストされたshapeの検証
$meta =Shapes::idx($data, ‘metadata’);
invariant(\is_array($meta), ‘Missing metadata shape’);
invariant(
\array_key_exists(‘login_count’, $meta) && \is_int($meta[‘login_count’]),
‘Missing or invalid type for “login_count”‘
);
invariant(
\array_key_exists(‘last_active_at’, $meta) && \is_string($meta[‘last_active_at’]),
‘Missing or invalid type for “last_active_at”‘
);
// すべてのチェックを通過した安全なデータをShapeとしてキャスト返却
return shape(
‘id’ => (int)$data[‘id’],
‘username’ => (string)$data[‘username’],
‘email’ => $data[‘email’] !== null ? (string)$data[‘email’] : null,
‘metadata’ => shape(
‘login_count’ => (int)$meta[‘login_count’],
‘last_active_at’ => (string)$meta[‘last_active_at’],
),
);
}
private static function toDomain(RawUserShape $shape): UserDomainModel {
return new UserDomainModel(
$shape[‘id’],
$shape[‘username’],
$shape[‘email’] ?? ‘no-email@enterprise.local’,
$shape[‘metadata’][‘login_count’],
new \DateTimeImmutable($shape[‘metadata’][‘last_active_at’]),
);
}
}
—
3. HHVMアーキテクチャにおけるShapeのメモリ表現と最適化
なぜ上記のコードが高速に動作するのか。HHVMの内部構造（HNIとバイナリ表現）の観点から説明する。
配列 vs Shape のメモリフットプリント
PHP/Hackの通常の配列は、ハッシュテーブル（MixedArray / Dict）として実装されており、キーのハッシュ計算や動的なメモリ再割り当てのコストが常につきまとう。
しかし、Shapeはコンパイル時にキーが完全に確定しているため、HHVMのランタイムはこれを内部的に「構造体（Struct）」に近いオフセットアクセスとして最適化することが可能になる。
1. キーの文字列比較の排除: JITコンパイルされたコードにおいて、Shapeのキーアクセスはハッシュルックアップではなく、指定されたインデックス（オフセット）へのダイレクトメモリアクセスに還元されるケースがある。
2. GC（ガベージコレクション）の負荷軽減: ライフサイクルが明確な一時的Shapeは、スワップ領域やアリーナアロケータ上で効率よく処理され、不要なヒープ割り当てを抑制する。
Type Aliasとしての利点
`type RawUserShape = shape(…)` は、新しいランタイムクラスを生成しない（Zero-cost abstraction）。クラスインスタンスを生成する前の「パース直後の安全なデータコンテナ」としてShapeを使用することは、メモリ効率と型安全性のバランスにおいて最適解である。
—
4. シニアエンジニアが押さえるべき実践的プラクティス
1. `<<__NoDynamicProperties>>` との組み合わせ:
ドメインモデルやマッパー周辺のクラスには必ずこの属性を付与し、予期せぬプロパティの動的追加によるハッシュテーブル化を防ぐこと。オブジェクトのメモリレイアウトをC言語の `struct` のように予測可能にする。
2. 境界での型アサーションの集約:
APIレスポンスのパーサーはシステムのエッジ（境界）にのみ配置する。ビジネスロジック層（Core Domain）へ一歩足を踏み入れた瞬間から、すべてのデータは検証済み（`RawUserShape` やドメインモデル）であり、コードベース内で `is_array` などの冗長なガードを書く必要性を完全に排除する。
3. Rx（Reactive Extensions）との親和性:
データフローがイミュータブルなShapeによって担保されているため、HHVMの `<<__Rx>>`（Reactive Code）制約を容易にクリアでき、並行処理や非同期IO処理（Async Functions）において競合のない安全なデータ伝搬を実現できる。
—
結論
Hackの `shape` 型は、単なるコード補完のためのツールではない。それは「動的な外部世界」と「静的な内部世界」を隔てる強靭な防壁であり、HHVMのJITコンパイラから最大のパフォーマンスを引き出すためのコンパイラへの指令書である。
型チェッカーを欺く妥協を排除し、すべての境界をShapeで武装せよ。そこに妥協のない高スループットと堅牢性が宿る。