"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; function _createMdxContent(props) { const _components = { a: "a", code: "code", h2: "h2", li: "li", p: "p", pre: "pre", strong: "strong", table: "table", tbody: "tbody", td: "td", th: "th", thead: "thead", tr: "tr", ul: "ul", ..._provideComponents(), ...props.components }, {TypeRuntimeGapDemo, UnwrapTradeoffDemo} = _components; if (!TypeRuntimeGapDemo) _missingMdxReference("TypeRuntimeGapDemo", true); if (!UnwrapTradeoffDemo) _missingMdxReference("UnwrapTradeoffDemo", true); return _jsxs(_Fragment, { children: [_jsx(_components.h2, { id: "들어가며", children: "들어가며" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.a, { href: "/trouble-shooting/29-global-response-advice", children: "서버 쪽 포스팅" }), "에서 모든 API 응답을 ", _jsx(_components.code, { children: "{ success, data, ... }" }), " 형식으로 통일했다. 그 짝으로 프론트에는 이 형식을 벗겨주는 Axios interceptor가 있다. 호출부마다 ", _jsx(_components.code, { children: "response.data.data" }), "를 파는 대신, interceptor가 성공이면 ", _jsx(_components.code, { children: "data" }), "만 돌려주고 실패면 ", _jsx(_components.code, { children: "ApiError" }), "를 던진다."] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-typescript", children: "publicApi.interceptors.response.use(\n (response) => {\n const data = response.data;\n if (isApiResponse(data)) {\n if (data.success) {\n return data.data; // 알맹이만 반환\n } else if (isApiErrorResponse(data)) {\n throw new ApiError(data.message, data.code);\n }\n }\n return response.data;\n },\n (error: AxiosError) => {\n if (error.response?.data && isApiErrorResponse(error.response.data)) {\n throw new ApiError(error.response.data.message, error.response.data.code);\n }\n throw new ApiError(\n error.message || \"An unknown error occurred.\",\n error.response?.status || 500,\n );\n },\n);\n" }) }), "\n", _jsx(_components.p, { children: "런타임은 의도대로 동작한다. 그런데 API 함수를 쓰는 순간 TypeScript가 막아선다." }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-typescript", children: "login: async (request: LoginRequest): Promise => {\n return publicApi.post(\"/api/v1/auth/login\", request);\n // Type 'AxiosResponse' is not assignable to type 'LoginResponse'\n},\n" }) }), "\n", _jsx(_components.h2, { id: "타입과-런타임이-다른-말을-한다", children: "타입과 런타임이 다른 말을 한다" }), "\n", _jsxs(_components.p, { children: ["Axios의 타입 정의에서 ", _jsx(_components.code, { children: "post()" }), "의 반환은 ", _jsx(_components.code, { children: "Promise>" }), "다. 그런데 우리 interceptor는 그 안에서 ", _jsx(_components.code, { children: "data.data" }), "를 꺼내 ", _jsx(_components.code, { children: "T" }), "를 돌려주도록 런타임 동작을 바꿔놨다. interceptor의 변환은 ", _jsx(_components.strong, { children: "타입 시스템 밖에서 일어나는 약속" }), "이라, TypeScript는 여전히 원래 타입 정의를 믿는다. 같은 코드를 세 가지 타입 전략으로 비교해보자."] }), "\n", _jsx(TypeRuntimeGapDemo, {}), "\n", _jsxs(_components.p, { children: [_jsx(_components.code, { children: "as Promise" }), " 캐스팅은 통과하지만 두 가지가 걸린다. API 함수가 늘어날 때마다 반복되고, 캐스팅은 컴파일러를 설득하는 게 아니라 입을 막는 행위라 interceptor 동작이 바뀌어도 아무도 알려주지 않는다."] }), "\n", _jsx(_components.p, { children: "답은 거짓말을 한 곳에서 진실로 정정하는 것이다. 인스턴스의 타입을 우리 interceptor의 실제 동작에 맞게 재정의한다." }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-typescript", children: "interface ApiInstance extends AxiosInstance {\n get(url: string, config?: AxiosRequestConfig): Promise;\n post(url: string, data?: unknown, config?: AxiosRequestConfig): Promise;\n put(url: string, data?: unknown, config?: AxiosRequestConfig): Promise;\n patch(url: string, data?: unknown, config?: AxiosRequestConfig): Promise;\n delete(url: string, config?: AxiosRequestConfig): Promise;\n}\n\nexport const publicApi = axios.create({ ... }) as ApiInstance;\n" }) }), "\n", _jsxs(_components.p, { children: ["런타임 코드는 한 줄도 안 바뀐다. 바뀌는 건 선언뿐이고, 이제 모든 호출부에서 ", _jsx(_components.code, { children: "post()" }), "가 ", _jsx(_components.code, { children: "Promise" }), "로 추론된다. interceptor가 런타임 계약을 바꿨으면 ", _jsx(_components.strong, { children: "타입 계약도 같은 곳에서 같이 바꿔주는 것까지가 구현" }), "이라는 게 이 단계의 결론이었다."] }), "\n", _jsxs(_components.p, { children: ["곁들여 둘. 응답이 정말 우리 형식인지 확인하는 type guard(", _jsx(_components.code, { children: "isApiResponse" }), ")는 외부 프록시 에러나 비표준 응답이 끼어들 때의 안전망이고, 모든 실패가 ", _jsx(_components.code, { children: "ApiError" }), " 하나로 수렴하니 React Query의 ", _jsx(_components.code, { children: "onError" }), "는 ", _jsx(_components.code, { children: "instanceof ApiError" }), " 분기 하나로 메시지와 코드를 다룬다."] }), "\n", _jsx(_components.h2, { id: "2막-언래핑-편의가-버린-것", children: "2막: 언래핑 편의가 버린 것" }), "\n", _jsx(_components.p, { children: "이 구조로 한참을 잘 쓰다가, 목록 API에 pagination이 들어오면서 문제가 드러났다." }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-json", children: "{\n \"status\": true,\n \"data\": [ ... ],\n \"pagination\": { \"pageNumber\": 0, \"totalPages\": 12 }\n}\n" }) }), "\n", _jsxs(_components.p, { children: ["interceptor는 ", _jsx(_components.code, { children: "data.data" }), "만 돌려주니, ", _jsx(_components.code, { children: "pagination" }), "은 호출부에 도달하기 전에 버려진다. 페이지네이션 UI를 만들 방법이 없다."] }), "\n", _jsx(UnwrapTradeoffDemo, {}), "\n", _jsxs(_components.p, { children: ["\"알맹이만 주는 편의\"는 알맹이 외의 모든 것을 버리는 결정이기도 했다. 응답에 메타데이터가 없던 시절에는 공짜 같던 편의가, 메타데이터가 생기는 순간 손실이 된 것이다. 그래서 interceptor가 검증과 에러 변환만 하고 ", _jsx(_components.strong, { children: "전체 응답을 반환" }), "하도록 되돌렸다."] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-typescript", children: "// interceptor: 검증/에러 변환만, 추출은 안 한다\nif (data.status) {\n return data; // ApiResponse 전체\n}\n\n// 호출부: 필요한 것을 직접 꺼낸다\nlogin: async (request: LoginRequestDTO): Promise => {\n const response = await publicApi.post(\"/api/v1/auth/login\", request);\n if (!response.data) {\n throw new Error(\"Login response data is missing\");\n }\n return response.data;\n},\n" }) }), "\n", _jsxs(_components.p, { children: ["호출부에 추출 한 줄이 늘었지만, pagination이 필요한 곳은 ", _jsx(_components.code, { children: "response.pagination" }), "으로 접근하고, ", _jsx(_components.code, { children: "data" }), "가 옵셔널이 되면서 \"성공인데 본문 없음\" 같은 변칙도 타입이 강제로 처리하게 만든다."] }), "\n", _jsxs(_components.p, { children: ["타입 쪽에도 후속 수정이 하나 따라왔다. 반환 타입을 ", _jsx(_components.code, { children: "Promise>" }), "로 바꾸려니 ", _jsx(_components.code, { children: "extends AxiosInstance" }), " 방식이 원본 시그니처와 충돌해서, 독립 인터페이스로 필요한 멤버만 명시하는 형태로 바꿨다."] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-typescript", children: "interface ApiInstance {\n get(url: string, config?: AxiosRequestConfig): Promise>;\n post(\n url: string,\n data?: unknown,\n config?: AxiosRequestConfig,\n ): Promise>;\n // ...\n defaults: AxiosInstance[\"defaults\"];\n interceptors: AxiosInstance[\"interceptors\"];\n}\n" }) }), "\n", _jsxs(_components.p, { children: ["상속 오버라이드는 원본과 호환되는 방향으로만 허용되는데, ", _jsx(_components.code, { children: "AxiosResponse" }), "를 ", _jsx(_components.code, { children: "T" }), "로 좁히는 것은 우연히 통과했고 ", _jsx(_components.code, { children: "ApiResponse" }), "로 바꾸는 것은 충돌했다. 어차피 원본 타입과 다른 말을 할 거라면 상속보다 독립 선언이 정직하다."] }), "\n", _jsx(_components.h2, { id: "두-시기의-정리", children: "두 시기의 정리" }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, {}), _jsx(_components.th, { children: "1기: data 추출" }), _jsx(_components.th, { children: "2기: 전체 반환" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: "호출부 코드" }), _jsx(_components.td, { children: "가장 깔끔" }), _jsx(_components.td, { children: "data 추출 한 줄 추가" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "pagination 등 메타데이터" }), _jsx(_components.td, { children: "접근 불가" }), _jsx(_components.td, { children: "접근 가능" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "data 누락 같은 변칙" }), _jsx(_components.td, { children: "런타임에서 발견" }), _jsx(_components.td, { children: "옵셔널 타입이 강제 처리" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "에러 일원화 (ApiError)" }), _jsx(_components.td, { children: "유지" }), _jsx(_components.td, { children: "유지" })] })] })] }), "\n", _jsxs(_components.p, { children: ["1기가 틀렸다기보다, 응답에 메타데이터가 없다는 전제가 깨지면서 맞는 답이 바뀌었다. interceptor에서 무엇을 벗길지는 \"지금 응답에 무엇이 있는가\"가 아니라 ", _jsx(_components.strong, { children: "앞으로 응답에 무엇이 생길 수 있는가" }), "를 기준으로 정하는 게 두 번 고치지 않는 길이었다."] }), "\n", _jsx(_components.h2, { id: "핵심-정리", children: "핵심 정리" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "interceptor의 응답 변환은 타입 시스템 밖의 런타임 약속이다. 변환을 넣었으면 인스턴스 타입 재정의로 타입 계약도 같은 곳에서 맞춘다. 호출부 캐스팅 반복은 컴파일러의 입을 막는 것일 뿐이다" }), "\n", _jsx(_components.li, { children: "type guard로 응답 형식을 런타임 검증하고, 모든 실패를 ApiError 하나로 수렴시키면 호출부 에러 처리가 instanceof 분기 하나로 끝난다" }), "\n", _jsx(_components.li, { children: "data만 추출하는 interceptor는 pagination 같은 메타데이터를 버리는 결정이다. 메타데이터가 생길 수 있다면 전체 응답 반환 + 호출부 추출이 유연하다" }), "\n", _jsx(_components.li, { children: "원본과 다른 시그니처가 필요하면 extends 오버라이드보다 독립 인터페이스가 정직하고 충돌도 없다" }), "\n"] }), "\n", _jsx(_components.h2, { id: "references", children: "References" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "https://axios-http.com/docs/interceptors", children: "Axios: Interceptors" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "https://www.typescriptlang.org/docs/handbook/2/objects.html", children: "TypeScript: Interfaces" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "https://tanstack.com/query/latest/docs/framework/react/guides/mutations#mutation-side-effects", children: "TanStack Query: Mutation Side Effects" }) }), "\n"] })] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = { ..._provideComponents(), ...props.components }; return MDXLayout ? _jsx(MDXLayout, { ...props, children: _jsx(_createMdxContent, { ...props }) }) : _createMdxContent(props); } return { default: MDXContent }; function _missingMdxReference(id, component) { throw new Error("Expected " + (component ? "component" : "object") + " `" + id + "` to be defined: you likely forgot to import, pass, or provide it."); }