이미 기술적으로는 충분히 가능하다고 보이지만, Spring Boot와 AWS를 메인으로 사용하던 조직에 변화를 만들려면 기존 기술 스택의 만족스러운 점들을 최대한 잃지 않으면서도 새로운 기술 스택이 가져오는 장점이 충분히 크다는 것을 보여야 합니다.

백엔드의 비즈니스 로직을 IoC(Inversion of Control) 컨테이너로 관리하는 것도 그 중 하나입니다. Spring을 통해 유지하던 백엔드 비즈니스 로직의 낮은 복잡도를 Next.js를 사용하면서도 그대로 유지할 수 있을지 탐구중이고, 그 과정에서 Node.js 생태게의 IoC 컨테이너중 하나인 inversify의 타입 안전성을 강화할 수 있는 inversify-typesafe 라이브러리를 작성해서 소개글을 적습니다.

2026.06.02 추가) 이 라이브러리를 실전에 적용해본 후기입니다: Next.js 풀스택 서버리스로 구현한 정산 데이터 전처리 시스템 개발 후기: inversify-typesafe로 프로젝트 복잡도 제어하기

들어가며

2014년에 AWS Lambda가 등장하면서 Serverless 컴퓨팅이 산업적으로 주목받기 시작했습니다. 2018년에는 Amazon Aurora Serverless v1이 릴리즈되었고, 2021년 말에는 PlanetScale처럼 개발자 경험을 극대화한 Serverless RDBMS(Relational Database Management System)가 등장해서 커뮤니티의 관심을 받았습니다.

Next.js는 등장부터 풀 스택 리액트 프레임워크로 주목을 받았고, 이제는 다양한 Serverless Edge Hosting 업체들(Vercel, Cloudflare, Netlify 등)을 통해서 풀 스택 리액트 애플리케이션을 간단하게 배포할 수 있는 세상이 되었습니다(opennext를 사용해야 하지만... 최근에는 플랫폼-중립적인 tanstack-start가 충분히 안정화가 되면서 상용 제품에 써도 큰 문제가 없을 것 같습니다).

Serverless RDBMS와 Serverless Edge Hosting은 이미 상용 제품에 활발이 사용되고 있습니다. 이 둘을 함께 활용하면 전형적인 웹 애플리케이션의 인프라에 필요한 노력을 극단적으로 줄일 수 있습니다. 예를 들어, 별도의 백엔드 API 서버 없이 Next.js의 백엔드에서 Serverless DB에 직접 커넥션을 맺고 데이터를 가져오는 것은 물론 Next.js의 백엔드를 그저 BFF(Backend for Frontend)가 아니라 백엔드 API를 제공하기 위한 프레임워크로도 사용할 수 있습니다 (기술적으로 가능하지만 권장하지 않습니다. Hono같이 Serverless를 타겟으로 하는 프레임워크가 성능과 DX 모두 훨씬 낫습니다).

만약 상용 제품을 Next.js만 사용해서 구현한다면, 저장소 하나에 백엔드와 프론트엔드 코드를 같이 관리해야하므로 시스템의 복잡도는 기하급수로 올라가갑니다. 객체지향 세상에선 이미 IoC(Inversion of Control) 컨테이너가 복잡도를 통제하기 위한 표준적인 도구로 사용되고 있고 Node.js 생태계에도 NestJS나 InversifyJS같은 훌륭한 IoC 컨테이너 라이브러리가 존재합니다

