juicer — 기존 코드에서 SSOT를 짜낸다 Image: AI generated

“우리는 이미 200 엔드포인트가 있는데요”

yongol 글을 읽은 사람이 묻는다. “좋은 건 알겠는데, 우리 프로젝트에는 이미 코드가 수만 줄이에요. 처음부터 SSOT를 작성해야 하나요?”

처음부터 작성하면 좋겠지만, 현실에서는 불가능하다. 운영 중인 서비스를 멈추고 명세를 처음부터 쓸 수 있는 팀은 없다. 영업 중인 가게의 기초를 뜯을 수는 없다.

그래서 juicer를 만들었다. 기존 코드에서 SSOT를 짜낸다.

과일을 통째로 넣으면 주스가 나온다

juicer는 웹 프레임워크 소스 코드를 정적 분석하여 선언적 명세를 자동 추출한다.

juicer scan --openapi ./my-project

이 한 줄이면 기존 코드에서 OpenAPI 3.0 스펙이 나온다. 수작업으로 며칠 걸리던 것이 초 단위로 끝난다.

런타임 오버헤드 제로. 계측(instrumentation) 불필요. 순수 정적 분석이다. 학술적으로도 같은 방향이 검증되고 있다. Huang et al.(2024)은 ICSE에서 소스 코드 정적 분석만으로 REST API의 OpenAPI 명세를 자동 생성하는 기법(Respector)을 발표했다.

세 가지 프레임워크

프레임워크언어추출
GinGo라우트, 바인딩, 응답, 미들웨어
NestJSTypeScript데코레이터, DTO, 가드, 인터셉터
FastAPIPython라우트, Pydantic 모델, 의존성

Go, TypeScript, Python — 가장 많이 쓰이는 백엔드 프레임워크 세 개를 커버한다.

추출하는 것

레이어출력
라우트HTTP 메서드, 경로, 핸들러 위치, 미들웨어
요청바디 바인딩 타입 + 구조체 필드, 쿼리/폼/경로 파라미터, 파일 업로드
응답상태 코드, 바디 타입 + 구조체 필드, json/validate 태그
OpenAPIpaths, parameters, requestBody, responses, components/schemas
DDL마이그레이션 히스토리에서 테이블별 CREATE TABLE 스냅샷
SQL리포지토리 메서드 스켈레톤 — CRUD 타입, 테이블, 파라미터, 반환

소스 코드에 흩어져 있던 결정이 선언적 명세로 응축된다.

DDL 통합

마이그레이션 파일이 50개 쌓여 있으면, 현재 스키마가 어떤 상태인지 파악하기 어렵다. ALTER TABLE이 누적된 순서를 머릿속에서 재생해야 한다.

juicer ddl ./migrations -o ./schema

마이그레이션 히스토리를 전부 읽고, 테이블별로 깨끗한 CREATE TABLE 스냅샷 하나를 출력한다. 50개 파일이 테이블 수만큼의 .sql 파일로 정리된다.

sqlc 쿼리 스캐폴딩

리포지토리 패턴으로 작성된 코드에서 SQL 쿼리 스켈레톤을 추출한다.

juicer sql next --repo ./repository --queries ./db/query

next — 래칫 워크플로우다. 쿼리가 없는 다음 리포지토리 메서드를 보여주고, 스켈레톤을 작성하면 다음으로 넘어간다. 전부 채우면 멈춘다.

juicer sql status

현재 진행 상태를 보여준다. 에이전트가 “다 했습니다"라고 선언하는 것이 아니라, 기계가 남은 메서드 수를 판정한다.

yongol 파이프라인으로의 진입

juicer의 출력은 yongol의 입력이다.

기존 코드
  ↓ juicer scan --openapi
  ↓ juicer ddl
  ↓ juicer sql next
OpenAPI + DDL + sqlc 쿼리
  ↓ yongol validate
  ↓ yongol generate
SSOT 기반 코드베이스

juicer가 기존 코드에서 SSOT를 역추출하고, yongol이 그 SSOT의 정합성을 검증하고 코드를 생성한다. brownfield에서 greenfield로의 전환이 한 번에 일어나는 것이 아니라, 점진적으로 일어난다. Perry와 Wolf(1992)가 정의한 아키텍처 침식(erosion)과 드리프트(drift) — 명세를 위반하면 침식이고, 명세에 무감각해지면 드리프트다. juicer는 이미 드리프트가 발생한 코드에서 명세를 역추출하여 일치시키는 도구다.

처음에는 juicer가 추출한 OpenAPI와 DDL만 yongol에 넣는다. validate를 돌리면 레이어 간 불일치가 드러난다. 하나씩 고친다. SSaC를 추가한다. Rego를 추가한다. Hurl을 추가한다. 매 단계마다 yongol이 정합성을 보장한다.

기초 공사가 아니라 내진 보강이다. Martin Fowler(2004)가 명명한 Strangler Fig 패턴 — 레거시를 한 번에 교체하지 않고 점진적으로 감싸서 대체하는 것. 영업 중인 가게 문을 닫지 않고 건물을 보강한다.

시작

npx skills add park-jun-woo/juicer

juicer scan --openapi ./my-project

기존 코드가 주스가 된다.

코드: github.com/park-jun-woo/juicer

출처

  • Huang, R., Motwani, M., Martinez, I., & Orso, A. (2024). Generating REST API Specifications through Static Analysis. Proceedings of the IEEE/ACM 46th International Conference on Software Engineering (ICSE 2024). ACM
  • Lercher, A., Macho, C., Bauer, C., & Pinzger, M. (2024). Generating Accurate OpenAPI Descriptions from Java Source Code. arXiv:2410.23873. arXiv
  • Chauhan, S., Rasheed, Z., et al. (2026). OpenAI for OpenAPI: Automated generation of REST API specification via LLMs. Journal of Systems and Software. arXiv
  • Perry, D. E. & Wolf, A. L. (1992). Foundations for the Study of Software Architecture. ACM SIGSOFT Software Engineering Notes, 17(4), 40-52. ACM
  • De Silva, L. & Balasubramaniam, D. (2012). Controlling software architecture erosion: A survey. Journal of Systems and Software, 85(1), 132-151. ScienceDirect
  • Fowler, M. (2004). StranglerFigApplication. martinfowler.com/bliki. Link
  • Fritzsch, J., Bogner, J., Wagner, S., & Zimmermann, A. (2019). Microservices Migration in Industry: Intentions, Strategies, and Challenges. 2019 IEEE ICSME, pp. 481-490. arXiv
  • Curino, C. A., Moon, H. J., & Zaniolo, C. (2008). Graceful database schema evolution: the PRISM workbench. Proceedings of the VLDB Endowment, 1(1), 761-772. VLDB
  • Nghiem, D., Guo, H., & Foster, J. S. (2023). A Qualitative Study of REST API Design and Specification Practices. 2023 IEEE VL/HCC, pp. 148-156. IEEE

관련 글