Java 프로젝트에 Kotlin 추가하기 – 튜토리얼

Java 프로젝트에 Kotlin 추가하기 – 튜토리얼

Kotlin은 Java와 완전히 상호 운용되므로, 모든 것을 다시 작성하지 않고도 기존 Java 프로젝트에 점진적으로 Kotlin을 도입할 수 있어요.

이 튜토리얼에서는 다음 내용을 배워요:

  • Java와 Kotlin 코드를 모두 컴파일하도록 Maven 또는 Gradle 빌드 도구를 설정하는 방법
  • 프로젝트 디렉터리에서 Java와 Kotlin 소스 파일을 구성하는 방법
  • IntelliJ IDEA를 사용해 Java 파일을 Kotlin으로 변환하는 방법

이 튜토리얼에는 기존 Java 프로젝트를 사용해도 되고, Maven과 Gradle 빌드 파일이 이미 설정된 공개 샘플 프로젝트를 클론해서 사용해도 돼요.

준비된 스킬(skill)을 사용해 변환 작업을 선호하는 AI 에이전트에게 넘길 수도 있어요. 다만 AI 처리 결과는 완전히 예측 가능하지 않다는 점을 명심하세요.

출처: Adding Kotlin to a Java project – tutorial

본문

프로젝트 구성

Java 프로젝트에 Kotlin을 추가하려면 사용하는 빌드 도구에 따라 Kotlin과 Java를 모두 사용하도록 프로젝트를 구성해야 해요.

프로젝트 구성은 Kotlin과 Java 코드가 모두 올바르게 컴파일되고 서로를 매끄럽게 참조할 수 있게 보장해요.

Maven

IntelliJ IDEA 2025.3부터 Maven 기반 Java 프로젝트에 첫 번째 Kotlin 파일을 추가하면 IDE가 자동으로 pom.xml 파일을 업데이트해 Kotlin Maven 플러그인과 표준 의존성을 포함해 줘요. 버전이나 빌드 단계를 커스터마이즈하고 싶다면 수동으로도 구성할 수 있어요.

Maven 프로젝트에서 Kotlin과 Java를 함께 사용하려면 pom.xml 파일에 Kotlin Maven 플러그인을 적용하고 Kotlin 의존성을 추가하세요.

  • <properties> 섹션에 Kotlin 버전 프로퍼티를 추가해요:
<properties>
    <kotlin.version>2.4.20</kotlin.version>
</properties>
  • <dependencies> 섹션에 필요한 의존성을 추가해요:
<dependencies>
    <!-- Add JUnit Jupiter engine for test runtime -->
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-engine</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-params</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>
  • <build><plugins> 섹션에 Kotlin 플러그인을 추가해요:
<build>
    <pluginManagement><!-- Lock down plugin versions to avoid using Maven defaults (can be moved to a parent pom file) -->
        <!-- No maven-compiler-plugin needed with Kotlin extensions -->
    </pluginManagement>
    <!-- Activate Kotlin Maven plugin for main and test sources -->
    <plugin>
        <groupId>org.jetbrains.kotlin</groupId>
        <artifactId>kotlin-maven-plugin</artifactId>
        <version>${kotlin.version}</version>
        <extensions>true</extensions>
    </plugin>
</build>

Kotlin Maven 플러그인에서 <extensions>true</extensions>를 활성화하면 다음과 같은 도움이 돼요:

  • 프로젝트에 kotlin-stdlib 의존성을 자동으로 추가해요.
  • Kotlin을 먼저 컴파일한 다음 Java를 컴파일하도록 실행 단계를 구성해요.
  • Java 코드에서 Kotlin 코드를, 반대로 Kotlin 코드에서 Java 코드를 참조할 수 있게 해요.
  • JVM 타깃 버전을 Java 컴파일러 버전과 자동으로 맞춰요.

Kotlin Maven 플러그인을 확장과 함께 사용할 때는 <build><pluginManagement> 섹션에 별도의 maven-compiler-plugin이 필요하지 않아요.

  • IDE에서 Maven 프로젝트를 다시 로드해요.
  • 테스트를 실행해 구성이 올바른지 확인해요:
./mvnw clean test

Gradle

Gradle 프로젝트에서 Kotlin과 Java를 함께 사용하려면 build.gradle.kts 파일에 Kotlin JVM 플러그인을 적용하고 Kotlin 의존성을 추가하세요.

  • plugins {} 블록에 Kotlin JVM 플러그인을 추가해요:
