[Gradle] api와 implementation의 차이 (feat. java-libraly 플러그인)

 

 

 

 

 

 

이전 글에서 살펴본 자바 플러그인에 이어, 이번 글에서는 자바 라이브러리 플러그인에 대해 알아보도록 하겠습니다.

 

 

 

 

 

🧐 java-library 플러그인

java-library 플러그인은 java 플러그인을 확장하여 추가적인 기능을 제공합니다.

즉 자바 플러그인을 확장했기 때문에, Java 플러그인에 의해 제공되는 모든 source set, task, configuration등 역시도 사용할 수 있습니다.

 

자바 라이브러리 플러그인은 자바 라이브러리를 생성할 때 사용하는데, Java 라이브러리는 이를 사용하는 다른 모듈 혹은 프로젝트에서 사용할 수 있는 API를 제공합니다.

 

자바 라이브러리 플러그인은 다음과 같이 사용할 수 있습니다.

plugins {
    id 'java-library'
}

 

 

 

 

 

 

 

🧐 api configuration

java-library 플러그인은 라이브러리 생성을 위해 api라는 configuration을 제공합니다.

(자바 라이브러리 플러그인은 자바 플러그인을 상속하였기 때문에, 자바 플러그인에서 제공하는 implementation 등의 configuration들 역시 모두 제공합니다.)

 

 

api configuration은 라이브러리가 제공하는 API에서 (사용자에게) 노출되어지는 의존성을 선언하는데 사용됩니다.

따라서 api로 선언된 의존성을 가진 모듈을 사용하는 소비자(다른 모듈, 혹은 다른 프로젝트 등)에서도 해당 라이브러리의 클래스 및 메서드에 접근할 수 있습니다.

이를 위해서, api로 선언된 의존성은 소비자의 compile classpath와 runtime classpath 모두에 포함됩니다.

 

 

 

 

 

 

 

🧐 api와 implementaion의 차이점

api로 선언된 의존성은 소비자의 compile classpath와 runtime classpath 모두에 포함되는 반면,

implementation configuration은 내부에서 사용되는 의존성을 선언하는데 사용됩니다.

 

즉 implementation을 사용하여 선언된 의존성은 해당 모듈 내부에서만 사용되고, 다른 모듈에 노출되지 않습니다.

이로 인해 모듈 내부에서 implementation으로 선언되어 사용되는 라이브러리의 변경사항은 다른 모듈에 영향을 미치지 않습니다.

이를 위해서, Implemetation을 사용하여 선언된 의존성은 소비자의 compile classpath에는 포함되지 않습니다.

api는 의존성을 다른 모듈에 노출하고, implementation은 의존성을 노출하지 않습니다.

 

 

 

 

 

🌱 예시

멀티 모듈 프로젝트를 예시로 살펴보겠습니다.

우선 전체 구조는 다음과 같습니다.

해당 프로젝트에는 module-api와 module-consumer라는 두 모듈이 존재하며, module-consumer에서 module-api를 의존하는 구조입니다.

 

 

 

 

🔎 root [settings.gradle]

rootProject.name = 'gradle-study'
include('module-api')
include('module-consumer')

 

 

 

 

🔎 root [build.gradle]

allprojects {
    group 'org.example'
    version 'unspecified'
    repositories {
        mavenCentral()
    }
}

 

 

 

🔎 module-api [build.gradle]

plugins {
    id 'java-library'
}

dependencies {
    api 'org.apache.httpcomponents:httpclient:4.5.7'
    implementation 'org.apache.commons:commons-lang3:3.5'
}

 

 

 

 

🔎 module-consumer [build.gradle]

plugins {
    id 'java'
}

group 'org.example'
version 'unspecified'

repositories {
    mavenCentral()
}

dependencies {
    implementation project(':module-api')
}

 

 

빌드 결과는 다음과 같습니다.

 

api로 선언한 의존성인 'org.apache.httpcomponents:httpclient:4.5.7'의 경우,

해당 모듈을 사용하는 다른 모듈(consumer)의 compileClasspath와 runtimeClasspath에 모두 포함됩니다.

 

implementation으로 선언한 의존성인 'org.apache.commons:commons-lang3:3.5'의 경우,

consumer의 compileClasspath에는 포함되지 않는 것을 알 수 있습니다.

 

 

 

 

 

 

 

 

 

 

🧐 언제 api를 쓰고, 언제 implemetation을 쓸까?

우선적인 규칙은 다음과 같습니다.

가능하다면 implementation을 써라.

이렇게 하면 해당 모듈에서 사용하는 의존성들이, 해당 모듈을 사용하는 다른 모듈의 compileClasspath에 포함되지 않으므로, 여러 장점을 많이 얻을 수 있습니다..

 

 

 

그렇다면 언제 api를 사용해야 할까요?

 

라이브러리가 구현하는 공개 API에 노출되는 의존성에 대해서 사용하여야 하는데, 그 예시는 다음과 같습니다.

상속받아 사용하거나 인터페이스를 구현하는 경우:
이는 상속받은 클래스나 구현한 인터페이스의 공개 API를 사용하는 다른 모듈에서 해당 타입을 사용할 수 있도록 하기 위함입니다.

