Kotlin ‐ API 안정성을 명시하라[Effective Kotlin Item 27] - thought-corner/Backend-PlayGround GitHub Wiki

API 안정성을 명시하라

  1. API가 변경되면 개발자들은 변경 사항에 따라 코드를 수동으로 업데이트 해야 한다.
  • 변경된 API를 프로젝트 내 다양한 곳에서 사용한다면 특히 문제가 될 수 있다. API가 사용된 코드를 수정하거나 대체하는 방법을 찾는 것이 어려울 수도 있다.
  • 공개 라이브러리에 포함된 API를 변경한다면 API를 사용한 프로젝트를 직접 수정할 수 없으며, 사용자들이 이를 변경해야 한다.
  • 이전 버전의 라이브러리가 더 이상 지원되지 않을 수도 있고 원하는 대로 동작하지 않을 수 있다. 프로그래머가 안정적인 새로운 버전의 라이브러리 사용을 기피하는 것은 매우 좋지 않은 상황이다.
  1. 사용자가 새로운 API를 배워야 한다.
  • 일반적으로 사용자들은 익숙한 것을 선호하며 새로운 걸 배우길 꺼린다.
  • 게다가 변경된 knowledge를 업데이트해야 한다.
  • 기존 방식을 새로운 방식으로 대체하는 것은 매우 어렵다.
  • 기존 방식을 고수하게 되면 보안 문제를 야기시킬 수 있으며, 라이브러리의 변경 사항을 따라가는 걸 더욱 어렵게 만드므로 전혀 바람직한 일이 아니다.

그럼 어떻게 하는지?

  • API 안정성을 명시하는 가장 간단한 방법은 문서에 API가 변경될 가능성이 높다는 점을 명시하는 것이다.
  • 공식적으로는 전체 라이브러리 또는 모듈 안정성을 버전으로 표현한다. 여러 버전 명명 체계가 있지만, 그 중에 거의 표준처럼 취급되는 버전 명명 체계가 있다.
  • 시맨틱 버저닝 시스템은 버전 번호를 세 부분, 즉 MAJOR, MINOR, PATCH로 구성한다. 각 부분은 0부터 시작하는 양의 정수이며, 공개 API에 중요한 변경이 있을 때 각각 1씩 증가시킨다.
    • MAJOR 버전 : 호환되지 않는 API 변경 사항
    • MINOR 버전 : 이전 버전과 호환되는 기능 추가
    • PATCH 버전 : 이전 버전과 호환되는 버그 수정

변경될 가능성이 높다면?

  • 새로운 API를 도입했지만 변경될 가능성이 높다면 먼저 이들을 다른 브랜치에 두어야 한다.
  • 몇몇 사용자들에게 새로운 API를 공개하고 싶다면 Experimental 메타 어노테이션을 사용해서 변경될 가능성이 높다고 경고할 수 있다.
  • Experimental API를 공개하고 사용할 순 있으나 경고 또는 오류가 표시된다.
  • Experimental API는 언제든지 변경될 수 있다고 생각해야 한다. API가 긴 시간 동안 Experimental로 유지되는 것을 걱정하지 말자. 안정적인 API가 될 때까지 오랜 시간이 걸리겠지만 더 나은 API를 만들기 위해 오랜 시간을 투자할 수 있다.
  • 안정적인 API를 변경할 떄는 사용자들이 변경 사항에 대응할 수 있도록 Deprecated 어노테이션으로 표시한다.