llm-wiki/raw/official-docs/gradle-java-library-api-vs-implementation.md

title, source_type, url, archive_url, related_branches, related_projects, tags, status, confidence, created, last_reviewed

title	source_type	url	archive_url	related_branches	related_projects	tags	status	confidence	created	last_reviewed
official-doc / Gradle Java Library Plugin — API vs Implementation Separation	official-doc	https://docs.gradle.org/current/userguide/java_library_plugin.html		feature-skeleton-package-blueprint-contract	ca-skeleton	official-doc ca-skeleton ci-cd gradle api-vs-implementation	raw	high	2026-05-28	2026-05-28

official-doc / Gradle Java Library Plugin — API vs Implementation Separation

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. Gradle 공식 User Guide의 Java Library Plugin 섹션. api vs implementation 구성(configuration) 분리 정책의 공식 근거. 검증된 요약은 /ingest 후 wiki/concepts/에 source-summary-template 형식으로 별도 작성. 원본은 raw에 영구 보관.

Parent / 활용 branch

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-skeleton-package-blueprint-contract	ca-tmpl 8개 Gradle 모듈에서 api vs implementation dependency 선언 정책의 공식 근거 — 어떤 module이 다른 module type을 공개 ABI로 노출하는지(api) vs 내부 구현에만 사용하는지(implementation)를 결정하는 기준

출처 / Source

• 원본 URL: https://docs.gradle.org/current/userguide/java_library_plugin.html
• 아카이브 URL: (미제공)
• 저자 / 조직: Gradle Inc. (공식 User Guide)
• 발행일: (현재 버전 유지 — "current" URL)
• 마지막 확인일: 2026-05-28

왜 저장했는지 / Why archived

ca-tmpl Clean Architecture 스켈레톤은 8개 Gradle 모듈(app-bootstrap, domain-core, application-core, adapter-web, adapter-persistence, adapter-outbound, shared-contract, sample-ticket)을 정의하고 있으나, 모듈 간 dependency 선언 시 api와 implementation 중 어느 것을 사용해야 하는지 정책이 미정이었다. 이 문서는 그 결정의 공식 Gradle 근거를 제공한다.

핵심 인용 / Key quotes (verbatim)

[§ API and implementation separation] "Dependencies appearing in the api configurations will be transitively exposed to consumers of the library, and as such will appear on the compile classpath of consumers."

[§ API and implementation separation] "Dependencies found in the implementation configuration will, on the other hand, not be exposed to consumers, and therefore not leak into the consumers' compile classpath."

[§ API and implementation separation] "Prefer the implementation configuration over api when possible"

[§ API and implementation separation / ABI definition] "An API dependency is one that contains at least one type that is exposed in the library binary interface, often referred to as its ABI (Application Binary Interface)."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
GRADLE-JAVALIB-C1	api configuration에 선언된 dependency는 라이브러리 소비자의 compile classpath에 전이적으로(transitively) 노출된다	"Dependencies appearing in the api configurations will be transitively exposed to consumers of the library, and as such will appear on the compile classpath of consumers."	official-vendor-doc	Gradle Java Library Plugin을 사용하는 모든 프로젝트	java plugin(non-library)의 동작, 런타임 classpath 동작
GRADLE-JAVALIB-C2	implementation configuration에 선언된 dependency는 소비자 compile classpath로 누출(leak)되지 않는다	"Dependencies found in the implementation configuration will, on the other hand, not be exposed to consumers, and therefore not leak into the consumers' compile classpath."	official-vendor-doc	Gradle Java Library Plugin을 사용하는 모든 프로젝트	runtime classpath에서의 동작, Spring Boot executable jar 패키징 동작
GRADLE-JAVALIB-C3	Gradle 공식 문서는 가능한 한 api 대신 implementation을 사용하도록 권고한다	"Prefer the implementation configuration over api when possible"	official-vendor-doc	Gradle Java Library Plugin을 사용하는 모든 프로젝트	언제 api가 반드시 필요한지에 대한 완전한 기준은 포함하지 않음
GRADLE-JAVALIB-C4	API dependency의 정의는 library binary interface(ABI)에 노출되는 type을 하나 이상 포함하는 dependency이다	"An API dependency is one that contains at least one type that is exposed in the library binary interface, often referred to as its ABI (Application Binary Interface)."	official-vendor-doc	Gradle Java Library Plugin의 api configuration 사용 판단	어떤 type이 ABI에 노출되는지의 상세 기준(superclass, public method parameter 등)은 이 단일 인용으로 완결되지 않음

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:

  • GRADLE-JAVALIB-C1: api 선언 시 소비자 compile classpath 전이적 노출 — multi-module 프로젝트에서 module A가 module B를 api로 선언하면 B의 dependency가 A의 소비자에게 전이됨
  • GRADLE-JAVALIB-C2: implementation 선언 시 소비자 compile classpath 비노출 — module 간 의도치 않은 transitive dependency 방지
  • GRADLE-JAVALIB-C3: implementation 우선 사용 권고 — 공식적인 기본 선택 지침
  • GRADLE-JAVALIB-C4: ABI 노출 여부가 api 사용의 판단 기준

• 이 자료가 증명하지 않는 것:

  • ca-tmpl 8개 모듈 각각에서 api를 써야 하는 구체적 경우 (예: domain-core의 type이 application-core의 public port에 노출되는지 여부) — 이는 ca-tmpl 자체 설계 결정
  • Spring Boot executable jar (bootJar) 환경에서 implementation의 런타임 포함 여부 — bootJar는 별도 규칙
  • testImplementation, runtimeOnly 등 다른 configuration의 동작

• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:

  • shared-contract를 application-core, adapter-*가 참조할 때 api로 선언해야 하는지 implementation으로 선언해도 되는지 — shared-contract의 type이 각 module의 public API에 노출되는지 여부로 결정
  • domain-core를 application-core가 참조할 때 api vs implementation — application-core의 port interface 반환 타입에 domain-core type이 포함되면 api 필요
  • multi-module에서 app-bootstrap이 모든 module을 implementation으로 선언 가능한지 — bootstrap은 소비자가 없으므로 implementation 사용이 일반적

메모 / Notes

• api vs implementation 정책은 module 간 의존 방향(Module Dependency Rule)과 별개의 결정이다. 의존 방향은 ArchUnit/Gradle dependency 규칙으로 강제하고, api vs implementation은 각 의존 선언 시 ABI 노출 여부로 판단한다.
• ca-tmpl 8개 모듈에서 가장 자주 api가 필요한 경우는 port interface의 파라미터/반환 타입에 다른 module의 type이 등장할 때이다 (미검증 추론 — Claims Extracted 아님).
• 추가로 봐야 할 동일 출처 페이지: Gradle User Guide의 "Java Library Plugin — The java-library plugin configurations" 섹션 (configuration hierarchy 전체), "Building Java projects with Gradle" 섹션.

Related / 관련

• 같은 주제 official-doc: raw/official-docs/supply-chain-gradle-vs-maven-dependency-locking — Gradle dependency locking 관련
• 이 자료를 활용할 wiki 요약: wiki/concepts/gradle-api-vs-implementation (생성 예정, /ingest 후)