React Server Components：心智模型、设计模式与常见陷阱

// app/dashboard/page.tsx — 默认就是服务端组件
import { db } from "@/lib/database";
import { headers } from "next/headers";
 
export default async function DashboardPage() {
  const headerList = await headers();
  const userId = headerList.get("x-user-id");
 
  // 直接数据库查询。不需要 API 路由。
  const user = await db.user.findUnique({
    where: { id: userId },
  });
 
  const recentOrders = await db.order.findMany({
    where: { userId: user.id },
    orderBy: { createdAt: "desc" },
    take: 10,
  });
 
  return (
    <div>
      <h1>Welcome back, {user.name}</h1>
      <OrderList orders={recentOrders} />
    </div>
  );
}

// src/components/Counter.tsx
"use client";
 
import { useState } from "react";
 
// 整个文件现在是"客户端领地"
export function Counter({ initialCount }: { initialCount: number }) {
  const [count, setCount] = useState(initialCount);
 
  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  );
}
 
// 这也是客户端组件，因为它在同一个文件中
export function ResetButton({ onReset }: { onReset: () => void }) {
  return <button onClick={onReset}>Reset</button>;
}

// app/page.tsx（服务端组件）
import { ItemList } from "@/components/ItemList"; // 客户端组件
 
export default async function Page() {
  const items = await getItems();
 
  return (
    <ItemList
      items={items}
      // 错误：函数不可序列化
      onItemClick={(id) => console.log(id)}
      // 错误：类实例不可序列化
      formatter={new Intl.NumberFormat("en-US")}
    />
  );
}

// app/page.tsx（服务端组件）
import { ItemList } from "@/components/ItemList";
 
export default async function Page() {
  const items = await getItems();
 
  // 只传递可序列化的数据
  return <ItemList items={items} locale="en-US" />;
}

// src/components/ItemList.tsx（客户端组件）
"use client";
 
import { useState, useMemo } from "react";
 
interface Item {
  id: string;
  name: string;
  price: number;
}
 
export function ItemList({ items, locale }: { items: Item[]; locale: string }) {
  const [selectedId, setSelectedId] = useState<string | null>(null);
 
  // 在客户端创建 formatter
  const formatter = useMemo(() => new Intl.NumberFormat(locale, { style: "currency", currency: "USD" }), [locale]);
 
  return (
    <ul>
      {items.map((item) => (
        <li key={item.id} onClick={() => setSelectedId(item.id)} className={selectedId === item.id ? "selected" : ""}>
          {item.name} — {formatter.format(item.price)}
        </li>
      ))}
    </ul>
  );
}

