ペルソナ: あなたは dig でアプリケーショングラフを配線する Go アーキテクトです。コンテナを composition root に配置し、具象型ではなくインターフェースに依存し、コンストラクタエラーを第一級の失敗として扱います。

Go での uber-go/dig を使用した依存性注入

リフレクションベースの DI ツールキット。アプリケーションフレームワークを強化するために設計されており（uber-go/fx の基盤となっています）、スタートアップ時にオブジェクトグラフを解決します。

公式リソース:

• pkg.go.dev/go.uber.org/dig
• github.com/uber-go/dig

このスキルはすべてを網羅しているわけではありません。詳細については、ライブラリドキュメントとコード例を参照してください。Context7 は発見プラットフォームとして支援できます。

go get go.uber.org/dig

dig vs. fx

fx は dig の上に構築され、同じコンテナエンジンを共有しています — DI プリミティブ（Provide、Invoke、In/Out 構造体、名前付き値、値グループ）は同一です。fx.In/fx.Out は dig.In/dig.Out の再エクスポートです。

fx が dig の上に追加するもの:

関心事	dig	fx
DI コンテナ	✅ dig.New()	✅ (組み込み)
ライフサイクルフック	❌	✅ fx.Lifecycle OnStart/OnStop
モジュールシステム	❌	✅ スコープ付きデコレータを持つ fx.Module
シグナル対応実行ループ	❌	✅ app.Run() は SIGINT/SIGTERM でブロック
構造化イベントロギング	❌	✅ fx.WithLogger / fxevent
スタートアップ/シャットダウンタイムアウト	❌	✅ fx.StartTimeout / fx.StopTimeout

dig を選択 する場合: 配線グラフのみが必要なとき — CLI ツール、呼び出し元に公開するコンテナを持つライブラリ、テストハーネス、またはライフサイクルを独自に管理する既存アプリケーションへの DI の埋め込み。

fx を選択 する場合: 長実行サービス（HTTP サーバー、ワーカー、デーモン）— ライフサイクルとシグナル処理はそこでは非交渉です。samber/cc-skills-golang@golang-uber-fx スキルを参照してください。

コンテナ

import "go.uber.org/dig"

c := dig.New()

便利なオプション: dig.DeferAcyclicVerification()（より高速なスタートアップ）、dig.RecoverFromPanics()（パニックを dig.PanicError に変換）、dig.DryRun(true)（呼び出さずに検証）。

Provide と Invoke

// コンストラクタを登録 — 遅延実行、出力が必要になったときのみ実行
err := c.Provide(func(cfg *Config) (*sql.DB, error) {
    return sql.Open("postgres", cfg.DSN)
})

// コンテナからサービスを取得 — 関数パラメータとして要求することで
err = c.Invoke(func(db *sql.DB) error {
    return db.Ping()
})

コンストラクタは遅延実行でありメモ化されます：各出力型は一度構築され、共有されます（コンテナごとのシングルトン）。Provide はコンストラクタが不正な場合は登録時にエラーになります；Invoke はコンストラクタのエラーを、それを誘発した依存パスとともに返します。

dig コンストラクタはあらゆる関数です。入力は依存性、出力は提供される型です。error（最後の戻り値）は構築失敗を通知します。「インターフェースを受け入れ、構造体を返す」に従います。

dig.In を使用したパラメータオブジェクト

コンストラクタが 4 個以上の依存性を持つようになったら、dig.In を埋め込んで、構造体フィールドにグループ化し、フィールドにタグを付けます：

type HandlerParams struct {
    dig.In

    Logger *zap.Logger
    DB     *sql.DB
    Cache  *redis.Client `optional:"true"`           // 提供されない場合はゼロ値
    DBRO   *sql.DB       `name:"readonly"`           // 名前付き依存性
    Routes []http.Handler `group:"routes"`           // 値グループ
}

func NewHandler(p HandlerParams) *Handler { /* ... */ }

タグ: name:"...", optional:"true", group:"...".

dig.Out を使用した結果オブジェクト

1 つのコンストラクタから複数の値を返し、結果に name/group タグを付けます：

type ConnResult struct {
    dig.Out

    ReadWrite *sql.DB `name:"primary"`
    ReadOnly  *sql.DB `name:"readonly"`
}

func NewConnections(cfg *Config) (ConnResult, error) { /* ... */ }

名前付き値

同じ型の 2 つのプロバイダはと衝突します。dig.Name で区別します：

c.Provide(NewPrimaryDB,  dig.Name("primary"))
c.Provide(NewReadOnlyDB, dig.Name("readonly"))

dig.In フィールドに name:"primary" / name:"readonly" を追加して消費します。

値グループ

多くのプロバイダ、1 つのコンシューマスライス — HTTP ハンドラ、ヘルスチェック、マイグレーションの典型例：

type RouteResult struct {
    dig.Out
    Handler http.Handler `group:"routes"`
}

func NewUserHandler(db *sql.DB) RouteResult { /* ... */ }
func NewPostHandler(db *sql.DB) RouteResult { /* ... */ }

type ServerParams struct {
    dig.In
    Routes []http.Handler `group:"routes"`
}

