ペルソナ: あなたはGoエンジニアであり、設定をレイヤー化されたシステムとして扱います。フラグが環境変数を優先し、環境変数がファイルを優先し、ファイルがデフォルトを優先します。そしてすべてのキーをバインドして、4つのレイヤーすべてを1つのAPIから到達可能に保ちます。

spf13/viper を使用した Go でのレイヤー化された設定

Viper は複数のソースから設定値を固定の優先順位に従って解決します。ユーザー向けのインターフェースはありません。コマンドやフラグを定義しません。その役割は「キー X の値は現在何か」という質問に対して、ソースレイヤーを最高優先度から最低優先度まで歩むことで答えることです。

公式リソース:

• pkg.go.dev/github.com/spf13/viper
• github.com/spf13/viper

このスキルは完全ではありません。詳細情報についてはライブラリドキュメントとコード例を参照してください。Context7 は発見可能性プラットフォームとして役立つことができます。

go get github.com/spf13/viper@latest

Viper vs. cobra

Cobra はコマンドツリーを保有しています。サブコマンド、フラグ、引数検証、補完です。Viper は設定解決を保有しています。「キー X の値は何か」という質問に対して、ソースレイヤーを歩くことで答えます。Viper はユーザー向けのインターフェースがありません。純粋にキー・バリュー解決器です。フラグのみの CLI には cobra だけを使用します。設定ファイルデーモンには viper だけを使用します。両方が必要な場合は両方を使用し、PersistentPreRunE で BindPFlag 経由でフラグをバインドします。

→ この統合の cobra 側については、samber/cc-skills-golang@golang-spf13-cobra を参照してください。

優先度パイプライン

Viper はこの順序でソースを歩いてキーを解決します（最初に設定された値が勝ちます）:

1. explicit Set()      — viper.Set("key", val)    最高優先度
2. フラグ             — バインドされた pflag.Flag
3. 環境変数            — BindEnv / AutomaticEnv
4. 設定ファイル        — ReadInConfig / MergeInConfig
5. KV リモート        — etcd / Consul
6. デフォルト         — viper.SetDefault("key", val)   最低優先度

このパイプラインは固定であり、再順序付けできません。これを理解することは、ほとんどの viper バグを防ぎます。設定ファイルから来るべき「はずの」キーが、環境変数またはデフォルト値を持つフラグで影を落とされるかもしれません。

ソースと設定ファイル

viper.SetConfigName("config")
viper.AddConfigPath("$HOME/.myapp")
if err := viper.ReadInConfig(); err != nil {
    var notFound *viper.ConfigFileNotFoundError
    if !errors.As(err, &notFound) {
        return fmt.Errorf("reading config: %w", err) // 実際のエラーのみを伝播
    }
}

ConfigFileNotFoundError は正常に処理する必要があります。設定ファイルは通常オプションです。欠落ファイルからの未処理のエラーは、フラグまたは環境変数のみで実行すれば完全に有効なプログラムをクラッシュさせます。

サポートされている形式（JSON、TOML、YAML、HCL、INI、properties）、MergeInConfig、リモート KV については、sources-and-formats.md を参照してください。

環境変数バインディングとキー置換

これは viper で最も高いバグ密度の領域です。3つの設定すべてをまとめて接続する必要があります。いずれかが欠けるとネストされたキー解決が破損します:

// ✓ 良い — スタートアップで3つすべてが接続されている
viper.SetEnvPrefix("MYAPP")                             // 衝突を防ぐ: PORT → MYAPP_PORT
viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))  // database.host → MYAPP_DATABASE_HOST
viper.AutomaticEnv()

// ✗ 悪い — SetEnvKeyReplacer がないと、viper は MYAPP_DATABASE.HOST を探す (ドット保持)

BindEnv、AllowEmptyEnv、環境変数対デフォルトの相互作用については、binding-and-env.md を参照してください。

フラグバインディング (cobra の接合部)

cobra フラグを viper に init() または PersistentPreRunE でバインドします。RunE ではバインドしないでください（遅すぎます。cobra は RunE 実行前にフラグをパースします）:

func init() {
    rootCmd.PersistentFlags().Int("port", 8080, "listen port")
    viper.BindPFlag("port", rootCmd.PersistentFlags().Lookup("port"))
    // viper.BindPFlags(cmd.Flags()) — FlagSet 全体を一度にバインド
}

AllowEmptyEnv とフラグ/環境変数の相互作用の詳細については、binding-and-env.md を参照してください。

構造体へのアンマーシャル

viper.Unmarshal は mapstructure を使用して解決された設定を構造体にマップします:

type Config struct {
    Port     int `mapstructure:"port"`
    Database struct {
        MaxConn int `mapstructure:"max_conn"` // 明示的なタグ: mapstructure はアンダースコア→キャメルケースを変換しません
    } `mapstructure:"database"`
}
var cfg Config
viper.Unmarshal(&cfg)

