donghyeon.kang/llm-wiki

Fork 0

Files

T

DongHyeonka 58515ab0f3 feat: 공식 문서 근거자료, 브랜치 기능 문서 작성

2026-07-29 18:05:17 +09:00

12 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title

source_type

url

archive_url

related_branches

related_projects

official-doc / Spring Boot — Application Availability (Liveness/Readiness) & SpringApplication Lifecycle

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/에 source-summary-template 형식으로 별도 작성. 원본은 raw에 영구 보관.

Parent / 활용 branch

Branch 이 자료가 정당화하는 결정

raw/branch-notes/feature-capability-provider-selection-contract capability 토폴로지 검증은 startup 에서 fail-fast 로 수행하고, 검증 실패는 컨텍스트 기동을 거부한다 — Spring Boot 자체의 애플리케이션 이벤트 순서(ApplicationStartedEvent → runner 실행, ApplicationFailedEvent on startup exception)가 근거. 또한 application availability state (LivenessState/ReadinessState)는 컨텍스트 refresh 완료 이후에만 변경되는 런타임 신호이며, startup 검증의 대체물이 아니라는 결정의 근거.

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-capability-provider-selection-contract	capability 토폴로지 검증은 startup 에서 fail-fast 로 수행하고, 검증 실패는 컨텍스트 기동을 거부한다 — Spring Boot 자체의 애플리케이션 이벤트 순서(`ApplicationStartedEvent` → runner 실행, `ApplicationFailedEvent` on startup exception)가 근거. 또한 application availability state (`LivenessState`/`ReadinessState`)는 컨텍스트 refresh 완료 이후에만 변경되는 런타임 신호이며, startup 검증의 대체물이 아니라는 결정의 근거.

출처

원본 URL: https://docs.spring.io/spring-boot/reference/features/spring-application.html
아카이브 URL: (미제공)
저자 / 조직: VMware / Spring Boot 프로젝트 (공식 레퍼런스)
발행일: 확인 안 됨 (WebFetch 결과 상단에 "SpringApplication :: Spring Boot 4.1.0" 표시 — 문서가 Spring Boot 4.1.0 레퍼런스 시점 버전임을 시사)
마지막 확인일: 2026-07-28

왜 저장했는지

feature-capability-provider-selection-contract branch 는 capability 토폴로지 검증을 "startup 시 fail-fast"로 둘지, 아니면 Spring Boot 의 ApplicationAvailability (readiness/liveness) 신호로 대체할지를 결정해야 한다. 본 문서는 Spring Boot 공식 레퍼런스가 (1) Liveness/Readiness state 를 컨텍스트 refresh 완료 이후의 런타임 신호로 정의하고, (2) ApplicationRunner/CommandLineRunner 도 "애플리케이션이 이미 시작된 후" 실행되며, (3) startup 중 예외는 별도의 ApplicationFailedEvent 경로로 분리된다는 것을 직접 진술하는지 확인하기 위해 발췌했다.

핵심 인용

[§Application Availability — Liveness State] "Indicates whether the application's internal state allows it to work correctly. A broken Liveness state signals that the application cannot recover and should be restarted by infrastructure (e.g., Kubernetes)."

[§Application Availability — Readiness State] "Indicates whether the application is ready to handle traffic. A failing Readiness state tells the platform not to route traffic to the application, typically during startup or when the application is too busy."

[§Application Events and Listeners — 이벤트 순서 목록 6번] "AvailabilityChangeEvent (LivenessState.CORRECT) – Application is live"

[§ApplicationRunner and CommandLineRunner] "If you need to run specific code once SpringApplication has started, implement ApplicationRunner or CommandLineRunner:"

[§Application Events and Listeners — 이벤트 순서 목록 9번] "ApplicationFailedEvent – If there's an exception on startup"

