React Server Components 深度解析

// app/actions.ts
'use server';

import { revalidatePath, revalidateTag } from 'next/cache';
import { redirect } from 'next/navigation';

export async function updateProfile(prevState, formData) {
  const userId = formData.get('userId');
  const name = formData.get('name');

  // 服务端校验
  if (!name || name.length < 2) {
    return { ok: false, message: '姓名至少 2 个字符' };
  }

  await db.users.update({
    where: { id: userId },
    data: { name }
  });

  // 让相关页面缓存失效，下次访问重新渲染
  revalidatePath('/profile');
  revalidateTag(`user-${userId}`);

  return { ok: true, message: '更新成功' };
}

// components/ProfileForm.tsx
'use client';

import { useActionState } from 'react';
import { useFormStatus } from 'react-dom';
import { updateProfile } from '@/app/actions';

// 独立的提交按钮组件，useFormStatus 读取所在 form 的提交态
function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? '保存中...' : '保存'}
    </button>
  );
}

export function ProfileForm({ user }) {
  const [state, formAction] = useActionState(updateProfile, {
    ok: false,
    message: ''
  });

  return (
    <form action={formAction}>
      <input type="hidden" name="userId" value={user.id} />
      <input type="text" name="name" defaultValue={user.name} />
      <SubmitButton />
      {state.message && (
        <p className={state.ok ? 'text-green' : 'text-red'}>
          {state.message}
        </p>
      )}
    </form>
  );
}

// lib/data.ts
import { cache } from 'react';

// cache 包裹后，同一次渲染内多次调用 getUser(1) 只查一次库
export const getUser = cache(async (id) => {
  return db.users.findUnique({ where: { id } });
});

// fetch 的缓存与重新验证控制
async function getProducts() {
  // 缓存 60 秒（ISR 风格），并打上标签便于按标签失效
  const res = await fetch('https://api.shop.com/products', {
    next: { revalidate: 60, tags: ['products'] }
  });
  return res.json();
}

// 完全不缓存（每次都取最新）
async function getLivePrice() {
  const res = await fetch('https://api.shop.com/price', {
    cache: 'no-store'
  });
  return res.json();
}

// lib/db.ts
import 'server-only'; // 护栏：此模块若被客户端组件导入则构建失败

export const db = createDbClient({
  // process.env.DATABASE_URL 只在服务端可读，不会泄露到浏览器
  url: process.env.DATABASE_URL,
  apiKey: process.env.INTERNAL_API_KEY
});

// 环境变量规则：
// - 只有以 NEXT_PUBLIC_ 开头的变量才会被注入客户端 bundle
// - 其余变量（如 DATABASE_URL）仅服务端可见
// 在客户端组件里读 process.env.DATABASE_URL 会得到 undefined

// components/Motion.tsx
'use client';

// 重新导出，给第三方库补上客户端边界
export { motion, AnimatePresence } from 'framer-motion';

// 之后在服务器组件里从这个包装文件导入即可
// import { motion } from '@/components/Motion';

// app/actions.ts
'use server';

import { revalidateTag } from 'next/cache';

export async function toggleLike(postId, liked) {
  await db.likes.upsert({
    where: { postId },
    create: { postId, liked },
    update: { liked }
  });
  revalidateTag(`post-${postId}`);
  const count = await db.likes.count({ where: { postId, liked: true } });
  return count; // 返回值会序列化回客户端
}

// components/LikeButtonRSC.tsx
'use client';

import { useState, useTransition } from 'react';
import { toggleLike } from '@/app/actions';

export function LikeButtonRSC({ postId, initialCount }) {
  const [count, setCount] = useState(initialCount);
  const [liked, setLiked] = useState(false);
  // useTransition 提供 pending 态，避免 UI 卡顿
  const [isPending, startTransition] = useTransition();

  const onClick = () => {
    const next = !liked;
    setLiked(next);
    startTransition(async () => {
      // 直接调用 Server Action，无需手写 fetch
      const serverCount = await toggleLike(postId, next);
      setCount(serverCount);
    });
  };

  return (
    <button onClick={onClick} disabled={isPending}>
      {liked ? '❤️' : '🤍'} {count}
    </button>
  );
}

