TIL

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

프로그래밍에선 최대한 표준적인 API를 선호하는데 이유는 다음과 같다.
- API가 만약 변경된다면 여러 코드를 수동으로 업데이트 해야한다.
  - 만약 많은 요소가 의존하고 있었다면 큰 문제가 될 것이다.
- 사용자가 새로운 API를 배워야 하고 그렇지 않다면 오래된 지식 때문에 문제가 생길 수 있다.
좋은 API는 한 번에 설계할 수는 없다.
- API 제작자는 이를 계속 개선해야 한다.
API가 불안정하다면 이를 명확하게 명시해야 하는데 이에 시멘틱 버저닝을 사용한다.
- MAJOR 버전: 호환되지 않는 수준의 API 변경
- MINOR 버전: 이전 변경과 호환되는 기능을 추가
- PATCH 버전: 간단한 버그 수정
라이브러리나 모듈이 MAJOR 버전이 0일 때는(0, y, z) 안정적일 거라 생각하면 안 된다.
- 베타 버전이 오래 유지되는 것이 의아할 수도 있지만 코틀린도 1.0 버전에 도달하기 까지 5년이 걸렸다.
API가 아직 안정적이지 않지만 일부 사용자가 이를 사용하도록 허용하려면 Experimental 메타 어노테이션을 보통 사용한다.
- 사용할 순 있지만 경고 또는 오류가 출력된다.

@Experimental(level = Experimental.Level.WARNING)
annotation class ExperimentalNewApi

@Deprecated("Use suspending getUsers instead")
fun getUsers() {
	// ...
}

@Deprecated("Use suspending getUsers instead", ReplaceWith("getUsers()")
fun getUsers() {
	// ...
}