llm-wiki/vault/20-evidence/official-docs/spring-smartlifecycle-reference.md

title, source_type, url, archive_url, related_projects, related_branches, tags, status, confidence, created, last_reviewed

title	source_type	url	archive_url	related_projects	related_branches	tags	status	confidence	created	last_reviewed
Spring Framework — Lifecycle / SmartLifecycle (start/stop, phase ordering, graceful shutdown)	official-doc	https://docs.spring.io/spring-framework/reference/core/beans/factory-nature.html			feature-outbound-http-client-baseline feature-runtime-health-lifecycle-contract	spring-framework lifecycle smart-lifecycle graceful-shutdown phase-ordering depends-on application-context bean-lifecycle official-doc	raw	high	2026-05-27	2026-05-27

Spring Framework — Lifecycle / SmartLifecycle (start/stop, phase ordering, graceful shutdown)

Layer: raw/official-docs/ — Spring Framework Reference / "Customizing the Nature of a Bean" → "Startup and Shutdown Callbacks" 섹션 verbatim. outbound HTTP client / scheduler / cache / background worker 의 graceful start/stop 메커니즘과 phase 기반 순서 보장의 1차 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-outbound-http-client-baseline	D8 — outbound HTTP client (또는 그 underlying connection pool / scheduler) 가 graceful shutdown 하려면 SmartLifecycle.stop(Runnable) 의 async callback 패턴을 따라야 하고, web server 보다 먼저 stop 되어야 한다 (phase 값 조정)
raw/branch-notes/feature-runtime-health-lifecycle-contract	start/stop 순서 보장 (phase ascending start / descending stop), depends-on 의존 stop 순서, isAutoStartup 의 ApplicationContext refresh 발동, DefaultLifecycleProcessor 의 timeout 동작

컨텍스트

ca-tmpl 의 runtime lifecycle contract 는 "stateful 컴포넌트 (HTTP client pool, scheduler, message listener) 는 web server 보다 먼저 stop 되어야 한다" 는 규칙을 갖는다. 이 규칙의 구현 mechanism 은 SmartLifecycle 의 phase 값 조정 (web server 는 default phase = Integer.MAX_VALUE - 1024, outbound 컴포넌트는 그보다 큰 값). 본 자료는 (1) Lifecycle 의 정확한 시그니처, (2) SmartLifecycle 의 추가 메서드 (isAutoStartup, stop(Runnable), getPhase), (3) startup ascending / shutdown descending 의 phase 시맨틱, (4) DefaultLifecycleProcessor 의 timeout 동작을 verbatim 으로 보존.

출처 / Source

• 원본 URL: https://docs.spring.io/spring-framework/reference/core/beans/factory-nature.html
• 아카이브 URL: (미수집)
• 저자 / 조직: Spring Framework (VMware / Broadcom)
• 발행일: rolling docs (current = 6.x)
• 마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§Startup and Shutdown Callbacks] "The Lifecycle interface defines the essential methods for any object that has its own lifecycle requirements (such as starting and stopping some background process):

public interface Lifecycle {
    void start();
    void stop();
    boolean isRunning();
}
```"

[§Startup and Shutdown Callbacks] "The following listing shows the definition of the SmartLifecycle interface:

public interface SmartLifecycle extends Lifecycle, Phased {
    boolean isAutoStartup();
    void stop(Runnable callback);
}
```"

[§Startup and Shutdown Callbacks - Phase Ordering] "When starting, the objects with the lowest phase start first. When stopping, the reverse order is followed. Therefore, an object that implements SmartLifecycle and whose getPhase() method returns Integer.MIN_VALUE would be among the first to start and the last to stop."

[§Startup and Shutdown Callbacks - Default Phase] "When considering the phase value, it is also important to know that the default phase for any 'normal' Lifecycle object that does not implement SmartLifecycle is 0."

[§Startup and Shutdown Callbacks - Dependency-Aware Shutdown] "The order of startup and shutdown invocations can be important. If a 'depends-on' relationship exists between any two objects, the dependent side starts after its dependency, and it stops before its dependency."

[§Startup and Shutdown Callbacks - ApplicationContext Refresh & Auto-Startup] "When the context is refreshed (after all objects have been instantiated and initialized), that callback is invoked. At that point, the default lifecycle processor checks the boolean value returned by each SmartLifecycle object's isAutoStartup() method. If true, that object is started at that point rather than waiting for an explicit invocation of the context's or its own start() method."

