[Go 공식문서 한국어 정리] ⓪15. Go Modules로 마이그레이션하기

[Go 공식문서 한국어 정리] ⓪15. Go Modules로 마이그레이션하기

원문 제목: Migrating to Go Modules
작성자: Jean Barkhuysen

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📌 1. 서론 — 이 문서가 다루는 내용
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Go 1.11에서 도입된 모듈 시스템은 공식 의존성 관리 솔루션입니다.
기존 dep, glide 같은 도구를 사용하거나 GOPATH에 의존하던 프로젝트를 모듈로 전환하는 방법을 설명합니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📌 2. 핵심 개념
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

① go mod init — 모듈 초기화
go mod init 명령으로 go.mod 파일을 생성합니다.
이미 dep이나 glide를 사용 중이면 기존 설정 파일에서 의존성을 자동으로 가져옵니다.

② go mod tidy — 의존성 정리
모듈이 사용하는 모든 패키지를 찾아서 go.mod와 go.sum을 갱신합니다.
// indirect 주석은 직접 import하지 않지만 필요한 의존성을 표시합니다.

③ go.sum — 체크섬 데이터베이스
go.mod에 기록된 각 라이브러리 버전의 체크섬을 저장합니다.
의존성의 무결성을 보장합니다.

④ v2 이상의 메이저 버전
v2.0.0 이상으로 태그된 프로젝트는 모듈 경로에 /v2 접미사를 추가해야 합니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📌 3. 주요 내용 상세
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

프로젝트는 세 가지 상태 중 하나일 수 있습니다.
1. 완전히 새로운 프로젝트
2. dep, glide 같은 비모듈 의존성 관리자를 사용하는 기존 프로젝트
3. 의존성 관리자 없이 GOPATH에 의존하는 기존 프로젝트

의존성 관리자가 있는 경우:
go mod init github.com/my/project
go mod tidy
go build ./...
go test ./...

go mod init이 Godeps.json, Gopkg.lock 등을 자동으로 인식합니다.
go mod tidy가 전이적 의존성을 해결하고 체크섬을 생성합니다.

버전 감사:
go list -m all로 현재 선택된 버전을 확인하고,
이전 의존성 파일과 비교하여 적절한 버전인지 확인합니다.
go mod why -m와 go mod graph로 버전 선택 이유를 파악할 수 있습니다.
go get으로 특정 버전으로 업그레이드/다운그레이드합니다.

의존성 관리자가 없는 경우:
go mod init으로 모듈 경로를 선언합니다.
go mod tidy로 모든 의존성을 자동으로 다운로드합니다.
최신 버전이 선택되므로, GOPATH에 있던 구버전과 호환되지 않을 수 있습니다.
이 경우 go get으로 원하는 버전을 지정합니다.

테스트 조정:
모듈 캐시는 읽기 전용이므로 테스트가 패키지 디렉토리에 파일을 쓰면 실패합니다.
임시 디렉토리에 파일을 복사하여 사용하도록 수정해야 합니다.
다른 모듈의 패키지에 상대 경로를 사용하는 테스트도 실패할 수 있습니다.
테스트 입력을 .go 소스 파일에 임베딩하거나 모듈 낶부로 복사해야 합니다.

정식 경로(canonical path):
go.mod 파일에 선언된 모듈 경로가 표준입니다.
github.com/golang/lint 대신 golang.org/x/lint를 사용해야 합니다.
import 문을 업데이트해야 할 수 있습니다.

릴리스 게시:
git tag v1.2.0 && git push origin v1.2.0으로 버전을 태깅합니다.
의존성에 Breaking Change가 없으면 go.mod 추가는 하위 호환됩니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📌 4. 실전 활용 / 예시
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

새로운 Go 프로젝트는 항상 go mod init으로 시작하는 것이 좋습니다.
기존 프로젝트의 모듈 전환은 go mod init과 go mod tidy 두 명령으로 대부분 완료됩니다.
CI/CD 파이프라인에서 go.sum의 무결성을 검증하면 보안을 강화할 수 있습니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📌 5. 정리
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Go Modules는 공식 의존성 관리 솔루션입니다.
go mod init으로 시작하고, go mod tidy로 의존성을 정리합니다.
go.sum은 의존성 무결성을 보장하며, go list -m all로 버전을 감사할 수 있습니다.

📎 출처 링크
https://go.dev/blog/migrating-to-go-modules

#Go #Golang #modules #dependency #공식문서