라이브러리 작성자를 위한 하위 호환성 가이드

라이브러리 작성자를 위한 하위 호환성 가이드

라이브러리를 만드는 가장 흔한 이유는, 더 넓은 커뮤니티에 기능을 공개하기 위해서예요. 그 커뮤니티는 한 팀일 수도, 한 회사일 수도, 특정 업계나 기술 플랫폼일 수도 있죠. 어느 경우든 하위 호환성(backward compatibility)은 중요한 고려 사항이 돼요. 커뮤니티가 넓어질수록 하위 호환성은 더 중요해지는데, 그만큼 사용자가 누구이고 어떤 제약 속에서 일하는지 덜 알게 되기 때문이에요.

하위 호환성은 한 단어로 설명되기보다, 바이너리(binary), 소스(source), 동작(behavioral) 수준에서 각각 정의돼요. 이번 섹션에서 이 유형들에 대해 자세히 알아볼게요.

참고할 점이 두 가지 있어요:

• 바이너리 호환성을 깨지 않고 소스 호환성만 깨는 것도, 그 반대도 가능해요.
• 소스 호환성을 보장하는 일은 바람직하지만 매우 어려워요. 라이브러리 작성자는 사용자가 함수나 타입을 호출하거나 인스턴스화할 수 있는 모든 경우를 고려해야 해요. 그래서 소스 호환성은 보통 '약속'이라기보다 '지향점'으로 보는 편이에요.

이어지는 내용에서는, 각 종류의 호환성을 지키기 위해 취할 수 있는 조치와 쓸 수 있는 도구를 설명할게요.

출처: Backward compatibility guidelines for library authors

본문

호환성의 유형

바이너리 호환성은, 라이브러리의 새 버전이 이전에 컴파일된 버전을 대체할 수 있다는 의미예요. 이전 버전 라이브러리를 상대로 컴파일된 소프트웨어는 계속 정상 동작해야 해요.

참고: 바이너리 호환성에 대해 더 자세히 알고 싶다면 Binary compatibility validator의 README나 Evolving Java-based APIs 문서를 참고하세요.

소스 호환성은, 라이브러리의 새 버전이 라이브러리를 사용하는 소스 코드를 전혀 수정하지 않아도 이전 버전을 대체할 수 있다는 뜻이에요. 다만 이 클라이언트 코드를 컴파일한 결과물이 라이브러리를 컴파일한 결과물과 더는 호환되지 않을 수 있으므로, 호환성을 보장하려면 클라이언트 코드를 새 버전 라이브러리에 맞춰 다시 빌드해야 해요.

동작 호환성은, 라이브러리의 새 버전이 버그 수정을 제외하고는 기존 기능을 바꾸지 않는다는 의미예요. 같은 기능이 관여하고, 같은 의미(semantics)를 가져야 해요.

호환 가능한 언어·API 버전 고르기

라이브러리를 배포할 때는 컴파일 타임과 런타임 호환성을 모두 고려해야 해요:

• 언어 버전은 직접 라이브러리를 사용하는 코드를 컴파일할 수 있는 Kotlin 컴파일러 버전을 결정해요.
• API 버전은 런타임에 필요한 최소 Kotlin 표준 라이브러리 버전을 결정해요.

대부분의 경우 언어 버전과 API 버전을 같게 쓰는 게 좋아요.

라이브러리에 더 새로운 언어 버전을 설정하면, 사용자들은 더 새로운 Kotlin 컴파일러 버전을 써야 해요:

• JVM에서는 사용자가 이전 언어 버전 이후의 아무 컴파일러 버전을 쓸 수 있어요. 예를 들어 라이브러리가 언어 버전 2.2를 쓰면, 사용자는 2.1.x, 2.2.x 또는 그 이후 버전 컴파일러를 쓸 수 있어요.
• 다른 플랫폼에서는 사용자가 라이브러리에 설정된 언어 버전과 같거나 그 이후의 컴파일러 버전을 써야 해요. 이 요구 사항은, 사용자가 컴파일러를 당장 업그레이드할 수 없을 때 새 버전 라이브러리로의 업그레이드를 미루게 만들 수 있어요.

