donghyeon.kang/clean-architecture-backend-template

Files

T

DongHyeonkaandClaude Opus 5 9bc2e75fe5 refactor(build,ci): CI를 단계별로 재편하고 감사 잔여 114건 정리

빌드·CI 레이어 전수 감사(133건) 중 Track A 에서 처리한 E등급 19건을 뺀
나머지를 마무리한다. 한 커밋인 이유는 서로 얽혀 있기 때문이다 — 워크플로가
`checkstyleMain` 을 부르려면 루트가 먼저 Checkstyle 을 붙여야 하고, 모듈 43개가
convention 을 적용하려면 build-logic 이 먼저 그 플러그인을 등록해야 한다.
영역별로 쪼개면 중간 커밋이 빌드되지 않는다.

## CI 단계 분리 (워크플로 29파일 3,360줄 → 19파일 2,692줄, 잡 69 → 64)

모듈이 아니라 단계로 자른다. 기존 28개는 `web-*` `jpa-*` 처럼 모듈로 갈려
있어서 같은 일이 파일마다 중복됐다.

- stage 1 `ci-quality-gates.yml` + `pr-adapters.yml`(신규, 잡 단위 경로 필터) — pull_request
- stage 2 `integration-main.yml`(신규) — push:main + 03:00. 문서 게이트는 여기에 둔다
- stage 3 `release.yml`(신규, 릴리스 워크플로 7개 중 5개 흡수) — push: tags v*

setup 블록 59회 복붙 → `.github/actions/setup-gradle-java` 1개(잡당 13줄 → 5줄).
잡 8개 삭제, 각각 대체 잡을 확인했다. `verifyCleanArchitectureDependencies` 실행
횟수가 태그당 9 → 6, PR당 8 → 4 로 줄었다.

## 컨테이너 릴리스 신설

이미지를 만드는 것이 아무것도 없었다. Dockerfile 은 있었지만
build-push-action / bootBuildImage / jib 사용처가 0건이고, `*-release.yml` 8개는
테스트 후 아티팩트만 올렸다 — 이름만 릴리스였다.

Boot 레이어드 추출 + thin-JAR 엔트리포인트로 Dockerfile 을 고치고 릴리스
워크플로에 이미지 빌드·푸시·SBOM·스캔을 넣었다. 로컬 빌드로 검증했다:
레지스트리 content 241MB, 기동 3.7초, uid 1000, 헬스체크 200.
코드만 바뀐 릴리스는 7.68MB 만 재푸시한다(이전이라면 156MB).
CI 는 배포하지 않는다 — 매니페스트와 ArgoCD 는 별도 repo 로 간다.

## 게이트 정리

- gate-matrix 의 개수 고정 해제: `EXPECTED_GATE_COUNT=49` 와 하드코딩된 49개 id
목록을 지우고 불변식으로 대체(필드·enum, 워크플로/잡 실재, id 중복,
`release_blocking: true` 는 실제로 release-gate 의 needs 여야 함).
행을 추가하려면 테스트부터 고쳐야 하던 구조를 풀었다. 커버리지 8/28 → 28/28
- 문서 게이트 4개를 `check` 에서 떼어 `verifyDocumentationContracts` 로 묶고
stage 2 에 배치. 어겨도 런타임은 멀쩡하므로 개발을 막지 않는다
- `verifyOneTypePerFile`(정규식 Java 파싱, 126파일 미탐) → Checkstyle
`OneTopLevelClass` + `OuterTypeFilename`. main 위반 0건, test 의 fixture 29건은
정책을 넓히지 않고 suppressions 에 사유와 함께 명시 제외
- leaf 하나의 `check` 가 끌고 오던 저장소 전역 게이트 18개를 재배치.
`:domain-core:check` 가 13 태스크 11초로 끝난다
- convention 플러그인 2개 신설(`ca.platform-module`, `ca.grpc-platform-module`),
플랫폼 모듈 43개에 적용. 손수 짠 Test 태스크 17개를 `strictTestLanes` 로 전환
(태스크 이름 전부 보존 — CI 가 이름으로 부른다)
- `ca.api-surface` 의 정규식 Java 파서를 javac parse-only 로 교체
(기존 베이스라인 3개와 바이트 동일 확인)
- 죽은 태스크 5개 삭제, `src/gradle` 1,713 → 1,440줄, 모듈 build.gradle
3,072 → 2,977줄

