Go言語入門：依存関係の管理 -Vol.14-

よっしー

こんにちは。よっしーです(^^)

本日は、Go言語の依存関係の管理ついて解説しています。

背景
ローカルディレクトリのモジュールコードを要求する
解説
1. ローカルモジュール参照の概念
基本的な設定方法
1. ディレクトリ構造
2. ステップバイステップの設定
require/replaceペアの詳細
1. なぜペアで使うのか?
2. v0.0.0-unpublishedの意味
go mod editコマンドの活用
1. 基本的な操作
2. 複数のローカルモジュールを管理
実践的な開発ワークフロー
1. ワークフロー1: 新しいライブラリの開発
2. ワークフロー2: 外部ライブラリのバグ修正
セキュリティとベストプラクティス
まとめ
おわりに

背景

Goでアプリケーションを開発していると、必ずと言っていいほど外部パッケージに依存することになります。HTTPルーターやデータベースドライバ、ロギングライブラリなど、車輪の再発明を避けて開発を効率化するために、私たちは日常的にこれらの外部モジュールを利用しています。

しかし、依存関係の管理は「最初に導入したら終わり」というわけにはいきません。セキュリティパッチのリリース、新機能の追加、破壊的変更への対応など、時間の経過とともに依存パッケージのアップグレードや置き換えが必要になってきます。また、複数の開発者が関わるプロジェクトでは、全員が同じバージョンの依存関係を使用できるよう、一貫性を保つことも重要です。

本記事では、Goが提供する依存関係管理ツールを使って、外部依存関係を取り込みながらもアプリケーションの安全性を保つ方法について解説します。公式ドキュメントの内容を日本語で紹介しながら、実際の開発現場で役立つ依存関係管理のベストプラクティスをお伝えしていきます。

Managing dependencies - The Go Programming Language

ローカルディレクトリのモジュールコードを要求する

要求されたモジュールのコードが、それを要求するコードと同じローカルドライブ上にあることを指定できます。以下のような場合に便利です:

独自の別モジュールを開発していて、現在のモジュールからテストしたい場合。
外部モジュールの問題を修正したり、機能を追加したりしていて、現在のモジュールからテストしたい場合。(なお、独自のリポジトリフォークから外部モジュールを要求することもできます。詳細については、Requiring external module code from your own repository forkを参照してください。)

Goコマンドにモジュールコードのローカルコピーを使用するよう指示するには、go.modファイルでreplaceディレクティブを使用して、requireディレクティブで指定されたモジュールパスを置き換えます。ディレクティブの詳細については、go.mod referenceを参照してください。

次のgo.modファイルの例では、現在のモジュールは外部モジュールexample.com/theirmoduleを要求し、置き換えが正しく機能することを保証するために存在しないバージョン番号(v0.0.0-unpublished)を使用しています。replaceディレクティブは、元のモジュールパスを../theirmodule(現在のモジュールのディレクトリと同じレベルにあるディレクトリ)で置き換えます。

module example.com/mymodule

go 1.23.0

require example.com/theirmodule v0.0.0-unpublished

replace example.com/theirmodule v0.0.0-unpublished => ../theirmodule

require/replaceペアを設定する際は、ファイルによって記述される要件が一貫性を保つように、go mod editおよびgo getコマンドを使用します:

$ go mod edit -replace=example.com/theirmodule@v0.0.0-unpublished=../theirmodule
$ go get example.com/theirmodule@v0.0.0-unpublished

注意: replaceディレクティブを使用する場合、Goツールは、Adding a dependencyで説明されているように外部モジュールを認証しません。

バージョン番号の詳細については、Module version numberingを参照してください。

解説

ローカルモジュール参照の概念

ローカルモジュールの使用は、隣の部屋にある道具を借りるようなものです:

隣の部屋の道具	ローカルモジュール
同じ家の中	同じドライブ上
すぐに借りられる	すぐに参照できる
修理して試せる	修正してテストできる
返す前に確認	公開前に検証
買わずに使える	ダウンロード不要

基本的な設定方法

ディレクトリ構造

典型的な構成:

