들어가며
100명 규모의 개발 조직에서 공용 라이브러리를 설계하고 배포한 경험이 있다. 혼자 쓰는 유틸리티 클래스를 만드는 것과, 조직 전체가 쓸 라이브러리를 만드는 것은 완전히 다른 종류의 작업이다.
이 글에서는 구체적인 사내 코드를 공개하지 않고, 대규모 조직에서 공용 라이브러리를 설계할 때 고려했던 원칙들을 정리한다.
원칙 1: 사용하는 쪽 코드가 가장 중요하다
라이브러리 내부 구현이 아무리 우아해도, 사용하는 쪽 코드가 복잡하면 실패한 설계다.
100명이 쓰는 라이브러리에서는, "라이브러리 내부 코드 1줄"을 줄이는 것보다 "사용하는 쪽 코드 1줄"을 줄이는 것이 100배 가치가 있다.
Kotlin 확장 함수의 활용
Kotlin을 쓰는 환경이라면 확장 함수가 강력한 도구다. 기존 클래스의 메서드 체이닝에 자연스럽게 끼어들 수 있기 때문이다.
예를 들어 페이징을 처리한다면, 별도 유틸리티 클래스를 호출하는 것보다 기존 쿼리 빌더에 .paginate(pageable) 형태로 체이닝하는 것이 사용 측에서 훨씬 자연스럽다.
원칙 2: 기본값이 있어야 한다
라이브러리를 도입할 때 설정해야 할 것이 많으면 도입 자체가 꺼려진다. "아무것도 설정하지 않아도 동작하는 기본 구현"을 제공해야 한다.
Spring Boot의 @ConditionalOnMissingBean 패턴이 이에 적합하다. 커스텀 구현체를 등록하지 않으면 기본 구현체가 자동으로 빈에 등록되고, 커스텀이 필요한 팀은 자신의 구현체를 등록하면 기본 구현체가 알아서 비활성화된다.
원칙 3: 확장은 열고, 핵심은 닫아라
조직 내 다양한 팀이 라이브러리를 사용하면, 각 팀의 요구사항이 조금씩 다르다. 이때 핵심 인터페이스를 잘 설계하면, 라이브러리를 수정하지 않고도 팀별 요구사항을 충족할 수 있다.
Kotlin의 sealed interface는 이 용도에 적합하다. 구현체의 종류를 컴파일 타임에 제한하면서도, 각 구현체의 내부 로직은 자유롭게 정의할 수 있다.
원칙 4: 문서가 코드를 대신한다
100명 규모 조직에서 라이브러리를 배포하면, 직접 설명할 수 있는 사람은 소수다. 나머지 90명 이상은 문서만 보고 사용해야 한다.
KDoc(Kotlin의 문서화 주석)을 상세하게 작성하는 것이 생각보다 큰 차이를 만든다.
좋은 KDoc의 조건:
•
파라미터의 제약 조건을 명시: "null인 경우 해당 정렬 조건은 무시됩니다"
•
사용 예시를 포함: @sample 태그 또는 코드 블록으로 실제 호출 방법 제시
•
반환값의 의미를 설명: "변환된 데이터와 페이징 메타데이터를 포함하는 객체"
원칙 5: 호환성을 미리 고려하라
대규모 조직에서는 프로젝트마다 사용하는 프레임워크 버전이 다를 수 있다. 예를 들어 Spring Boot 2.x와 3.x가 동시에 존재하는 환경이라면, 동일한 인터페이스를 두고 각 버전별 구현체를 별도 모듈로 분리해야 한다.
라이브러리를 처음 설계할 때 이 가능성을 고려하지 않으면, 나중에 모듈 분리 작업이 매우 고통스러워진다.
원칙 6: 사용성과 유지보수성은 양보 불가
사용하기 편하게 만드는 것(사용성)과, 내부 설계를 바꿀 때 기존 사용자에게 영향을 주지 않는 것(유지보수성)은 서로 충돌할 수 있다.
예를 들어, 확장 함수를 많이 제공하면 사용성은 좋아지지만, 확장 함수의 시그니처를 바꾸면 모든 사용처에 영향이 간다. 반대로 모든 것을 인터페이스 뒤로 숨기면 유지보수성은 좋아지지만 사용하기 번거로워진다.
이 둘 사이의 균형점을 찾는 것이 라이브러리 설계의 핵심이다. 내 경험상, 사용 측에 노출되는 API(확장 함수, public 메서드)는 최소화하되, 각 API의 사용 경험을 최대화하는 방향이 좋았다.
결론
대규모 조직에서 공용 라이브러리를 만드는 것은 "코드를 잘 짜는 것"이 아니라 "다른 사람이 잘 쓸 수 있게 만드는 것"이다.
나 자신을 위한 유틸리티를 만들 때와 가장 큰 차이는, 설명할 수 없는 사람들이 대부분이라는 점이다. 문서, 기본값, 확장 포인트 — 이 세 가지가 라이브러리의 채택률과 만족도를 결정한다.
