第 13 讲｜Caching 全景：4 层缓存的真相

┌────────────────────────────────────────────────────────────────────┐
│                          浏览器                                    │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │  ④ Router Cache（segment cache）                              │ │
│  │     - 客户端内存                                              │ │
│  │     - 生命周期：单个浏览器会话                                │ │
│  │     - key：URL → CacheNode                                    │ │
│  │     - 第 9 讲                                                  │ │
│  └──────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────┘
                                 ↑
                               navigate / prefetch
                                 ↓
┌────────────────────────────────────────────────────────────────────┐
│                          服务端进程                                │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │  ③ Full Route Cache                                          │ │
│  │     - .next/server/app/{path}.html / .meta / .rsc            │ │
│  │     - 生命周期：build / ISR 周期                             │ │
│  │     - key：URL → 完整 HTML + RSC payload                     │ │
│  └──────────────────────────────────────────────────────────────┘ │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │  ② Data Cache（fetch / unstable_cache / 'use cache'）       │ │
│  │     - .next/cache/{...} 或自定义 CacheHandler                │ │
│  │     - 生命周期：跨请求、跨部署可选                          │ │
│  │     - key：fetch URL+body+tags / unstable_cache key 等       │ │
│  │     - 第 11 讲                                                │ │
│  └──────────────────────────────────────────────────────────────┘ │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │  ① Request Memoization（React.cache 套 fetch）              │ │
│  │     - 内存（AsyncLocalStorage scope）                        │ │
│  │     - 生命周期：单次请求                                     │ │
│  │     - key：fetch URL + init                                   │ │
│  └──────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────┘

// 概念伪代码（实际在 patchFetch 里）
const memoizedFetch = React.cache((url, init) => originalFetch(url, init));
globalThis.fetch = memoizedFetch;

// app/products/[id]/layout.tsx
async function getProduct(id: string) {
  const res = await fetch(`/api/products/${id}`, { next: { revalidate: 60 } });
  return res.json();
}

export default async function Layout({ params, children }) {
  const product = await getProduct(params.id); // 第一次 fetch
  return (
    <>
      <Breadcrumb name={product.name} />
      {children}
    </>
  );
}

// app/products/[id]/page.tsx
export default async function Page({ params }) {
  const product = await getProduct(params.id); // 第二次：命中 ① memoization，零 HTTP
  return <ProductDetail product={product} />;
}

export class IncrementalCache implements IncrementalCacheType {
  readonly dev?: boolean
  readonly disableForTestmode?: boolean
  readonly cacheHandler?: CacheHandler
  readonly hasCustomCacheHandler: boolean
  readonly prerenderManifest: DeepReadonly<PrerenderManifest>
  readonly requestHeaders: Record<string, undefined | string | string[]>
  readonly allowedRevalidateHeaderKeys?: string[]
  readonly minimalMode?: boolean
  readonly fetchCacheKeyPrefix?: string
  readonly isOnDemandRevalidate?: boolean
  readonly revalidatedTags?: readonly string[]

  private static readonly debug: boolean =
    !!process.env.NEXT_PRIVATE_DEBUG_CACHE

.next/server/app/products/123.html        # SSR HTML
.next/server/app/products/123.rsc         # RSC payload
.next/server/app/products/123.meta        # 元数据（status, headers）

export const enum CachedRouteKind {
  APP_PAGE = 'APP_PAGE',
  APP_ROUTE = 'APP_ROUTE',
  PAGES = 'PAGES',
  FETCH = 'FETCH',
  REDIRECT = 'REDIRECT',
  IMAGE = 'IMAGE',
}

export interface CachedAppPageValue {
  kind: CachedRouteKind.APP_PAGE
  // this needs to be a RenderResult so since renderResponse
  // expects that type instead of a string
  html: RenderResult
  rscData: Buffer | undefined
  status: number | undefined
  postponed: string | undefined
  headers: OutgoingHttpHeaders | undefined
  segmentData: Map<string, Buffer> | undefined
}

export interface CachedPageValue {
  kind: CachedRouteKind.PAGES
  // this needs to be a RenderResult so since renderResponse
  // expects that type instead of a string
  html: RenderResult
  pageData: Object
  status: number | undefined
  headers: OutgoingHttpHeaders | undefined
}

export interface CachedRouteValue {
  kind: CachedRouteKind.APP_ROUTE
  // this needs to be a RenderResult so since renderResponse
  // expects that type instead of a string
  body: Buffer
  status: number
  headers: OutgoingHttpHeaders
}

浏览器输入 URL
    ↓
HTTP GET /products/123 → server
    ↓
③ Full Route Cache 查 .next/server/app/products/123.html → miss
    ↓
进入 React renderToReadableStream，开始装配组件树
    ↓
Page 组件中 await fetch('/api/p/123', { next: { tags: [...] } })
    ↓
① Request Memoization 查内存 → miss（首次）
    ↓
② Data Cache 查 .next/cache/fetch-cache/{key} → miss
    ↓
真实 HTTP 请求 /api/p/123
    ↓
存 ② Data Cache（异步），存 ① Request Memoization
    ↓
继续渲染，可能再用 unstable_cache 读 ② → 同样 miss → 写
    ↓
渲染完成，存 ③ Full Route Cache
    ↓
HTML 流式响应到浏览器
    ↓
浏览器初始化客户端 router，把 SeedData 写入 ④ Router Cache

HTTP GET /products/123
    ↓
③ Full Route Cache hit → 直接返回 HTML + RSC
    ↓
（不经过任何 React 渲染、fetch、② ① 都不查）
    ↓
浏览器继续命中 ④ 不发 RSC 请求

// app/posts/[slug]/page.tsx
export const revalidate = 600  // 10 分钟 ISR

async function getPost(slug: string) {
  const res = await fetch(`https://api.example.com/posts/${slug}`, {
    next: { revalidate: 60, tags: [`post:${slug}`] },
  })
  return res.json()
}

export default async function PostPage({ params }) {
  const { slug } = await params
  const post = await getPost(slug)
  return <Article post={post} />
}

// 编辑接口完成后
revalidateTag(`post:${slug}`); // 失效 ②
revalidatePath(`/posts/${slug}`); // 失效 ③

cd learning/nextjs-40-lectures/fixtures/lecture-13
NEXT_PRIVATE_DEBUG_CACHE=1 pnpm dev
# 浏览器打开 http://localhost:3013/