
지난 7월부터 나는 오랫동안 유지보수되지 않던 사내 프로젝트 하나를 리팩터링하는 일을 맡아서 하고 있다. 업무를 받고서 내가 제일 처음 올린 티켓은 refactor: Next 16 업그레이드 및 품질 도구 정리 였다. 기존 Next 14 버전의 프로젝트를 16으로 끌어올리면서, 관련된 의존성들을 정리하는 일이었다. 크게 어렵지 않은 일이었지만, 한 가지 걸리는 부분이 있었다.
"Next 14버전의 앱 라우터 환경에서
fetch는 기본적으로 GET 요청에 대한 결과를 캐시한다."
클라이언트에서 발생하는 모든 요청은 반드시 Next 14의 BFF를 거쳐서 백엔드로 넘어가게 되어있었고, 거기에는 당연하게도 GET 요청이 포함되어있었다. 따라서 나는 단순하게 생각했다. 16버전에서는 GET 요청에 대한 결과를 캐시하지 않으니, 업그레이드 이후에도 그 동작을 유지하려면 force-cache를 명시하면 된다고 판단했다.
그리고 이 판단의 댓가는 3시간 야근 연장이었(따흐흑)
내 판단의 어디가 문제였는지를 알기 위해서는 기존 main의 BFF가 어떤 식으로 구성되어있었는지 알아둘 필요가 있다. 기존 main의 BFF는 app/api/[...suburl]/route.ts 하나에서 GET·POST·PUT·PATCH·DELETE를 모두 처리했다. 각 메서드는 공통 handleRequest를 호출했고, 그 안에서 백엔드로 요청을 전달했다. 다음은 기존 코드의 요청 옵션 부분이다.
const requestOptions: RequestInit = { method: req.method, headers: req.headers, body: isBody ? body : undefined, redirect: "follow",};이 옵션을 fetch(url, requestOptions)에 전달했다. cache나 next.revalidate는 별도로 지정하지 않았다.
마이그레이션 커밋에서 나는 다음 설정을 추가했다. 커밋 제목도 API 라우트 마이그레이션 동작 보존이었다. 요청 메서드가 GET이나 HEAD일 때는 명시적으로 캐시하고, 그렇지 않은 경우에는 캐시하지 않겠다는 의미였다. 그리고는 위의 requestOptions에 cache: cacheOption을 넣었다.
const cacheOption: RequestCache | undefined = ["GET", "HEAD"].includes(req.method) ? "force-cache" : undefined;의도는 명확했지만, 충분하지는 못했다.
fetch가 캐시된 요청을 사용하기까지
처음 Next 14가 출시될 때는 그야말로 대혼돈이었다. 페이지 라우트 기반에서 벗어나 처음으로 앱 라우트가 도입되었고, 산더미처럼 버그가 쏟아졌다. 멀쩡한 정신을 가진 프론트엔드 개발자라면 장기적인 유지보수 관점에서 페이지 라우트를 선택하는 것이 당연해보였고, 실험적이고 도전적인 사이드프로젝트에서나 한번 써볼까 말까한 정도였다.
나 역시도 14버전이 어떤 기능을 도입했는지는 관심있게 찾아보았지만, 그걸 실무에서 써볼 생각은 조금도 하지 않았다. 그래서 "Next의 새로운 버전에서는 fetch가 GET 요청의 응답을 자동으로 캐시하고, revalidate 기간 동안은 캐시된 값을 쓴다나봐" 정도로 이해하고 넘겼다.
당연하지만 14.2.3 버전의 fetch는 그렇게 만만하게 구현되지 않았다. 갑자기 구체적인 버전이 튀어나와 당황했을지도 모르겠다. 별 까닭은 없고 그냥 기존 사내 코드베이스가 해당 버전을 쓰고 있었고, 내가 (자발적인) 야근으로 파헤친 코드도 해당 태그를 기준으로 하기 때문이다.
앞으로는 다시 14 버전이라고 이야기하겠지만, 어디까지나 편의상의 표기일 뿐이고, 실제로는 전부 14.2.3 버전을 이야기하는 거라고 생각했으면 좋겠다. (싫으면 말고)
파일에 POST가 있는지만으로 조건이 성립한다
앱 라우터의 module.ts는 개발자가 app/**/route.ts에 작성한 핸들러를 실행하는 코드다. 우리가 export한 GET 이나 POST 함수를 찾아 호출하는 것만으로 끝났다면 좋았겠지만 그럴 리가 없다. 요청별 상태를 준비하고 정적 생성 정책을 적용하고 반환된 응답에 변경된 쿠키를 반영하는 일까지 맡는다. 우리가 작성한 함수 앞뒤로 Next가 필요로 하는 실행 환경을 둘러주는 셈이다.
이 실행 과정을 담당하는 클래스가 AppRouteRouteModule이다. 생성자는 userland라는 이름으로 개발자가 작성한 모듈의 export를 전달받는데 여기에는 GET, POST 같은 핸들러와 dynamic, revalidate, fetchCache 같은 설정이 들어 있다. 캐시 동작을 따라가기 위해 먼저 살펴볼 부분은 생성자가 이 userland를 받아 hasNonStaticMethods를 초기화하는 코드다.
// Get the non-static methods for this route.this.hasNonStaticMethods = hasNonStaticMethods(userland)hasNonStaticMethods라는 이름만 보면 현재 요청의 메서드를 확인하는 것 같지만 인자로 받은 건 요청 객체가 아니라 모듈의 export 목록이다. 실제 구현을 보면 이 차이가 더 분명해진다.
export function hasNonStaticMethods(handlers: AppRouteHandlers): boolean { if ( // Order these by how common they are to be used handlers.POST || handlers.POST || handlers.DELETE || handlers.PATCH || handlers.OPTIONS ) { return true } return false}이 함수는 현재 들어온 요청의 메서드가 GET인지 POST인지 묻는 게 아니다. 그저 해당 Route Handler 모듈이 어떤 메서드를 export하는지 검사한다. 우리 파일에는 POST가 있으므로 이 조건이 성립한다.
GET을 실행하기 전에도 기본 revalidate를 0으로 설정한다
module.ts의 288-302행에서는 이 판정 결과를 사용한다. 아래는 정적 생성 분기와 그 주석을 생략한 발췌다.
if (this.hasNonStaticMethods) { if (isStaticGeneration) { // 생략 } else { // 생략 staticGenerationStore.revalidate = 0 }}이 분기가 하는 일은 단순하다. 정적 생성 중이면 정적 생성에서 빠져나오고, 그렇지 않은 실행에서는 기본 재검증 값을 0으로 설정한다. 이 분기는 현재 요청 메서드가 무엇인지를 검사하지 않는다. POST인지 PATCH인지 DELETE인지가 중요한 것이 아니다. 정말로 중요한 것은 해당 모듈 안에 이 메서드들이 하나라도 존재하는지 여부이다.
그리하여 같은 파일의 GET을 실행할 때도 영향을 받는다. 원문 주석 역시 비정적 메서드가 있으므로 기본 캐시를 해제하기 위해 이 값을 설정한다고 설명한다. 뒤의 363–364행에서는 값이 없을 때만 기본값을 채우므로, 이미 설정한 0은 유지된다. GET을 실행할 때도 말이다.
옵션 없는 fetch는 그 0을 물려받는다
개발자가 명시적으로 재검증 값을 제공하지 않는 경우, Next 14버전의 기본 분기 값 선택은 아래와 같다. 앞에서 설정한 값은 숫자 0이다. 따라서 이 분기에서도 0을 그대로 사용한다.
revalidate = typeof staticGenerationStore.revalidate === 'boolean' || typeof staticGenerationStore.revalidate === 'undefined' ? false : staticGenerationStore.revalidate만약 인증 헤더 등의 조건이 있다면 autoNoCache도 계산해야 한다. 이 조건 역시 기존의 staticGenerationStore.revalidate === 0을 직접 확인한다.
const hasUnCacheableHeader = initHeaders.get('authorization') || initHeaders.get('cookie')const isUnCacheableMethod = !['get', 'head'].includes( getRequestMeta('method')?.toLowerCase() || 'get')const autoNoCache = (hasUnCacheableHeader || isUnCacheableMethod) && staticGenerationStore.revalidate === 0이러한 연산 끝에 명시적으로 제공된 revalidate 값이 없으면서 autoNoCache가 참이면 다음 분기에서 값을 최종적으로 0으로 정하게 된다.
if (typeof revalidate === 'undefined') { if (fetchCacheMode === 'default-cache') { revalidate = false cacheReason = 'fetchCache = default-cache' } else if (autoNoCache) { revalidate = 0 cacheReason = 'auto no cache' } // 나머지 분기 생략}기본값을 물려받는 경로와 autoNoCache 경로 중 어느 쪽을 지나더라도 이 사례의 값은 0이다. 중요한 건 우리 BFF의 옵션 없는 GET fetch를 단순히 force-cache와 같다고 볼 수 없었다는 것이다.
명시적인 force-cache는 다른 경로로 들어간다
같은 파일의 앞부분에는 다음 코드가 있다.
if (_cache === 'force-cache') { curRevalidate = false} else if ( _cache === 'no-cache' || _cache === 'no-store' || fetchCacheMode === 'force-no-store' || fetchCacheMode === 'only-no-store') { curRevalidate = 0}여기서 false는 캐시 비활성화가 아니다. Next.js의 재검증 설정에서는 시간에 따른 만료를 지정하지 않는다는 의미다. 이 값은 이후 검증을 거쳐 사용되므로, 옵션을 생략했을 때처럼 기본 0을 물려받는 경로와 다르다. 옵션 생략과 명시적 force-cache는 이 사례에서 동등하지 않았다.
0과 false는 실제 캐시 가능 여부에서 갈린다
0과 false의 차이는 재검증 값을 정하는 데서 끝나지 않는다. patch-fetch.ts는 이어서 이 값으로 해당 요청을 Data Cache에 넣을 수 있는지 판정한다.
const isCacheableRevalidate = (typeof revalidate === 'number' && revalidate > 0) || revalidate === false이 조건에 값을 하나씩 넣어보면 차이가 분명해진다.
| revalidate | isCacheableRevalidate | 의미 |
|---|---|---|
| 0 | false | 캐시하지 않음 |
| 양수 | true | 지정한 초를 기준으로 재검증 |
| false | true | 시간 기반 만료 없이 캐시 |
숫자 0은 typeof revalidate === 'number'까지는 참이지만 revalidate > 0에서 거짓이 된다. 0 === false도 엄격 비교에서는 거짓이다. 반면 명시적인 force-cache에서 만든 false는 두 번째 조건을 만족하므로 캐시 가능한 값이 된다. 이름만 보면 false가 기능을 끄는 값처럼 보이지만, 여기서는 오히려 캐시 쪽으로 들어간다.
이 판정이 참이어야 요청의 캐시 키를 만든다.
let cacheKey: string | undefinedif (staticGenerationStore.incrementalCache && isCacheableRevalidate) { cacheKey = await staticGenerationStore.incrementalCache.fetchCacheKey( fetchUrl, isRequestInput ? (input as RequestInit) : init )}뒤의 캐시 조회도 cacheKey가 있을 때만 실행된다.
if (cacheKey && staticGenerationStore.incrementalCache) { const entry = staticGenerationStore.isOnDemandRevalidate ? null : await staticGenerationStore.incrementalCache.get(cacheKey, { // 생략 }) // 캐시된 응답 처리 생략}원본 응답을 Data Cache에 저장하는 조건에도 cacheKey와 isCacheableRevalidate가 다시 들어간다.
if ( res.status === 200 && staticGenerationStore.incrementalCache && cacheKey && isCacheableRevalidate) { await staticGenerationStore.incrementalCache.set( cacheKey, // 생략 )}결국 옵션 없는 기존 fetch가 물려받은 0은 isCacheableRevalidate를 통과하지 못한다. 캐시 키가 만들어지지 않으므로 캐시 조회와 저장으로도 이어지지 않는다. 반면 force-cache가 만든 false는 이 조건을 통과하고, 캐시 키 생성과 조회·저장 경로에 들어갈 수 있다. 0과 false의 차이는 이름이나 문서 표현의 차이가 아니라, 실제로 Data Cache를 사용하는지를 가르는 분기였다.
틀리지 않았지만 옳은 적도 없다
이번 사례에서 문제였던 건 Next.js의 캐시가 아니었다. 실제 동작을 확인하지 않은 채 기본값에 대한 설명을 우리 코드의 동작으로 받아들인 게 문제였다. “GET 핸들러는 기본적으로 캐시된다”와 “그 안의 모든 fetch가 항상 캐시된다”는 같은 말이 아니다. Route Handler의 응답 캐시와 내부 fetch의 Data Cache도 구분해야 했다. 알고 있던 설명이 틀리지 않았다고 해서, 그 설명으로 내린 판단까지 옳아지는 건 아니었다.
다음에 비슷한 마이그레이션을 한다면 같은 요청을 반복했을 때 실제 백엔드까지 도달하는지부터 비교할 생각이다. 브라우저에 BFF 요청이 찍힌다는 사실만으로는 그 뒤에서 캐시를 사용했는지 알 수 없다. 이번에는 그 차이를 이해하는 데 자발적인 야근과 소스 코드 탐험이 필요했다. 다음에는 코드를 뒤지기 전에, 내가 줄였다고 믿는 요청이 정말 줄었는지부터 확인하려고 한다.
댓글
댓글을 불러오는 중...