[Effective Kotlin] 28 - API 안정성을 확인하라

아래의 이유들 때문에 프로그래밍에서는 안정적이고 최대한 표준적인 API를 선호합니다.

1. API가 변경되고, 개발자가 이를 업데이트했다면, 여러 코드를 수동으로 업데이트 해야합니다.
   1. 많은 요소가 이 API에 의존하고 있다면 변경에 대응하거나 다른 대안을 찾기 어렵기 때문에 이는 큰 문제가 됩니다.
   2. 하지만 이 때문에 라이브러리가 변경되어도 이전 라이브러리를 유지하는 경우가 많은데, 이럴 경우 업데이트가 어려워지고, 버그와 취약성등이 발생할 수 있습니다.
2. 사용자가 새로운 API를 배워야 합니다.

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

 

간단한 방법은 작성자가 API 또는 API 일부가 불안정하다면 이를 명확하게 알려 줘야 합니다. 일반적으로 버전을 활용해서 라이브러리와 모듈의 안정성을 나타냅니다.

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

Experimental 메타 어노테이션을 사용해서 사용자들에게 아직 해당 요소가 안정적이지 않다는 것을 알려주는 것이 좋습니다. (Experimental 메타 어노테이션을 붙이면, 요소를 보고 사용할 수 있지만, 사용할 때 경고 또는 오류(설정된 레벨에 따라 다름)가 출력됩니다.)

이러한 요소는 언제든지 변경될 수 있습니다. 따라서 요소를 오랜 시간 동안 실험적 기능으로 유지하는 것을 두려워하지 말기 바랍니다. (Kotlin은 1.0에 도달하기 까지 5년 이상 소요되었습니다.)

 

안정적인 API의 일부를 변경해야 한다면, 전환하는 데  시간을 두고 Deprecated  어노테이션을 활용해서 사용자들에게 미리 알려줘야 합니다.

(직접적인 대안이 있다면, ReplaceWith를 붙여 주는 것도 좋습니다.)

@Deprecated("Use Suspending getUsers instead",
ReplaceWith("getUsers()"))
fun getUsers(callback: (List<User>)-> Unit) {
	// ...
}

 

정리

사용자는 API의 안정성에 대해 알아야 합니다. 안정적인 API를 사용하는 것이 좋습니다. 다만 안정적이라고 생각했던 API에 예상하지 못한 변경이 일어났다면, 나쁜 상황입니다. 이러한 변경은 수많은 사람들에게 고통을 줄 수 있습니다. 따라서 모듈과 라이브러리를 만드는 사람들과 이를 사용하는 사람들 사이에 커뮤니케이션이 중요합니다. 커뮤니케이션은 버전 이름, 문서, 어노테이션 등을 통해 할 수 있습니다. 또한 안정적인 API에 변경을 가할 때는 사용자가 적응할 충분한 시간을 줘야 합니다.