こんにちは！Hack言語の世界へようこそ。
世界最高峰のHHVMアーキテクチャや、あの厳格な静的型チェッカーの息吹を感じながらコードを書く毎日は、型フェチのエンジニアにとってたまらないものですよね。
今回は、中級者の一歩先を行くあなたへ向けて、「カスタムAttributeによる静的解析の拡張」というテーマを徹底解説します。
「他の言語から来たけれど、プロジェクト独自の厳しいコーディング規約を、もっとスマートに自動で検知させたいな…」と思ったことはありませんか？実はHackなら、あなた自身のルールを型チェッカーに直接教え込むことができるんです。
ここをクリアすれば、Hackの型システムの真髄がグッと見えてきますよ。一緒にマスターしていきましょう！
—
1. なぜカスタムAttributeを使うのか？（背景と基本の考え方）
Hackの静的型チェッカー（`hh_client`）は非常に優秀です。`int`や`string`といったプリミティブ型はもちろん、ジェネリクスやNullableの厳密な管理まで、実行時エラーを未然に防いでくれますよね。
しかし、大規模な開発現場では「型システムだけでは縛りきれない業務ロジック上のルール」が出てきます。例えば、こんな規約はありませんか？
- 「決済処理を行うメソッドには、必ず特定のセキュリティ監査ログ用Attributeを付与しなければならない」
- 「レガシーなAPIを呼び出すクラスには、`@Deprecated`の代わりに独自の移行期限を示すAttributeが必須」
これを単なる「目視のコードレビュー」に頼っていると、必ずヒューマンエラーが起きてしまいます。そこで登場するのが、カスタムAttributeと静的解析の組み合わせです。
イメージ図：型チェッカーの拡張フロー
[ あなたの書いたHackコード ]
↓
[ HHVM型チェッカー (hh_client) ] ← ★ここにカスタムルールを適用！
↓
[ 違反があればビルド時に即座に赤線（エラー）を検知 ]
Hackでは、ユーザー定義のAttributeを作ることで、コードのメタデータ（付加情報）を型チェッカーに読み込ませることができます。それでは、具体的にどう実装するのかを見ていきましょう！
—
2. 実践：カスタムAttributeを定義して使ってみる
まずは、プロジェクト独自のルールとして「機密データを扱うメソッド」であることを明示するカスタムAttributeを作ってみましょう。
Hackでは、Attributeを定義するために `<<__Attribute(...)>>` というメタAttributeがついた特殊なクラス（あるいは型）を定義します。
<
namespace HackExpert\Security;
// ① カスタムAttribute自体の定義
// ターゲットをメソッド（__Method）に限定することで、意図しない場所への付与を防ぎます。
<<__Attribute(__Method)>>
final class ConfidentialOperation implements \HH\ClassAttribute {
public function __construct(
public string $securityLevel,
) {}
}
// ② 実際にコードで利用する例
class PaymentService {
// カスタムAttributeを付与し、引数としてセキュリティレベルを渡す
<
public function executeTransfer(int $amount, string $destinationAccount): void {
// 決済処理のコアロジック
\HH\Lib\tuple($amount, $destinationAccount); // ダミー使用
}
// エラー例：セキュリティレベルが必要なのに付与していない（後述のルールで検知したい対象）
public function refundUser(int $userId): void {
// 返金処理
\HH\Lib\Tuple($userId);
}
}
コードのポイント
- `<<__Attribute(__Method)>>`: このアノテーションにより、このクラスが「メソッドに対してのみ付与できるAttribute」であることをHHVMに伝えます。
- コンストラクタ (`__construct`) を定義することで、Attribute側にパラメータ（ここでは `string $securityLevel`）を持たせることができます。これにより、単なる目印を超えた「リッチなメタデータ」が実現できます。
—
3. 型チェッカーと静적解析はどう連携するのか？
「ふむふむ、Attributeを付けるところまでは分かった。でも、これをどうやって『ルール違反の検知』に繋げるの？」と思いましたよね？
ここで重要な事実をお伝えします。実は、標準のHHVM型チェッカー単体では「このAttributeがついていない場合にエラーにする」という複雑なビジネスロジックのバリデーションを直接は行えません。（型チェッカーはあくまで型とアノテーションの整合性をみるためです）
そのため、実務では以下の2つのアプローチを組み合わせます。
1. Hackの型システムによる安全性担保: Attributeの引数の型（例：文字列が渡されているか）は型チェッカーが完全に保証します。
2. 静的解析ツールの拡張（Linter / Custom AST visitor）: HHVMのエコシステムや、プロジェクト独自のCIパイプライン（またはHHVMの拡張API）でAST（抽象構文木）を走査し、「`PaymentService` 内の特定のメソッドに `ConfidentialOperation` が付いているか」をチェックするカスタムLinterスクリプトを走らせます。
例えば、カスタムLinterスクリプトの概念コードは次のように書けます。
namespace HackExpert\Linter;
class ConfidentialityLinter {
// 抽象構文木(AST)を走査するイメージ
public static function lintMethod(ReflectionMethod $method): void {
$isPaymentMethod = \HH\Lib\Str\starts_with($method->getName(), ‘execute’) ||
\HH\Lib\Str\starts_with($method->getName(), ‘refund’);
if ($isPaymentMethod) {
// カスタムAttributeがついていなければ、静的解析エラーとしてexit codeを返す
$hasAttribute = $method->getAttribute(HackExpert\Security\ConfidentialOperation::class) !== null;
if (!$hasAttribute) {
throw new \RuntimeException(
“Coding Rule Violation: メソッド ‘{$method->getName()}’ は決済・機密系処理のため、<
);
}
}
}
}
これをCI/CDパイプライン（GitHub Actionsなど）のビルドプロセスや、開発者の手元での `hh_client` 実行後のフックとして組み込むことで、「規約違反のコードは絶対にコミットさせない・ビルドさせない」という堅牢な開発環境が完成します。
—
4. 陥りやすい文法・設計エラーと回避のコツ
HackでカスタムAttributeを設計する際、初心者がハマりがちなポイントをいくつかシェアしておきますね。ここを知っておくだけで、無駄な試行錯誤をゴッソリ回避できますよ！
エラーその1: Attributeのターゲット（スコープ）を間違える
- 症状: クラスにつけたいAttributeをプロパティにつけてしまい、型チェッカーに怒られる。
- 対策: 定義時の `<<__Attribute(...)>>` のフラグを正しく設定しましょう。
- クラスなら `__Class`
- メソッドなら `__Method`
- プロパティなら `__Property`
をビット演算子や複数指定で適切にコントロールします。
エラーその2: 動的な値や定数以外をAttributeの引数に渡そうとする
- 症状: 「Attributeの引数にはコンパイル時定数（Literal）しか使えません」というエラーが出る。
- 原因と対策: HackのAttributeは、コンパイル時に確定する静的なメタデータです。そのため、変数（`$x`）や実行時に関数が返した値をそのまま渡すことはできません。必ず文字列リテラルや整数リテラルを渡すように設計してください。
// ❌ ダメな例
$level = ‘HIGH’;
<
// ⭕ 正しい例
<
—
まとめ：ここをクリアすれば、Hackの基本はバッチリマスターできますよ！
今回は、カスタムAttributeを使った静的解析の拡張について、アーキテクチャの裏側も交えて解説しました。
- カスタムAttributeを活用することで、コードにリッチなメタデータを付与できる。
- Attributeの引数の型安全性は、Hackの厳格な型チェッカーがしっかりと守ってくれる。
- プロジェクト固有の厳格な規約は、型システムとカスタムLinterを組み合わせることで、完全自動で検知・強制できる。
一見難しそうに見えるHackの高度な機能も、本質（HHVMがどのようにコードを解釈しているか）を理解してしまえば怖くありません。この知見を武器に、あなたのプロジェクトをより堅牢で美しいコードベースへと導いていってくださいね。
それでは、素晴らしいHackライフを！質問があればいつでもコメント欄でお待ちしています。