go-best-practices

Go のベストプラクティス

パターン	適用する場面
最小限の main	新しいバイナリ
単一のブートストラップ	モード間でのアプリケーションの配線
順序を考慮したシャットダウン	長時間実行されるプロセス
ノンブロッキングのファンアウト	チャネルベースのイベントシステム
並行処理のテスト	goroutine を使うコード全般
階層化された設定	複数ソースからの設定
クロスプラットフォーム対応のパス	ファイル／設定パスの解決
安全なデバッグログ	HTTP クライアントの計装
ゴールデンテストのマトリクス	レンダリング／出力コンポーネント
焦点を絞ったリンター	CI パイプラインの設定

コード例については、references/patterns.md を参照してください。

ルール

1. main.go はスタブにします。 cmd.Execute() を呼び出し、それ以外は何もしません。診断機能（pprof）は環境変数で有効化します。

2. ブートストラップ経路は 1 つにします。 すべてのモード（対話型、ヘッドレス、テスト）で同じ初期化関数を共有します。経路が 2 つあると、実装にずれが生じます。

3. 順序を考慮してシャットダウンします。 依存先より先に依存元をキャンセルし、その後、独立したクリーンアップをタイムアウト付きコンテキストのもとで並列実行します。並列フェーズでは WaitGroup を使用して待機します。

4. 送信側をブロックしてはいけません。 明示的な破棄ポリシーを設け、チャネルへの送信はノンブロッキングにします。破棄はデバッグレベルでログに記録します。ポリシーを文書化してください。

5. 並行処理は仕組みを使ってテストします。 タイミングの決定性には testing/synctest を、リークの検出には goleak.VerifyNone を使用し、タイマー／チャネルのデッドロックには専用のリグレッションテストを用意します。

6. 設定の優先順位を明示します。 グローバル → プロジェクト → フラグの順にします。CWD から上位へたどってプロジェクト設定を見つけ、逆順にして最も近い設定を優先し、ディープマージします。

7. プラットフォームパスを一元管理します。 用途ごとに関数を 1 つ設けます。解決順序は、環境変数による上書き → XDG → プラットフォームのデフォルト → フォールバックです。

8. デバッグログではシークレットをマスキングします。 http.RoundTripper をラップします。authorization、api-key、token、secret に一致するヘッダーをフィルタリングします。本番環境での割り当てを避けるため、デバッグレベルの場合のみ有効にします。

9. マトリクスにはゴールデンテストを使用します。 複数の軸（レイアウト × テーマ × サイズ）を、並列サブテストとして組み合わせます。連続する範囲を網羅して、オフバイワンのバグを検出します。

10. すべてのリンターではなく、焦点を絞ったリンターを使います。 実際のバグを検出するもの（bodyclose、noctx、tparallel）を有効にします。ノイズの多いデフォルトは無効にします。プロジェクト固有のチェックはスクリプトとして追加します。テストでは常に -race を使用します。