「このクラスを変更したら何に影響が出るか分からない」という不安を抱えたままリファクタリングに踏み切れなかった経験が、このシリーズの出発点です。JarvizのJSONLフォーマットさえ理解すれば、Java以外の言語でも同じ武器が使えると気づいたのは大きな収穫でした。
なぜコードの関係を可視化するのか
図1: Javaコード可視化の全体フロー — 静的解析からクラス図・コールグラフ・Jarviz出力まで
数千クラス・数万メソッドを抱えるJavaシステムに初めて入ったとき、 あるいは長年稼働してきたレガシーシステムを改修するとき、 「このクラスを変更したら何に影響が出るか」を把握するのは容易ではない。
ドキュメントが古い、存在しない——という状況は珍しくない。 IDE の Find Usages や Call Hierarchy は手元の1クラスを起点に辿るには便利だが、 システム全体のホットスポットや循環依存を一目で把握する手段にはなりにくい。
⚠️ こんな場面で可視化が助けになる
・変更の影響範囲が読めずリファクタリングに踏み出せない
・「神クラス」が存在することは分かっているが規模感が掴めない
・デッドコード（呼ばれていないメソッド）が埋もれている
・モジュール間の依存が複雑に絡み合いアーキテクチャが崩壊しかけている
構造と振る舞いを分けて見る意義
コードの関係には大きく2つの側面がある。
| 視点 | 見えるもの | 代表的な可視化 |
|---|---|---|
| 構造 | クラスの継承・実装・集約関係。「何が何を知っているか」 | UMLクラス図・PlantUML |
| 振る舞い | メソッドの呼び出し連鎖。「誰が誰を呼ぶか」 | Call Graph・シーケンス図 |
どちらか一方だけでは全体像が掴めない。 構造図でクラスの依存関係を把握し、Call Graph で実行時の呼び出しフローを追い、 最終的に Jarviz の3Dマップで全体を俯瞰する——という3段階のアプローチが有効だ。
このシリーズのゴール
このシリーズを読み終えた後、以下ができるようになることを目指す。
✅ シリーズ終了後にできること
1. JavaのClassおよびMethod関係を複数の手法で抽出できる
2. ASM / JavaParser を使って依存関係情報をプログラムで取り出せる
3. Jarviz の JSONL フォーマットを理解し、Java 以外の言語（Python・Kotlin・TypeScript 等）でも同フォーマットを生成して3Dマップを表示できる
4. 3Dマップからホットスポット・デッドコード・循環依存を発見できる
特に JSONL フォーマットの理解と他言語への応用はこのシリーズの目玉である。
Jarviz 自体は Java の JAR を直接解析するツールだが、
内部で使用する jarviz-graph（可視化エンジン）はシンプルな JSONL を受け取るだけでよい。
この事実を理解すれば、どの言語でも同じ3Dマップを活用できる。
可視化手法の選び方
3段階の可視化手法はそれぞれ適した用途がある。状況に合わせて使い分けることが重要だ。
| 手法 | 適した用途 | 限界 |
|---|---|---|
| UMLクラス図（PlantUML / Mermaid） | 設計レビュー・新メンバーへの説明・クラス構造の理解。静的な依存関係を把握したいとき | 大規模コードでは図が膨大になりすぎて読めなくなる。動的な呼び出しは見えない |
| Method Call Graph（ASM / JavaParser） | 影響範囲調査・デッドコード発見・特定メソッドがどこから呼ばれているかの調査 | 静的解析は実際の実行パスと異なる場合がある（ポリモーフィズム・リフレクション） |
| Jarviz 3Dマップ | システム全体の俯瞰・ホットスポット発見・循環依存の検出・アーキテクチャ全体の健全性確認 | 細部の確認には不向き。JARまたはJSONLが必要で、ソースがない場合はクラス名のみになる |
シリーズ全体マップ
前提知識と環境
| 項目 | 内容 |
|---|---|
| Java | Java 11 以上（バイトコード解析のため JDK が必要） |
| Maven / Gradle | ビルドツールの基本操作が分かること |
| Node.js | jarviz-graph の実行に必要（v18 以上推奨） |
| Python（オプション） | PART 05 で他言語応用のサンプルとして使用 |
💡 記事中のコードについて
解析対象サンプルとして order-service（受注）・inventory-service（在庫）・payment-service（決済）という架空のマイクロサービスを想定する。
実際のプロジェクトのコードで試す場合は、パッケージ名・クラス名を適宜読み替えてほしい。
Java可視化でよくある誤り
JavaParserやJarvizを使ってJavaソースを可視化する際、ツール選定とシリーズ全体の設計方針でつまずくケースが多いです。
| 誤り/失敗パターン | 何が起きるか | 正しい対処/防止策 |
|---|---|---|
| 実行トレース系ツール（JProfilerなど）を静的可視化に使おうとする | 実行環境の準備が必要で大規模レガシーコードには適用できない | 実行不要な静的解析ツール（JavaParser）を使いAST走査で関係情報を取得する |
| 可視化の目的（クラス関連図 vs Call Graph vs 3D）を決めずに着手する | 後から出力形式を変えるたびに実装を大幅に作り直す羽目になる | PART 01でClass関連図→Call Graph→Jarviz 3Dの段階的アプローチを計画してから実装する |
| JavaParser非対応のJavaバージョン（記法）のソースを渡す | ParseExceptionが発生し解析が止まる | 対象ソースのJavaバージョンとJavaParserのバージョン対応表を確認してから使用する |