아이템 28. API 안전성을 확인하라

API 안전성을 확인하라 #

API 또는 API의 일부가 불안정하다면, 작성자/개발자가 이를 명확하게 알려줘야 한다.

일반적으로 버전을 활용해서 라이브러리, 모듈의 안전성을 나타낸다.

많은 버저닝 시스템이 있지만 일반적으로 사용되는 것은 **시멘틱 버저닝(Semantic Versioning, SemVer)**이다.

시멘틱 버저닝의 표기법은 {MAJOR}.{MINOR}.{PATCH} 이다.
각각의 부분은 0 이상의 정수로 구성되고, 변경 마다 1씩 증가시킨다.

구분	설명	비고
MAJOR	호환되지 않는 수준의 API 변경	MAJOR 증가 시, MINOR, PATCH 는 0으로 초기화한다.
MINOR	이전 변경과 호환되는 기능 추가	MINOR 증가 시, PATCH 는 0으로 초기화한다.
PATCH	간단한 버그 수정

사전 배포, 빌드 메타데이터 등은 추가적인 레이블을 활용할 수 있다. (← SNAPSHOT, EXPERIMENTAL 과 같은 것을 의미하는 것 같다.)

MAJOR 버전이 0인 경우(0.y.z)는 초기 개발 전용 버전을 의미한다. 언제든지 변경될 수 있으며, 안정적이지 않음을 의미한다.

오랜 시간 동안 MAJOR가 0이거나 실험적 기능(@Experimental)으로 유지하는 것을 두려워해서는 안된다. 속도는 느릴 수 있지만 더 좋은 API를 설계하기 위해서라면 충분히 유지하는 것이 좋다.

안정적인 API의 일부를 변경해야 한다면, @Deprecated 어노테이션을 활용할 수 있다.

@Deprecated("~~~", ReplaceWith="~~~")
fun OOO() {}

단, Deprecated 로 마킹했더라도 사용자가 이 변경에 적응할 시간이 필요하다.

완벽하게 제거하기 위해서는 꽤 오랜 시간이 걸린다. (몇 년이 걸릴 수 있다.)

충분한 시간이 지난 뒤 Major 배포 업그레이드와 함께 Deprecated 기능을 제거한다.

구분	설명	비고
MAJOR	호환되지 않는 수준의 API 변경	MAJOR 증가 시, MINOR, PATCH 는 0으로 초기화한다.
MINOR	이전 변경과 호환되는 기능 추가	MINOR 증가 시, PATCH 는 0으로 초기화한다.
PATCH	간단한 버그 수정

Deprecated 기능을 제거하는 것 = Major 버전업이 필요한 것으로? :thinking: