Overview
백엔드에서 이미 작성한 API를 프론트에서 다시 작성하지 않기 위한 TypeScript HTTP client
@byeolnaerim/typed-rx-http는 Swagger/OpenAPI에 작성된 REST API 사양을 TypeScript type과 RxJS 기반의 HTTP service로 연결하기 위해 만든 라이브러리입니다.
제가 이 라이브러리에서 원했던 것은 거창한 HTTP 추상화가 아니었습니다. 백엔드에서 방금 작성한 URL과 request/response DTO를 프론트에서 또 작성하지 않고, 생성된 함수를 import해서 바로 호출하는 것이었습니다.
Origin story
저는 프론트에서 Next.js와 TypeScript를 사용하고, 백엔드에서는 Java와 WebFlux를 사용합니다. 이 조합으로 프로젝트를 만들다 보니 똑같은 내용을 양쪽에서 반복해서 작성하는 일이 너무 많았습니다.
백엔드에서는 entity와 request/response DTO를 만들고 endpoint를 작성합니다. 그런데 프론트에서 그 endpoint를 호출하려면 URL을 다시 타이핑하고, 백엔드 DTO와 거의 같은 type이나 interface를 또 만들어야 했습니다. 솔직히 말하면 백엔드에서 제가 작성했던 것을 프론트에서 한 번 더 작성하는 것과 다름이 없었습니다.
이런 반복은 코드의 양만 늘리는 것이 아니라, 한쪽의 필드나 URL이 바뀌었을 때 다른 쪽을 빠뜨릴 가능성도 같이 늘렸습니다. 그래서 백엔드의 REST API 사양을 프론트 HTTP client 코드로 예측 가능하게 생성해야 할 필요성을 절실하게 느꼈습니다.
그 과정에서 실제 프로젝트인 nplauction.com에 백엔드용reactive-mongo-dsl과webflux-fe-dev-assistant의 프로토타입을, 프론트에는 typed-rx-http의 프로토타입을 먼저 적용했습니다. typed-rx-http는 처음부터 별개의 아이디어로 시작했다기보다, webflux-fe-dev-assistant를 만들면서 프론트에 필요한 짝을 함께 만들다 보니 부가적으로 태어난 라이브러리에 가깝습니다.
실제 프로젝트에서의 사용 방식
실제 화면 코드에서 createHttpClient나 URL을 매번 작성하지는 않습니다. 프로젝트에 commonService.ts를 한 번 만들고, Swagger에서 생성된 service 함수만 import해서 사용합니다.
const response = await firstValueFrom(
workplacesSearch({ params: { keyword: "kim" } }),
);위 코드에는 URL 문자열도 없고 response interface도 없습니다. URL, HTTP method, parameter type과 response type은 생성된 service 안에 들어 있습니다. 한 번의 응답은 firstValueFrom으로 받고, 크롤링 진행 상황처럼 여러 값이 이어지는 요청은subscribe로 받습니다. 이것이 현재 NPL 프로젝트에서 가장 일반적으로 사용하는 방식입니다.
어디에서 가장 잘 맞을까
백엔드 팀과 프론트 팀이 나뉘어 있고, 백엔드 팀에서 정상적인swagger.json을 제공할 수 있다면 TypeScript를 사용하는 프론트 개발자에게 특히 효율적일 수 있습니다. Java WebFlux functional endpoint를 사용한다면 webflux-fe-dev-assistant와 함께 사용할 때 제가 원했던 자동화 흐름을 가장 그대로 만들 수 있습니다.
그렇다고 typed-rx-http를 WebFlux에서만 사용하도록 만들고 싶지는 않았습니다. 백엔드가 직접 Swagger를 만들어주지 않더라도 OpenAPI 사양에 맞는 TypeScript paths type이 있다면 문자열 URL과 요청 타입을 매번 손으로 작성하는 일을 줄이는 데에는 사용할 수 있습니다. RSocket client도 같은 이유로 AsyncAPI 문서를 기준으로 생성되도록 만들었습니다.
swagger.json 또는asyncapi-rsocket.json의 구조를 먼저 확인하는 것이 좋습니다.