문서가격블로그
문의하기
로그인무료로 가입하기
Back to Tech Articles

대규모 Go 애플리케이션을 위한 최적의 프로젝트 레이아웃

Sep 15, 2025
# Misc

Ethan Miller

Product Engineer · Leapcell

이 게시물은 English, 日本語 및 Deutsch에서도 볼 수 있습니다.
Cover of "대규모 Go 애플리케이션을 위한 최적의 프로젝트 레이아웃"

소개

Go가 견고하고 확장 가능한 시스템 구축에 계속해서 인기를 얻으면서 대규모 Go 프로젝트의 구성은 장기적인 성공에 중요한 요소가 됩니다. 잘 구조화된 프로젝트는 가독성과 유지보수성을 향상시킬 뿐만 아니라 팀 협업을 촉진하고 개발 주기를 가속화합니다. 반대로, 잘못 구성된 코드베이스는 빠르게 복잡한 문제로 이어져 향후 개발을 방해하고 기술 부채를 증가시킬 수 있습니다. 이 글에서는 대규모 Go 애플리케이션 구조화를 위한 모범 사례를 살펴보고 유지보수 가능하고 확장 가능하며 관용적인 Go 프로젝트를 만들기 위한 청사진을 제공합니다.

핵심 개념

프로젝트 구조의 구체적인 내용을 살펴보기 전에 이러한 모범 사례의 기초가 되는 몇 가지 핵심 개념을 정의해 보겠습니다.

  • 모듈성: 대규모 시스템을 작고 독립적이며 상호 교환 가능한 구성 요소로 분할합니다. 각 모듈은 명확한 책임을 지고 잘 정의된 인터페이스를 가져야 합니다.
  • 관심사 분리(SoC): 소프트웨어 시스템 내에서 서로 다른 기능 또는 책임을 구분하고 이를 서로 다른 구성 요소에 할당합니다. 예를 들어, 비즈니스 로직은 데이터 액세스 로직과 분리되어야 합니다.
  • 캡슐화: 단일 단위 내에서 데이터를 조작하는 데이터와 메서드를 번들로 묶고 구성 요소의 내부 상태에 직접 액세스하는 것을 제한합니다. Go에서는 종종 내보내지 않은 필드와 메서드를 통해 이를 달성합니다.
  • 관용적인 Go: Go 커뮤니티에서 일반적으로 사용되는 규칙과 패턴을 준수합니다. 여기에는 명확한 명명, 오류 처리 및 동시성 패턴이 포함됩니다.

대규모 Go 애플리케이션 구조화

좋은 프로젝트 구조의 목표는 코드를 찾고, 목적을 이해하고, 의도하지 않은 부작용을 일으키지 않고 수정하기 쉽게 만드는 것입니다. 다음은 대규모 Go 애플리케이션을 구성하는 자세한 접근 방식입니다.

최상위 디렉토리 구조

대규모 Go 프로젝트에 대한 일반적이고 효과적인 최상위 구조는 종종 다음과 같습니다.

/my-awesome-app
├── cmd/
├── internal/
├── pkg/
├── api/
├── web/
├── config/
├── build/
├── scripts/
├── test/
├── vendor/
├── Dockerfile
├── Makefile
├── go.mod
├── go.sum
└── README.md

이러한 각 디렉토리를 살펴보겠습니다.

  • cmd/: 이 디렉토리는 실행 가능한 애플리케이션의 주요 패키지를 보유합니다. cmd/ 내의 각 하위 디렉토리는 별개의 실행 파일을 나타냅니다.

    • 예시: 애플리케이션에 웹 서버와 백그라운드 작업자가 있다면 cmd/server/main.go 및 cmd/worker/main.go를 가질 수 있습니다. 이렇게 하면 이것이 독립 실행형 애플리케이션임을 명확하게 알 수 있습니다.
    // cmd/server/main.go
package main

import (
    "fmt"
    "log"
    "net/http"

    "my-awesome-app/internal/app" // 내부 패키지 가져오기 예시
)

