【Hackを掌握する極限の知見】Shape型でJSONレスポンスを征服する：動的データ構造の静的要塞化
コードレビューをしていて、未だに外部APIからのレスポンスをただの `array
「このキー名は本当に存在するか？」「値の型は文字列か、それともnullを許容するのか？」――そんな不毛な不安を抱えながら、コードのあちこちに `idx()` や三項演算子をばら撒くのは、厳格な静吸引力を持つHack言語の恩恵を自らドブに捨てる行為に他ならない。
今回は、動的なJSONレスポンスをShape型（`shape`）によって完全に手なずけ、HHVMの型チェッカーを限界まで働かせるための実践的アプローチを伝授する。
—
1. なぜ `array` や `dict` では不十分なのか？
PHPの系譜を引き継ぐ開発者は、連想配列（Map）を見ると反射的に `array` や `dict` を使いたがる。しかし、考えてみてほしい。
// 悪夢の動的配列アプローチ
function process_user(dict
// キーのタイポ（例: ‘usename’）に気づくのは本番環境のSentryアラートが鳴った瞬間
$name = idx($response, ‘username’, ‘Anonymous’);
// 型が保証されていないため、意図せずintが飛んできて下流で致命傷になる
$age = $response[‘age’];
}
このコードの何がクソなのか？
1. IDEが補完してくれない：開発者はAPIドキュメントと睨めっこしながらキーを手打ちする羽目になる。
2. リファクタリング耐性がゼロ：API側で `username` が `user_name` に変わった時、コードベース全体のgrep地獄が始まる。
3. 型チェッカーが無力：`mixed` の海では、HHVMの強力な静的解析エンジンもただの飾りだ。
これを解決するのが、Hackの Shape型 である。
—
2. Shape型とは何か？（構造的タイピングの極み）
Shape型は、固定されたキーと、それぞれのキーに対する厳格な型を持つ「名前のない構造体」だ。
HHVMの内部において、Shapeは最適化された配列として表現され、追加の実行時オーバーヘッドを最小限に抑えつつ、完全にコンパイル時の静的型安全性を保証する。
まずは、プロダクションコードでそのまま使える、堅牢なAPIレスポンス・マッピングの模範解答を見てほしい。
プロダクションコード例：User APIレスポンスの要塞化
namespace Hack\BestPractices;
<<__Newable>>
class UserApiResponseMapper {
// 1. Shape型の定義（型エイリアスとして宣言し、ドメイン全体で共有する）
public type TUserShape = shape(
‘id’ => int,
‘username’ => string,
‘email’ => ?string, // nullを許容する場合は ? をつける
‘is_active’ => bool,
‘metadata’ => shape(
‘login_count’ => int,
‘last_login_at’ => ?string,
),
);
/
- 外部APIからの生のJSON文字列を、厳格なShape型へマッピングする
- @param string $jsonResponse 外部APIからの生レスポンス
- @return this::TUserShape 型安全に保証されたShapeデータ
/
public static function deserialize(string $jsonResponse): this::TUserShape {
// json_decodeの第2引数でtrueを指定し、dictとしてデコードする
// Hackでは json_decode は通常 dict/vec を返すように設計されている
$data = json_decode($jsonResponse, true);
if (!is_dict($data)) {
throw new \InvalidArgumentException(“Invalid JSON payload: expected root object.”);
}
// 2. 境界値検証（Runtime Boundary Validation）
// 静的型システムはコンパイル時を守るが、外部からのI/Oは実行時検証が必須
self::validateShapeStructure($data);
// 型チェッカーに対し、ここを通ったデータは TUserShape であると確約する
// 実際にはHHVMの型チェッカーが構造の整合性を追跡する
return/ UNSAFE_EXPR / $data;
}
/
- 最小限の実行時バリデーション
- （厳密には外部ライブラリや専用の型ガードを使用するが、ここでは概念を示す）
/
private static function validateShapestructure(dict
// 必須キーの存在チェックと型の簡易アサーション
if (!\array_key_exists(‘id’, $data) || !\is_int($data[‘id’])) {
throw new \InvalidArgumentException(“Field ‘id’ is missing or invalid.”);
}
if (!\array_key_exists(‘username’, $data) || !\is_string($data[‘username’])) {
throw new \InvalidArgumentException(“Field ‘username’ is missing or invalid.”);
}
// … 他のフィールドの検証が続く
}
}
—
3. テクニカルリードからの視点：なぜこの設計が美しいのか？
上記のコードには、大規模開発を生き抜くための知見が凝縮されている。
① 境界（Boundary）での防衛
どれほどHackの型システムが強靭であっても、HTTPの向こう側から飛んでくるJSONは `mixed` の無法地帯だ。
システムのエッジ（境界線）である `deserialize` メソッドでのみ実行時チェックを行ない、ひとたびShape型として内側に取り込んでしまえば、その後のビジネスロジック層では一切の型キャストやキー存在確認が不要になる。
② ネストしたShapeの表現力
実務のAPIレスポンスはフラットではない。上記の `metadata` のように、Shapeの中にShapeをネストさせることで、複雑なJSON構造であってもIDEの完全な補完と型チェックの恩恵を受けられる。
function render_user_dashboard(UserApiResponseMapper::TUserShape $user): string {
// $user[‘metadata’][‘login_count’] は intであることが静的に保証されている
// 万が一キーを ‘login_cnt’ などとタイポしようものなら、型チェッカーが即座にビルドを落とす
return “Welcome back, {$user[‘username’]}! Logins: ” . (string)$user[‘metadata’][‘login_count’];
}
—
4. パフォーマンス上の注意点：Shape vs クラス
「なぜDTO（Data Transfer Object）クラスを使わず、Shape型を使うのか？」という疑問を持つアーキテクトもいるだろう。
HHVMの内部において、Shapeは単なるプリミティブな配列（dict）のラッパーとして最適化される。
- メモリ効率：インスタンス化のオーバーヘッドがクラスに比べて圧倒的に少ない。数万件のレコードを処理するバッチ処理や、高スループットなAPIゲートウェイにおいて、GC（ガベージコレクション）の負荷を劇的に軽減できる。
- シリアライゼーション：JSONへの変換・逆変換が極めて容易（`json_encode` にそのまま渡せる）。
ただし、複雑な振る舞い（メソッド）を持たせるドメインモデルの場合はクラス（またはRecord型）を使うべきだ。「データの構造（State）」を扱うにはShape、「振る舞い（Behavior）」を伴うならクラス。この使い分けができるかどうかが、エンジニアの設計センスの分水嶺となる。
—
結びにかえて
Hack言語のStrict ModeとShape型を使いこなすことは、コードの記述量を増やすことではない。むしろ、将来発生するであろう「バグの調査時間」「仕様変更時の恐怖」「レガシー化するコードベースへの絶望」という膨大な負債を先払いして消し去る行為なのだ。
明日、いや、今すぐ、あなたのプロジェクトにある `dict
それを綺麗に平らげることこそが、真のHackプロフェッショナルの仕事である。