【実務・中級編】【中級者向け】カスタムAttributeによる静的解析の拡張：プロジェクト固有のコーディング規約を型チェッカーに教え込む – Hack言語 コア・静的型システムとHHVMのアーキテクチャ解析バイブル

【Hackを掌握する極限の知見】カスタムAttributeによる静的解析の拡張：プロジェクト固有のコーディング規約を型チェッカーに教え込む

テックリードとしてコードレビューを行っていると、次のようなフラストレーションに直面しないだろうか。

「このドメインモデルは、必ず特定のトランザクションコンテキスト内でのみインスタンス化されなければならない」
「この外部APIラッパーのメソッドは、必ず非同期コンテキスト（Async）から呼び出されなければならないが、静的型チェッカー（hh_client）単体ではそれを検知できない」

一般的な動的言語や、緩い静的解析しか持たないエコシステムであれば、これらは「開発者の意識の高さ」や「ドキュメントの熟読」という不確実な要素に依存するか、実行時例外（Runtime Exception）で検知するしかなかった。

しかし、我々が使っている Hack言語 と HHVM（HipHop Virtual Machine） のアーキテクチャは違う。HHVMの型チェッカー（Typechecker）は、単なるシンタックスチェッカーではなく、ミリ秒単位でAST（抽象構文木）を解析し、全コードベースのグラフ構造をメモリ上に保持する極めて強力な推論エンジンだ。

今回は、HackのカスタムAttributeと型チェッカーの挙動を深く理解し、プロジェクト固有のビジネスルールやコーディング規約を「静的型の世界」に強制的に組み込むための極限の知見を伝授する。

—

1. Hackの型チェッカーとAttributeの裏側

まず、Hackにおける `<<__Attribute>>` の正体を理解しなければならない。
多くのプログラミング言語（PHPのAttributesやJavaのAnnotationsなど）において、アノテーションは「実行時にリフレクションでメタデータを取り出すため」のものだ。

だが、Hackの世界では異なる。Hackの型チェッカーは、コンパイル時（hh_clientのデーモンプロセスが常駐するバックグラウンド解析時）に、コード上に付与された属性を解釈する。つまり、「実行時コストを一切かけずに、静的解析のルールを追加するためのフックポイント」として機能する。

プロジェクト特有の制約を型チェッカーに教え込むとは、言い換えれば「HHVMの型推論エンジンに、独自のバリデーションルールをコンパイル時アサーションとして注射する」ことに他ならない。

—

2. 実践：ドメイン駆動設計における「トランザクション境界の強制」

例として、ECドメインにおける「特定の集約（Aggregate）の変更は、必ず専用のマネージャー経由で行わなければならない」という規約を強制するカスタムAttributeを設計しよう。

直面しがちなアンチパターンは、ドメインモデルのコンストラクタやセッターにロジックを散りばめ、レビューで指摘し合うことだ。これを型チェッカーに検知させる。

プロダクションコード例

以下のコードは、厳格なStrictモード（`<<____Enforce>>` 相当の規約）下で、不正な箇所からのインスタンス化を型レベルでブロックするための設計パターンだ。

<>

namespace HackExpert\Architecture\Security;

/

• 【カスタムAttribute】
• この属性が付与されたクラスやメソッドは、指定されたオーソライザー経由でなければ
• 呼び出しやインスタンス化ができないことを型チェッカーに教え込む。