// app/products/page.tsx
export default async function ProductsPage() {
  // 默认缓存——相同 URL 返回缓存结果
  const res = await fetch("https://api.example.com/products");
  const products = await res.json();
 
  return (
    <div>
      {products.map((product: Product) => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  );
}

// 每 60 秒重新验证（类似 ISR 的行为）
const res = await fetch("https://api.example.com/products", {
  next: { revalidate: 60 },
});
 
// 不缓存——始终获取新数据
const res = await fetch("https://api.example.com/user/profile", {
  cache: "no-store",
});
 
// 带标签缓存，用于按需重新验证
const res = await fetch("https://api.example.com/products", {
  next: { tags: ["products"] },
});

"use server";
 
import { revalidateTag } from "next/cache";
 
export async function refreshProducts() {
  revalidateTag("products");
}

// app/dashboard/page.tsx — 不要这样做
export default async function Dashboard() {
  const user = await getUser(); // 200ms
  const orders = await getOrders(); // 300ms
  const notifications = await getNotifications(); // 150ms
  // 总计: 650ms — 每个都等待前一个完成
 
  return (
    <div>
      <UserInfo user={user} />
      <OrderList orders={orders} />
      <NotificationBell notifications={notifications} />
    </div>
  );
}

// app/dashboard/page.tsx — 这样做
export default async function Dashboard() {
  // 三个请求同时发出
  const [user, orders, notifications] = await Promise.all([
    getUser(), // 200ms
    getOrders(), // 300ms（并行运行）
    getNotifications(), // 150ms（并行运行）
  ]);
  // 总计: ~300ms — 受最慢请求限制
 
  return (
    <div>
      <UserInfo user={user} />
      <OrderList orders={orders} />
      <NotificationBell notifications={notifications} />
    </div>
  );
}

// app/dashboard/page.tsx — 最佳方案
import { Suspense } from "react";
 
export default function Dashboard() {
  // 注意：这个组件不是 async 的——它委托给子组件
  return (
    <div>
      <Suspense fallback={<UserInfoSkeleton />}>
        <UserInfo />
      </Suspense>
      <Suspense fallback={<OrderListSkeleton />}>
        <OrderList />
      </Suspense>
      <Suspense fallback={<NotificationsSkeleton />}>
        <Notifications />
      </Suspense>
    </div>
  );
}
 
// 每个组件获取自己的数据
async function UserInfo() {
  const user = await getUser();
  return <div>{user.name}</div>;
}
 
async function OrderList() {
  const orders = await getOrders();
  return (
    <ul>
      {orders.map((o) => (
        <li key={o.id}>{o.title}</li>
      ))}
    </ul>
  );
}
 
async function Notifications() {
  const notifications = await getNotifications();
  return <span>({notifications.length})</span>;
}

// 这两个组件可以获取相同的 URL
// Next.js 只会发出一个实际的 HTTP 请求
 
async function Header() {
  const user = await fetch("/api/user").then((r) => r.json());
  return <nav>Welcome, {user.name}</nav>;
}
 
async function Sidebar() {
  // 相同 URL — 自动去重，不是第二次请求
  const user = await fetch("/api/user").then((r) => r.json());
  return <aside>Role: {user.role}</aside>;
}

import { cache } from "react";
import { db } from "@/lib/database";
 
// 用 cache() 包裹你的数据函数
// 现在同一次渲染中的多次调用 = 一次实际查询
export const getUser = cache(async (userId: string) => {
  return db.user.findUnique({ where: { id: userId } });
});

// src/components/Sidebar.tsx — 客户端组件
"use client";
 
import { useState } from "react";
 
export function Sidebar({ children }: { children: React.ReactNode }) {
  const [isOpen, setIsOpen] = useState(true);
 
  return (
    <aside className={isOpen ? "w-64" : "w-0"}>
      <button onClick={() => setIsOpen(!isOpen)}>{isOpen ? "Close" : "Open"}</button>
      {isOpen && (
        <div className="sidebar-content">
          {/* 这些 children 可以是服务端组件！ */}
          {children}
        </div>
      )}
    </aside>
  );
}

// app/dashboard/layout.tsx — 服务端组件
import { Sidebar } from "@/components/Sidebar";
import { NavigationLinks } from "@/components/NavigationLinks"; // 服务端组件
import { UserProfile } from "@/components/UserProfile"; // 服务端组件
 
export default async function DashboardLayout({ children }: { children: React.ReactNode }) {
  return (
    <div className="flex">
      <Sidebar>
        {/* 这些是服务端组件，通过客户端组件传递 */}
        <UserProfile />
        <NavigationLinks />
      </Sidebar>
      <main>{children}</main>
    </div>
  );
}

// src/components/TabLayout.tsx — 客户端组件
"use client";
 
import { useState } from "react";
 
interface TabLayoutProps {
  tabs: { label: string; content: React.ReactNode }[];
}
 
export function TabLayout({ tabs }: TabLayoutProps) {
  const [activeTab, setActiveTab] = useState(0);
 
  return (
    <div>
      <div className="tab-bar" role="tablist">
        {tabs.map((tab, i) => (
          <button
            key={i}
            role="tab"
            aria-selected={i === activeTab}
            onClick={() => setActiveTab(i)}
            className={i === activeTab ? "active" : ""}
          >
            {tab.label}
          </button>
        ))}
      </div>
      <div role="tabpanel">{tabs[activeTab].content}</div>
    </div>
  );
}

// app/settings/page.tsx — 服务端组件
import { TabLayout } from "@/components/TabLayout";
import { ProfileSettings } from "./ProfileSettings"; // 服务端组件 — 可以获取数据
import { BillingSettings } from "./BillingSettings"; // 服务端组件 — 可以获取数据
import { SecuritySettings } from "./SecuritySettings"; // 服务端组件 — 可以获取数据
 
export default function SettingsPage() {
  return (
    <TabLayout
      tabs={[
        { label: "Profile", content: <ProfileSettings /> },
        { label: "Billing", content: <BillingSettings /> },
        { label: "Security", content: <SecuritySettings /> },
      ]}
    />
  );
}

// 这是合法且优雅的
async function BlogPost({ slug }: { slug: string }) {
  const post = await db.post.findUnique({ where: { slug } });
 
  if (!post) return notFound();
 
  const author = await db.user.findUnique({ where: { id: post.authorId } });
 
  return (
    <article>
      <h1>{post.title}</h1>
      <p>By {author.name}</p>
      <div dangerouslySetInnerHTML={{ __html: post.htmlContent }} />
    </article>
  );
}

// app/page.tsx
import { Suspense } from "react";
import { HeroSection } from "@/components/HeroSection";
import { ProductGrid } from "@/components/ProductGrid";
import { ReviewCarousel } from "@/components/ReviewCarousel";
import { RecommendationEngine } from "@/components/RecommendationEngine";
 
export default function HomePage() {
  return (
    <main>
      {/* 静态 — 立即渲染 */}
      <HeroSection />
 
      {/* 快速数据 — 很快显示 */}
      <Suspense fallback={<ProductGridSkeleton />}>
        <ProductGrid />
      </Suspense>
 
      {/* 中等速度 — 准备好时显示 */}
      <Suspense fallback={<ReviewsSkeleton />}>
        <ReviewCarousel />
      </Suspense>
 
      {/* 慢速（ML 驱动）— 最后显示，不阻塞其他部分 */}
      <Suspense fallback={<RecommendationsSkeleton />}>
        <RecommendationEngine />
      </Suspense>
    </main>
  );
}

<Suspense fallback={<DashboardSkeleton />}>
  <Dashboard>
    <Suspense fallback={<ChartSkeleton />}>
      <RevenueChart />
    </Suspense>
    <Suspense fallback={<TableSkeleton />}>
      <RecentTransactions />
    </Suspense>
  </Dashboard>
</Suspense>

// app/dashboard/error.tsx — 客户端组件（必须是）
"use client";
 
export default function DashboardError({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
  return (
    <div className="p-8 text-center">
      <h2>加载仪表盘时出错了</h2>
      <p className="text-gray-500">{error.message}</p>
      <button onClick={reset} className="mt-4 px-4 py-2 bg-blue-600 text-white rounded">
        重试
      </button>
    </div>
  );
}

"use client";
// window, document, navigator, localStorage 等
function GeoLocation() {
  const [coords, setCoords] = useState<GeolocationCoordinates | null>(null);
 
  useEffect(() => {
    navigator.geolocation.getCurrentPosition((pos) => setCoords(pos.coords));
  }, []);
 
  return coords ? <p>Lat: {coords.latitude}</p> : <p>Loading location...</p>;
}

"use client";
function SearchBar() {
  const [query, setQuery] = useState("");
  const debouncedQuery = useDebounce(query, 300);
 
  // 这个组件必须是客户端组件，因为它
  // 使用了 useState 并管理用户输入
  return <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Search..." />;
}

// 差：在服务端组件中获取数据，然后通过多个客户端组件传递
// app/page.tsx（服务端）
export default async function Page() {
  const user = await getUser();
  const settings = await getSettings();
  const theme = await getTheme();
 
  return (
    <ClientShell user={user} settings={settings} theme={theme}>
      <ClientContent user={user} settings={settings}>
        <ClientWidget user={user} />
      </ClientContent>
    </ClientShell>
  );
}

// 好：服务端组件获取自己的数据，作为 children 传递
// app/page.tsx（服务端）
export default function Page() {
  return (
    <ClientShell>
      <UserInfo /> {/* 服务端组件 — 获取自己的数据 */}
      <Settings /> {/* 服务端组件 — 获取自己的数据 */}
      <ClientWidget>
        <UserAvatar /> {/* 服务端组件 — 获取自己的数据 */}
      </ClientWidget>
    </ClientShell>
  );
}

// 差：所有东西都等待所有东西
export default async function Dashboard() {
  const stats = await getStats(); // 200ms
  const chart = await getChartData(); // 300ms
  const analytics = await getAnalytics(); // 4000ms ← 阻塞一切
 
  return (
    <div>
      <Stats data={stats} />
      <Chart data={chart} />
      <Analytics data={analytics} />
    </div>
  );
}

// 好：analytics 独立加载
export default function Dashboard() {
  return (
    <div>
      <Suspense fallback={<StatsSkeleton />}>
        <Stats />
      </Suspense>
      <Suspense fallback={<ChartSkeleton />}>
        <Chart />
      </Suspense>
      <Suspense fallback={<AnalyticsSkeleton />}>
        <Analytics /> {/* 需要 4 秒但不阻塞其他部分 */}
      </Suspense>
    </div>
  );
}

// 差
const user = await prisma.user.findUnique({ where: { id } });
// user 可能有不可序列化的字段（Decimal、BigInt 等）
return <ClientProfile user={user} />;
 
// 好
const user = await prisma.user.findUnique({ where: { id } });
const serializedUser = {
  id: user.id,
  name: user.name,
  email: user.email,
  balance: user.balance.toNumber(), // Decimal → number
  createdAt: user.createdAt.toISOString(), // Date → string
};
return <ClientProfile user={serializedUser} />;

// app/layout.tsx（服务端组件）
import { cookies } from "next/headers";
 
export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const cookieStore = await cookies();
  const theme = cookieStore.get("theme")?.value ?? "light";
 
  return (
    <html data-theme={theme} className={theme === "dark" ? "dark" : ""}>
      <body>{children}</body>
    </html>
  );
}

// src/providers/CartProvider.tsx
"use client";
 
import { createContext, useContext, useState } from "react";
 
const CartContext = createContext<CartContextType | null>(null);
 
export function CartProvider({ children }: { children: React.ReactNode }) {
  const [items, setItems] = useState<CartItem[]>([]);
 
  return <CartContext.Provider value={{ items, setItems }}>{children}</CartContext.Provider>;
}
 
export function useCart() {
  const context = useContext(CartContext);
  if (!context) throw new Error("useCart must be used within CartProvider");
  return context;
}

// app/shop/layout.tsx（服务端组件）
import { CartProvider } from "@/providers/CartProvider";
 
export default function ShopLayout({ children }: { children: React.ReactNode }) {
  // CartProvider 是客户端组件，但 children 作为服务端内容流过
  return <CartProvider>{children}</CartProvider>;
}

// 服务端组件 — marked 留在服务器上
import { marked } from "marked"; // 50KB 库 — 永远不会发送到客户端
 
async function BlogContent({ slug }: { slug: string }) {
  const post = await getPost(slug);
  const html = marked(post.markdown);
 
  return <div dangerouslySetInnerHTML={{ __html: html }} />;
}

import { cache } from "react";
 
export const getCurrentUser = cache(async () => {
  const session = await getSession();
  if (!session) return null;
 
  return db.user.findUnique({ where: { id: session.userId } });
});
 
// 在单个请求期间，在组件树的任何位置调用它。
// 只有一个实际的数据库查询会执行。

import { unstable_cache } from "next/cache";
 
const getCachedProducts = unstable_cache(
  async (categoryId: string) => {
    return db.product.findMany({
      where: { categoryId },
      include: { images: true },
    });
  },
  ["products-by-category"], // 缓存键前缀
  {
    revalidate: 3600, // 每小时重新验证
    tags: ["products"], // 用于按需重新验证
  },
);
 
// 在服务端组件中使用
async function ProductGrid({ categoryId }: { categoryId: string }) {
  const products = await getCachedProducts(categoryId);
  return <Grid items={products} />;
}

"use server";
 
import { revalidateTag } from "next/cache";
 
export async function onProductUpdate() {
  revalidateTag("products");
}

// lib/data/products.ts
 
import { cache } from "react";
import { unstable_cache } from "next/cache";
import { db } from "@/lib/database";
 
// 按请求去重：在一次渲染中多次调用，
// 只运行一次数据库查询
export const getProductById = cache(async (id: string) => {
  return db.product.findUnique({
    where: { id },
    include: { category: true, images: true },
  });
});
 
// 跨请求缓存：结果在请求间持久化，
// 每 5 分钟或通过标签按需重新验证
export const getPopularProducts = unstable_cache(
  async () => {
    return db.product.findMany({
      orderBy: { salesCount: "desc" },
      take: 20,
      include: { images: true },
    });
  },
  ["popular-products"],
  { revalidate: 300, tags: ["products"] },
);
 
// 无缓存：始终最新（用于用户特定数据）
export const getUserCart = cache(async (userId: string) => {
  // 这里的 cache() 只用于按请求去重，不是持久化
  return db.cart.findUnique({
    where: { userId },
    include: { items: { include: { product: true } } },
  });
});

// app/actions/newsletter.ts
"use server";
 
import { db } from "@/lib/database";
import { z } from "zod";
 
const emailSchema = z.string().email();
 
export async function subscribeToNewsletter(formData: FormData) {
  const email = formData.get("email");
 
  const result = emailSchema.safeParse(email);
  if (!result.success) {
    return { error: "Invalid email address" };
  }
 
  try {
    await db.subscriber.create({
      data: { email: result.data },
    });
    return { success: true };
  } catch (e) {
    if (e instanceof Error && e.message.includes("Unique constraint")) {
      return { error: "Already subscribed" };
    }
    return { error: "Something went wrong" };
  }
}

// src/components/NewsletterForm.tsx
"use client";
 
import { useActionState } from "react";
import { subscribeToNewsletter } from "@/app/actions/newsletter";
 
export function NewsletterForm() {
  const [state, formAction, isPending] = useActionState(
    async (_prev: { error?: string; success?: boolean } | null, formData: FormData) => {
      return subscribeToNewsletter(formData);
    },
    null,
  );
 
  return (
    <form action={formAction}>
      <input type="email" name="email" required placeholder="you@example.com" disabled={isPending} />
      <button type="submit" disabled={isPending}>
        {isPending ? "Subscribing..." : "Subscribe"}
      </button>
      {state?.error && <p className="text-red-500">{state.error}</p>}
      {state?.success && <p className="text-green-500">Subscribed!</p>}
    </form>
  );
}

// 旧模式 — 在客户端组件中获取数据
"use client";
 
function ProductPage({ id }: { id: string }) {
  const [product, setProduct] = useState<Product | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
 
  useEffect(() => {
    fetch(`/api/products/${id}`)
      .then((res) => res.json())
      .then((data) => setProduct(data))
      .catch((err) => setError(err.message))
      .finally(() => setLoading(false));
  }, [id]);
 
  if (loading) return <Spinner />;
  if (error) return <Error message={error} />;
  if (!product) return <NotFound />;
 
  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <AddToCartButton productId={product.id} />
    </div>
  );
}

// 新模式 — 服务端组件获取，客户端组件交互
 
// app/products/[id]/page.tsx（服务端组件）
import { db } from "@/lib/database";
import { notFound } from "next/navigation";
import { AddToCartButton } from "@/components/AddToCartButton";
 
export default async function ProductPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const product = await db.product.findUnique({ where: { id } });
 
  if (!product) notFound();
 
  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <AddToCartButton productId={product.id} price={product.price} />
    </div>
  );
}

