[Go 공식문서 한국어 정리] ⓪21. Go Modules v2 이상 다루기

[Go 공식문서 한국어 정리] ⓪21. Go Modules v2 이상 다루기

원문 제목: Go Modules: v2 and Beyond
작성자: Jean Barkhuysen; Tyler Bui-Palsulich

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

프로젝트가 성숙해지면서 과거의 설계 결정을 변경해야 할 때가 있습니다.
이 문서는 메이저 버전 v2 이상을 생성하고 게시하는 방법, 그리고 여러 메이저 버전을 유지하는 방법을 설명합니다.

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

① import 호환성 규칙
같은 import 경로를 가진 패키지는 하위 호환되어야 합니다.
새 메이저 버전은 이전 버전과 하위 호환되지 않으므로 다른 모듈 경로를 가져야 합니다.

② 메이저 버전 접미사
v2부터 모듈 경로 끝에 /v2, /v3 등을 추가해야 합니다.
gopkg.in은 .v2 형태를 허용하지만, 다른 도메인은 /v2가 필요합니다.

③ 서브디렉토리 전략
v2/ 디렉토리에 v2+ 코드를 개발하는 것이 권장됩니다.
이는 GOPATH 모드와도 호환되며, 모든 메이저 버전을 동시에 개발할 수 있습니다.

④ 브랜치 전략
브랜치로 메이저 버전을 분리할 수도 있지만, 기본 브랜치에 v2+ 코드가 있으면
모듈을 인식하지 못하는 도구에서 혼란이 생길 수 있습니다.

⑤ v2 개발 및 게시
v2/ 디렉토리를 만들고 go.mod의 모듈 경로에 /v2를 추가합니다.
모든 낶부 import 경로도 /v2를 포함하도록 업데이트합니다.
v2.0.0-alpha.1 같은 프리릴리즈로 실험할 수 있습니다.
안정화 후 v2.0.0 태그를 게시합니다.

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

github.com/googleapis/gax-go 예시:
- v1: github.com/googleapis/gax-go
- v2: github.com/googleapis/gax-go/v2

v2 디렉토리를 만들고 기존 코드를 복사합니다.
go mod edit -module github.com/googleapis/gax-go/v2 v2/go.mod으로 모듈 경로를 변경합니다.

find와 sed로 모든 import 경로를 업데이트합니다.
find . -type f -name '*.go' -exec sed -i -e 's,github.com/my/project,github.com/my/project/v2,g' {} ;

v2는 별도의 모듈로 취급되므로 v0/v1과 동시에 빌드에 포함될 수 있습니다.

메이저 버전 변경은 개발 및 유지보수 오버헤드를 증가시킵니다.
사용자도 마이그레이션 비용을 감수해야 합니다.
따라서 강력한 이유가 있을 때만 메이저 버전을 변경해야 합니다.

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

라이브러리를 설계할 때는 v1 릴리스 전에 API를 충분히 검증합니다.
v2로 넘어갈 때는 마이그레이션 가이드를 작성하여 사용자 부담을 줄입니다.

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

메이저 버전 v2+는 모듈 경로에 접미사를 추가해야 합니다.
서브디렉토리 전략이 GOPATH 호환성과 유지보수 측면에서 가장 권장됩니다.
메이저 버전 변경은 큰 비용이 따른므로 신중하게 결정해야 합니다.

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

#Go #Golang #modules #v2 #semver #공식문서