Quick Flow

mkdir myapp
cd myapp
go mod init example.com/myapp

go.mod는 단순 의존성 파일이 아니라 이 프로젝트의 모듈 경계와 import 기준점입니다.

기본 흐름

go mod init부터 시작한다

Go 프로젝트는 보통 폴더를 만든 뒤 go mod init으로 시작합니다. 이 명령이 현재 디렉터리를 하나의 모듈 경계로 만들고, import 경로의 기준점을 정합니다.

go mod init example.com/myapp

생성된 go.mod는 대략 이런 형태입니다.

module example.com/myapp

go 1.26

여기서 module 경로는 나중에 패키지를 import할 때 기준이 됩니다. go directive는 이 모듈이 기대하는 최소 언어·도구 동작을 나타내므로, 새 문법을 쓸 때는 CI와 개발자의 toolchain도 함께 맞춰야 합니다.

패키지와 모듈은 같은 말이 아니다

• 모듈: go.mod 기준 배포/의존성 경계
• 패키지: 같은 디렉터리에 모인 Go 소스 묶음

즉 하나의 모듈 안에 여러 패키지가 들어갈 수 있습니다.

myapp/
  go.mod
  cmd/api/main.go
  internal/service/user.go
  pkg/timeutil/clock.go

초반 구조는 단순하게, 경계는 분명하게

작은 프로젝트라면 처음부터 복잡한 디렉터리 트리를 만들 필요는 없습니다. 다만 실행 진입점과 재사용 코드 경계는 빨리 분리해 두는 편이 좋습니다.

myapp/
  go.mod
  main.go

프로젝트가 커지면 보통 아래 구조가 자주 나옵니다.

• cmd/: 실행 파일 진입점
• internal/: 외부 모듈에서 직접 import하지 못하게 막을 코드
• pkg/: 외부 재사용 의도가 분명할 때만 쓰는 관례 디렉터리

cmd/와 pkg/는 Go 도구가 특별 취급하는 문법이 아닙니다. internal/만 import 규칙을 강제합니다. 외부에 안정 API를 약속할 계획이 없다면 코드가 있다는 이유만으로 pkg/ 아래에 둘 필요는 없습니다.

cmd/와 internal/은 실전에서 자주 쓴다

cmd/는 API 서버, 워커, CLI처럼 실행 단위가 둘 이상일 때 특히 유용합니다.

cmd/
  api/
    main.go
  worker/
    main.go

internal/은 "이 코드는 우리 모듈 안에서만 써야 한다"는 의도를 구조로 드러냅니다.

internal/
  auth/
  store/

internal 아래 패키지는 해당 internal의 부모 디렉터리 바깥에서 import할 수 없습니다. 같은 모듈 안이라도 그 디렉터리 경계 밖이면 import할 수 없고, 반대로 허용 범위 안의 여러 모듈은 이 경계를 공유할 수 있습니다.

go run, go build, go test 진입점 감각

go run .
go build ./...
go test ./...

• go run .: 현재 패키지를 바로 실행
• go build ./...: 하위 패키지 전체 빌드 확인
• go test ./...: 하위 패키지 전체 테스트

작은 프로젝트에서도 이 세 명령이 초반 표준 흐름이 됩니다.

go run .은 현재 디렉터리가 main package일 때만 실행 파일을 만듭니다. 또 ./...는 현재 모듈 아래의 package 패턴이며, nested module은 자동으로 모두 포함하지 않습니다. 저장소에 go.mod가 여러 개라면 각 모듈 또는 workspace 기준으로 검증 명령을 정합니다.

선택 기준

주의할 점