alova 1

Bora Im·2024년 7월 16일

What is alova
alova는 경량 요청 전략 라이브러리입니다. 복잡한 요청 시나리오를 처리할 수 있는 완전한 솔루션 세트를 제공합니다. 저희는 이를 요청 전략(Request Strategy)이라고 부릅니다. 여러 복잡한 요청 로직을 빠르게 구현하기 위해서는 한 줄의 코드만 있으면 됩니다. 개발 효율성을 향상시킬 수 있을 뿐만 아니라 앱의 운영 효율성을 향상시키고 서버에 가해지는 압력을 줄일 수 있습니다.

가장 간단한 요청 예)

const response = await alovaInstance.Get('/api/user');

평범하죠? 요청 상태를 자동으로 관리하는 또 다른 예를 살펴보겠습니다.
loading, error, data는 반응형 데이터입니다.
react, vue, svelte 등의 UI 프레임워크에서는 뷰에서 바로 바인딩할 수 있으며 요청에 따라 처리됩니다. State는 이 반응형 데이터를 자동으로 유지 관리합니다.

const { loading, error, data } = useRequest(alovaInstance.Get('/api/user'));

다음은 페이지, 페이지 크기 등이 변경되면 다른 매개변수를 가진 요청을 자동으로 트리거하는 페이징 요청 전략의 예입니다.

const { loading, error, data, page, pageSize, total } = usePagination((page, size) =>
  alovaInstance.Get('/api/user/list', {
    params: { page, size }
  })
);

Quick Start

alova 인스턴스 만들기
alova에서는 alova 인스턴스를 통해 요청을 해야 합니다. 일단 하나 만들어 보겠습니다.
alova 인스턴스를 만들 때 요청 어댑터를 지정해야 합니다. 여기서는 fetch API를 기반으로 한 패키지인 GlobalFetch 요청 어댑터를 사용하는 것이 좋습니다.

import { createAlova } from 'alova';
import GlobalFetch from 'alova/GlobalFetch';

const alovaInstance = createAlova({
  requestAdapter: GlobalFetch()
});

GET 요청
alovaInstance.Get을 통해 요청을 보내면 GlobalFetch 요청 어댑터 덕분에 Response 인스턴스가 수신됩니다.
- 비동기 함수에서는 await alovaInstance.Get을 사용하여 응답을 기다릴 수도 있습니다.
POST 요청
alovaInstance.Post를 통해 데이터를 제출하는 것도 쉽습니다.

// GET
alovaInstance
  .Get('https://jsonplaceholder.typicode.com/todos/1')
  .then(response => response.text())
  .then(data => {
    app.innerHTML = data;
  });

// POST
alovaInstance
  .Post('https://jsonplaceholder.typicode.com/posts', {
    title: 'foo',
    body: 'bar',
    userId: 1
  })
  .then(response => response.text())
  .then(data => {
    app.innerHTML = data;
  });

Method Instance

이전 장에서는 요청을 보내고 응답 데이터를 받아오려고 했습니다.
실제로 alovaInstance.Get(...)은 요청을 시작하는 함수가 아니라, 메소드 인스턴스를 만드는 PromiseLike 인스턴스입니다. Promise 객체처럼 then, catch, finally 메소드를 사용하거나 요청 보내기를 기다릴(await) 수 있습니다.

const userMethodInstance = alovaInstance.Get('/api/user');

userMethodInstance.then(response => {...});
userMethodInstance.catch(error => {...});
userMethodInstance.finally(() => {...});

try {
  await userMethodInstance;
} catch (error) {
  // ...
} finally {
  // ...
}

// 더 간단한 방법
const response = await alovaInstance.Get('/api/user');

각 메소드 인스턴스는 각 요청의 유형, 요청 URL, 요청 헤더, 요청 매개변수 등을 설명합니다.
또한 메소드 인스턴스에서 요청 동작을 정의하여 메소드가 요청을 처리하는 방법을 제어할 수 있습니다.

📤Request type

alova는 GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH 등 총 7가지 요청 유형을 제공합니다.

