Files
clean-architecture-backend-…/gradle
DongHyeonka cbfa776270 build!: 시험 classpath·이미지 고정·카탈로그·API surface 입력을 정본대로 맞춘다
문제:
- ca.spring-library가 모든 spring leaf(30)의 testImplementation에
  spring-boot-starter-webmvc-test를 넣어, MockMvc를 쓰지 않는 23 leaf가 Tomcat을
  시험 classpath에 resolve하고 lock했다.
- container-images.properties 머리말은 「digest로 고정」이라는데 postgres-17·18이
  tag만이었다. 머리말은 「쓰는 lane만 다시 돈다」고 했지만 파일 전체가 모든 Test
  task의 입력이라 이미지 하나만 바꿔도 모든 lane이 다시 돈다. postgres-16-4는
  아무도 읽지 않았다.
- libs.versions.toml에 아무도 읽지 않는 칸이 있었다(라이브러리 9, 버전 4,
  루트에 적용하지 않는 플러그인 4).
- config/spotbugs/exclude.xml에 없는 클래스의 항목이 있었다(exclude-test.xml에
  이미 있다).
- notification의 API surface가 상대 경로로 application-notification 소스를
  가리켰고, ApiSurface 플러그인은 없는 추가 root를 말없이 건너뛰어 승인 update가
  줄어든 표면을 기록할 수 있었다.
- verify-mongodb-platform.sh가 고르는 클래스가 없는 :app-bootstrap:test
  --tests '*CleanArchitectureTest'를 불러 늘 실패했고, 이미지 기록이 카탈로그와
  다른 tag였다.

고친 것:
- 규약은 spring-boot-starter-test만 준다. 시험이 실제로 쓰는 것을 leaf가 직접
  선언한다. MockMvc를 쓰는 web·web-advanced·web-fileserver·web-notification·
  app-bootstrap은 webmvc-test starter, graphql은 TestRestTemplate의
  spring-boot-resttestclient, durable-operation은 WebApplicationContextRunner의
  spring-web, 시험이 JSON을 읽는 objectstorage·persistence-jpa·persistence-mongo·
  notification-platform은 jackson-databind, redis-runtime은 jackson-annotations
  (compileOnly, 본 코드와 같은 이유)다. 모든 Java source set을 한 빌드에서 컴파일해
  빠진 곳이 없음을 확인하고 lockfile을 다시 만들었다(Tomcat·webmvc 시험 자동설정이
  빠짐). graphql·persistence-mongo AGENTS의 허용·시험 목록을 같이 고쳤다.
- postgres 17·18을 desktop runner에서 받은 digest로 고정했다(17.11, 18.6). 목록을
  읽을 때 digest 없는 값을 GradleException으로 거절한다(ContainerImageCatalogTest).
  머리말을 실제 캐시 동작으로 고쳤고 postgres-16-4를 지웠다. persistence-jpa
  release registry의 PostgreSQL tag는 아무도 읽지 않아 지우고, 이미지는 카탈로그가
  정한다고 적었다.
- 카탈로그의 미사용 칸을 지우고 머리말을 지금 쓰임에 맞췄다.
- 죽은 spotbugs 항목을 지웠다.
- notification은 project(':application-notification')로 root를 잡고, 없는 추가
  root는 설정 단계에서 실패한다(ApiSurfaceConventionTest).
- mongo 스크립트는 :app-bootstrap:architectureTest를 부르고, 이미지 기록은
  카탈로그 mongo-8 값을 읽는다.
- graphql build.gradle에 앞 커밋의 document-contract lane을 함께 둔다. 저장소 루트
  (ca.repository.root)와 읽는 registry 파일은 그 lane만 받고, 시험은 그 속성으로만
  루트를 읽는다(cwd에서 거슬러 찾지 않는다).
버린 대안: 이미지마다 쓰는 lane을 선언해 입력을 나누기 — lane 수십 개에 키
목록을 다시 적어야 하고 빠뜨리면 캐시가 거짓 통과한다.

검증: 아래 PR 본문(desktop resolveAndLockAll·build-logic test·모든 source set 컴파일·
leaf check).

BREAKING CHANGE: ca.spring-library가 시험 classpath에 spring-boot-starter-webmvc-test를
넣지 않는다. MockMvc·TestRestTemplate·Jackson을 그 starter로 받던 파생 leaf는 의존을
직접 선언해야 시험이 컴파일된다. 카탈로그의 digest 없는 이미지와 없는 API surface 추가
root는 설정 단계에서 실패한다. version catalog의 미사용 칸을 지웠다. 할 일은
docs/upgrade/2026-11-round9-build.md다.

Refs: RR9-04-06, RR9-04-11, RR9-04-12, RR9-04-13, RR9-04-14, RR9-04-15, RR9-04-16
2026-11-13 06:34:32 +09:00
..

