モジュールで組んだネットワークサービスに、境界を守ってモジュールを足す

## モジュール同士を、中身ではなく共通のインターフェースでつなぐ - モジュールシステムを拡張の中心的な境界として扱う。認証、ストレージ、検証、変換、ルーティング、プロトコルエンドポイントは、互いの内部実装を直接呼ぶのではなく、共有フレームワークのインターフェースを実装する。 - 安定したインターフェース、設定プリミティブ、アドレス処理、エラー型、ログ記録の契約は、再利用可能なフレームワーク層に置く。具体的な実装は、役割別の内部パッケージに置く。 - 実行ファイルのエントリポイントは薄く保つ。サービスパッケージを読み込み、組み込みモジュールが登録済みであることを保証し、起動シーケンスを呼び出す役割に限定する。 - 最上位モジュールは、設定と遅延初期化レジストリを通して接続する。各リクエストやメッセージは、照合規則で選ばれた検証器、変更器、配送先ターゲットからなる明示的なパイプラインへ流す。 - 実装は兄弟実装ではなく安定したインターフェースへ依存させ、循環依存を避ける。 ## リポジトリのビルドラッパーでビルドし、影響する所をテストする - 対応しているビルドタグや機能オプションも含め、リポジトリのビルドラッパーを正規のビルド経路として使う。バージョン情報や必須フラグを省く場当たり的なコンパイラーコマンドへ置き換えてはならない。 - 横断的な変更では、ユニットテスト一式を実行する。挙動がプロトコル、ストレージ、配送の境界をまたぐ場合は、文書化された作業ディレクトリから統合テストハーネスを実行する。 - ビルドシステムが行うバージョン情報の埋め込みを維持する。実行環境がネイティブ実装に依存するライブラリを使う場合は、ソースコードを診断する前に、必要なネイティブコンパイラーとライブラリが利用できることを確認する。 - 反復作業中は対象パッケージに絞ったテストを優先し、完了前に直接影響する統合経路を実行する。省略したテストがあれば、具体的な環境上の理由とともに報告する。 ## 新しいモジュールを役割ごとのフォルダに置き、登録する 1. 実装は、検証、配送先、認証、ストレージ、検索、変換、エンドポイント処理など、その役割に対応する内部ディレクトリへ置く。 2. 共通のモジュールライフサイクルインターフェースと、役割固有のインターフェースの両方を実装する。役割の契約は安定したフレームワーク層に置く。 3. 定められた役割接頭辞の命名規則を使い、パッケージ初期化時にファクトリーを登録する。 4. リポジトリが指定する登録用インポートまたはマニフェストを通して、実装をサービスの組み込みモジュール配線へ加える。副作用だけで登録する方式が既定なら、登録コードは副作用専用のままにする。 5. 既存の役割用スケルトンやヘルパーがあれば、それを出発点にする。ステートレス用ヘルパーは、そのモジュールがリクエストをまたぐ可変状態を本当に保持しない場合に限って使う。 6. 設定、登録、正常動作、一時的な失敗、境界エラーの対応付けに焦点を絞ったテストを追加する。 ## 再試行できるかを示し、クライアントに内部の情報を見せないエラーを返す - モジュール境界を越えるエラーには、フレームワークの構造化エラーパッケージを使う。呼び出し元がプロトコル状態、再試行の可否、または原因モジュールを必要とする場合に、分類されていない整形済みエラーを返してはならない。 - 外部向けステータスコード、対応している場合は拡張ステータスまたはサブタイプ、クライアントへ安全に示せる一般的なメッセージ、担当する検査または配送先の名前を含める。 - 一時的な失敗には明示的な印を付け、ディスパッチャーが再試行可能な状態と恒久的な拒否を区別できるようにする。 - クライアントに見えるメッセージには、サーバー設定、内部パス、認証情報、実装詳細を含めない。 - 予期しない内部障害には構造化した診断フィールドを付け、フレームワークのロガーを通して記録する。元の原因は保持するが、リモートクライアントには明かさない。 ## リクエストの間で状態を共有せず、バックグラウンド処理のpanicを回復する - リクエストやメッセージの間で、リクエスト単位の可変状態を決して共有しない。フレームワークの契約が明示的に直列化しない限り、検査と変換は並行して実行されるものとみなす。 - 起動したすべてのgoroutineまたはバックグラウンドタスクは、その境界でpanicを回復し、障害を記録し、1つのタスクがサービス全体を停止させないようにしなければならない。 - 外部識別子は、比較または保存の前に正規化する。ドメインに似た識別子には、独自の整形処理を考案せず、フレームワークが要求するUnicode表現、正規化形式、大文字・小文字の同一視を適用する。 - モジュール設定は、共有の設定マップとライフサイクルメソッドを通して解析する。未知または無効な設定は、既存モジュールと同じ方式で拒否する。 - 言語標準のグローバルロガーではなく、フレームワークのロガーを使う。フレームワークが提供している場合は、操作単位または配送単位のロガーを作り、関連イベントの文脈を維持する。 - マージ前に、登録、設定の解析、並行実行、正規化、構造化した失敗、ログを、それぞれの挙動を証明できる最小の境界でテストして確認する。