프로젝트 구조 파악하기
Chapter 7. 코드베이스 적응
'이 복잡한걸 언제 다 이해하지?
소스 코드를 클론받았다. 프로젝트 폴더가 생겼다. 이제 VSCode로 폴더를 열었다. 그리고 멍했다.
왼쪽 파일 트리에 폴더가 끝없이 펼쳐진다. ... 폴더 안에 또 폴더, 그 안에 또 폴더. 파일은 수백 개다.
'도대체 어디서부터 봐야 하지?'
코드를 열어봤다. 코드 라인 1500줄. 모르는 함수들이 가득하다.
import 문만 20개가 넘는다. utils 폴더를 열어봤다. 파일만 30개다. 게다가 다 비슷비슷하게 생겼다.
'이걸 언제 다 이해하지? 선배들은 이 복잡한 구조를 어떻게 다 아는 거지?'
원래 그런거다. 아무도 처음부터 전체 구조를 이해하지 못한다. 선배들도 처음엔 똑같았다. 여기서는 프로젝트 구조를 체계적으로 파악하는 방법을 정리했다.
폴더 구조 이해하기
프로젝트를 처음 열면 폴더가 정말 많다. 하지만 대부분의 프로젝트는 비슷한 구조를 따른다.
핵심 폴더 찾기
모든 폴더를 다 볼 필요 없다. 일단 이 다섯 개만 찾자.
1. 실제 소스 폴더 애플리케이션 코드가 들어있는 폴더. 가장 중요하다.
자바 기준으로 src 처럼 실제 애플리케이션으로 동작하는 코드 폴더를 먼저 보는게 중요하다.
2. 테스트 폴더 (또는 tests, tests) 테스트 코드가 들어있는 폴더.
테스트 코드를 읽으면 실제 코드가 어떻게 작동하는지 이해하는 데 큰 도움이 된다.
3. 환경 폴더 (configs) 설정 파일들이 모여 있는 폴더.
데이터베이스 연결 설정, 외부 API 키, 환경별 설정 등이 여기 있다.
4. 정적 파일 폴더 (static, assets) 정적 파일들. 이미지, CSS, 폰트 등.
프론트엔드 프로젝트에서 주로 보는 부분이고 서버에서 어떤 디자인 요소들을 가지고 잇는지 확인 할 수 있다.
5. 문서 (doc, documentation) 프로젝트 문서가 있는 폴더.
API 명세서, 아키텍처 다이어그램, 개발 가이드 등이 있으면 금상첨화다.
무시해도 되는 폴더
처음에는 이런 폴더들은 크게 신경 쓰지 않아도 된다. 시니어 개발자들도 크게 신경쓰지 않고 코딩한다.
1. 외부 라이브러리 폴더
외부 라이브러리들(node_modules / vendor )이 모여있는 폴더이다. 열어봤자 이해도 못한다. 파일이 수만 개인 경우도 있다.
2. 빌드된 빌드 폴더
빌드된 결과물(dist / build / out) 소스 코드가 아니라서 우리가 볼수 있는 코드의 형식이 아니므로 볼 필요도 볼수도 없다.
3. 버전 관리 폴더
버전 관리 폴더(.git) 는 개발자가 삭제할 경우는 있어도 안에 내용을 직접 수정할 일은 거의 없다.
신입 개발자 시절 프로젝트를 클론받고 열었는데 폴더가 한 30개는 넘었던거 같다. '다 봐야 하나?' 라며 의문을 품고 위에서부터 하나씩 열어봤다.
첫 번째 폴더. 설정 파일들. 뭔 소린지 모르겠다.
두 번째 폴더. 알 수 없는 파일들 가득.
세 번째 폴더. 클릭. 파일이 로드 되다 멈췄다. 로딩 중. 5분 경과. 파일이 수만 개. 강제 종료.
네 번째 폴더. 압축된 코드. 읽을 수 없는 암호 같은 텍스트.
다섯 번째 폴더. 또 이상한 파일들.
옆자리 선배가 웃으며 물었다. "뭐 하고 있어요?"
"코드 보려고요. 근데 폴더가 너무 많아서..."
선배는 내 화면을 보더니 말했다.
"우선 src 폴더만 보면 돼요. 나머지는 나중에 필요할 때 보면 되고요."
그렇게 필요한 폴더 먼저 보게되니 프로젝트 구조가 갑자기 단순해 보였던 기억이 난다. 소스가 모여있는 폴더를 위주로 점점 넓혀가자.
실전 팁
프로젝트를 처음 열면 폴더 트리를 나무 가지 바라보듯 구경해보자. 그리고 I중요한 폴더는 눈으로 익혀두자 나중에 다시 폴더를 볼 때 친근해질 것이다.
주요 설정 파일 위치
코드를 실행하려면 설정이 필요하다. 어떤 DB에 연결할지, 어떤 포트를 쓸지, API 키는 뭔지 이런 정보들이 설정 파일에 들어있다.
환경 변수 파일
.env 가장 흔한 설정 파일. DB 주소, API 키, 포트 번호 같은 것들이 여기 있다. 문제는 .env 파일이 보통 Git에 올라가지 않는다는 것. 비밀번호 같은 민감한 정보가 들어있기 때문이다. 그래서 처음 클론받으면 .env 파일이 없다. 대신 .env.example 파일이 있다. 빈 칸으로 되어 있는 템플릿이다. 그렇다면 어디서 값을 구하는지 알아보자
방법:
사내 위키 문서 확인
팀 Slack 채널의 고정 메시지
동료에게 직접 물어보기
비밀번호 관리 도구 (1Password, Vault 등)
실전 팁
.env 파일 값들은 따로 메모장에 정리해두자. 컴퓨터 바꾸거나 프로젝트 다시 세팅할 때 편하다.
언어별 설정 파일
Node.js : package.json
프로젝트 이름, 버전, 실행 명령어, 필요한 라이브러리 목록이 들어있다.
여기서 가장 중요한 건 scripts 부분. npm start, npm test 같은 명령어가 실제로 뭘 실행하는지 여기 정의되어 있다.
"어떻게 실행하지?" 싶을 때 제일 먼저 보는 파일이다.
Python : requirements.txt
필요한 라이브러리 목록. 버전까지 명시되어 있다.
보통 pip install -r requirements.txt 명령어로 한 번에 설치한다. 버전이 명시된 이유는 나중에 라이브러리 버전 차이로 생기는 문제를 방지하기 위해서다.
예전 버전으로 개발된 프로젝트를 최신 라이브러리로 실행하면 작동 안 하는 경우가 많다.
Java : pom.xml 또는 build.gradle
Maven이나 Gradle 설정 파일. 프로젝트 의존성과 빌드 방법이 들어있다.
처음 보면 XML 태그 천지라 복잡해 보이지만, 천천히 읽어보면 어떤 라이브러리 쓰는지 다 보인다. Spring Boot 프로젝트라면 여기서 버전 관리한다.
프레임워크 설정 파일
Spring Boot : application.yml 또는 application.properties 파일에서 DB 연결, 서버 포트, 로그 레벨 등 애플리케이션 전체 설정등을 확인 할 수 있따.
일반 설정 : 보통의 프레임워크들은 config.json 또는 config.js 프레임워크 없이도 쓰는 범용 설정 파일이므로 이렇게 config 라는 이름의 파일을 확인해보자.
기타 설정 파일
nginx.conf : 웹서버 설정
어떤 포트로 들어오는 요청을 어디로 보낼지 정의. 예를 들어 사용자가 example.com/api로 요청을 보내면, 내부적으로 3000번 포트로 돌리는 식. 일종의 교통 경찰 역할을 한다.
Dockerfile : Docker 컨테이너 설정
이미지를 어떻게 만들지 정의된 파일이다. "Ubuntu 깔고, Node.js 설치하고, 패키지 설치하고, 앱 실행" 이런 과정을 코드로 적어둔 것으로 이 파일 하나면 누구 컴퓨터에서든 똑같은 환경을 만들 수 있다. "내 컴퓨터에서는 되는데요?" 문제를 해결하는 마법 파일이다.
docker-compose.yml : 여러 컨테이너 한번에 실행
DB, 웹서버, 애플리케이션을 한 번에 띄우는 설정 보통 개발할 때 "DB 켜고, Redis 켜고, 앱 켜고..." 필요한 프로그램을 실행하는걸 일일이 하기 귀찮다. 그래서 docker-compose up 명령어 하나로 다 켜질 수 있도록 만든 파일이다.
이런 파일들은 처음엔 몰라도 된다. 읽을 줄만 알면 충분하다. 수정할 일은 나중에 생긴다. 입사 초기에는 기능 개발에 집중하면 된다. nginx, Docker 설정은 보통 이미 세팅되어 있고, 건드릴 일이 거의 없다.
구조 파악 실전 전략
처음 프로젝트 받으면 이 순서로 한번 실습해보자.
1일차: 훑어보기 (30분)
폴더 구조 파악
README 읽기
엔트리 포인트 찾기
README는 정말 중요하다. 어떻게 실행하는지, 어떤 환경 변수가 필요한지, 주의사항은 뭔지 다 나와 있다. README가 없거나 오래됐다면? 동료에게 물어보는 수밖에 없다.
하지 말 것: 코드 한 줄씩 읽지 말기. 모든 폴더 다 열지 말기.
처음엔 욕심내서 모든 코드를 이해하려고 한다. 하지만 그러면 하루 종일 해도 끝이 안 난다. 일단 큰 그림만 보자.
2일차: 설정 세팅 (1시간)
.env 만들기
환경 변수 채우기
실행해보기
에러 해결
실행하다 보면 에러가 난다. 당연하다. 처음부터 바로 실행되는 경우는 거의 없다. 에러 메시지를 잘 읽고, 모르면 구글 검색하거나 동료에게 물어보자.
보통 이런 에러들이 많다:
환경 변수 빠짐
포트 번호 충돌
데이터베이스 연결 실패
라이브러리 버전 충돌
3일차: 한 가지 기능 따라가기 (2시간)
간단한 API 하나 선택
엔트리 포인트부터 끝까지 따라가기
각 파일 역할 이해
로그인 API나 사용자 조회 API 같은 간단한 것부터 시작하자. 복잡한 결제나 정산 로직은 나중에 보면 된다.
디버거 쓰거나 console.log 찍으며 확인. 실제로 실행하면서 보는 게 제일 빠르다.
4일차: 테스트 코드 읽기 (1시간)
간단한 테스트 찾기
기대 동작 이해하기
실행해보기
테스트 코드는 살아있는 문서다. 어떤 입력을 넣으면 어떤 출력이 나와야 하는지 명확하게 나와 있다. 복잡한 주석보다 테스트 코드 한 줄이 더 명확할 때가 많다.
5일차: 문서 읽기 (1시간)
사내 위키 찾기
아키텍처 다이어그램 보기
API 명세서 읽기
문서가 잘 정리되어 있으면 정말 행복하다. 하지만 현실은 문서가 없거나, 있어도 오래돼서 실제 코드와 다른 경우가 많다. 그래도 참고는 된다.
체크리스트: 프로젝트 구조 파악 완료
폴더 구조
src 폴더 위치
test 폴더 위치
config 폴더 위치
주요 하위 폴더들
설정 파일
.env 파일 만들기
환경 변수 채우기
개발 환경 실행 성공
주요 설정 파일 위치
폴더 이름은 그와 관련된 네이밍을 갖는다. 그러므로 이름만 보고 추측하는 능력을 길러보자. controllers 는 API 요청 처리, models 는 DB 데이터 구조, services 는 비즈니스 로직, utils 는 공통 함수 폴더 이름만 봐도 대충 뭐 하는 곳인지 눈치껏 알 수 있다. 정확히 몰라도 괜찮다. 일단 추측하고 열어보는 것만으로도 상당한 도움이 될 것이다.
코드는 탐험
처음 프로젝트 코드를 열면 압도당한다. 파일이 너무 많고, 코드가 너무 복잡하고, 모르는 게 너무 많다.
괜찮다. 아무도 처음부터 모든 걸 이해하지 못한다. 시니어 개발자도 새 프로젝트에 들어가면 한두 주는 코드 읽는 데 보낸다.
코드는 책처럼 처음부터 끝까지 읽는 게 아니다. 지도처럼 필요한 곳을 찾아가는 거다.
오늘은 로그인 흐름을 따라갔다면, 내일은 결제 흐름을 따라가보자. 모레는 에러 처리를 보고, 그다음엔 테스트 코드를 읽어보자.
하나씩, 천천히 한 달 후면 어느새 익숙해져 있을 것이다. "아, 이 기능은 여기 있지" 하면서 바로 찾아갈 수 있게 된다.