사용자들은 또한 라이브러리에 설정된 API 버전보다 최소한 같거나 새로운 Kotlin 표준 라이브러리 버전을 제공해야 해요. 그래서 런타임 환경을 사용자가 통제하기 어렵고 새로운 표준 라이브러리 버전을 제공하기 힘든 경우(Gradle이나 IDE 플러그인처럼)에는 업그레이드가 더 어려워질 수 있어요.

라이브러리에 가장 잘 맞는 언어·API 버전을 고르세요. 새 버전은 최신 Kotlin 기능을 쓸 수 있게 해 주고, 이전 버전은 더 많은 사용자가 라이브러리를 쓰게 해 줘요. 어떤 선택이 최선인지는 라이브러리의 사용 사례와 그것에 의존하는 사용자 수에 따라 달라져요.

Binary compatibility validator 사용하기

JetBrains는 Binary compatibility validator라는 도구를 제공해요. 이 도구로 API의 여러 버전 간에 바이너리 호환성을 보장할 수 있어요.

이 도구는 Gradle 플러그인으로 구현되어 있고, 빌드에 두 개의 태스크를 추가해요:

• apiDump 태스크는 API를 설명하는 사람이 읽을 수 있는 .api 파일을 만들어요.
• apiCheck 태스크는 저장된 API 설명을 현재 빌드에서 컴파일된 클래스와 비교해요.

apiCheck 태스크는 빌드 시점에 표준 Gradle check 태스크에 의해 호출돼요. 호환성이 깨지면 빌드가 실패하죠. 이때는 apiDump 태스크를 수동으로 실행해서 이전 버전과 새 버전의 차이를 비교해 보세요. 변경 내용에 만족한다면 VCS 안에 있는 기존 .api 파일을 갱신하면 돼요.

이 validator는 멀티플랫폼 라이브러리가 만든 KLib 검증에 대한 실험적 지원을 제공해요.

Kotlin Gradle 플러그인의 바이너리 호환성 검증

Kotlin Gradle 플러그인은 2.2.0 버전부터 바이너리 호환성 검증을 지원해요. 자세한 내용은 Kotlin Gradle 플러그인의 바이너리 호환성 검증 문서를 참고하세요.

반환 타입을 명시적으로 지정하기

Kotlin 코딩 가이드라인에서 논의한 것처럼, API 안에서는 함수 반환 타입과 프로퍼티 타입을 항상 명시적으로 지정해야 해요. Explicit API mode에 관한 섹션도 함께 참고하세요.

다음 예시를 볼게요. 라이브러리 작성자가 JsonDeserializer를 만들면서, 편의를 위해 확장 함수로 Int 타입과 연결했어요:

class JsonDeserializer<T>(private val fromJson: (String) -> T) {
    fun deserialize(input: String): T {
        ...
    }
}

fun Int.defaultDeserializer() = JsonDeserializer { ... }

이제 이 작성자가 구현을 JsonOrXmlDeserializer로 바꿨다고 해 볼게요:

class JsonOrXmlDeserializer<T>(
    private val fromJson: (String) -> T,
    private val fromXML: (String) -> T
) {
    fun deserialize(input: String): T {
        ...
    }
}

fun Int.defaultDeserializer() = JsonOrXmlDeserializer({ ... }, { ... })

XML을 역직렬화할 수 있는 기능이 추가되긴 했지만 기존 기능은 계속 동작해요. 다만 이 변경은 바이너리 호환성을 깨요.

기존 API 함수에 인자를 추가하지 않기

공개 API에 기본값이 없는 인자를 추가하면 바이너리·소스 호환성이 모두 깨져요. 사용자가 이전보다 더 많은 정보를 호출에 제공해야 하기 때문이에요. 그런데 기본값이 있는 인자를 추가하는 것조차 호환성을 깰 수 있어요.

예를 들어 lib.kt에 이런 함수가 있다고 해 볼게요:

fun fib() = … // Returns zero

그리고 client.kt에는 이런 함수가 있어요:

fun main() {
    println(fib()) // Prints zero
}

이 두 파일을 JVM에서 컴파일하면 LibKt.class와 ClientKt.class 결과물이 생겨요.

