第 15 讲：请求一生：从 router-server 到 app-render

# CLI 入口
node packages/next/dist/bin/next start
  ↓ (next-start.ts)
startServer(opts)  # 来自 lib/start-server.ts
  ↓
http.createServer(handler)
  ↓
router-server.ts → initialize()

const handler = async (req, res) => {
  await requestHandler(req, res);
};
const server = http.createServer(handler);
server.listen(port, hostname);

}): Promise<ServerInitResult> {
  const type = process.env.__NEXT_PRIVATE_RENDER_WORKER
  if (type) {
    process.title = 'next-render-worker-' + type
  }

const requestHandlerImpl: WorkerRequestHandler = async (req, res) => {

const hotReloaderResult = await development.bundler.hotReloader.run(
  req,
  res,
  parsedUrl
)

if (hotReloaderResult.finished) {
  return hotReloaderResult
}

const {
  finished,
  parsedUrl,
  statusCode,
  resHeaders,
  bodyStream,
  matchedOutput,
} = await resolveRoutes({
  req,
  res,
  isUpgradeReq: false,
  signal: signalFromNodeResponse(res),
  invokedOutputs,
})

async function invokeRender(
  parsedUrl: NextUrlWithParsedQuery,
  invokePath: string,
  handleIndex: number,
  additionalRequestMeta?: RequestMeta
) {
  // ...
  addRequestMeta(req, 'invokePath', invokePath)
  addRequestMeta(req, 'invokeQuery', parsedUrl.query)
  addRequestMeta(req, 'middlewareInvoke', false)

  // ...
  try {
    const initResult =
      await renderServer?.instance?.initialize(renderServerOpts)
    try {
      await initResult?.requestHandler(req, res)

const server = next({
  ...opts,
  hostname: opts.hostname || 'localhost',
  customServer: false,
  httpServer: opts.server,
  port: opts.port,
}) as NextServer

// ...

requestHandler = server.getRequestHandler()
upgradeHandler = server.getUpgradeHandler()

return this.handleRequest.bind(this)

public async handleRequest(
  req: ServerRequest,
  res: ServerResponse,
  parsedUrl?: NextUrlWithParsedQuery
): Promise<void> {
  await this.prepare()
  const method = req.method.toUpperCase()
  const tracer = getTracer()

  return tracer.withPropagatedContext(req.headers, () => {
    // ...
    return tracer.trace(
      BaseServerSpan.handleRequest,
      {
        spanName: `${method}`,
        kind: SpanKind.SERVER,
        attributes: {
          'http.method': method,
          'http.target': req.url,
        },
      },
      async (span) =>
        this.handleRequestImpl(req, res, parsedUrl).finally(() => {

const route = rootSpanAttributes.get('next.route')
if (route) {
  const name = isRSCRequest
    ? `RSC ${method} ${route}`
    : `${method} ${route}`

  span.setAttributes({
    'next.route': route,
    'http.route': route,
    'next.span_name': name,
  })
  span.updateName(name)

// when invokePath is specified we can short short circuit resolving
// ...
const invokePath = getRequestMeta(req, 'invokePath')
const useInvokePath = !useMatchedPathHeader && invokePath

const result = await this.findPageComponents({
  locale: getRequestMeta(ctx.req, 'locale'),
  page,
  query,
  params: ctx.renderOpts.params || {},
  isAppPath,
  sriEnabled: !!this.nextConfig.experimental.sri?.algorithm,
  appPaths,
  // Ensuring for loading page component routes is done via the matcher.
  shouldEnsure: false,
})

// 概念伪代码（实际逻辑在 renderToResponseWithComponentsImpl 里）
const cached = await responseCache.get(cacheKey, async () => {
  // miss 时执行渲染
  return await this.renderHTML(req, res, pathname, query, renderOpts);
});

if (cached.isMiss) {
  // 渲染并写入 cache
} else {
  // 直接复用 cached.value
}

protected async renderHTML(
  req: NodeNextRequest,
  res: NodeNextResponse,
  pathname: string,
  query: NextParsedUrlQuery,
  renderOpts: LoadedRenderOpts
): Promise<RenderResult> {
  return getTracer().trace(NextNodeServerSpan.renderHTML, async () =>
    this.renderHTMLImpl(req, res, pathname, query, renderOpts)
  )
}

private async renderHTMLImpl(
  req: NodeNextRequest,
  res: NodeNextResponse,
  pathname: string,
  query: NextParsedUrlQuery,
  renderOpts: LoadedRenderOpts
): Promise<RenderResult> {
  if (process.env.NEXT_MINIMAL) {
    throw new Error(
      'Invariant: renderHTML should not be called in minimal mode'
    )
  } else {
    renderOpts.nextFontManifest = this.nextFontManifest

    if (this.enabledDirectories.app && renderOpts.isAppPath) {
      return lazyRenderAppPage(
        req,
        res,
        pathname,
        query,
        null,
        renderOpts as LoadedRenderOpts<AppPageModule>,
        this.getServerComponentsHmrCache(),
        {
          buildId: this.buildId,
          deploymentId: this.deploymentId,
          // ...
        }
      )
    } else {
      return lazyRenderPagesPage(/* ... */)
    }
  }
}

public render(
  req: BaseNextRequest,
  res: BaseNextResponse,
  context: AppPageRouteHandlerContext
): Promise<RenderResult> {
  return renderToHTMLOrFlight(
    req,
    res,
    context.page,
    context.query,
    context.fallbackRouteParams,
    context.renderOpts,
    context.serverComponentsHmrCache,
    context.sharedContext
  )
}

export const renderToHTMLOrFlight: AppPageRender = (
  req,
  res,
  pagePath,
  query,
  fallbackRouteParams,
  renderOpts,
  serverComponentsHmrCache,
  sharedContext
) => {
  if (!req.url) {
    throw new Error('Invalid URL')
  }

  const url = parseRelativeUrl(req.url, undefined, false)

  const parsedRequestHeaders = parseRequestHeaders(req.headers, {
    isRoutePPREnabled: renderOpts.experimental.isRoutePPREnabled === true,
    previewModeId: renderOpts.previewProps?.previewModeId,
  })

  // ... interpolatedParams + postponedState 处理 ...

  const workStore = createWorkStore({
    page: renderOpts.routeModule.definition.page,
    renderOpts,
    isPrefetchRequest,
    buildId: sharedContext.buildId,
    deploymentId: sharedContext.deploymentId,
    previouslyRevalidatedTags,
    nonce,
  })

  return workAsyncStorage.run(
    workStore,
    renderToHTMLOrFlightImpl,
    req,
    res,
    url,
    pagePath,
    query,
    renderOpts,
    workStore,
    parsedRequestHeaders,
    postponedState,
    serverComponentsHmrCache,
    sharedContext,
    interpolatedParams,
    fallbackRouteParams
  )
}

┌─────────────────────────────────────────────────────────────────┐
│ HTTP Request                                                    │
└──────────────────────────────┬──────────────────────────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│ http.createServer (start-server.ts)                             │
└──────────────────────────────┬──────────────────────────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│ router-server.ts: requestHandlerImpl                            │
│  1. filterInternalHeaders                                       │
│  2. (dev only) hotReloader.run                                  │
│  3. resolveRoutes:                                              │
│       redirects → headers → rewrites                            │
│       middleware (在 router-utils 里调用 edge-runtime sandbox)   │
│       fsChecker (静态资源、appPaths、pagesPaths)                  │
│  4. (dev devVirtualFsItem 分支)                                  │
│  5. 应用 resHeaders / status / bodyStream                        │
│  6. invokeRender(parsedUrl, invokePath, ...)                    │
│       └─ addRequestMeta('invokePath', ...)                      │
│       └─ renderServer.initialize() → server.getRequestHandler() │
└──────────────────────────────┬──────────────────────────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│ render-server.ts: requestHandler                                │
│  本质是 NextNodeServer.getRequestHandler()                       │
└──────────────────────────────┬──────────────────────────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│ base-server.ts: handleRequest → handleRequestImpl               │
│  1. await this.prepare()                                        │
│  2. 创建 OTEL root span (next.span_type=BaseServerSpan.handleR.) │
│  3. invokePath fast path → matchers.match(pathname)             │
│  4. renderToResponse → renderPageComponent                      │
│       └─ findPageComponents (require page module)               │
│       └─ renderToResponseWithComponents                         │
│            └─ ResponseCache.get(cacheKey) [第13讲: 4层缓存]      │
│                ├─ HIT  → 直接 res.write                          │
│                └─ MISS → renderHTML                             │
└──────────────────────────────┬──────────────────────────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│ next-server.ts: renderHTMLImpl                                  │
│  if (isAppPath) lazyRenderAppPage(...)                          │
│  else            lazyRenderPagesPage(...)                       │
└──────────────────────────────┬──────────────────────────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│ AppPageRouteModule.render (route-modules/app-page/module.ts)    │
│  └─ renderToHTMLOrFlight (app-render.tsx)                       │
│       1. parseRequestHeaders                                    │
│       2. interpolateParallelRouteParams                         │
│       3. parsePostponedState                                    │
│       4. workAsyncStorage.run(workStore, renderToHTMLOrFlightImpl)│
│            └─ React 渲染（第 16 ~ 19 讲展开）                      │
└─────────────────────────────────────────────────────────────────┘

cd learning/nextjs-40-lectures/fixtures/lecture-15
pnpm install
pnpm dev

[trace] BaseServerSpan.handleRequest GET /products/iphone-15  (45ms)
  ├─ NextNodeServerSpan.findPageComponents  (3ms)
  ├─ ResponseCacheSpan.get  (1ms)  [MISS]
  ├─ NextNodeServerSpan.renderHTML  (38ms)
  │    └─ AppRenderSpan.renderToHTMLOrFlight  (37ms)
  │         ├─ AppRenderSpan.createComponentTree  (12ms)
  │         └─ AppRenderSpan.renderToReadableStream  (24ms)