프로젝트 구조까지 정리했다면, 이제 Go 개발에서 빠질 수 없는 주제인
의존성 관리, 즉 go mod를 살펴볼 차례다.
예전의 GOPATH 기반 개발을 경험한 사람이라면
go mod 도입 이후 “훨씬 편해졌다”는 말을 많이 하게 된다.
다만 실제로 쓰다 보면
go.mod, go.sum, replace, tidy 같은 개념에서 한 번쯤 헷갈리게 된다.
이 글에서는
- go mod의 기본 개념
- go.mod / go.sum의 역할
- 실무에서 자주 쓰는 명령어와 주의점
을 중심으로 정리한다.
Go 모듈이란 무엇인가
Go 모듈은 프로젝트 단위의 의존성 관리 시스템이다.
- 프로젝트가 어떤 라이브러리를 사용하는지
- 어떤 버전을 사용하는지
- 어떻게 재현 가능한 빌드를 보장하는지
를 명확하게 관리한다.
Go 1.16 이후부터는
go mod가 사실상 표준 방식이 되었고,
GOPATH 없이도 개발이 가능하다.
go mod init: 모듈 시작하기
새 프로젝트에서 가장 먼저 실행하는 명령어다.
go mod init github.com/yourname/myapp
이 명령을 실행하면 go.mod 파일이 생성된다.
module github.com/yourname/myapp
go 1.22
- module: 이 프로젝트의 모듈 경로
- go: 사용 중인 Go 버전 기준
실제로 써보면,
모듈 경로는 import 경로의 기준점이 되기 때문에
처음에 한 번은 신중하게 정하는 게 좋다.
go.mod 파일의 역할
go.mod는 의존성 선언서다.
require (
github.com/gin-gonic/gin v1.9.1
)
- 어떤 모듈을
- 어떤 버전으로 사용하는지
를 명시한다.
중요한 점은,
직접 수정하기보다 go 명령어에 맡기는 것이 기본 원칙이라는 점이다.
go.sum은 왜 필요한가
go.sum은 처음 보면 다소 생소하다.
github.com/gin-gonic/gin v1.9.1 h1:xxxx
github.com/gin-gonic/gin v1.9.1/go.mod h1:yyyy
go.sum의 역할은 다음과 같다.
의존성 무결성 검증
- 다운로드한 모듈이 변조되지 않았는지 확인
- 동일한 빌드 결과를 보장
⚠️ 주의할 점
go.sum은 자동 생성 파일이지만,
삭제하거나 무시하면 안 된다.
git에 반드시 함께 커밋하는 게 정상적인 사용 방식이다.
의존성 추가와 정리
새로운 패키지 사용 시
import "github.com/gin-gonic/gin"
이 상태에서 빌드를 하거나 테스트를 실행하면
go build
- 필요한 모듈이 자동으로 다운로드
- go.mod / go.sum이 자동 갱신
직접 require를 추가할 필요는 거의 없다.
go mod tidy
실무에서 가장 자주 사용하는 명령어 중 하나다.
go mod tidy
- 사용하지 않는 의존성 제거
- 필요한 의존성 자동 추가
- go.mod, go.sum 정리
브랜치 이동이나 리팩터링 후에는
습관처럼 한 번씩 실행하는 경우가 많다.
버전 선택 규칙 (Minimal Version Selection)
Go 모듈은 MVS (Minimal Version Selection) 규칙을 따른다.
- 가능한 가장 낮은 버전 선택
- 충돌 시 더 높은 최소 버전으로 조정
이 방식 덕분에
의존성 그래프가 단순해지고,
“왜 이 버전이 설치됐는지”를 추적하기 쉬워진다.
다만 Maven, npm에 익숙한 사람이라면
처음엔 다소 보수적으로 느껴질 수 있다.
replace 지시어: 로컬/임시 대체
개발 중에는 replace를 쓰는 경우도 있다.
replace github.com/example/lib => ../lib
- 로컬 모듈로 대체
- 포크 버전 테스트
- 임시 패치 적용
⚠️ 주의할 점
replace는 개발 단계에서는 유용하지만,
실수로 운영 코드에 남아 있지 않도록 주의해야 한다.
vendor 디렉터리는 언제 쓰나
go mod vendor
- 의존성을 프로젝트 내부에 복사
- 네트워크 없이 빌드 가능
일반적인 서버 개발에서는 잘 쓰이지 않지만,
- 폐쇄망 환경
- 빌드 재현성이 특히 중요한 경우
에는 여전히 의미가 있다.
실무에서 자주 겪는 포인트
- go.mod 충돌은 대부분 tidy로 해결
- go.sum 변경은 정상적인 현상
- 의존성 문제를 수동으로 고치려 하지 말 것
실제로 써보면,
go mod는 건드릴수록 문제가 생기고,
맡길수록 안정적이라는 느낌을 받게 된다.
정리
go mod는
Go 프로젝트를 재현 가능하게 만드는 기반 도구다.
- go.mod: 의존성 선언
- go.sum: 무결성 보장
- tidy: 정리의 핵심
go mod를 정확히 이해하면,
의존성 때문에 시간을 소모하는 일이 눈에 띄게 줄어든다.
다음 글에서는 의존성 관리 다음 단계로
Go 빌드(build)와 실행, 그리고 배포 흐름을 다루면 자연스럽다.
'backend' 카테고리의 다른 글
| Go 테스트 코드 작성 정리: testing 패키지와 Go식 테스트 문화 (1) | 2026.01.22 |
|---|---|
| Go 로깅과 설정 관리 정리: 운영 환경을 고려한 기본 기준 (1) | 2026.01.21 |
| Go 프로젝트 구조와 패키지 설계: 실무에서 흔히 쓰는 기준 정리 (0) | 2026.01.19 |
| Go 언어 select 문 정리: 여러 channel을 동시에 다루는 방법 (0) | 2026.01.18 |
| Go 언어 channel 기초: goroutine 간 통신과 동기화 방법 (1) | 2026.01.17 |