ADR014: HTTP 가져오기 라이브러리의 올바른 사용
지금까지 우리는 Node.js 맥락에서 node-fetch 사용을 권장해 왔습니다.
출처: 문서
본문
맥락
지금까지 우리는 ADR013을 통해 Node.js 맥락에서 node-fetch 사용을 권장해 왔습니다. 그 이후 Backstage의 최소 요구 사항이 Node.js 20 이상으로 업그레이드되었습니다. Node.js 플랫폼은 이 버전들에서 안정적이고 신뢰할 수 있는 undici 기반의 네이티브 fetch를 확립했습니다. 또한 새 버전의 Node.js에서만 나타나는 서드파티 라이브러리 사용에 몇 가지 문제가 있습니다.
결정
Node.js에서 실행되는 모든 코드(백엔드와 CLI 포함)는 HTTP 데이터 가져오기에 네이티브 fetch를 사용해야 하며, fetch 구현이 주입되거나 참조될 수 있는 코드에서는 TypeScript 타입으로 typeof fetch를 사용해야 합니다. 예:
import { ResponseError } from '@backstage/errors';// this is implicitly global.fetchconst response = await fetch('https://example.com/api/v1/users.json');if (!response.ok) { throw await ResponseError.fromResponse(response);}const users = await response.json();
프론트엔드 플러그인과 패키지는 fetchApiRef를 사용하는 것을 선호해야 합니다.
import { useApi } from '@backstage/core-plugin-api';// Inside some React component...const { fetch } = useApi(fetchApiRef);const response = await fetch('https://example.com/api/v1/users.json');if (!response.ok) { throw await ResponseError.fromResponse(response);}const users = await response.json();
동형(isomorphic) 패키지는 모킹과 타입 정의를 위해 cross-fetch 패키지에 의존해야 합니다. 바람직하게는, 동형 패키지의 클래스와 함수가 typeof fetch 타입의 인자를 받아 호출자가 선호하는 fetch 구현을 제공할 수 있게 해야 합니다. 이렇게 하면 호출자들이 인증이나 기타 정보를 호출에 덧붙이고, 크로스 플랫폼 방식으로 메트릭 등을 추적할 수 있습니다. 예:
import crossFetch from 'cross-fetch';export class MyClient { private readonly fetch: typeof crossFetch; constructor(options: { fetch?: typeof crossFetch }) { this.fetch = options.fetch || crossFetch; } async users() { return await this.fetch('https://example.com/api/v1/users.json'); }}
결과
Node.js 플랫폼에서 node-fetch 등의 서드파티 fetch 대체 패키지에서 점진적으로 벗어날 것입니다.
msw 1.x에서 사용하는 @mswjs/interceptors 라이브러리는 네이티브 fetch를 제대로 지원하지 않으며 아마도 앞으로도 지원하지 않을 것입니다. 네이티브 fetch를 사용하도록 전환하면, msw 기반 테스트가 트래픽을 캡처하고 차단하는 데 모두 실패하기 시작하는 것을 볼 수 있습니다. 일부 테스트는 더 새 버전의 인터셉터를 사용하는 msw 2.x 이상을 대신 사용하도록 다시 작성해야 할 수 있습니다.