9. Modules and Packages

Alert

이 글은 Claude Code의 도움을 받아 작성되었습니다

TL;DR

• 저장소 ⊃ 모듈 ⊃ 패키지의 세 계층 구조와 각 층의 역할 구분
• 모듈은 go.mod를 루트로 하고 전역에서 유일한 식별자(보통 저장소 경로)를 가짐
• import는 파일이 아니라 폴더(패키지) 단위이고, 경로는 모듈 이름 + 폴더 경로
• 식별자 첫 글자 대문자면 공개, 소문자면 비공개를 컴파일러가 강제
• 패키지 이름은 디렉터리명과 일치시키고 설명적으로 짓되 함수 이름에서 반복하지 않음
• internal/ 폴더는 부모 트리 밖에서 import 불가, go mod tidy로 의존성 동기화
• 프로젝트는 작으면 단일 패키지, 커지면 cmd/·internal/·pkg/로 분리

Python에서는 같은 폴더의 파일을 import utils처럼 바로 가져오거나, 상대경로(from . import helper)로 끌어다 쓴다. Go는 그렇게 동작하지 않는다. 아무 파일이나 경로로 부르는 게 아니라, 모듈과 패키지라는 단위로 움직인다. 이 글은 Python의 모듈/패키지/import/pip에 익숙한 개발자가 Go의 코드 구성 방식을 이해하도록 정리한다.

---

1. 저장소·모듈·패키지 — 세 계층

Go의 코드 구성은 세 단계로 쌓여 있다. 위에서부터 저장소, 모듈, 패키지다.

• 저장소(repository) — 버전 관리 시스템(VCS)이 다루는 공간이다. 깃 저장소 하나가 여기에 해당한다. 코드 전체가 보관되고 버전이 매겨지는 가장 바깥 껍데기다.
• 모듈(module) — 저장소 안에서 함께 배포되는 Go 라이브러리나 애플리케이션의 최상위 루트다. 하나 이상의 패키지로 구성되며, 전역에서 유일한 식별자를 가진다. 보통 저장소 경로(github.com/user/proj)를 그대로 식별자로 쓴다. 루트에 go.mod 파일이 있어야 모듈로 인정된다.
• 패키지(package) — 함께 컴파일되는 소스 파일의 묶음이다. 파일 상단의 package 선언으로 이름이 정해지고, import의 최소 단위가 된다. 하나의 폴더가 하나의 패키지다.

저장소와 모듈은 보통 1:1

대부분은 저장소 하나에 모듈 하나(루트에 go.mod 하나)다. 이 글도 그 기본 경우를 전제한다. 다만 하위 디렉터리에 go.mod를 더 두면 한 저장소가 여러 모듈로 갈리는 멀티모듈 저장소도 가능하다. 라이브러리 본체와, 무거운 의존성을 쓰는 tools/·examples/를 분리하거나 컴포넌트를 독립적으로 버전 관리할 때 쓴다. 다만 모듈 경계를 넘으면 상대경로 import가 안 되고 도구(go build ./... 등)도 모듈 단위로만 동작해 관리가 복잡해지므로, 특별한 이유가 없으면 저장소당 모듈 하나가 권장된다.

Python과 대비하면 이렇다.

Python	Go
모듈 = 파일 하나(utils.py)	패키지 = 폴더 하나
패키지 = 디렉터리 + __init__.py	모듈 = go.mod를 루트로 하는 라이브러리/앱
(저장소 개념은 언어 차원에서 안 다룸)	저장소 = VCS 공간, 모듈을 담는 바깥 껍데기

가장 헷갈리는 지점은 “패키지”라는 단어다. Python에서 패키지는 pip install로 받는 배포 단위에 가깝지만, Go에서 그 배포 단위는 모듈이다. Go의 패키지는 더 작은 단위, 즉 import해서 쓰는 폴더 하나를 가리킨다.

단어 매핑 주의

• Python “module”(파일) ↔ Go “package”(폴더)
• Python “package”(pip로 받는 것) ↔ Go “module”(go get으로 받는 것)

같은 단어라도 가리키는 대상이 한 칸씩 어긋난다. 이 표를 머릿속에 두면 나머지가 쉬워진다.

---

2. 모듈 시작하기

새 프로젝트는 모듈 초기화로 시작한다. 01편에서 다룬 go mod init이 그 명령이다.

mkdir myproj && cd myproj
go mod init github.com/user/myproj

이 명령이 go.mod 파일을 만든다. 내용은 단순하다.

module github.com/user/myproj
 
go 1.24