[§Startup and Shutdown Callbacks - Graceful Shutdown via Callback] "The stop method defined by SmartLifecycle accepts a callback. Any implementation must invoke that callback's run() method after that implementation's shutdown process is complete. That enables asynchronous shutdown where necessary, since the default implementation of the LifecycleProcessor interface, DefaultLifecycleProcessor, waits up to its timeout value for the group of objects within each phase to invoke that callback."

[§Lifecycle Callbacks vs Destruction - SmartLifecycle Distinction] "It is strongly recommended that the internal state in any such bean also allows for an immediate destroy callback without a preceding stop since this may happen during an extraordinary shutdown after a cancelled bootstrap or in case of a stop timeout caused by another bean."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
SPRING-SMARTLC-C1	Lifecycle interface 는 background process 의 시작/종료 요구 사항을 가진 객체용이며 정확한 시그니처는 void start(), void stop(), boolean isRunning() 3개	[§Startup and Shutdown Callbacks] "The Lifecycle interface defines the essential methods for any object that has its own lifecycle requirements (such as starting and stopping some background process)" + public interface Lifecycle { void start(); void stop(); boolean isRunning(); }	official-vendor-doc	Spring Framework 모든 버전 (Lifecycle interface)	start()/stop() 이 idempotent 한지의 contract 는 본 인용 범위 밖
SPRING-SMARTLC-C2	SmartLifecycle 은 Lifecycle, Phased 를 확장하며 추가로 boolean isAutoStartup() 과 void stop(Runnable callback) 두 메서드를 정의	[§Startup and Shutdown Callbacks] public interface SmartLifecycle extends Lifecycle, Phased { boolean isAutoStartup(); void stop(Runnable callback); }	official-vendor-doc	Spring Framework (SmartLifecycle interface 사용 시)	default 구현체 (e.g. Spring Boot 의 web server lifecycle) 의 정확한 phase 값은 본 인용 범위 밖
SPRING-SMARTLC-C3	startup 시 가장 낮은 phase 가 먼저 시작; shutdown 시 반대 순서 (가장 높은 phase 가 먼저 stop). Integer.MIN_VALUE 반환 객체는 startup 시 가장 먼저, shutdown 시 가장 늦게	[§Phase Ordering] "When starting, the objects with the lowest phase start first. When stopping, the reverse order is followed. Therefore, an object that implements SmartLifecycle and whose getPhase() method returns Integer.MIN_VALUE would be among the first to start and the last to stop."	official-vendor-doc	SmartLifecycle + Phased 사용 시	동일 phase 내 객체 간 startup 순서 보장은 본 인용 범위 밖
SPRING-SMARTLC-C4	SmartLifecycle 를 구현하지 않는 일반 Lifecycle 객체의 default phase 는 0	[§Default Phase] "When considering the phase value, it is also important to know that the default phase for any 'normal' Lifecycle object that does not implement SmartLifecycle is 0."	official-vendor-doc	Lifecycle 구현체이고 SmartLifecycle 미구현 시	SmartLifecycle 의 default phase (getPhase 미오버라이드 시) 는 본 인용 범위 밖 — interface 자체에 default method 없음
SPRING-SMARTLC-C5	depends-on 관계가 있으면 의존 측은 의존 대상 이후 시작하고 의존 대상 이전에 stop 한다	[§Dependency-Aware Shutdown] "The order of startup and shutdown invocations can be important. If a 'depends-on' relationship exists between any two objects, the dependent side starts after its dependency, and it stops before its dependency."	official-vendor-doc	@DependsOn annotation 또는 XML depends-on	depends-on 이 phase 순서를 override 하는지 (동일 phase 내에서 만 적용인지) 는 본 인용 범위 밖
SPRING-SMARTLC-C6	ApplicationContext refresh 후 default lifecycle processor 가 각 SmartLifecycle.isAutoStartup() 을 확인하고 true 면 자동 start() 호출 (명시적 호출 대기 안 함)	[§ApplicationContext Refresh & Auto-Startup] "When the context is refreshed (after all objects have been instantiated and initialized), that callback is invoked. At that point, the default lifecycle processor checks the boolean value returned by each SmartLifecycle object's isAutoStartup() method. If true, that object is started at that point rather than waiting for an explicit invocation of the context's or its own start() method."	official-vendor-doc	SmartLifecycle + DefaultLifecycleProcessor (default)	isAutoStartup() == false 시 어느 trigger 로 start 되는지는 본 인용 범위 밖 (명시 context.start() 또는 bean 직접 호출)
SPRING-SMARTLC-C7	SmartLifecycle.stop(Runnable) 은 async shutdown 을 가능하게 함. 구현체는 shutdown 완료 후 callback 의 run() 호출 필수. DefaultLifecycleProcessor 는 각 phase 내 객체들이 callback 호출할 때까지 timeout 까지 대기	[§Graceful Shutdown via Callback] "The stop method defined by SmartLifecycle accepts a callback. Any implementation must invoke that callback's run() method after that implementation's shutdown process is complete. That enables asynchronous shutdown where necessary, since the default implementation of the LifecycleProcessor interface, DefaultLifecycleProcessor, waits up to its timeout value for the group of objects within each phase to invoke that callback."	official-vendor-doc	SmartLifecycle 구현체 (Runnable overload)	timeout default 값 (30초) 은 본 인용 범위 밖 — DefaultLifecycleProcessor.setTimeoutPerShutdownPhase 별도
SPRING-SMARTLC-C8	SmartLifecycle bean 의 내부 state 는 stop() 없이 destroy callback 만 호출되는 경우도 안전하게 처리해야 함 (bootstrap 취소 또는 다른 bean 의 stop timeout 으로 인한 비정상 shutdown 시)	[§SmartLifecycle Distinction] "It is strongly recommended that the internal state in any such bean also allows for an immediate destroy callback without a preceding stop since this may happen during an extraordinary shutdown after a cancelled bootstrap or in case of a stop timeout caused by another bean."	official-vendor-doc	SmartLifecycle + destroy callback (e.g. DisposableBean) 동시 구현 시	어떤 bean 의 stop timeout 이 다른 bean 의 destroy 를 trigger 하는 정확한 cascade 는 본 인용 범위 밖

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • SPRING-SMARTLC-C1: Lifecycle interface 의 3개 메서드 정확한 시그니처
  • SPRING-SMARTLC-C2: SmartLifecycle extends Lifecycle, Phased + 추가 2개 메서드
  • SPRING-SMARTLC-C3: startup ascending / shutdown descending phase 순서
  • SPRING-SMARTLC-C4: 일반 Lifecycle default phase = 0
  • SPRING-SMARTLC-C5: depends-on 의 startup/shutdown 순서 영향
  • SPRING-SMARTLC-C6: ApplicationContext refresh + isAutoStartup() == true → 자동 start
  • SPRING-SMARTLC-C7: stop(Runnable) 의 async 시맨틱 + DefaultLifecycleProcessor 의 phase-level timeout 대기
  • SPRING-SMARTLC-C8: stop 없는 destroy 가능성에 대비한 state 설계 권고
