오픈소스 생태계에 기여하다

사내에서 Python API를 Rust로 마이그레이션하는 작업을 진행하고 있습니다.

이 과정에서 저희 팀은 자체 솔루션인 vespertide를 활용해 DB 모델을 생성하고 있습니다. vespertide는 DB 모델을 JSON으로 정의해두면, 이를 읽어 Rust route에서 사용할 수 있는 struct를 생성해주는 라이브러리입니다.

기존에는 models 폴더 아래에서 별도의 디렉터리 구조 없이 모든 모델을 한 곳에서 관리했습니다. 하지만 모델 수가 40개, 50개 이상으로 늘어나면서 문제가 분명해졌습니다. 파일명에 prefix를 강하게 두지 않으면 전체 맥락을 파악하기 어려웠고, 어떤 도메인에 속한 모델인지도 한눈에 들어오지 않았습니다.

특히 이번 마이그레이션 작업은 이미 파일 구조를 나눠서 진행하고 있었기 때문에, vespertide도 하위 폴더 구조를 자연스럽게 지원해야 할 필요가 있었습니다.

기존 문제

문제는 vespertide export를 실행했을 때, 관계형 참조 경로가 폴더 구조를 고려하지 못한다는 점이었습니다.

예를 들어 모델 구조가 아래와 같다고 가정해보겠습니다.

models
ㄴ/admin
| ㄴ admin.json
ㄴ/est
  ㄴ est.json

이때 est.json의 username 컬럼이 admin 테이블의 username을 참조하고 있다고 해보겠습니다. 이 상태에서 vespertide export를 실행하면 결과는 아래처럼 생성됩니다.

models
ㄴ/admin
| ㄴ admin.rs
ㄴ/est
  ㄴ est.rs

겉으로 보면 정상적으로 변환된 것처럼 보이지만, 실제로는 est.rs 내부의 참조 경로에 문제가 있었습니다.

super::admin::Entity

이 경로는 현재 파일 구조에서는 올바르지 않습니다. est.rs에서 super::는 est 모듈을 기준으로 해석되는데, 그 안에는 admin이 존재하지 않기 때문입니다. 결국 Rust 컴파일 에러가 발생하게 됩니다.

정상적으로 동작하려면 참조 경로는 아래 두 가지 형태 중 하나여야 했습니다.

1. super::super::admin::admin::Entity
2. crate::models::admin::admin::Entity

그래서 왜 항상 super::로만 경로가 생성되는지 확인하기 위해 vespertide 내부 코드를 직접 분석했습니다.

원인 분석

코드를 따라가 보니, .rs 모델을 생성하는 과정에서 참조 경로를 super::로 하드코딩하고 있다는 점을 확인할 수 있었습니다.

이 문제는 단순히 경로 하나를 고치는 수준이 아니었습니다. 모델을 도메인별 디렉터리로 나누어 관리하는 순간 바로 드러나는 구조적 문제였고, 더 큰 프로젝트나 복잡한 폴더 구조에서 vespertide를 안정적으로 사용하려면 반드시 해결해야 하는 이슈라고 판단했습니다.

문제를 추적하면서 중점적으로 본 흐름은 아래 세 단계였습니다.

1. 파일 탐색: walk_models
2. 상대 경로 추출: strip_prefix
3. 최종 출력 경로 생성: build_output_path

특히 상대 경로를 추출하는 과정에서는 DFS 방식으로 디렉터리를 재귀 탐색하며 구조를 따라가도록 로직을 정리했습니다. 또한, 가독성 측면에서 super를 반복해서 쓰기 보다는 절대경로를 사용하는 것이 가독성이 좋다 판단을 하였고, 2번으로 작업을 진행했습니다.

실제 변경 내용은 아래 PR에서 확인할 수 있습니다.

https://github.com/dev-five-git/vespertide/pull/128/changes#diff-38a5201db5a35f078cddf187a4ce3c9b85b04e7452137fee6537cfe7f12ee4b8

이번 기여를 통해 배운 점

이번 경험을 통해 두 가지를 크게 배웠습니다.

첫째, 오픈소스 기여는 거창한 것에서 시작되지 않는다는 점입니다. 결국은 "내가 실제로 쓰면서 불편한 점을 해결하고 싶다"는 문제의식과, "왜 이렇게 동작하지?"라고 스스로 질문하는 태도에서 출발한다는 것을 느꼈습니다.

둘째, AI가 많이 도와주는 시대가 되었더라도 결국 문제를 발견하는 것은 사용자라는 점입니다. 실제로 사용해보지 않으면 어떤 부분이 불편한지, 어떤 구조에서 한계가 드러나는지 알기 어렵습니다.

앞으로도 단순히 일관된 케이스만 보는 데 그치지 않고, 직접 사용하면서 불편한 지점을 찾고 더 나은 생태계를 만드는 데 기여하고 싶습니다.

긴 글 읽어주셔서 감사합니다.