Kotlin 2.0 호환성 가이드

_언어를 현대적으로 유지하기_와 _편안한 업데이트_는 Kotlin 언어 설계의 근본 원칙 중 하나입니다. 전자는 언어 발전을 저해하는 구성 요소를 제거해야 한다고 말하며, 후자는 코드 마이그레이션이 가능한 한 원활하게 이루어지도록 이러한 제거가 사전에 잘 전달되어야 한다고 말합니다.

대부분의 언어 변경 사항은 업데이트된 변경 로그나 컴파일러 경고와 같은 다른 채널을 통해 이미 발표되었지만, 이 문서는 Kotlin 1.9에서 Kotlin 2.0으로의 마이그레이션을 위한 완전한 참조 자료를 제공합니다.

NOTE

Kotlin K2 컴파일러는 Kotlin 2.0의 일부로 도입되었습니다. 새 컴파일러의 이점, 마이그레이션 중 발생할 수 있는 변경 사항, 이전 컴파일러로 롤백하는 방법에 대한 정보는 K2 컴파일러 마이그레이션 가이드를 참조하세요.

기본 용어

이 문서에서는 여러 종류의 호환성을 소개합니다:

• 소스: 소스 호환되지 않는 변경 사항은 (오류나 경고 없이) 이전에 잘 컴파일되던 코드가 더 이상 컴파일되지 않도록 합니다.
• 바이너리: 두 바이너리 아티팩트는 서로 교체했을 때 로딩 또는 링크 오류가 발생하지 않으면 바이너리 호환된다고 합니다.
• 동작: 동일한 프로그램이 변경 적용 전후에 다른 동작을 보일 경우 해당 변경 사항은 동작 호환되지 않는다고 합니다.

이러한 정의는 순수 Kotlin에 대해서만 제공된다는 점을 기억하세요. 다른 언어 관점(예: Java)에서의 Kotlin 코드 호환성은 이 문서의 범위를 벗어납니다.

언어

투영된 리시버에 대한 합성 세터 사용 폐지

이슈: KT-54309

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

요약: Java 클래스의 합성 세터를 사용하여 클래스의 투영된 타입과 충돌하는 타입을 할당하면 오류가 발생합니다.

사용 중단 주기:

• 1.8.20: 합성 프로퍼티 세터가 반공변 위치에 투영된 매개변수 타입을 가지며 호출 사이트 인자 타입을 호환되지 않게 만들 때 경고를 보고합니다.
• 2.0.0: 경고를 오류로 격상합니다.

Java 서브클래스에서 오버로드된 인라인 클래스 매개변수로 함수를 호출할 때의 올바른 맹글링

이슈: KT-56545

구성 요소: 코어 언어

호환되지 않는 변경 타입: 동작

사용 중단 주기:

• 2.0.0: 함수 호출에서 올바른 맹글링 동작을 사용합니다. 이전 동작으로 되돌리려면 -XXLanguage:-MangleCallsToJavaMethodsWithValueClasses 컴파일러 옵션을 사용하세요.

반공변성 캡처된 타입에 대한 올바른 타입 근사 알고리즘

이슈: KT-49404

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 1.8.20: 문제가 있는 호출에 대해 경고를 보고합니다.
• 2.0.0: 경고를 오류로 격상합니다.

프로퍼티 초기화 전에 프로퍼티 값 접근 금지

이슈: KT-56408

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 2.0.0: 영향을 받는 컨텍스트에서 프로퍼티가 초기화되기 전에 접근될 때 오류를 보고합니다.

이름이 같은 임포트된 클래스에서 모호성이 있을 때 오류 보고

이슈: KT-57750

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 2.0.0: 여러 패키지에 별표 임포트로 존재하는 클래스 이름을 결정할 때 오류를 보고합니다.

기본적으로 invokedynamic 및 LambdaMetafactory를 통해 Kotlin 람다 생성

이슈: KT-45375

구성 요소: 코어 언어

호환되지 않는 변경 타입: 동작

사용 중단 주기:

• 2.0.0: 새 동작을 구현합니다. 람다는 기본적으로 invokedynamic 및 LambdaMetafactory를 사용하여 생성됩니다.

표현식이 필요한 경우 단일 브랜치 if 조건문 금지

이슈: KT-57871

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 2.0.0: if 조건문에 단일 브랜치만 있는 경우 오류를 보고합니다.

제네릭 타입의 스타-프로젝션을 전달하여 자체 상위 바운드 위반 금지

