init: llm-wiki-haness 하네스 설계
This commit is contained in:
DongHyeonka
@@ -0,0 +1,85 @@
|
||||
---
|
||||
title: "official-doc / Gradle Java Library Plugin — API vs Implementation Separation"
|
||||
source_type: official-doc
|
||||
url: https://docs.gradle.org/current/userguide/java_library_plugin.html
|
||||
archive_url:
|
||||
related_branches: [feature-skeleton-package-blueprint-contract]
|
||||
related_projects: [ca-skeleton]
|
||||
tags: [official-doc, ca-skeleton, ci-cd, gradle, api-vs-implementation]
|
||||
status: raw
|
||||
confidence: high
|
||||
created: 2026-05-28
|
||||
last_reviewed: 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` 후)
|
||||
Reference in New Issue
Block a user