endpoint-plus 심층 분석: 차세대 AI 네이티브 요청 스위트 (Request Suite)

💡 GitHub Repository: github.com/zandko/endpoint-plus

🌟 이 프로젝트가 도움이 되었거나 영감을 주었다면, Star를 눌러주세요! 저희는 이 프로젝트의 미래를 함께 만들어가기 위해 피드백, 이슈, 그리고 PR (Pull Request)을 적극적으로 기다리고 있습니다.

📌 1. 서론: 정말로 또 다른 요청 라이브러리가 필요할까요?

현대 프론트엔드 엔지니어링에서 네트워크 요청은 단순히 몇 개의 JSON 데이터를 가져오는 것보다 훨씬 더 복잡합니다. 모든 API 호출 주변에서 개발자들은 매일 지속되는 네 가지 골칫거리와 싸워야 합니다:

1. "인간 변환기" 인터페이스 세금 (The "Human Converter" Interface Tax): 백엔드 개발자가 수십 개 또는 수백 개의 필드를 포함하는 중첩된 JSON 응답을 전달할 때, 개발자는 TypeScript interfaces를 직접 수동으로 작성하거나 불안정한 온라인 포맷터에 끊임없이 붙여넣어야 합니다. API 필드가 변경될 때마다 타입을 업데이트하는 것은 유지보수의 악몽이 됩니다.
2. 런타임 간의 파편화 (Fragmentation Across Runtimes): 표준 브라우저 코드는 fetch나 axios를 사용합니다. 하지만 WeChat Mini-programs와 uni-app은 독자적인 래퍼 API (wx.request 또는 uni.request)를 요구합니다. 한편, SSR (Server-Side Rendering) 컨텍스트 (Nuxt/Next와 같은)는 서버 호환 클라이언트를 필요로 합니다. 결국 헤더, 인터셉터 (interceptors), 에러 핸들러 (error handlers)의 세 가지 별도 복사본을 유지 관리하게 됩니다.
3. 동시 401 무음 토큰 갱신 (Concurrent 401 Silent Token Refresh): 인증 토큰이 만료되고 여러 개의 병렬 요청이 동시에 백엔드에 도달할 때, 어떻게 하면 데드락 (deadlock)을 일으키지 않고 모든 요청을 깔끔하게 일시 중지하고, 이를 실행 큐 (execution queue)에 넣고, 정확히 하나의 토큰 갱신 요청을 보낸 뒤, 새로운 자격 증명으로 큐를 다시 실행할 수 있을까요?

AI Assistant Hallucinations (AI 어시스턴트 환각): AI 주도 코딩 시대에 Cursor나 GitHub Copilot과 같은 도구들은 빈번하게 존재하지 않는 파라미터를 만들어내거나, 구식 API를 제안하거나, 버그가 있는 fetch 함수를 생성하여 디버깅 사이클에 시간을 낭비하게 만듭니다.

이러한 정확한 문제들을 해결하기 위해, 우리는 **endpoint-plus**를 구축하고 오픈 소스로 공개했습니다. 이는 개발자를 수동 타이핑, 멀티 플랫폼 런타임 불일치, 그리고 반복적인 API 설정으로부터 해방시키기 위해 설계된 **차세대 크로스 플랫폼 요청 클라이언트 및 개발자 도구 스위트 (Request Suite)**입니다.

🏗️ 2. 핵심 아키텍처: 디커플링 (Decoupling)의 힘

endpoint-plus는 **고도로 추상화된 물리적 전송 계층 (Physical Transport Layer)**과 **플러그형 미들웨어 파이프라인 (Pluggable Middleware Pipeline)**을 도입함으로써 기존 요청 클라이언트의 모놀리식 (Monolithic) 오버헤드를 방지합니다.

graph TD
    A[Application Code 내의 API 호출] --> B[endpoint-plus Core Client]
    B --> C[Interceptors & Onion-Model Middleware]
...

1. 교체 가능한 물리적 전송 계층 (Swappable Physical Transports)