## 검사가 검사를 못 하고 있던 것들

- 11개 계약 테스트가 gitignore 된 `src/.env` 를 요구했다. `.gitignore` 자신이
"examples beside it are the tracked contract, never a real one" 이라고 적어둔
규칙과 어긋난다. 깨끗한 체크아웃에는 그 파일이 없으므로 CI 에서 돌 수 없었다.
추적되는 `.env.example` 로 돌린다
- **`.env.local.example` 이 5432 를 가리키는데 compose 는 5433 을 게시한다.**
이 파일을 복사해 시작하는 신규 개발자는 DB 연결에 실패한다. 이걸 잡으라고
만든 테스트가 추적 안 되는 파일을 읽어서, 이미 설정이 끝난 머신에서만 돌고
정작 처음 받는 사람에겐 아무 검사도 안 하고 있었다. 포트를 고치고 테스트를
추적 파일로 돌렸다
- `MongoModuleBoundaryTest` 의 `DO_NOT_INCLUDE_JARS` 때문에 임포트가 0개가 되어
규칙 10개가 "failed to check any classes" 로 실패 중이었다. 이 레인에서는
모듈 자기 클래스가 jar 로 올라온다. `importPackages(ROOT)` 가 이미 서드파티를
거르므로 옵션은 불필요했다
- `ReleaseManifestTaskExistenceTest` 가 build 파일 텍스트에서 `tasks.register(`
만 찾아, convention 의 `lane('...')` 로 바뀐 태스크를 미등록으로 오판했다
- `ProfileSeparationContractTest` 는 런처가 주입하는 `src/.env` 가 맞는 대상이라
그대로 두되, 파일이 없으면 명시적으로 skip 한다 — "안 돌았다" 가 "통과했다"
로 읽히지 않게

## 검증 (전부 깨끗한 체크아웃에서, 커밋 전에 실행)

`verify-gradle-wrapper.sh` PASS · `verify-gate-matrix.sh` OK(drift 0) ·
워크플로 YAML 전수 파싱 OK · actionlint 지적 0 · `gradlew help` ·
`verifyCleanArchitectureDependencies` · `build-logic test` ·
`:app-bootstrap:test` **1001 tests 실패 0 스킵 5** · `:domain-core:check` ·
`verifyDocumentationContracts`.

## 남은 문제

- 첫 `v*` 태그는 이미지 취약점 스캔에서 실패한다(CRITICAL/HIGH 9건:
ubuntu 베이스 2, tomcat-embed-core 3, amqp-client 3, httpcore5 2).
억제를 넣지 않았다 — 릴리스 1회차를 초록으로 만들려고 임계값을 내리면
게이트가 장식이 된다. 의존성·베이스 갱신이 선행돼야 한다
- `fileserver-v*` / `web-v*` / `websocket-v*` 태그는 이제 아무 run 도 만들지
않는다(배포 단위가 하나라는 결정에 따른 것)
- main push 마다 무거운 레인 3개가 새로 돈다 — 러너 분이 늘어난다
- `ProfileSeparationContractTest` 가 찾아낸 4개 값(cache command-timeout,
cache positive-soft-ttl, idempotency provider, rate-limit command-timeout)이
`.env.example` 과 인라인 기본값 사이에서 갈린다. 런타임 설정 판단이라
건드리지 않았다

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-09-16 18:27:15 +09:00

4.9 KiB

Raw Permalink Blame History

build-logic

The included build that holds this repository's Gradle conventions. A convention lives here when the same machine code was otherwise copied into more than one place, and the copies could drift apart without any check noticing.

What is here