웹 관련 기능은 Next.js가 담당할 것이기 때문에 이 상황에서는 다른 부가 기능 없이 단순히 IoC 기능만 제공할 수 있는 컨테이너만 있으면 됩니다. NestJS에서 웹 부분을 제외하고 DI 기능만 쓸 수 있지만(https://docs.nestjs.com/faq/serverless#using-standalone-application-feature), 번들 크기가 inversify보다 3배 무겁고 (inversify: 57.9kB, @nestjs/core: 189.2kB) 제게 필요했던 기능이 Inversify만으로 충분히 제공되기 때문에 Next.js로 구성한 백엔드의 복잡도를 통제하기 위한 도구로 inversify를 골라 이것저것 실험을 해보고 있습니다.

Inversify는 그 자체로 이미 훌륭하지만, 사용해보니 타입 선언을 조금만 개선하면 타입스크립트의 기능을 활용해 타입-안전하게 의존성 주입을 할 수 있을 것 같아서 라이브러리를 작성했습니다: inversify-typesafe

inversify의 기본 예제 살펴보기

아래는 inversify가 제공하는 Dependency Inversion 예제입니다.

import { Container, inject, injectable, ServiceIdentifier } from 'inversify';

interface Weapon {
  damage: number;
}

// symbol은 Node.js의 원시타입중 하나. 이 예제에서는 문자열과 유사하다고 생각해도 충분하다.
const ninjaServiceId: ServiceIdentifier<Ninja> = Symbol.for('NinjaServiceId');
const weaponServiceId: ServiceIdentifier<Weapon> = Symbol.for('WeaponServiceId');

@injectable()
class Katana implements Weapon {
  public readonly damage: number = 10;
}

@injectable()
class Ninja {
  constructor(
    // JVM에서는 런타임에도 타입 정보가 살아있으므로, 어떤 인터페이스의 구현체가 인스턴스가 하나만 등록되어 있다면
    // 컴포넌트의 인스턴스를 주입받기 위해 따로 이름을 입력하지 않아도 인스턴스 주입이 가능하다.
    // 그러나 타입스크립트는 런타임에 타입 정보가 사라지므로 어떤 인터페이스의 구현체 인스턴스가 하나만
    // 등록되어 있더라도 주입받을 인스턴스에 대한 이름(혹은 ID)을 필수로 입력해야 한다.
    // 이 예제에서는 런타임에 Weapon 인스턴스의 타입 정보를 사용할 수 없으므로 weaponServiceId라는 값을 사용한다.
    @inject(weaponServiceId)
    public readonly weapon: Weapon, // 구현체 대신 인터페이스를 의존 (Dependency Inversion)
  ) {}
}

const container: Container = new Container();

// 서비스 ID와 구현체를 매핑
container.bind(ninjaServiceId).to(Ninja);
container.bind(weaponServiceId).to(Katana);

// 특정 bean을 요청했을 때 인스턴스를 생성해서 제공한다 (lazy).
const ninja: Ninja = container.get(ninjaServiceId);

console.log(ninja.weapon.damage);

(Demo: https://stackblitz.com/edit/inversify-di)

이대로도 나쁘지 않지만, 타입스크립트를 더 잘 활용하면 더 나은 코드를 작성할 수 있지 않을까요?

예를 들어

1. 컨테이너에서 서비스를 조회할 때 서비스 ID만 입력해도 자동으로 타입이 추론된다면?
2. 컨테이너에 등록되지 않은 서비스 ID를 입력했을 때 컴파일 에러가 발생한다면?
3. 서비스를 주입받을 때 등록되지 않은 서비스 ID를 입력하면 컴파일 에러가 발생한다면?

inversify-typesafe 라이브러리를 작성하다

Inversify 컨테이너의 타입-안전성을 강화하기 위해 간단한 라이브러리를 작성했습니다: inversify-typesafe

실행 가능한 Demo: https://stackblitz.com/edit/inversify-typesafe

import { createTypesafeContainer, returnTypesafeInject, TypesafeServiceConfig } from "inversify-typesafe";

// https://inversify.io/docs/introduction/dependency-inversion/
interface Weapon {
  damage: number;
}

class Katana implements Weapon {
  public readonly damage: number = 10;
}

export const typesafeInject = returnTypesafeInject<Services>()

class Ninja {
  constructor(
    // decorator의 parameter가 존재하지 않는 서비스 ID면 컴파일에러 발생
    @typesafeInject("weaponServiceId")
    public readonly weapon: Weapon,
  ) { }
}

export type Services = {
  "ninjaServiceId": Ninja; // class
  "weaponServiceId": Weapon; // interface
};

export const serviceConfig: TypesafeServiceConfig<Services> = {
  // 'Ninja'와 호환되지 않는 서비스를 바인딩하려고 하면 컴파일 에러 발생
  "ninjaServiceId": (bind) => bind().to(Ninja),
  // 'Weapon'과 호환되지 않는 서비스를 바인딩하려고 하면 컴파일 에러 발생
  // 두 번째 파라미터인 _container를 활용해서 복잡한 바인딩을 수행할 수 있다
  "weaponServiceId": (bind, _container) => bind().to(Katana),
};

// 컨테이너를 생성할 때 타입 정보를 따로 입력하지 않아도 추론해서 사용한다
const typesafeContainer = createTypesafeContainer(serviceConfig);

// 서비스 ID를 입력하면 자동으로 타입 추론을 한다.
console.log(typesafeContainer.get("ninjaServiceId").weapon.damage);

구현 철학

inversify-typesafe를 구현하면서 다음과 같은 점들을 고려했습니다:

1. 라이브러리는 타입-안전성을 위해 특정한 서비스 등록 방식을 강제하지만, InversifyJS의 기능을 제한해서는 안 된다.
2. 라이브러리 사용자는 원할 때 언제든지 InversifyJS의 모든 기능을 사용할 수 있어야 한다.
3. 위 두 가지 원칙을 지키면서 사용자의 실수를 가능한 한 컴파일 타임에 잡아야 한다.
4. 라이브러리 사용자가 선언해야 하는 타입은 최소화해야 한다.

장점

• 컨테이너에 문자열 서비스 ID를 입력하면 추가적인 타입 작성 없이 등록된 타입을 자동으로 추론합니다.
• 서비스를 찾기 위해 get 메서드에 문자열을 입력할 때, 코드 편집기의 자동 완성을 통해 등록된 서비스 ID를 확인할 수 있습니다.
• 컨테이너에 등록되지 않은 서비스 ID를 입력하면 컴파일 에러가 발생합니다.
• 서비스를 주입할 때 등록되지 않은 서비스 ID를 입력하면 컴파일 에러가 발생합니다.
• 추가적인 peer depepdency가 없습니다. 오직 inversify와 reflect-metadata만 있으면 됩니다.
• 100% 테스트 커버리지.

사용법

1. Services 맵 타입 선언

export type Services = {
  "ninjaServiceId": Ninja; // class
  "weaponServiceId": Weapon; // interface
};

사용자는 컨테이너에 등록될 서비스를 선언하기 위해 Services(또는 원하는 이름) 맵 타입을 작성해야 합니다. Services 타입의 키는 서비스 ID로 사용됩니다. InversifyJS는 다양한 타입(class, symbol 등)을 서비스 ID로 등록하지만, inversify-typesafe는 오직 string 타입만을 서비스 ID로 사용합니다. string을 사용함으로써 TypeScript의 String Literal Types 기능을 활용하여 마법 같은 타입 안전성을 제공할 수 있습니다.

2. 서비스 설정 작성

import { TypesafeServiceConfig } from "inversify-typesafe";

export const serviceConfig: TypesafeServiceConfig<Services> = {
  "ninjaServiceId": (bind) => bind().to(Ninja),
  "weaponServiceId": (bind, _container) => bind().to(Katana),
};

이 라이브러리는 TypesafeServiceConfig<T>라는 유틸리티 타입을 제공합니다. TypesafeServiceConfig<T>는 타입 T의 키를 서비스 ID로 사용하도록 강제합니다. 앞서 선언한 Services 타입을 TypesafeServiceConfig의 타입 매개변수로 전달하면 Services 타입의 키만 사용할 수 있도록 제한됩니다. Services에 존재하지 않는 키를 입력하거나 Services의 모든 키에 대한 함수를 제공하지 않으면 컴파일 에러가 발생하여 사용자가 더 안전하게 코드를 작성할 수 있게 합니다.

객체의 값은 사용자가 Inversify의 모든 바인딩 기능을 활용할 수 있도록 람다를 사용합니다. 람다는 첫 번째 매개변수로 bind, 두 번째 매개변수로 container를 받습니다. 첫 번째 매개변수 bind는 서비스 ID를 컨테이너에 바인딩하기 위한 thunk () => container.bind(serviceId)입니다. 객체의 키를 서비스 ID로 바인딩하는 thunk가 매개변수로 전달되므로, 사용자는 서비스 ID에 서비스를 어떻게 매핑할지 선택할 수 있습니다(bind().to(Service)). 사용자가 Services 타입 선언과 호환되지 않는 서비스를 매핑하려고 하면 컴파일 에러가 발생합니다.

람다의 두 번째 매개변수는 container를 받습니다. 간단한 경우에는 첫 번째 매개변수 bind만 사용해도 충분하지만, 서비스 등록 과정에서 컨테이너에 직접 접근해야 하는 경우 두 번째 매개변수를 활용할 수 있습니다.

3. 타입 안전한 컨테이너 생성

import { createTypesafeContainer } from "inversify-typesafe";

const typesafeContainer = createTypesafeContainer(serviceConfig);

createTypesafeContainer() 함수는 TypesafeServiceConfig<T> 타입의 인수를 받아 TypesafeContainer<T>를 반환합니다. 사용자는 제네릭 타입 매개변수를 수동으로 지정할 필요가 없습니다.

4. 서비스 가져오기

const ninjaService = typesafeContainer.get("ninjaServiceId");

사용자가 선언한 Services 타입의 키를 인수로 전달하면 바인딩된 서비스가 반환됩니다. 반환 타입은 추가적인 타입 작성 없이 잘 추론되며, 코드 편집기의 자동 완성을 통해 등록된 서비스 ID를 확인할 수 있습니다.

Services의 키가 아닌 값을 입력하면 컴파일 에러가 발생합니다.

5. 서비스 주입하기

import { returnTypesafeInject } from "inversify-typesafe";

export const typesafeInject = returnTypesafeInject<Services>()

class Ninja {
  constructor(
    @typesafeInject("weaponServiceId")
    public readonly weapon: Weapon,
  ) { }
}

사용자가 선언한 Services 타입을 타입 매개변수로 하여 고계 함수 returnTypesafeInject<T>()를 호출하면 데코레이터 함수가 반환됩니다. 이 데코레이터의 매개변수에 Services 타입의 키가 아닌 값을 입력하면 컴파일 에러가 발생합니다.

6. 모든 InversifyJS 기능 사용 가능

import { ServiceIdentifier } from "inversify";

const ninjaService = typesafeContainer._get("ninjaServiceId" as ServiceIdentifier<Ninja>);

TypesafeContainer<T> 타입의 _get 메서드는 기존 Container 타입의 get 메서드와 동일한 기능을 수행합니다. 타입 안전성이 강화된 기능이 아닌 원래의 get 메서드가 필요할 때 _get 메서드를 사용할 수 있습니다.

get 메서드를 제외한 모든 메서드는 InversifyJS Container 타입과 동일합니다.

조금 더 Spring과 비슷하게: inversify-typesafe-spring-like

InversifyJS의 scope 기본값은 Request입니다. 컨테이너의 get 함수를 호출할 때마다 새로운 객체를 생성합니다.

웹 백엔드 환경에서는 특별한 경우가 아니라면 한 번 생성한 인스턴스를 재활용하므로 기본 scope 값을 Singleton으로 사용하는게 보통이고, Spring의 IoC 컨테이너의 기본 scope도 Singleton입니다.

inversify-typesafe-spring-like 라이브러리는 inversify-typesafe 라이브러리를 확장해서 Spring Framework와 유사한 DX(Developer Experience)를 제공하는 간단한 라이브러리입니다.

라이브러리의 API는 Spring의 용어를 반영하여 설계했습니다:

1. createTypesafeContext() -> ApplicationContext()
   • Note: defaultScope는 기본적으로 Singleton으로 설정됩니다.
2. returnTypesafeInject() -> returnAutowired()
3. TypesafeServiceConfig<T> -> BeanConfig<T>

기본 scope와 용어 변경 외에는 inversify-typesafe와 동일합니다.

실행 가능한 Demo: https://stackblitz.com/edit/inversify-typesafe-spring-like

import { ApplicationContext, BeanConfig, returnAutowired } from "inversify-typesafe-spring-like";

interface Article {
  id: number;
  title: string;
  content: string;
}

interface ArticleOutgoingPort {
  getById(id: number): Promise<Article>
}

class ArticleRepository implements ArticleOutgoingPort {
  getById(id: number): Promise<Article> {
    return Promise.resolve({
      id: id,
      title: `title #${id}`,
      content: `content #${id}`,
    })
  }
}

interface GetArticleUseCase {
  execute(id: number): Promise<Article>
}

const { Autowired } = returnAutowired<Beans>();

class ArticleQueryService implements GetArticleUseCase {
  constructor(
    @Autowired("ArticleOutgoingPort") // compile error if a parameter of @Autowired is not a key of Beans.
    private readonly articleOutgoingPort: ArticleOutgoingPort,
  ) { }
  execute(id: number): Promise<Article> {
    return this.articleOutgoingPort.getById(id);
  }
}

type Beans = {
  GetArticleUseCase: GetArticleUseCase; // interface (class is also possible)
  ArticleOutgoingPort: ArticleOutgoingPort; // interface (class is also possible)
}

const beanConfig: BeanConfig<Beans> = {
  // compile error if ArticleQueryService is not compatible with GetArticleUseCase.
  GetArticleUseCase: (bind) => bind().to(ArticleQueryService),
  // compile error if ArticleRepository is not compatible with ArticleOutgoingPort.
  ArticleOutgoingPort: (bind) => bind().to(ArticleRepository), 
}

const applicationContext = ApplicationContext(beanConfig);

const getArticleUseCase = applicationContext.get("GetArticleUseCase")

getArticleUseCase.execute(1).then(console.log)

마무리

제 개인 블로그(https://myeongjae.kim/)와 회사의 프로젝트에서 inverisfy-typesafe를 적극적으로 사용하고 있습니다. 최근에는 연 1,400억 원 규모의 매출을 올리는 국내 콘텐츠 회사의 정산 데이터 전처리 시스템을 Next.js로 구현하면서 이 라이브러리를 활용해 백엔드의 복잡도를 성공적으로 통제했습니다.

개인 블로그의 프레임워크를 tanstack-start로 교체하면서도, inversify로 보호하던 core 레이어는 코드 변경 없이 프레임워크 교체를 완료했습니다.

타입스크립트와 서버리스 환경의 장점을 취하면서도 의존성 주입을 활용하고 싶으신 분들에게 적극 추천 드립니다.

• inversify-typesafe
• inversify-typesafe-spring-like

안녕하세요, 디어코퍼레이션의 김명재입니다.

토이프로젝트가 아닌 실제 제품에 Next.js App Router를 사용해보셨나요? 이번에 저희 회사에서 웹 애플리케이션을 새로 셋팅할 필요가 생겼고 저는 과감하게 Next.js의 App Router를 선택했습니다(회사에서는 기존 제품에도 Next.js를 사용하고 있었고 저도 5년째 사용하고 있습니다). 이 글에서는 App Router를 선택한 배경과 App Router에서 fetch를 사용하기 위해 어떻게 정든 Axios를 떠나보냈는지를 중심 주제로 다룹니다.

Next.js App Router와 fetch

Next.js는 2022년 10월 25일 컨퍼런스에서 app directory를 발표했습니다. App directory는 기존의 Page Router를 대체합니다. 2023년 5월 4일 Next.js 13.4.0버전에서 app direoctry는 beta딱지를 벗고 stable이 되었습니다. 저희 회사에서 도입한 시점인 7월달엔 13.4.6버전이 릴리즈되어 있었고, stable 변경 이후 6번의 업데이트가 있었으니 이제 제품에 써봐도 괜찮을 것 같다는 느낌이었습니다(App directory는 13.2버전부터 App Router라는 이름으로 불리기 시작했습니다. 이하에서는 정식 명칭인 App Router로 적겠습니다).

그러나 느낌만으로 결정을 할 수는 없으니... 제품에 적용하기 전에 먼저 제가 9년째 유지보수하고 있는 제 블로그를 App Router로 다시 구현하면서 학습을 했습니다. 디렉토리 구성, 서버 사이드 렌더링, 비동기 호출(API 요청), 에러처리, 캐시 등 실제 제품을 구현할 때 고려해야 할 것들을 신경쓰며 학습을 했습니다. App Router를 사용한 블로그의 모든 기능이 문제없이 작동했고 App Router에 익숙해지면서 자신감이 생겼습니다.

App Router를 사용하면서 가장 강하게 들었던 느낌은 AppRouter가 Page Router보다 훨씬 더 서버 친화적으로 코드를 작성하도록 유도한다는 것이었습니다. 이전엔 클라이언트 렌더링을 위한 프레임워크에 서버쪽 기능을 추가한 느낌이었다면, App Router부터는 렌더링의 주도권이 완전히 서버쪽으로 넘어갔다는 느낌을 받았습니다. 옛날의 클래식한 웹 프레임워크의 향수가 느껴지는 그런 느낌. 하지만 모던한.

App Router 문서를 읽어보니 Next.js 서버쪽에서 캐싱 관련 기능을 fetch를 확장해서 제공하고 있고, fetch가 아닌 다른 라이브러리를 사용한다면 직접 캐싱 관련 설정을 해주어야 합니다.

현재 회사는 물론 일해왔던 회사들에서도 제품에 fetch가 아닌 Axios를 사용했었습니다. 지금까지 개발했던 제품들이 Axios의 번들 크기(11.2KB, minified + gzipped)도 허용하지 못할만큼 용량 최적화가 필요하진 않았기 때문입니다. 익숙한 Axios를 사용해서 빠르게 개발하는게 이제까지는 좋은 선택이었지만, 프레임워크에서 fetch를 쓰라고 하니 드디어 미루고 미뤘던 fetch를 학습해야 할 때가 온 것 같았습니다. Next.js에서 제공하는 fetch를 거부하고 굳이 Axios를 고집하면서 Next.js에 캐시 관련 설정을 수동으로 관리할 명분도 없었습니다.

fetch는 이런저런게 아쉬워요!

아래 항목들은 Axios에서 제공하지만 fetch에는 없어서 아쉽다고 느꼈던 기능들입니다.

1. baseUrl을 설정할 수 없다.
2. default header를 설정할 수 없다.
3. request, response interceptor가 없다.
4. json serialize, deserialize를 직접 해야 한다.

Axios는 인스턴스를 생성할 때 baseUrl과 default header를 설정하면 모든 요청에 대해서 url의 origin이 비어있는 경우 baseUrl을 origin으로 사용하고 default header를 넣어줍니다.

import axios from 'axios';

const axiosInstance = axios.create({
    baseURL: 'https://your-api-endpoint.com'
    headers: {
        'Accept': 'application/json',
    }
})

// https://your-api-endpoint.com/article 에
//  'Accept: application/json' 헤더가 붙어있는 get요청을 보낸다
axios.get('/article')

request interceptor는 요청을 보내기 전에, response interceptor는 요청을 받은 후에 실행합니다.

axiosInstance.interceptors.request.use(config => {
  // 매 요청마다 localStorgae의 토큰을 조회해서 헤더에 추가한다.
  config['Authorization'] = localStorage.getItem('token');
  return config;
})

axiosInstance.interceptors.request.use(undefined, error => {
  // Unauthorized 응답을 받으면 가지고 있던 토큰을 제거한다.
  if (error.isAxiosError && e.response?.status === 401) {
    localStorage.removeItem('token');
  }
})

Axios는 request config의 data에 object를 넣을 수 있고, response도 json이라면 자동으로 object로 만들어줍니다.

axiosInstance.post<{id: number}>('/create', {
  title: 'title',
  content: 'content'
})
  .then(response => response.data)
  .then(console.log)

// 출력 예시: {id: 1}. 문자열이 아니라 객체가 나온다.

Axios에 다른 여러가지 기능들도 있지만, 특히 이 4가지 기능이 없다면 모든 요청에 매번 같은 설정값을 넣어줘야 합니다. 변경사항이 생기기라도 하면 fetch함수를 호출할 때마다 같은 작업을 해야 하고, 혹시 뭔가를 빠뜨린다면 장애로 이어질 수도 있습니다.

누가 만들어놓지 않았을까?

저 혼자 Next.js를 쓰는 것도 아니고 저 혼자 fetch를 쓰는 것도 아니니 당연히 누군가 위 기능을 제공하는 라이브러리를 만들었을텐데요, 아래는 제가 찾은 솔루션들과 장단점들입니다.

1. fetch-intercept

https://www.npmjs.com/package/fetch-intercept

fetch와 interceptor관련 내용으로 검색을 하면 가장 먼저 찾을 수 있는 라이브러리입니다. 하지만 baseUrl과 default headers 기능을 제공하지 않고 전역에 선언되어있는 fetch를 몽키패치 해버리기 때문에 이 라이브러리를 선택할 수는 없었습니다.

Next.js에서 fetch를 사용하는 3가지 맥락

Next.js에서는 fetch를 다양한 맥락에서 사용하게 됩니다. 제 멘탈 모델에서는 크게 3가지가 있습니다.

1. 클라이언트 사이드(웹브라우저)에서 AJAX 요청
2. 서버 사이드에서 렌더링하기 위한 AJAX 요청
3. 서버 사이드에서 렌더링이 아니라 프록시 역할로 AJAX 요청을 하고 응답을 그대로 내보냄(route.ts 파일)

하나의 fetch에서 이 3가지 상황을 모두 대응하는건 좋은 선택이 아니므로 fetch-intercept는 기각입니다.

장점

• 가벼운 번들 사이즈 (762 Byte, minified + gzipped)

단점

• baseUrl 기능이 없다.
• default headers 기능이 없다.
• 전역에 선언된 fetch 에 몽키패치를 해버리기 때문에 모든 fetch 호출에 request, response interceptor가 적용된다. fetch를 다양한 맥락에서 사용해야 하는 Next.js에는 어울리지 않는다.

2. wretch

https://github.com/elbywan/wretch

wretch는 fetch-intercept보다 많은 기능을 제공합니다. baseUrl과 default header도 설정할 수 있습니다. interceptor도 middleware라는 이름으로 제공하고 있습니다. 전역 fetch를 건드리지 않고 wretch instance를 생성해서 사용하는 방식이기 때문에 side effect도 없어서 안심하고 사용할 수 있습니다.

하지만 Axios처럼 400이상의 응답 상태에 대해서 모두 에러를 던지기 때문에 Next.js 서버쪽에서 프록시 역할을 할 때 wretch는 적합하지 않습니다. 외부 서비스 API를 호출하고 응답을 그대로 반환하는 프록시 역할에 wretch를 사용한다면, 400이상의 응답 상태 때문에 던진 예외를 다시 잡아서 정상적인 Response 객체로 만들어서 return해야 하는데 그럴거면 그냥 원본의 fetch를 사용하는게 낫습니다.

// file: src/app/sample/api/[[...path]]/route.ts
// Next.js의 route.ts에서 fetch로 외부 서비스를 호출한다.
// 상태 코드에 따른 예외를 던지지 않기 때문에 Response를 그대로 클라이언트에 전달하기만 하면 된다.

import { NextRequest } from "next/server";  

const pathPrefix = "/sample/api";

export async function GET(request: NextRequest) {  
  const { nextUrl, method, headers } = request;  

  return fetch("https://postman-echo.com" + nextUrl.pathname.replace(pathPrefix, ""), {  
    method,  
    headers,  
  });  
}

게다가 wretch는 fetch와 호환되지 않는 자신만의 인터페이스를 가지고 있기 때문에 wretch 인스턴스를 생성할 때 뿐만 아니라 사용할 때도 wretch만의 인터페이스를 학습해야 한다는 점도 아쉬웠습니다. 위에서 이야기한 Next.js의 3가지 맥락을 하나의 라이브러리로 통합하지 못하고 파편화되는건 만족스럽지 않기 때문에 wretch도 선택할 수 없었습니다.

장점

• 다양한 기능 (baseUrl, default header, interceptor 모두 지원)
• 상대적으로 가벼운 번들 사이즈 (1.9KB, minified + gzipped)

단점

• Axios처럼 response status에 따라 에러를 던지기 때문에 Next.js의 route.ts에서 사용하려면 추가 조치가 필요하다. 그럴바엔 그냥 fetch를 쓰는게 낫다.
• wretch 인스턴스를 생성할 때 뿐만 아니라 사용할 때도 fetch와 호환되지 않는 자신만의 인터페이스를 가지고 있기 때문에 추가로 학습이 필요하다.

3. ofetch

https://github.com/unjs/ofetch

ofetch는 Nuxt.js에서 기본으로 사용하는 라이브러리입니다. wretch와 마찬가지로 다양한 기능을 제공하고 있기 때문에 기능만으로는 부족함이 없었고, 상태 코드에 따른 에러를 던지지 않게 설정할 수 있는 옵션도 제공하고 있습니다(https://github.com/unjs/ofetch/issues/207). wretch와는 다르게 자신만의 인터페이스를 정의한게 아니라 fetch 인터페이스의 호환을 유지하면서 추가 기능을 붙였기 때문에 wretch보다는 필요한 학습량도 적고, proxy역할을 할 때도 특별한 변환작업 없이 사용할 수 있습니다.

하지만 검색해봐도 ofetch를 Next.js의 App Router에서 사용해봤다는 레퍼런스가 없었기 때문에 만약 ofetch를 선택했더라면 Next.js와 잘 맞을지, 그리고 문제가 생겼을 때 트러블슈팅을 직접 해야한다는 것도 부담이었습니다.

번들 사이즈도 fetch-intercept, wretch에 비해 많이 컸습니다 (5KB). 제가 필요한건 그저 baseUrl과 default header 설정, 그리고 interceptor인데... 번들 사이즈는 큰 이슈는 아니었지만 그래도 아쉽긴 마찬가지였습니다.

장점

• 다양한 기능 (baseUrl, default header, interceptor 모두 지원)
• Next.js의 route.ts파일에서도 사용할 수 있도록 response 상태와 상관 없이 예외를 던지지 않고 응답을 전달할 수 있다.
• fetch와 호환되는 인터페이스를 가졌다.

단점

• Next.js에서 ofetch를 사용하는 레퍼런스가 부족하다. App Router도 새로운 기술인데 여기에 ofetch까지 얹어서 사용하기는 부담스럽다.
• 필요한 기능에 비해 번들 사이즈가 크다 (5KB)

쓸만한 라이브러리가 없다!

도저히 마음에 드는 라이브러리가 없어서 그냥 직접 만들었습니다(??)

사실은 라이브러리를 홍보하기 위해 작성한 글입니다

제가 원하던 기능은 딱 3가지(baseUrl, default headers, interceptors)였고 Next.js에서 제공하는 fetch 구현체를 사용할 수 있어야 했습니다. fetch관련 라이브러리중에 그나마 찾을 수 있었던게 위 3개의 라이브러리였고 모두 만족스럽지 않아서 그냥 직접 구현해서 쓰기로 했습니다. 복잡한 기능이 필요한게 아니었고, 처음부터 외부에 공개할 라이브러리를 만들려고 한 것도 아니었기 때문에 빠르게 만들었습니다.

라이브러리로 공개할 예정에 없던 코드

(fyi. 저희 회사는 반말을 사용하고 있습니다 😄 https://notion.deering.co/)

(스크린샷의 주석 2번 항목은 잘못 적혀있습니다. 'generic으로 response body type을 정하는 기능'도 함수 안에서 구현하려고 하다가 바깥에서 처리하도록 결정했는데 PR올릴 때는 주석이 아직 남아있었네요)

그저 내부용으로 사용하려고 했던, 1시간만에 만든 간단한 코드였습니다. 초기버전에서는 상태에 따른 예외처리 옵션도 설정할 수 있었지만 공개한 라이브러리에는 상태 코드에 따른 예외 처리 기능은 제거했습니다. 사용하시는 분들이 interceptor로 충분히 직접 구현하실 수 있기 때문입니다.

스크린샷의 returnCustomizedFetch는 간단한 고계함수(함수를 인수로 받거나 결과 값으로 반환하는 함수)입니다. 매개변수로 받은 defaultOptions가 적용된 fetch함수를 return합니다. fetch를 호출하기 전에 request interceptor에서 전처리를 하고 호출해서 받은 response를 response interceptor에서 후처리 합니다. return하는 함수는 fetch 함수와 완전히 같은 인터페이스를 갖습니다.

만들어놓고 보니 조금만 손보면 범용적으로 사용할 수 있어보였습니다. 초기 버전에서는 전역에 선언되어 있는 fetch를 직접 사용했지만, fetch를 defaultOptions 으로 받을 수 있다면 모든 환경에서 사용할 수 있는 코드를 만들 수 있을 것 같았습니다.

재귀적인 타입 선언, 무한으로 즐기는 interceptor

1. defaultOptions로 받은 fetch에 baseUrl, default headers, interceptor를 적용한 fetch함수를 return합니다.
2. 이 fetch함수를 다시 defaultOptions에 넣어서 새로운 기능을 추가합니다.
3. 2번에서 만든 함수를 다시 defaultOptions에 넣어서 새로운 기능을 추가합니다.
4. 3번에서 만든 함수를 다시...

전역에 선언된 fetch를 사용하는게 아니라 매개변수로 fetch를 받아서 사용한다면 코드는 외부 세계를 참조하지 않는 순수한 함수가 됩니다. 여기서 '순수한'이라는 의미는 함수형 프로그래밍의 관점에서 순수하다는 의미인데, 함수가 스코프 바깥 세계를 참조하지 않기 때문에 같은 매개변수를 넣으면 언제나 동일한 fetch함수를 return한다는 뜻입니다.

fetch를 return하는 함수가 매개변수로 fetch를 받는 재귀적인 타입 구조는 사용자가 원하는 만큼 필요할 때마다 fetch를 쉽게 확장할 수 있게 해줍니다. 뭔가 아름다운 구조를 만든 것 같아서 저는 신나서 PR을 올렸습니다.

스크린샷의 fetchOnClient는 3가지 기능을 합성한 fetch함수입니다.

export const fetchOnClient = returnFetchForDeerBackend({
  fetch: returnFetchThrowingErrorByStatusCode({
    fetch: returnFetchWithLoader({
      headers: defaultHeaders,
      baseUrl: ENV.NEXT_PUBLIC_BASE_URL,
    }),
  }),
});

1. 비동기 요청을 보내기 전에 로딩화면을 보여주고 요청이 끝나면 로딩화면을 제거합니다.
2. 400이상의 상태를 받았을 때 예외를 던집니다.
3. response body에서 특정한 필드를 추출합니다.

만들어놓고 보니 returnFetch함수는 지금까지 배우고 경험했던 코드에 비추어 봤을 때 부끄럽지 않은 코드였고, 아직 한국에서 Next.js의 App Router가 대중화된 상황은 아니니 라이브러리로 만들어 공개한다면 한국의 Next.js 생태계에 기여할 수 있을 것 같았습니다. 그래서 공개합니다: return-fetch

return-fetch 한 번 맛보세요!

위에서 말씀드렸듯이 return-fetch는 Next.js의 클라이언트 사이드와 서버 사이드에서 모두 사용할 수 있는 fetch 확장 라이브러리를 찾다 찾다 못 찾아서 직접 구현한 라이브러리입니다. 딱 필요한 3가지 기능만을 구현하면서 다른 라이브러리들이 가진 단점을 모두 제거했습니다.

실제 코드는 여기서 볼 수 있습니다: https://github.com/deer-develop/return-fetch/blob/main/src/index.ts#L148. 짧고 간단한 코드지만 이 코드 덕분에 저는 Axios 없이도 빠르게 제품 개발을 할 수 있었습니다. 이 코드를 작성하면서 중요하게 생각했던 것들과 어떻게 응용할 수 있는지 자세하게 말씀드리겠습니다.

return-fetch의 핵심 철학

1. 딱 3가지 기능만 구현합니다
   • baseUrl, default headers, interceptors
2. 아무런 라이브러리를 의존하지 않고 오직 타입스크립트만 사용합니다.
3. LSP(Liskov substitution principle) 를 지킵니다.
   • 기존에 fetch를 사용하고 있던 모든 곳을 return-fetch로 교체하더라도 문제없이 작동합니다.
4. 사용자가 interceptor를 쉽게 추가할 수 있어야 합니다.
5. 사용자가 SRP(Single responsibility principle) 를 지킬 수 있어야 합니다.
   • 사용자가 직접 한 번에 하나의 기능을 제공하는 interceptor를 작성하고, interceptor가 적용된 fetch를 조합하면서 원하는 기능이 적용된 fetch를 생성할 수 있습니다.

어떻게 쓰나요?

return-fetch는 fetch함수를 return하는 함수입니다. 매개변수로 baseUrl, default header와 interceptor를 받아서 기본값이 적용된 fetch함수를 만듭니다.

import returnFetch from "return-fetch";

const fetchExtended = returnFetch({
  baseUrl: "https://jsonplaceholder.typicode.com",
  headers: { Accept: "application/json" },
  interceptors: {
    request: async (args) => {
      console.log("********* before sending request *********");
      console.log("url:", args[0].toString());
      console.log("requestInit:", args[1], "\n\n");
      return args;
    },

    response: async (response, requestArgs) => {
      console.log("********* after receiving response *********");
      console.log("url:", requestArgs[0].toString());
      console.log("requestInit:", requestArgs[1], "\n\n");
      return response;
    },
  },
});

fetchExtended("/todos/1", { method: "GET" })
  .then((it) => it.text())
  .then(console.log);

returnFetch의 return값인 fetchExtended를 fetch대신 사용하면 됩니다. fetchExtended는 fetch와 완전히 동일한 인터페이스(매개변수와 리턴타입)를 갖기 때문에 기존에 사용하던 fetch처럼 그대로 사용하면 됩니다.

위 예제는 API요청을 보내기 전에 request interceptor에서 로그를 출력하고, API요청의 응답을 받은 후에 repsonse interceptor에서 로그를 출력합니다. request interceptor의 매개변수는 baseUrl과 default header가 적용된 상태입니다.

request interceptor의 return값을 API요청할 때 사용하기 때문에 요청을 보내기 전에 request interceptor에서 요청에 대한 전처리를 할 수 있고, response interceptor의 return값이 fetchExtended함수의 return값이 되기 때문에 response interceptor에서 응답에 대한 후처리를 할 수 있습니다.

https://stackblitz.com/edit/return-fetch 여기에서 실제로 라이브러리를 사용해보실 수 있습니다.

return-fetch의 장단점

장점

• 가볍습니다 (733Byte, minified + gzipped)
• fetch가 있는 어떤 실행환경에서도 사용할 수 있습니다 (Node.js, 웹브라우저, React Native, Web Worker 등등).
• 모든 fetch polyfill과 호환됩니다.
• Side effect가 없습니다. 전역 fetch를 건드리지 않습니다. 외부 세계의 상태를 바꾸지 않으므로 안심하고 사용할 수 있습니다.
• 재귀적인 타입 선언 덕분에 특별한 처리 없이도 interceptor를 원하는 만큼 추가할 수 있습니다.
• 테스트 커버리지 100%를 유지합니다. 모든 기능을 테스트했습니다.
• Next.js App Router환경에서 잘 작동합니다. Next.js를 사용하시는 분들이라면 마음놓고 쓰셔도 됩니다.

단점

• 뼈대만 제공합니다. 필요한 기능이 있다면 직접 구현해야 합니다.
  • baseUrl과 default header 기능도 request interceptor로 직접 구현할 수 있지만, 이 두 가지 기능은 정말 많이 쓰이기 때문에 편의상 구현해놨습니다.
• 신규 라이브러리라서 쓰는 사람이 별로 없습니다(😢).

필요한 기능이 있나요? 제가 만들어놨습니다.

이렇게 작고 간단한 라이브러리로 뭘 할 수 있을까요? 제가 원하는 기능은 모두 다 만들 수 있었습니다.

예를 들어서

1. 요청 보내기 전에 로딩 화면을 띄우고 요청 보낸 후에 로딩 화면을 제거하기
2. 응답으로 400이상의 상태를 받았을 때 에러를 던지기
3. request body를 string이 아니라 json으로 받고, response body도 json으로 return하는 fetch함수 만들기
4. 401응답을 받았을 때 쿠키를 제거하고 요청을 다시 한 번 보내기
5. returnFetch 를 사용하는 함수를 조합해서 기능 합치기
6. 전역 fetch 교체하기

이 정도가 있습니다. 필요한 게 있으시면 https://github.com/deer-develop/return-fetch/issues 이슈에 올려주세요! 제가 한 번 만들어 보겠습니다 😎

1. 요청 보내기 전에 로딩 화면을 띄우고 요청 보낸 후에 로딩 화면을 제거하기

간단한 예제입니다. returnFetch와 동일한 타입의 함수인 returnFetchWithLoadingIndicator가 return하는 함수를 fetch대신 사용하면 됩니다.

import returnFetch, { ReturnFetch } from "return-fetch";
import { displayLoadingIndicator, hideLoadingIndicator } from "@/your/adorable/loading/indicator";

// Write your own high order function to display/hide loading indicator
const returnFetchWithLoadingIndicator: ReturnFetch = (args) => returnFetch({
  ...args,
  interceptors: {
    request: async (args) => {
      setLoading(true);
      return args;
    },
    response: async (response) => {
      setLoading(false);
      return response;
    },
  },
})

// Create an extended fetch function and use it instead of the global fetch.
export const fetchExtended = returnFetchWithLoadingIndicator({
  // default options
});

https://return-fetch.myeongjae.kim/#1-displayhide-loading-indicator 여기에서 위 코드를 직접 실행해보실 수 있습니다.

다만 실제로 저 코드를 사용하게 되면 API를 호출할 때마다 로딩화면이 깜빡거려서 거슬리는 느낌을 받습니다. 저희 제품에는 응답 지연시간이 200ms 이상일 때만 로딩화면이 보이도록 조치해서 사용하고 있습니다(이 기능도 역시 returnFetch로 구현했습니다).

2. 응답으로 400이상의 상태를 받았을 때 에러를 던지기

import returnFetch, { ReturnFetch } from "return-fetch";

// Write your own high order function to throw an error if a response status is more than or equal to 400.
const returnFetchThrowingErrorByStatusCode: ReturnFetch = (args) => returnFetch({
  ...args,
  interceptors: {
    response: async (response) => {
      if (response.status >= 400) {
        throw await response.text().then(Error);
      }

      return response;
    },
  },
})

// Create an extended fetch function and use it instead of the global fetch.
export const fetchExtended = returnFetchThrowingErrorByStatusCode({
  // default options
});

https://return-fetch.myeongjae.kim/#2-throw-an-error-if-a-response-status-is-more-than-or-equal-to-400 여기에서 위 코드를 직접 실행해보실 수 있습니다.

3. request body를 string이 아니라 json으로 받고, response body도 json으로 return하는 fetch함수 만들기

Axios처럼 response body의 타입을 generic으로 지정할 수 있습니다. 아래 코드는 별도의 패키지 공개했습니다: return-fetch-json

import returnFetch, { FetchArgs, ReturnFetchDefaultOptions } from "return-fetch";

// Use as a replacer of `RequestInit`
type JsonRequestInit = Omit<NonNullable<FetchArgs[1]>, "body"> & { body?: object };

// Use as a replacer of `Response`
export type ResponseGenericBody<T> = Omit<
  Awaited<ReturnType<typeof fetch>>,
  keyof Body | "clone"
> & {
  body: T;
};

export type JsonResponse<T> = T extends object
  ? ResponseGenericBody<T>
  : ResponseGenericBody<unknown>;


// this resembles the default behavior of axios json parser
// https://github.com/axios/axios/blob/21a5ad34c4a5956d81d338059ac0dd34a19ed094/lib/defaults/index.js#L25
const parseJsonSafely = (text: string): object | string => {
  try {
    return JSON.parse(text);
  } catch (e) {
    if ((e as Error).name !== "SyntaxError") {
      throw e;
    }

    return text.trim();
  }
};

// Write your own high order function to serialize request body and deserialize response body.
export const returnFetchJson = (args?: ReturnFetchDefaultOptions) => {
  const fetch = returnFetch(args);

  return async <T>(
    url: FetchArgs[0],
    init?: JsonRequestInit,
  ): Promise<JsonResponse<T>> => {
    const response = await fetch(url, {
      ...init,
      body: init?.body && JSON.stringify(init.body),
    });

    const body = parseJsonSafely(await response.text()) as T;

    return {
      headers: response.headers,
      ok: response.ok,
      redirected: response.redirected,
      status: response.status,
      statusText: response.statusText,
      type: response.type,
      url: response.url,
      body,
    } as JsonResponse<T>;
  };
};

// Create an extended fetch function and use it instead of the global fetch.
export const fetchExtended = returnFetchJson({
  // default options
});

//////////////////// Use it somewhere ////////////////////
export type ApiResponse<T> = {
  status: number;
  statusText: string;
  data: T;
};

fetchExtended<ApiResponse<{ message: string }>>("/sample/api/echo", {
  method: "POST",
  body: { message: "Hello, world!" }, // body should be an object.
}).then(it => it.body);

약간 길지만 기본적인 구현은 이전 예제들과 동일합니다. https://return-fetch.myeongjae.kim/#3-serialize-request-body-and-deserialize-response-body 여기에서 실행해볼 수 있습니다.

4. 401응답을 받았을 때 쿠키를 제거하고 요청을 다시 한 번 보내기

let retryCount = 0;

const returnFetchRetry: ReturnFetch = (args) => returnFetch({
  ...args,
  interceptors: {
    response: async (response, requestArgs, fetch) => {
      if (response.status !== 401) {
        return response;
      }

      console.log("not authorized, trying to get refresh cookie..");
      const responseToRefreshCookie = await fetch(
        "https://httpstat.us/200",
      );
      if (responseToRefreshCookie.status !== 200) {
        throw Error("failed to refresh cookie");
      }

      retryCount += 1;
      console.log(`(#${retryCount}) succeeded to refresh cookie and retry request`);
      return fetch(...requestArgs);
    },
  },
});

const fetchExtended = returnFetchRetry({
  baseUrl: "https://httpstat.us",
});

fetchExtended("/401")
  .then((it) => it.text())
  .then((it) => `Response body: "${it}"`)
  .then(console.log)
  .then(() => console.log("\n Total counts of request: " + (retryCount + 1)))

response interceptor에서 응답을 확인하고 상태가 401이라면 retry를 합니다. https://return-fetch.myeongjae.kim/#8-retry-a-request 여기에서 실행해보실 수 있습니다.

5. returnFetch 를 사용하는 함수를 조합해서 기능 합치기

제가 returnFetch에서 가장 좋아하는 기능입니다. 이전 예제들은 각각 하나의 기능만 구현했는데, 만약 로딩 화면도 보여주고싶고 상태가 400이상일 때 에러도 던지고싶고 request, response body를 객체로 사용하고 싶으면 어떻게 해야 할까요?

코드를 다시 작성할 필요 없이 위 함수들을 재활용해서 조합하면 됩니다.

import {
  returnFetchJson,
  returnFetchThrowingErrorByStatusCode,
  returnFetchWithLoadingIndicator
} from "@/your/customized/return-fetch";

/*
  Compose high order functions to create your awesome fetch.
   1. Add loading indicator.
   2. Throw an error when a response's status code is 400 or more.
   3. Serialize request body and deserialize response body as json and return it.
*/
export const fetchExtended = returnFetchJson({
  fetch: returnFetchThrowingErrorByStatusCode({
    fetch: returnFetchWithLoadingIndicator({
      // default options
    }),
  }),
});

//////////////////// Use it somewhere ////////////////////
fetchExtended("/sample/api/echo", {
  method: "POST",
  body: { message: "Hello, world!" }, // body should be an object.
}).catch((e) => { alert(e.message); });

https://return-fetch.myeongjae.kim/#4-compose-above-three-high-order-functions-to-create-your-awesome-fetch- 여기에서 실행해보실 수 있습니다.

returnFetch는 매개변수로 fetch함수를 받을 수 있습니다. returnFetch의 return값은 fetch함수의 인터페이스와 동일하기 때문에 fetch대신 사용할 수 있으므로 returnFetch의 매개변수에 자리에도 들어갈 수 있습니다. returnFetch는 기능이 추가된 fetch를 계속 감싸면서 기능을 덧붙일 수 있습니다.

특별한 처리 없이 재귀적인 타입 선언만으로 복수의 interceptor를 처리할 수 있는 것이 returnFetch의 최대 장점입니다. 위에서 보시는 것처럼 하나의 기능만 추가하는 함수를 작성해서 하나의 책임만 지도록 할 수 있기 때문에 returnFetch의 사용자는 단일 책임 원칙(Single Responsibility Principle)을 지킬 수 있습니다. 라이브러리에서 별도의 interceptor 중첩 처리를 하지 않기 때문에 번들 사이즈도 작게 유지할 수 있었습니다.

6. 전역 fetch 교체하기

returnFetch는 리스코프 치환 원칙(Liskov substitution principle)을 만족하기 때문에 returnFetch가 생성한 함수를 전역 fetch대신 사용할 수 있습니다. 전역 fetch를 사용하는 모든 곳에서 로딩 화면을 보여주고 400이상의 응답을 받았을 때 예외를 던지고 싶다면 아래처럼 함수를 조합하고 fetch를 덮어씌우면 됩니다.

import {
  returnFetchJson,
  returnFetchThrowingErrorByStatusCode,
  returnFetchWithLoadingIndicator
} from "@/your/customized/return-fetch";

// save global fetch reference.
const globalFetch = globalThis.fetch;
export const fetchExtended = returnFetchThrowingErrorByStatusCode({
  fetch: returnFetchWithLoadingIndicator({
    fetch: globalFetch, // use global fetch as a base.
  }),
});

// replace global fetch with your customized fetch.
globalThis.fetch = fetchExtended;

전역 공간을 건드리는 행위는 절대 추천하지 않습니다. 하지만 꼭 필요한 순간도 있을테니, 그 때도 returnFetch를 문제없이 사용할 수 있습니다.

Next.js에서 return-fetch를 어떻게 사용하면 좋을까요?

위에서 말씀드린 것처럼 Next.js에서 API요청을 하는 3가지 맥락이 있습니다.

1. 클라이언트 사이드(웹브라우저)에서 AJAX 요청
2. 서버 사이드에서 렌더링하기 위한 AJAX 요청
3. 서버 사이드에서 렌더링이 아니라 프록시 역할로 AJAX 요청을 하고 응답을 그대로 내보냄(route.ts 파일)

1. 클라이언트 사이드(웹브라우저)에서 AJAX 요청

클라이언트 사이드에서 AJAX 요청을 할 때는 3가지 기능을 추가해서 사용하고 있습니다.

1. 요청을 보내기 전에 로딩화면을 보여주고 응답을 받으면 로딩화면을 제거한다.
2. 응답의 상태 코드가 400이상이라면 에러를 던진다
3. request, response body를 객체로 넣으면 자동으로 직렬화/역직렬화를 한다. repsonse body의 타입은 generic으로 지정할 수 있다.

2. 서버 사이드에서 렌더링하기 위한 AJAX 요청

서버 사이드 렌더링용 데이터를 가져올 때는 2가지 기능을 추가해서 사용하고 있습니다.

1. 응답의 상태 코드가 400이상이라면 에러를 던진다
2. request, response body를 객체로 넣으면 자동으로 직렬화/역직렬화를 한다. repsonse body의 타입은 generic으로 지정할 수 있다.

3. 서버 사이드에서 렌더링이 아니라 프록시 역할로 AJAX 요청을 하고 응답을 그대로 내보냄(route.ts 파일)

서버 사이드에서 프록시 역할을 해야 할 때(route.ts 파일)는 기능을 추가하지 않고 baseUrl과 defaultHeader만 지정해서 사용하고 있습니다. 받은 response를 별도의 처리 없이 그대로 client에 전달하기 때문입니다.

마무리

fetch를 다양한 환경에서 사용해야하는 Next.js와 return-fetch는 잘 어울립니다. Axios에 익숙하지만 Next.js의 App Router를 사용할 예정이라면 Axios와 fetch사이에서 갈등할 수밖에 없습니다. 갈등의 순간에 제 라이브러리가 현명한 선택을 도울 수 있으면 좋겠습니다.

request, response body를 객체로 받을 수 있게 해주는 코드는 많이 쓰일 것 같아서 쉽게 받아서 사용하실 수 있도록 npm에 새로운 패키지로 등록했습니다. return-fetch 사랑해주세요! (신규 라이브러리라 사용하기가 부담스럽다면 ofetch를 추천합니다, 번들 사이즈가 7배 정도 크지만...)

감사합니다.

부록: fetch library 비교

1. fetch-intercept

https://www.npmjs.com/package/fetch-intercept

장점

• 가벼운 번들 사이즈 (762 Byte, minified + gzipped)

단점

• baseUrl을 설정할 수 없다.
• default headers를 설정할 수 없다.
• 전역에 선언된  fetch 에 몽키패치를 해버리기 때문에 모든 fetch 호출에 request, response interceptor가 적용된다. fetch를 다양한 맥락에서 사용해야 하는 Next.js에는 어울리지 않는다.

2. wretch

https://www.npmjs.com/package/wretch

장점

• 다양한 기능 (baseUrl, default header, interceptor 모두 지원)
• 상대적으로 가벼운 번들 사이즈 (1.9KB, minified + gzipped)

단점

• Axios처럼 response status에 따라 에러를 던지기 때문에 Next.js의 route.ts에서 사용하려면 추가 조치가 필요하다.
• wretch 인스턴스를 생성할 때 뿐만 아니라 사용할 때도 fetch와 호환되지 않는 자신만의 인터페이스를 가지고 있기 때문에 추가로 학습이 필요하다.

3. ofetch

https://www.npmjs.com/package/ofetch

장점

• 다양한 기능 (baseUrl, default header, interceptor 모두 지원)
• Next.js의 route.ts에서도 사용할 수 있도록 response 상태와 상관 없이 예외를 던지지 않고 응답을 전달할 수 있다.
• fetch와 호환되는 인터페이스를 가졌다.

단점

• Next.js에서 ofetch를 사용하는 레퍼런스가 부족하다. App Router도 새로운 기술인데 여기에 ofetch까지 얹어서 사용하기는 부담스럽다.
• 필요한 기능에 비해 번들 사이즈가 크다 (5KB)

4. return-fetch

https://www.npmjs.com/package/return-fetch

장점

• 가볍다 (733Byte, minified + gzipped)
• fetch만 있다면 어떤 실행환경에서도 사용할 수 있다 (Node.js, 웹브라우저, React Native, Web Worker 등등).
• 모든 fetch polyfill과 호환된다.
• Side effect가 없다. 전역 fetch를 건드리지 않는다. 외부 세계의 상태를 바꾸지 않으므로 안심하고 사용할 수 있다.
• 재귀적인 타입 선언 덕분에 특별한 처리 없이도 interceptor를 원하는 만큼 추가할 수 있다.
• 테스트 커버리지가 100%다. 모든 기능을 테스트했다.
• Next.js App Router환경에서 잘 작동한다. Next.js 사용자는 마음놓고 써도 된다.

단점

• 뼈대만 제공한다. 필요한 기능이 있다면 직접 구현해야 한다.
  • baseUrl, default header 기능도 request interceptor만 있으면 직접 구현할 수 있지만, 다행히 이 두 가지 기능은 탑재되어 있다.
• 신규 라이브러리라서 쓰는 사람이 별로 없다(😢).