Instance creation function	Parameters
GET	`alovaInstance.Get(url[, config])`
POST	`alovaInstance.Post(url[, data[, config]])`
PUT	`alovaInstance.Put(url[, data[, config]])`
DELETE	`alovaInstance.Delete(url[, data[, config]])`
HEAD	`alovaInstance.Head(url[, config])`
OPTIONS	`alovaInstance.Options(url[, config])`
PATCH	`alovaInstance.Patch(url[, data[, config]])`

Parameter Description
- url : 요청 경로
- data : 요청 본문 데이터
- config : 요청 헤더, params 매개변수, 요청 동작 매개변수 등과 같은 구성을 포함하는 요청 구성 객체

메소드 인스턴스를 사용자 정의하여 생성할 수도 있습니다. 이는 요청 유형을 동적으로 지정해야 할 때 유용합니다.

import { Method } from 'alova';

const method = new Method('GET', alovaInstance, '/api/users', {
  params: {
    ID: 1
  }
});

📤Request parameters

URL parameters

params를 통해 URL 매개변수를 전달하면 params 매개변수가 URL 뒤에 ? 형식으로 연결됩니다.
물론 URL 뒤에 직접 연결할 수도 있으며 효과는 동일합니다.

alovaInstance.Get('/todo/list', {
  params: {
    userId: 1
  }
});

alovaInstance.Get('/todo/list?userId=1');

Request body

POST, PUT, DELETE, PATCH 요청을 보낼 때 요청 본문을 통해 데이터를 보낼 수 있습니다.
이때 전달된 두 번째 매개변수는 요청 본문입니다.
POST 요청이 params 매개변수를 전달할 수도 있다는 점은 주목할 가치가 있습니다.

alovaInstance.Post(
  '/todo',
  // second parameter : request body
  {
    title: 'test todo',
    time: '12:00'
  },
  // third parameter : configuration
  {
    params: {
      userId: 1
    }
  }
);

Request header

headers를 통해 요청 헤더를 지정합니다.

alovaInstance.Get('/user', {
  headers: {
    'Content-Type': 'application/json;charset=UTF-8'
  }
});

요청 어댑터가 지원하는 기타 매개변수

요청 헤더, params 매개변수 외에도 해당 요청 어댑터가 지원하는 매개변수 구성도 지원합니다.
GlobalFetch를 alova의 요청 어댑터로 사용하는 경우, 메소드 인스턴스에서 모든 fetch API 지원 매개변수를 구성할 수 있습니다. 이러한 매개변수는 요청 중에 fetch 함수에 전달됩니다.

alovaInstance.Get('/todo/list', {
  // ...
  credentials: 'same-origin',
  referrerPolicy: 'no-referrer',
  mode: 'cors'
});

📤Request behavior

요청 동작은 요청이 처리되는 방법을 설명하는 데 사용됩니다.

Timeout

요청 시간 초과를 설정합니다.

// Request timeout at request level
alovaInstance.Get('/todo/list', {
  // ...
  timeout: 10000
});

요청이 전송되었지만 아직 응답되지 않은 경우, 동일한 요청이 다시 전송되어
다음 시나리오와 같이 요청 낭비 또는 반복적인 제출(submission) 문제가 발생합니다.

컴포넌트는 생성될 때 초기화 데이터를 얻습니다. 페이지가 동시에 여러 컴포넌트를 렌더링하면 여러 개의 동일한 요청이 동시에 전송됩니다.
제출 버튼이 비활성화되지 않은 상태에서 사용자가 제출 버튼을 여러 번 클릭했습니다.
사전 로드가 완료되기 전에 사전 로드 페이지에 들어가면 여러 개의 동일한 요청이 전송됩니다.
react의 StrictMode에서 반복되는 요청을 방지합니다.

Request sharing은 이러한 문제를 해결하는 데 사용됩니다.
이는 애플리케이션의 유창성을 향상시킬 뿐만 아니라 서버 부담도 줄여줍니다.
요청 공유는 기본적으로 활성화(enabled)되어 있습니다. 특정 요청에 대한 요청 공유를 끄려면 다음과 같이 하세요.

alovaInst.Get('/todo', {
  // ...
  shareRequest: false
});

