Quick Comparison

Go 의존성의 배포 경계는 go.mod, 여러 모듈을 함께 개발하는 로컬 표면은 go.work, 특정 의존성을 다른 버전이나 로컬 경로로 바꾸는 규칙은 replace가 담당합니다.

기본 흐름

go.mod는 모듈의 기준 파일이다

module example.com/myapp

go 1.26

require github.com/google/uuid v1.6.0

go.mod는 import 경로의 기준과 의존성 버전을 선언합니다. 하나의 저장소에 하나의 모듈만 둘 수도 있고, 필요하면 여러 모듈을 둘 수도 있습니다.

go.sum은 직접 편집하는 파일이 아니다

go.sum은 모듈 다운로드 결과의 checksum을 기록해 같은 module version 내용이 바뀌지 않았는지 검증합니다. 직접 편집해 의존성을 바꾸는 파일이 아니므로, 충돌을 해결할 때 내용을 이해할 수는 있어야 하지만 보통은 go mod tidy, go test, go build 흐름으로 정리합니다.

go mod tidy

replace는 의존성 대체 규칙이다

replace example.com/lib => ../lib

로컬에서 아직 배포하지 않은 모듈을 연결하거나, 임시 fork를 테스트할 때 replace를 씁니다. 이 규칙은 해당 go.mod를 쓰는 빌드에 영향을 줍니다.

의존하는 라이브러리의 go.mod에 들어 있는 replace는 main module의 빌드에 적용되지 않습니다. 배포하지 않은 로컬 경로 replace를 애플리케이션 go.mod에 남기면 다른 개발자와 CI에는 없는 경로를 요구하게 됩니다.

워크스페이스

여러 모듈을 같이 개발하면 go.work를 쓴다

go work init ./app ./lib

go.work는 여러 모듈을 한 작업 공간에서 같이 보게 해 줍니다. 로컬에서 app과 lib를 동시에 고치면서 import를 연결할 때 편합니다.

go 1.26

use (
	./app
	./lib
)

배포 기준은 여전히 각 모듈의 go.mod다

go.work는 로컬 개발 편의에 가깝습니다. CI나 배포 환경에서 workspace를 쓸지 여부는 팀 규칙으로 정해야 합니다. 라이브러리 자체의 의존성은 결국 각 모듈의 go.mod에 남아야 합니다.

workspace가 켜진 로컬에서는 go.work의 use와 replace가 단일 모듈 검증과 다른 결과를 만들 수 있습니다. release 후보나 라이브러리 호환성을 확인할 때는 GOWORK=off go test ./...로 각 go.mod만 사용한 결과도 확인합니다. go work sync는 workspace가 쓰는 모듈의 의존성 요구를 동기화할 때 쓰며, 임의의 replace를 배포 규칙으로 바꾸는 명령은 아닙니다.

선택 기준

주의할 점