/
<<__Attribute( // クラス、メソッド、プロパティへの付与を許可 _IsMap::CLASS | _IsMap::METHOD | _IsMap::CstConst )>>
class EnforceTransactionBoundary implements \HH\ClassAttribute {
public function __construct(
public string $authorizedCallerClass
) {}
}

/

• 許可されたトランザクションマネージャー（認可された呼び出し元）

/
final class OrderTransactionManager {
public function createNewOrder(int $userId): OrderDomainModel {
// マネージャー経由の呼び出しは型チェッカーにより許可される
return new OrderDomainModel($userId);
}
}

/

• 【保護されたドメインモデル】
• 直接の `new OrderDomainModel()` は静的解析エラーとなるべき対象。

/
class OrderDomainModel {
// 規約として、このコンストラクタは OrderTransactionManager からのみ呼ばれるべき
<<__Internal>>
public function __construct(
private int $userId,
private string $status = ‘PENDING’
) {
// ドメインロジックの初期化
}

public function getUserId(): int {
return $this->userId;
}
}

/

• 【アンチパターンの例（レビューで弾かれるべきコード）】

/
final class UnauthorizedService {
public function doSomethingEvil(int $userId): void {
// ❌ 型チェッカーまたはカスタム静的解析Linterがここで警告/エラーを出すべき箇所
// 直接ドメインモデルを生成しているため、トランザクション境界を破壊している
$order = new OrderDomainModel($userId);
}
}

—

3. 型チェッカーの限界を超える：Hack Linter / Custom Typechecker Plugin との連携

純粋なHackのビルトイン型チェッカーは汎用的な型安全性を保証するが、「特定のクラス名とAttributeの組み合わせを追跡する」ようなドメイン固有の制約までは、標準の `hh_server` の設定だけでは完全な検出が難しい場合がある。

そこで実務の現場では、HackのLinter拡張（カスタムLinterスクリプト）をCIパイプラインおよび開発者のエディター（VSCode / Nuclide）に統合する。

HHVMのASTを出力する標準ツール（`hh_client –ast` または JSON形式の出力）を利用し、先ほどの `EnforceTransactionBoundary` 属性がついたモデルが、指定された `authorizedCallerClass` 以外からインスタンス化されていないかをパースする小規模な静的解析スクリプトを仕込むのが、テックリードとしての正しいアプローチだ。

パフォーマンス上の注意点

カスタム静的解析を導入する際、絶対に犯してはならないミスが「実行時リフレクションへの依存」だ。

• NGな設計: `ReflectionClass` や `ReflectionAttribute` をリクエストごとに実行し、動的に境界チェックを行う。これはPHP時代の悪い癖であり、HHVMのJITコンパイラ最適化の恩恵を台無しにし、スループットを数分の１に低下させる。
• 正しい設計: すべての検証は「ビルド時（`hh_client` の型チェックフェーズおよびCIのLinter実行時）」に完結させる。ランタイムには一切のオーバーヘッドを残さない。これがHack言語のポテンシャルを極限まで引き出す唯一の方法である。

—

4. 非同期API連携における安全性の担保：Async Boundary Attribute

もう一つの実務的な応用例として、非同期I/O（Async API）の呼び出し漏れを防ぐパターンを見てみよう。Hackは `Awaitable` による強力な非同期モデルを持つが、「非同期でなければならない重い処理を、うっかり同期コンテキストでブロッキングして呼んでしまう」という事故が起きがちだ。

<>

namespace HackExpert\Architecture\Async;

<<__Attribute(_IsMap::METHOD)>>
class RequiresAsyncContext implements \HH\ClassAttribute {}

class ExternalApiClient {
<>
public async function fetchUserDataAsync(int $id): Awaitable {
// 重いI/O処理のシミュレーション
// HH::Asio\join(…) などを同期的に叩くことは絶対に許されない
$response = await \HH\Asio\usleep(10000);
return new UserDto($id, “Expert Developer”);
}
}

final class UserDto {
public function __construct(public int $id, public string $name) {}
}

この `<>` が付与されたメソッドを呼び出す側は、必ず `await` 式を使用しているか、あるいは呼び出し元自体が `async` 関数であることを、カスタムLinterによって静的に強制する。これにより、プロダクション環境での予期せぬスレッドブロックやデッドロックの芽を、コードがデプロイされるはるか前に摘み取ることが可能になる。

—

テックリードからの総括

Hack言語の真の強さは、単に「PHPに型がついた」という表面的なものではない。
HHVMという底知れぬパフォーマンスを持つエンジンと、妥協のない静的型チェッカーが織りなす「開発者フィードバックループの速さ」にある。

プロジェクト固有のコーディング規約を属人化させず、カスタムAttributeと静的解析の拡張によって「間違ったコードがコンパイルできない（型エラーになる）世界」を構築せよ。それこそが、大規模Webアプリケーションを破綻させずにスケールさせるための唯一にして最上のエンジニアリングである。