常に mapstructure タグを使用してください — 暗黙的なマッピングはネストされた構造体とアンダースコア名付きフィールドに対して脆弱です。Sub("database").Unmarshal より UnmarshalKey("database", &dbCfg) を優先してください。キーが欠落している場合、Sub が必要とする nil チェックを避けます。

time.Duration / net.IP / スライスデコーダーおよびカスタム DecodeHook 登録については、unmarshal.md を参照してください。

サブツリー

viper.Sub("database") はプレフィックスにスコープされた新しい *viper.Viper を返すか、キーが存在しない場合は nil を返します。結果に対してメソッドを呼び出す前に常に nil チェックしてください。nil リスクを完全に避ける UnmarshalKey("database", &dbCfg) を優先してください。

ホットリロード

viper.WatchConfig()
viper.OnConfigChange(func(e fsnotify.Event) { /* 変更された値を再適用 */ })

WatchConfig は fsnotify を使用し、inode を監視します。アトミックリネーム経由で書き込むエディタ（vim、neovim）は inode を置き換えます。コールバックは発火しないかもしれません。ホットリロードを echo >> config.yaml でテストします。エディタの保存ではなく。レース安全なリロードパターンについては、watch-and-reload.md を参照してください。

テスト分離

テストではグローバル viper を使用しないでください — テストケース間で状態がリークします。テストごとに viper.New() を使用して、各インスタンスが分離されます:

v := viper.New()
v.SetConfigFile("testdata/config.yaml")
require.NoError(t, v.ReadInConfig())

t.Setenv の相互作用と Reset() の制限については、testing-and-isolation.md を参照してください。

ベストプラクティス

1. プレフィックス + キー置換 + AutomaticEnv をまとめて設定 — いずれかが欠けるとネストされた環境変数キーは無言で解決されません（database.host → DATABASE.HOST の代わりに DATABASE_HOST）。
2. ConfigFileNotFoundError を正常に処理 — 欠落した設定ファイルはフラグと環境変数のみで実行されるサービスをクラッシュさせるべきではありません。
3. 設定構造体に常に mapstructure タグを使用 — 暗黙的なマッピングはネストされたアンダースコア名付きフィールドを無言で見落とします。
4. テストでは viper.New() を使用、グローバルを使用しない — グローバルはテスト実行間で状態を蓄積します。テストごとのインスタンスは分離されています。
5. Execute() 前にフラグをバインド — RunE でバインディングすると遅すぎます。cobra は RunE 実行前にフラグをパースします。

よくある間違い

間違い	失敗する理由	修正
SetEnvKeyReplacer なし AutomaticEnv	database.host は MYAPP_DATABASE.HOST を探す（ドット保持）— マッチしない	AutomaticEnv 前に SetEnvKeyReplacer(strings.NewReplacer(".", "_")) を追加
構造体フィールドに mapstructure タグなし	ネストされたアンダースコア名付きフィールドを無言で見落とす	すべてのフィールドに mapstructure:"key_name" を追加
テストでグローバル viper を使用	あるテストからの状態が次のテストを汚染し、フレーキーな順序付けを引き起こす	テストごとに viper.New() を作成
ConfigFileNotFoundError チェック欠落	欠落した設定ファイルはフラグ/環境変数のみで実行するべきサービスをクラッシュさせる	errors.As(err, &notFound) — not-found 以外のエラーのみを伝播

さらに読む

• sources-and-formats.md — サポートされているファイル形式、マルチパス検索、MergeInConfig、リモート KV（etcd/Consul）
• binding-and-env.md — BindEnv、AutomaticEnv、SetEnvPrefix、SetEnvKeyReplacer、AllowEmptyEnv、タイミングルール
• unmarshal.md — Unmarshal、UnmarshalKey、mapstructure タグ、カスタム DecodeHooks（Duration、IP、スライス）
• watch-and-reload.md — WatchConfig、OnConfigChange、fsnotify の注意点、アトミックリネームの罠、レース安全パターン
• testing-and-isolation.md — テストごとの viper.New()、t.Setenv の相互作用、Reset() の制限、スナップショット/復元

クロスリファレンス

• → 一般的な CLI アーキテクチャについては samber/cc-skills-golang@golang-cli スキルを参照してください。プロジェクトレイアウト、終了コード、シグナルハンドリング、cobra+viper 統合
• → この統合の cobra 側については samber/cc-skills-golang@golang-spf13-cobra スキルを参照してください（フラグ定義とバインディング）
• → 一般的な Go テストパターンについては samber/cc-skills-golang@golang-testing スキルを参照してください

spf13/viper でバグまたは予期しない動作が発生した場合は、https://github.com/spf13/viper/issues で issue をオープンしてください。