Go Modules — 의존성 관리

Go 1.11에 도입된 Go Modules 는 Go의 공식 의존성 관리 시스템입니다. GOPATH 방식의 한계를 극복하고 버전 관리와 재현 가능한 빌드를 지원합니다.

모듈 초기화 — go mod init

# 새 모듈 초기화
go mod init github.com/yourname/myproject

# 로컬 모듈 (공개하지 않는 경우)
go mod init myproject

go mod init 실행 후 go.mod 파일이 생성됩니다.

go.mod 파일 구조

module github.com/yourname/myproject  ← 모듈 경로

go 1.21                               ← 최소 Go 버전

require (
    github.com/gin-gonic/gin v1.9.1   ← 직접 의존성
    github.com/stretchr/testify v1.8.4
)

require (
    // 간접 의존성 (직접 의존성이 필요로 하는 패키지)
    github.com/bytedance/sonic v1.9.1 // indirect
    github.com/gabriel-vasile/mimetype v1.4.2 // indirect
)

주요 go 명령어

# 패키지 추가 (자동으로 go.mod, go.sum 업데이트)
go get github.com/gin-gonic/gin

# 특정 버전 지정
go get github.com/gin-gonic/gin@v1.9.1

# 최신 버전으로 업그레이드
go get -u github.com/gin-gonic/gin

# 모든 의존성 최신 버전으로
go get -u ./...

# 사용하지 않는 의존성 제거 + 필요한 것 추가
go mod tidy

# 의존성을 vendor 디렉터리에 복사
go mod vendor

# 의존성 다운로드
go mod download

# 모듈 그래프 확인
go mod graph

# 의존성 검증
go mod verify

go.sum 파일

go.sum은 각 모듈의 암호학적 해시를 저장해 빌드 재현성과 보안을 보장합니다.

github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5cB7BeOkPtxjfCSye0AAm1R0RVIqJ+Jmg=
github.com/gin-gonic/gin v1.9.1/go.mod h1:hPrL7YrpYKXt5YId3A/Tnip5kqbEAP+KLuI3SUcPTeU=

go.sum은 수동으로 편집하면 안 됩니다. go mod tidy나 go get이 자동으로 관리합니다.

버전 관리

Go Modules는 시맨틱 버저닝(SemVer) 을 따릅니다.

v1.2.3
│ │ │
│ │ └── 패치 버전 (버그 수정)
│ └──── 마이너 버전 (새 기능, 하위 호환)
└────── 메이저 버전 (하위 호환 불가 변경)

메이저 버전 업그레이드 (v2+)

// v2 이상은 임포트 경로에 버전 포함
import "github.com/foo/bar/v2"
import "github.com/foo/bar/v3"

go get github.com/foo/bar/v2@v2.0.0

버전 지시자

v1.9.1          정확한 버전
>=v1.9.0        최소 버전
latest          최신 릴리즈
@main           메인 브랜치 (비권장)
@hash           커밋 해시

로컬 모듈 참조 — replace 지시자

로컬에서 개발 중인 패키지를 참조할 때 사용합니다.

// go.mod
module github.com/myorg/myapp

go 1.21

require (
    github.com/myorg/mylib v0.1.0
)

replace (
    // 로컬 경로로 대체
    github.com/myorg/mylib => ../mylib

    // 특정 버전으로 대체 (취약점 패치 등)
    github.com/vulnerable/pkg v1.0.0 => github.com/safe/pkg v1.0.1
)

실전 예제 — 프로젝트 설정

# 1. 프로젝트 초기화
mkdir mywebapp && cd mywebapp
go mod init github.com/yourname/mywebapp

# 2. 의존성 추가
go get github.com/gin-gonic/gin@v1.9.1
go get github.com/stretchr/testify@v1.8.4

# 3. 코드 작성

// main.go
package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default()

    r.GET("/ping", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{
            "message": "pong",
        })
    })

    r.Run(":8080")
}

# 4. 불필요한 의존성 정리
go mod tidy

# 5. 빌드
go build ./...

# 6. 테스트
go test ./...

go.mod에서 자주 보는 지시자

module  모듈 경로 선언
go      최소 Go 버전
require 의존성 선언
replace 의존성 경로 재정의
exclude 특정 버전 제외
retract 게시된 버전 철회 (모듈 작성자용)

// retract 예시 — 잘못 게시된 버전 철회
retract (
    v1.0.5 // 심각한 버그 포함
    [v1.1.0, v1.1.5] // 범위 철회
)

GOPATH vs Go Modules

항목	GOPATH	Go Modules
코드 위치	$GOPATH/src/ 필수	어디서나 가능
버전 관리	불가	SemVer 지원
재현성	낮음	go.sum으로 보장
의존성 파일	없음	go.mod, go.sum
현재 상태	레거시	✅ 공식 표준

GONOSUMCHECK, GONOSUMDB, GOPRIVATE

사내 비공개 패키지를 사용할 때 설정합니다.

# 비공개 모듈 설정 (체크섬 DB 우회)
go env -w GONOSUMCHECK="*.corp.example.com/*"
go env -w GOPRIVATE="github.com/mycompany/*"
go env -w GOPROXY="https://proxy.golang.org,direct"

핵심 정리

• go mod init: 모듈 초기화, go.mod 생성
• go get: 의존성 추가/업그레이드
• go mod tidy: 불필요 의존성 제거, 필요한 것 추가
• go.sum: 빌드 재현성을 위한 해시 파일 (수동 편집 금지)
• SemVer 필수: v2+ 는 임포트 경로에 /v2 포함
• replace 지시자: 로컬 개발이나 보안 패치에 활용