func main() {
    fmt.Println("Starting web server...")
    http.HandleFunc("/", app.HandleRoot) // 앱 로직 사용 예시
    log.Fatal(http.ListenAndServe(":8080", nil))
}

  • internal/: 캡슐화를 강제하기 위한 중요한 디렉토리입니다. Go의 특수 internal 패키지 규칙은 internal/ 내의 패키지가 바로 위에서만 가져올 수 있음을 의미합니다. 이를 통해 다른 프로젝트에서 내부 코드를 직접 가져와 종속하는 것을 방지하여 명확한 API 경계를 강화할 수 있습니다.

    • 예시: internal/ 디렉토리는 다음과 같은 내용을 포함할 수 있습니다.
      • internal/app/: 핵심 애플리케이션 로직, 비즈니스 규칙 및 서비스.
      • internal/data/: 데이터 액세스 로직 (리포지토리, ORM, 데이터베이스 연결).
      • internal/platform/: 인프라 수준 코드 (예: 메일러, 로깅, 인증 세부 정보).
      • internal/thirdparty/: 직접 노출하고 싶지 않은 외부 서비스에 대한 래퍼.
    // internal/app/handlers.go
package app

import (
    "fmt"
    "net/http"
)

func HandleRoot(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "Hello from the internal app!")
}

    이 app 패키지는 my-awesome-app 외부의 다른 Go 모듈에서 직접 가져올 수 없습니다.

  • pkg/: 외부 애플리케이션이나 패키지에서 안전하게 사용할 수 있는 라이브러리 코드용입니다. 다른 프로젝트에서 활용할 수 있는 재사용 가능한 구성 요소를 제공하려는 경우 여기에 배치하십시오.

    • 예시: 일반 유틸리티 함수에 대한 pkg/utils/ 또는 다른 사람이 사용할 수 있는 인증 라이브러리를 구축하는 경우 pkg/auth/.
    // pkg/utils/stringutils.go
package utils

// Reverse는 문자열을 뒤집습니다.
func Reverse(s string) string {
    runes := []rune(s)
    for i, j := 0 := 0; i < len(runes)/2; i, j = i+1, j-1 {
        runes[i], runes[j] = runes[j], runes[i]
    }
    return string(runes)
}

  • api/: OpenAPI/Swagger 사양, Protobuf 정의 또는 GraphQL 스키마와 같은 API 정의를 포함합니다. 이 디렉토리는 백엔드와 클라이언트 간의 명확한 계약을 보장합니다.

  • web/: Go 애플리케이션이 직접 제공하는 경우 정적 웹 자산, 템플릿 및 잠재적으로 프런트엔드 빌드 아티팩트입니다.

  • config/: 구성 파일, 템플릿 또는 스키마 정의 (예: .yaml, .json).

  • build/: 다른 환경에 대한 Dockerfile, 빌드 스크립트 또는 CI/CD 구성과 같은 빌드 관련 자산입니다.

  • scripts/: 개발, 배포 또는 도구링을 위한 다양한 스크립트입니다.

  • test/: 개별 단위 테스트와 함께 바로 옆에 있지 않은 장기 통합 테스트 또는 엔드투엔드 테스트입니다.

  • vendor/: Go Modules에서 폐기되었지만 과거에는 타사 종속 항목의 복사본을 저장하는 데 사용되었습니다. go mod vendor는 여전히 이 디렉토리를 생성할 수 있지만, 명시적 벤더링이 필요한 경우(예: 에어 갭 환경)가 아닌 이상 일반적으로 VCS에 커밋되지 않습니다.

  • Dockerfile: 애플리케이션의 Docker 이미지를 정의합니다.

  • Makefile: 일반적인 빌드, 테스트 및 배포 명령을 포함합니다.

  • go.mod, go.sum: 종속성 관리에 필수적인 Go 모듈 정의 파일입니다.

  • README.md: 프로젝트 개요, 설정 지침 및 기여 가이드라인입니다.

명명 및 모듈성 원칙

  • 패키지 명명: Go 패키지 이름은 짧고 모두 소문자이며 내용에 대한 설명이어야 합니다. 복수형을 피하십시오 (예: pkg/users는 pkg/user여야 합니다).
  • 인터페이스 캡슐화: 구현되는 곳이 아닌 소비되는 곳에 인터페이스를 정의합니다. 이는 느슨한 결합을 촉진합니다.
  • 결합도 및 응집도: 높은 응집도(관련 코드가 함께 배치됨)와 낮은 결합도(구성 요소가 서로에 대한 종속성이 최소화됨)를 목표로 합니다. internal/ 디렉토리는 이를 달성하기 위한 핵심 도구입니다.

