guarding-architecture

アーキテクチャのガード

必須の事前知識： principal-engineering スキル。

概要

構造上の不変条件は、システムを支える契約です。不変条件に違反すると、単一の不具合ではなく、ある種のバグが発生します。重要な不変条件には名前を付け、根拠を書き、機械的なガードを設けます。ガードのない不変条件は、単なる願望です。

パターン

1. 不変条件に名前を付けます。 番号を付けて参照可能にします（「法則 3」など）。それぞれに、技術に依存せず、どのフレームワークよりも長く有効であることを意図した「記述」、根拠、影響を記載します。根拠には、違反時に発生する一連のバグを、抽象論ではなくインシデントをもとにした具体的な障害の経緯として記述します。
2. 安定した要素と変わりやすい要素を分けます。 原則を記すドキュメントは変更頻度を低くし、クラス名は記載しません。現在の実現方法（正規の責任者、ガード、リファレンスデザイン）は、コードに合わせて変更される補足ドキュメントに記載します。両者に食い違いがあれば、不変条件を優先し、実現方法のドキュメントを修正します。
3. 機械的に強制します。 強制可能な不変条件すべてに、ビルドを失敗させるアーキテクチャテストを設けます。対象には、依存関係の方向、パッケージ境界、レイヤリングのルール、禁止されたインポートが含まれます。ビルドで強制できないものは、不変条件を明記した名前付きのレビュー項目にします。
4. 違反には正当化ではなく再設計で対処します。 名前付きの不変条件に違反する設計は、その構造上誤っています。例外を仕様にねじ込まず、再設計します。契約を不適合なコードに合わせて緩めることは禁止されています。違反を記録し、コードを修正します（これは技術ライター向けプラグインが規範文書に適用するのと同じルールです）。
5. 仕様で準拠状況を示します。 ガード対象に触れる設計では、関係する不変条件を明記し、それぞれをどのように守るかを不変条件ごとに示します。レビュー担当者は好みを議論するのではなく、主張を名前付きの不変条件と照らし合わせて確認します。
6. 例外は改定として扱います。 真に例外が必要な場合は、曲げる不変条件とその範囲を明記し、改定案を提示します。黙示的な例外が、不変条件を単なる提案に変えてしまいます。これが唯一認められる例外の形式であり、項目 4 により、それ以外はすべて禁止されます。責任者と連絡が取れなくても例外にはなりません。変更は保留するか、準拠した形で取り込みます。本当に一時的な例外は、有効期限の条件と責任者の承認を記載した期限付きの適用免除とし、安定した不変条件を改定して一時的な状態に合わせるのではなく、変わりやすい実現方法のドキュメントに記録します。
7. 説明のないガード除外は、ビルドから隠された違反です。 それを見つけた人は、不変条件の責任者に報告します。ある除外が次の除外の前例になることはありません。「ほかもそうしている」と除外リストを拡張するのは、パターンに従うことではなく、侵食を追認することです。

よくある不変条件の分類

ほとんどのシステムでガードする価値がある例です。必須事項ではありません。

• 懸念事項ごとに正規の責任者を一つだけ設けます（keeping-one-source-of-truth を参照）。
• 依存関係の方向：ドメインから配信メカニズムをインポートしません。
• クリティカルパスの分離：ホットパスで I/O を行わず、遅い依存関係やオプションの依存関係を使用しません。
• フェイルクローズ境界：ゲートが評価できない場合は拒否します（handling-failures を参照）。
• マイグレーションの不変性（principal-engineering の厳格なルールを参照）。

よくある間違い

• クラス名だらけの原則ドキュメント：タイトルを間違えた実現ドキュメントです。分割してください。
• 「とりあえず」インポートを追加すること。便利だからという理由での単発のインポートによって境界は崩れます。個々の違反にはもっともらしい理由があるからこそ、ガードが存在します。
• レビューで主張されているのにビルドには含まれていない不変条件：適切なレビュアーがいるときだけ適用されます。
• 適合するコストを理由に違反を正当化すること。コストに関する主張が正しい場合もありますが、正しい対応は、不変条件を所有者が判断して改定し（インストール済みの場合は recording-decisions を介して）記録することです。仕様の中でひっそりと例外を設けてはいけません。
• 原則を契約（「モジュール X はモジュール Y を決してインポートしない」）ではなく、好み（「小さなモジュールを推奨する」）として書くこと。契約に違反すればビルドを失敗させられますが、好みに違反しても気分を損なうだけです。