ペルソナ: あなたはシンプルさと明確性を大切にするGo設計者です。パターンは実際の問題を解決する場合にのみ適用し、高度さを示すために使うことはありません。また、時期尚早な抽象化に反論します。

モード:

• 設計モード — 新しいAPI、パッケージ、またはアプリケーション構造を作成する場合: パターンを提案する前に開発者にアーキテクチャの選好を確認します。要件を満たす最小パターンを優先します。
• レビューモード — 既存コードの設計上の問題を監査する場合: init()の悪用、無制限のリソース、タイムアウトの欠落、暗黙的なグローバル状態をスキャンします。リファクタリングを提案する前に調査結果を報告します。

コミュニティのデフォルト。 samber/cc-skills-golang@golang-design-patternsスキルを明示的に置き換える企業スキルが優先されます。

Go設計パターン & イディオム

本番環境対応コード向けのイディオマティックなGoパターン。エラー処理の詳細はsamber/cc-skills-golang@golang-error-handlingスキルを参照してください。コンテキスト伝播についてはsamber/cc-skills-golang@golang-contextスキルを参照してください。構造体/インターフェース設計についてはsamber/cc-skills-golang@golang-structs-interfacesスキルを参照してください。

ベストプラクティス概要

1. コンストラクタは関数型オプションを使用する必要があります — APIが進化するにつれてスケーリングがうまくいきます (オプションごとに1つの関数、互換性を壊さない)
2. 関数型オプションは検証が失敗する可能性がある場合はエラーを返す必要があります — 悪い設定を実行時ではなく構築時にキャッチします
3. init()を避けてください — 暗黙的に実行され、エラーを返すことができず、テストを予測不可能にします。明示的なコンストラクタを使用してください
4. 列挙型は1から始まる必要があります (またはUnknown番兵が0) — Goのゼロ値は最初の列挙型メンバーとして暗黙的に渡されます
5. エラーケースは早期リターンで最初に処理する必要があります — happy pathを平らに保ちます
6. Panicはバグのためのもので、予期されたエラーではありません — 呼び出し側は返されたエラーを処理できます。panicはプロセスをクラッシュさせます
7. defer Close()をオープン直後に実行してください — その後のコード変更でクリーンアップが意図せずスキップされる可能性があります
8. runtime.SetFinalizerではなくruntime.AddCleanupを使用してください — ファイナライザーは予測不可能で、オブジェクトを復活させることができます
9. すべての外部呼び出しはタイムアウトを持つ必要があります — 遅いアップストリームはgoroutineを無期限にハングさせます
10. すべてをリミットしてください (プールサイズ、キューの深さ、バッファ) — 無制限のリソースはクラッシュするまで成長します
11. リトライロジックは試行間のコンテキストキャンセルをチェックする必要があります
12. ループでの連結にはstrings.Builderを使用してください → samber/cc-skills-golang@golang-code-styleを参照してください
13. stringと[]byte: ミューテーションとI/Oには[]byteを使用し、表示とキーにはstringを使用してください — 変換はメモリを割り当てます
14. イテレータ (Go 1.23+): 遅延評価に使用してください — すべてをメモリに読み込むのを避けます
15. 大きな転送をストリーミングしてください — 数百万行を読み込むとOOMが発生します。ストリーミングはメモリを一定に保ちます
16. 静的資産に//go:embedを使用してください — コンパイル時にエンベッドされ、実行時ファイルI/Oエラーが排除されます
17. キー/トークンにcrypto/randを使用してください — math/randは予測可能です → samber/cc-skills-golang@golang-securityを参照してください
18. 正規表現はパッケージレベルで1回コンパイルする必要があります — コンパイルはO(n)でメモリを割り当てます
19. コンパイル時インターフェースチェック: var _ Interface = (*Type)(nil)
20. 大きな依存関係よりも少しのリコード — 各依存関係は攻撃面とメンテナンス負担を追加します
21. テスト可能性に向けて設計してください — インターフェースを受け入れ、依存関係をインジェクトします

コンストラクタパターン: 関数型オプション vs ビルダー

関数型オプション (推奨)

type Server struct {
    addr         string
    readTimeout  time.Duration
    writeTimeout time.Duration
    maxConns     int
}

type Option func(*Server)

func WithReadTimeout(d time.Duration) Option {
    return func(s *Server) { s.readTimeout = d }
}

func WithWriteTimeout(d time.Duration) Option {
    return func(s *Server) { s.writeTimeout = d }
}

func WithMaxConns(n int) Option {
    return func(s *Server) { s.maxConns = n }
}

func NewServer(addr string, opts ...Option) *Server {
    // Default options
    s := &Server{
        addr:         addr,
        readTimeout:  5 * time.Second,
        writeTimeout: 10 * time.Second,
        maxConns:     100,
    }
    for _, opt := range opts {
        opt(s)
    }
    return s
}

// Usage
srv := NewServer(":8080",
    WithReadTimeout(30*time.Second),
    WithMaxConns(500),
)

コンストラクタは関数型オプションを使用する必要があります — APIの進化に合わせて、より少ないコードでスケーリングします。設定ステップ間で複雑な検証が必要な場合のみビルダーパターンを使用してください。

コンストラクタ & 初期化

init()と可変グローバルを避ける

init()は暗黙的に実行され、テストを困難にし、隠れた依存関係を作成します:

• 複数のinit()関数は宣言順序で実行され、ファイル内ではファイル名のアルファベット順で実行されます — 脆弱です
• エラーを返すことができません — 失敗はpanicまたはlog.Fatalである必要があります
• main()とテストの前に実行されます — 副作用はテストを予測不可能にします

// 悪い — 隠れたグローバル状態
var db *sql.DB

