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

よっしー

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

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

背景
モジュールプロキシサーバーの指定
解説
1. モジュールプロキシの概念
GOPROXY環境変数の基本
1. デフォルト設定
2. GOPROXYの設定方法
カンマ vs パイプの違い
企業内プロキシの設定
GOPRIVATE環境変数
高度な設定パターン
中国など特定地域での設定
1. 中国での推奨設定
トラブルシューティング
ベストプラクティス
おわりに

背景

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

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

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

Managing dependencies - The Go Programming Language

モジュールプロキシサーバーの指定

Goツールを使用してモジュールを操作する場合、ツールはデフォルトでproxy.golang.org(Googleが運営する公開モジュールミラー)から、またはモジュールのリポジトリから直接モジュールをダウンロードします。Goツールがモジュールのダウンロードと認証に別のプロキシサーバーを使用するように指定できます。

あなた(またはあなたのチーム)が使用したい別のモジュールプロキシサーバーをセットアップまたは選択している場合、これを行いたいと思うかもしれません。たとえば、依存関係の使用方法をより細かく制御するために、モジュールプロキシサーバーをセットアップする人もいます。

Goツールが使用する別のモジュールプロキシサーバーを指定するには、GOPROXY環境変数を1つ以上のサーバーのURLに設定します。Goツールは、指定した順序で各URLを試行します。デフォルトでは、GOPROXYは最初に公開のGoogleが運営するモジュールプロキシを指定し、次にモジュールのリポジトリからの直接ダウンロード(モジュールパスで指定)を指定します:

GOPROXY="https://proxy.golang.org,direct"

他の動作をサポートする値を含むGOPROXY環境変数の詳細については、goコマンドリファレンスを参照してください。

変数を他のモジュールプロキシサーバーのURLに設定でき、URLをカンマまたはパイプで区切ります。

カンマを使用する場合、Goツールは現在のURLがHTTP 404または410を返す場合にのみリスト内の次のURLを試行します。

GOPROXY="https://proxy.example.com,https://proxy2.example.com"

パイプを使用する場合、Goツールは HTTPエラーコードに関係なくリスト内の次のURLを試行します。

GOPROXY="https://proxy.example.com|https://proxy2.example.com"

Goモジュールは、公開インターネットで利用できないバージョン管理サーバーやモジュールプロキシで頻繁に開発および配布されます。GOPRIVATE環境変数を設定して、goコマンドがプライベートソースからモジュールをダウンロードしてビルドするように構成できます。その後、goコマンドはプライベートソースからモジュールをダウンロードしてビルドできます。

GOPRIVATEまたはGONOPROXY環境変数は、プライベートでありプロキシから要求すべきでないモジュールプレフィックスに一致するglobパターンのリストに設定できます。たとえば:

GOPRIVATE=*.corp.example.com,*.research.example.com

解説

モジュールプロキシの概念

モジュールプロキシは、配送センターのようなものです:

配送システム	モジュールプロキシ
地域配送センター	proxy.golang.org
企業専用倉庫	社内プロキシ
直接配送	direct(GitHubから直接)
配送ルート	GOPROXY設定
プライベート配送	GOPRIVATE設定

GOPROXY環境変数の基本

デフォルト設定

Goのデフォルト動作:

# デフォルトのGOPROXY設定
echo $GOPROXY
# https://proxy.golang.org,direct

# 意味:
# 1. まずproxy.golang.orgから取得を試みる
# 2. 失敗したら直接リポジトリから取得(direct)

動作フロー:

モジュールのダウンロード要求
        ↓
proxy.golang.orgにアクセス
        ↓
┌──────┴──────┐
成功           失敗(404/410)
↓              ↓
使用      GitHubから直接取得
              (direct)

GOPROXYの設定方法

一時的な設定:

# Linux/macOS
export GOPROXY=https://proxy.example.com,direct

# Windows (PowerShell)
$env:GOPROXY="https://proxy.example.com,direct"

# Windows (CMD)
set GOPROXY=https://proxy.example.com,direct

永続的な設定:

# Linux/macOS (.bashrc, .zshrc等)
echo 'export GOPROXY=https://proxy.example.com,direct' >> ~/.bashrc
source ~/.bashrc

# Goコマンドで設定(推奨)
go env -w GOPROXY=https://proxy.example.com,direct

# 確認
go env GOPROXY
# https://proxy.example.com,direct

カンマ vs パイプの違い

カンマ(,)の動作

特定のエラーでのみフォールバック:

GOPROXY="https://proxy1.example.com,https://proxy2.example.com,direct"