projects/
├── myapp/              # あなたのアプリケーション
│   ├── go.mod
│   ├── main.go
│   └── handlers/
│       └── api.go
│
└── theirmodule/        # 開発中のライブラリ
    ├── go.mod
    ├── library.go
    └── utils.go

ステップバイステップの設定

完全な手順:

# ===== ステップ1: ディレクトリ構造を作成 =====

mkdir -p ~/projects
cd ~/projects

# ライブラリを作成
mkdir theirmodule
cd theirmodule
go mod init example.com/theirmodule

# ライブラリのコードを書く
cat > library.go << 'EOF'
package theirmodule

import "fmt"

func SayHello(name string) {
    fmt.Printf("Hello from theirmodule, %s!\n", name)
}

func Calculate(x, y int) int {
    return x + y
}
EOF

# テストを書く
cat > library_test.go << 'EOF'
package theirmodule

import "testing"

func TestCalculate(t *testing.T) {
    result := Calculate(2, 3)
    if result != 5 {
        t.Errorf("Expected 5, got %d", result)
    }
}
EOF

# テスト実行
go test
# PASS

cd ..

# ===== ステップ2: アプリケーションを作成 =====

mkdir myapp
cd myapp
go mod init example.com/myapp

# アプリケーションのコードを書く
cat > main.go << 'EOF'
package main

import "example.com/theirmodule"

func main() {
    theirmodule.SayHello("World")
    result := theirmodule.Calculate(10, 20)
    println("Result:", result)
}
EOF

# ===== ステップ3: require/replaceペアを設定 =====

# 方法1: 手動でgo.modを編集
cat > go.mod << 'EOF'
module example.com/myapp

go 1.21

require example.com/theirmodule v0.0.0-unpublished

replace example.com/theirmodule v0.0.0-unpublished => ../theirmodule
EOF

# 方法2: コマンドで設定(推奨)
go mod edit -replace=example.com/theirmodule@v0.0.0-unpublished=../theirmodule
go get example.com/theirmodule@v0.0.0-unpublished

# ===== ステップ4: 実行とテスト =====

# 実行
go run main.go
# Hello from theirmodule, World!
# Result: 30

# ビルド
go build
./myapp
# Hello from theirmodule, World!
# Result: 30

# テスト
go test ./...
# ok      example.com/myapp       0.001s

require/replaceペアの詳細

なぜペアで使うのか?

requireとreplaceの役割:

require example.com/theirmodule v0.0.0-unpublished
// ↑ このモジュールが必要だと宣言

replace example.com/theirmodule v0.0.0-unpublished => ../theirmodule
// ↑ 実際はローカルのコードを使う

理由:

requireディレクティブ:
- 依存関係を明示
- バージョン情報を保持
- 将来の公開を想定

replaceディレクティブ:
- 開発中の一時的な措置
- ローカルパスを指定
- 公開前に削除予定

v0.0.0-unpublishedの意味

特別なバージョン番号:

require example.com/theirmodule v0.0.0-unpublished
                                 │
                                 └─ 「未公開」を示す慣習的な表記

代替パターン:

// パターン1: v0.0.0-unpublished(推奨)
require example.com/theirmodule v0.0.0-unpublished

// パターン2: v0.0.0
require example.com/theirmodule v0.0.0

// パターン3: 疑似バージョン
require example.com/theirmodule v0.0.0-20231215120000-000000000000

// パターン4: 将来の公開バージョン
require example.com/theirmodule v1.0.0-dev

推奨される使い方:

// 開発初期: v0.0.0-unpublished
require example.com/newlib v0.0.0-unpublished
replace example.com/newlib v0.0.0-unpublished => ../newlib

// 公開準備中: 予定バージョン
require example.com/newlib v1.0.0
replace example.com/newlib v1.0.0 => ../newlib

// 公開後: replaceを削除
require example.com/newlib v1.0.0

go mod editコマンドの活用

基本的な操作

replaceディレクティブの追加:

# 基本形式
go mod edit -replace=モジュールパス@バージョン=置き換えパス

# 具体例
go mod edit -replace=example.com/theirmodule@v0.0.0-unpublished=../theirmodule