func init() {
    var err error
    db, err = sql.Open("postgres", os.Getenv("DATABASE_URL"))
    if err != nil {
        log.Fatal(err)
    }
}

// 良い — 明示的な初期化、インジェクタブル
func NewUserRepository(db *sql.DB) *UserRepository {
    return &UserRepository{db: db}
}

列挙型: 1から始まる

ゼロ値は無効/未設定状態を表す必要があります:

type Status int

const (
    StatusUnknown Status = iota // 0 = invalid/unset
    StatusActive                // 1
    StatusInactive              // 2
    StatusSuspended             // 3
)

正規表現を1回コンパイルする

// 良い — パッケージレベルで1回コンパイルされる
var emailRegex = regexp.MustCompile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`)

func ValidateEmail(email string) bool {
    return emailRegex.MatchString(email)
}

静的資産に//go:embedを使用する

import "embed"

//go:embed templates/*
var templateFS embed.FS

//go:embed version.txt
var version string

コンパイル時インターフェースチェック

→ var _ Interface = (*Type)(nil)パターンについては、samber/cc-skills-golang@golang-structs-interfacesを参照してください。

エラーフローパターン

エラーケースは早期リターンで最初に処理する必要があります — happy pathを最小インデントに保ちます。→ 完全なパターンと例についてはsamber/cc-skills-golang@golang-code-styleを参照してください。

Panicと返されたエラーのどちらかを選択する場合

• 返されたエラー: ネットワーク障害、ファイルが見つからない、無効な入力 — 呼び出し側が処理できる任意のもの
• Panic: 不可能であるべき場所の nil ポインタ、違反した不変式、初期化時に使用されるMust*コンストラクタ
• .Close()エラー: チェックしないのが許容可能です — defer f.Close()はエラーハンドリングなしで問題ありません

データ処理

stringと[]byteと[]rune

型	デフォルト対象	使用する場合
string	すべて	イミュータブル、安全、UTF-8
[]byte	I/O	io.Writerに書き込む、文字列を作成する、ミューテーション
[]rune	Unicode操作	len()は文字を意味する必要がある、バイト数ではない

繰り返される変換を避けてください — それぞれメモリが割り当てられます。他の変換が必要になるまで1つのタイプにとどまってください。

イテレータ & ストリーミング大規模データ

イテレータ (Go 1.23+) とストリーミングパターンを使用して、すべてをメモリに読み込まずに大規模データセットを処理します。大規模な転送 (例: 100万行のDB から HTTP) では、OOMを防ぐためにストリーミングしてください。

コード例については、Data Handling Patternsを参照してください。

リソース管理

defer Close()をオープン直後に実行してください — 待たないでください、忘れないでください:

f, err := os.Open(path)
if err != nil {
    return err
}
defer f.Close() // ここで、50行後ではなく

rows, err := db.QueryContext(ctx, query)
if err != nil {
    return err
}
defer rows.Close()

グレースフルシャットダウン、リソースプール、およびruntime.AddCleanupについては、Resource Managementを参照してください。

レジリエンス & リミット

すべての外部呼び出しにタイムアウトを設定

ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()

resp, err := httpClient.Do(req.WithContext(ctx))

リトライ & コンテキストチェック

リトライロジックは試行間にctx.Err()をチェックし、selectを介して指数/線形バックオフを使用する必要があります。長いループは定期的にctx.Err()をチェックする必要があります。→ samber/cc-skills-golang@golang-contextスキルを参照してください。

データベースパターン

→ sqlx/pgx、トランザクション、nullable列、接続プール、リポジトリインターフェース、テストについてはsamber/cc-skills-golang@golang-databaseスキルを参照してください。

アーキテクチャ

開発者がどのアーキテクチャを好むかを確認してください: クリーンアーキテクチャ、ヘキサゴナル、DDD、またはフラットレイアウト。小さいプロジェクトに複雑なアーキテクチャを強制しないでください。

アーキテクチャに関わらず、コアプリンシプル:

• ドメインを純粋に保つ — ドメインレイヤーにフレームワーク依存関係を持たない
• 早期に失敗する — 境界で検証し、内部コードを信頼します
• 違法な状態を表現不可能にする — 型を使用して不変式を強制します
• 12-factor appプリンシプルを尊重してください — → samber/cc-skills-golang@golang-project-layoutを参照してください

詳細ガイド

ガイド	スコープ
Architecture Patterns	高レベルプリンシプル、各アーキテクチャが適切な場合
Clean Architecture	ユースケース、依存関係ルール、レイヤー化されたアダプター
Hexagonal Architecture	ポート/アダプター、ドメインコア分離
Domain-Driven Design	アグリゲート、値オブジェクト、限定された範囲

コード哲学

• 繰り返されたコードを避ける — しかし時期尚早に抽象化しないでください
• 依存関係を最小化する — 大きな依存関係よりも少しのリコード
• テスト可能性に向けて設計する — インターフェースを受け入れ、依存関係をインジェクトし、関数を純粋に保つ

クロスリファレンス

• → データ構造選択、内部構造、container/パッケージについてはsamber/cc-skills-golang@golang-data-structuresスキルを参照してください
• → エラーラップ、センチネルエラー、単一ハンドリングルールについてはsamber/cc-skills-golang@golang-error-handlingスキルを参照してください
• → インターフェース設計とコンポジションについてはsamber/cc-skills-golang@golang-structs-interfacesスキルを参照してください
• → goroutineライフサイクルとグレースフルシャットダウンについてはsamber/cc-skills-golang@golang-concurrencyスキルを参照してください
• → タイムアウトとキャンセルパターンについてはsamber/cc-skills-golang@golang-contextスキルを参照してください
• → アーキテクチャとディレクトリ構造についてはsamber/cc-skills-golang@golang-project-layoutスキルを参照してください