用户输入 URL
  → 服务端（是否预渲染？缓存？）
  → 返回 HTML（有多大？多快？）
  → 浏览器解析 + 下载 JS
  → 水合（是否一致？是否阻塞交互？）
  → 客户端路由接管（切换是否够快？状态是否保留？）

08 路由与渲染架构
  ├─ 前置：06 框架与组件化、07 状态管理（URL 即状态）
  ├─ 紧接：11 性能（LCP/TTFB/水合）、10 网络（缓存与 CDN）
  ├─ 交叉：14 Node/BFF（SSR 服务）、15 跨端（容器内路由）
  └─ 长期：17 架构（微前端路由、多团队契约）

/**
 * hash 路由的最小实现：只依赖浏览器事件。
 * 面试常问「前端路由原理」，这就是答案的第一层。
 */
window.addEventListener('hashchange', () => {
  const path = location.hash.slice(1) || '/';
  render(path);
});

function navigate(path) {
  location.hash = path; // 会触发 hashchange，并写入历史
}

/**
 * history 路由：pushState 不会刷新页面，但也不会触发任何事件，
 * 所以「前进/后退」必须自己监听 popstate。
 */
function navigate(path) {
  history.pushState({ path }, '', path);
  render(path); // 手动渲染
}

window.addEventListener('popstate', (e) => {
  render(e.state?.path ?? location.pathname);
});

/**
 * 路由表 = 路径模式 → 组件 + 元信息。
 * 三个概念：嵌套（children）、动态段（:id）、索引路由（index）。
 */
const routes = [
  {
    path: '/',
    element: <Layout />,
    children: [
      { index: true, element: <Home /> },
      { path: 'orders', element: <OrderList /> },
      { path: 'orders/:id', element: <OrderDetail /> },
      { path: '*', element: <NotFound /> },
    ],
  },
];

/**
 * 路径参数用于「资源身份」，查询参数用于「视图配置」。
 * 判断标准：这个值变了，是不是同一个资源？
 */
function OrderDetail() {
  const { id } = useParams();                    // /orders/123 → id = '123'
  const [params] = useSearchParams();            // ?tab=log&page=2
  const tab = params.get('tab') ?? 'detail';

  // id 变了要重新请求；tab 变了只是切视图
  const { data } = useQuery({ queryKey: ['order', id], queryFn: () => fetchOrder(id) });

  return <Tabs value={tab} items={[{ key: 'detail', content: <Detail data={data} /> }]} />;
}

// ✅ 用 Link：可右键新开、可被爬虫抓取、可访问
<Link to="/orders">订单</Link>

// ✅ 编程式：需要先做副作用（保存、校验）时
const navigate = useNavigate();
async function handleSubmit() {
  await save();
  navigate('/orders', { replace: true }); // replace：不留下表单页历史
}

// ❌ 用 div + onClick：丢失链接语义与键盘可达性
<div onClick={() => navigate('/orders')}>订单</div>

/**
 * 每个路由一个 chunk：首屏只加载当前页面。
 * fallback 要放在「布局内部」，否则整页闪白。
 */
const OrderList = lazy(() => import('./pages/OrderList'));

<Route path="orders" element={
  <Suspense fallback={<ListSkeleton />}>
    <OrderList />
  </Suspense>
} />

/**
 * 守卫本质是「渲染前判断」。
 * 注意：前端守卫只解决体验，真正的权限必须服务端校验。
 */
function RequireAuth({ children }) {
  const { user, loading } = useAuth();
  const location = useLocation();

  if (loading) return <FullPageLoading />;
  if (!user) return <Navigate to="/login" state={{ from: location }} replace />;
  return children;
}

const location = useLocation();
const from = location.state?.from?.pathname ?? '/';
navigate(from, { replace: true });

/**
 * 最小 history 路由：拦截链接点击 + 监听 popstate。
 * 注意：pushState 不会触发 popstate，只有前进/后退才会。
 */
function createRouter(onChange) {
  const navigate = (url, state = {}) => {
    history.pushState(state, '', url);
    onChange(location.pathname);
  };

  document.addEventListener('click', (event) => {
    const link = event.target.closest('a[data-link]');
    if (!link || event.metaKey || event.ctrlKey) return;
    event.preventDefault();
    navigate(link.getAttribute('href'));
  });

  window.addEventListener('popstate', (event) => {
    onChange(location.pathname, event.state);
  });

  return { navigate };
}

/**
 * 保存并恢复滚动位置：按 history key 存，避免不同条目互相覆盖。
 */
const positions = new Map();

window.addEventListener('scroll', () => {
  positions.set(history.state?.key ?? location.pathname, window.scrollY);
}, { passive: true });

function restoreScroll() {
  const key = history.state?.key ?? location.pathname;
  window.scrollTo(0, positions.get(key) ?? 0);
}

需要登录后才看 → CSR（或 SSR + 私有缓存）
内容要 SEO、更新频繁 → SSR 或 RSC
内容稳定、量大 → SSG
内容较稳定但要能更新 → ISR

