refactor: 문서 개선 중

2026-09-21 14:30:55 +09:00
parent c93cdea150
commit 805a18f486
1497 changed files with 525837 additions and 59152 deletions
@@ -20,7 +20,7 @@ verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지

 ## 규칙

-1. 애너테이션은 후보를 만들 뿐이다
+1. 애너테이션은 빈 후보만 등록한다
   Component 나 Repository 나 Bean 은 이 클래스가 빈이 될 수 있다는 뜻이지 빈이라는 뜻이 아니다. 스캔 범위 밖이거나 조건이 거짓이거나 소유자가 없으면 후보로 끝난다.

 2. 이름은 아무것도 보장하지 않는다
@@ -32,8 +32,8 @@ verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지
 4. 확인은 도달 경로로 한다
   세 경로 중 어느 것이 이 클래스를 소유하는지 묻는다. 스캔이면 범위와 제외를, 자동설정이면 imports 파일과 조건을, 명시 조립이면 그 생성 지점을 확인한다.

-5. main 참조 0 은 강한 신호다
-   프로덕션 소스에서 그 타입을 참조하는 파일이 자기 자신뿐이면, 테스트만 그것을 쓴다는 뜻이다.
+5. searched direct reference 0부터 확인하되 거기서 멈추지 않는다
+   프로덕션 소스의 직접 참조 검색에서 선언 자신 외의 사용처를 찾지 못했다는 뜻까지가 증거다. 이것만으로 runtime 미사용을 확정하지 않는다. component scan, auto-configuration imports와 `@Bean`, lifecycle callback, event/post processor, ServiceLoader·reflection·configuration/resource discovery처럼 정적 직접 참조에 잡히지 않는 경로도 확인한다.

 ## 적용 조건

@@ -12,7 +12,7 @@ verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지

 # @ConditionalOnBean은 조건이 만족될 수 있는지까지 확인해야 한다

-조건부 빈을 선언해 두고 그 조건을 만족시킬 수 있는 경로가 있는지 확인하지 않아, 능력 전체가 조용히 없는 상태를 막는다. Spring 은 조건 불만족을 정상 동작으로 보므로 로그에도 액추에이터에도 신호가 남지 않는다.
+조건부 빈을 선언해 두고 그 조건을 만족시킬 수 있는 경로가 있는지 확인하지 않아 능력 전체가 조립되지 않는 상태를 막는다. 조건 불만족이 application failure나 health failure로 자동 승격되지 않을 수는 있지만, condition evaluation evidence 자체가 사라지는 것은 아니다. Spring Boot의 `ConditionEvaluationReport`와, endpoint가 노출된 경우 Actuator `/actuator/conditions`에서 match 여부와 이유를 확인할 수 있다.

 ## 목적

@@ -29,8 +29,8 @@ verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지
 3. 플랫폼이 제공하지 않겠다고 선언한 경우 질문을 바꾼다
   애플리케이션이 제공해야 하는 계약이라면, 물을 것은 조건이 아니라 출하 애플리케이션이 그 계약을 이행하는가다.

-4. 조건 불만족은 오류로 보고되지 않는다
-   Spring 은 조건부 빈이 조건을 만족하지 못하는 것을 정상 동작으로 본다. 로그에도 액추에이터에도 신호가 없다.
+4. 조건 불만족과 관측 가능성을 구분한다
+   조건이 맞지 않았다는 사실이 application failure나 health failure로 자동 승격되지 않을 수 있다. 그렇다고 condition evaluation evidence가 없어지는 것은 아니다. `ConditionEvaluationReport`와, endpoint가 노출된 경우 `/actuator/conditions`에서 positive/negative match와 이유를 확인한다.

 5. 꺼진 것과 조립될 수 없는 것을 구별할 방법을 남긴다
   둘이 런타임에서 같아 보이면 운영자는 차이를 알 수 없다.
@@ -1,7 +1,7 @@
 ---
 kind: REFERENCE
 slug: the-startup-validator-follows-the-autoconfiguration-root
-title: 시작 검증기가 도는지는 그 능력에 자동설정 루트가 있는지와 일치한다
+title: 시작 검증기는 실제 lifecycle과 assembly 경로에서 실행 여부를 확인한다
 topic: assembly-ownership
 project: clean-architecture-backend-template
 status: 게시 전
@@ -10,7 +10,7 @@ rootTreeNode: reference:the-startup-validator-follows-the-autoconfiguration-root
 verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지 않았다
 ---

-# 시작 검증기가 도는지는 그 능력에 자동설정 루트가 있는지와 일치한다
+# 시작 검증기는 실제 lifecycle과 assembly 경로에서 실행 여부를 확인한다

 검증기 파일이 존재하고 그 테스트가 통과한다는 사실을 검증이 실행된다는 증거로 읽는 것을 막는다. 규칙이 많고 잘 테스트되어 있다는 것은 품질의 증거이지 실행의 증거가 아니다.

@@ -20,11 +20,11 @@ verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지

 ## 규칙

-1. 검증기의 호출자를 센다
-   프로덕션 호출자가 0 이고 테스트 호출자만 있으면 그 검증은 실행 시점에 적용되지 않는다.
+1. searched direct caller를 확인한다
+   프로덕션 직접 호출을 찾지 못한 것은 강한 신호지만 그것만으로 runtime 미실행을 확정하지 않는다.

-2. 자동설정 루트가 부르는지 확인한다
-   능력의 조립 지점이 검증기를 호출하지 않으면, 그 능력이 배포되기 시작해도 검증은 자동으로 시작되지 않는다.
+2. assembly와 lifecycle 경로를 함께 확인한다
+   `@Bean`·component scan·auto-configuration, lifecycle callback, application event, post processor, framework discovery를 차례로 확인한다. 실제 부팅이 가능하면 condition report와 시작 로그도 함께 본다.

 3. 규칙 수와 실행 여부를 분리해서 본다
   규칙이 많고 잘 테스트되어 있다는 것은 품질의 증거이지 실행의 증거가 아니다.
@@ -44,7 +44,7 @@ verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지

 ## 예시

-gRPC 플랫폼의 시작 검증기는 188줄에 13개 위반 규칙을 담고 있고, 호출자는 자기 테스트뿐이다. 같은 패키지의 자동설정은 106줄에 Bean 이 9개인데 검증기를 부르지 않는다.
+gRPC 플랫폼의 시작 검증기는 188줄에 13개 위반 규칙을 담고 있다. 현재 분석에서는 searched direct caller가 테스트에 있고 같은 패키지의 자동설정이 검증기를 직접 부르지 않는다는 점을 확인했다. 이 사실을 runtime 미실행으로 확정하려면 다른 lifecycle·framework discovery 경로도 닫아야 한다.

 ## 관계