Cursor와 함께 알아본 프로젝트 구조

들어가며

프로젝트 구조는 코드의 가독성, 유지보수성, 확장성에 직접적인 영향을 미치는 중요한 요소다. 평소 코드를 작성하던대로 작성하다가 문득 프로젝트 구조를 이대로 가져가는게 옳은지 고민하게됐고, Cursor에게 보편적인 프로젝트 구조를 물어보게됐다. 그런고로 이번 글에서는 리팩토링 과정과 함께 몇몇 프로젝트 구조에 대해 Cursor에게 물어본 내용을 정리해보고자 한다.

초기 구조

처음에는 생각없이 기능을 구현하다보니, 다음과 같이 모든 관련 코드가 하나의 파일(jobQueue.ts)에 있었다.

// 초기 jobQueue.ts
export const JOB_STATUS = {
  QUEUED: 'queued',
  DOWNLOADING: 'downloading',
  // ... 기타 상태들
} as const;

export type JobStatus = typeof JOB_STATUS[keyof typeof JOB_STATUS];

export interface Job {
  id: string;
  status: JobStatus;
  // ... 기타 속성들
}

class JobQueue {
  // ... 큐 관련 로직
}

계속해서 코드를 작성해나가다보니 라인수가 길어져 가독성이 떨어지는 것은 물론, 다음과 같은 문제점을 지니고 있었다.

1. 단일 책임 원칙 위반: 하나의 파일이 너무 많은 책임을 가짐
2. 코드 재사용의 어려움: 타입과 인터페이스가 큐 로직과 결합됨
3. 테스트의 어려움: 관심사가 분리되지 않아 단위 테스트가 복잡해짐

일반적인 프로젝트 구조를 살펴보자!

1. 도메인 중심 구조 (Domain-Driven Structure)

도메인 중심 구조는 Domain-Driven Design(DDD)의 영향을 받은 구조다. 이 접근 방식은 비즈니스 도메인을 중심으로 코드를 구성한다.

lib/
├── models/                # 도메인 모델
│   ├── job.ts            # Job 도메인 모델
│   └── jobStatus.ts      # 상태 정의
├── modules/              # 도메인 로직
│   └── queue/           
│       └── jobQueue.ts   # 큐 관련 비즈니스 로직
└── types/                # 공통 타입 정의

장점:

• 비즈니스 도메인이 코드 구조에 직접 반영됨
• 도메인 전문가와의 소통이 용이
• 확장성이 좋음

단점:

• 작은 프로젝트에서는 과도한 구조가 될 수 있음
• 도메인 경계 설정이 어려울 수 있음

2. 기능 중심 구조 (Feature-Driven Structure)

이 구조는 Feature-Sliced Design에서 영감을 받았다. 각 기능을 독립적인 단위로 취급한다.

lib/
├── features/             # 기능별 모듈
│   └── jobProcessing/    # 작업 처리 기능
│       ├── models/       # 기능별 모델
│       │   ├── job.ts
│       │   └── jobStatus.ts
│       └── queue.ts      # 기능 로직
└── shared/               # 공통 코드

장점:

• 기능 단위의 코드 응집도가 높음
• 새로운 기능 추가가 용이
• 팀 단위 작업이 용이

단점:

• 기능 간 중복이 발생할 수 있음
• 공통 코드 관리가 어려울 수 있음

3. 계층형 구조 (Layered Architecture)

전통적인 계층형 아키텍처를 따르는 구조다.

lib/
├── core/                 # 핵심 비즈니스 로직
│   ├── models/
│   └── services/
├── infrastructure/       # 외부 시스템 연동
└── presentation/        # UI 관련

장점:

• 책임이 명확히 분리됨
• 테스트가 용이
• 기술 스택 변경이 용이

단점:

• 과도한 추상화가 발생할 수 있음
• 작은 변경에도 여러 계층을 수정해야 할 수 있음

프로젝트 구조 선택 가이드

프로젝트 구조를 선택할 때 고려해야 할 사항들:

1. 프로젝트 규모
   • 작은 규모: 단순한 구조 선호
   • 큰 규모: 도메인/기능 중심 구조 고려
2. 팀 구성
   • 소규모 팀: 단순하고 직관적인 구조
   • 대규모 팀: 명확한 경계와 책임 분리가 있는 구조
3. 비즈니스 도메인 복잡도
   • 단순한 도메인: 기능 중심 구조
   • 복잡한 도메인: 도메인 중심 구조
4. 확장 계획
   • 단기 프로젝트: 단순한 구조
   • 장기 프로젝트: 확장성을 고려한 구조

결론

프로젝트 구조는 한 번 결정되면 변경하기 어려우므로, 초기에 신중한 선택이 필요하다. 실제로 프로젝트 구조를 결정하는 데에는 더 많은 방법론이 있겠지만, 지금처럼 혼자서 진행하는 경우에는 사이드 프로젝트를 진행할 때는 도메인 중심 구조와 기능 중심 구조를 적절하게 혼합해서 사용하는게 좋을 듯 하다는 결론을 내렸다.

참고 자료

• Domain-Driven Design - Martin Fowler
• Feature-Sliced Design
• Clean Architecture - Robert C. Martin
• Layered Architecture - O'Reilly
• TypeScript Project Structure - TypeScript 공식 문서
• React Project Structure - React 공식 문서