refactor: 리펙토링 진행중 의존성 gradle은 얇게 유지, 각 모듈에서 처리하고 있는 부분에 대해서 리펙토링
This commit is contained in:
@@ -0,0 +1,272 @@
|
||||
# App Bootstrap Build Composition — implementation plan
|
||||
|
||||
Design authority: the 2026-09-23 "App Bootstrap Build Composition 설계 작업 문서".
|
||||
Review authority: `docs/reviews/2026-09-18-techlead-review/` §00, §12, §13 and
|
||||
`docs/reviews/2026-09-23-techlead-review-application-closure.md`.
|
||||
|
||||
This plan is the §17 deliverable. It settles the three decisions the design document deliberately
|
||||
left open — what "selection" *is* mechanically, where the contract is enforced, and what a
|
||||
composition module is allowed to be — and then splits the work into the task units §17 names. It
|
||||
does not restate the design.
|
||||
|
||||
## 0. Measured baseline
|
||||
|
||||
Re-measured on the current tree rather than quoted (design §15 forbids reusing an old log).
|
||||
|
||||
The design document's named gate is green:
|
||||
|
||||
./gradlew verifyCleanArchitectureDependencies :adapter:outbound:persistence-jpa:test \
|
||||
:app-bootstrap:test :app-bootstrap:architectureTest --continue # exit 0, 0 FAILED
|
||||
|
||||
`:app-bootstrap:runtimeClasspath` resolves **33 project edges**. Every optional capability is among
|
||||
them, including the three the earlier pass lowered to `runtimeOnly`:
|
||||
|
||||
graphql httpclient persistence-mongo <- runtimeOnly, still on the classpath
|
||||
fileserver notification cache-redis redis-runtime
|
||||
messaging-spring-boot-starter + 16 further messaging leaves
|
||||
|
||||
This is the design document's §2.3 claim, confirmed: `runtimeOnly` moved these off the *compile*
|
||||
classpath and left them in the artifact. Nothing about the shipped jar changed.
|
||||
|
||||
## 1. Decision — selection is a Gradle edge, and the repository already has one
|
||||
|
||||
The design document asks for a mechanism without naming one. It does not need a new one: **object
|
||||
storage is already in the target state**, and `docs/capability-status.md` already documents it that
|
||||
way — WIRED **no**, "The leaf is not an `app-bootstrap` dependency … A fork that wants it adds the
|
||||
edge", with `integrationTestImplementation project(':adapter:outbound:objectstorage')` supplying it
|
||||
to the lane that proves it assembles.
|
||||
|
||||
So the work is not to invent Build Composition. It is to move the other capabilities to the shape
|
||||
one capability already has.
|
||||
|
||||
**Selection = the presence of a project dependency in `app-bootstrap/build.gradle`.** Not a Gradle
|
||||
property, not a feature variant, not a capability DSL. Reasons, in the order design §9 ranks them:
|
||||
|
||||
- it is the existing Gradle model, and it is already how object storage works;
|
||||
- a property would make the shipped artifact depend on how the build was invoked, so two builds of
|
||||
the same commit could ship different jars — the opposite of what a composition contract is for;
|
||||
- the thing a fork edits is one line in one file, which is what a template should ask of an adopter.
|
||||
|
||||
Rejected alternative, recorded because it is the obvious one: `-PcaCapabilities=fileserver,...`. It
|
||||
reads well and it is worse — it moves the answer to "does this build ship Fileserver?" out of the
|
||||
repository and into the invocation, and no test can pin an invocation.
|
||||
|
||||
## 2. Decision — the contract is enforced by the verifier that already exists
|
||||
|
||||
Design §7.1 requires a RED test proving an unselected capability is absent from
|
||||
`runtimeClasspath`, and design §9 forbids adding a bespoke verifier for it.
|
||||
|
||||
Both are satisfiable at once. `ca.dependency-policy` already resolves a named configuration and
|
||||
fails on forbidden or missing coordinates (`dependencyPolicy { absent … required … }`,
|
||||
`VerifyDependencyPolicyTask`, wired into `check`). A project dependency resolves to a real
|
||||
`ModuleVersionIdentifier` — `dev.caskeleton:<project name>` — so an absence on `runtimeClasspath` is
|
||||
expressible today, with no new task, no new source set and no string scanning.
|
||||
|
||||
// app-bootstrap/build.gradle
|
||||
dependencyPolicy {
|
||||
absent 'dev.caskeleton:fileserver',
|
||||
'Fileserver is an optional capability; the minimal composition does not ship it.'
|
||||
}
|
||||
|
||||
That is the Phase 1 RED: it fails on the current tree, because the edge is there.
|
||||
|
||||
Two things this deliberately does **not** replace:
|
||||
|
||||
- the Runtime Activation tests. Design §3.1 is the whole point — `absent` answers "is it in the
|
||||
artifact", the existing OFF-state guards answer "is it assembled". Neither is evidence for the
|
||||
other, and the plan keeps them in different files so they cannot be confused.
|
||||
- the boot artifact evidence design §7.5 asks for. `runtimeClasspath` is what `bootJar` packages, so
|
||||
the two agree by construction — but "by construction" is an argument, not a measurement. One
|
||||
`bootJar` content assertion is added once, in Step 7, as a check *of the argument*, not per
|
||||
capability.
|
||||
|
||||
## 3. Decision — what a composition module may contain
|
||||
|
||||
A `composition:<capability>` module exists only when a capability genuinely spans adapters that must
|
||||
not depend on each other. It contains cross-adapter wiring and nothing else: no business rule, no
|
||||
transport surface, no settings that a single leaf could own. If a capability turns out to be
|
||||
self-contained after the leaf-ownership pass, **no composition module is created for it** — the leaf
|
||||
is selected directly, exactly as object storage is.
|
||||
|
||||
This matters because the fileserver work in the 2026-09-23 closure §3-B.5 already found that the
|
||||
package which looked like one cross-adapter assembly was two assemblies merged. The same question is
|
||||
asked before each composition module is created, not after.
|
||||
|
||||
Registry: each new module gets a `modules.json` entry with explicit `allowed_dependencies`.
|
||||
`settings.gradle` includes registered projects automatically, so registration *is* inclusion. A
|
||||
composition module is **not** a composition root: it composes a capability, it does not run.
|
||||
|
||||
## 4. Task units
|
||||
|
||||
Ordered. A unit is done when its own focused command is green; no unit starts before the previous
|
||||
one is.
|
||||
|
||||
| # | Unit | Done when |
|
||||
| --- | --- | --- |
|
||||
| 1 | Fileserver Build Composition RED test | `:app-bootstrap:verifyDependencyPolicy` fails naming `dev.caskeleton:fileserver`, and the failure text is the contract |
|
||||
| 2 | Fileserver composition extraction | the 4 cross-adapter configurations left in bootstrap by closure §3-B.5 move to `composition:fileserver`; bootstrap's fileserver edges are gone; unit 1 is green |
|
||||
| 3 | Fileserver ON/OFF regression | OFF-state and ON-state tests unchanged in meaning and green, from the source set that selects the composition |
|
||||
| 4 | Notification composition extraction | same shape, same three units collapsed into one because the pattern is proven |
|
||||
| 5 | Persistence/JPA ownership review | per-file verdict against design §11 Q1–Q4, recorded; only files that answer Q1 or Q2 move |
|
||||
| 6 | Messaging / Redis residual ownership | broker selection becomes a build edge; Redis keeps only the two application-wide files closure §3-B.5 already justified |
|
||||
| 7 | Mongo / HTTP client / GraphQL actual optionalization | `runtimeOnly` → absent; one `bootJar` assertion proves the classpath argument |
|
||||
| 8 | Minimal + full composition certification | minimal = `:app-bootstrap` main; full = the app-bootstrap `systemTest` source set selecting every capability. No new application module unless a source set proves insufficient |
|
||||
| 9 | Registry / docs / comment alignment | `modules.json`, `capability-status.md` WIRED column, and the "shipped so an operator can enable it" comments in `app-bootstrap/build.gradle` all say the same thing |
|
||||
| 10 | Focused → repository-wide gates | design §15 command, then `ci`, dependency locks, public-path snapshot, optional-platforms |
|
||||
|
||||
Unit 8 uses a source set rather than a new module because `app-bootstrap:integrationTest` already
|
||||
does exactly this for object storage. Design §6.2 warns against forcing `sample-portfolio` to carry
|
||||
every capability, and this avoids it without adding a module.
|
||||
|
||||
## 5. What this plan does not do
|
||||
|
||||
Taken from design §10, repeated here because a plan that omits them invites them:
|
||||
|
||||
- no mechanical removal of every `dev.caskeleton.adapter.*` import; ownership is argued per file
|
||||
- no new platform layer, no new build DSL, no per-capability verifier
|
||||
- no change to provider behaviour, no feature work, no unrelated test cleanup
|
||||
- no staging, commit or push — repository policy is `human-only`
|
||||
- no working-tree cleanup; the tree carries 36 tracked deletions and 54 untracked additions from the
|
||||
previous pass, and closure §5 records how they must be committed
|
||||
|
||||
## 6. Regression guard
|
||||
|
||||
Design §14's list is the non-negotiable set. Each unit's focused command includes whichever of these
|
||||
it can break:
|
||||
|
||||
JPA boundary gate :adapter:outbound:persistence-jpa:test
|
||||
Redis composition unit isolation :adapter:outbound:cache-redis:test
|
||||
app-bootstrap architecture test :app-bootstrap:architectureTest
|
||||
runtime activation OFF guards :app-bootstrap:test, :app-bootstrap:systemTest
|
||||
configuration cache ci/integrationCheck/releaseCheck --dry-run --configuration-cache
|
||||
gRPC operation-ledger CI caller -p optional-platforms integrationCheck
|
||||
|
||||
Leaf ownership already moved for Redis and Fileserver (closure §3-B.5) is a floor, not a starting
|
||||
point: this work extends it and must not walk it back.
|
||||
|
||||
## 7. Progress — units 1 and 2
|
||||
|
||||
### Unit 1 is done
|
||||
|
||||
`app-bootstrap/build.gradle` declares the contract as a `dependencyPolicy` absence on
|
||||
`runtimeClasspath`. It was checked for vacuity before it was trusted: a temporary `required` on the
|
||||
same coordinate passed, which is what proves `dev.caskeleton:fileserver` is the shape a project
|
||||
dependency actually resolves to. Without that probe an `absent` rule with a misspelled coordinate
|
||||
would have been green from the first day and meant nothing.
|
||||
|
||||
### Unit 2 is done except for one measured blocker
|
||||
|
||||
Moved, in this order, because each step unblocked the next:
|
||||
|
||||
1. **`RuntimeProfileSnapshot` → `adapter:outbound:support`.** It was the real coupling. A capability
|
||||
configuration that has a production-only rule had to ask app-bootstrap what the profile was, so
|
||||
the configuration could not leave app-bootstrap. BOOT-002 said "one composition-root owner"; it
|
||||
now says one owner for the repository, which is strictly stronger and is what lets a composition
|
||||
module ask the question at all.
|
||||
2. **`composition:fileserver-platform` created and registered.** Named for the capability rather
|
||||
than the directory: `:composition:fileserver` resolves to `dev.caskeleton:fileserver`, the same
|
||||
coordinate as `adapter:outbound:fileserver`, and Gradle silently substituted the module for
|
||||
itself. The messaging family already prefixes its leaves for this reason.
|
||||
3. **The 13 cross-adapter configurations moved**, with the auto-configuration and management-context
|
||||
registration files that name them. `StartupFailures` became
|
||||
`CapabilityStartupValidationException`, the same seam the Redis and Fileserver leaf moves used.
|
||||
4. **app-bootstrap's fileserver edges removed**; the lanes that verify the capability select it.
|
||||
5. **BOOT-007 moved to the module it governs**, with `allowEmptyShould(false)`. Left where it was it
|
||||
would have analysed an empty package and passed for having nothing to check — and BOOT-012 caught
|
||||
the rule leaving the pinned set, which is that guard working rather than an obstacle.
|
||||
|
||||
Result: `adapter:outbound:fileserver` is off the minimal runtime classpath. Project edges on
|
||||
`:app-bootstrap:runtimeClasspath` went from 33 to 32.
|
||||
|
||||
**The blocker, measured rather than estimated.** `application-fileserver` is still there, and not
|
||||
through the composition. It arrives through three leaves every application needs, because the
|
||||
capability's code is inside them:
|
||||
|
||||
| leaf | fileserver files |
|
||||
| --- | --- |
|
||||
| `adapter:inbound:web` (`web.fileserver.*`) | 62 |
|
||||
| `adapter:outbound:persistence-jpa` (`persistence.fileserver.*`) | 25 |
|
||||
| `adapter:outbound:identifier` | 1 |
|
||||
|
||||
So Fileserver was never only "assembled by the composition root". It is embedded in required leaves,
|
||||
and no composition module can express selecting it out until those 88 files move to leaves of their
|
||||
own. The coupling was measured and is one-directional and small — `web.fileserver` reaches
|
||||
`web.{core, observability, auth}` nine times, and exactly one non-fileserver web class
|
||||
(`WebModuleBoundary`) reaches back — so the split is tractable. It is unit 2b, and it is the next
|
||||
thing to do.
|
||||
|
||||
The contract line stays RED. Softening it to make the gate green would record the opposite of what
|
||||
was measured, and design §7.1 asks for this test to be RED before the structure changes, not after
|
||||
it is convenient.
|
||||
|
||||
### Verification at this point
|
||||
|
||||
./gradlew verifyCleanArchitectureDependencies :adapter:outbound:persistence-jpa:test \
|
||||
:app-bootstrap:test :app-bootstrap:architectureTest \
|
||||
:composition:fileserver-platform:check :adapter:outbound:support:test --continue # green
|
||||
|
||||
./gradlew ci --continue # 1,276 tasks, exactly one failure:
|
||||
# :app-bootstrap:verifyDependencyPolicy, the intended RED
|
||||
|
||||
One failing task out of 1,276, and it is the one this unit deliberately left failing. Nothing else
|
||||
in the repository regressed.
|
||||
|
||||
## 8. Unit 2 is complete — the Fileserver vertical slice
|
||||
|
||||
The blocker recorded above was right about the cause and wrong about the size. `application-fileserver`
|
||||
arrived through three required leaves, and all three turned out to be clean extractions:
|
||||
|
||||
| Extracted | Into | Why it was clean |
|
||||
| --- | --- | --- |
|
||||
| 1 file — the upload identifier factory | `adapter:outbound:fileserver` | It implements one Fileserver port and nothing else. One class is why every application that needed an identifier also resolved the Fileserver use cases. |
|
||||
| 25 files + 4 migrations | `adapter:outbound:persistence-fileserver` (new leaf) | The package imported `application.fileserver`, JPA, Hibernate, Spring Data and JDBC — and not one type from any other `persistence.*` package. No seam was needed. |
|
||||
| 62 files | `adapter:inbound:web-fileserver` (new leaf) | `web.fileserver` imports `web.{core, auth, observability}` nine times; exactly one non-fileserver class referenced it back, and only in a javadoc sentence. |
|
||||
|
||||
The web platform's module map did **not** move. `WebStableModule` still declares the twelve fileserver
|
||||
modules and their edges, and `WebBuildModel.platformSourceRoots()` now returns two roots — which is
|
||||
what that method's plural has meant since it was written. A second copy of the map in the second leaf
|
||||
would have been a second answer to "is this edge declared", and the map is the one thing a platform
|
||||
must not have two of.
|
||||
|
||||
Result: `:app-bootstrap:runtimeClasspath` went from **33 project edges to 31**, and the contract now
|
||||
names the whole capability rather than the part that was easy to remove:
|
||||
|
||||
absent 'dev.caskeleton:fileserver'
|
||||
absent 'dev.caskeleton:application-fileserver'
|
||||
absent 'dev.caskeleton:web-fileserver'
|
||||
absent 'dev.caskeleton:persistence-fileserver'
|
||||
|
||||
### What the repository's own guards caught
|
||||
|
||||
Every move was stopped first by a guard already in the tree, and every one was the same shape — a
|
||||
rule still pointing at something that had moved:
|
||||
|
||||
- `JpaModuleBoundaryTest`: *"a rule about a package that does not exist passes by finding nothing"*
|
||||
- `ArchRuleDiscoveryContractTest` (BOOT-012): a rule leaving the pinned set is a decision, not a deletion
|
||||
- `verifyJpaApiSurface` / `verifyJpaAdopterApiSurface`: surface change promoted to a review decision
|
||||
- `PersistenceEntityScanCoverageTest`: an opt-in package that is no longer opt-in because it is no longer here
|
||||
|
||||
`verifyJpaAdopterApiSurface` was **not** widened by allowlist (design §28). Its scan excludes the
|
||||
directory that *owns* the implementation; there are two such leaves now, so the exclusion was
|
||||
corrected, and the baseline file still governs every other module's imports.
|
||||
|
||||
### One regression this introduced and then removed
|
||||
|
||||
The new web leaf first declared `spring-boot-starter-webflux`. The web leaf's own build file says in
|
||||
a comment why it declares `spring-webflux` instead: the starter puts reactor-netty — a second
|
||||
embedded server — on the runtime classpath of an application that already has Tomcat. The new leaf
|
||||
now matches, and the lock files record the difference.
|
||||
|
||||
### Verification
|
||||
|
||||
./gradlew ci verifyDependencyLocks --continue # exit 0, 0 FAILED
|
||||
|
||||
Repository-wide, everything green, including `:app-bootstrap:verifyDependencyPolicy` — the RED that
|
||||
opened this unit.
|
||||
|
||||
### Next
|
||||
|
||||
Unit 4, the Notification composition. Unit 3's ON/OFF regressions are covered by the tests that moved
|
||||
with the code (`FileserverRuntimeAssemblyTest`, `FileserverPlatformAutoConfigurationTest` in the
|
||||
composition module, `FileserverCompositionIntegrationTest` in app-bootstrap's integration lane) and
|
||||
all are green in the run above.
|
||||
Reference in New Issue
Block a user