이제 fib 함수를 피보나치 수열을 나타내도록 재구현해 컴파일했다고 해 볼게요. fib(3)은 2, fib(4)는 3을 반환하는 식이죠. 기존 동작을 보존하려고 파라미터를 추가하되 기본값을 0으로 지정했어요:

fun fib(input: Int = 0) = … // Returns Fibonacci member

이제 lib.kt 파일을 다시 컴파일해야 해요. client.kt 파일은 다시 컴파일할 필요가 없을 거라고 예상할 수 있겠죠. 그래서 ClientKt.class를 이렇게 호출해 볼게요:

$ kotlin ClientKt.class

그런데 이렇게 하면 NoSuchMethodError가 발생해요:

Exception in thread "main" java.lang.NoSuchMethodError: 'int LibKt.fib()'
       at LibKt.main(fib.kt:2)
       at LibKt.main(fib.kt)
       …

이유는 Kotlin/JVM 컴파일러가 생성하는 바이트코드에서 메서드 시그니처가 바뀌었기 때문이에요. 그래서 바이너리 호환성이 깨진 거예요.

다만 소스 호환성은 유지돼요. 두 파일을 모두 다시 컴파일하면 프로그램은 이전처럼 동작해요.

오버로드로 바이너리 호환성 유지하기

배포된 API에 선택적 파라미터를 추가할 때는 실험적인 @IntroducedAt 애너테이션으로 바이너리 호환성을 유지할 수 있어요.

추가한 각 선택적 파라미터에, 도입된 버전과 함께 애너테이션을 붙여요. 예를 들어:

@OptIn(ExperimentalVersionOverloading::class)
fun fib(@IntroducedAt("1.1") input: Int = 0) = …

컴파일러는 이 정보를 사용해서 대응하는 숨은 오버로드(hidden overload)를 생성해요.

JVM용 Kotlin 코드를 작성할 때는, 기본값이 있는 함수에 @JvmOverloads 애너테이션을 써서 오버로드를 생성할 수도 있어요.

참고: @JvmOverloads 애너테이션은 Kotlin 호출자에게 바이너리 호환성을 보존해 주지 않아요. 배포된 API를 바꿀 때는 @IntroducedAt 애너테이션이나 수동 오버로드를 사용하세요.

기본값이 있는 단일 함수 대신 오버로드를 직접 만들 수도 있어요. 예를 들어 fib() 함수가 Int 파라미터를 받게 하고 싶다면, 별도의 오버로드를 만들어요:

fun fib() = …
fun fib(input: Int) = …

반환 타입을 넓히거나 좁히지 않기

API를 발전시키다 보면 함수의 반환 타입을 넓히거나(wide) 좁히고(narrow) 싶어질 때가 흔해요. 예를 들어 다음 버전에서 반환 타입을 List에서 Collection으로, 또는 Collection에서 List로 바꾸고 싶을 수 있죠.

인덱싱 지원 요청을 충족하려고 타입을 List로 좁히고 싶을 수도 있어요. 반대로, 다루는 데이터에 자연스러운 순서가 없다는 걸 깨달아서 타입을 Collection으로 넓히고 싶을 수도 있고요.

반환 타입을 넓히면 호환성이 깨진다는 건 쉽게 알 수 있어요. List에서 Collection으로 바꾸면 인덱싱을 쓰는 코드가 모두 깨지죠.

반대로 반환 타입을 좁히는 것, 예를 들어 Collection에서 List로 바꾸면 호환성이 유지될 거라고 생각할 수 있어요. 안타깝게도 소스 호환성은 유지되지만 바이너리 호환성은 깨져요.

Library.kt 파일에 이런 데모 함수가 있다고 해 볼게요:

public fun demo(): Number = 3

그리고 Client.kt에는 이 함수를 쓰는 클라이언트가 있어요:

fun main() {
    println(demo()) // Prints 3
}

demo의 반환 타입을 바꾸고 Library.kt만 다시 컴파일하는 상황을 가정해 볼게요:

fun demo(): Int = 3

클라이언트를 다시 실행하면 (JVM에서) 다음 오류가 발생해요:

Exception in thread "main" java.lang.NoSuchMethodError: 'java.lang.Number Library.demo()'
        at ClientKt.main(call.kt:2)
        at ClientKt.main(call.kt)
        …