# 結果を確認
cat go.mod
# ...
# replace example.com/theirmodule v0.0.0-unpublished => ../theirmodule

requireディレクティブの追加:

# requireを追加
go mod edit -require=example.com/theirmodule@v0.0.0-unpublished

# または、go getで追加(推奨)
go get example.com/theirmodule@v0.0.0-unpublished

完全なコマンドセット:

# ステップ1: replaceを設定
go mod edit -replace=example.com/theirmodule@v0.0.0-unpublished=../theirmodule

# ステップ2: requireを追加
go get example.com/theirmodule@v0.0.0-unpublished

# ステップ3: 整理
go mod tidy

# ステップ4: 確認
cat go.mod

複数のローカルモジュールを管理

# 複数のreplaceを一度に設定

# 方法1: 個別に実行
go mod edit -replace=example.com/lib1@v0.0.0-unpublished=../lib1
go mod edit -replace=example.com/lib2@v0.0.0-unpublished=../lib2
go mod edit -replace=example.com/lib3@v0.0.0-unpublished=../lib3

# requireを追加
go get example.com/lib1@v0.0.0-unpublished
go get example.com/lib2@v0.0.0-unpublished
go get example.com/lib3@v0.0.0-unpublished

# 方法2: go.modを直接編集
cat >> go.mod << 'EOF'

replace (
    example.com/lib1 v0.0.0-unpublished => ../lib1
    example.com/lib2 v0.0.0-unpublished => ../lib2
    example.com/lib3 v0.0.0-unpublished => ../lib3
)
EOF

# 整理
go mod tidy

実践的な開発ワークフロー

ワークフロー1: 新しいライブラリの開発

完全な開発サイクル:

# ===== フェーズ1: 初期セットアップ =====

cd ~/projects

# ライブラリを作成
mkdir calculator-lib
cd calculator-lib
go mod init github.com/username/calculator-lib

# 初期コードを書く
cat > calculator.go << 'EOF'
package calculator

func Add(a, b int) int {
    return a + b
}

func Multiply(a, b int) int {
    return a * b
}
EOF

# テストを書く
cat > calculator_test.go << 'EOF'
package calculator

import "testing"

func TestAdd(t *testing.T) {
    if Add(2, 3) != 5 {
        t.Error("Add failed")
    }
}

func TestMultiply(t *testing.T) {
    if Multiply(2, 3) != 6 {
        t.Error("Multiply failed")
    }
}
EOF

# テスト実行
go test -v
# PASS

cd ..

# ===== フェーズ2: アプリケーションで使用 =====

mkdir calculator-app
cd calculator-app
go mod init example.com/calculator-app

# アプリケーションコード
cat > main.go << 'EOF'
package main

import (
    "fmt"
    "github.com/username/calculator-lib"
)

func main() {
    sum := calculator.Add(10, 20)
    product := calculator.Multiply(10, 20)
    
    fmt.Printf("Sum: %d\n", sum)
    fmt.Printf("Product: %d\n", product)
}
EOF

# ローカルライブラリを使用
go mod edit -replace=github.com/username/calculator-lib@v0.0.0-unpublished=../calculator-lib
go get github.com/username/calculator-lib@v0.0.0-unpublished

# 実行
go run main.go
# Sum: 30
# Product: 200

# ===== フェーズ3: ライブラリを改善 =====

cd ../calculator-lib

# 新機能を追加
cat >> calculator.go << 'EOF'

func Subtract(a, b int) int {
    return a - b
}

func Divide(a, b int) (int, error) {
    if b == 0 {
        return 0, fmt.Errorf("division by zero")
    }
    return a / b, nil
}
EOF

# テストを追加
cat >> calculator_test.go << 'EOF'

func TestSubtract(t *testing.T) {
    if Subtract(10, 3) != 7 {
        t.Error("Subtract failed")
    }
}

func TestDivide(t *testing.T) {
    result, err := Divide(10, 2)
    if err != nil || result != 5 {
        t.Error("Divide failed")
    }
}
EOF

# テスト実行
go test -v
# PASS

# ===== フェーズ4: アプリケーションで新機能を使用 =====

cd ../calculator-app

# アプリケーションを更新
cat > main.go << 'EOF'
package main

import (
    "fmt"
    "github.com/username/calculator-lib"
)

func main() {
    sum := calculator.Add(10, 20)
    diff := calculator.Subtract(20, 10)
    product := calculator.Multiply(10, 20)
    quotient, _ := calculator.Divide(20, 10)
    
    fmt.Printf("Sum: %d\n", sum)
    fmt.Printf("Difference: %d\n", diff)
    fmt.Printf("Product: %d\n", product)
    fmt.Printf("Quotient: %d\n", quotient)
}
EOF

# 実行(ローカルの最新版を自動的に使用)
go run main.go
# Sum: 30
# Difference: 10
# Product: 200
# Quotient: 2

# ===== フェーズ5: 公開準備 =====

cd ../calculator-lib

# Gitリポジトリを初期化
git init
git add .
git commit -m "Initial release"

# GitHubにプッシュ
git remote add origin https://github.com/username/calculator-lib.git
git push -u origin main

# バージョンタグを作成
git tag v1.0.0
git push origin v1.0.0

# ===== フェーズ6: アプリケーションで公開版を使用 =====

cd ../calculator-app

# replaceを削除
go mod edit -dropreplace=github.com/username/calculator-lib

# 公開版を使用
go get github.com/username/calculator-lib@v1.0.0

# go.modを確認
cat go.mod
# module example.com/calculator-app
# 
# go 1.21
# 
# require github.com/username/calculator-lib v1.0.0

# 動作確認
go run main.go
# (同じ出力)

ワークフロー2: 外部ライブラリのバグ修正

# ===== シナリオ: 外部ライブラリにバグを発見 =====

cd ~/projects

# 外部ライブラリをクローン
git clone https://github.com/external/library.git
cd library

# バグ修正用のブランチ
git checkout -b fix-calculation-bug

# バグを修正
nano math.go
# バグを修正

# テスト
go test ./...
# PASS

# コミット
git add .
git commit -m "Fix calculation bug in edge case"

cd ..

# ===== 自分のアプリでテスト =====

cd myapp

# ローカルの修正版を使用
go mod edit -replace=github.com/external/library@v1.5.0=../library
go get github.com/external/library@v1.5.0

# テスト
go test ./...
# バグ修正が機能することを確認

# 統合テスト
go run main.go
# 正常動作

# ===== プルリクエストを作成 =====

cd ../library
git push origin fix-calculation-bug

# GitHubでプルリクエストを作成

# ===== マージされるまで待つ =====

# マージされて新バージョンがリリースされたら
cd ../myapp

# replaceを削除
go mod edit -dropreplace=github.com/external/library

# 最新版を取得
go get github.com/external/library@v1.5.1

# 確認
go test ./...

セキュリティとベストプラクティス

セキュリティに関する注意

重要な警告:

⚠️ replaceディレクティブを使用する場合の注意:

1. チェックサム検証がスキップされる
   └─ go.sumによる整合性チェックが行われない

2. 改ざんのリスク
   └─ ローカルコードは検証されない

3. 再現性の問題
   └─ 他の環境では動作しない可能性

安全な使用方法:

# ✅ 開発環境でのみ使用
# ✅ 一時的な措置として使用
# ✅ コミット前に削除
# ✅ チームで使用ルールを統一

# ❌ 本番環境で使用しない
# ❌ 長期間使用しない
# ❌ 公開リポジトリにコミットしない

ベストプラクティス

1. ディレクトリ構造の統一:

推奨構造:

~/projects/
├── myapp/
│   └── go.mod (replace ../lib1)
├── lib1/
│   └── go.mod
└── lib2/
    └── go.mod

利点:
✅ 相対パスが単純
✅ チーム全員が同じ構造を使える
✅ スクリプトでの自動化が容易

2. バージョン番号の慣習:

// 開発初期
require example.com/mylib v0.0.0-unpublished

// ベータ版準備
require example.com/mylib v0.1.0-beta

// リリース候補
require example.com/mylib v1.0.0-rc.1

