contracts

コントラクト

境界をまたぐインターフェースは、現在の編集が終わった後も存続する約束として扱います。

コントラクトを特定する

境界を変更する前に、コントラクトとその利用者を明示します。

• HTTP、RPC、GraphQL、または CLI のリクエストとレスポンス。
• データベーススキーマ、マイグレーションの出力、または永続化されるデータの形状。
• イベント、キューメッセージ、Webhook、またはバックグラウンドジョブのペイロード。
• 公開モジュールのエクスポート、またはパッケージ API。
• 設定、環境変数、機能フラグ、またはファイル形式。
• UI ルート、URL の形式、または外部から見える動作。

現在のリポジトリの外部に呼び出し元が存在する可能性がある場合は、互換性が重要だと考えます。

変更を分類する

実装の前に、コントラクトの変更を分類します。

• 追加的：既存の意味を変えずに、任意フィールド、新しいエンドポイント、新しい列挙値、または新機能を追加します。
• 範囲縮小：入力を拒否したり、状態を削除したり、検証を厳格化したり、受け入れる動作を減らしたりします。
• 破壊的：既存のフィールドや動作を削除、改名、型変更、並べ替えしたり、その意味を変更したりします。
• 意味的：形状は維持しながら、外部から観測できる意味を変更します。

追加的な変更が通常は最も安全です。範囲縮小、破壊的、意味的な変更には、明示的な移行計画または互換性計画が必要です。

互換性を維持する

互換性を維持する方法を優先します。

• 削除する前に追加します。
• 移行期間中は旧形式と新形式の両方を読み取ります。
• 旧形式を読み取る側がなくなってから、新形式のみを書き込みます。
• 動作の互換性を維持できない場合は、外部利用 API にバージョンを付けます。
• 厳格さがコントラクトの一部でない限り、未知のフィールドを許容します。
• デフォルト値とフィールドがない場合の動作を文書化します。

もう一方への影響がないと証明されていない限り、提供側または利用側の片方だけを更新しないでください。

境界をテストする

利用者が観測する境界でコントラクトを検証します。

• 公開 API とイベントのコントラクトテスト。
• 永続化データのマイグレーションテスト。
• エンコード／デコード、またはインポート／エクスポートの往復テスト。
• 旧ペイロードや旧スキーマの互換性フィクスチャ。
• ツールチェーンが対応している場合は、型チェックやスキーマチェック。

内部の単体テストだけでは、コントラクトの互換性が維持されていることを証明できません。

完了条件

コントラクトが明示され、利用者が考慮され、変更が分類されており、範囲縮小、破壊的、または意味的な変更について互換性や移行への対応が明確で、提供側と利用側の両方への影響が確認され、依存先から観測できる境界を検証できていること。