[이펙티브 코틀린] 아이템 28. API 안정성을 확인하라

프로그래밍에서도 안정적이고 최대한 표준적인 API를 선호한다. 주요 이유는 아래와 같다.

 

1. API가 바뀌고 개발자가 이를 업데이트했다면 여러 코드를 수동으로 업데이트해야 한다. 많은 요소가 이 API에 의존하고 있다면 큰 문제가 된다. 변경에 대응하거나 다른 대안을 찾는 건 어렵다. 특히 다른 개발자가 API를 사용한 경우에는 익숙하지도 않아 더 어려울 것이다. 라이브러리의 작은 변경은 이를 활용하는 다른 코드들의 많은 부분을 변경하게 만들 수 있다. 그래서 라이브러리가 바뀌어도 이전 라이브러리를 유지하는 경우가 많다. 하지만 그럴수록 점점 업데이트가 어려워지고 버그, 취약성 등이 발생할 수 있다. 오래된 라이브러리는 더 이상 지원되지 않을 수도 있다. 따라서 개발자가 안정적인 라이브러리로 업데이트하는 걸 두려워한다는 건 매우 안 좋은 상황이다
2. 사용자가 새 API를 배워야 한다. 새로 배운다는 것은 힘들고 고통스러운 일이므로 많은 사람이 이를 피한다. 하지만 새로 배우지 않으면 오래된 지식 때문에 보안 문제가 발생할 수 있다. 따라서 처음부터 안정적이지 않은 모듈을 많이 공부하는 것보다는 안정적인 모듈부터 공부해두는 게 좋다.

 

좋은 API를 한 번에 설계할 수는 없다. API 제작자는 이를 계속 개선하기 위해 변경을 원한다. 따라서 프로그래밍 커뮤니티는 계속 API를 안정적으로 유지하기 위한 의견을 제시해 균형을 맞춰야 한다.

간단한 방법은 작성자가 API 또는 API 일부가 불안정하다면 이를 명확하게 알려 줘야 한다. 많은 버저닝 시스템이 있지만 일반적으로 시멘틱 버저닝을 사용한다. 이 시스템은 버전 번호를 3개 번호, 즉 MAJOR, MINOR, PATCH로 나눠 구성한다. 각 부분은 0 이상의 정수로 구성되며 0부터 시작해서 API에 아래와 같은 변경사항이 있을 때 1씩 증가시킨다

 

• MAJOR 버전 : 호환되지 않는 수준의 API 변경
• MINOR 버전 : 이전 변경과 호환되는 기능 추가
• PATCH 버전 : 간단한 버그 수정

 

버전은 MAJOR.MINOR.PATCH 형태로 붙인다. MAJOR를 증가시킬 때는 MINOR, PATCH를 0으로 돌려 둔다. 사전 배포와 빌드 메타데이터 등은 추가적인 레이블을 활용한다. 메이저 버전이 0인 경우(0.y.z)는 초기 개발 전용 버전을 의미한다. 따라서 언제든 바뀔 수 있고 안정적이지 않다는 의미다. 따라서 라이브러리, 모듈이 시멘틱 버저닝에 따라 버전이 붙는다면 MAJOR 버전이 0일 때는 안정적인 거라고 생각하면 안 된다.

안정적인 API에 새 요소를 추가할 때 아직 해당 요소가 안정적이지 않다면 먼저 다른 브랜치에 해당 요소를 두는 게 좋다. 일부 사용자가 이를 사용하도록 허용하려면 일단 Experimental 메타 어노테이션을 써서 사용자들에게 아직 해당 요소가 안정적이지 않다는 것을 알려주는 게 좋다.