// 正式リリース後(replaceを削除)
require example.com/mylib v1.0.0

3. コミット前のチェックリスト:

# スクリプト: pre-commit-check.sh
#!/bin/bash

echo "Checking for local replace directives..."

if grep -q "replace.*\.\." go.mod; then
    echo "❌ Error: Local path replace found in go.mod"
    echo "Please remove before committing:"
    grep "replace.*\.\." go.mod
    exit 1
fi

echo "✅ No local replace directives found"
exit 0

4. ドキュメント化:

# README.md

## Development Setup

### Local Library Development

If you're developing `mylib` locally:

```bash
# Clone both repositories
git clone https://github.com/user/myapp.git
git clone https://github.com/user/mylib.git

# Setup local development
cd myapp
go mod edit -replace=github.com/user/mylib@v0.0.0-unpublished=../mylib
go get github.com/user/mylib@v0.0.0-unpublished

# Run tests
go test ./...

⚠️ Important: Don’t commit go.mod with replace directives!


---

## トラブルシューティング

### 問題1: モジュールが見つからない

```bash
# エラー
$ go build
module example.com/theirmodule: cannot find module providing package example.com/theirmodule

# 原因と対処:

# 原因1: パスが間違っている
# 確認
ls ../theirmodule
# ls: cannot access '../theirmodule': No such file or directory

# 対処: 正しいパスを指定
ls ../their-module  # 正しいディレクトリ名
go mod edit -replace=example.com/theirmodule@v0.0.0-unpublished=../their-module

# 原因2: モジュール名が不一致
cat ../theirmodule/go.mod
# module github.com/user/different-name  # ❌ 異なる

# 対処: 正しいモジュール名を使用
go mod edit -replace=github.com/user/different-name@v0.0.0-unpublished=../theirmodule

問題2: ビルドは成功するがIDEでエラー

# 症状: go buildは成功するが、VS Codeなどで赤線

# 原因: IDEのキャッシュが古い

# 対処1: gopls再起動(VS Code)
# Ctrl+Shift+P → "Go: Restart Language Server"

# 対処2: キャッシュクリア
go clean -modcache
go mod download

# 対処3: IDE再起動

問題3: テストが失敗する

# エラー
$ go test ./...
package example.com/theirmodule is not in GOROOT

# 原因: go.modが正しく設定されていない

# 対処:
# 1. requireとreplaceの両方があるか確認
cat go.mod
# require example.com/theirmodule v0.0.0-unpublished  # ✅
# replace example.com/theirmodule v0.0.0-unpublished => ../theirmodule  # ✅

# 2. go mod tidyを実行
go mod tidy

# 3. 再テスト
go test ./...

まとめ

ローカルモジュール使用の完全ガイド

基本設定:

# ステップ1: replaceディレクティブを追加
go mod edit -replace=モジュールパス@v0.0.0-unpublished=../ローカルパス

# ステップ2: requireディレクティブを追加
go get モジュールパス@v0.0.0-unpublished

# ステップ3: 使用
go run main.go

go.modの構造:

module example.com/myapp

go 1.21

require example.com/theirmodule v0.0.0-unpublished

replace example.com/theirmodule v0.0.0-unpublished => ../theirmodule

使用シーン

新しいライブラリ開発:
✅ ローカルパスreplace
✅ 素早い反復開発
✅ 公開前のテスト

外部ライブラリ修正:
✅ ローカルクローン
✅ バグ修正・機能追加
✅ プルリクエスト準備

本番リリース:
✅ replaceを削除
✅ 公開バージョンを使用
✅ 再現可能なビルド

重要なポイント

✅ requireとreplaceをペアで使用
✅ v0.0.0-unpublishedを使用
✅ go mod editで設定
✅ コミット前に削除
❌ 本番環境で使用しない
❌ セキュリティチェックがない

これで、ローカルモジュールを効率的に開発できます!

おわりに

本日は、Go言語の依存関係の管理について解説しました。

よっしー

何か質問や相談があれば、コメントをお願いします。また、エンジニア案件の相談にも随時対応していますので、お気軽にお問い合わせください。

それでは、また明日お会いしましょう(^^)