Visão geral

Cliente HTTP seguro baseado em RxJS para TypeScript e adaptador opcional Next.js/RSocket

@byeolnaerim/typed-rx-httpé um cliente HTTP que injeta tipos de Paths estilo OpenAPI, verificando tipos para URL, método HTTP, parâmetros de caminho/query e corpo da requisição, retornando resultados como Observable RxJS.

O que eu queria nesta biblioteca não era uma abstração HTTP elaborada. Era poder importar e chamar diretamente as funções geradas, sem ter que reescrever a URL e os DTOs de request/response que acabei de criar no backend.

Forma básica de uso do Core

O fluxo básico é preparar tipos de Paths estilo OpenAPI, criar um HeaderStore se necessário, gerar o cliente com createHttpClient<Paths>() e chamar callApi<R>(). O gerador automático de serviços ou backend WebFlux não são requisitos obrigatórios para este fluxo.

O tipo de requisição é determinado pelos Paths, e o tipo de resposta é escolhido pelo chamador em R de callApi<R>(). Não impõe um ResponseWrapper específico. NDJSON, cache CSR, autenticação de sessão, funcionalidades do Next.js e RSocket são adicionadas apenas quando necessário.

A geração automática do OpenAPI é uma funcionalidade opcional

O script node auto que cria tipos TypeScript e arquivos de serviço a partir de JSON Swagger/OpenAPI é uma funcionalidade opcional separada do cliente HTTP Core. Usuários comuns do Core, /next, /rsocket não precisam executar o gerador.

História de origem

Eu uso Next.js e TypeScript no frontend, e Java e WebFlux no backend. Ao criar um projeto com essa combinação, acabei repetindo muito o mesmo conteúdo em ambos os lados.

No backend, crio entidades e DTOs de request/response e escrevo endpoints. No entanto, para chamar esse endpoint no frontend, preciso reescrever a URL e criar tipos ou interfaces quase idênticas aos DTOs do backend. Para ser honesto, não é diferente de reescrever o que já escrevi no backend.

Essa repetição não só aumenta a quantidade de código, mas também aumenta a possibilidade de esquecer de atualizar o outro lado quando um campo ou URL muda. Por isso, senti a necessidade urgente de gerar de forma previsível o código do cliente HTTP do frontend a partir das especificações da API REST do backend.

Nesse processo, apliquei primeiro o protótipo para o backend no projeto real nplauction.comreactive-mongo-dslewebflux-fe-dev-assistanto protótipo do frontend com typed-rx-http. O typed-rx-http não começou como uma ideia separada, mas surgiu como uma biblioteca adicional enquanto criava o webflux-fe-dev-assistant, desenvolvendo o que era necessário para o frontend.

Forma de uso em projetos de geração automática do Swagger

Em projetos que utilizam a geração automática de serviços Swagger, createHttpClientnão escrevo a cada vez. Crio uma vez no projeto e uso apenas as funções de serviço geradas a partir do Swagger. commonService.tscria-se uma vez um adaptador HTTP público de propriedade do projeto e utiliza-se apenas as funções de serviço geradas pelo OpenAPI. commonService.ts não é o nome do arquivo gerado pela biblioteca, mas sim o nome definido pelo projeto, e o código completo pode ser conferido na documentação de início/HTTP Client.

const response = await firstValueFrom(
  workplacesSearch({ params: { keyword: "kim" } }),
);

O código acima não contém strings de URL ou interfaces de response escritas manualmente. A URL, método HTTP, tipo de parâmetro e tipo de response estão incluídos no serviço gerado. Uma única resposta é recebida como firstValueFrome solicitações com vários valores, como o progresso de uma tarefa, podem ser recebidas comosubscribe.

Onde se encaixa melhor?

Se o backend e o frontend estiverem separados e o backend puder fornecer umswagger.jsonválido, você pode reduzir o trabalho repetitivo no frontend em TypeScript. Se você usar o endpoint funcional do Java WebFlux, pode combinar com o webflux-fe-dev-assistant para conectar a geração de documentação e a criação de serviços.

typed-rx-http Core não depende do WebFlux. É compatível com TypeScript de acordo com a especificação OpenAPI, independentemente da implementação do backend. paths Se houver um tipo, pode-se usá-lo para reduzir a necessidade de escrever manualmente a URL de string e o tipo de solicitação a cada vez. O cliente RSocket pode ser usado diretamente no ponto de entrada /rsocket, e o gerador AsyncAPI pode ser utilizado apenas em projetos que necessitam da geração automática de serviços de rota/requisição/resposta.

Escopo atualmente verificado

Os resultados da geração podem variar dependendo da estrutura da documentação OpenAPI ou AsyncAPI e da ferramenta de geração utilizada. Não garantimos a saída de todos os frameworks e ferramentas de geração de documentação, portanto, verifique os resultados gerados antes de aplicar.swagger.json ouasyncapi-rsocket.jsona estrutura gerada.

Repositório: github.com/joohyoungkim19940805/typed-rx-http