ADR-0003: 서버 상태 조회 수단으로 내장 httpResource를 채택하고 TanStack Query 도입을 유보한다
상태
Superseded by 0011
2026-08-10에 로딩 전략을 검토하며 데이터 로딩 모델이 fetch-then-render로 바뀌었습니다. "서버 상태 조회의 기본 수단은 httpResource"라는 본 ADR의 핵심 결정이 "화면 진입에 필수인 데이터는 리졸버"로 대체됩니다. httpResource는 오버레이 내부, 보조 정보, 폴링에서 계속 사용하므로 도구가 기각된 것은 아닙니다.
TanStack Query를 유보한 결정과 그 재검토 조건은 유효합니다.
날짜
2026-08-10
맥락
화면이 서버 데이터를 조회하는 방식을 정해야 합니다. 선택지는 프레임워크 내장 API와 외부 서버 상태 라이브러리 두 갈래입니다.
Angular 22에서 resource()와 httpResource가 @publicApi 22.0으로 안정화되었습니다. 시그널 기반 조회, 로딩·에러 상태 노출, 요청 변경 시 이전 요청 자동 취소, reload(), SSR 전송 상태 자동 연동을 제공합니다.
제공하지 않는 것은 교차 화면 캐시, 요청 중복 제거, 키 단위 무효화, stale-while-revalidate, 재시도 정책입니다. TanStack Query는 이들을 제공합니다.
판단이 갈릴 것으로 예상했던 지점은 캐시 무효화와 FSD 계층 규칙의 충돌이었습니다. features에서 데이터를 변경한 뒤 pages의 조회를 갱신해야 하는데 features는 상위 계층인 pages를 임포트할 수 없습니다. TanStack Query는 queryKey가 문자열이라 계층 참조 없이 무효화가 가능합니다.
검토 결과 이 충돌은 어느 쪽을 골라도 같은 방식으로 해소됩니다. 무효화 신호를 shared에 두고 features가 발행, pages가 구독하면 내장 API도 계층 위반 없이 동작합니다. 실제 차이는 메커니즘이 라이브러리에 내장되어 있는가, 직접 작성하는가입니다.
결정
서버 상태 조회의 기본 수단은 httpResource입니다. 외부 서버 상태 라이브러리를 초기에 도입하지 않습니다.
무효화는 shared/api/에 두는 신호 객체(InvalidationBus)로 처리합니다. 무효화 키는 도메인 단위 상수로 정의하며 호출부에 문자열을 직접 기재하지 않습니다.
변경 요청은 httpResource가 아니라 HttpClient를 직접 사용합니다. httpResource는 읽기 전용이며 요청이 바뀔 때 진행 중인 작업을 중단하므로 변경 요청에 사용하면 중도 취소될 수 있습니다.
세부 규칙은 서버 상태와 클라이언트 상태가 원본입니다.
도입 재검토 조건
다음이 측정으로 확인되면 TanStack Query 도입을 신규 ADR로 판단합니다.
| 조건 | 확인 방법 |
|---|---|
| 동일 데이터의 중복 요청이 실제로 발생 | 네트워크 기록에서 반복 요청 확인 |
| 화면 전환 시 재조회 지연이 체감됨 | 목록에서 상세로 갔다 돌아올 때의 지연 측정 |
| 무효화 키가 열 개를 넘고 상호 의존이 발생 | invalidation-keys.ts 규모 확인 |
검토한 대안
TanStack Query 초기 도입
| 구분 | 내용 |
|---|---|
| 장점 | 캐시·중복 제거·키 단위 무효화가 처음부터 제공됩니다. 무효화 메커니즘을 직접 설계할 필요가 없습니다 |
| 단점 | Angular 어댑터가 @tanstack/angular-query-experimental 이름으로만 배포되며 정식 명칭 패키지가 없습니다. 공식 문서가 마이너·패치 릴리스에서도 파괴적 변경 가능성을 명시하고 패치 수준 버전 고정을 권고합니다. SSR 전송 상태를 직접 배선해야 합니다 |
| 기각 사유 | 2순위 품질 목표가 규칙의 자동 강제이며 그 전제는 안정성입니다. 실험 단계 패키지에 조회 경로 전체를 의존시키는 것은 이 목표와 성격이 충돌합니다. 필요성이 측정으로 확인되지 않은 상태에서 감수할 위험이 아닙니다 |
NgRx SignalStore
| 구분 | 내용 |
|---|---|
| 장점 | Angular 생태계의 사실상 표준 상태 관리이며 withEntities로 목록 상태를 구조화합니다 |
| 단점 | 서버 캐시를 직접 다루지 않아 조회 계층을 별도로 정해야 합니다. 보일러플레이트가 늘어납니다 |
| 기각 사유 | 해결하려는 문제가 클라이언트 상태 구조화가 아니라 서버 상태 조회입니다. 도구와 문제가 맞지 않습니다 |
결과
외부 의존성 없이 시작하며, 조회 코드가 Angular 공식 문서와 동일한 형태가 되어 에이전트가 별도 학습 없이 작성할 수 있습니다. SSR 전송 상태 연동에 배선이 필요 없습니다.
감수하는 사항은 다음과 같습니다.
- 무효화 메커니즘을 직접 작성하고 유지합니다. 분량은 크지 않으나 우리 코드이므로 결함도 우리 책임입니다.
- 같은 화면의 컴포넌트 둘이 같은 데이터를 조회하면 요청이 두 번 나갑니다. 상위 컴포넌트가 한 번 조회해 전달하는 규칙으로 회피하며, 이 규칙은 자동 강제되지 않아 코드 리뷰에서 확인합니다.
- 화면 전환 시 캐시가 없어 매번 재조회합니다. 목록에서 상세로 갔다 돌아오면 로딩이 다시 보입니다.
- 추후 도입 시 이미 작성된 조회 코드를 전수 이전해야 합니다. 이 비용을 낮추기 위해 조회 함수를
api세그먼트에 모으고 컴포넌트가 직접httpResource를 호출하지 않도록 합니다.
확인이 필요한 항목
resource의 요청 파라미터 변경 시 이전 값 유지 여부가 미확인입니다. ResourceStatus에 loading과 reloading이 구분되어 있어 reload() 중에는 이전 값이 유지되나, 파라미터 변경 시에는 loading으로 전이하며 값이 초기화되는 것으로 파악됩니다. 목록 필터 변경 시의 화면 깜빡임에 영향을 주므로 실측이 필요하며, 결과에 따라 본 ADR의 도입 재검토 조건이 조정될 수 있습니다.