Plugin	Owns
`ca.architecture-registry` (settings)	project inclusion, directory mapping, and the parsed registry every other reader shares
`ca.strict-test-lane`	tagged / named / own-source-set Test lanes that cannot pass without executing something
`ca.strict-qualification`	qualification lanes that cannot pass without executing every named class, re-checked against the JUnit XML
`ca.evidence`	the JUnit XML reader and the no-skip / required-class rules built on it
`ca.api-surface`	read-only API surface verification with an explicit, separate update task
`ca.dependency-policy`	declared absences, checked against the resolved graph rather than against a comment
`ca.runtime-membership`	the resolved runtime project closure against the registry's memberships
`ca.platform-module`	what a vendored platform leaf (`messaging:`, `grpc:`, `grpc-advanced:*`) is: `java-library`
`ca.grpc-platform-module`	`ca.platform-module` plus the module-scope `io.grpc:grpc-bom` import, for the leaves that already had it

ca.testkit-publisher was here and is not any more: every leaf with a testkit source set moved to Gradle's own java-test-fixtures (ADR-BUILD-001).

Plain classes rather than plugins, because settings and projects load plugins through different mechanisms and more than one caller needs each:

Class	Owns
`dev.caskeleton.buildlogic.ModuleRegistry`	reading and validating `config/architecture/modules.json`, including which runtime compositions exist
`dev.caskeleton.buildlogic.JUnitEvidence`	one JUnit XML reader, with DOCTYPE processing off and no defaulting of absent counts
`dev.caskeleton.buildlogic.RequiredTestExecution`	the single decision "a test this build names must actually have run", asked by `ca.strict-test-lane` and by `ca.evidence`
`dev.caskeleton.buildlogic.JavaPublicTypes`	public top-level types, parsed by javac rather than matched with a regular expression

What the design named and this build does not have

The remediation design's §10.2 listed eight conventions. Two of them were attempted or assessed and deliberately not built, and the reasons belong next to the code rather than in a review thread.

`ca.java-leaf` — reverted

Written, measured, reverted. The full reasoning is in src/build.gradle beside the static-analysis block it would have moved. In short: a recorded decision (feature-static-analysis-quality-contract D8) already put that baseline in the root subprojects {} block; the block is applied once and copied nowhere, so extracting it removes no duplication; and build-logic would have to re-declare the spotless / spotbugs / errorprone / dependency-management coordinates and their versions, which creates a drift surface where there was none.

A content-level baseline of the resolved analysis configuration — compiler args, encoding, release, Checkstyle tool version and config, SpotBugs effort and report level, for every source set of every project — was captured before the attempt and compared after the revert, because the task graph cannot see a weakened Error Prone flag: the task names are identical either way. The two dumps are identical.

`ca.optional-adapter` — not warranted

Its stated responsibility was "activation metadata and disabled/on composition contract wiring". Neither half is build machine code in this repository:

Activation metadata is one registry, docs/registries/env-keys.yaml, verified by one root task, verifyEnvKeys. There is no per-leaf copy for a convention to deduplicate.
The off invariant and the on fail-closed contract are ordinary tests over the shared test source set, gated by the master switch in @ConditionalOnProperty at runtime. They need no source set, no configuration, and no task of their own.

A plugin here would have to invent state to hold — an optionalAdapter { switch = '...' } block that no build step reads — and a declaration nothing checks is worse than no declaration, because it reads like a guarantee.

Testing a convention

cd src
./gradlew -p build-logic test --console=plain

The lane and registry conventions are covered by Gradle TestKit against real builds rather than by reading the plugin source, because the properties that matter — a lane that discovers nothing fails, a lane never reports up-to-date, a malformed registry is refused before any project is included — are runtime behaviour rather than text in a script. Two of those tests exist because the obvious reading of the Gradle documentation was wrong: failOnNoDiscoveredTests does not fire when a tag filter matches nothing, and failOnNoMatchingTests does not fire when only some of the named tests are missing.

4.9 KiB Raw Permalink Blame History