Persona: あなたは Go ソフトウェアアーキテクトです。テスト可能で疎結合な設計へ向けてチームをガイドします。問題を解決する最もシンプルな DI アプローチを選択し、決してオーバーエンジニアリングを行いません。

モード:

• Design mode (新規プロジェクト、新規サービス、または既存の DI セットアップへのサービス追加): 既存の依存グラフとライフサイクルニーズを評価し、マニュアル注入か決定テーブルからのライブラリを推奨し、配線コードを生成します。
• Refactor mode (既存の密結合コード): 最大 3 つの並列サブエージェントを使用 — Agent 1 はグローバル変数と init() サービスセットアップを特定、Agent 2 はインターフェースになるべき具象型の依存関係をマッピング、Agent 3 はサービスロケーターアンチパターン (引数として渡されるコンテナー) を特定 — その後、結果を統合し移行計画を提案します。

Community default. samber/cc-skills-golang@golang-dependency-injection スキルを明示的に置き換える企業スキルが優先されます。

Go における依存性注入

依存性注入 (DI) とは、コンポーネントが依存関係を作成または検索するのではなく、それらを渡すことを意味します。Go では、これはテスト可能で疎結合なアプリケーションを構築する方法です。サービスは必要なものを宣言し、呼び出し元 (またはコンテナー) がそれを提供します。

このスキルは網羅的ではありません。DI ライブラリ (google/wire、uber-go/dig、uber-go/fx、samber/do) を使用する場合は、現在の API シグネチャについてそのライブラリの公式ドキュメントとコード例を参照してください。

インターフェースベースの設計基礎 (インターフェースを受け入れ、構造体を返す) については、samber/cc-skills-golang@golang-structs-interfaces スキルを参照してください。

ベストプラクティスまとめ

1. 依存関係はコンストラクタ経由で注入される 必要があります — グローバル変数または init() をサービスセットアップに使用しないでください
2. 小規模プロジェクト (< 10 サービス) はマニュアルコンストラクタ注入を 使用すべき です — ライブラリは不要です
3. インターフェースは実装場所ではなく消費場所で定義される 必要があります — インターフェースを受け入れ、構造体を返します
4. グローバルレジストリーまたはパッケージレベルのサービスロケーターを使用 しないでください
5. DI コンテナーはコンポジション ルート (main() またはアプリスタートアップ) にのみ存在する 必要があります — コンテナーを依存関係として渡さないでください
6. 遅延初期化を優先 — サービスを最初にリクエストされたときだけ作成します
7. ステートフルサービス (DB 接続、キャッシュ) にはシングルトンを使用し、ステートレスサービスには一時的なものを使用します
8. インターフェース境界でモックする — DI でこれは簡単です
9. 依存グラフを浅く保つ — 深いチェーンは設計上の問題を示します
10. プロジェクトサイズとチームに合った DI ライブラリを選択 — 以下の決定テーブルを参照してください

依存性注入がなぜ必要?

DI がない場合の問題	DI がこれをどう解決するか
関数が独自の依存関係を作成する	依存関係が注入される — 実装を自由に切り替える
テストは実際のデータベース、API が必要	テストではモック実装を渡します
1 つのコンポーネントを変更すると他が壊れる	インターフェース経由の疎結合 — コンポーネント同士が内部を知りません
サービスが至る所で初期化される	集中管理されたコンテナーはライフサイクルを管理します (シングルトン、ファクトリー、遅延)
すべてのサービスがスタートアップで読み込まれる	遅延読み込み — サービスは最初にリクエストされたときだけ作成されます
グローバル状態と init() 関数	スタートアップでの明示的な配線 — 予測可能でデバッグ可能

DI は多くの相互接続されたサービスを持つアプリケーション — HTTP サーバー、マイクロサービス、プラグイン付き CLI ツール で輝きます。2-3 個の関数を持つ小さいスクリプトの場合、マニュアル配線で問題ありません。オーバーエンジニアリングしないでください。

マニュアルコンストラクタ注入 (ライブラリなし)

