빠른 흐름

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.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/와 internal/은 실전에서 자주 쓴다

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

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

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

internal/
  auth/
  store/

internal 아래 패키지는 같은 모듈 바깥에서 import할 수 없습니다.

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

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

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

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

선택 기준

주의할 점