Claims Extracted

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
SB-AVAIL-C1	Liveness State 는 애플리케이션 내부 상태가 정상 동작 가능한지를 나타내며, broken 상태는 "복구 불가 → 인프라가 재시작해야 함"을 의미하는 런타임 헬스 신호다.	[§Application Availability] "Indicates whether the application's internal state allows it to work correctly. A broken Liveness state signals that the application cannot recover and should be restarted by infrastructure (e.g., Kubernetes)."	`official-vendor-doc`	LivenessState 의 의미론 — "복구 불가능해진 이미 살아있는 프로세스"를 인프라가 재시작하도록 신호하는 용도	LivenessState/ReadinessState 가 startup-time capability 토폴로지 정합성 검증에 적합한 메커니즘이라거나 Spring Boot 가 그 용도로 권장한다는 것 — 문서는 이 용도를 언급하지 않음
SB-AVAIL-C2	Readiness State 는 트래픽 처리 준비 여부를 나타내며, failing 상태는 "아직 트래픽 라우팅하지 말라"는 뜻이고 전형적으로 startup 도중이나 과부하 시 사용된다.	[§Application Availability] "Indicates whether the application is ready to handle traffic. A failing Readiness state tells the platform not to route traffic to the application, typically during startup or when the application is too busy."	`official-vendor-doc`	Readiness = "아직 트래픽 라우팅하지 마라"는 신호이며, 문서 스스로 startup 도중 상태로 명시 — 즉 컨텍스트는 이미 살아있고 프로세스도 떠 있는 상태에서의 트래픽 게이팅	Readiness=REFUSING_TRAFFIC 설정이 컨텍스트 기동 자체를 거부(refresh 실패/프로세스 종료)하는 것과 동등하다는 것 — 트래픽만 안 보낼 뿐 컨텍스트는 이미 완성되어 떠 있음
SB-AVAIL-C3	애플리케이션 이벤트 순서에서 `AvailabilityChangeEvent(LivenessState.CORRECT)` 는 6번째 이벤트로, `ApplicationStartedEvent`(5번, "컨텍스트 refresh 이후, runner 이전") 다음에 발생한다.	[§Application Events and Listeners] "AvailabilityChangeEvent (LivenessState.CORRECT) – Application is live" (목록 6번, 5번 항목 "ApplicationStartedEvent – After context refresh, before runners" 뒤)	`official-vendor-doc`	Liveness 신호가 컨텍스트 refresh 완료 이후에만 발생한다는 시점 근거 — refresh 도중의 bean 초기화 실패는 이 이벤트 이전 단계에서 이미 별도 경로(ApplicationFailedEvent)로 분기됨	문서가 "capability 토폴로지 검증"이라는 개념 자체를 언급하거나 그 검증을 refresh 단계에 두라고 권고한다는 것 — 이는 이벤트 순서로부터의 추론이지 원문의 명시적 진술이 아님
SB-AVAIL-C4	`ApplicationRunner`/`CommandLineRunner` 는 "`SpringApplication` 이 이미 시작된 후(once ... has started)" 실행하도록 설계된 확장점이다.	[§ApplicationRunner and CommandLineRunner] "If you need to run specific code once `SpringApplication` has started, implement `ApplicationRunner` or `CommandLineRunner`:"	`official-vendor-doc`	Runner 실행 시점이 컨텍스트 refresh 완료 이후(모든 싱글턴 빈이 이미 완전히 wiring된 시점)라는 것 — capability 토폴로지 검증을 Runner 에 두면 "이미 활성화된 컨텍스트"를 사후 점검하는 것이 됨	Runner 가 예외를 던졌을 때 프로세스가 종료되는지 여부 — 이 문서 발췌에는 명시 없음 (Spring 일반 지식이지 이 페이지의 verbatim 진술 아님)
SB-AVAIL-C5	애플리케이션 이벤트 순서에서 startup 중 예외는 정상 경로(Started→Live→Ready→AcceptingTraffic)와 분리된 `ApplicationFailedEvent` 로 별도 처리된다.	[§Application Events and Listeners] "ApplicationFailedEvent – If there's an exception on startup" (목록 9번)	`official-vendor-doc`	Spring Boot 자체의 라이프사이클 모델이 startup 중 예외를 "정상 가용성 상태 진행과는 별개의 실패 경로"로 취급한다는 것 — fail-fast 의 이벤트 모델적 근거	이 이벤트가 정확히 어떤 종료 코드/JVM exit 동작으로 이어지는지에 대한 구체 메커니즘 — 이 발췌 페이지는 `ExitCodeGenerator` 인터페이스만 별도로 언급할 뿐 `ApplicationFailedEvent` 와의 직접 연결을 verbatim 으로 진술하지 않음