# 動作:
# 1. proxy1にアクセス
#    - 成功 → 使用
#    - 404/410 → proxy2へ
#    - その他のエラー → 失敗
# 2. proxy2にアクセス
#    - 成功 → 使用
#    - 404/410 → directへ
#    - その他のエラー → 失敗
# 3. direct(GitHubなどから直接取得)

実例:

# 設定
export GOPROXY="https://primary.company.com,https://backup.company.com,direct"

# シナリオ1: 正常な場合
$ go get github.com/gin-gonic/gin
# 1. primary.company.comにアクセス → 成功
# ✅ primary.company.comから取得

# シナリオ2: プライマリが404
$ go get github.com/new/package
# 1. primary.company.comにアクセス → 404
# 2. backup.company.comにアクセス → 成功
# ✅ backup.company.comから取得

# シナリオ3: プライマリがネットワークエラー
$ go get github.com/some/package
# 1. primary.company.comにアクセス → タイムアウト
# ❌ エラー(次のプロキシを試さない)

パイプ(|)の動作

すべてのエラーでフォールバック:

GOPROXY="https://proxy1.example.com|https://proxy2.example.com|direct"

# 動作:
# 1. proxy1にアクセス
#    - 成功 → 使用
#    - 任意のエラー → proxy2へ
# 2. proxy2にアクセス
#    - 成功 → 使用
#    - 任意のエラー → directへ
# 3. direct(GitHubなどから直接取得)

実例:

# 設定
export GOPROXY="https://unreliable.proxy.com|https://reliable.proxy.com|direct"

# シナリオ1: プライマリがタイムアウト
$ go get github.com/some/package
# 1. unreliable.proxy.comにアクセス → タイムアウト
# 2. reliable.proxy.comにアクセス → 成功
# ✅ reliable.proxy.comから取得

# シナリオ2: プライマリが500エラー
$ go get github.com/another/package
# 1. unreliable.proxy.comにアクセス → 500 Internal Server Error
# 2. reliable.proxy.comにアクセス → 成功
# ✅ reliable.proxy.comから取得

使い分けガイド

カンマ(,)を使用:
✅ 信頼性の高いプロキシ
✅ フェイルオーバーは例外的
✅ パフォーマンス重視

パイプ(|)を使用:
✅ 不安定なネットワーク
✅ 信頼性の低いプロキシ
✅ 可用性重視

企業内プロキシの設定

シナリオ1: 単一の企業プロキシ

基本的な設定:

# 企業プロキシを最優先
export GOPROXY="https://proxy.company.com,https://proxy.golang.org,direct"

# 設定の永続化
go env -w GOPROXY="https://proxy.company.com,https://proxy.golang.org,direct"

# 確認
go env GOPROXY
# https://proxy.company.com,https://proxy.golang.org,direct

動作確認:

# モジュールをダウンロード
go get github.com/gin-gonic/gin

# 詳細ログで確認
go get -x github.com/gin-gonic/gin
# get https://proxy.company.com/github.com/gin-gonic/gin/@v/list
# ... 企業プロキシから取得

シナリオ2: 冗長化された企業プロキシ

高可用性構成:

# プライマリとバックアップ
export GOPROXY="https://proxy1.company.com,https://proxy2.company.com,https://proxy.golang.org,direct"

# またはパイプで(より強固)
export GOPROXY="https://proxy1.company.com|https://proxy2.company.com|https://proxy.golang.org|direct"

実践例:

# 東京と大阪にプロキシサーバー
export GOPROXY="https://proxy-tokyo.company.com|https://proxy-osaka.company.com|direct"

# チーム全体で統一
cat > .envrc << 'EOF'
export GOPROXY="https://proxy-tokyo.company.com|https://proxy-osaka.company.com|direct"
export GOPRIVATE="*.company.com"
EOF

# direnvを使用(プロジェクトディレクトリで自動設定)
direnv allow

シナリオ3: 地域別プロキシ

地域ごとの最適化:

# アジアリージョン
export GOPROXY="https://proxy-asia.company.com,https://proxy.golang.org,direct"

# ヨーロッパリージョン
export GOPROXY="https://proxy-eu.company.com,https://proxy.golang.org,direct"

# アメリカリージョン
export GOPROXY="https://proxy-us.company.com,https://proxy.golang.org,direct"

GOPRIVATE環境変数

プライベートモジュールの設定

基本的な使い方:

# 単一のドメイン
export GOPRIVATE=github.com/mycompany

# 複数のドメイン
export GOPRIVATE=github.com/mycompany,gitlab.company.com

