---
kind: CONCEPT
slug: three-assembly-paths
title: Spring 조립의 세 경로와 각각이 결정하는 것
topic: assembly-ownership
project: clean-architecture-backend-template
status: 게시 전
sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
rootTreeNode: concept:three-assembly-paths
evidenceCapturedOn: 2026-09-01
assets:
  - key: three-assembly-paths
    file: ../../../final/evidence/rendered/three-assembly-paths.svg
  - key: three-assembly-paths-diagram
    file: ../../../final/assets/diagrams/three-assembly-paths.svg
evidence:
  - ../../../final/evidence/raw/three-assembly-paths.txt
  - ../../../final/evidence/raw/tl-web-six-unowned-components.txt
source:
  - 원본 분석 절은 final/document.md#1-4, #7-1 · analysis/18 · analysis/14 §7.1 이다.
---

# Spring 조립의 세 경로와 각각이 결정하는 것

이 저장소의 빈은 컴포넌트 스캔, 자동설정 등록, 그리고 컨텍스트 이전 확장의 세 경로로 들어온다. 어떤 컴포넌트가 실제로 존재하는지는 그 셋 중 어느 것이 그것을 소유하는가로 정해진다.

## 관계

- **스캔에서 뺀 다섯 패키지의 컴포넌트 여섯을 두 자동설정 어느 쪽도 소유하지 않았다**
  경로가 바뀌는 지점에서 소유권이 끊긴 사례다.
- **넓은 스캔을 좁히자 여덟 컴포넌트에 아무것도 도달하지 않았다**
  같은 형태가 퍼시스턴스 리프에서 나타난 사례다.
- **@Bean이 있다는 것은 조립 증거가 아니다**
  이 개념을 확인 절차로 옮긴 규칙이다.

## 본문

<!-- body:start -->

이 저장소에서 빈이 컨텍스트에 들어오는 경로가 셋이고 각각 다른 질문에 답한다.

## 조립의 세 경로

:::evidence key="three-assembly-paths-diagram" alt="빈이 들어오는 경로에서 컴포넌트 스캔과 imports 와 spring.factories 세 갈래가 나온다" caption="조립의 세 경로" zoom="false"
:::

**컴포넌트 스캔**(`@ComponentScan` + `AUTO_CONFIGURED_PACKAGES` 제외 정규식) · **`.imports`**(8개 파일 / 13개 클래스가 전부) · **`spring.factories`**(EnvironmentPostProcessor 6 · SpringBootExceptionReporter · AutoConfigurationImportFilter · ApplicationListener).

## 세 경로가 각각 답하는 질문

:::evidence key="three-assembly-paths" alt="분석 문서 final/document.md 에서 이 기록의 근거 절을 그대로 잘라낸 18줄. 코드베이스를 측정한 것이 아니라 원본 판정이 무엇을 적었는지를 보여 준다." caption="final/document.md 발췌 — 18줄" zoom="true"
:::

## 조립 표면이 좁다

조립 결함을 판정할 때 세 경로를 다 읽어야 한다. main Java 4,614개 중 스테레오타입 보유가 206개(4.5%)뿐이다.

:::note

없음 — 세 경로의 내용을 전수 판독했다

:::

## 경로 1 — 컴포넌트 스캔

컴포지션 루트는 `@SpringBootApplication` 대신 `@SpringBootConfiguration` + `@EnableAutoConfiguration` + `@ComponentScan`을 직접 쓴다. javadoc이 이유를 적는다 — 스캔에 `excludeFilters`가 필요한데 그 애너테이션은 속성을 노출하지 않으므로, 스캔할 패키지를 대신 명시한다.

```java
@ComponentScan(
    basePackages = {
      "dev.caskeleton.bootstrap",
      "dev.caskeleton.adapter",
      "dev.caskeleton.application",
      "dev.caskeleton.domain",
      "dev.caskeleton.shared"
    },
    excludeFilters = {
      @ComponentScan.Filter(type = FilterType.CUSTOM, classes = TypeExcludeFilter.class),
      @ComponentScan.Filter(
          type = FilterType.CUSTOM,
          classes = AutoConfigurationExcludeFilter.class),
      @ComponentScan.Filter(
          type = FilterType.REGEX,
          pattern = CaSkeletonApplication.AUTO_CONFIGURED_PACKAGES)
    })
```

정규식은 13개 패키지 접두사를 제외한다. 클래스 목록이 아니라 접두사인 이유도 적혀 있다 — 선택적 능력에 새 설정이 추가됐을 때, 아무도 제외를 기억하지 못했다는 이유로 활성화되면 안 되기 때문이다.

## 경로 2 — 자동설정 등록

제외된 패키지는 `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`로 들어온다. 이 저장소에는 그런 파일이 8개 있다.

```text
adapter/inbound/graphql
adapter/inbound/web
adapter/outbound/cache-redis
adapter/outbound/messaging
adapter/outbound/persistence-mongo
app-bootstrap
grpc/grpc-spring-boot-starter
messaging/messaging-spring-boot-starter
```

여기에 관리 컨텍스트용 `ManagementContextConfiguration.imports`가 하나 더 있다. Fileserver admin 라우트가 공개 커넥터가 아니라 관리 평면에 실리는 것이 이 파일의 역할이다.

## 경로 3 — 컨텍스트가 생기기 전

`META-INF/spring.factories`는 컨텍스트가 존재하기 전에 동작하는 확장을 등록한다.

```text
org.springframework.boot.EnvironmentPostProcessor=\
dev.caskeleton.bootstrap.activation.MasterSwitchEnvironmentPostProcessor,\
dev.caskeleton.bootstrap.activation.RuntimeEnvironmentProfileValidator,\
dev.caskeleton.bootstrap.activation.CapabilityDependencyEnvironmentValidator,\
...

org.springframework.boot.autoconfigure.AutoConfigurationImportFilter=\
dev.caskeleton.bootstrap.autoconfigure.persistencejpa.JpaOffAutoConfigurationImportFilter
```

`AutoConfigurationImportFilter`가 특히 중요하다. 이것은 후보 집합 자체를 좁히므로, 프로젝트의 어떤 조건보다 먼저 동작한다. 프레임워크 자신의 자동설정을 후보에서 빼는 것이 그 일이다.

## 세 경로가 만드는 함정

| 상황 | 증상 |
|---|---|
| 스캔에서 뺐는데 자동설정이 소유하지 않음 | 컴포넌트가 아무 데도 없다. 기동은 성공한다 |
| 자동설정 파일에 없는데 이름만 AutoConfiguration | 등록되지 않는다. 능력 리포트는 있다고 말한다 |
| `@Import`로 들어오는 클래스에 빈 조건 | 파싱 시점 평가라 빈 정의가 아직 없다 |

:::warning

세 경로의 공통점은 실패가 조용하다는 것이다. Spring은 "등록되지 않은 컴포넌트"를 오류로 보지 않는다. 그것이 정상 동작이기 때문이다.

:::

## 확인 순서

어떤 컴포넌트가 실제로 존재하는지 물을 때는 순서가 있다.

1. 컴포지션 루트의 스캔 범위와 제외 정규식을 읽는다
2. 제외됐다면 `.imports` 파일에서 그 패키지의 소유자를 찾는다
3. 소유자가 있다면 그것이 `@Bean`이나 `@Import`로 대상을 실제로 만드는지 확인한다
4. 조건이 붙어 있다면 그 조건이 언제 평가되는지 확인한다

<!-- body:end -->