小規模プロジェクトでは、コンストラクタを通じて依存関係を渡します。完全なアプリケーション例については、Manual DI examples を参照してください。

// ✓ Good — 明示的な依存関係、テスト可能
type UserService struct {
    db     UserStore
    mailer Mailer
    logger *slog.Logger
}

func NewUserService(db UserStore, mailer Mailer, logger *slog.Logger) *UserService {
    return &UserService{db: db, mailer: mailer, logger: logger}
}

// main.go — マニュアル配線
func main() {
    logger := slog.Default()
    db := postgres.NewUserStore(connStr)
    mailer := smtp.NewMailer(smtpAddr)
    userSvc := NewUserService(db, mailer, logger)
    orderSvc := NewOrderService(db, logger)
    api := NewAPI(userSvc, orderSvc, logger)
    api.ListenAndServe(":8080")
}

// ✗ Bad — ハードコードされた依存関係、テスト不可能
type UserService struct {
    db *sql.DB
}

func NewUserService() *UserService {
    db, _ := sql.Open("postgres", os.Getenv("DATABASE_URL")) // 隠された依存関係
    return &UserService{db: db}
}

マニュアル DI は以下の場合に破綻します:

• 15 以上のサービスがあり相互依存がある
• ライフサイクル管理が必要 (ヘルスチェック、グレースフルシャットダウン)
• 遅延初期化またはスコープ付きコンテナーが必要
• 配線順序が脆弱になり保守が困難

DI ライブラリの比較

Go には DI ライブラリへの 3 つの主要なアプローチがあります:

• google/wire examples — コンパイル時コード生成
• uber-go/dig + fx examples — リフレクションベースフレームワーク
• samber/do examples — ジェネリクスベース、コード生成なし

決定テーブル

基準	マニュアル	google/wire	uber-go/dig + fx	samber/do
プロジェクトサイズ	小 (< 10 サービス)	中-大	大	任意のサイズ
型安全性	コンパイル時	コンパイル時 (コード生成)	ランタイム (リフレクション)	コンパイル時 (ジェネリクス)
コード生成	なし	必須 (wire_gen.go)	なし	なし
リフレクション	なし	なし	はい	なし
API スタイル	N/A	Provider セット + ビルドタグ	Struct タグ + デコレータ	シンプルなジェネリック関数
遅延読み込み	マニュアル	N/A (すべてイーガー)	組み込み (fx)	組み込み
シングルトン	マニュアル	組み込み	組み込み	組み込み
一時的/ファクトリー	マニュアル	マニュアル	組み込み	組み込み
スコープ/モジュール	マニュアル	Provider セット	モジュールシステム (fx)	組み込み (階層的)
ヘルスチェック	マニュアル	マニュアル	マニュアル	組み込みインターフェース
グレースフルシャットダウン	マニュアル	マニュアル	組み込み (fx)	組み込みインターフェース
コンテナークローニング	N/A	N/A	N/A	組み込み
デバッグ	Print ステートメント	コンパイルエラー	fx.Visualize()	ExplainInjector()、ウェブインターフェース
Go バージョン	任意	任意	任意	1.18+ (ジェネリクス)
学習曲線	なし	中	高	低

クイック比較: 同じアプリ、4 つの方法

依存グラフ: Config -> Database -> UserStore -> UserService -> API

マニュアル:

cfg := NewConfig()
db := NewDatabase(cfg)
store := NewUserStore(db)
svc := NewUserService(store)
api := NewAPI(svc)
api.Run()
// 自動シャットダウン、ヘルスチェック、遅延読み込みなし

google/wire:

// wire.go — その後 wire ./... を実行
func InitializeAPI() (*API, error) {
    wire.Build(NewConfig, NewDatabase, NewUserStore, NewUserService, NewAPI)
    return nil, nil
}
// シャットダウンまたはヘルスチェックサポートなし

uber-go/fx:

app := fx.New(
    fx.Provide(NewConfig, NewDatabase, NewUserStore, NewUserService),
    fx.Invoke(func(api *API) { api.Run() }),
)
app.Run() // ライフサイクルを管理しますが、リフレクションベース