이슈: KT-61718

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 2.0.0: 제네릭 타입의 스타-프로젝션을 전달하여 자체 상위 바운드가 위반될 때 오류를 보고합니다.

비공개 인라인 함수의 반환 타입에서 익명 타입 근사화

이슈: KT-54862

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 1.9.0: 추론된 반환 타입에 익명 타입이 포함된 비공개 인라인 함수에 대해 경고를 보고합니다.
• 2.0.0: 이러한 비공개 인라인 함수의 반환 타입을 상위 타입으로 근사화합니다.

로컬 함수 타입 프로퍼티의 invoke 컨벤션보다 로컬 확장 함수 호출을 우선하는 오버로드 결정 동작 변경

이슈: KT-37592

구성 요소: 코어 언어

호환되지 않는 변경 타입: 동작

사용 중단 주기:

• 2.0.0: 새로운 오버로드 결정 동작을 구현합니다. 함수 호출이 invoke 컨벤션보다 일관되게 우선순위를 가집니다.

바이너리 의존성에서 상위 타입 변경으로 인해 상속된 멤버 충돌 발생 시 오류 보고

이슈: KT-51194

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 1.7.0: 바이너리 의존성에서 상위 타입에 상속된 멤버 충돌이 발생한 선언에 대해 CONFLICTING_INHERITED_MEMBERS_WARNING 경고를 보고합니다.
• 2.0.0: 경고를 오류인 CONFLICTING_INHERITED_MEMBERS로 격상합니다.

불변 타입 매개변수의 @UnsafeVariance 어노테이션 무시

이슈: KT-57609

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 2.0.0: 새로운 동작을 구현합니다. @UnsafeVariance 어노테이션은 반공변 매개변수에서 타입 불일치에 대한 오류를 보고할 때 무시됩니다.

컴패니언 객체 멤버에 대한 호출 외부 참조 타입 변경

이슈: KT-54316

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 1.8.20: 컴패니언 객체 함수 참조 타입이 언바운드 참조로 추론될 때 경고를 보고합니다.
• 2.0.0: 모든 사용 컨텍스트에서 컴패니언 객체 함수 참조가 바운드 참조로 추론되도록 동작을 변경합니다.

비공개 인라인 함수에서 익명 타입 노출 금지

이슈: KT-33917

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 1.3.0: 비공개 인라인 함수에서 반환되는 익명 객체의 자체 멤버 호출에 대해 경고를 보고합니다.
• 2.0.0: 이러한 비공개 인라인 함수의 반환 타입을 상위 타입으로 근사화하고 익명 객체 멤버에 대한 호출을 결정하지 않습니다.

while 루프 break 후 불안정한 스마트 캐스트에 대한 오류 보고

이슈: KT-22379

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 2.0.0: 새로운 동작을 구현합니다. 이전 동작은 언어 버전 1.9로 전환하여 복원할 수 있습니다.

교차 타입 변수에 해당 교차 타입의 서브타입이 아닌 값이 할당될 때 오류 보고

이슈: KT-53752

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 2.0.0: 교차 타입을 가진 변수에 해당 교차 타입의 서브타입이 아닌 값이 할당될 때 오류를 보고합니다.

SAM 생성자로 구성된 인터페이스에 opt-in이 필요한 메서드가 포함된 경우 opt-in 요구

이슈: KT-52628

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 1.7.20: SAM 생성자를 통한 OptIn 사용에 대해 경고를 보고합니다.
• 2.0.0: SAM 생성자를 통한 OptIn 사용에 대해 경고를 오류로 격상합니다 (또는 OptIn 마커 심각도가 경고인 경우 계속 경고를 보고합니다).

타입 별칭 생성자에서 상위 바운드 위반 금지

이슈: KT-54066

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 1.8.0: 타입 별칭 생성자에서 상위 바운드가 위반되는 경우에 대해 경고를 도입합니다.
• 2.0.0: K2 컴파일러에서 경고를 오류로 격상합니다.

구조분해 변수의 실제 타입을 지정된 명시적 타입과 일치시키기

이슈: KT-57011

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 2.0.0: 새로운 동작을 구현합니다. 구조분해 변수의 실제 타입은 지정된 명시적 타입과 일치합니다.

opt-in이 필요한 기본값을 가진 매개변수 타입을 가진 생성자를 호출할 때 opt-in 요구

