backend

Go 모듈(go mod)과 의존성 관리: 실무에서 헷갈리지 않는 기준 정리

mirabo01 2026. 1. 20. 22:09

프로젝트 구조까지 정리했다면, 이제 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)와 실행, 그리고 배포 흐름을 다루면 자연스럽다.