제네틱 타입 파라미터를 포함하여, public 메서드의 파라미터 혹은 반환값으로 사용되는 경우:
이는 다른 모듈에서 해당 메서드를 호출하거나 오버라이드할 때 해당 타입을 사용할 수 있도록 하기 위함입니다. 또한, 제네릭 파라미터 타입을 api 종속성으로 정의해야 하는 이유는 해당 제네릭 타입의 실제 타입 인자가 노출되기 때문입니다.

public 필드에서 사용되는 경우:
이는 다른 모듈에서 해당 필드를 사용할 수 있도록 하기 위함입니다.

pulbic 애노테이션을 사용하는 경우:
이는 다른 모듈에서 해당 애노테이션을 사용할 수 있도록 하기 위함입니다.

 

 

 

이와 대조적으로, api를 사용하지 않고, implementation으로 가능한 경우는 다음과 같습니다.

메서드 내부에서만 사용되는 경우

private 멤버변수로만 사용되는 경우

내부(inner) 클래스에서만 발견되는 유형 (내부 클래스는 static nested class를 의미하는 것이 아님)

 

 

 

 

 

 

 

🌱 예시

다음 예시에서, 두 개의 third-party 라이브러리를 사용합니다.

하나는 클래스의 public API에 노출되고, 다른 하나는 내부에서만 사용됩니다.

 

import로는 어느 것이 어느것인지 알 수 없으므로 필드와 생성자, 메서드들을 살펴보아야 합니다.

import org.apache.commons.lang3.exception.ExceptionUtils;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.HttpStatus;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;

import java.io.ByteArrayOutputStream;

public class HttpClientWrapper {

    private final HttpClient client; // private member로 사용됩니다.

    // HttpClient 는 public 메서드의 파라미터로 사용됩니다.
    public HttpClientWrapper(HttpClient client) {
        this.client = client;
    }

    public byte[] doRawGet(String url) {
        HttpGet request = new HttpGet(url);
        try {
            HttpEntity entity = doGet(request);
            ByteArrayOutputStream baos = new ByteArrayOutputStream();
            entity.writeTo(baos);
            return baos.toByteArray();
        } catch (Exception e) {
            ExceptionUtils.rethrow(e); // ExceptionUtils는 메서드 내부에서만 사용됩니다.
        } finally {
            request.releaseConnection();
        }
        return null;
    }

    // HttpGet 와 HttpEntity 는 private 메서드에서만 사용되므로, API에 속하지 않습니다.
    private HttpEntity doGet(HttpGet get) throws Exception {
        HttpResponse response = client.execute(get);
        if (response.getStatusLine().getStatusCode() != HttpStatus.SC_OK) {
            System.err.println("Method failed: " + response.getStatusLine());
        }
        return response.getEntity();
    }
}

 

위 클래스의 public 생성자는 파라미터로 HttpClient를 사용합니다.

따라서 HttpClient는 해당 API를 사용하는 다른 모듈에게 노출되어집니다.

HttpGet과 HttpEntity는 private 메서드에서만 사용되므로 이들은 HttpClient를 노출하지는 않습니다.

 

위 예시에서는 오직 생성자에 사용된 HttpClient에 의하여 httpclient에 대한 dependency를 api으로 설정해야 합니다.

 

반면에 ExceptionUtils은 오직 메서드 바디에서만 사용되기 때문에 이는 implementation 을 사용해야 합니다.

dependencies {
    api 'org.apache.httpcomponents:httpclient:4.5.7'
    implementation 'org.apache.commons:commons-lang3:3.5'
}

 

 

위 모듈을 다른 모듈에서 사용하면, classpath는 다음과 같이 설정됩니다.

 

api로 의존성을 설정한다면, 컴파일과 런타임 classpath 모두에 포함되는것을 확인할 수 있습니다.

그러나 implementation을 사용한다면 런타임 classpath에만 포함되는 것을 알 수 있습니다.

 

 

 

만약 위에서 설정된 api를 implementation으로 바꾼 뒤, 다른 모듈에서 사용한다면, 다음과 같이 컴파일 에러가 발생합니다.

 

 

 

 

 

 

 

 

 

🧐 Java Library plugin configuration

아래 그림은 java-library에서 제공하는 configuration 들의 관계를 나타낸 것입니다.

 

 

위 그림을 통해 알 수 있듯이, compileClasspath, runtimeElements, runtimeClasspath은 implementation을 상속하기 때문에, implementation으로 선언된 의존성은 compileClasspath, runtimeElements, runtimeClasspath에서도 모두 포함됩니다.

 

마찬가지로 apiElements와 implementation는 api를 상속받았기 때문에, api에 정의된 의존성들은 implementation과 apiElements 모두에서 사용 가능합니다.

 

 

 

 

 

 

다음 그림은 테스트 구성 설정을 나타냅니다.

 

 

 

 

 

 

 

 

🔎 Reference

https://docs.gradle.org/current/userguide/java_plugin.html#java_plugin

The Java Plugin

https://docs.gradle.org/current/userguide/java_library_plugin.html

The Java Library Plugin