modular-go

modular-go

小規模で、役割が明確で、進化させやすい Go パッケージを設計するための簡潔なガイダンスです。

目的と適用場面

• Go パッケージの設計、リファクタリング、コードレビューに使用します。
• API の境界、状態のモデル化、処理フローの分解に焦点を当てます。
• 適切な抽象化レベルを判断する際に使用します。ローカルヘルパー、ユーティリティパッケージ、マネージャー、ビルダーなどが対象です。
• 利便性のためのエクスポートより、明示的な境界を優先します。

設計原則

1. エクスポートするものはすべて約束になります。公開範囲は最小限に保ち、意図を明確にします。
2. 1 つのパッケージには、1 文で説明できる 1 つの責務を持たせます。
3. 幅広さより深さを優先します。豊かな実装を隠す狭いインターフェースは、幅広く浅いインターフェースより長持ちします。
4. デフォルトではステートレスにします。可変状態は負債とみなし、そのライフサイクルコストに見合う理由がある場合にのみ導入します。
5. ファイルサイズではなく、責務の境界に沿って分割します。新しい境界を設ける場合は、間接化のコストに見合う価値が必要です。
6. オーケストレーションで全体の流れを示し、機能メソッドで処理を実行します。
7. 境界は変換レイヤーです。エラー、型、プロトコルの変換はコアロジックではなく境界で行います。
8. 実際の問題を解決する最小の抽象化を選び、早すぎる汎用化を避けます。
9. ライフサイクルは設計上の重要事項です。起動パスと併せて終了パスも設計します。

ワークフロー

1. パッケージの責務を 1 つ定義します。
2. 明確でわかりやすい主要なエントリーポイント（型、インターフェース、または関数）を 1 つ公開します。
3. デフォルトではヘルパーをローカルに保ち、パッケージ間で実際に再利用する場合にのみ xxxutil に切り出します。
4. トランスポートハンドラーはプロトコルのマッピングに専念させ、処理は注入された依存関係に委譲します。
5. 役割に特化した関数を組み合わせてオーケストレーションを構成し、各段階の意図を短いコメントで示します。
6. パッケージを 1 文で説明できなくなったら、境界を見直します。
7. マージ前に、リファレンスのチェックリストに照らして再確認します。

トピック

トピック	ガイダンス	リファレンス
モジュール境界	API を最小限にし、深いインターフェースと広いインターフェースを分ける	references/module-boundary.md
状態の流れ	ステートレス関数と一度限りの状態オブジェクトを使用する	references/state-flow.md
オーケストレーション	単一の公開エグゼキューターと内部ヘルパーを使用する	references/orchestration.md
gRPC の実践	ハンドラーは薄い変換レイヤーとし、トランスポートをドメインから分離する	references/grpc-practices.md
レビューチェックリスト	マージ前に、手早くアーキテクチャの健全性を確認する	references/review-checklist.md

リファレンス

• リファレンスファイルは、意図的に短く、タスクに焦点を絞っています。
• ソースへのリンクは、各リファレンスファイルのフロントマター urls に記載されています。