Usage Boundaries

이 자료가 직접 증명하는 것:
- SB-AVAIL-C1/SB-AVAIL-C2: LivenessState/ReadinessState 는 "이미 살아있는 프로세스"에 대한 런타임 헬스·트래픽 게이팅 신호이며, 정의상 컨텍스트가 이미 완성된 이후에 의미를 갖는다.
- SB-AVAIL-C3/SB-AVAIL-C4: 이벤트 순서상 Liveness 신호 변경과 Runner 실행은 모두 ApplicationStartedEvent("After context refresh, before runners") 이후에 위치한다 — 즉 컨텍스트 refresh 가 이미 성공적으로 끝난 다음의 일이다.
- SB-AVAIL-C5: startup 중 예외는 정상 가용성 상태 전이와 분리된 별도 실패 이벤트(ApplicationFailedEvent)로 취급된다.
이 자료가 증명하지 않는 것:
- "capability 토폴로지 검증"이라는 ca-skeleton 고유 개념 자체 — Spring Boot 문서는 이 용어를 전혀 언급하지 않는다. 위 5개 claim 은 모두 일반적인 SpringApplication 라이프사이클 이벤트 순서에 대한 진술이며, 이로부터 "그러므로 capability 토폴로지 검증은 refresh 단계에서 fail-fast 로 해야 한다"는 결론은 branch 저자의 추론이지 원문의 직접 진술이 아니다.
- Runner 가 예외를 던질 때 프로세스 종료/exit code 동작의 구체 메커니즘.
- Readiness=REFUSING_TRAFFIC 이 컨텍스트 기동 실패와 "동등"하다는 주장 — 오히려 원문은 정반대(Readiness 는 컨텍스트가 이미 뜬 상태의 트래픽 게이팅)를 보여준다.
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-skeleton 의 실제 컨텍스트 초기화 훅(@PostConstruct, SmartInitializingSingleton, ApplicationListener<ContextRefreshedEvent> 등 refresh 단계 내 실행 지점 중 정확히 어디에 capability 토폴로지 검증을 배치할지)은 이 문서에 없다 — 별도 Spring Framework ApplicationContext refresh 문서 또는 실제 구현으로 검증 필요.
- ApplicationFailedEvent 발생 시 Spring Boot 가 SpringApplication.run() 호출자에게 예외를 어떻게 전파하는지(예: run() 이 예외를 던지는지)는 본 발췌에 없음.

메모

인용 해석 후보 (미검증, branch 저자 추론 — 이 문서가 직접 말한 것 아님): "이벤트 순서(ApplicationStartedEvent → runner → AvailabilityChangeEvent)가 보여주는 건 Liveness/Readiness 와 Runner 모두 컨텍스트가 이미 완성된 이후라는 사실이므로, capability 토폴로지처럼 '컨텍스트가 완성되기 전에 막아야 하는' 검증은 이 두 메커니즘이 아니라 컨텍스트 refresh 도중(예: bean 초기화 또는 BeanFactoryPostProcessor/SmartInitializingSingleton)에 두어야 한다"는 결론은 이 문서의 이벤트 순서 사실에서 추론한 것이지, 문서가 "capability 검증을 여기에 두라"고 명시적으로 권고한 것이 아니다. wiki/concepts 로 승격 시 이 구분을 명확히 유지할 것.
추가로 봐야 할 동일 출처 페이지: Spring Framework 공식 문서의 ApplicationContext.refresh() 생명주기(BeanFactoryPostProcessor, SmartInitializingSingleton, ContextRefreshedEvent) — 이 페이지(SpringApplication)는 Spring Boot 레벨 이벤트만 다루고, refresh 내부의 세부 콜백 순서는 다루지 않는다.
WebFetch 도구 특성상 원본 HTML 을 AI 모델이 마크다운으로 정리한 결과다. 원문 그대로 보존을 프롬프트로 요청했고 self-grep 은 이 정리된 텍스트 기준으로 통과했으나, Spring 공식 페이지의 byte-for-byte HTML 과 100% 동일하다는 보장은 없다 — 재검증 시 페이지를 직접 열어 대조 권장.

12 KiB Raw Permalink Blame History Unescape Escape