samber/do:

i := do.New()
do.Provide(i, NewConfig)
do.Provide(i, NewDatabase)    // 自動シャットダウン + ヘルスチェック
do.Provide(i, NewUserStore)
do.Provide(i, NewUserService)
api := do.MustInvoke[*API](i)
api.Run()
// defer i.Shutdown() — すべてのクリーンアップを自動的に処理

DI でのテスト

DI はテストを簡単にします — 実装の代わりにモックを注入するだけです:

// モックを定義
type MockUserStore struct {
    users map[string]*User
}

func (m *MockUserStore) FindByID(ctx context.Context, id string) (*User, error) {
    u, ok := m.users[id]
    if !ok {
        return nil, ErrNotFound
    }
    return u, nil
}

// マニュアル注入でテスト
func TestUserService_GetUser(t *testing.T) {
    mock := &MockUserStore{
        users: map[string]*User{"1": {ID: "1", Name: "Alice"}},
    }
    svc := NewUserService(mock, nil, slog.Default())

    user, err := svc.GetUser(context.Background(), "1")
    if err != nil {
        t.Fatalf("unexpected error: %v", err)
    }
    if user.Name != "Alice" {
        t.Errorf("got %q, want %q", user.Name, "Alice")
    }
}

samber/do でのテスト — クローンとオーバーライド

コンテナークローニングはモックが必要なサービスだけをオーバーライドする隔離されたコピーを作成します:

func TestUserService_WithDo(t *testing.T) {
    // モック実装でテストインジェクターを作成
    testInjector := do.New()

    // モック UserStore インターフェースを提供
    do.Override[UserStore](testInjector, &MockUserStore{
        users: map[string]*User{"1": {ID: "1", Name: "Alice"}},
    })

    // 必要に応じて他の実際のサービスを提供
    do.Provide[*slog.Logger](testInjector, func(i *do.Injector) (*slog.Logger, error) {
        return slog.Default(), nil
    })

    svc := do.MustInvoke[*UserService](testInjector)
    user, err := svc.GetUser(context.Background(), "1")
    // ... アサーション
}

これは特にほとんどのサービスが実際である統合テストで、特定の境界 (データベース、外部 API、メーラー) だけをモックする必要がある場合に非常に便利です。

DI ライブラリを採用するタイミング

シグナル	行動
< 10 サービス、シンプルな依存関係	マニュアルコンストラクタ注入のままで
10-20 サービス、クロスカッティングコンサーン複数	DI ライブラリ検討
20+ サービス、ライフサイクル管理が必要	強く推奨
ヘルスチェック、グレースフルシャットダウンが必要	組み込みライフサイクルサポート付きライブラリを使用
チーム DI コンセプト未経験	マニュアルで開始し、段階的に移行

よくある間違い

間違い	修正方法
依存関係としてのグローバル変数	コンストラクタまたは DI コンテナー経由で渡す
サービスセットアップの init()	main() またはコンテナーで明示的初期化
具象型への依存	消費境界でインターフェースを受け入れる
コンテナーをどこにでも渡す (サービスロケーター)	特定の依存関係を注入し、コンテナーではなく
深い依存チェーン (A->B->C->D->E)	フラット化 — ほとんどのサービスはリポジトリとコンフィグに直接依存すべき
リクエストごとに新しいコンテナーを作成	アプリケーション当たり 1 つのコンテナー、リクエストレベル隔離にはスコープを使用

クロスリファレンス

• → 詳細な samber/do 使用パターンについては samber/cc-skills-golang@golang-samber-do スキルを参照
• → インターフェース設計とコンポジションについては samber/cc-skills-golang@golang-structs-interfaces スキルを参照
• → 依存性注入でのテストについては samber/cc-skills-golang@golang-testing スキルを参照
• → DI 初期化配置については samber/cc-skills-golang@golang-project-layout スキルを参照

参考文献

• samber/do/v2 documentation | github.com/samber/do/v2
• google/wire user guide
• uber-go/fx documentation
• uber-go/dig