1. 浏览器请求 /orders/1
2. Node 服务收到请求
3. 调用接口拿数据（可能聚合多个）
4. renderToString(<App url="/orders/1" />) → HTML 字符串
5. 返回 HTML（首屏可见，但按钮点不动）
6. 浏览器下载 JS
7. hydrate：复用 DOM，绑定事件
8. 之后由客户端路由接管

/**
 * 最小 SSR 服务：理解「同构」最直接的方式。
 * 真实框架多了：路由匹配、数据预取、流式、缓存、安全。
 */
import express from 'express';
import { renderToString } from 'react-dom/server';

const app = express();

app.get('*', async (req, res) => {
  const store = createStore();                       // 每次请求独立 store
  const data = await loadDataFor(req.path);          // 服务端预取
  store.dispatch({ type: 'hydrate', payload: data });

  const html = renderToString(
    <Provider store={store}>
      <App location={req.path} />
    </Provider>,
  );

  res.send(`<!DOCTYPE html>
<html>
  <body>
    <div id="root">${html}</div>
    <script>window.__INITIAL_STATE__=${JSON.stringify(store.getState())}</script>
    <script type="module" src="/client.js"></script>
  </body>
</html>`);
});

/**
 * 典型修法：把「客户端才知道的东西」推迟到挂载后。
 * 不要用 suppressHydrationWarning 掩盖真实问题。
 */
function LocalTime({ iso }) {
  const [text, setText] = useState('');        // 首屏两边都渲染空
  useEffect(() => {
    setText(new Date(iso).toLocaleString());   // 挂载后才有本地时区
  }, [iso]);
  return <time dateTime={iso}>{text}</time>;
}

// ❌ 模块顶层访问 window：服务端 import 时就崩
const width = window.innerWidth;

// ✅ 延迟到运行时，并做存在性判断
function getWidth() {
  return typeof window === 'undefined' ? 0 : window.innerWidth;
}

// ✅ 浏览器专属库用动态 import
useEffect(() => {
  import('chart-lib').then(({ render }) => render(ref.current));
}, []);

/**
 * loader 模式：路由匹配后、渲染前拿数据。
 * 好处：没有「加载中闪烁」，数据与路由强绑定。
 * 代价：导航会被数据请求阻塞，需要 loading 反馈。
 */
const router = createBrowserRouter([
  {
    path: '/orders/:id',
    loader: async ({ params }) => {
      const order = await fetchOrder(params.id);
      if (!order) throw new Response('Not Found', { status: 404 });
      return order;
    },
    element: <OrderDetail />,
    errorElement: <RouteError />,
  },
]);

function OrderDetail() {
  const order = useLoaderData(); // 同步拿到，无需 loading 分支
  return <Detail data={order} />;
}

/**
 * 意图预取：hover / 可见时提前加载下一页的代码与数据。
 * 注意节制：预取过多会挤占带宽，反而拖慢当前页。
 */
function OrderLink({ id }) {
  const queryClient = useQueryClient();
  const prefetch = () => {
    queryClient.prefetchQuery({ queryKey: ['order', id], queryFn: () => fetchOrder(id), staleTime: 30_000 });
  };

  return (
    <Link to={`/orders/${id}`} onMouseEnter={prefetch} onFocus={prefetch}>
      订单 {id}
    </Link>
  );
}

/**
 * 路由级错误边界：一个页面崩了，导航仍然可用。
 * 404 也用 errorElement 承载（loader 抛 404 Response）。
 */
<Route path="orders/:id" element={<OrderDetail />} errorElement={<RouteError />} />

/**
 * 滚动恢复：SPA 默认不会像 MPA 那样还原位置。
 * 规则：前进/后退还原，新导航置顶。
 */
function ScrollRestoration() {
  const { pathname } = useLocation();
  const navigationType = useNavigationType(); // POP | PUSH | REPLACE

  useEffect(() => {
    if (navigationType === 'POP') return; // 后退交给浏览器/自行缓存
    window.scrollTo(0, 0);
  }, [pathname, navigationType]);

  return null;
}

时间轴（传统 SSR）
[等待数据 800ms][渲染 200ms][传输 300ms] → 首字节 1.3s

时间轴（流式 SSR）
[壳 50ms] → 立即返回 → [商品区 400ms] → 追加 → [推荐区 800ms] → 追加
首字节 50ms，用户先看到布局与骨架

/**
 * Suspense 是流式的边界：fallback 先发给浏览器，
 * 数据就绪后，服务端把「补充 HTML + 切换脚本」一起推过去。
 */
<Suspense fallback={<Skeleton />}>
  <SlowRecommendations />   {/* 服务端 await 数据，期间先发 fallback */}
</Suspense>

/**
 * 服务端组件：直接查库、读文件，不会进入客户端包。
 * 需要交互的部分，拆成带 'use client' 的客户端组件。
 */