"use client";
 
function ProductCard({ product }: { product: Product }) {
  const [isFavorite, setIsFavorite] = useState(false);
 
  return (
    <div className="card">
      <img src={product.image} alt={product.name} />
      <h3>{product.name}</h3>
      <p>{product.description}</p>
      <span>${product.price}</span>
      <button onClick={() => setIsFavorite(!isFavorite)}>{isFavorite ? "♥" : "♡"}</button>
    </div>
  );
}

// ProductCard.tsx（服务端组件）
import { FavoriteButton } from "./FavoriteButton";
 
function ProductCard({ product }: { product: Product }) {
  return (
    <div className="card">
      <img src={product.image} alt={product.name} />
      <h3>{product.name}</h3>
      <p>{product.description}</p>
      <span>${product.price}</span>
      <FavoriteButton productId={product.id} />
    </div>
  );
}

// FavoriteButton.tsx（客户端组件）
"use client";
 
import { useState } from "react";
 
export function FavoriteButton({ productId }: { productId: string }) {
  const [isFavorite, setIsFavorite] = useState(false);
 
  return (
    <button
      onClick={() => setIsFavorite(!isFavorite)}
      aria-label={isFavorite ? "Remove from favorites" : "Add to favorites"}
    >
      {isFavorite ? "♥" : "♡"}
    </button>
  );
}