요청 정의를 실제 하부 네트워크 구현으로부터 분리함으로써, endpoint-plus는 100% 통일된 코드 시맨틱 (Code Semantics)을 제공합니다. 클라이언트를 생성할 때 전송 어댑터 (Transport Adapter)를 교체하기만 하면 됩니다.

• Standard Fetch (경량화, 외부 의존성 없음, 현대적인 브라우저 및 Node 22+ 권장):

  import { createInstance, createFetchTransport } from 'endpoint-plus';
  const api = createInstance({ transport: createFetchTransport() });

• Mini Program & uni-app (플랫폼별 요청, 파일 업로드 및 다운로드 처리):

  import { createMiniappTransport } from 'endpoint-plus/miniapp';
  const api = createInstance({ transport: createMiniappTransport({ runtime: wx }) });

• Axios Transport (업로드 진행률 모니터링이나 레거시 설정이 필요한 프로젝트에 최적):

  import { createAxiosTransport } from 'endpoint-plus/transports/axios';
  const api = createInstance({ transport: createAxiosTransport() });

2. Onion-Model Middleware (양파 모델 미들웨어)

전통적인 요청/응답 인터셉터 (request/response interceptors) 외에도, endpoint-plus는 Koa/Express 스타일의 양파 모델 미들웨어 (Onion-Model Middleware) 시스템을 도입합니다. 이를 통해 비동기 함수 (async functions)를 사용하여 전체 실행 수명 주기를 감쌀 수 있습니다:

