[Gradle] Gradle 라이브러리 참조 문제 정리

Gradle에서 자주 발생하는 라이브러리 참조 문제를 정리합니다.

라이브러리 프로젝트(예: A)에서 다른 라이브러리(B, C 등)를 의존성으로 추가하고 이를 Maven에 배포했을 때,

해당 라이브러리를 참조하는 외부 프로젝트(예: X)에서 의존성이 전파되지 않아 클래스가 보이지 않는 문제가 생길 수 있습니다.

이러한 문제를 직면하고, 해결한 내용을 정리하였습니다.

---

api vs implementation 차이점

Gradle의 dependencies 블록에서 자주 사용하는 두 선언 방식의 차이:

선언 방식 외부 프로젝트에서 접근 가능 여부 전이성

api	O (전파됨)	전이됨
implementation	X (내부에서만 사용 가능)	전이되지 않음

• implementation: 현재 모듈 내부에서만 사용하는 라이브러리. 다른 프로젝트에서는 이 라이브러리에 접근할 수 없습니다.
• implementation: 현재 모듈뿐 아니라, 이 모듈을 참조하는 프로젝트에도 함께 전파되어 사용할 수 있습니다.
• 편하게 저는 implementation(private), implementation(public)으로 빗대어 이해했습니다.

따라서 다른 프로젝트에서도 사용해야 하는 라이브러리는 반드시 api로 선언해야 합니다.

 

TODO

신규로 생성한 프로젝트에서는 implementation으로 선언이 되어있었습니다.

이전 라이브러리 프로젝트를 확인해보니 api로 선언해보니 정상적으로 참조 할 수 있었다는 것을 확인하였습니다.
다만 gradle cache 기능 때문에 라이브러리를 변경해도 신규 라이브러리를 가져오지 않아서 어려움을 겪었습니니다.

 

https://curiouskidd.tistory.com/88

캐시를 지우는 방법을 정리한 블로그 글입니다.

---

java-library 플러그인의 필요성

api와 implementation의 구분은 java-library 플러그인이 적용된 경우에만 유효합니다. 해당 플러그인이 없으면 Gradle은 두 선언 방식의 차이를 무시합니다.

plugins {
    id("java-library")
}

• 이 플러그인이 있어야 Gradle이 .pom 파일에 전이 의존성을 정확히 기록할 수 있습니다.

---

Gradle 내부 동작

1. api로 선언된 라이브러리는
   • 현재 프로젝트의 컴파일 classpath + 런타임 classpath에 포함
   • 외부 프로젝트가 이 프로젝트를 참조할 때도 함께 전이됨
   • .pom 파일에도 <dependency>로 포함됨
2. implementation으로 선언된 라이브러리는
   • 현재 프로젝트의 컴파일 classpath + 런타임 classpath에 포함
   • 외부 프로젝트에는 포함되지 않음
   • .pom 파일에도 포함되지 않음

---

✅ Maven POM 파일에서 의존성 확인하기

Gradle에서 api로 선언한 라이브러리는 .pom 파일에 <dependency> 항목으로 포함되어야 합니다.

예시:

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.12.0</version>
    <scope>compile</scope>
</dependency>

• 만약 api로 선언했음에도 .pom 파일에 해당 항목이 없다면 java-library 플러그인이 누락되었거나, 배포 시점의 문제가 의심됩니다.

---

📝 체크리스트 요약

항목 확인할 내용

api 선언 여부	외부 프로젝트에서 해당 라이브러리를 사용할 수 있어야 함
java-library 플러그인 적용 여부	api/implementation 구분이 적용되는지 확인
.pom 파일 확인	Maven 저장소에서 직접 확인하거나, 로컬 캐시에서 .pom 파일 열기

---

이와 같은 Gradle 의존성 전파 문제는 내부 동작을 이해하고 적절한 선언과 플러그인 설정만 하면 쉽게 해결할 수 있습니다.