⚠️ 동일한 요청을 식별하는 방법
메소드 인스턴스의 요청 메소드, 요청 URL, 요청 헤더, URL 매개변수, 요청 본문이 고유 식별자로 사용됩니다. 동일한 식별자는 메소드 인스턴스의 참조 주소를 비교하는 것이 아니라 동일한 요청을 나타냅니다.

Transform response data (응답 데이터 변환)

때로는 응답 데이터를 균일하게 변환해야 할 때도 있습니다. 응답 데이터를 필요한 구조로 변환하기 위해 메소드 인스턴스에 대한 transformData 함수를 설정할 수 있습니다.

alovaInstance.Get('/todo/list', {
  transformData(rawData, headers) {
    return rawData.list.map(item => {
      return {
        ...item,
        statusText: item.done ? 'Completed' : 'In progress'
      };
    });
  }
});

Response cache

응답 캐시를 사용하면 매번 데이터를 가져오라는 요청을 보내지 않고도 서버 측 데이터를 여러 번 더 효과적으로 활용할 수 있습니다. GET 요청은 기본적으로 메모리 캐시 시간을 5분으로 설정합니다. 필요하지 않은 경우 다음 방법으로 현재 요청에 대한 캐시를 끌 수 있습니다.

alovaInstance.Get('/todo/list', {
  // 기본 응답 캐시를 끄려면 0 또는 null로 설정하세요.
  cacheFor: 0
});

🛑Interrupt request

[v2.6.2+] 요청을 중단하기 위해 메소드 인스턴스의 abort(중단)을 호출합니다.

const userMethod = alovaInstance.Get('/api/user');
userMethod.then(res => {
  // ...
});

const handleCancel = () => {
  userMethod.abort();
};

⌛업로드/다운로드 진행 상황

메소드 인스턴스의 onUpload를 통한 업로드 진행 이벤트와 onDownload를 통한 다운로드 진행 이벤트를 바인딩하여 바인딩 해제(unbinding) 함수를 반환합니다.

const uploadMethod = alovaInstance.Post('/todo/uploadfile', formData);
const offUploadEvent = uploadMethod.onUpload(event => {
  console.log('파일 크기:', event.total);
  console.log('업로드됨:', event.loaded);
});

uploadMethod.then(res => {
  // 업로드 요청 완료 처리
});

// 업로드 콜백 바인딩 해제 (업로드 이벤트 리스너 해제) e.g. 컴포넌트 언마운트 시
const handleOffEvent = () => {
  offUploadEvent();
};

const downloadMethod = alovaInstance.Get('/todo/downloadfile');
const offDownloadEvent = downloadMethod.onDownload(event => {
  console.log('파일 크기:', event.total);
  console.log('다운로드됨:', event.loaded);
});

downloadMethod.then(res => {
  // 다운로드 요청 완료 처리
});

// 다운로드 콜백 바인딩 해제
const handleOffEvent = () => {
  offDownloadEvent();
};

⚠️ alova/fetch 어댑터 사용 시 주의사항
fetch API 제한으로 alova에서 제공하는 alova/fetch 어댑터는 업로드 진행 상황을 지원하지 않습니다.
업로드 진행 상황이 필요한 경우 XMLHttpRequest adapter 또는 axios adapter를 사용하세요.

Upload/Download Status Type

type Progress = {
  /** 총 데이터 양 */
  total: number;
  /** 완료된 데이터 양 */
  loaded: number;
};

Bora Im

다음 포스트

alova 1

alova

Introduce

Quick Start

Method Instance

📤Request type

📤Request parameters

URL parameters

Request body

Request header

요청 어댑터가 지원하는 기타 매개변수

📤Request behavior

Timeout

Transform response data (응답 데이터 변환)

Response cache

🛑Interrupt request

⌛업로드/다운로드 진행 상황

alova 2

0개의 댓글

alova 1

alova

Introduce

Quick Start

Method Instance

📤Request type

📤Request parameters

URL parameters

Request body

Request header

요청 어댑터가 지원하는 기타 매개변수

📤Request behavior

Timeout

Request sharing (요청 공유)

Transform response data (응답 데이터 변환)

Response cache

🛑Interrupt request

⌛업로드/다운로드 진행 상황

alova 2

0개의 댓글