핵심 개념

Fetcher의 기준은 단순합니다. Runtime behavior는 ky가 맡고, OpenAPI awareness는 wrapper와 TypeScript type이 맡습니다.

아래에는 실제 KyInstance가 있습니다

createFetcher()는 KyInstance를 만들거나 decorate합니다. 반환된 client는 callable이며 shortcut method를 갖고, create와 extend를 노출하고, ky의 retry와 stop도 보존합니다.

import ky from 'ky';
import { createFetcher } from '@ilokesto/fetcher/openapi';

const instance = ky.create({ prefixUrl: '/api' });
const api = createFetcher<paths>(instance);
const adminApi = api.extend({ headers: { 'x-admin': '1' } });

단축 메서드는 타입이 지정된 요청 빌더입니다

api.get, api.post, api.put, api.patch, api.delete는 OpenAPI path와 grouped request object를 받습니다. Wrapper는 이 object를 plain ky options로 normalize합니다.

api.post('/uploads/{uploadId}', {
  params: {
    path: { uploadId: 'upload-1' },
    query: { overwrite: true },
  },
  headers: {
    'x-upload-token': token,
  },
  formData: {
    file,
  },
});

호출형 API는 ky에 가깝게 유지됩니다

Client 자체는 ky처럼 호출할 수 있습니다. Typed OpenAPI call에서는 options object에 method를 넣고 path, searchParams, json 같은 direct option을 사용합니다.

api('/users/{id}', {
  method: 'GET',
  path: { id: '42' },
  searchParams: { include: 'profile' },
});

이 분리는 의도된 설계입니다. Shortcut은 grouped contract를 쓰고, callable usage는 plain ky에 가깝게 유지합니다.

훅을 위한 컨텍스트가 주입됩니다

문자열 URL request에는 options.context.openapi가 주입되며 pathTemplate과 method를 포함합니다. Hook에서 tracing, metrics, auth routing, request log에 사용할 수 있습니다.

const api = createFetcher<paths>({
  hooks: {
    beforeRequest: [(_request, options) => {
      options.context.openapi?.pathTemplate;
      options.context.openapi?.method;
    }],
  },
});

기본 API는 예외를 던지고 safe는 결과를 반환합니다

기본 API는 ky ResponsePromise를 반환하고 HTTP 실패 시 예외를 던집니다. safe API는 같은 요청을 수행하지만 { ok: true, data, response } 또는 { ok: false, error, response }를 반환합니다.

다음 단계

그룹 요청에서 단축 메서드 정규화 규칙을 확인하세요.
오류 처리에서 예외와 safe 결과 중 알맞은 방식을 선택하세요.
ky 훅에서 주입된 OpenAPI 컨텍스트를 활용하세요.