# ワイルドカード
export GOPRIVATE=*.company.com,*.internal.example.com

# 永続化
go env -w GOPRIVATE="*.company.com"

GOPRIVATEの動作

プライベートモジュールの処理:

GOPRIVATE="*.company.com"が設定されている場合:

github.com/mycompany/public
└─ プロキシ経由で取得
   └─ チェックサム検証あり

github.com/mycompany.company.com/private
└─ プロキシをバイパス
   └─ 直接Gitから取得
   └─ チェックサム検証なし
   └─ 認証情報使用

実践例: プライベートリポジトリの設定

# ===== ステップ1: GOPRIVATE設定 =====

export GOPRIVATE="github.com/mycompany/*,gitlab.company.com/*"
go env -w GOPRIVATE="github.com/mycompany/*,gitlab.company.com/*"

# ===== ステップ2: Git認証設定 =====

# GitHub Personal Access Token
git config --global url."https://${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"

# GitLab Private Token
git config --global url."https://oauth2:${GITLAB_TOKEN}@gitlab.company.com/".insteadOf "https://gitlab.company.com/"

# SSH を使用(推奨)
git config --global url."git@github.com:".insteadOf "https://github.com/"

# ===== ステップ3: プライベートモジュールを使用 =====

cat > go.mod << 'EOF'
module example.com/myapp

go 1.21

require (
    github.com/mycompany/private-lib v1.0.0  // プライベート
    github.com/gin-gonic/gin v1.9.1          // パブリック
)
EOF

# ===== ステップ4: ダウンロード =====

go mod download

# プライベートリポジトリは直接GitHubから
# パブリックリポジトリはプロキシ経由

# ===== 確認 =====

go list -m all
# github.com/mycompany/private-lib v1.0.0
# github.com/gin-gonic/gin v1.9.1

高度な設定パターン

パターン1: ハイブリッド構成

企業プロキシ + プライベートリポジトリ:

# 環境変数設定
export GOPROXY="https://proxy.company.com,https://proxy.golang.org,direct"
export GOPRIVATE="*.company.com,github.com/mycompany/*"
export GONOPROXY="*.company.com,github.com/mycompany/*"
export GONOSUMDB="*.company.com,github.com/mycompany/*"

# 永続化
go env -w GOPROXY="https://proxy.company.com,https://proxy.golang.org,direct"
go env -w GOPRIVATE="*.company.com,github.com/mycompany/*"
go env -w GONOPROXY="*.company.com,github.com/mycompany/*"
go env -w GONOSUMDB="*.company.com,github.com/mycompany/*"

動作:

公開モジュール(github.com/gin-gonic/gin):
1. proxy.company.com → 成功
2. チェックサム検証あり

プライベートモジュール(github.com/mycompany/secret):
1. プロキシをバイパス
2. GitHubから直接取得
3. チェックサム検証なし
4. Git認証使用

パターン2: 完全オフライン環境

インターネット接続なし:

# ローカルプロキシのみ使用
export GOPROXY="https://proxy.local.company.com"
export GONOPROXY="none"
export GONOSUMDB="*"

# または
export GOPROXY="file:///path/to/local/cache"

ローカルキャッシュの作成:

# 開発マシンで依存関係をダウンロード
go mod download

# キャッシュをエクスポート
go mod vendor

# vendorディレクトリをオフライン環境にコピー
tar czf vendor.tar.gz vendor/

# オフライン環境で使用
tar xzf vendor.tar.gz
go build -mod=vendor

パターン3: CI/CD最適化

GitHub Actionsの例:

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.21'
      
      # プロキシ設定
      - name: Configure Go proxy
        run: |
          go env -w GOPROXY="https://proxy.golang.org,direct"
          go env -w GOPRIVATE="github.com/${{ github.repository_owner }}/*"
      
      # プライベートリポジトリアクセス
      - name: Configure Git credentials
        run: |
          git config --global url."https://${{ secrets.GH_TOKEN }}@github.com/".insteadOf "https://github.com/"
      
      - name: Download dependencies
        run: go mod download
      
      - name: Build
        run: go build -v ./...
      
      - name: Test
        run: go test -v ./...

中国など特定地域での設定

中国での推奨設定

人気のあるプロキシ:

# Goproxy.cn (七牛云)
export GOPROXY="https://goproxy.cn,direct"

# Goproxy.io (アリババ)
export GOPROXY="https://goproxy.io,direct"

# Athens (Microsoftサポート)
export GOPROXY="https://athens.azurefd.net,direct"

# 複数のフォールバック
export GOPROXY="https://goproxy.cn,https://goproxy.io,https://proxy.golang.org,direct"