여기서 module 줄에 적힌 이름이 핵심이다. 이 이름이 모든 import 경로의 기준점이 된다. 모듈 안에서 다른 패키지를 부를 때 경로가 전부 이 이름에서 출발한다.

Python으로 치면 pyproject.toml을 만드는 일에 해당한다. uv init이나 [project] 섹션을 작성하는 것과 비슷한 자리다.

# pyproject.toml — Python 쪽 대응
[project]
name = "myproj"
version = "0.1.0"

다만 결정적 차이가 하나 있다. Python의 name은 패키지를 배포할 때 쓰는 이름일 뿐, 코드 안의 import 경로와 직접 묶이지 않는다. Go의 module 이름은 곧바로 import 경로가 된다. 모듈 이름을 정한다는 건 import 경로를 정한다는 뜻이다. 그래서 보통 저장소를 올릴 주소(github.com/user/myproj)를 그대로 쓴다.

하필 저장소 주소를 쓰는 이유는, 모듈 이름이 import 접두사이자 Go가 그 코드를 받아오는 위치이기도 하기 때문이다. 나 혼자 로컬에서만 빌드한다면 module myproj처럼 아무 이름이나 줘도 잘 돌아간다. 하지만 누군가(미래의 나 포함) 이 모듈을 go get으로 가져가려면 그 이름이 실제 받아올 수 있는 주소여야 한다. Go는 첫 경로 요소에 점(.)이 없는 이름(myproj)은 원격에서 받을 수 없는 것으로 취급하므로, 도메인이 들어간 주소라야 어디서 가져올지 알 수 있다.

모듈 이름을 나중에 바꾸면 생기는 일

모듈 이름은 그 모듈 안 모든 패키지의 import 접두사다. 그래서 이름을 바꾸면 그 접두사를 쓰던 import가 전부 깨진다. 예를 들어 module myproj로 시작해서 이렇게 짰다고 하자.

// main.go — 모듈 이름이 myproj일 때
import "myproj/extract"

나중에 공개하려고 go.mod의 모듈 이름을 github.com/user/myproj로 바꾸면, 위 import는 더 이상 없는 myproj를 가리켜 빌드가 깨진다. 모듈 안의 모든 자기 패키지 import를 새 접두사로 고쳐야 한다.

// 전부 이렇게 바꿔야 함
import "github.com/user/myproj/extract"

외부 패키지(fmt, github.com/gin-gonic/gin 등)를 부르는 import는 안 깨지고, 내 모듈 자신을 가리키던 import만 깨진다. 게다가 이미 이 모듈을 의존성으로 쓰던 다른 프로젝트도 똑같이 깨진다(그들에겐 사실상 다른 모듈이 된다). 그래서 처음부터 실제 저장소 주소로 정해두는 게 좋다.

---

3. 패키지와 import

패키지는 폴더, import는 폴더 단위

모든 Go 파일은 첫 줄에 자기가 속한 패키지를 선언한다.

package extract

여기서 두 규칙이 따라온다.

• 같은 폴더의 파일은 같은 패키지여야 한다. 한 폴더 안에서 package extract와 package parse를 섞을 수 없다.
• import는 파일이 아니라 폴더(패키지) 단위로 한다. Python처럼 특정 파일(from utils.helper import f)을 콕 집어 가져오지 않는다. 폴더를 통째로 가져오고, 그 안의 공개 식별자를 쓴다.

import 경로는 모듈 이름 + 폴더 경로로 만들어진다. 모듈이 github.com/user/myproj이고 그 안에 extract/ 폴더가 있다면 경로는 이렇게 된다.

import "github.com/user/myproj/extract"

Python의 from myproj.extract import names와 모양은 비슷하지만, Go는 점(.) 대신 슬래시(/)로 경로를 잇고, 끝에 오는 건 파일이 아니라 폴더라는 점이 다르다.

엄밀히는 import는 폴더 경로다

경로 끝의 extract는 폴더 이름이지, 그 안 파일이 선언한 package 이름이 아니다. 둘은 별개다. import는 폴더 경로로 하고, 코드에서 부를 때는 그 폴더가 선언한 package 이름으로 한다. 보통 이 둘을 같게 맞추지만(관례) 다를 수도 있다 — 폴더가 coolstuff인데 package mylib이면 import ".../coolstuff"로 가져와 mylib.Hello()로 부른다. 별칭을 안 붙여도 Go가 소스에서 package 이름을 읽어 알아서 묶어주므로 그냥 동작한다. 다만 goimports는 폴더 이름과 package 이름이 다르면 헷갈림을 줄이려고 실제 package 이름을 별칭으로 붙여준다(import mylib ".../coolstuff").