フラットン — ,flatten を追加（例：group:"routes,flatten"）して、スライスをネストするのではなく展開します。グループの順序は保証されていません；順序が重要な場合は、1 つのコンストラクタから明示的な順序付きスライスを提供します。

インターフェースとしての提供（dig.As）

具象コンストラクタを登録し、別のアダプタなしで 1 つ以上のインターフェースの下で公開します：

c.Provide(NewPostgresDB, dig.As(new(Database), new(io.Closer)))
// コンシューマは Database または io.Closer を要求；*PostgresDB は隠されています。

完全なアプリケーション例

func main() {
    c := dig.New()

    must(c.Provide(NewConfig))
    must(c.Provide(NewLogger))
    must(c.Provide(NewDatabase))
    must(c.Provide(NewServer))

    err := c.Invoke(func(srv *http.Server) error {
        return srv.ListenAndServe()
    })
    if err != nil {
        log.Fatal(err)
    }
}

func must(err error) { if err != nil { panic(err) } }

dig には組み込みライフサイクルがありません。OnStart/OnStop フック、シグナル処理、グレースフルシャットダウンが必要な場合は、fx を使用してください — samber/cc-skills-golang@golang-uber-fx スキルを参照してください。

Decorate、Scopes、オプションの依存性、エラーヘルパー、および Visualize については、advanced.md を参照してください。

ベストプラクティス

1. コンテナを composition root に配置します — *dig.Container をパラメータとして渡さないでください；これは main() の配管の詳細のように扱います。サービスロケータパターンは DI の テスト可能性の利益を損なわせます。
2. 具象型ではなくインターフェースに依存します — テストで本番環境コードに触れることなく実装を入れ替えることができ、dig.As を使用して広い構造体から狭いインターフェースを公開できます。
3. コンストラクタが 4 個以上の依存性を持つようになったら、パラメータオブジェクト（dig.In 構造体）を優先します — コールサイトは読みやすいままで、新しい依存性を追加するのは 1 行変更で済み、署名の破壊になりません。
4. モジュールで登録をグループ化します（モジュールごと 1 ファイル、そのモジュールに対して c.Provide を呼び出します）— レビューとリファクタリングはモジュール単位の関心事になり、後で fx.Module にモジュールを抽出するときに配線を書き直さずに済みます。
5. テストでグラフを熱心に検証します — 組成ルートに対して CI で c.Invoke を呼び出し、最初のリクエストではなくブート時に不足しているプロバイダを表面化させます。DryRun(true) はコンストラクタ実行をスキップします。
6. パニックではなくコンストラクタからエラーを返します — dig はそれを依存パスでラップし、失敗ポイントを明らかにします。

よくある間違い

間違い	修正
サービスにコンテナを渡す	コンテナは main() に属します。サービスが必要とする型付き依存性を注入してください；そうしないとテストが本当のコンテナを構築する必要があります。
Name なしで同じ型に対して 2 つのプロバイダがある	dig は Provide 時にエラーになります。いずれかに名前を付けるか、dig.Out 結果構造体を返す単一のプロバイダにマージしてください。
Provide エラーを無視する	各 Provide を must ヘルパーでラップしてください。無声の登録エラーは後ではるか後の欠落型エラーになります。
グループを使用する場合、順序が重要である	グループは順序なしです。順序が重要な場合（ミドルウェアチェーン、マイグレーション順序）、1 つのコンストラクタで明示的な順序付きスライスを提供してください。
インポート時に副作用を持つコンストラクタ	init() を空のままにしてください — グラフが構築された後、コンストラクタ内でのみ作業を開始します。

テスト

dig コンテナは安価です — テストごとに新しいものを構築し、Decorate でプロバイダをオーバーライドし、Invoke を呼び出してシステムを駆動します。完全なパターン（テストごとの配線、共有ヘルパー、CI でのグラフ検証、配線時エラーのアサーション、コンストラクタパニックからの回復）については、testing.md を参照してください。

さらに読む

• advanced.md — Decorate、Scopes、オプションの依存性、エラーヘルパー、Visualize、完全なクイックリファレンス
• recipes.md — エンドツーエンドの例：ルートグループを持つ HTTP サーバー、2 つのデータベース、リクエストスコープ、デコレータ、ドライラン検証
• testing.md — テストパターンとグラフ検証

相互参照

• → samber/cc-skills-golang@golang-uber-fx スキルを参照してください。アプリケーションライフサイクル、モジュール、および dig の上に構築されたシグナル対応 Run() について
• → samber/cc-skills-golang@golang-dependency-injection スキルを参照してください。DI の概念とライブラリ比較について
• → samber/cc-skills-golang@golang-samber-do スキルを参照してください。リフレクションなしのジェネリクスベースの代替案について
• → samber/cc-skills-golang@golang-google-wire スキルを参照してください。コンパイル時 DI（ランタイムコンテナなし）について
• → samber/cc-skills-golang@golang-structs-interfaces スキルを参照してください。インターフェース設計パターンについて
• → samber/cc-skills-golang@golang-testing スキルを参照してください。一般的なテストパターンについて

uber-go/dig でバグまたは予期しない動作に遭遇した場合は、https://github.com/uber-go/dig/issues で issue をオープンしてください。