plugins {
    // Other plugins
    kotlin("jvm") version "2.4.20"
}
  • JVM 툴체인 버전을 Java 버전과 일치하도록 설정해요:
kotlin {
    jvmToolchain(17)
}

이렇게 하면 Kotlin이 Java 코드와 동일한 JDK 버전을 사용하게 돼요.

  • dependencies {} 블록에 Kotlin 테스트 유틸리티를 제공하고 JUnit과 통합되는 kotlin("test") 라이브러리를 추가해요:
dependencies {
    // Other dependencies

    testImplementation(kotlin("test"))
    // Other test dependencies
}
  • IDE에서 Gradle 프로젝트를 다시 로드해요.
  • 테스트를 실행해 구성이 올바른지 확인해요:
./gradlew clean test

프로젝트 구조

이 구성으로 동일한 소스 디렉터리에 Java와 Kotlin 파일을 섞어 놓을 수 있어요:

src/
  ├── main/
  │    ├── java/          # Java and Kotlin production code
  │    └── kotlin/        # Additional Kotlin production code (optional)
  └── test/
       ├── java/          # Java and Kotlin test code
       └── kotlin/        # Additional Kotlin test code (optional)

이 디렉터리들은 수동으로 만들거나, 첫 번째 Kotlin 파일을 추가할 때 IntelliJ IDEA가 만들어 주게 할 수 있어요.

Kotlin 플러그인은 src/main/java와 src/test/java 디렉터리를 모두 자동으로 인식하므로 동일한 디렉터리에 .kt 파일과 .java 파일을 함께 둘 수 있어요.

Java 파일을 Kotlin으로 변환하기

Kotlin 플러그인에는 Java 파일을 Kotlin으로 자동 변환하는 Java-to-Kotlin 변환기(J2K)도 번들로 포함되어 있어요. 파일에 J2K를 사용하려면 IntelliJ IDEA의 컨텍스트 메뉴 또는 Code 메뉴에서 Convert Java File to Kotlin File을 클릭하세요.

Convert Java to Kotlin

변환기가 완벽하지는 않지만 대부분의 보일러플레이트 코드를 Java에서 Kotlin으로 꽤 잘 변환해 줘요. 다만 때로는 수동으로 조금 손봐야 할 부분이 있어요.

컴파일러 플러그인 살펴보기

Spring이나 Java Persistence API(JPA)를 사용하는 더 복잡한 프로젝트라면 Kotlin의 언어 기능을 프레임워크 기대에 맞게 자동 조정해 보일러플레이트를 줄여 주는 Kotlin 컴파일러 플러그인을 사용할 수 있어요:

  • all-open 플러그인은 특정 어노테이션이 사용될 때 클래스와 그 멤버를 자동으로 open으로 만들어 줘요. 이는 클래스를 non-final로 요구하는 Spring 같은 프레임워크에서 특히 유용해요.

Spring용으로는 all-open 위에 감싼 전용 kotlin-spring 플러그인을 사용할 수 있어요. 이 플러그인은 Spring 어노테이션을 자동으로 지정해 줘요.

  • no-arg 플러그인은 특정 어노테이션이 있는 클래스에 인자 없는 생성자(제로-인자 생성자)를 하나 더 생성해 줘요. 이를 통해 JPA가 기본 생성자가 없는 클래스도 인스턴스화할 수 있게 돼요.

no-arg 위에 감싼 kotlin-jpa 플러그인도 사용할 수 있어요. 이 플러그인은 no-arg 어노테이션을 자동으로 지정해 줘요.

  • power-assert 플러그인은 어서션에 대한 컨텍스트 정보가 담긴 상세한 실패 메시지를 제공해 디버깅 경험을 개선해 줘요. 중간 값을 보여 줘서 테스트가 왜 실패했는지 이해하는 데 도움을 줘요.

다음 단계

Java 프로젝트에서 Kotlin을 활용하는 가장 쉬운 방법은 먼저 Kotlin 테스트를 추가하는 거예요.

Java 프로젝트에 첫 번째 Kotlin 테스트를 추가하세요.

참고 자료

  • Kotlin과 Java 상호 운용 세부 사항
  • Maven 빌드 구성 참조

더 알아보기

  • Kotlin으로 백엔드 개발하기
  • Kotlin과 JUnit으로 Java 코드 테스트하기 – 튜토리얼