이슈: KT-55111

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 1.8.20: opt-in이 필요한 매개변수 타입을 가진 생성자 호출에 대해 경고를 보고합니다.
• 2.0.0: 경고를 오류로 격상합니다 (또는 OptIn 마커 심각도가 경고인 경우 계속 경고를 보고합니다).

동일한 스코프 레벨에서 이름이 같은 프로퍼티와 이넘 엔트리 간의 모호성 보고

이슈: KT-52802

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 1.7.20: 컴파일러가 동일한 스코프 레벨에서 이넘 엔트리 대신 프로퍼티로 결정할 때 경고를 보고합니다.
• 2.0.0: K2 컴파일러에서 동일한 스코프 레벨에 이름이 같은 프로퍼티와 이넘 엔트리가 모두 있을 때 모호성을 보고합니다 (이전 컴파일러에서는 경고를 그대로 유지).

한정자 결정 동작을 변경하여 이넘 엔트리보다 컴패니언 프로퍼티 선호

이슈: KT-47310

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 2.0.0: 새로운 결정 동작을 구현합니다. 이넘 엔트리보다 컴패니언 프로퍼티가 선호됩니다.

invoke 호출 리시버 타입 및 invoke 함수 타입을 desugar된 형태로 작성된 것처럼 결정

이슈: KT-58260

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 2.0.0: invoke 호출 리시버 타입 및 invoke 함수 타입을 마치 desugar된 형태로 작성된 것처럼 독립적으로 결정합니다.

비공개 인라인 함수를 통해 비공개 클래스 멤버 노출 금지

이슈: KT-55179

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 1.9.0: 내부 인라인 함수에서 비공개 클래스 컴패니언 객체 멤버를 호출할 때 PRIVATE_CLASS_MEMBER_FROM_INLINE_WARNING 경고를 보고합니다.
• 2.0.0: 이 경고를 PRIVATE_CLASS_MEMBER_FROM_INLINE 오류로 격상합니다.

투영된 제네릭 타입에서 명확히 null 불가능한 타입의 null 허용 여부 수정

이슈: KT-54663

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 2.0.0: 새로운 동작을 구현합니다. 투영된 타입은 모든 인플레이스(in-place) non-null 타입을 고려합니다.

전위 증분 연산자의 추론된 타입을 inc() 연산자의 반환 타입 대신 게터의 반환 타입과 일치시키도록 변경

이슈: KT-57178

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 2.0.0: 새로운 동작을 구현합니다. 전위 증분 연산자의 추론된 타입은 inc() 연산자의 반환 타입 대신 게터의 반환 타입과 일치하도록 변경됩니다.

상위 클래스에 선언된 제네릭 내부 클래스에서 내부 클래스를 상속할 때 바운드 검사 강제

이슈: KT-61749

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 2.0.0: 제네릭 내부 상위 클래스의 타입 매개변수의 상위 바운드가 위반될 때 오류를 보고합니다.

예상 타입이 함수 타입 매개변수를 가진 함수 타입일 때 SAM 타입을 가진 호출 가능 참조 할당 금지

이슈: KT-64342

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 2.0.0: 예상 타입이 함수 타입 매개변수를 가진 함수 타입일 때 SAM 타입을 가진 호출 가능 참조에 대해 컴파일 오류를 보고합니다.

컴패니언 객체에 대한 어노테이션 결정 시 컴패니언 객체 스코프 고려

이슈: KT-64299

구성 요소: 코어 언어

호환되지 않는 변경 타입: 동작

사용 중단 주기:

• 2.0.0: 새로운 동작을 구현합니다. 컴패니언 객체에 대한 어노테이션 결정 시 컴패니언 객체 스코프는 더 이상 무시되지 않습니다.

안전 호출과 컨벤션 연산자 조합에 대한 평가 의미론 변경

이슈: KT-41034

구성 요소: 코어 언어

호환되지 않는 변경 타입: 동작

사용 중단 주기:

• 1.4.0: 각 잘못된 호출에 대해 경고를 보고합니다.
• 2.0.0: 새로운 결정 동작을 구현합니다.

백킹 필드와 커스텀 세터가 있는 프로퍼티는 즉시 초기화되어야 함

이슈: KT-58589

구성 요소: 코어 언어

호환되지 않는 변경 타입: 동작

사용 중단 주기:

• 1.9.20: 주 생성자가 없는 경우 MUST_BE_INITIALIZED 경고를 도입합니다.
• 2.0.0: 경고를 오류로 격상합니다.