設定例:

# ~/.bashrc または ~/.zshrc
export GOPROXY="https://goproxy.cn,direct"
export GO111MODULE=on

# 適用
source ~/.bashrc

# 確認
go env GOPROXY
# https://goproxy.cn,direct

トラブルシューティング

問題1: プロキシに接続できない

# エラー
$ go get github.com/gin-gonic/gin
go: github.com/gin-gonic/gin@v1.9.1: Get "https://proxy.company.com/...": dial tcp: lookup proxy.company.com: no such host

# 診断
curl -I https://proxy.company.com
# curl: (6) Could not resolve host: proxy.company.com

# 対処1: プロキシURLを確認
go env GOPROXY
# typoがないか確認

# 対処2: ネットワーク接続確認
ping proxy.company.com

# 対処3: directにフォールバック
export GOPROXY="https://proxy.company.com,direct"
# または
export GOPROXY="direct"  # プロキシを完全にバイパス

問題2: プライベートリポジトリへのアクセス拒否

# エラー
$ go get github.com/mycompany/private-repo
go: github.com/mycompany/private-repo@v1.0.0: reading https://proxy.golang.org/...: 410 Gone

# 原因: プライベートリポジトリがプロキシ経由でアクセスされている

# 対処: GOPRIVATEを設定
export GOPRIVATE="github.com/mycompany/*"
go env -w GOPRIVATE="github.com/mycompany/*"

# Git認証を設定
git config --global url."git@github.com:".insteadOf "https://github.com/"

# 再試行
go get github.com/mycompany/private-repo

問題3: チェックサムエラー

# エラー
$ go get github.com/package/name
go: github.com/package/name@v1.0.0: verifying module: checksum mismatch

# 原因: プロキシのキャッシュが古い、または改ざん

# 対処1: プロキシをバイパス
GOPROXY=direct go get github.com/package/name

# 対処2: キャッシュをクリア
go clean -modcache
go get github.com/package/name

# 対処3: チェックサムデータベースを確認
go env GOSUMDB
# sum.golang.org

ベストプラクティス

企業環境での推奨設定

推奨構成:

# 複数のフォールバック(カンマ区切り)
export GOPROXY="https://proxy-primary.company.com,https://proxy-backup.company.com,https://proxy.golang.org,direct"

# プライベートモジュール
export GOPRIVATE="*.company.com,github.com/company-org/*"

# プライベートモジュールはプロキシを使わない
export GONOPROXY="*.company.com,github.com/company-org/*"

# プライベートモジュールはチェックサムデータベースを使わない
export GONOSUMDB="*.company.com,github.com/company-org/*"

チーム全体での統一

プロジェクトルートに設定ファイル:

# .envrc (direnv使用)
export GOPROXY="https://proxy.company.com,https://proxy.golang.org,direct"
export GOPRIVATE="*.company.com"
export GONOPROXY="*.company.com"
export GONOSUMDB="*.company.com"

# README.md
cat >> README.md << 'EOF'
## Development Setup

### Environment Variables

```bash
# Copy and run in your shell
go env -w GOPROXY="https://proxy.company.com,https://proxy.golang.org,direct"
go env -w GOPRIVATE="*.company.com"
go env -w GONOPROXY="*.company.com"
go env -w GONOSUMDB="*.company.com"

Private Repository Access

# SSH (recommended)
git config --global url."git@github.com:".insteadOf "https://github.com/"

# HTTPS with token
git config --global url."https://${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"

EOF


---

## まとめ

### GOPROXY設定の基本

```bash
# デフォルト
GOPROXY="https://proxy.golang.org,direct"

# カスタムプロキシ
GOPROXY="https://proxy.company.com,https://proxy.golang.org,direct"

# 冗長化(カンマ: 404/410のみフォールバック)
GOPROXY="https://proxy1.com,https://proxy2.com,direct"

# 冗長化(パイプ: 全エラーでフォールバック)
GOPROXY="https://proxy1.com|https://proxy2.com|direct"

GOPRIVATE設定

# プライベートモジュールを指定
GOPRIVATE="*.company.com,github.com/mycompany/*"

# プロキシバイパス
GONOPROXY="*.company.com"

# チェックサムデータベースバイパス
GONOSUMDB="*.company.com"

主要コマンド

# 設定確認
go env GOPROXY
go env GOPRIVATE

# 永続的設定
go env -w GOPROXY="https://proxy.example.com,direct"
go env -w GOPRIVATE="*.company.com"

# 一時的設定
export GOPROXY="https://proxy.example.com,direct"