같은 패키지 안에서는 import가 필요 없다

같은 폴더에 있고 같은 package 이름을 가진 파일끼리는 서로를 자유롭게 부른다. import도, 접두어도 필요 없다.

// a.go
package extract
func Names() {}
 
// b.go (같은 폴더)
package extract
func run() {
    Names() // 같은 패키지 — 그냥 호출
}

Python에서 같은 모듈(파일) 안의 함수를 그냥 부르는 것과 같은 감각인데, Go에서는 그 범위가 파일이 아니라 폴더 전체로 넓어진다. 폴더 안의 파일들이 사실상 하나로 합쳐진다고 보면 된다.

다른 패키지는 폴더를 나누고 import한다

다른 동작을 하는 코드를 분리하려면 폴더를 나누고, 쓰는 쪽에서 import한다.

// extract/extract.go
package extract
func Names() []string { return nil }
 
// main.go
package main
 
import "github.com/user/myproj/extract"
 
func main() {
    names := extract.Names() // 패키지 이름으로 접근
}

다른 패키지의 식별자는 반드시 패키지명.식별자 형태로 부른다(extract.Names). 이 점이 Python의 from x import *와 다르다. Go는 이름을 전역으로 풀어 헤치지 않고, 항상 어느 패키지에서 왔는지 드러낸다.

이름이 겹치는 패키지는 alias로 구분

표준 라이브러리에는 폴더 경로는 다르지만 패키지 이름이 같은 경우가 있다. 대표적으로 crypto/rand와 math/rand 둘 다 패키지 이름이 rand다. 그대로 같이 import하면 충돌하므로 별칭(alias)을 붙인다.

import (
    crand "crypto/rand"
    mrand "math/rand"
)
 
func main() {
    _ = crand.Reader
    _ = mrand.Intn(10)
}

Python의 import numpy as np와 같은 발상이다. 다만 Go에서는 보기 좋자고 쓰는 게 아니라, 이름 충돌을 푸는 실용적 장치로 주로 쓴다.

정리

• 같은 패키지 = 같은 폴더 + 같은 package명 → import 불필요, 그냥 호출
• 다른 패키지 = 다른 폴더 → import 필요 + 패키지명.식별자로 접근
• import 경로 = 모듈 이름 + 폴더 경로

---

4. 공개와 비공개: 대문자 규칙

Go에는 public, private 키워드가 없다. 대신 식별자 첫 글자의 대소문자로 외부 공개 여부를 정한다.

• 첫 글자가 대문자 → 공개(exported). 다른 패키지에서 접근 가능
• 첫 글자가 소문자 → 비공개(unexported). 같은 패키지 안에서만 접근 가능

package extract
 
func Names() []string { return nil } // 공개 — 밖에서 extract.Names() 가능
func parse() string   { return "" }  // 비공개 — extract 패키지 안에서만 사용
 
type User struct {
    Name string // 공개 필드
    age  int    // 비공개 필드
}

이 규칙은 함수, 타입, 변수, 상수, 구조체 필드 등 모든 패키지 레벨 식별자에 똑같이 적용된다. 그래서 02편에서 이름 짓는 법을 다룰 때 대소문자가 단순한 스타일이 아니라고 했던 것이다. 첫 글자 하나가 접근 범위를 결정한다.

Python과 비교하면 차이가 분명하다. Python에서 _name처럼 밑줄을 붙이는 건 “쓰지 말라”는 관례일 뿐, 강제력이 없다. 밖에서 obj._name으로 접근해도 인터프리터는 막지 않는다.

# Python — 관례일 뿐, 막지 않음
class User:
    def __init__(self):
        self.name = "Alice"
        self._age = 30   # "내부용"이라는 신호일 뿐
 
u = User()
print(u._age)  # 30 — 그냥 접근됨

Go는 컴파일러가 강제한다. 소문자로 시작하는 식별자를 다른 패키지에서 부르면 컴파일 자체가 실패한다.

공개 API를 좁게 유지하는 법

밖에서 꼭 써야 하는 것만 대문자로, 나머지는 소문자로 둔다. 공개 면적이 좁을수록 나중에 내부 구현을 바꿀 자유가 커진다. Python에서는 이걸 규율로 지켜야 하지만, Go에서는 대소문자만 맞추면 컴파일러가 대신 지켜 준다.

---

5. 패키지 이름 짓기 관례

디렉터리 이름과 맞춘다