invoke 연산자 컨벤션 호출에서 임의의 표현식에 대한 Unit 변환 금지

이슈: KT-61182

구성 요소: 코어 언어

호환되지 않는 변경 타입: 동작

사용 중단 주기:

• 2.0.0: 변수 및 invoke 결정에서 임의의 표현식에 Unit 변환이 적용될 때 오류를 보고합니다. 영향을 받는 표현식에 대해 이전 동작을 유지하려면 -XXLanguage:+UnitConversionsOnArbitraryExpressions 컴파일러 옵션을 사용하세요.

안전 호출로 필드에 접근할 때 null 허용 값을 non-null Java 필드에 할당하는 것을 금지

이슈: KT-62998

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 2.0.0: null 허용 값이 non-null Java 필드에 할당되는 경우 오류를 보고합니다.

원시 타입 매개변수를 포함하는 Java 메서드를 오버라이드할 때 스타-투영된 타입 요구

이슈: KT-57600

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 2.0.0: 새로운 동작을 구현합니다. 원시 타입 매개변수에 대한 오버라이딩은 금지됩니다.

V에 컴패니언이 있을 때 (V)::foo 참조 결정 변경

이슈: KT-47313

구성 요소: 코어 언어

호환되지 않는 변경 타입: 동작

사용 중단 주기:

• 1.6.0: 현재 컴패니언 객체 인스턴스에 바인딩된 호출 가능 참조에 대해 경고를 보고합니다.
• 2.0.0: 새로운 동작을 구현합니다. 타입 주변에 괄호를 추가하는 것이 더 이상 타입의 컴패니언 객체 인스턴스에 대한 참조를 만들지 않습니다.

사실상 공개적인 인라인 함수에서 암묵적인 비공개 API 접근 금지

이슈: KT-54997

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 1.8.20: 공개 인라인 함수에서 암묵적인 비공개 API에 접근할 때 컴파일 경고를 보고합니다.
• 2.0.0: 경고를 오류로 격상합니다.

프로퍼티 게터에 use-site get 어노테이션 사용 금지

이슈: KT-57422

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 1.9.0: 게터에 use-site get 어노테이션이 있을 때 경고 (진행 모드에서는 오류)를 보고합니다.
• 2.0.0: 경고를 INAPPLICABLE_TARGET_ON_PROPERTY 오류로 격상합니다. 경고로 되돌리려면 -XXLanguage:-ProhibitUseSiteGetTargetAnnotations를 사용하세요.

빌더 추론 람다 함수에서 타입 매개변수가 상위 바운드로 암묵적으로 추론되는 것 방지

이슈: KT-47986

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 1.7.20: 타입 인자에 대한 타입 매개변수가 선언된 상위 바운드로 추론될 수 없을 때 경고 (진행 모드에서는 오류)를 보고합니다.
• 2.0.0: 경고를 오류로 격상합니다.

공개 시그니처에서 로컬 타입을 근사화할 때 null 허용 여부 유지

이슈: KT-53982

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 1.8.0: 유연한 타입은 유연한 상위 타입으로 근사화됩니다. 선언이 null 불가능해야 하는 null 불가능 타입으로 추론되어 NPE를 피하기 위해 타입을 명시적으로 지정해야 함을 알릴 때 경고를 보고합니다.
• 2.0.0: null 허용 타입은 null 허용 상위 타입으로 근사화됩니다.

스마트 캐스팅 목적을 위한 false && ... 및 false || ... 특별 처리 제거

이슈: KT-65776

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 2.0.0: 새로운 동작을 구현합니다. false && ... 및 false || ...에 대한 특별 처리는 없습니다.

이넘의 인라인 오픈 함수 금지

이슈: KT-34372

구성 요소: 코어 언어

호환되지 않는 변경 타입: 소스

사용 중단 주기:

• 1.8.0: 이넘의 인라인 오픈 함수에 대해 경고를 보고합니다.
• 2.0.0: 경고를 오류로 격상합니다.

도구

Gradle의 가시성 변경

이슈: KT-64653

구성 요소: Gradle

호환되지 않는 변경 타입: 소스

요약: 이전에는 특정 DSL 컨텍스트를 위한 Kotlin DSL 함수 및 프로퍼티가 의도치 않게 다른 DSL 컨텍스트로 유출되었습니다. 이를 방지하기 위해 @KotlinGradlePluginDsl 어노테이션을 추가하여 Kotlin Gradle 플러그인 DSL 함수 및 프로퍼티가 의도하지 않은 수준으로 노출되는 것을 방지합니다. 다음 수준들이 서로 분리됩니다:

• Kotlin 확장
• Kotlin 타겟
• Kotlin 컴파일
• Kotlin 컴파일 태스크

사용 중단 주기:

• 2.0.0: 가장 일반적인 경우, 빌드 스크립트가 잘못 구성된 경우 컴파일러가 수정 제안과 함께 경고를 보고합니다. 그렇지 않으면 컴파일러가 오류를 보고합니다.

kotlinOptions DSL 사용 중단

이슈: KT-63419

구성 요소: Gradle

호환되지 않는 변경 타입: 소스

요약: kotlinOptions DSL 및 관련 KotlinCompile<KotlinOptions> 태스크 인터페이스를 통해 컴파일러 옵션을 구성하는 기능은 사용 중단되었습니다.

사용 중단 주기:

• 2.0.0: 경고를 보고합니다.

KotlinCompilation DSL에서 compilerOptions 사용 중단

이슈: KT-65568

구성 요소: Gradle

호환되지 않는 변경 타입: 소스

요약: KotlinCompilation DSL에서 compilerOptions 프로퍼티를 구성하는 기능은 사용 중단되었습니다.

사용 중단 주기:

• 2.0.0: 경고를 보고합니다.

CInteropProcess 처리의 이전 방식 사용 중단

이슈: KT-62795

구성 요소: Gradle

호환되지 않는 변경 타입: 소스

요약: CInteropProcess 태스크와 CInteropSettings 클래스는 이제 defFile 및 defFileProperty 대신 definitionFile 프로퍼티를 사용합니다.

이는 defFile이 동적으로 생성될 때 CInteropProcess 태스크와 defFile을 생성하는 태스크 사이에 추가 dependsOn 관계를 추가할 필요성을 제거합니다.

Kotlin/Native 프로젝트에서 Gradle은 이제 연결된 태스크가 빌드 프로세스 후반에 실행된 후 definitionFile 프로퍼티의 존재 여부를 지연하여 확인합니다.

사용 중단 주기:

• 2.0.0: defFile 및 defFileProperty 매개변수는 사용 중단되었습니다.

kotlin.useK2 Gradle 프로퍼티 제거

이슈: KT-64379

구성 요소: Gradle

호환되지 않는 변경 타입: 동작

요약: kotlin.useK2 Gradle 프로퍼티가 제거되었습니다. Kotlin 1.9.*에서는 K2 컴파일러를 활성화하는 데 사용될 수 있었지만, Kotlin 2.0.0 이상에서는 K2 컴파일러가 기본적으로 활성화되므로 이 프로퍼티는 더 이상 효과가 없으며 이전 컴파일러로 전환하는 데 사용될 수 없습니다.

사용 중단 주기:

• 1.8.20: kotlin.useK2 Gradle 프로퍼티는 사용 중단되었습니다.
• 2.0.0: kotlin.useK2 Gradle 프로퍼티가 제거되었습니다.

사용 중단된 플랫폼 플러그인 ID 제거

이슈: KT-65187

구성 요소: Gradle

호환되지 않는 변경 타입: 소스

요약: 다음 플랫폼 플러그인 ID에 대한 지원이 제거되었습니다:

• kotlin-platform-android
• kotlin-platform-jvm
• kotlin-platform-js
• org.jetbrains.kotlin.platform.android
• org.jetbrains.kotlin.platform.jvm
• org.jetbrains.kotlin.platform.js

사용 중단 주기:

• 1.3: 플랫폼 플러그인 ID는 사용 중단되었습니다.
• 2.0.0: 플랫폼 플러그인 ID는 더 이상 지원되지 않습니다.

outputFile JavaScript 컴파일러 옵션 제거

이슈: KT-61116

구성 요소: Gradle

호환되지 않는 변경 타입: 소스

요약: outputFile JavaScript 컴파일러 옵션이 제거되었습니다. 대신 컴파일된 JavaScript 출력 파일이 작성되는 디렉터리를 지정하려면 Kotlin2JsCompile 태스크의 destinationDirectory 프로퍼티를 사용할 수 있습니다.

사용 중단 주기:

• 1.9.25: outputFile 컴파일러 옵션은 사용 중단되었습니다.
• 2.0.0: outputFile 컴파일러 옵션이 제거되었습니다.