api.registerRequestMiddleware(async (config, next) => {
  const start = Date.now();
  try {
...

🔮 3. TypeScript 타입 체조 (Type Gymnastics): 컴파일 타임 경로 패턴 매칭 (Compile-Time Path Pattern Matching)

이것이 endpoint-plus의 핵심적인 타입 안전성 (type-safety) 기능입니다: 모든 요청마다 제네릭 인자 (generic arguments)를 수동으로 캐스팅할 필요가 없습니다. TypeScript가 URL 문자열을 파싱하여 컴파일 타임 (compile-time)에 올바른 응답 타입을 직접 추론합니다.

예를 들어, .d.ts 파일에 라우트 (routes)를 선언하고 나면:

declare module 'endpoint-plus' {
  namespace YwEndpoint {
    interface Routes {
...

에디터에서 즉시 타입 안전성과 자동 완성 (autocompletion)을 제공합니다:

// 🌟 TypeScript 5.0+ const generic parameter pattern matching
const userList = await api.get('/users');
//    ^? User[] (GET /users로부터 추론됨)
...

🧠 타입 파서 (Type Parser)의 내부 작동 원리

우리는 재귀적 조건부 타입 (recursive conditional types)을 활용하여 URL 쿼리 (queries), 해시 앵커 (hash anchors), 도메인 접두사 (domain prefixes)를 제거하고, 경로를 세그먼트 (segments)로 파싱하여 매개변수 템플릿 (parameter templates)과 패턴 매칭을 수행합니다:

type EndpointRoutePathMatches<
  TRoutePath extends string,
  TUrl extends string,
...

이를 통해 핫 리로드 (hot-reloads) 중에 무거운 코드 생성 (code-generation) 단계를 거치지 않고도 백엔드와 프론트엔드 간의 엄격한 타입 정렬 (type alignment)을 보장합니다.

⚡ 4. 킬러 기능: Vite DevTools & Quiet Code Generator

인터페이스 타입 (interface types)을 수동으로 작성하는 것은 지루한 일입니다. 그래서 우리는 endpoint-plus-devtools (Vite 플러그인)를 구축했습니다.

vite.config.ts에 추가하기만 하면 됩니다:

import { endpointPlusDevtools } from 'endpoint-plus-devtools/vite';

export default defineConfig({
...

1. 작동 방식

1. 작동 방식

• AST 스캐닝 (AST Scanning): Vite 개발 서버가 부팅될 때 플러그인이 백그라운드에서 소스 트리(.ts, .tsx, .vue)를 구문 분석하여 모든 api.get / api.post 호출을 식별하고 시각적인 엔드포인트 맵을 구축합니다.
• 실시간 응답 캡처 (Live Response Capture): 브라우저 내 DevTools 오버레이를 열고, 엔드포인트를 선택한 후 테스트합니다. 오버레이는 백엔드에서 반환되는 실제 JSON 응답 페이로드를 캡처합니다.
• 스키마 생성 (Schema Generation):

🔌 6. 플러그형 엔터프라이즈급 미들웨어 (Pluggable Enterprise-Grade Middleware)

우리는 번들 크기를 작게 유지하는 것을 지향합니다. endpoint-plus의 모든 기능은 모듈화되어 있어, 필요한 플러그인만 선택적으로(opt-in) 사용할 수 있습니다.

플러그인 이름	임포트 경로 (Import Path)	해결하는 핵심 문제
refresh-token	endpoint-plus/plugins/refresh-token	동시성 안전(Concurrency-safe) 요청 버퍼링, 무음 토큰 갱신 (silent token refresh), 그리고 요청 재실행 (request replay)
...

동시성 안전 무음 토큰 갱신 (Concurrency-Safe Silent Token Refresh) 예시:

import { createRefreshTokenPlugin } from 'endpoint-plus/plugins/refresh-token';

api.use(
...

🤖 7. AI 네이티브 (AI-Native): LLM 코파일럿을 위한 사전 로드된 기술 (Preloaded Skills)

AI 어시스턴트가 정확한 코드를 작성할 수 있도록, endpoint-plus는 패키지 폴더 내에 사전 로드된 **AI 기술 (AI Skills)**을 포함하고 있습니다.

이 파일들을 로컬 커스텀 디렉토리로 복사하세요:

# 로컬 커스텀 폴더 생성
mkdir -p .agents/skills
# node_modules에서 지침(instructions) 복사
...

복사가 완료되면, 귀하의 AI 어시스턴트(예: Cursor 또는 Antigravity)가 즉시 이 파일들을 읽어 우리의 API 레이아웃, SSE 버퍼링 옵션, 그리고 미들웨어 패턴을 학습하게 됩니다. Cursor에 다음과 같이 프롬프트를 입력할 수 있습니다:

"무음 토큰 갱신(silent token refresh), 중복 제거 게이팅(deduplication gating) 기능이 포함된 엔드포인트 설정을 작성하고, get 메서드를 내보내줘(export)"

그러면 AI는 환각(hallucination)된 메서드나 파라미터 없이, 100% 정확하고 컴파일 가능한(compile-safe) 설정을 출력할 것입니다!

🤝 8. 함께 참여하여 미래를 만들어가세요

endpoint-plus는 허용 범위가 넓은 MIT 라이선스 (MIT License) 하에 배포되며, 이미 프로덕션 환경에서 복잡하고 트래픽이 높은 크로스 플랫폼 앱들을 구동하고 있습니다.

커뮤니티의 피드백, 풀 리퀘스트 (pull requests), 그리고 아이디어를 환영합니다! 우리는 다음과 같은 분야에서 기여할 분들을 적극적으로 찾고 있습니다:

1. 더 많은 전송 계층 (More Transports): Taro, React Native 또는 특정 서버리스 엣지(serverless edge) 환경을 위한 어댑터.
2. 개발 도구(DevTools) 강화: 더 풍부한 UI 대시보드, 응답 속도 그래프, 그리고 캐시 히트(cache hits) 통계.
3. 새로운 미들웨어 (New Middleware): 페이로드 검증(payload validation), 요청 서명 생성(request signature generation), 또는 모의 응답(mock response) 어댑터를 위한 플러그인.

이 프로젝트가 마음에 드신다면, 저희 리포지토리를 확인하고 Star ⭐️를 눌러주세요!

• 🔗 GitHub Repository: https://github.com/zandko/endpoint-plus
• 📦 NPM Registry: pnpm add endpoint-plus