Go パッケージとインポート

このスキルが適用されない場合: パッケージ内の個別の識別子の命名については、go-naming を参照してください。単一ファイル内の関数の編成については、go-functions を参照してください。インポート規則を強制するリンターの設定については、go-linting を参照してください。

パッケージの編成

Util パッケージを避ける

パッケージ名は、パッケージが提供するものを説明する必要があります。util、helper、common のような一般的な名前は避けてください。意味を曖昧にし、インポート競合を引き起こします。

// 良い例: 意味のあるパッケージ名
db := spannertest.NewDatabaseFromFile(...)
_, err := f.Seek(0, io.SeekStart)

// 悪い例: 曖昧な名前は意味を隠す
db := test.NewDatabaseFromFile(...)
_, err := f.Seek(0, common.SeekStart)

一般的な名前は名前の一部として使用できます (例: stringutil) が、パッケージ全体の名前になるべきではありません。

パッケージサイズ

質問	アクション
目的を 1 文で説明できますか?	いいえ → 責務ごとに分割
ファイルがエクスポートされていないシンボルを共有しない?	これらのファイルは別のパッケージにできます
ユーザーグループが異なる部分を使用する?	ユーザーの境界に沿って分割
Godoc ページが圧倒的?	発見性を改善するために分割

分割しないでください: ファイルが長いだけの理由、単一型パッケージを作成するため、または循環依存を作成する場合。

パッケージを分割するか結合するか、パッケージ内でファイルを編成するか、CLI プログラムを構造化するかを決定するときは、references/PACKAGE-SIZE.md を読んでください。

---

インポート

インポートは空行で区切られたグループに編成されます。標準ライブラリパッケージが常に最初に来ます。goimports を使用して自動的に管理してください。

import (
    "fmt"
    "os"

    "github.com/foo/bar"
    "rsc.io/goversion/version"
)

クイックルール:

ルール	ガイダンス
グループ化	stdlib が最初、その後外部。拡張: stdlib → その他 → proto → 副作用
名前変更	衝突がない限り避けてください。最も局所的なインポートの名前を変更します。Proto パッケージは pb サフィックス付き
ブランクインポート (import _)	main パッケージまたはテストのみ
ドットインポート (import .)	循環依存テストファイルを除き、決して使用しないでください

拡張グループ化でインポートを編成する、proto パッケージの名前を変更する、またはブランク/ドットインポートを決定するときは、references/IMPORTS.md を読んでください。

---

init() を避ける

可能な限り init() を避けてください。避けられない場合、次の要件を満たす必要があります:

1. 完全に決定的である
2. 他の init() の順序付けから独立している
3. 環境状態がない (環境変数、作業ディレクトリ、引数)
4. I/O がない (ファイルシステム、ネットワーク、システムコール)

許容される使用: 単一の割り当てにできない複雑な式、プラグイン可能なフック (database/sql ダイアレクトなど)、決定的な事前計算。

init() を明示的な関数にリファクタリングする必要がある場合、または許容される init() の使用を理解する場合は、references/PACKAGE-SIZE.md を読んでください。

---

Main での終了

os.Exit または log.Fatal* を呼び出すのは main() でのみ です。他のすべての関数はエラーを返すべきです。

理由: 明らかでない制御フロー、テスト不可能、defer ステートメントがスキップされます。

ベストプラクティス: run() パターンを使用します — ロジックを func run() error に抽出し、単一の終了ポイントで main() から呼び出します:

func main() {
    if err := run(); err != nil {
        log.Fatal(err)
    }
}

run() パターンを実装する、CLI サブコマンドを構造化する、またはフラグ命名規則を選択するときは、references/PACKAGE-SIZE.md を読んでください。

---

コマンドラインフラグ

アドバイス: フラグは package main でのみ定義してください。

• フラグ名は snake_case を使用します: --outputDir ではなく --output_dir
• ライブラリはパラメータとして設定を受け入れるべき、直接フラグを読むべきではありません — これにより、テスト可能で再利用可能なままになります
• 標準の flag パッケージを優先します。POSIX 規約 (ダブルダッシュ、シングルキャラクタショートカット) が必要な場合のみ pflag を使用します

// 良い例: main でのフラグ、ライブラリへのパラメータとして渡される
func main() {
    outputDir := flag.String("output_dir", ".", "directory for output files")
    flag.Parse()
    if err := mylib.Generate(*outputDir); err != nil {
        log.Fatal(err)
    }
}

---

関連スキル

• パッケージの命名: パッケージ名の選択、スタッタリングの回避、またはエクスポートされたシンボルの命名については、go-naming を参照してください
• パッケージ間のエラーハンドリング: %w vs %v でパッケージ境界でエラーをラップするときは、go-error-handling を参照してください
• インポートリント: goimports local-prefixes を設定したり、インポートグループ化を強制したりするときは、go-linting を参照してください
• グローバル状態: init() を明示的な初期化で置き換えたり、可変グローバルを避けたりするときは、go-defensive を参照してください