• 이 자료가 증명하지 않는 것:
  • Spring Boot 의 WebServerGracefulShutdownLifecycle 같은 구현체의 정확한 phase 값
  • DefaultLifecycleProcessor 의 default timeout = 30초 (별도 페이지/JavaDoc 참조)
  • graceful shutdown trigger 와 OS signal (SIGTERM) 간의 매핑 (별도 ApplicationContext 종료 hook 문서)
  • SmartLifecycle 객체가 모두 stop 한 후에 DisposableBean.destroy() 가 호출된다는 정확한 순서 보장
  • reactive context (WebFlux) 에서 lifecycle 동작이 같다는 뜻 (별도 페이지)
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • ca-tmpl 의 outbound HTTP client pool 이 SmartLifecycle 을 구현하는지 (또는 wrapping 필요)
  • web server (Tomcat embedded) 의 graceful shutdown phase 값 (Integer.MAX_VALUE - 1024 known constant) 보다 큰 phase 를 outbound 컴포넌트에 부여해야 outbound 이 먼저 stop
  • spring.lifecycle.timeout-per-shutdown-phase Spring Boot property 의 default = 30s 검증 (DefaultLifecycleProcessor.timeoutPerShutdownPhase)

메모 / Notes

• 인용 1 해석 후보 (미검증):
  • "web server 보다 먼저 stop" → outbound client 의 phase 를 web server phase 보다 크게 설정 (shutdown descending 이므로 큰 phase 가 먼저 stop)
• 추가로 봐야 할 동일 출처 페이지:
  • https://docs.spring.io/spring-framework/reference/core/beans/factory-nature.html#beans-factory-shutdown (ApplicationContext shutdown hook)
  • https://docs.spring.io/spring-boot/reference/web/graceful-shutdown.html (Spring Boot graceful shutdown property)

Related / 관련

• 같은 주제 다른 official-doc:
  • raw/official-docs/spring-restclient-builder-reference (lifecycle managed client 후보)
  • raw/official-docs/spring-tx-management-reference
• 인용하는 branch:
  • raw/branch-notes/feature-outbound-http-client-baseline
  • raw/branch-notes/feature-runtime-health-lifecycle-contract
• 인용하는 project:
  • raw/project-notes/ca-skeleton-operational-contract
• 인용하는 wiki: (미작성)