// components/TodoList.tsx
'use client';

import { useOptimistic } from 'react';
import { addTodo } from '@/app/actions';

export function TodoList({ todos }) {
  const [optimisticTodos, addOptimistic] = useOptimistic(
    todos,
    (state, newTodo) => [...state, { ...newTodo, sending: true }]
  );

  async function formAction(formData) {
    const text = formData.get('text');
    addOptimistic({ id: 'temp', text }); // 立即显示，标记 sending
    await addTodo(formData);              // 真正写库
  }

  return (
    <>
      <form action={formAction}>
        <input name="text" />
        <button type="submit">添加</button>
      </form>
      <ul>
        {optimisticTodos.map(t => (
          <li key={t.id} style={{ opacity: t.sending ? 0.5 : 1 }}>
            {t.text}
          </li>
        ))}
      </ul>
    </>
  );
}

// app/page.tsx —— 服务器组件，不 await，直接把 Promise 传下去
import { Suspense } from 'react';
import { Comments } from '@/components/Comments';

export default function Page() {
  const commentsPromise = getComments(); // 注意：没有 await

  return (
    <Suspense fallback={<p>加载评论中...</p>}>
      <Comments commentsPromise={commentsPromise} />
    </Suspense>
  );
}

// components/Comments.tsx —— 客户端组件用 use() 解开 Promise
'use client';

import { use } from 'react';

export function Comments({ commentsPromise }) {
  const comments = use(commentsPromise); // 挂起直到 resolve
  return (
    <ul>
      {comments.map(c => <li key={c.id}>{c.text}</li>)}
    </ul>
  );
}

// app/dashboard/page.tsx
import { cookies, headers } from 'next/headers';

export default async function Dashboard() {
  // 使用 cookies() 会让此页转为动态渲染
  const cookieStore = await cookies();
  const theme = cookieStore.get('theme')?.value ?? 'light';

  const headerList = await headers();
  const country = headerList.get('x-vercel-ip-country');

  // 基于用户上下文的个性化数据
  const data = await getPersonalizedData({ theme, country });
  return <DashboardView data={data} theme={theme} />;
}

// app/blog/[slug]/page.tsx —— 静态生成 + 预渲染路径
export async function generateStaticParams() {
  const posts = await getAllPostSlugs();
  // 构建时预生成这些路径为静态 HTML
  return posts.map(p => ({ slug: p.slug }));
}

export default async function BlogPost({ params }) {
  const { slug } = await params;
  const post = await getPost(slug); // 构建时执行，产出纯静态页
  return <Article post={post} />;
}

// app/layout.tsx —— 嵌套布局，导航时不卸载、状态保留
export default function RootLayout({ children }) {
  return (
    <html lang="zh">
      <body>
        <Navbar />                {/* 静态外壳，可预渲染 */}
        <div className="flex">
          <Sidebar />
          <main>{children}</main> {/* 页面在此插槽切换 */}
        </div>
      </body>
    </html>
  );
}

// 部分预渲染理念（示意）：外壳静态，动态块 Suspense 流式
export default function Page() {
  return (
    <>
      <StaticHero />                          {/* 构建时预渲染，秒开 */}
      <Suspense fallback={<RecoSkeleton />}>
        <PersonalizedReco />                  {/* 请求时动态流式 */}
      </Suspense>
    </>
  );
}

// app/product/[id]/page.tsx
import { Suspense } from 'react';

export default async function ProductPage({ params }) {
  const { id } = params;
  // 主信息优先，评价与推荐用 Suspense 流式补上
  const product = await getProduct(id); // 直连数据库，无 API 层

  return (
    <div>
      <ProductGallery images={product.images} /> {/* 客户端：图片轮播 */}
      <h1>{product.name}</h1>
      <Price value={product.price} />
      <AddToCartButton productId={product.id} /> {/* 客户端 */}

      <Suspense fallback={<ReviewsSkeleton />}>
        <Reviews productId={id} />          {/* 服务器组件，流式 */}
      </Suspense>
      <Suspense fallback={<RecoSkeleton />}>
        <Recommendations productId={id} />  {/* 服务器组件，流式 */}
      </Suspense>
    </div>
  );
}