예시: HTTP 요청 처리

cmd/, internal/app/, internal/data/ 디렉토리가 HTTP 요청 처리 시나리오에서 어떻게 상호 작용하는지 살펴보겠습니다.

// internal/data/user.go
package data

import (
	"errors"
	"fmt"
)

// User는 사용자 엔티티를 나타냅니다.
type User struct {
	ID   string
	Name string
}

// UserRepository는 사용자 데이터 작업을 위한 인터페이스를 정의합니다.
type UserRepository interface {
	GetUserByID(id string) (*User, error)
}

// InMemoryUserRepository는 메모리 내 맵을 사용하여 UserRepository를 구현합니다.
type InMemoryUserRepository struct {
	users map[string]*User
}

// NewInMemoryUserRepository는 새 메모리 내 사용자 리포지토리를 생성합니다.
func NewInMemoryUserRepository() *InMemoryUserRepository {
	return &InMemoryUserRepository{
		users: map[string]*User{
			"1": {ID: "1", Name: "Alice"},
			"2": {ID: "2", Name: "Bob"},
		},
	}
}

// GetUserByID는 메모리 내 저장소에서 ID로 사용자를 검색합니다.
func (r *InMemoryUserRepository) GetUserByID(id string) (*User, error) {
	user, ok := r.users[id]
	if !ok {
		return nil, errors.New("user not found")
	}
	return user, nil
}
// internal/app/userService.go
package app

import (
	"my-awesome-app/internal/data" // 내부 데이터 패키지 가져오기
)

// UserService는 사용자에 대한 비즈니스 로직을 제공합니다.
type UserService struct {
	repo data.UserRepository
}

// NewUserService는 새 사용자 서비스를 생성합니다.
func NewUserService(repo data.UserRepository) *UserService {
	return &UserService{repo: repo}
}

// GetUserName은 ID로 사용자의 이름을 반환합니다.
func (s *UserService) GetUserName(id string) (string, error) {
	user, err := s.repo.GetUserByID(id)
	if err != nil {
		return "", err
	}
	return user.Name, nil
}
// cmd/server/main.go
package main

import (
	"fmt"
	"log"
	"net/http"
	"strings"

	"my-awesome-app/internal/app"
	"my-awesome-app/internal/data"
)

func main() {
	userRepo := data.NewInMemoryUserRepository()
	userService := app.NewUserService(userRepo)

	http.HandleFunc("/user/", func(w http.ResponseWriter, r *http.Request) {
		id := strings.TrimPrefix(r.URL.Path, "/user/")
		if id == "" {
			http.Error(w, "User ID is required", http.StatusBadRequest)
			return
		}

		name, err := userService.GetUserName(id)
		if err != nil {
			http.Error(w, err.Error(), http.StatusNotFound)
			return
		}
		fmt.Fprintf(w, "User Name: %s\n", name)
	})

	fmt.Println("Server listening on :8080...")
	log.Fatal(http.ListenAndServe(":8080", nil))
}

이 예시에서 cmd/server/main.go는 모든 것을 연결합니다. internal/app/userService.go는 데이터 액세스를 위해 internal/data/user.go에 종속되는 비즈니스 로직을 포함합니다. app 또는 data 패키지는 외부 모듈에서 직접 가져올 수 없으므로 내부 일관성과 제어된 종속성을 보장합니다.

결론

대규모 Go 애플리케이션을 효과적으로 구성하는 것은 장기적인 성공에 매우 중요합니다. 명확하고 모듈식이며 관용적인 프로젝트 구조를 채택함으로써 개발자는 유지보수성, 협업 촉진 및 애플리케이션 확장을 훨씬 쉽게 할 수 있습니다. cmd/, internal/, pkg/ 디렉토리를 활용하는 권장 구조는 견고하고 확장 가능한 Go 시스템 구축을 위한 견고한 기반을 제공합니다. 잘 구조화된 Go 프로젝트는 예측 가능하고 즐겁게 작업할 수 있으며, 개발자가 종속성을 푸는 대신 기능에 집중할 수 있도록 합니다.

Share this article

HackerNews

More Posts from Leapcell

cover

브라우저 기반 애플리케이션을 위한 Go와 WebAssembly

cover

맞춤형 Go 린터를 사용한 팀 코딩 규칙 강제 적용

Popular Posts