이건 main 메서드에서 생성된 바이트코드의 다음 명령어 때문에 일어나요:

0: invokestatic  #12 // Method Library.demo:()Ljava/lang/Number;

JVM은 Number를 반환하는 demo라는 정적 메서드를 호출하려 해요. 그런데 이 메서드가 더는 존재하지 않으니, 바이너리 호환성이 깨진 거죠.

API에 data class 사용 피하기

일반적인 개발에서 data class의 강점은, 여러분을 위해 자동으로 생성되는 추가 함수들이에요. 그런데 API 설계에서는 이 강점이 약점으로 바뀌어요.

예를 들어 API에 이런 data class를 쓴다고 해 볼게요:

data class User(
    val name: String,
    val email: String
)

나중에 active라는 프로퍼티를 추가하고 싶을 수 있어요:

data class User(
    val name: String,
    val email: String,
    val active: Boolean = true
)

이 변경은 두 가지 방식으로 바이너리 호환성을 깨요. 첫째, 생성된 생성자(constructor)의 시그니처가 달라져요. 둘째, 생성된 copy 메서드의 시그니처도 바뀌죠.

원래 시그니처(Kotlin/JVM 기준)는 이랬어요:

public final User copy(java.lang.String, java.lang.String)

active 프로퍼티를 추가한 뒤에는 시그니처가 이렇게 돼요:

public final User copy(java.lang.String, java.lang.String, boolean)

생성자의 경우와 마찬가지로, 이것도 바이너리 호환성을 깨요.

이 문제들은 보조 생성자(secondary constructor)를 직접 작성하고 copy 메서드를 오버라이드하는 방식으로 우회할 수는 있어요. 다만 그 노력이 data class를 쓰는 편리함을 상쇄할 만큼 크죠.

data class의 또 다른 문제는, 생성자 인자의 순서를 바꾸면 구조 분해(destructuring)에 쓰이는 생성된 componentX 메서드에 영향을 준다는 거예요. 바이너리 호환성을 깨지 않더라도, 순서를 바꾸면 동작 호환성은 확실히 깨져요.

애너테이션 타깃 바꾸지 않기

애너테이션을 공개한 뒤에는, 배포 이후 그 허용 타깃(target)을 바꾸지 않는 게 좋아요. 타깃을 바꾸면 사용자가 기존 코드를 다시 컴파일할 때 같은 애너테이션이 적용되는 방식이 달라질 수 있어요.

예를 들어 애너테이션이 AnnotationTarget.FIELD만 선언하면, 프로퍼티에 붙은 수식어 없는 애너테이션은 backing field에 적용돼요:

@Target(AnnotationTarget.FIELD)
annotation class Example

class User {
    @Example
    val name: String = ""
}

나중에 AnnotationTarget.PROPERTY를 추가하면, 같은 수식어 없는 애너테이션은 대신 프로퍼티에 적용돼요:

@Target(AnnotationTarget.PROPERTY, AnnotationTarget.FIELD)
annotation class Example

class User {
    @Example
    val name: String = ""
}

이건 Kotlin 컴파일러가 field 타깃보다 property 타깃을 먼저 선택하기 때문이에요. field 타깃은 property가 적용되지 않을 때만 사용돼요.

이로 인해, 특정 생성 요소에 애너테이션이 붙기를 기대하는 도구나 프레임워크의 호환성이 깨질 수 있어요. 특히 property 타깃은 Java에서 보이지 않아요. Java 리플렉션이나 Java 애너테이션 프로세서가 backing field에서 애너테이션을 찾아야 한다면, 사용자는 field use-site 타깃을 명시적으로 지정해야 해요:

class User {
    @field:Example
    val name: String = ""
}

PublishedApi 애너테이션 사용 시 고려 사항

Kotlin은 인라인 함수(inline function)가 라이브러리 API의 일부가 되는 걸 허용해요. 이 함수들에 대한 호출은 사용자가 작성한 클라이언트 코드에 인라인돼요. 이로 인해 호환성 문제가 생길 수 있어서, 이 함수들은 비공개 API 선언을 호출할 수 없게 되어 있어요.