gradle/ — 빌드가 고정하는 것

이 폴더에는 빌드가 버전과 목록을 고정하는 파일만 둔다. Gradle 루트(저장소 루트)의 표준 자리다.

파일 고정하는 것 읽는 곳
wrapper/ Gradle 버전과 배포본 해시 gradlew
libs.versions.toml 프로젝트 밖 의존: 라이브러리·플러그인 버전 Gradle 버전 카탈로그(libs.*), build-logic/settings.gradle
modules.json 프로젝트 안 의존: leaf 목록(id, Gradle 경로, 폴더)과 허용 edge settings 플러그인 ca.architecture-registry, 방향 검사, scripts/ 검사
container-images.properties 시험이 띄우는 컨테이너 이미지(digest 고정) ca.java-conventions가 시험 JVM에 ca.test.image.*로 넘긴다

registry와 이미지 목록은 버전 카탈로그와 같은 종류라 여기에 둔다: 카탈로그가 밖에서 받는 것을, registry가 안에서 서로 쓰는 것을, 이미지 목록이 시험이 띄우는 것을 고정한다. config/는 코드 검사 도구 설정(checkstyle, spotbugs)만 둔다.

이력: 2026-11-11 저장소 재배치 전에는 registry가 src/config/architecture/, 이미지 목록이 src/config/testing/에 있었다(docs/upgrade/2026-11-relayout.md).

아키텍처 모듈 registry(modules.json)

Gradle 경로와 폴더는 다르다. :app-bootstrap은 src/bootstrap/app, :application-core는 src/application/core, :composition:outbox-relay는 src/bootstrap/outbox-relay에 있다. 폴더를 찾을 때는 source_path를, 명령을 쓸 때는 gradle_path를 읽는다.

modules.json은 Gradle 프로젝트의 정체(id, Gradle 경로, 소스 경로)와 각 leaf가 볼 수 있는 운영 프로젝트 edge를 정확히 적는다. 빈 allowed_dependencies 목록에도 뜻이 있다: 그 leaf가 일부러 다른 프로젝트에 기대지 않는다는 뜻이지, registry 항목을 덜 채웠다는 뜻이 아니다.

domain-core, shared-contract가 그 예다. 빈 목록은 분명한 경계이고, 실제 프로젝트 edge를 들여와 리뷰하기 전까지 비어 있어야 한다. 반대로 목록에 적힌 edge는 빌드가 실제로 쓰는 것과 맞아야 한다. 예를 들어 adapter-outbound-persistence-mongo의 목록은 ["application-core", "shared-contract"]이고 MongoRegistryPermissionParityTest가 두 방향을 모두 본다.

런타임 조립 구성원은 빌드 로직이 해석된 runtime classpath에서 얻는다. 이 registry에 모듈마다 칸으로 다시 적지 않는다.

별도 repo 라이브러리: library_groups와 allowed_libraries

소유자가 다른 repo에서 배포하는 라이브러리(메시징 dev.cakit.messaging, gRPC dev.cakit.grpc)는 이 빌드의 프로젝트가 아니라 외부 좌표다. 그래서 프로젝트 edge 규칙(allowed_dependencies)이 보지 못한다. 그 빈자리를 두 칸이 메운다(설계 design-docs repo-structure/05-library-repos.md 10.2절 T2, 소유자 승인 2026-11-07).

  • 맨 위 library_groups: 다스릴 라이브러리의 Maven group 접두사. 지금 ["dev.cakit"]이다. 이 접두사와 같거나 그 아래(dev.cakit. 다음) group만 다스린다. 다른 group(Spring, Kafka client 등)은 이 칸과 상관없다.
  • 행마다 선택 칸 allowed_libraries: 그 leaf가 쓸 수 있는 라이브러리 모듈의 group:artifact 목록. 없으면 빈 목록과 같다. 값은 library_groups 안의 group이어야 하고 겹치면 안 된다(registry를 읽을 때 거절).
  • 방향 검사(verifyModuleDependencyDirection, verifyCleanArchitectureDependencies 아래)는 프로젝트 edge와 같은 방식으로 대조한다: 운영 선언(api·implementation·compileOnly·runtimeOnly)의 소유 group 좌표와, compileClasspath에서 보이는 소유 group 모듈(라이브러리 모듈이 api로 내보낸 것 포함)이 모두 칸에 있어야 한다. 시험 구성은 보지 않는다.
  • 그래서 지금 지키는 약속 셋이 검사로 남는다: bridge(adapter-outbound-messaging)는 messaging-core-api만 본다. Kafka capability(adapter-outbound-messaging-kafka)는 starter-kafka를 runtimeOnly로만 싣는다. 계층 leaf는 칸이 비어 있으니 라이브러리를 쓸 수 없다.