// app/actions.ts
'use server';

import { revalidateTag } from 'next/cache';
import { getSession } from '@/lib/auth';

// 第一个参数是绑定值，第二个才是 FormData
export async function deleteComment(commentId: string, formData: FormData) {
  const session = await getSession();
  if (!session) throw new Error('未登录');

  const comment = await db.comment.findUnique({ where: { id: commentId } });
  // 鉴权：只能删自己的评论
  if (!comment || comment.authorId !== session.userId) {
    throw new Error('无权操作');
  }

  await db.comment.delete({ where: { id: commentId } });
  revalidateTag(`comments-${comment.postId}`);
}

// components/CommentItem.tsx
'use client';

import { deleteComment } from '@/app/actions';

export function CommentItem({ comment }: { comment: Comment }) {
  // bind 在服务端把 commentId 固化进 action 引用，客户端无法篡改
  const deleteAction = deleteComment.bind(null, comment.id);
  return (
    <form action={deleteAction}>
      <span>{comment.text}</span>
      <button type="submit">删除</button>
    </form>
  );
}

// 用 zod 做服务端强校验的标准写法
'use server';

import { z } from 'zod';

const schema = z.object({
  title: z.string().min(1).max(120),
  price: z.coerce.number().positive().max(1_000_000),
});

export async function createProduct(prevState: unknown, formData: FormData) {
  const parsed = schema.safeParse({
    title: formData.get('title'),
    price: formData.get('price'),
  });
  if (!parsed.success) {
    // 把字段级错误回传给 useActionState
    return { ok: false, errors: parsed.error.flatten().fieldErrors };
  }
  await db.product.create({ data: parsed.data });
  revalidateTag('products');
  return { ok: true, errors: {} };
}

'use client';
import { useTransition } from 'react';
import { setStatus } from '@/app/actions';

export function StatusToggle({ id, initial }: { id: string; initial: string }) {
  const [pending, startTransition] = useTransition();
  return (
    <button
      disabled={pending}                         // 关键：pending 期间禁用，杜绝连点竞态
      onClick={() =>
        startTransition(async () => {
          await setStatus(id, initial === 'on' ? 'off' : 'on');
        })
      }
    >
      {pending ? '处理中…' : '切换'}
    </button>
  );
}

// lib/products.ts
import { unstable_cache } from 'next/cache';

// 1) 时间重验证：数据可容忍一定陈旧度，典型如商品列表、文章
export const getProducts = unstable_cache(
  async () => db.product.findMany(),
  ['products-list'],                 // 缓存 key 片段
  { revalidate: 120, tags: ['products'] } // 120s 后台重验证 + 打 tag
);

// 2) fetch 层的时间重验证（等价能力，用于外部 API）
async function getRates() {
  const res = await fetch('https://api.fx.com/rates', {
    next: { revalidate: 300, tags: ['fx'] },
  });
  return res.json();
}

// 3) 事件驱动的按需重验证：写操作后精确失效
'use server';
import { revalidateTag, revalidatePath } from 'next/cache';

export async function publishPost(id: string) {
  await db.post.update({ where: { id }, data: { status: 'published' } });

  revalidateTag('posts');            // 失效所有带 posts tag 的数据缓存
  revalidatePath(`/blog/${id}`);      // 失效该文章的整条路由缓存
  revalidatePath('/blog');           // 列表页也要刷
}

// 反例：一个大 Suspense 包住所有慢内容 —— 三块互相等待
async function BadDashboard() {
  return (
    <Suspense fallback={<PageSkeleton />}>
      <RevenueChart />     {/* 800ms */}
      <RetentionChart />   {/* 1400ms —— 拖累前两块一起等到 1400ms */}
      <TopProducts />      {/* 600ms */}
    </Suspense>
  );
}