async function OrderPage({ id }) {
  const order = await db.order.findUnique({ where: { id } }); // 只在服务端执行
  return (
    <section>
      <h1>{order.title}</h1>
      <PayButton orderId={order.id} />   {/* 客户端组件：有交互 */}
    </section>
  );
}

用户 → 最近的边缘节点（50ms 内）
        ├─ 命中缓存 → 直接返回（10ms）
        └─ 未命中 → 边缘执行渲染 / 回源

/dashboard
  ├─ @analytics   （并行槽位：独立加载、独立 Suspense）
  ├─ @team
  └─ children     （主内容）

/**
 * 用 Suspense 划分可独立水合的边界：
 * 首屏关键区先水合，评论区等次要区域延后。
 */
function App() {
  return (
    <Layout>
      <Suspense fallback={<Skeleton />}>
        <Header />
        <ProductInfo />
      </Suspense>
      <Suspense fallback={<CommentSkeleton />}>
        <Comments />
      </Suspense>
    </Layout>
  );
}

页面是否需要被搜索引擎收录？
├─ 否 → 是否登录后可见？
│        ├─ 是 → CSR（可加 BFF 聚合）
│        └─ 否 → SSG（营销页首选）
└─ 是 → 内容是否每人不同？
         ├─ 否 → 更新频率？
         │        ├─ 低 → SSG
         │        └─ 中 → ISR
         └─ 是 → 能否接受服务器成本？
                  ├─ 能 → SSR / RSC（+ 流式）
                  └─ 不能 → SSR + 分层缓存，或 RSC 局部化

/order/share/:token  → SSR + 短缓存（60s）+ 流式
其余 /app/*         → CSR

/**
 * 分享页：SSR + 流式 + CDN 缓存。
 * 注意：token 相关数据不进共享缓存，按 token 做 key 或直接 no-store。
 */
export async function loader({ params }) {
  const order = await getSharedOrder(params.token);
  if (!order) throw new Response('Not Found', { status: 404 });
  return order;
}

export default function SharedOrder() {
  const order = useLoaderData();
  return (
    <>
      <OrderSummary order={order} />          {/* 关键内容先渲染 */}
      <Suspense fallback={<Skeleton />}>
        <Recommendations orderId={order.id} /> {/* 慢区块后补 */}
      </Suspense>
    </>
  );
}

/**
 * 极简 history 路由：支持动态参数与通配。
 * @param {Array<{path: string, render: (params: object) => void}>} routes
 */
function createRouter(routes) {
  /** 把 /user/:id 编译为正则与参数名 */
  const compile = (path) => {
    const keys = [];
    const source = path
      .replace(/\/:(\w+)/g, (_, key) => {
        keys.push(key);
        return '/([^/]+)';
      })
      .replace(/\*/g, '(.*)');
    return { keys, regex: new RegExp(`^${source}$`) };
  };

  const table = routes.map((route) => ({ ...route, ...compile(route.path) }));

  /** 匹配当前路径并渲染 */
  const resolve = () => {
    const path = location.pathname;
    for (const route of table) {
      const matched = path.match(route.regex);
      if (!matched) continue;
      const params = Object.fromEntries(route.keys.map((k, i) => [k, decodeURIComponent(matched[i + 1])]));
      route.render(params);
      return;
    }
    // 未匹配：交给 404 处理
  };

  /**
   * 编程式导航。
   * @param {string} url 目标地址
   * @param {{replace?: boolean}} [options]
   */
  const push = (url, { replace = false } = {}) => {
    history[replace ? 'replaceState' : 'pushState']({}, '', url);
    resolve();
  };

  window.addEventListener('popstate', resolve);
  document.addEventListener('click', (e) => {
    const link = e.target.closest('a[data-link]');
    if (!link || e.metaKey || e.ctrlKey || link.target === '_blank') return;
    e.preventDefault();
    push(link.getAttribute('href'));
  });

  resolve();
  return { push };
}

/**
 * 将路由模式转为匹配器，静态段得分高于动态段。
 * @param {string} pattern 形如 /order/:id/detail
 */
function createMatcher(pattern) {
  const segments = pattern.split('/').filter(Boolean);
  const keys = [];

  const regex = new RegExp(
    '^' +
      segments
        .map((seg) => {
          if (seg === '*') {
            keys.push('wildcard');
            return '(.*)';
          }
          if (seg.startsWith(':')) {
            keys.push(seg.slice(1));
            return '([^/]+)';
          }
          return '/' + seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
        })
        .join('')
        .replace(/^\/\//, '/') +
      '/?$'
  );

  /** 静态段越多越优先，通配最少优先 */
  const score = segments.reduce((acc, seg) => {
    if (seg === '*') return acc - 10;
    if (seg.startsWith(':')) return acc + 1;
    return acc + 3;
  }, 0);

  return {
    score,
    match(path) {
      const m = path.match(regex);
      if (!m) return null;
      return Object.fromEntries(keys.map((k, i) => [k, m[i + 1]]));
    },
  };
}