패키지 이름은 보통 그 패키지가 든 디렉터리 이름과 같게 짓는다. extract/ 폴더 안 파일이면 package extract다. 예외는 실행 파일의 진입점이 되는 main, 그리고 버전이 붙은 디렉터리 정도다. 이 관례를 지키면 import 경로의 마지막 조각과 코드에서 쓰는 패키지 이름이 일치해 혼란이 줄어든다.

설명적으로 짓는다 — util 같은 잡탕 금지

여러 가지를 한데 모은 util, common, helpers 같은 이름은 피한다. 그 안에 뭐가 있는지 이름만 봐서는 알 수 없기 때문이다. 기능을 드러내는 이름으로 폴더를 나눈다.

// 권장하지 않음 — util에 뭐가 들었는지 모른다
util.ExtractNames(doc)
 
// 권장 — 패키지 이름이 곧 설명이 된다
extract.Names(doc)

패키지명을 식별자에서 반복하지 않는다

호출하는 쪽에서는 항상 패키지명.식별자 형태가 되므로, 식별자에 패키지 이름을 또 넣으면 말이 겹친다.

// 권장하지 않음 — "extract.ExtractNames" 처럼 extract가 두 번
package extract
func ExtractNames() {}
 
// 권장 — 호출하면 "extract.Names"로 깔끔하다
package extract
func Names() {}

예외는 패키지 이름과 핵심 타입/함수가 자연스럽게 같아지는 경우다. 표준 라이브러리의 sort.Sort가 그런 예다. 정렬 패키지의 대표 동작이 정렬이니 이름이 겹쳐도 어색하지 않다. 이런 경우만 예외로 둔다.

한 줄 기준

호출하는 쪽에서 어떻게 읽히는지를 먼저 그려 본다. extract.Names(doc)처럼 패키지명과 식별자가 한 문장으로 읽히면 잘 지은 이름이다.

---

6. internal 패키지

공개 코드와 내부 구현을 나눌 때 Go는 internal/이라는 특별한 폴더 이름을 제공한다. internal/ 안의 패키지는 그 폴더의 부모 디렉터리 트리 밖에서는 import할 수 없다. 이 제약은 관례가 아니라 컴파일러가 강제한다.

구조 예시를 보자.

myproj/
├── go.mod              // module github.com/user/myproj
├── main.go
├── internal/
│   └── store/
│       └── store.go    // package store
└── extract/
    └── extract.go      // package extract

여기서 internal/store는 myproj/ 트리 안의 코드(main.go, extract)에서는 자유롭게 import할 수 있다. 하지만 이 모듈을 가져다 쓰는 다른 모듈은 github.com/user/myproj/internal/store를 import하려 하면 컴파일 에러가 난다.

// 같은 모듈 안 — 가능
import "github.com/user/myproj/internal/store"
 
// 다른 모듈에서 — 컴파일 에러
// use of internal package ... not allowed

쓰임은 명확하다. 공개하고 싶지 않은 내부 구현을 internal/에 두면, 외부에서 그 코드에 의존하는 일을 원천 차단할 수 있다. 공개 API는 좁게 유지하고 내부는 마음대로 바꿀 수 있는 자유가 생긴다.

Python에는 이런 강제 장치가 없다. 4번에서 본 _prefix처럼 패키지 차원에서도 “내부용”이라는 신호를 줄 수는 있지만, 다른 코드가 굳이 import하겠다면 막을 방법이 없다. Go의 internal/은 폴더 이름 하나로 그 경계를 컴파일러가 지켜 준다.

---

7. 의존성 관리

외부 라이브러리를 다루는 명령은 01편의 go get/go install 표와 이어진다. 여기서는 의존성 관리에 초점을 맞춘다.

추가와 정리

# 의존성 추가 — go.mod와 go.sum에 기록된다
go get github.com/gin-gonic/gin
 
# 의존성 정리·동기화 — 코드가 실제로 쓰는 것에 맞춘다
go mod tidy

go get은 라이브러리를 추가하고, go mod tidy는 코드를 훑어 실제로 import하는 것만 남기고 빠진 건 채운다. 안 쓰는 의존성은 go.mod에서 빠지고, import했는데 빠진 건 추가된다. 작업을 마친 뒤 go mod tidy를 돌려 상태를 맞추는 게 습관이다.

버전 확인과 업그레이드

# 사용 가능한 버전 목록 확인
go list -m -versions github.com/gin-gonic/gin
 
# 특정 버전 지정
go get github.com/gin-gonic/gin@v1.10.0
 
# 마이너·패치까지 최신으로 업그레이드
go get -u github.com/gin-gonic/gin
 
