Rust 프로젝트 구조화 및 모범 사례 정리

Rust 프로젝트 구조 이해하기: 기본부터 모범 사례까지

Rust는 강력한 모듈 시스템과 패키지 관리 도구인 Cargo를 기반으로 한 생태계를 갖추고 있습니다. 효율적이고 유지보수하기 쉬운 프로젝트 구조 설계는 Rust 개발에서 매우 중요합니다.

이번 글에서는 Rust 프로젝트 구조 기본과 함께, 실무에서 널리 쓰이는 모범 사례를 정리해보겠습니다.

1. Cargo 기반 기본 프로젝트 구조

Rust 프로젝트는 기본적으로 cargo new 또는 cargo init 명령어로 생성할 수 있으며, 생성된 디렉터리 구조는 다음과 같습니다:

my_project/
├── Cargo.toml
├── Cargo.lock
└── src/
    └── main.rs

- Cargo.toml: 프로젝트 메타데이터 및 의존성 관리 파일 - Cargo.lock: 의존성 버전 고정 파일 (주로 배포 시 사용) - src/main.rs: 실행 가능한 바이너리 프로젝트의 진입점 파일

2. 라이브러리와 바이너리 분리하기

대부분의 Rust 프로젝트는 실행 파일과 라이브러리를 동시에 가집니다. 이 경우 구조는 다음과 같이 확장할 수 있습니다:

my_project/
├── Cargo.toml
├── src/
│   ├── main.rs       # 바이너리 진입점
│   └── lib.rs        # 라이브러리 코드

- main.rs는 사용자 인터페이스나 실행 로직 중심 - lib.rs에는 핵심 비즈니스 로직 및 재사용 가능한 함수, 모듈 작성

3. 모듈과 서브모듈 관리

Rust의 mod 키워드를 활용해 모듈을 정의하며, 복잡한 코드는 여러 파일과 폴더로 분리합니다. 예를 들어:

src/
├── lib.rs
├── utils.rs
└── handlers/
    ├── mod.rs
    ├── user.rs
    └── auth.rs

`lib.rs` 내부에는 다음과 같이 모듈을 선언합니다:

// lib.rs
pub mod utils;
pub mod handlers;

`handlers/mod.rs`는 서브모듈들을 한 곳에서 관리합니다:

// handlers/mod.rs
pub mod user;
pub mod auth;

4. 외부 크레이트와 의존성 관리

Cargo.toml에 의존성을 명확히 적고, cargo update, cargo audit 등의 도구로 주기적인 점검을 권장합니다. 또한, 불필요한 의존성을 최소화해 빌드 속도와 보안성을 확보하세요.

5. 테스트 코드 분리 및 작성

Rust는 tests/ 폴더를 통해 통합 테스트를 관리합니다. 단위 테스트는 각 모듈 내 #[cfg(test)] mod tests 영역에 작성하는 것이 관례입니다.

my_project/
├── src/
│   └── lib.rs
└── tests/
    └── integration_test.rs

6. 문서화와 코드 스타일 유지

- 함수, 모듈에는 ///를 활용해 문서 주석 작성 - cargo fmt로 일관된 코드 스타일 유지 - cargo clippy로 코드 품질과 잠재적 버그 점검

7. 환경별 설정과 비밀 정보 관리

환경 변수와 비밀키는 .env 파일이나 OS 환경변수를 활용해 관리하며, dotenv 크레이트 사용을 추천합니다. 절대 .env 파일을 버전관리 시스템에 올리지 마세요.

8. 프로젝트 규모에 따른 구조 확장

대규모 프로젝트에서는 다음과 같이 여러 개의 바이너리와 라이브러리를 혼합해 관리할 수 있습니다:

my_project/
├── Cargo.toml
├── src/
│   ├── main.rs
│   └── lib.rs
├── benches/
├── examples/
├── tests/
└── tools/
    └── cli_tool.rs

- benches/: 벤치마크 테스트 - examples/: 사용 예제 코드 - tools/: 보조 도구 또는 CLI 툴 코드

결론: Rust 프로젝트 구조화는 명확한 모듈 분리와 Cargo 활용이 핵심

Rust 프로젝트를 잘 구조화하면 코드 재사용성 증가, 유지보수 용이성, 협업 효율성을 크게 높일 수 있습니다. 이번 글에서 소개한 기본 구조와 모범 사례를 참고해 여러분의 Rust 프로젝트에 맞는 최적의 설계를 해보세요.

더 나아가, cargo workspaces를 활용한 멀티 패키지 관리, CI/CD 통합, 자동 문서화 도구 활용 등도 고민해보면 좋습니다.