// 正例：按速度拆边界，各自就绪各自补片
async function GoodDashboard() {
  return (
    <>
      <QuickStats />                                {/* 同步，秒出 */}
      <Suspense fallback={<ChartSkeleton h={320} />}>
        <RevenueChart />                            {/* 800ms 后补片 */}
      </Suspense>
      <Suspense fallback={<ChartSkeleton h={320} />}>
        <RetentionChart />                          {/* 1400ms 后补片，不拖累别人 */}
      </Suspense>
      <Suspense fallback={<ListSkeleton rows={5} />}>
        <TopProducts />                             {/* 600ms 后补片 */}
      </Suspense>
    </>
  );
}

// lib/data.ts
import { cache } from 'react';

export const getRevenue = cache(async () => {
  return db.$queryRaw`SELECT ...`;
});

// 预热函数：故意不 await，只为触发请求进入 memo 缓存
export const preloadRevenue = () => { void getRevenue(); };

// page.tsx —— 父组件先并行预热，子组件再各自 Suspense 消费
import { preloadRevenue, preloadRetention } from '@/lib/data';

export default function Page() {
  preloadRevenue();     // 立即发起，不阻塞
  preloadRetention();   // 立即发起，不阻塞

  return (
    <>
      <Suspense fallback={<ChartSkeleton />}><RevenueChart /></Suspense>
      <Suspense fallback={<ChartSkeleton />}><RetentionChart /></Suspense>
    </>
  );
}

// ❌ 隐式瀑布：user 拿到后才发 posts，再才发 followers —— 三段串行
async function slow(userId: string) {
  const user = await fetchUser(userId);        // 200ms
  const posts = await fetchPosts(userId);      // 300ms
  const followers = await fetchFollowers(userId); // 250ms
  return { user, posts, followers };           // 合计约 750ms
}

// ✅ 并行：三个请求同时发出，总耗时 = 最慢的那个
async function fast(userId: string) {
  const [user, posts, followers] = await Promise.all([
    fetchUser(userId),
    fetchPosts(userId),
    fetchFollowers(userId),
  ]);
  return { user, posts, followers };           // 合计约 300ms
}

// Server Action / 服务器组件抛出的 Error，在生产会被 React 脱敏
// 客户端只会收到通用消息和一个 digest，真实 message/stack 不下发（防信息泄露）

'use server';
export async function riskyAction() {
  try {
    await doSomething();
    return { ok: true as const, data: '...' };
  } catch (e) {
    // 推荐：把错误转成可序列化、可展示的结构化结果，而不是直接 throw
    console.error('[riskyAction]', e);               // 完整错误留在服务端日志
    return { ok: false as const, message: '操作失败，请稍后再试' };
  }
}

// error.tsx 里通过 digest 关联服务端日志，便于排障
'use client';
export default function Error({ error, reset }: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <div>
      <p>页面出错了</p>
      {/* digest 是 React 生成的错误指纹，可在服务端日志里检索到对应真实堆栈 */}
      {error.digest && <code>错误编号：{error.digest}</code>}
      <button onClick={reset}>重试</button>
    </div>
  );
}

// 场景：一个只在浏览器可用的图表库，禁用 SSR
import dynamic from 'next/dynamic';

// ssr:false 让它只在客户端加载，避免服务端访问 window 崩溃
const HeavyChart = dynamic(() => import('@/components/HeavyChart'), {
  ssr: false,
  loading: () => <ChartSkeleton />,
});

// 场景：全局 Provider (主题/状态) 用 children 组合，仍让子树是服务器组件
'use client';
import { ThemeProvider } from 'some-ui-lib';

export function Providers({ children }: { children: React.ReactNode }) {
  return <ThemeProvider>{children}</ThemeProvider>;
}

// app/layout.tsx （服务器组件）
// <Providers> 是客户端边界，但 {children} 里的页面依然是服务器组件
// 因为 children 作为已渲染元素传入，不会被拉进客户端 bundle

// lib/user.ts
import { experimental_taintObjectReference as taintObject } from 'react';

export async function getUser(id: string) {
  const user = await db.user.findUnique({ where: { id } });
  // 污染整个对象：若被整体传给客户端组件会报错，逼你只挑选安全字段传递
  taintObject('禁止把完整 user 对象传到客户端', user);
  return user;
}