# バッチ設計書 19-ValidateApiDiff

## 概要

本ドキュメントは、現行バージョンとベースラインのAPI差分を検証するNukeビルドターゲット「ValidateApiDiff」の設計仕様を記載したものです。

### 本バッチの処理概要

ValidateApiDiffターゲットは、Microsoft.DotNet.ApiCompat.Toolを使用して、現在のビルドとベースラインバージョン間のAPI互換性を検証し、破壊的変更がないことを確認するバッチ処理です。

**業務上の目的・背景**：APIの後方互換性維持はフレームワーク開発の最重要課題の一つです。公開APIの破壊的変更（メソッドの削除、シグネチャの変更、アクセシビリティの制限等）は、既存のユーザーアプリケーションを壊す可能性があります。本バッチは、API互換性ツールを使用して自動的に破壊的変更を検出し、意図しないAPI変更がリリースされることを防止します。

**バッチの実行タイミング**：DownloadApiBaselinePackagesターゲット完了後に実行されます。Packageターゲットの一部として実行され、CIパイプラインでの品質ゲートとして機能します。

**主要な処理内容**：
1. GlobalDiff情報から各パッケージの差分情報を取得
2. 各フレームワーク別にApiCompatToolを実行
3. 抑制ファイル（suppression file）の読み込みと適用
4. API互換性エラーの検出とレポート
5. 抑制ファイルの更新（ローカルビルド時）

**前後の処理との関連**：DownloadApiBaselinePackagesターゲットに依存しています。Packageターゲットから依存されており、テスト実行とNuGetパッケージ作成の後に実行されます。

**影響範囲**：API互換性エラーが検出された場合、ビルドが失敗します。ローカルビルドでは抑制ファイルが自動更新される場合があります。

## バッチ種別

品質検証 / API互換性チェック

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（CI/CDパイプライン実行時） |
| 実行時刻 | 指定なし |
| 実行曜日 | 指定なし |
| 実行日 | 指定なし |
| トリガー | DownloadApiBaselinePackages完了後 / 手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| DownloadApiBaselinePackages完了 | ベースラインと現在のアセンブリが展開されていること |
| GlobalDiff設定済み | 差分情報が利用可能であること |
| Microsoft.DotNet.ApiCompat.Tool | APICompatツールが利用可能であること |

### 実行可否判定

- DependsOnでDownloadApiBaselinePackagesターゲットに依存
- GlobalDiffプロパティが設定されていること

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| configuration | string | No | Release | ビルド構成（Debug/Release） |
| update-api-suppression | bool | No | IsLocalBuild | 抑制ファイルを更新するかどうか |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| artifacts/api-diff/assemblies/baseline/ | DLL | ベースラインアセンブリ |
| artifacts/api-diff/assemblies/current/ | DLL | 現在のアセンブリ |
| api/{PackageId}.nupkg.xml | XML | API互換性抑制ファイル |
| GlobalDiffプロパティ | オブジェクト | 差分情報 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| コンソール出力 | テキスト | 検証結果・エラー情報 |
| api/{PackageId}.nupkg.xml | XML | 更新された抑制ファイル（update-api-suppression時） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | {PackageId}.nupkg.xml |
| 出力先 | api/ |
| 文字コード | UTF-8 |
| 形式 | XML |

## 処理フロー

### 処理シーケンス

```
1. DownloadApiBaselinePackages依存関係の確認
   └─ GlobalDiffの存在確認
2. 各パッケージの並列処理
   └─ Parallel.ForEachによる並列実行
3. 各パッケージの検証
   └─ ValidatePackageメソッド呼び出し
4. 各フレームワークの検証
   └─ ベースライン/現在のパスを相対パスに変換
   └─ 抑制ファイルの読み込み
   └─ ディレクトリセパレータの調整（Windows対応）
   └─ ApiCompatToolの実行
5. エラー検出
   └─ stderr出力の収集
   └─ エラーがあれば例外スロー
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[GlobalDiff確認]
    B --> C{各パッケージ並列処理}
    C --> D[抑制ファイル確認]
    D --> E{各フレームワーク}
    E --> F[相対パス変換]
    F --> G[ApiCompatTool実行]
    G --> H{エラー検出?}
    H -->|Yes| I[エラー収集]
    H -->|No| J[次のフレームワーク]
    I --> J
    J --> K{次のフレームワーク?}
    K -->|Yes| E
    K -->|No| L{次のパッケージ?}
    L -->|Yes| C
    L -->|No| M{全体でエラー?}
    M -->|Yes| N[例外スロー]
    M -->|No| O[成功終了]
```

## データベース操作仕様

### 操作別データベース影響一覧

本バッチはデータベース操作を行いません。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | データベース操作なし |

### テーブル別操作詳細

データベース操作は行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ApiCompatError | API互換性エラー | 破壊的変更が検出された | 抑制ファイル更新または変更の取り消し |
| ToolExecutionFailed | ツール実行失敗 | ApiCompatToolが異常終了 | ツールのインストール確認 |
| GlobalDiffNull | 差分情報なし | DownloadApiBaselinePackagesが失敗 | 前提ターゲットの確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

1. API互換性エラーの場合：
   - 意図的な変更: 抑制ファイルを更新（`--update-api-suppression`オプション）
   - 意図しない変更: コードを修正して後方互換性を維持
2. ツール実行失敗の場合：Microsoft.DotNet.ApiCompat.Toolの復元を確認
3. パス関連エラーの場合：ディレクトリセパレータの不整合を確認

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（データベース操作なし） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数十パッケージ × 複数フレームワーク |
| 目標処理時間 | CI環境で5分以内 |
| メモリ使用量上限 | ApiCompatToolの要件に依存 |

## 排他制御

- Parallel.ForEachによる並列処理
- 各パッケージは独立して処理
- 抑制ファイルへの同時書き込みなし（パッケージごとに別ファイル）

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 各パッケージ処理開始時 | "Validating API for package {Id}" |
| エラーログ | API互換性エラー検出時 | 詳細なエラーメッセージ |
| 終了ログ | 処理完了時 | 検証完了通知 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 15分 | Azure Pipelines通知 |
| API互換性エラー | 1件以上 | PRコメント/ビルド失敗通知 |

## 備考

- Microsoft.DotNet.ApiCompat.Tool（net8.0版）を使用
- 抑制ファイルはapi/ディレクトリに保存
- Windows環境ではディレクトリセパレータ（\と/）の変換処理が実行される
- `--permit-unnecessary-suppressions`オプションで不要な抑制も許可
- ローカルビルドではデフォルトで抑制ファイル更新が有効（UpdateApiValidationSuppression）
- Parallel.ForEachで各パッケージを並列処理
- 抑制ファイルのパスは`<Left>`/`<Right>`タグ内で管理
