Hackを掌握する極限の知見：Attributeを活用したコード生成と「妥協なき型安全性」の共存
テックリードの私だ。コードレビューの際、「メタプログラミングや動的なコード生成を使いたいが、どうしても静的型チェッカー（hh_client）の恩恵が薄れ、`mixed` の蔓延やランタイムエラーの温床になる」という愚痴をよく耳にする。
甘えるな。HHVMとHackの静能美を理解していれば、「メタプログラミングの柔軟性」と「厳格な静的型付け（Strict Mode）」は決してトレードオフではない。
今回は、Hackの `<<__Attribute>>`（User Attributes）を駆使し、コンパイル時（正確には型チェック時）の安全性を完璧に担保したままコード生成・ルーティング処理を構築する、実務直結のアーキテクチャを伝授する。
—
なぜ「動的な仕組み」がHackでは嫌われるのか
PHPから派生した言語でありながら、Hackの本質は「JITコンパイルされる圧倒的な実行速度」と「妥協のない静的型チェッカー」の融合にある。
多くの開発者がやりがちなアンチパターンを見てみこう。
// 【悪手】リフレクションと動的呼び出しに頼ったコード
<<__EntryPoint>>
function bad_example(): void {
// 文字列ベースのルーティングやメソッド呼び出し
$controllerName = “UserApiController”;
$methodName = “getData”;
// hh_clientはこの文字列の先に何があるか追跡できないため、
// ここで `mixed` や動的コールが生まれ、型安全性が完全に崩壊する。
}
このアプローチは、リファクタリング耐性をゼロにする。メソッド名をリネームした瞬間に本番で爆発するコードを、プロのエンジニアが書いていいはずがない。
では、どうすべきか？ 「User Attributesでメタデータを宣言し、それを元に型安全な構造を静的に紐付ける」 のだ。
—
堅牢な設計：Attributeベースの型安全ルーティング＆コード生成パターン
ここでは、HTTPリクエストを受け取るコントローラー群に対し、カスタム属性を付与して「どのパスにどの型のリクエスト・レスポンスが紐づくか」を完全に静的に定義する設計を示す。
以下のプロダクションコードを見てほしい。コピペし、自社のアーキテクチャの基盤として組み込むといい。
<<__FILE__>>
namespace Hack\Advanced\MetaProgramming;
// 1. ルート定義用のカスタム属性（Parameterを強固に縛る）
<<__Attribute(__Class, __Persistent)>>
final class ApiRoute {
public function __construct(
public string $path,
public string $method = ‘GET’,
) {}
}
// 2. リクエスト・レスポンスのインターフェイス定義
interface IRequest {}
interface IResponse {}
// — 実際のドメイン層の定義 —
final class UserGetRequest implements IRequest {
public function __construct(public int $userId) {}
}
final class UserGetResponse implements IResponse {
public function __construct(public string $userName) {}
}
// 3. 属性を付与したコントローラー（厳格な型付け）
<
final class GetUserController {
// 引数と戻り値の型が完全に保証されている
public function handle(UserGetRequest $req): UserGetResponse {
// ここにビジネスロジックを書く
return new UserGetResponse(“User_”.$req->userId);
}
}
// 4. 型安全なディスパッチャ（HHVMリフレクションの正しい使い方）
final class ApiDispatcher {
/
- 指定されたクラス群から属性を読み取り、静的マッピングを構築する。
- 実際にはコードジェネレーターやビルドスクリプトで事前実行することを推奨する。
/
public static function resolveAndExecute(string $classStr, IRequest $request): IResponse {
$refClass = new \ReflectionClass($classStr);
// 属性の取得
$attributes = $refClass->getAttributes();
$routeAttr = null;
foreach ($attributes as $attr) {
if ($attr->getName() === ApiRoute::class) {
// 属性のインスタンス化と型キャスト
$instance = $attr->getInstance();
if ($instance is ApiRoute) {
$routeAttr = $instance;
break;
}
}
}
if ($routeAttr === null) {
throw new \InvalidArgumentException(“Class {$classStr} is not a valid ApiRoute.”);
}
// メソッドの実行（ここではconventionとして ‘handle’ を強制）
$instance = $refClass->newInstance();
if (!method_exists($instance, ‘handle’)) {
throw new \BadMethodCallException(“Handler method missing.”);
}
// Hackの型チェッカーを欺かない、厳格な呼び出し
// 実際の実装ではここでパラメータの型一致を静的/動的に検証する
return $instance->handle($request);
}
}
—
この設計がプロダクションで最強である理由
1. リフレクションのコストを「コンパイル時 / ビルド時」に排除する
Runtimeにおける `ReflectionClass::getAttributes()` の多用は、パフォーマンスのボトルネックになりうる。真に洗練されたシステムでは、このコード生成・属性解析をビルドプロセス（CLIスクリプトなど）で事前に行い、結果を静的なマップファイル（あるいはコードそのもの）として出力する。
しかし、「ソースコードの記述元（Single Source of Truth）」としてAttributeを使うことで、開発者はアノテーションのタイポや不整合から解放される。
2. `is` 演算子によるスマートキャストの徹底
上記のコードで、`if ($instance is ApiRoute)` というスマートキャストを使っている点に注目してほしい。
Hackの型チェッカーは、この条件分岐以降、$instance が確実に `ApiRoute` 型であることを認識する。`mixed` や `any` のような逃げ道を一切許さない、これがHackの厳格さ（Strict Mode）だ。
—
チーフアーキテクトからの実践的アドバイス
1. `<<__ConsistentConstruct>>` との組み合わせ
もしファクトリーパターンやDIコンテナと属性を組み合わせる場合、`<<__ConsistentConstruct>>` 属性をクラスに付与することで、子クラスのコンストラクタシグネチャの互換性を静的チェックさせることができる。動的インスタンス化の不安要素を完全に排除せよ。
2. HHVMのJIT最適化を意識した型ヒント
HHVMのJITコンパイラは、型が完全に確定しているコードに対して驚異的なネイティブコードを生成する。逆に、引数や戻り値に `mixed` が混ざると、Type-Specialization（型特化）の恩恵を受けられず、ICacheミスやボクシング（Boxed values）のオーバーヘッドが増大する。Attributeから得たメタデータを処理する際も、必ず具象型（Concrete types）へ即座にキャストし、型チェッカーのレールに乗せ続けろ。
結び
メタプログラミングは「型安全性の放棄」と同義ではない。HackのパワフルなAttribute機構と厳格な型システムを正しく手なづければ、保守性が高く、かつ圧倒的なパフォーマンスを誇るWebアプリケーションアーキテクチャが手に入る。
妥協のないコードを書け。それがプロのエンジニアだ。