복잡함을 피하는 실용적 백엔드 폴더 구조
과도한 아키텍처를 피하고, cmd, internal, migrations 등 실무에서 가장 널리 쓰이는 직관적이고 실용적인 폴더 구조를 알아봅니다.
백엔드 코딩을 시작할 때 비개발자들을 가장 당황하게 만드는 것은 '도대체 어느 폴더에 무슨 파일을 만들어야 하는가?'입니다. AI에게 "로그인 기능 만들어줘"라고 지시하면, 어떤 AI는 `main.go` 파일 하나에 수천 줄의 코드를 전부 때려 넣고, 어떤 AI는 쓸데없이 폴더를 10단계로 쪼개어 알아보기 힘들게 만듭니다. 이번 파트에서는 복잡하고 거창한 아키텍처를 피하면서도, 전 세계 Go 개발자들이 가장 사랑하고 실무에서 널리 쓰이는 가장 깔끔한 폴더 구조인 `cmd`와 `internal` 구조에 대해 알아봅니다.
모든 프로그램의 심장부: `cmd` 폴더
백엔드 프로젝트를 열었을 때 가장 먼저 찾아야 할 폴더는 `cmd` (command의 약자)입니다. 이 폴더 안에는 우리 서버를 켜고 끄는 전원 버튼인 `main.go` 파일이 들어있습니다.
`main.go` 파일은 회사의 '프론트 데스크'와 같습니다. 이곳에서는 복잡한 업무를 직접 처리하지 않습니다. 그저 데이터베이스를 켜서 연결하고, 서버 포트(예: 8080번)를 열고, 일꾼들을 배치하는 세팅 작업만 수행합니다.
cmd 폴더의 철칙
- 1cmd 폴더 안에는 서버를 실행하기 위한 설정 코드(main.go)만 있어야 합니다.
- 2이곳에 '비밀번호를 검사하는 로직'이나 '게시글을 DB에 저장하는 쿼리문' 같은 복잡한 비즈니스 로직이 한 줄이라도 들어가면 안 됩니다.
외부인 출입 금지구역: `internal` 폴더
`cmd`가 전원 버튼이라면, 실제 우리 서비스의 핵심 두뇌이자 모든 백엔드 코드가 모여 있는 진짜 작업장은 `internal` 폴더입니다.
Go 언어에는 아주 독특하고 강력한 폴더 규칙이 하나 있습니다. 폴더 이름을 `internal`이라고 지으면, Go 컴파일러가 강력한 문지기 역할을 하여 "이 폴더 밖의 다른 프로젝트나 외부에 있는 코드는 절대 이 폴더 안의 코드를 가져다 쓸(import) 수 없다!"라고 강제합니다. 즉, 우리 서버만의 철저한 프라이빗 금고가 되는 것입니다.
가장 실용적인 폴더 구조 예시
내_프로젝트_폴더/
├── cmd/
│ └── api/
│ └── main.go <-- 서버 전원 켜는 곳 (DB 세팅, 포트 열기)
├── internal/
│ ├── user/ <-- 유저 도메인 (회원가입, 로그인 등)
│ ├── post/ <-- 게시글 도메인 (글쓰기, 읽기 등)
│ └── auth/ <-- 인증 도메인 (토큰 검사 등)
├── migrations/ <-- DB 테이블 생성(CREATE TABLE) 스크립트 모음
├── go.mod <-- 외부 패키지 장바구니 명세서
└── go.sum <-- 장바구니 영수증 (보안 검증용)비개발자인 우리는 `internal` 폴더 안에 우리가 다룰 주제(도메인)별로 `user`, `post` 등 작은 폴더들을 만들고, 그 안에 관련 코드들을 옹기종기 모아두기만 하면 됩니다.
바이브코딩의 함정: 섣부른 오버엔지니어링
유튜브나 블로그를 보면 '클린 아키텍처(Clean Architecture)', 'DDD(Domain-Driven Design)', '헥사고날(Hexagonal)' 등 멋진 설계 방법론이 넘쳐납니다. AI에게 코드를 짜달라고 할 때 "클린 아키텍처로 짜줘!"라고 폼을 잡고 지시하는 순간, 지옥문이 열립니다.
기능 하나를 추가하기 위해 5~6개의 폴더를 이리저리 돌아다니며 파일을 수정해야 하고, 코드는 미로처럼 꼬여버립니다. 대규모 배달 앱 정도의 트래픽을 감당하는 팀 단위 개발에서는 훌륭한 방법이지만, 우리가 만드는 1인 바이브코딩 서비스에서는 오히려 독이 됩니다.
백엔드 설계 시 유의사항
권장
- 도메인 단위(예: user, post, comment)로 폴더를 직관적으로 나누고, 그 안에서 파일들을 관리하는 모듈식 모놀리스(Modular Monolith) 구조를 지향하세요.
- AI가 만들어준 코드가 너무 쪼개져 있다면, '너무 과도한 클린 아키텍처는 쓰지 말고 직관적인 3계층(Handler, Service, Repository) 구조로 합쳐줘'라고 명확히 지시하세요.
주의
- 하나의 main.go 파일 안에 모든 기능을 다 쑤셔 넣지 마세요. 코드가 500줄이 넘어가면 AI도 코드를 잃어버리고 헛소리를 하기 시작합니다.
- 초기부터 거창한 마이크로서비스(MSA)를 도입하여 서버를 여러 개로 쪼개는 짓을 절대 하지 마세요. 배포와 관리의 악몽이 시작됩니다.
개념 퀴즈
퀴즈 답을 맞춰야 학습 완료가 됩니다.여러분은 Go 언어로 쇼핑몰 백엔드를 바이브코딩하고 있습니다. 로그인, 장바구니, 주문 처리 등 우리 서비스의 '핵심 비즈니스 로직' 코드들을 외부 프로젝트에서 함부로 가져다 쓰지 못하게 안전하게 보호하면서 모아두는 가장 핵심적인 폴더의 이름은 무엇인가요?
3줄 요약
- 1Go 백엔드 프로젝트의 진입점인 cmd 폴더 안의 main.go 파일은 복잡한 로직 없이 서버를 세팅하고 켜는 스위치 역할만 담당합니다.
- 2실제 서비스의 핵심 비즈니스 로직과 도메인별 기능들은 외부 접근이 차단된 안전한 internal 폴더 안에 직관적으로 모아서 관리합니다.
- 3초기 개발부터 클린 아키텍처나 마이크로서비스 같은 거창한 폴더 쪼개기를 지시하면 개발 속도가 심각하게 느려지므로, 단순하고 실용적인 구조를 유지해야 합니다.