第 22 讲：Route Handlers 与 Server Actions：HTTP 接口的两套范式

app/api/cart/
  ├─ route.ts
  └─ [itemId]/
     └─ route.ts

// app/api/cart/route.ts
export async function GET(req: Request) { ... }
export async function POST(req: Request) { ... }
export const PUT = async (req: Request) => { ... }

export const HTTP_METHODS = [
  'GET',
  'HEAD',
  'OPTIONS',
  'POST',
  'PUT',
  'DELETE',
  'PATCH',
] as const

    if (process.env.NODE_ENV === 'development') {
      const lowercased = HTTP_METHODS.map((method) => method.toLowerCase())
      for (const method of lowercased) {
        if (method in userland) {
          Log.error(
            `Detected lowercase method '${method}' in '${
              this.resolvedPagePath
            }'. Export the uppercase '${method.toUpperCase()}' method name to fix this error.`
          )
        }
      }

  private resolveHandler(method: string): AppRouteHandlerFn {
    // Prevent RCE: only allow recognized HTTP methods.
    if (!isHTTPMethod(method)) return () => new Response(null, { status: 400 })

    return this._methods[method]
  }

  public async handle(
    req: NextRequest,
    context: AppRouteRouteHandlerContext
  ): Promise<Response> {
    await this.ensureUserland()
    // ...
    const handler = liveUserland
      ? this.resolveHandlerFromUserland(req.method, liveUserland)
      : this.resolveHandler(req.method)

    const staticGenerationContext: WorkStoreContext = {
      page: this.definition.page,
      renderOpts: context.renderOpts,
      buildId: context.sharedContext.buildId,
      // ...
    }

    const userland = liveUserland ?? this._userland

    staticGenerationContext.renderOpts.fetchCache = userland.fetchCache

    const actionStore: ActionStore = {
      isAppRoute: true,
      isAction: getIsPossibleServerAction(req),
    }

    const implicitTags = await getImplicitTags(...)

    const requestStore = createRequestStoreForAPI(req, req.nextUrl, implicitTags, undefined, context.previewProps)
    const workStore = createWorkStore(staticGenerationContext)

    const response: unknown = await this.actionAsyncStorage.run(
      actionStore,
      () =>
        this.workUnitAsyncStorage.run(requestStore, () =>
          this.workAsyncStorage.run(workStore, async () => {
            // ...
            const hasNonStatic = liveUserland
              ? hasNonStaticMethods(liveUserland)
              : this._hasNonStaticMethods
            if (hasNonStatic) {
              if (workStore.isStaticGeneration) {
                const err = new DynamicServerError(
                  'Route is configured with methods that cannot be statically generated.'
                )

export class WrappedNextRouterError {

// 默认行为
export async function GET() { return Response.json({...}) }
// 在 build 时被 prerender → 返回静态 JSON

// 强制 dynamic
export const dynamic = 'force-dynamic'
export async function GET(req: NextRequest) {
  const ip = req.headers.get('x-forwarded-for')  // 用了 headers → 自动 dynamic
  return Response.json({ ip })
}

// app/cart/page.tsx
import { addToCart } from './actions'

export default function Cart() {
  return <form action={addToCart}>...</form>
}

// app/cart/actions.ts
'use server'
export async function addToCart(formData: FormData) {
  // mutation logic
  revalidateTag('cart')
}

const actionStore: ActionStore = {
  isAppRoute: true,
  isAction: getIsPossibleServerAction(req),
}

// app/api/chat/route.ts
export const runtime = "edge";

export async function POST(req: Request) {
  const { messages } = await req.json();

  const stream = new ReadableStream({
    async start(controller) {
      const encoder = new TextEncoder();
      for await (const chunk of openai.chat.completions.create({
        messages,
        stream: true,
      })) {
        const text = chunk.choices[0]?.delta?.content ?? "";
        controller.enqueue(
          encoder.encode(`data: ${JSON.stringify({ text })}\n\n`),
        );
      }
      controller.close();
    },
  });

  return new Response(stream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache",
      Connection: "keep-alive",
    },
  });
}

const res = await fetch("/api/chat", {
  method: "POST",
  body: JSON.stringify({ messages }),
});
const reader = res.body!.pipeThrough(new TextDecoderStream()).getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(value);
}

"use server";
export async function upload(formData: FormData) {
  const file = formData.get("file") as File;
  await uploadToS3(file);
}

export async function POST(req: Request) {
  const formData = await req.formData();
  const file = formData.get("file") as File;
  // ...
}

"use server";
import { cookies } from "next/headers";
export async function login(token: string) {
  cookies().set("token", token, { httpOnly: true, secure: true });
}

import { NextResponse } from "next/server";
export async function POST(req: Request) {
  const res = NextResponse.json({ ok: true });
  res.cookies.set("token", "...", { httpOnly: true });
  return res;
}

import { revalidateTag, revalidatePath } from 'next/cache'

// Route Handler
export async function POST() {
  await db.products.create(...)
  revalidateTag('products')   // 标记带 tag 'products' 的所有 cache 失效
  revalidatePath('/products') // 标记这个路径的 prerender 失效
  return Response.json({ ok: true })
}

export async function POST(req: Request) {
  try {
    const body = await req.json();
    if (!body.name) {
      return Response.json({ error: "name required" }, { status: 400 });
    }
    // ...
  } catch (err) {
    return Response.json({ error: "internal" }, { status: 500 });
  }
}

// app/cart/error.tsx
"use client";
export default function ErrorBoundary({ error }: { error: Error }) {
  return <div>购物车操作失败：{error.message}</div>;
}

export async function OPTIONS() {
  return new Response(null, {
    headers: {
      "Access-Control-Allow-Origin": "https://my-app.com",
      "Access-Control-Allow-Methods": "GET, POST",
      "Access-Control-Allow-Headers": "Content-Type, Authorization",
    },
  });
}

export async function POST(req: Request) {
  const auth = req.headers.get("authorization");
  if (!verify(auth)) return new Response("Unauthorized", { status: 401 });
  // ...
}

cd learning/nextjs-40-lectures/fixtures/lecture-22
pnpm install
pnpm dev
# http://localhost:3022

# 1. Route Handler
curl http://localhost:3022/api/todos
curl -X POST http://localhost:3022/api/todos -H 'Content-Type: application/json' -d '{"text":"hello"}'

# 2. SSE
curl -N http://localhost:3022/api/sse

# 3. Server Action（在浏览器里点表单按钮）

# 4. Lowercase method 错误演示
curl -X get http://localhost:3022/api/todos
# 仍可，因为 HTTP method 在传输层不区分大小写，但用户 export 必须大写