レガシーPHPの静的解析の導入は、ツールの最も厳格なレベルを有効にして何千もの警告を修正することではありません。ビジネスルールが分散し、古い依存関係があり、テストが少ないアプリケーションでは、その方法は潜在的に重大な欠陥と歴史的な技術的負債を混在させ、チームを停滞させ、安全でない変更を招くおそれがあります。
初期の目標は異なります。新たな変更を一つひとつ検証しやすくし、重要なフローにおける不確実性を減らし、既存の負債に対処する明示的な道筋を持つことです。静的解析はコードに関する構造的な情報をもたらします。一方、モダナイゼーションには、製品上の判断、テスト、リリース管理も必要です。
すべてのルールを一度に有効化すると保守が止まりがちな理由
レガシープロジェクトには、暗黙的な型、文書化されていないnull値、責務が多すぎるメソッド、グローバル変数への直接アクセス、到達不能コード、レイヤー間の曖昧な契約が蓄積している場合があります。初日から厳格なルールでリポジトリ全体を解析すると、通常は優先順位を付けられないほど長い一覧になります。
問題は量だけではありません。警告ごとにコンテキストが必要です。一見誤っている呼び出しが外部の条件によって保護されている場合や、依存関係が不完全なアノテーションを使用している場合、ローカルの規約がコード上に表現されていない場合があります。そのコンテキストを理解せずに修正すると、誰も文書化していなかったビジネス上の振る舞いを変えてしまう可能性があります。
また、しばしば混同される次の3つの目標を分けることが重要です。
- 可視性: リスクと契約が不確実な領域を把握すること。
- 変更管理: 変更によって新たな検出可能な問題が導入されるのを防ぐこと。
- 負債削減: 歴史的な問題を優先順位に従って解消すること。
2番目の目標が最適な出発点です。製品開発を続けるための前提条件として大規模な修正を求めることなく、リリース品質を向上できます。
静的解析で検出できることと、代替できない管理策
アナライザーは型を推論し、呼び出しを追跡し、互換性のない引数、不可能な戻り値、未定義のプロパティ、nullになり得る変数、到達不能な分岐、インターフェースとその実装の不一致を検出できます。また、ルールを定義すれば、密結合した依存関係、一貫性なく使用されるAPI、侵害されたアーキテクチャ境界を特定するのにも役立ちます。
これらのシグナルは、リファクタリングで特に価値があります。たとえば、メソッドを変更してCustomer|nullを返すようにすると、常にインスタンスが存在すると想定する利用側を見つけられます。この警告は本番環境に障害があることを証明するものではありませんが、顧客が存在しない場合に何が起こるべきかの判断を迫ります。
しかし、解析だけでは、注文は請求前にのみキャンセルできること、割引が商取引ポリシーに従って計算されること、外部連携が許容時間内に応答することといったルールを検証できません。実際の権限、データ移行、並行性、パフォーマンス、本番構成も観測しません。
安全なリファクタリングは、3つの観点を組み合わせます。
- 静的解析による契約とコード経路の確認。
- 自動テストによる既知の振る舞いの維持。まずは重要なフローから始めます。
- 機能レビューと観測による、ビジネスルール、外部への影響、デプロイ後の振る舞いの検証。
問題を測定する前にパイロットを準備する
最初の対象範囲は、変更が頻繁であるか相応のリスクがある、限定されたビジネスモジュールにすべきです。ただし、アプリケーション全体で最も不透明な中核部分は避けます。有用なパイロットには特定可能な責任者がいて、ルールが理解可能な発見事項を生むかを把握できます。
解析を実行する前に、簡潔なインベントリを作成してください。
- 重要な経路: 認証、決済、注文、請求、個人データ、または障害時の影響が大きいその他の操作。
- 入力と出力: コントローラー、コマンド、キューコンシューマー、API、インポートファイル、スケジュールされたジョブ。
- 依存関係: PHPのバージョン、放棄されたパッケージ、拡張機能、生成コード、型情報のないライブラリ。
- 現在の規約: 値オブジェクト、例外、コレクション、null、連想配列、データアクセスの使用。
- 利用可能なテスト: どのシナリオをカバーするか、どのデータを準備するか、信頼性の限界は何か。
このインベントリにより、各警告を孤立して解釈することを避けられます。また、ネイティブ型を追加するのが適切な場所と、古い依存関係の曖昧さをアプリケーション全体へ広げないために、その周囲でアダプターを維持すべき場所を判断できます。
恒久的な免責にしないベースラインを作る
ベースラインは既存の問題を記録し、チームが新規または変更済みのコードにより高い基準を要求できるようにします。これは移行のためのツールであり、負債が許容可能であるという宣言ではありません。
代表的な発見事項のサンプルをレビューした後に生成してください。結果に構成エラー、解析すべきでないパス、誤って含まれたサードパーティコードが含まれるなら、先に修正します。ノイズで膨らんだベースラインは、最初から価値を失います。
有用にするには、運用ルールと結び付けます。
- レビュー可能な根拠なしに、ベースラインへ新しい項目を追加しない。
- 修正した問題は、同じ変更内でベースラインから削除する。
- 影響を受けるファイルまたはモジュールに手を加える際、項目をレビューする。
- 例外には、所有者、技術的な理由、レビュー日またはレビュー条件を設定する。
エラーのカテゴリ全体を隠すより、説明付きの非常に限定的な抑制を記録する方が望ましいです。外部ライブラリが契約を表現していないために警告を解決できない場合は、そのライブラリを型付けされたアダプターにカプセル化し、例外をその境界に限定してください。
リスクと判断コストで発見事項を分類する
すべての診断がリリースをブロックするに値するわけではありません。分類は、ツールが割り当てる重大度だけでなく、潜在的な影響と確実性の度合いを反映すべきです。
高優先度: 契約と重要データ
まず、互換性のない戻り値、ビジネス操作での誤った型の引数、nullになり得るアクセス、外部境界で検証されていない値、モジュール間の契約違反を扱います。これらは、十分でないテストでは通過しない欠陥を明らかにすることがよくあります。
中優先度: 対象範囲を広げる不確実性
形状が不明な配列、複数のレイヤーを通過するmixed値、過度に広い型を返すメソッドは、必ずしも即時の障害を引き起こすわけではありません。それでも、変更ごとのコストを高めます。フローに手を加える際に、適切であればDTO、値オブジェクト、明示的な契約を定義して解消するのが望ましいです。
低優先度: 影響が実証されていない整理
スタイル、冗長なコード、内部規約は可読性を改善できますが、ドメインリスクや緊急のリリースと競合させるべきではありません。別タスクにまとめるか、変更が機械的で検証可能な場合にのみ自動ルールを適用してください。
介入の順序: 新たな負債を防ぎ、稼働中のフローを守る
実践的な順序は、提案された変更に対して継続的インテグレーションで解析を実行することから始まります。初期のブロック基準は単純で構いません。ベースライン外の新たなエラーを導入せず、変更したファイルのレベルを悪化させないことです。
その後、ディレクトリまたはモジュールごとにルールを厳格化します。新しいドメインコード、アプリケーションサービス、最近追加されたアダプターから始め、歴史的なインフラストラクチャレイヤーではより寛容な基準を維持するのが一般的です。この分割はレガシーを放棄する言い訳ではありません。境界を可視化し、徐々に移動できるようにします。
進行中の各変更では、小さな対象範囲を優先してください。
- 維持する必要がある振る舞いに対するキャラクタリゼーションテストを追加する。
- 最も重要な入出力契約を宣言する。
- その経路に影響する警告を修正する。
- 短いステップでリファクタリングし、機能上の差分をレビューする。
- モジュールが維持できるようになったら、より厳格なルールを有効化する。
型とアノテーションは実際の知識を記述すべきです。警告を黙らせるためだけにnull非許容型を宣言すると、リスクを次の利用側へ移すだけです。設計上値が欠ける可能性があるなら、そのように表現し、呼び出し側コードに処理方法を判断させてください。
ノイズでブロックせずに継続的デリバリーへ管理策を統合する
解析結果は、変更を作成する人にとって読みやすいものでなければなりません。新しいエラー、影響を受けるファイル、ルール、重要である理由を示す情報を公開してください。責任者がなく、行われた変更との関係もない長大なレポートは避けます。
釣り合いの取れた基準を定義してください。重要フローの契約欠陥はブロックできます。見た目だけの改善はフォローアップに回せます。依存関係からの不確実な警告は、アダプター、文書化された構成、または一時的な例外につなげるべきです。コードレビューは、修正がビジネス上の意図を尊重しているかを判断します。アナライザーはその判断を置き換えません。
意思決定を導く指標で進捗を測定します。モジュールごとの未解決の重要な問題、削除されたベースライン項目、厳格なルールで解析された変更の割合、重要経路にある曖昧な契約の数、キャラクタリゼーションテストでカバーされたリファクタリングの割合です。目的はグローバルな警告をゼロにすることではなく、変更における不確実な範囲を減らすことです。
整理をモダナイゼーションと混同するアンチパターン
- 理由なく警告を抑制する: 発生源のリスクを減らさずに情報を除去します。
- 発見事項ゼロを追求する: 重要なプロセスが安全でないまま、無関係な詳細に能力を割く可能性があります。
- 近くのすべてのファイルを修正する: 変更規模が増え、リグレッションのレビューが難しくなります。
- 未知のデータを信頼できるかのように型付けする: 不確実性をモデル化する代わりに隠します。
- 新しいルールであらゆるリリースをブロックする: 反発を生み、チームを恒久的な例外探しへ向かわせます。
パイロット開始のチェックリスト
- 技術的な所有者、ビジネス上の重要性、限定された対象範囲を持つモジュールを選ぶ。
- その入力、出力、依存関係、重要なシナリオを特定する。
- 解析を実行し、構成エラーを除去して、結果のサンプルをレビューする。
- 既存の負債に限定したベースラインを作成し、誰が変更できるかを定義する。
- パイロットの変更では、高リスクの新規問題をブロックする。
- 影響を受けやすい経路をリファクタリングする前に、キャラクタリゼーションテストを追加する。
- 繰り返し発生する発見事項、例外、ノイズを生むルールを毎週レビューする。
- 結果が理解可能で実行可能な場合にのみ、基準を厳格化する。
このアプローチにより、静的解析はレガシーの欠陥レポートではなく、管理の仕組みになります。各変更がより明確な契約、不確実性の低下、PHPを段階的にモダナイズするためのより安全な基盤をもたらします。