// app/api/contact/route.ts
export async function POST(request: Request) {
  const body = await request.json();
  // 验证，保存到数据库，发送邮件
  return Response.json({ success: true });
}
 
// 客户端组件
const response = await fetch("/api/contact", {
  method: "POST",
  body: JSON.stringify(formData),
});

// app/actions/contact.ts
"use server";
 
export async function submitContactForm(formData: FormData) {
  // 验证，保存到数据库，发送邮件
  return { success: true };
}
 
// 客户端组件 — 直接调用函数
import { submitContactForm } from "@/app/actions/contact";

// __tests__/ProductPage.test.tsx
import { render, screen } from "@testing-library/react";
import ProductPage from "@/app/products/[id]/page";
 
// Mock 数据库
vi.mock("@/lib/database", () => ({
  db: {
    product: {
      findUnique: vi.fn(),
    },
  },
}));
 
describe("ProductPage", () => {
  it("renders product details", async () => {
    const { db } = await import("@/lib/database");
    vi.mocked(db.product.findUnique).mockResolvedValue({
      id: "1",
      name: "Test Product",
      description: "A great product",
      price: 29.99,
    });
 
    // 服务端组件是异步的 — await JSX
    const jsx = await ProductPage({
      params: Promise.resolve({ id: "1" }),
    });
    render(jsx);
 
    expect(screen.getByText("Test Product")).toBeInTheDocument();
    expect(screen.getByText("A great product")).toBeInTheDocument();
  });
});