인라인된 공개 함수에서 라이브러리의 내부(internal) API를 호출해야 한다면, 그 내부 선언에 @PublishedApi 애너테이션을 붙이면 돼요. 이렇게 하면 내부 선언이 사실상 공개(public)이 돼요. 컴파일된 클라이언트 코드에 그 참조가 들어가게 되기 때문이죠. 그래서 변경할 때는 공개 선언처럼 다뤄야 해요. 그런 변경이 바이너리 호환성에 영향을 줄 수 있거든요.

API를 실용적으로 발전시키기

시간이 지나며 기존 선언을 제거하거나 변경해서 라이브러리 API에 호환성을 깨는 변경(breaking change)을 해야 하는 경우가 있어요. 이런 상황을 실용적으로 다루는 방법을 이번 섹션에서 이야기할게요.

사용자가 라이브러리 새 버전으로 업그레이드할 때, 프로젝트 소스 코드에 라이브러리 API에 대한 해결되지 않은 참조(unresolved reference)가 남으면 안 돼요. 라이브러리 공개 API에서 무언가를 즉시 제거하는 대신, 폐기(deprecation) 주기를 따라야 해요. 이렇게 하면 사용자에게 대안으로 이주할 시간을 줄 수 있어요.

이전 선언에 @Deprecated 애너테이션을 붙여서 교체되고 있다는 걸 알려주세요. 이 애너테이션의 파라미터는 폐기에 관한 중요한 정보를 제공해요:

• message는 무엇이, 왜 바뀌는지 설명해야 해요.
• replaceWith 파라미터는 가능하면 새 API로의 자동 이주를 제공하는 데 써야 해요.
• 폐기의 level은 API를 점진적으로 폐기하는 데 사용해야 해요. 자세한 내용은 Kotlin 문서의 Deprecated 페이지를 참고하세요.

일반적으로 폐기는 먼저 경고(warning), 그다음 오류(error), 그리고 마지막으로 선언을 숨기는 순서로 진행돼요. 이 과정은 여러 마이너 릴리스에 걸쳐 일어나고, 사용자가 프로젝트에서 필요한 변경을 할 시간을 주죠. API 제거 같은 호환성을 깨는 변경은 메이저 릴리스에서만 해야 해요. 라이브러리는 다른 버전 관리·폐기 전략을 채택할 수도 있지만, 그 내용은 사용자에게 알려서 올바른 기대를 갖도록 해야 해요.

더 자세한 내용은 Kotlin Evolution principles 문서나, KotlinConf 2023에서 Leonid Startsev가 발표한 Evolving your Kotlin API painlessly for clients 강연에서 확인할 수 있어요.

RequiresOptIn 메커니즘 사용하기

Kotlin 표준 라이브러리는 opt-in 메커니즘을 제공해요. 이 메커니즘으로 사용자가 API의 일부를 쓰기 전에 명시적인 동의를 요구할 수 있죠. 이는 @RequiresOptIn으로 애너테이션된 마커 애너테이션(marker annotation)을 만드는 방식으로 동작해요. 특히 라이브러리에 새 API를 도입할 때, 소스·동작 호환성에 대한 기대를 관리하는 데 이 메커니즘을 사용해야 해요.

이 메커니즘을 쓰기로 했다면 다음 모범 사례를 따르는 걸 권장해요:

• API의 다른 부분에 서로 다른 보장을 제공하려고 opt-in 메커니즘을 사용해요. 예를 들어 기능을 Preview, Experimental, Delicate로 표시할 수 있어요. 각 범주는 문서와 KDoc 주석에서 적절한 경고 메시지와 함께 명확히 설명해야 해요.
• 라이브러리가 실험적 API를 사용한다면, 그 애너테이션을 사용자에게 전파하세요. 이렇게 하면 사용자가 아직 발전 중인 의존성을 갖고 있다는 걸 인지할 수 있어요.
• 이미 존재하는 선언을 폐기하려고 opt-in 메커니즘을 쓰지 마세요. 앞서 설명한 대로 @Deprecated를 사용해야 해요.

더 알아보기

• 심적 복잡성 최소화 전략 — Minimizing mental complexity 페이지
• 정보를 담는 문서 작성하기 — Informative documentation
• 테스트 용이성 — Testability