HTTP Client
Core client를 직접 사용하는 방법을 먼저 설명하고, 그 다음 자동 생성 service가 사용하는 프로젝트 공용 HTTP adapter를 선택적 통합 예제로 설명합니다.
Core client 직접 사용
createHttpClient<Paths>()에 주입하는 Paths가 요청 계약입니다. url과 method는 Paths의 key에서, queryString과 pathVariable은 parameters에서, body는 requestBody에서 타입이 결정됩니다.
응답 타입은 callApi<R>()의 R을 호출자가 지정합니다. Core는 OpenAPI responses에서 응답 타입을 자동 추론하지 않습니다.
httpClient.ts
ts응답 shape는 API별로 선택
typed-rx-http는 ResponseWrapper를 강제하지 않습니다. 서버 응답이 wrapper라면 wrapper 타입을 R로 지정하고, 그렇지 않으면 실제 응답 타입을 그대로 지정합니다.
선택: 프로젝트 공용 adapter + 자동 생성 service
아래 commonService 구성은 Core의 필수 구조가 아니라, 여러 생성 service에 인증·SSR header·cache 정책을 한 번에 적용하려는 프로젝트 통합 패턴입니다.
프로젝트 commonService가 하는 일
commonService는 @byeolnaerim/typed-rx-http가 제공하는 특별한 클래스명이 아니라, 프로젝트에서 공통 HTTP 정책을 한 곳에 모으기 위해 사용하는 사용자 소유 파일을 뜻합니다. 파일명은 자유롭고 아래 예제에서는 실제 프로젝트 이름인 rxjsHttpService.ts를 사용합니다.
화면과 자동 생성 service마다 createHttpClient를 반복하지 않고, 이 파일이 생성한 callApi와 callApiStream을 공통 진입점으로 사용합니다. 따라서 인증 갱신, SSR header 전달, cache와 오류 처리 규칙을 한 번 수정하면 모든 생성 service에 동일하게 적용됩니다.
commonService/rxjsHttpService 전체 코드부터 보기
1. 최소 완성형
commonService의 본질은 아래 코드입니다. headerStore와 typed HTTP client를 한 번 만들고, generated service가 공통으로 사용할 callApi/callApiStream을 export합니다. uploadFile과 createSSEObservable도 같은 client에서 그대로 노출할 수 있습니다.
rxjsHttpService.ts
ts2. Next.js + session auth + CSR/SSR cache까지 포함한 확장형
아래는 같은 공용 adapter에 session auth, SSR header와 CSR/SSR cache를 추가한 전체 프로젝트 예제입니다. generated service가 cache wrapper까지 import하는 프로젝트라면 이 형태가 기준이 됩니다. 그대로 복사한 뒤 setLogin import, ApiTypes와 CacheNames 위치, 인증 API 경로, 환경 변수와 unauthorized 경로만 자신의 프로젝트에 맞게 조정하면 됩니다.
rxjsHttpService.ts
ts코드 구성별 역할
paths
createHttpClient와 ServiceArguments가 URL, method, path variable, query와 body 타입을 검사할 때 사용하는 OpenAPI paths 타입입니다.
headerStore
브라우저에서 Content-Type과 Authorization 같은 공통 header를 저장하고 세션 인증 및 RSocket 연결과 공유합니다.
headersProvider
CSR에서는 headerStore를 반환하고 SSR에서는 현재 요청의 Cookie와 Authorization을 읽어 요청마다 다른 header를 제공합니다.
service
base URL, 공통 header, 서버 401 처리와 기본 오류 메시지를 가진 실제 typed HTTP client입니다.
sessionAuth
요청 전에 세션 token을 동기화하고 401이면 refresh 후 원래 Observable을 한 번 재시도하며, 실패하면 logout 흐름을 실행합니다.
callApi / callApiStream
자동 생성된 일반 REST service와 NDJSON stream service가 import하는 공통 함수입니다. 둘 다 RxJS Observable을 반환합니다.
callApiClientCache / callApiServerCache
브라우저에서는 CSR cache를 사용하고 서버에서는 @byeolnaerim/typed-rx-http/next의 SSR cache를 동적으로 불러오는 cache wrapper입니다.
자동 생성 service와 연결되는 방식
생성기는 commonServiceFile의 상대 경로를 계산해 각 service에 import를 넣습니다. 화면은 공용 파일을 직접 호출하지 않고 생성된 함수를 import하며, 생성 함수가 path, params, body를 ServiceArguments의 pathVariable, queryString, body로 변환해 callApi에 전달합니다.
generateSwagger.cjs
js한 번의 응답은 firstValueFrom
검색, 저장, 삭제처럼 한 번 응답하고 끝나는 REST API는 생성된 Observable을firstValueFrom으로 받으면 기존 async 함수 안에서도 자연스럽게 사용할 수 있습니다.
BusinessSearchPage.tsx
tsx화면에서는 params만 보이지만, 생성된 service 안에는 URL, HTTP method와 response type이 들어 있습니다. query parameter는 항상{ params: { ... } }로 전달합니다.
여러 응답은 subscribe
작업 진행률이나 RSocket stream처럼 여러 값이 도착하는 요청은subscribe로 받고, 컴포넌트가 사라질 때 구독을 해제합니다.
BatchJobPage.tsx
tsx직접 callApi를 사용하는 경우
서비스 생성기를 사용하지 않는 프로젝트나 생성 전 임시 endpoint를 확인할 때는 공용 service의 callApi를 직접 호출할 수 있습니다. 요청 타입은 paths에서 검사하고 응답 타입은 호출자가 제너릭으로 지정합니다.