# 패치 버전만 올리기(더 보수적)
go get -u=patch github.com/gin-gonic/gin

go.sum의 역할

go get을 하면 go.mod에 버전이, go.sum에 그 버전의 체크섬이 기록된다. go.sum은 받은 의존성이 위변조되지 않았는지 검증하는 잠금 역할을 한다. Python의 uv.lock이나 requirements.txt의 해시 핀과 비슷한 위치다. 두 파일 모두 버전 관리에 커밋한다.

Python과 대응을 정리하면 이렇다.

Go	Python(uv)	용도
go get <pkg>	uv add <pkg>	의존성 추가
go mod tidy	uv sync	실제 사용에 맞게 정리·동기화
go get -u <pkg>	uv lock --upgrade-package <pkg>	업그레이드
go.mod + go.sum	pyproject.toml + uv.lock	의존성 명세 + 잠금

벤더링은 지금은 비선호

의존성을 저장소 안 vendor/ 폴더에 복사해 넣는 벤더링도 가능하다(go mod vendor). 다만 모듈 캐시와 go.sum 검증이 자리잡은 지금은 특수한 상황(폐쇄망 빌드 등)이 아니면 잘 쓰지 않는다. 기본은 모듈 캐시에 맡긴다.

---

8. 모듈 구성(프로젝트 레이아웃)

정해진 정답 구조가 강제되지는 않지만, 규모에 따라 자리잡은 관례가 있다.

작으면 단일 패키지

코드가 작으면 폴더를 나누지 않고 루트에 파일 몇 개로 둔다. package main 하나로 충분한 경우가 많다. 미리 폴더부터 쪼개는 건 과하다.

myproj/
├── go.mod
├── main.go
└── helper.go

여러 바이너리는 cmd/

실행 파일을 여럿 만든다면(예: 서버와 CLI 도구), 루트에 cmd/ 폴더를 두고 바이너리마다 하위 디렉터리를 만든다.

myproj/
├── go.mod
├── cmd/
│   ├── server/
│   │   └── main.go   // 서버 바이너리
│   └── cli/
│       └── main.go   // CLI 바이너리
├── internal/         // 공개하지 않을 내부 코드
└── pkg/              // 외부에 공개할 라이브러리 코드(필요할 때만)

• internal/ — 이 모듈 안에서만 쓰는 코드(6번 참고). 외부 import 차단
• pkg/ — 다른 모듈이 가져다 써도 되는 공개 코드. 필요할 때만 만든다

pkg/는 의무가 아니다. 공개할 게 없으면 만들지 않는다.

순환 의존성은 컴파일 에러

패키지 A가 B를 import하고 B가 다시 A를 import하면, Go는 이를 순환 의존성으로 보고 컴파일을 거부한다. Python은 런타임에 순환 import를 어느 정도 허용하지만, Go는 컴파일 단계에서 막는다. 순환이 생기면 보통 공통 부분을 제3의 패키지로 빼서 푼다.

init 함수와 blank import는 절제

패키지에는 init 함수를 둘 수 있는데, 이 함수는 패키지가 로드될 때 자동으로 한 번 실행된다. 편해 보이지만 실행 순서가 코드에 드러나지 않아 흐름을 추적하기 어렵게 만든다. 가능하면 명시적인 초기화를 쓰고 init은 절제하는 게 좋다.

blank import는 그 init만 실행시키려고 식별자 없이 패키지를 가져오는 방식이다.

import _ "github.com/lib/pq" // 패키지의 init만 실행(드라이버 등록 등)

데이터베이스 드라이버 등록처럼 정해진 패턴에서만 쓰고, 일반적인 의존성 연결에는 쓰지 않는다.

---

Python 개발자를 위한 한 줄 요약

Go에서 코드를 나누고 묶는 단위는 폴더(패키지)와 go.mod(모듈)다. 대소문자로 공개 범위를 정하고, import 경로는 모듈 이름에서 출발한다 — Python처럼 아무 파일이나 끌어오는 대신, 경계를 컴파일러가 지켜 준다.

여기까지가 모듈과 패키지의 큰 그림이다. 인터페이스는 07편, 오류 처리는 08편에서 다뤘고, 앞으로는 고루틴과 동시성(고루틴 스케줄링, 채널), 제네릭처럼 더 깊은 주제를 별도 편에서 다룬다. 외부 라이브러리의 사용법이 궁금할 때는 pkg.go.dev에서 찾으면 된다. 공개된 모듈이 자동으로 인덱싱되어 있어, 패키지의 공개 식별자와 문서를 바로 확인할 수 있다.