React 应用架构设计最佳实践

src/
├── components/
│   ├── Button.tsx
│   ├── Modal.tsx
│   └── Header.tsx
├── hooks/
│   ├── useAuth.ts
│   └── useApi.ts
├── utils/
│   └── helpers.ts
└── App.tsx

src/
├── features/
│   ├── auth/
│   │   ├── components/
│   │   │   ├── LoginForm.tsx
│   │   │   └── RegisterForm.tsx
│   │   ├── hooks/
│   │   │   └── useAuth.ts
│   │   ├── api/
│   │   │   └── authApi.ts
│   │   ├── types/
│   │   │   └── auth.types.ts
│   │   ├── utils/
│   │   │   └── validators.ts
│   │   └── index.ts          // 唯一对外出口（barrel file）
│   ├── dashboard/
│   └── profile/
├── shared/
│   ├── components/           // 跨功能复用的 UI 组件
│   ├── hooks/
│   └── utils/
├── lib/                      // 第三方库封装（axios 实例、dayjs 配置等）
├── app/                      // 应用级配置（路由、Provider、store）
└── App.tsx

// features/auth/index.ts —— 只导出对外契约
export { LoginForm } from './components/LoginForm';
export { RegisterForm } from './components/RegisterForm';
export { useAuth } from './hooks/useAuth';
export type { User, AuthState } from './types/auth.types';
// 注意：authApi、validators 是内部实现，不导出，外部无法直接依赖

// .eslintrc.js —— 禁止绕过 barrel file 直接 import 功能内部文件
module.exports = {
  rules: {
    'no-restricted-imports': ['error', {
      patterns: [
        {
          group: ['@/features/*/*'],
          message: '请从 features/xxx 的 index.ts 导入，禁止依赖内部实现文件',
        },
      ],
    }],
  },
};

// ❌ 反例：UI 组件里直接写 fetch，三层耦合在一起，无法测试、无法复用
const UserPage = () => {
  const [user, setUser] = useState(null);
  useEffect(() => {
    fetch('https://api.example.com/user/1', {
      headers: { Authorization: 'Bearer ' + localStorage.getItem('token') },
    })
      .then((r) => r.json())
      .then((data) => setUser({ ...data, displayName: data.first + ' ' + data.last }));
  }, []);
  return <div>{user?.displayName}</div>;
};

// ✅ 正例：三层分离

// —— 数据访问层：features/user/api/userApi.ts ——
import { httpClient } from '@/lib/http';
import type { UserDTO } from '../types/user.types';

export const userApi = {
  getById: (id: string) => httpClient.get<UserDTO>(`/user/${id}`),
};

// —— 业务逻辑层：features/user/hooks/useUser.ts ——
import { useQuery } from '@tanstack/react-query';
import { userApi } from '../api/userApi';

export function useUser(id: string) {
  return useQuery({
    queryKey: ['user', id],
    queryFn: () => userApi.getById(id),
    // 业务规则：把后端 DTO 转换为前端领域模型
    select: (dto) => ({
      id: dto.id,
      displayName: `${dto.first} ${dto.last}`,
      isVip: dto.level >= 3,
    }),
  });
}

// —— 表现层：features/user/components/UserPage.tsx ——
export const UserPage = ({ id }: { id: string }) => {
  const { data: user, isLoading } = useUser(id);
  if (isLoading) return <Spinner />;
  return <div>{user?.displayName}{user?.isVip && <VipBadge />}</div>;
};

// 定义抽象接口（契约）
export interface AnalyticsClient {
  track(event: string, payload?: Record<string, unknown>): void;
}

// 具体实现可以有多个：生产用 Segment，测试用 mock
class SegmentAnalytics implements AnalyticsClient {
  track(event: string, payload?: Record<string, unknown>) {
    window.analytics?.track(event, payload);
  }
}

class NoopAnalytics implements AnalyticsClient {
  track() { /* 测试环境什么都不做 */ }
}

// 通过 Context 注入抽象，组件只依赖接口
const AnalyticsContext = createContext<AnalyticsClient>(new NoopAnalytics());

export const useAnalytics = () => useContext(AnalyticsContext);

// 业务组件不知道底层是 Segment 还是别的，只依赖 track 契约
const CheckoutButton = () => {
  const analytics = useAnalytics();
  return <button onClick={() => analytics.track('checkout_clicked')}>结算</button>;
};

// 生产环境注入真实实现，测试环境注入 Noop，实现了控制反转
// <AnalyticsContext.Provider value={new SegmentAnalytics()}>

// 原子组件：Button
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'danger';
  size?: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
  onClick?: () => void;
  disabled?: boolean;
}

const Button: React.FC<ButtonProps> = ({
  variant = 'primary',
  size = 'md',
  children,
  onClick,
  disabled = false,
}) => {
  return (
    <button
      className={`btn btn-${variant} btn-${size}`}
      onClick={onClick}
      disabled={disabled}
    >
      {children}
    </button>
  );
};

// 原子组件：Input
interface InputProps {
  value: string;
  onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
  placeholder?: string;
  type?: string;
}

const Input: React.FC<InputProps> = ({ value, onChange, placeholder, type = 'text' }) => (
  <input className="input" value={value} onChange={onChange} placeholder={placeholder} type={type} />
);

// 分子组件：SearchForm（组合 Input + Button）
const SearchForm: React.FC<{ onSearch: (query: string) => void }> = ({ onSearch }) => {
  const [query, setQuery] = useState('');

  return (
    <form onSubmit={(e) => { e.preventDefault(); onSearch(query); }}>
      <Input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search..."
      />
      <Button>Search</Button>
    </form>
  );
};

// 组织组件：Header（组合多个分子/原子）
const Header: React.FC<{ onSearch: (q: string) => void }> = ({ onSearch }) => {
  return (
    <header className="header">
      <Logo />
      <Navigation />
      <SearchForm onSearch={onSearch} />
      <UserMenu />
    </header>
  );
};

// 模板组件：定义布局骨架，用 slot（children/props）填充
interface DashboardTemplateProps {
  header: React.ReactNode;
  sidebar: React.ReactNode;
  main: React.ReactNode;
}

const DashboardTemplate: React.FC<DashboardTemplateProps> = ({ header, sidebar, main }) => (
  <div className="dashboard-layout">
    <div className="dashboard-header">{header}</div>
    <div className="dashboard-body">
      <aside className="dashboard-sidebar">{sidebar}</aside>
      <main className="dashboard-main">{main}</main>
    </div>
  </div>
);

// 展示组件：纯函数式，只关心怎么画
interface UserCardProps {
  name: string;
  avatar: string;
  online: boolean;
  onMessage: () => void;
}

const UserCard: React.FC<UserCardProps> = ({ name, avatar, online, onMessage }) => (
  <div className="user-card">
    <img src={avatar} alt={name} />
    <span>{name}</span>
    {online && <span className="dot-online" />}
    <Button onClick={onMessage}>发消息</Button>
  </div>
);

// 容器组件：负责取数据、处理业务，委托展示组件渲染
const UserCardContainer: React.FC<{ userId: string }> = ({ userId }) => {
  const { data: user } = useUser(userId);
  const { mutate: openChat } = useOpenChat();

  if (!user) return <UserCardSkeleton />;

  return (
    <UserCard
      name={user.displayName}
      avatar={user.avatar}
      online={user.online}
      onMessage={() => openChat(userId)}
    />
  );
};

// 父子组件通信：props 向下，回调向上
interface ChildProps {
  data: string;
  onUpdate: (newValue: string) => void;
}

const Child: React.FC<ChildProps> = ({ data, onUpdate }) => (
  <div>
    <span>{data}</span>
    <button onClick={() => onUpdate('new value')}>Update</button>
  </div>
);

const Parent: React.FC = () => {
  const [value, setValue] = useState('initial');
  return <Child data={value} onUpdate={setValue} />;
};

// ❌ props drilling：theme 层层透传
const App = () => {
  const [theme, setTheme] = useState('light');
  return <Page theme={theme} setTheme={setTheme} />;
};
const Page = ({ theme, setTheme }) => <Layout theme={theme} setTheme={setTheme} />;
const Layout = ({ theme, setTheme }) => <Toolbar theme={theme} setTheme={setTheme} />;
const Toolbar = ({ theme, setTheme }) => <ThemeButton theme={theme} setTheme={setTheme} />;

// ✅ 用 Context 消除透传
const ThemeContext = createContext<{ theme: string; setTheme: (t: string) => void }>({
  theme: 'light',
  setTheme: () => {},
});

const ThemedButton: React.FC = () => {
  const { theme, setTheme } = useContext(ThemeContext);
  return (
    <button
      className={`btn btn-${theme}`}
      onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}
    >
      Toggle Theme
    </button>
  );
};

// 通用数据请求 Hook
function useFetch<T>(url: string) {
  const [data, setData] = useState<T | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    let cancelled = false;
    setLoading(true);
    fetch(url)
      .then((res) => {
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
        return res.json();
      })
      .then((json) => { if (!cancelled) setData(json); })
      .catch((e) => { if (!cancelled) setError(e); })
      .finally(() => { if (!cancelled) setLoading(false); });
    return () => { cancelled = true; }; // 清理，避免卸载后 setState
  }, [url]);

  return { data, loading, error };
}

// 防抖 Hook
function useDebounce<T>(value: T, delay = 300): T {
  const [debounced, setDebounced] = useState(value);
  useEffect(() => {
    const timer = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(timer);
  }, [value, delay]);
  return debounced;
}

// 本地存储同步 Hook
function useLocalStorage<T>(key: string, initial: T) {
  const [value, setValue] = useState<T>(() => {
    const raw = localStorage.getItem(key);
    return raw ? (JSON.parse(raw) as T) : initial;
  });
  useEffect(() => {
    localStorage.setItem(key, JSON.stringify(value));
  }, [key, value]);
  return [value, setValue] as const;
}

// 组合使用：搜索框 + 防抖 + 请求
const SearchPage = () => {
  const [keyword, setKeyword] = useState('');
  const debouncedKeyword = useDebounce(keyword, 400);
  const { data, loading } = useFetch<Result[]>(`/api/search?q=${debouncedKeyword}`);

  return (
    <div>
      <input value={keyword} onChange={(e) => setKeyword(e.target.value)} />
      {loading ? <Spinner /> : <ResultList results={data ?? []} />}
    </div>
  );
};

interface DataFetcherProps<T> {
  url: string;
  children: (state: { data: T | null; loading: boolean; error: Error | null }) => React.ReactNode;
}

function DataFetcher<T>({ url, children }: DataFetcherProps<T>) {
  const { data, loading, error } = useFetch<T>(url);
  return <>{children({ data, loading, error })}</>;
}

// 使用：调用方完全掌控渲染
<DataFetcher<User[]> url="/api/users">
  {({ data, loading, error }) => {
    if (loading) return <Spinner />;
    if (error) return <ErrorView message={error.message} />;
    return <UserList users={data ?? []} />;
  }}
</DataFetcher>

// 加载态 HOC
function withLoading<P extends object>(Wrapped: React.ComponentType<P>) {
  return function WithLoading(props: P & { isLoading: boolean }) {
    const { isLoading, ...rest } = props;
    if (isLoading) return <Spinner />;
    return <Wrapped {...(rest as P)} />;
  };
}

// 权限控制 HOC
function withAuth<P extends object>(Wrapped: React.ComponentType<P>, requiredRole: string) {
  return function WithAuth(props: P) {
    const { user } = useUser('me');
    if (!user) return <Redirect to="/login" />;
    if (!user.roles.includes(requiredRole)) return <Forbidden />;
    return <Wrapped {...props} />;
  };
}

// 组合使用
const ProtectedDashboard = withAuth(withLoading(Dashboard), 'admin');

// —— 1. 组件内部状态：useState ——
const Counter: React.FC = () => {
  const [count, setCount] = useState(0);
  return (
    <div>
      <span>{count}</span>
      <button onClick={() => setCount((c) => c + 1)}>+1</button>
    </div>
  );
};

// —— 复杂内部状态：useReducer ——
type Action =
  | { type: 'add'; text: string }
  | { type: 'toggle'; id: string }
  | { type: 'clear' };

function todoReducer(state: Todo[], action: Action): Todo[] {
  switch (action.type) {
    case 'add':
      return [...state, { id: crypto.randomUUID(), text: action.text, done: false }];
    case 'toggle':
      return state.map((t) => (t.id === action.id ? { ...t, done: !t.done } : t));
    case 'clear':
      return state.filter((t) => !t.done);
    default:
      return state;
  }
}

const TodoApp = () => {
  const [todos, dispatch] = useReducer(todoReducer, []);
  return <TodoList todos={todos} onToggle={(id) => dispatch({ type: 'toggle', id })} />;
};

// —— 2. 跨组件状态：Context API ——
interface User {
  id: string;
  name: string;
  email: string;
}

interface UserContextType {
  user: User | null;
  login: (user: User) => void;
  logout: () => void;
}

const UserContext = createContext<UserContextType | null>(null);

export const UserProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const [user, setUser] = useState<User | null>(null);

  // 用 useMemo 稳定 value 引用，避免 Provider 每次渲染都触发所有消费者重渲染
  const value = useMemo(
    () => ({
      user,
      login: (u: User) => setUser(u),
      logout: () => setUser(null),
    }),
    [user],
  );

  return <UserContext.Provider value={value}>{children}</UserContext.Provider>;
};

export const useUserContext = () => {
  const context = useContext(UserContext);
  if (!context) throw new Error('useUserContext must be used within UserProvider');
  return context;
};

// —— 3a. 全局状态：Zustand（轻量、无样板） ——
import { create } from 'zustand';
import { devtools, persist } from 'zustand/middleware';

interface CartState {
  items: CartItem[];
  addItem: (item: CartItem) => void;
  removeItem: (id: string) => void;
  total: () => number;
}

const useCartStore = create<CartState>()(
  devtools(
    persist(
      (set, get) => ({
        items: [],
        addItem: (item) => set((s) => ({ items: [...s.items, item] })),
        removeItem: (id) => set((s) => ({ items: s.items.filter((i) => i.id !== id) })),
        total: () => get().items.reduce((sum, i) => sum + i.price * i.qty, 0),
      }),
      { name: 'cart-storage' }, // 自动持久化到 localStorage
    ),
  ),
);

// 组件中按需订阅，只有 items 变化才重渲染
const CartBadge = () => {
  const count = useCartStore((s) => s.items.length);
  return <span>{count}</span>;
};

// —— 3b. 全局状态：Redux Toolkit（大型团队、需要严格规范） ——
import { createSlice, configureStore, PayloadAction } from '@reduxjs/toolkit';

interface AuthState {
  token: string | null;
  status: 'idle' | 'loading' | 'authenticated';
}

const authSlice = createSlice({
  name: 'auth',
  initialState: { token: null, status: 'idle' } as AuthState,
  reducers: {
    setToken: (state, action: PayloadAction<string>) => {
      state.token = action.payload;      // Immer 让你"直接改"，底层生成不可变副本
      state.status = 'authenticated';
    },
    logout: (state) => {
      state.token = null;
      state.status = 'idle';
    },
  },
});

export const { setToken, logout } = authSlice.actions;

export const store = configureStore({
  reducer: { auth: authSlice.reducer },
});

export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;

// —— 3c. 全局状态：Jotai（原子化、自底向上） ——
import { atom, useAtom } from 'jotai';

const countAtom = atom(0);
const doubledAtom = atom((get) => get(countAtom) * 2); // 派生 atom，自动追踪依赖

const JotaiCounter = () => {
  const [count, setCount] = useAtom(countAtom);
  const [doubled] = useAtom(doubledAtom);
  return (
    <div>
      <p>{count} × 2 = {doubled}</p>
      <button onClick={() => setCount((c) => c + 1)}>+1</button>
    </div>
  );
};

// ❌ 错误：冗余状态，fullName 与 firstName/lastName 会不同步
const [firstName, setFirstName] = useState('');
const [lastName, setLastName] = useState('');
const [fullName, setFullName] = useState(''); // 冗余！

// ✅ 正确：最小化状态 + 派生值
const [firstName, setFirstName] = useState('');
const [lastName, setLastName] = useState('');
const fullName = `${firstName} ${lastName}`; // 渲染时派生，永远同步

// ✅ 昂贵派生用 useMemo 缓存
const sortedFilteredList = useMemo(() => {
  return rawData.filter((x) => x.active).sort((a, b) => a.rank - b.rank);
}, [rawData]);

interface TodoListProps {
  todos: Todo[];
  onToggle: (id: string) => void;
  onDelete: (id: string) => void;
}

const TodoList: React.FC<TodoListProps> = ({ todos, onToggle, onDelete }) => (
  <ul>
    {todos.map((todo) => (
      <TodoItem key={todo.id} todo={todo} onToggle={onToggle} onDelete={onDelete} />
    ))}
  </ul>
);

// 父组件是唯一的状态权威，子组件通过回调"申请"变更
const TodoApp: React.FC = () => {
  const [todos, setTodos] = useState<Todo[]>([]);

  const handleToggle = (id: string) =>
    setTodos((prev) => prev.map((t) => (t.id === id ? { ...t, completed: !t.completed } : t)));

  const handleDelete = (id: string) =>
    setTodos((prev) => prev.filter((t) => t.id !== id));

  return <TodoList todos={todos} onToggle={handleToggle} onDelete={handleDelete} />;
};

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

// 基础查询：带缓存策略
const useUserPosts = (userId: string) =>
  useQuery({
    queryKey: ['posts', userId],
    queryFn: () => fetchUserPosts(userId),
    staleTime: 5 * 60 * 1000,   // 5 分钟内数据视为新鲜，不重新请求
    gcTime: 10 * 60 * 1000,     // 组件卸载后缓存保留 10 分钟
    refetchOnWindowFocus: true, // 窗口重新聚焦时后台刷新
    retry: 3,                   // 失败自动重试 3 次
  });

// 依赖查询：等前一个查询完成才发起
const useUserAndPosts = (userId: string) => {
  const userQuery = useQuery({ queryKey: ['user', userId], queryFn: () => fetchUser(userId) });
  const postsQuery = useQuery({
    queryKey: ['posts', userId],
    queryFn: () => fetchUserPosts(userId),
    enabled: !!userQuery.data, // 只有拿到 user 后才查 posts
  });
  return { userQuery, postsQuery };
};

// 分页查询
const usePaginatedPosts = (page: number) =>
  useQuery({
    queryKey: ['posts', 'page', page],
    queryFn: () => fetchPosts(page),
    placeholderData: (prev) => prev, // 翻页时保留上一页数据，避免闪烁
  });

const useToggleLike = () => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (postId: string) => api.toggleLike(postId),

    onMutate: async (postId) => {
      // 1. 取消正在进行的相关查询，避免覆盖乐观更新
      await queryClient.cancelQueries({ queryKey: ['posts'] });

      // 2. 快照旧数据，用于回滚
      const previous = queryClient.getQueryData<Post[]>(['posts']);

      // 3. 乐观地立即更新缓存
      queryClient.setQueryData<Post[]>(['posts'], (old) =>
        (old ?? []).map((p) =>
          p.id === postId ? { ...p, liked: !p.liked, likes: p.likes + (p.liked ? -1 : 1) } : p,
        ),
      );

      return { previous };
    },

    onError: (_err, _postId, context) => {
      // 4. 失败：回滚到快照
      if (context?.previous) queryClient.setQueryData(['posts'], context.previous);
    },

    onSettled: () => {
      // 5. 无论成败，最终与服务器同步一次
      queryClient.invalidateQueries({ queryKey: ['posts'] });
    },
  });
};

my-monorepo/
├── apps/
│   ├── web/                  // 主站
│   ├── admin/                // 管理后台
│   └── mobile-h5/            // 移动 H5
├── packages/
│   ├── ui/                   // 共享组件库
│   ├── hooks/                // 共享 hooks
│   ├── utils/                // 共享工具
│   ├── api-client/           // 共享 API 客户端
│   ├── tsconfig/             // 共享 TS 配置
│   └── eslint-config/        // 共享 lint 配置
├── pnpm-workspace.yaml
├── turbo.json
└── package.json

// turbo.json —— 定义任务依赖与缓存
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "lint": {},
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

// apps/web/package.json 里声明依赖 "@myorg/ui": "workspace:*"
import { Button, Modal } from '@myorg/ui';
import { useDebounce } from '@myorg/hooks';
import { formatCurrency } from '@myorg/utils';

import { lazy, Suspense } from 'react';
import { createBrowserRouter } from 'react-router-dom';

// 每个页面单独打包，访问时才加载
const Dashboard = lazy(() => import('./pages/Dashboard'));
const Settings = lazy(() => import('./pages/Settings'));
const Reports = lazy(() => import('./pages/Reports'));

const router = createBrowserRouter([
  {
    path: '/dashboard',
    element: (
      <Suspense fallback={<PageSkeleton />}>
        <Dashboard />
      </Suspense>
    ),
  },
  {
    path: '/settings',
    element: (
      <Suspense fallback={<PageSkeleton />}>
        <Settings />
      </Suspense>
    ),
  },
]);

// 重量级组件（如富文本编辑器、图表库）按需加载
const RichEditor = lazy(() => import('./RichEditor'));

const ArticleForm = () => {
  const [editing, setEditing] = useState(false);
  return (
    <div>
      <button
        onClick={() => setEditing(true)}
        // 鼠标悬停即预加载，点击时几乎无等待
        onMouseEnter={() => import('./RichEditor')}
      >
        开始编辑
      </button>
      {editing && (
        <Suspense fallback={<Spinner />}>
          <RichEditor />
        </Suspense>
      )}
    </div>
  );
};

import { Component, ErrorInfo, ReactNode } from 'react';

interface Props {
  fallback: (error: Error, reset: () => void) => ReactNode;
  children: ReactNode;
}

interface State {
  error: Error | null;
}

class ErrorBoundary extends Component<Props, State> {
  state: State = { error: null };

  static getDerivedStateFromError(error: Error): State {
    return { error }; // 渲染出错时切换到 fallback UI
  }

  componentDidCatch(error: Error, info: ErrorInfo) {
    // 上报到监控平台（Sentry 等）
    reportError(error, { componentStack: info.componentStack });
  }

  reset = () => this.setState({ error: null });

  render() {
    if (this.state.error) return this.props.fallback(this.state.error, this.reset);
    return this.props.children;
  }
}

// 分区包裹：某个 widget 崩溃不影响整页
const DashboardPage = () => (
  <div>
    <ErrorBoundary fallback={(e, reset) => <WidgetError onRetry={reset} />}>
      <RevenueWidget />
    </ErrorBoundary>
    <ErrorBoundary fallback={(e, reset) => <WidgetError onRetry={reset} />}>
      <UserActivityWidget />
    </ErrorBoundary>
  </div>
);

// —— 组件集成测试：React Testing Library ——
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { LoginForm } from './LoginForm';

describe('LoginForm', () => {
  it('renders email and password inputs', () => {
    render(<LoginForm onSubmit={jest.fn()} />);
    expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
    expect(screen.getByLabelText(/password/i)).toBeInTheDocument();
  });

  it('calls onSubmit with form data', async () => {
    const handleSubmit = jest.fn();
    render(<LoginForm onSubmit={handleSubmit} />);

    await userEvent.type(screen.getByLabelText(/email/i), 'test@example.com');
    await userEvent.type(screen.getByLabelText(/password/i), 'password123');
    await userEvent.click(screen.getByRole('button', { name: /submit/i }));

    expect(handleSubmit).toHaveBeenCalledWith({
      email: 'test@example.com',
      password: 'password123',
    });
  });

  it('shows validation error for invalid email', async () => {
    render(<LoginForm onSubmit={jest.fn()} />);
    await userEvent.type(screen.getByLabelText(/email/i), 'invalid-email');
    await userEvent.click(screen.getByRole('button', { name: /submit/i }));
    expect(screen.getByText(/invalid email/i)).toBeInTheDocument();
  });
});

// —— 自定义 Hook 测试：renderHook ——
import { renderHook, act } from '@testing-library/react';
import { useCounter } from './useCounter';

it('increments count', () => {
  const { result } = renderHook(() => useCounter(0));
  expect(result.current.count).toBe(0);
  act(() => result.current.increment());
  expect(result.current.count).toBe(1);
});

// —— API mock：MSW（Mock Service Worker）在网络层拦截，测试更真实 ——
import { http, HttpResponse } from 'msw';
import { setupServer } from 'msw/node';

const server = setupServer(
  http.get('/api/users', () =>
    HttpResponse.json([{ id: '1', name: 'Alice' }]),
  ),
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

import { test, expect } from '@playwright/test';

test('用户能完成登录流程', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('邮箱').fill('user@example.com');
  await page.getByLabel('密码').fill('password123');
  await page.getByRole('button', { name: '登录' }).click();
  await expect(page).toHaveURL('/dashboard');
  await expect(page.getByText('欢迎回来')).toBeVisible();
});

// .eslintrc.js
module.exports = {
  extends: [
    'eslint:recommended',
    'plugin:react/recommended',
    'plugin:react-hooks/recommended',
    'plugin:@typescript-eslint/recommended',
    'prettier',
  ],
  rules: {
    'react/react-in-jsx-scope': 'off',
    'react-hooks/rules-of-hooks': 'error',
    'react-hooks/exhaustive-deps': 'warn',
    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
    // 强制功能模块边界，禁止跨功能深层导入
    'no-restricted-imports': ['error', {
      patterns: [{ group: ['@/features/*/*'], message: '请从 feature 的 index.ts 导入' }],
    }],
  },
};

// .prettierrc
{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 100
}

// package.json
{
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md,css}": ["prettier --write"]
  }
}

/**
 * Button 组件 - 基础按钮组件
 *
 * @example
 * // 基础用法
 * <Button onClick={handleClick}>Click me</Button>
 *
 * // 不同变体
 * <Button variant="primary">Primary</Button>
 * <Button variant="secondary">Secondary</Button>
 * <Button variant="danger">Danger</Button>
 *
 * // 不同尺寸
 * <Button size="sm">Small</Button>
 * <Button size="md">Medium</Button>
 * <Button size="lg">Large</Button>
 */
interface ButtonProps {
  /** 按钮变体样式 */
  variant?: 'primary' | 'secondary' | 'danger';
  /** 按钮尺寸 */
  size?: 'sm' | 'md' | 'lg';
  /** 点击事件处理 */
  onClick?: () => void;
  /** 子元素 */
  children: React.ReactNode;
}

// Button.stories.tsx —— Storybook 交互文档
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: 'Atoms/Button',
  component: Button,
  args: { children: '按钮' },
};
export default meta;

type Story = StoryObj<typeof Button>;

export const Primary: Story = { args: { variant: 'primary' } };
export const Danger: Story = { args: { variant: 'danger' } };
export const Small: Story = { args: { size: 'sm' } };

# GitHub Actions CI/CD 示例
name: CI/CD Pipeline

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Type check
        run: npm run typecheck

      - name: Test
        run: npm run test:coverage

      - name: Build
        run: npm run build

      - name: Upload bundle size report
        run: npx size-limit

      - name: Deploy to Vercel
        if: github.ref == 'refs/heads/main'
        run: npx vercel --prod --token=${{ secrets.VERCEL_TOKEN }}

      - name: Build affected packages only
        run: npx turbo run build lint test --filter=...[origin/main]
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}

# .github/CODEOWNERS
/src/features/auth/       @team-identity
/src/features/payment/    @team-billing
/packages/ui/             @team-design-system
*.config.js               @team-platform

// ❌ 反例：一个巨型 Context，theme 变了连带 user 消费者一起重渲染
interface AppContextType {
  user: User | null;
  theme: 'light' | 'dark';
  locale: string;
  notifications: Notification[];
}
const AppContext = createContext<AppContextType>(/* ... */);

// ✅ 正例：拆分为独立 Context，各自独立更新
const UserContext = createContext<User | null>(null);
const ThemeContext = createContext<'light' | 'dark'>('light');
const LocaleContext = createContext<string>('zh-CN');

// 组合 Provider，但内部状态互不干扰
const AppProviders: React.FC<{ children: React.ReactNode }> = ({ children }) => (
  <UserProvider>
    <ThemeProvider>
      <LocaleProvider>{children}</LocaleProvider>
    </ThemeProvider>
  </UserProvider>
);

const TodoStateContext = createContext<Todo[]>([]);
const TodoDispatchContext = createContext<React.Dispatch<Action>>(() => {});

export const TodoProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const [todos, dispatch] = useReducer(todoReducer, []);
  return (
    <TodoStateContext.Provider value={todos}>
      {/* dispatch 引用永远稳定，只用 dispatch 的组件永不因 todos 变化重渲染 */}
      <TodoDispatchContext.Provider value={dispatch}>
        {children}
      </TodoDispatchContext.Provider>
    </TodoStateContext.Provider>
  );
};

export const useTodos = () => useContext(TodoStateContext);
export const useTodoDispatch = () => useContext(TodoDispatchContext);

// AddButton 只需要 dispatch，不订阅 todos，列表更新时它不重渲染
const AddButton = () => {
  const dispatch = useTodoDispatch();
  return <button onClick={() => dispatch({ type: 'add', text: '新任务' })}>添加</button>;
};

import { createContext, useContextSelector } from 'use-context-selector';

const StoreContext = createContext<{ user: User; cart: Cart } | null>(null);

// 只订阅 user.name，cart 变化不会触发本组件重渲染
const UserName = () => {
  const name = useContextSelector(StoreContext, (s) => s?.user.name);
  return <span>{name}</span>;
};

import { createContext, useContext, useState, ReactNode } from 'react';

interface TabsContextType {
  active: string;
  setActive: (id: string) => void;
}
const TabsContext = createContext<TabsContextType | null>(null);

const useTabs = () => {
  const ctx = useContext(TabsContext);
  if (!ctx) throw new Error('Tabs 子组件必须在 <Tabs> 内使用');
  return ctx;
};

// 父组件：持有共享状态
function Tabs({ defaultValue, children }: { defaultValue: string; children: ReactNode }) {
  const [active, setActive] = useState(defaultValue);
  return (
    <TabsContext.Provider value={{ active, setActive }}>
      <div className="tabs">{children}</div>
    </TabsContext.Provider>
  );
}

// 子组件通过 Context 隐式共享状态，用户无需手动传 props
function TabList({ children }: { children: ReactNode }) {
  return <div className="tab-list" role="tablist">{children}</div>;
}

function Tab({ value, children }: { value: string; children: ReactNode }) {
  const { active, setActive } = useTabs();
  return (
    <button
      role="tab"
      aria-selected={active === value}
      className={active === value ? 'tab tab-active' : 'tab'}
      onClick={() => setActive(value)}
    >
      {children}
    </button>
  );
}

function TabPanel({ value, children }: { value: string; children: ReactNode }) {
  const { active } = useTabs();
  if (active !== value) return null;
  return <div role="tabpanel">{children}</div>;
}

// 挂载子组件，形成命名空间 API
Tabs.List = TabList;
Tabs.Tab = Tab;
Tabs.Panel = TabPanel;

// 使用：声明式、结构一目了然，用户完全掌控布局
const Demo = () => (
  <Tabs defaultValue="profile">
    <Tabs.List>
      <Tabs.Tab value="profile">资料</Tabs.Tab>
      <Tabs.Tab value="settings">设置</Tabs.Tab>
    </Tabs.List>
    <Tabs.Panel value="profile"><ProfilePanel /></Tabs.Panel>
    <Tabs.Panel value="settings"><SettingsPanel /></Tabs.Panel>
  </Tabs>
);

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

// 1. 用 zod 定义 schema，校验规则与类型是同一份来源（single source of truth）
const registerSchema = z
  .object({
    email: z.string().email('邮箱格式不正确'),
    password: z.string().min(8, '密码至少 8 位'),
    confirm: z.string(),
  })
  .refine((data) => data.password === data.confirm, {
    message: '两次密码不一致',
    path: ['confirm'],
  });

// 2. 从 schema 自动推导 TS 类型，无需手写 interface
type RegisterForm = z.infer<typeof registerSchema>;

const RegisterPage = () => {
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting },
  } = useForm<RegisterForm>({ resolver: zodResolver(registerSchema) });

  const onSubmit = async (data: RegisterForm) => {
    await api.register(data); // 校验通过才会走到这里
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('email')} placeholder="邮箱" />
      {errors.email && <span className="error">{errors.email.message}</span>}

      <input type="password" {...register('password')} placeholder="密码" />
      {errors.password && <span className="error">{errors.password.message}</span>}

      <input type="password" {...register('confirm')} placeholder="确认密码" />
      {errors.confirm && <span className="error">{errors.confirm.message}</span>}

      <button disabled={isSubmitting}>{isSubmitting ? '提交中...' : '注册'}</button>
    </form>
  );
};

// lib/http.ts —— 统一的 HTTP 客户端封装
import axios, { AxiosError } from 'axios';

export const httpClient = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  timeout: 15000,
});

// 请求拦截器：统一注入鉴权头
httpClient.interceptors.request.use((config) => {
  const token = getToken();
  if (token) config.headers.Authorization = `Bearer ${token}`;
  return config;
});

// 响应拦截器：统一错误处理与 401 刷新
httpClient.interceptors.response.use(
  (response) => response.data, // 直接返回 data，业务层不用每次 .data
  async (error: AxiosError) => {
    if (error.response?.status === 401) {
      const refreshed = await tryRefreshToken();
      if (refreshed) return httpClient(error.config!); // 刷新成功后重放
      redirectToLogin();
    }
    // 归一化错误结构，业务层拿到统一的 error shape
    return Promise.reject(normalizeError(error));
  },
);

// 统一错误模型
export interface ApiError {
  code: string;
  message: string;
  status: number;
}

function normalizeError(error: AxiosError): ApiError {
  return {
    code: (error.response?.data as any)?.code ?? 'UNKNOWN',
    message: (error.response?.data as any)?.message ?? '网络异常，请稍后重试',
    status: error.response?.status ?? 0,
  };
}

// features/order/api/orderApi.ts —— 领域 API 只声明契约
import { httpClient } from '@/lib/http';
import type { Order, CreateOrderInput } from '../types';

export const orderApi = {
  list: (params: { page: number; status?: string }) =>
    httpClient.get<Order[]>('/orders', { params }),
  detail: (id: string) => httpClient.get<Order>(`/orders/${id}`),
  create: (input: CreateOrderInput) => httpClient.post<Order>('/orders', input),
  cancel: (id: string) => httpClient.post<void>(`/orders/${id}/cancel`),
};

// React.memo：props 未变则跳过重渲染，适合纯展示的重组件
const ExpensiveList = React.memo(({ items }: { items: Item[] }) => (
  <ul>{items.map((i) => <li key={i.id}>{i.name}</li>)}</ul>
));

const Parent = () => {
  const [count, setCount] = useState(0);
  const [items] = useState<Item[]>(bigList);

  // useCallback：稳定回调引用，配合 memo 才生效
  const handleSelect = useCallback((id: string) => {
    console.log('selected', id);
  }, []);

  // useMemo：缓存昂贵计算结果
  const sorted = useMemo(() => [...items].sort((a, b) => a.rank - b.rank), [items]);

  return (
    <>
      <button onClick={() => setCount((c) => c + 1)}>{count}</button>
      {/* count 变化时，ExpensiveList 因 props 未变而不重渲染 */}
      <ExpensiveList items={sorted} onSelect={handleSelect} />
    </>
  );
};

import { useVirtualizer } from '@tanstack/react-virtual';

const VirtualList = ({ rows }: { rows: Row[] }) => {
  const parentRef = useRef<HTMLDivElement>(null);
  const virtualizer = useVirtualizer({
    count: rows.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 40, // 每行预估高度
    overscan: 5,
  });

  return (
    <div ref={parentRef} style={{ height: 600, overflow: 'auto' }}>
      <div style={{ height: virtualizer.getTotalSize(), position: 'relative' }}>
        {virtualizer.getVirtualItems().map((vItem) => (
          <div
            key={vItem.key}
            style={{
              position: 'absolute',
              top: 0,
              transform: `translateY(${vItem.start}px)`,
              height: vItem.size,
            }}
          >
            {rows[vItem.index].name}
          </div>
        ))}
      </div>
    </div>
  );
};

// app/products/page.tsx —— 服务端组件：直接读数据库，不进客户端 bundle
import { db } from '@/lib/db';
import { AddToCartButton } from './AddToCartButton';

export default async function ProductsPage() {
  const products = await db.product.findMany(); // 直接查库，无需 API 层
  return (
    <ul>
      {products.map((p) => (
        <li key={p.id}>
          {p.name} - ￥{p.price}
          {/* 交互部分下沉到客户端组件 */}
          <AddToCartButton productId={p.id} />
        </li>
      ))}
    </ul>
  );
}

// app/products/AddToCartButton.tsx —— 客户端组件：需要 onClick 交互
'use client';
import { useCartStore } from '@/stores/cart';

export function AddToCartButton({ productId }: { productId: string }) {
  const addItem = useCartStore((s) => s.addItem);
  return <button onClick={() => addItem(productId)}>加入购物车</button>;
}

// 集成 Sentry：错误追踪 + 性能监控
import * as Sentry from '@sentry/react';

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN,
  environment: import.meta.env.MODE,
  integrations: [Sentry.browserTracingIntegration(), Sentry.replayIntegration()],
  tracesSampleRate: 0.1,      // 采样 10% 的性能数据
  replaysOnErrorSampleRate: 1, // 出错时录制回放，便于复现
});

// 用 Sentry 增强的错误边界包裹应用
const App = () => (
  <Sentry.ErrorBoundary fallback={<AppCrashScreen />} showDialog>
    <AppProviders>
      <RouterProvider router={router} />
    </AppProviders>
  </Sentry.ErrorBoundary>
);

// 上报核心 Web 指标（Core Web Vitals）
import { onCLS, onINP, onLCP } from 'web-vitals';

function reportWebVitals(metric: { name: string; value: number }) {
  navigator.sendBeacon('/analytics/vitals', JSON.stringify(metric));
}

onLCP(reportWebVitals); // 最大内容绘制
onINP(reportWebVitals); // 交互到下次绘制
onCLS(reportWebVitals); // 累积布局偏移

// config/env.ts —— 集中校验环境变量，缺失即启动失败（fail fast）
import { z } from 'zod';

const envSchema = z.object({
  VITE_API_BASE_URL: z.string().url(),
  VITE_SENTRY_DSN: z.string().optional(),
  MODE: z.enum(['development', 'staging', 'production']),
});

export const env = envSchema.parse(import.meta.env);
// 类型安全的 env，任何拼写错误在启动时就暴露，而非运行时

import { useState, useTransition, useDeferredValue, useMemo } from 'react';

const SearchableList = ({ allItems }: { allItems: Item[] }) => {
  const [query, setQuery] = useState('');
  const [result, setResult] = useState<Item[]>(allItems);
  const [isPending, startTransition] = useTransition();

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const value = e.target.value;
    setQuery(value); // 紧急更新：输入框必须立即响应，不被过滤计算阻塞

    // 非紧急更新：过滤一万条数据，可被后续输入打断、丢弃过时结果
    startTransition(() => {
      const next = allItems.filter((i) =>
        i.name.toLowerCase().includes(value.toLowerCase()),
      );
      setResult(next);
    });
  };

  return (
    <div>
      <input value={query} onChange={handleChange} placeholder="搜索..." />
      {/* isPending 提供过渡态视觉反馈，而非白屏卡顿 */}
      <div style={{ opacity: isPending ? 0.5 : 1 }}>
        <VirtualList rows={result} />
      </div>
    </div>
  );
};

const ProductGrid = ({ keyword }: { keyword: string }) => {
  // 当 keyword 快速变化时，deferredKeyword 会"落后"一拍，让紧急渲染先完成
  const deferredKeyword = useDeferredValue(keyword);
  const isStale = keyword !== deferredKeyword;

  // 昂贵渲染基于延迟值，避免每次击键都重算
  const filtered = useMemo(
    () => heavyFilter(deferredKeyword),
    [deferredKeyword],
  );

  return (
    <div style={{ opacity: isStale ? 0.6 : 1 }}>
      {filtered.map((p) => <ProductCard key={p.id} product={p} />)}
    </div>
  );
};

// 声明式加载：每个数据块独立挂起，先到先渲染，不必等最慢的
const Dashboard = () => (
  <div className="dashboard">
    <Suspense fallback={<CardSkeleton />}>
      <RevenueCard />       {/* 200ms 返回，先渲染 */}
    </Suspense>
    <Suspense fallback={<CardSkeleton />}>
      <SlowAnalyticsCard /> {/* 1500ms 返回，晚渲染，不阻塞上面 */}
    </Suspense>
  </div>
);

// 远程应用 remote (团队 B) webpack.config.js
const { ModuleFederationPlugin } = require('webpack').container;

module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: 'orderApp',
      filename: 'remoteEntry.js',
      // 对外暴露的模块
      exposes: {
        './OrderList': './src/features/order/OrderList',
      },
      // 共享依赖：宿主与远程共用同一份 React 实例，避免 hooks 报错
      shared: {
        react: { singleton: true, requiredVersion: '^18.2.0' },
        'react-dom': { singleton: true, requiredVersion: '^18.2.0' },
      },
    }),
  ],
};

// 宿主应用 host (团队 A) webpack.config.js
new ModuleFederationPlugin({
  name: 'shell',
  remotes: {
    // 运行时从团队 B 的部署地址加载
    orderApp: 'orderApp@https://order.example.com/remoteEntry.js',
  },
  shared: {
    react: { singleton: true },
    'react-dom': { singleton: true },
  },
});

// 宿主中像本地组件一样懒加载远程组件
import { lazy, Suspense } from 'react';

// @ts-expect-error 远程模块类型需通过 d.ts 声明补充
const RemoteOrderList = lazy(() => import('orderApp/OrderList'));

const OrdersRoute = () => (
  <ErrorBoundary fallback={() => <RemoteLoadFailed app="订单" />}>
    <Suspense fallback={<PageSkeleton />}>
      <RemoteOrderList />
    </Suspense>
  </ErrorBoundary>
);

// —— tokens 层：与框架无关的设计变量 ——
export const tokens = {
  color: {
    primary: { 50: '#eff6ff', 500: '#3b82f6', 700: '#1d4ed8' },
    danger: { 500: '#ef4444' },
    neutral: { 0: '#fff', 900: '#111827' },
  },
  spacing: { xs: '4px', sm: '8px', md: '16px', lg: '24px' },
  radius: { sm: '4px', md: '8px', full: '9999px' },
  fontSize: { sm: '14px', md: '16px', lg: '20px' },
} as const;

// —— composed 层：基于 tokens + primitive 封装成品组件 ——
import * as DialogPrimitive from '@radix-ui/react-dialog';
import { tokens } from '../tokens';

// primitive 提供焦点陷阱、ESC 关闭、aria 属性等无障碍能力
export const Modal = ({ open, onClose, title, children }: ModalProps) => (
  <DialogPrimitive.Root open={open} onOpenChange={onClose}>
    <DialogPrimitive.Portal>
      <DialogPrimitive.Overlay className="ds-overlay" />
      <DialogPrimitive.Content
        className="ds-modal"
        style={{ borderRadius: tokens.radius.md, padding: tokens.spacing.lg }}
      >
        <DialogPrimitive.Title>{title}</DialogPrimitive.Title>
        {children}
      </DialogPrimitive.Content>
    </DialogPrimitive.Portal>
  </DialogPrimitive.Root>
);

import { cva, type VariantProps } from 'class-variance-authority';

const buttonVariants = cva('ds-btn', {
  variants: {
    variant: {
      primary: 'ds-btn--primary',
      secondary: 'ds-btn--secondary',
      ghost: 'ds-btn--ghost',
    },
    size: { sm: 'ds-btn--sm', md: 'ds-btn--md', lg: 'ds-btn--lg' },
  },
  defaultVariants: { variant: 'primary', size: 'md' },
});

// 变体类型自动推导，传错值编译期报错
type ButtonProps = VariantProps<typeof buttonVariants> &
  React.ButtonHTMLAttributes<HTMLButtonElement>;

export const Button = ({ variant, size, className, ...rest }: ButtonProps) => (
  <button className={buttonVariants({ variant, size, className })} {...rest} />
);

// 1. 定义各服务的抽象接口
interface Services {
  auth: AuthService;
  analytics: AnalyticsClient;
  storage: StorageService;
  featureFlags: FeatureFlagService;
}

// 2. 创建容器 Context
const ServicesContext = createContext<Services | null>(null);

export const useService = <K extends keyof Services>(key: K): Services[K] => {
  const services = useContext(ServicesContext);
  if (!services) throw new Error('组件必须包裹在 ServicesProvider 内');
  return services[key];
};

// 3. 组合根（Composition Root）：应用启动时在唯一入口装配所有实现
export const ServicesProvider = ({ children }: { children: React.ReactNode }) => {
  const services = useMemo<Services>(
    () => ({
      auth: new HttpAuthService(httpClient),
      analytics: new SegmentAnalytics(),
      storage: new LocalStorageService(),
      featureFlags: new RemoteFeatureFlagService(httpClient),
    }),
    [],
  );
  return <ServicesContext.Provider value={services}>{children}</ServicesContext.Provider>;
};

// 4. 业务组件只依赖抽象，通过 key 取服务
const LoginButton = () => {
  const auth = useService('auth');
  const analytics = useService('analytics');
  const handleLogin = async () => {
    await auth.login();
    analytics.track('login_success');
  };
  return <button onClick={handleLogin}>登录</button>;
};

// 测试专用的假服务集合
const mockServices: Services = {
  auth: { login: jest.fn().mockResolvedValue(true), logout: jest.fn() },
  analytics: { track: jest.fn() },
  storage: { get: jest.fn(), set: jest.fn() },
  featureFlags: { isEnabled: () => true },
};

const renderWithServices = (ui: React.ReactElement) =>
  render(
    <ServicesContext.Provider value={mockServices}>{ui}</ServicesContext.Provider>,
  );

it('登录成功后上报埋点', async () => {
  renderWithServices(<LoginButton />);
  await userEvent.click(screen.getByRole('button', { name: '登录' }));
  expect(mockServices.auth.login).toHaveBeenCalled();
  expect(mockServices.analytics.track).toHaveBeenCalledWith('login_success');
});

import useSWR, { SWRConfig } from 'swr';

// 全局配置：统一 fetcher、错误重试、去重窗口
const AppSWRProvider = ({ children }: { children: React.ReactNode }) => (
  <SWRConfig
    value={{
      fetcher: (url: string) => httpClient.get(url),
      dedupingInterval: 2000,      // 2 秒内相同 key 的请求去重合并
      errorRetryCount: 3,
      revalidateOnFocus: true,     // 窗口聚焦时重新验证
      keepPreviousData: true,      // 切 key 时保留旧数据，避免闪烁
    }}
  >
    {children}
  </SWRConfig>
);

// 使用：key 即缓存键，相同 key 全应用共享同一份缓存
const useProfile = (id: string) => {
  const { data, error, isLoading, mutate } = useSWR<Profile>(`/user/${id}`);
  return { profile: data, error, isLoading, refresh: mutate };
};

UI 组件  ──读──▶  缓存层（SWR / React Query）  ──未命中/过期──▶  API 层  ──▶  后端
   ▲                     │
   └──── 数据变化推送 ─────┘（缓存更新自动触发相关组件重渲染）

import useSWRInfinite from 'swr/infinite';

const usePosts = () => {
  const { data, size, setSize, isValidating } = useSWRInfinite<Post[]>(
    // getKey：根据页码生成每页的缓存键，返回 null 表示到底了
    (pageIndex, prev) => {
      if (prev && prev.length === 0) return null;
      return `/posts?page=${pageIndex + 1}&limit=20`;
    },
  );
  const posts = data ? data.flat() : [];
  const isEnd = data && data[data.length - 1]?.length < 20;
  return { posts, loadMore: () => setSize(size + 1), isEnd, isValidating };
};

import { createBrowserRouter } from 'react-router-dom';

const router = createBrowserRouter([
  {
    path: '/',
    element: <RootLayout />,          // 共享导航/页脚
    errorElement: <RouteError />,     // 路由级错误边界
    children: [
      { index: true, element: <Home /> },
      {
        path: 'dashboard',
        element: <DashboardLayout />,  // 嵌套布局：侧边栏 + Outlet
        loader: requireAuth,           // 进入前的权限守卫
        children: [
          {
            path: 'orders/:id',
            element: <OrderDetail />,
            // loader 在渲染前并行取数，避免组件内 useEffect 瀑布
            loader: ({ params }) => orderApi.detail(params.id!),
          },
        ],
      },
    ],
  },
]);

// loader：路由匹配时自动执行，组件用 useLoaderData 直接拿到数据
export const orderLoader = async ({ params }: LoaderFunctionArgs) => {
  const [order, items] = await Promise.all([
    orderApi.detail(params.id!),
    orderApi.items(params.id!),
  ]); // 并行取数，而非组件挂载后串行
  return { order, items };
};

const OrderDetail = () => {
  const { order, items } = useLoaderData() as OrderLoaderData;
  return <OrderView order={order} items={items} />;
};

// action：表单提交等变更操作，配合 <Form> 声明式提交
export const cancelOrderAction = async ({ params }: ActionFunctionArgs) => {
  await orderApi.cancel(params.id!);
  return redirect('/dashboard/orders');
};

// 以"能力（permission）"而非"角色（role）"为判定单位，更灵活
type Permission =
  | 'order:read' | 'order:write' | 'order:cancel'
  | 'user:manage' | 'report:export';

interface AuthUser {
  id: string;
  roles: string[];
  permissions: Permission[];
}

// 角色到能力的映射集中管理，改权限不用改业务代码
const ROLE_PERMISSIONS: Record<string, Permission[]> = {
  admin: ['order:read', 'order:write', 'order:cancel', 'user:manage', 'report:export'],
  operator: ['order:read', 'order:write'],
  viewer: ['order:read'],
};

const PermissionContext = createContext<Set<Permission>>(new Set());

export const useCan = () => {
  const granted = useContext(PermissionContext);
  return (perm: Permission) => granted.has(perm);
};

// 声明式守卫组件：无权限则不渲染（或渲染兜底）
export const Can = ({
  perform,
  children,
  fallback = null,
}: {
  perform: Permission;
  children: React.ReactNode;
  fallback?: React.ReactNode;
}) => {
  const can = useCan();
  return <>{can(perform) ? children : fallback}</>;
};

// 使用：权限判定与业务 UI 解耦，一目了然
const OrderToolbar = () => (
  <div>
    <Can perform="order:write"><EditButton /></Can>
    <Can perform="order:cancel"><CancelButton /></Can>
    <Can perform="report:export" fallback={<UpgradeHint />}>
      <ExportButton />
    </Can>
  </div>
);

// 与第二十七章的 loader 结合，在进入路由前拦截
export const requirePermission =
  (perm: Permission) =>
  async () => {
    const user = await getCurrentUser();
    if (!user) throw redirect('/login');
    if (!user.permissions.includes(perm)) throw redirect('/403');
    return null;
  };

// 路由配置中挂载
// { path: 'admin/users', loader: requirePermission('user:manage'), element: <UserAdmin /> }

// —— 领域层：纯 TypeScript，不依赖任何 React/网络，可独立单测 ——
// domain/order/Order.ts
export class Order {
  private constructor(
    public readonly id: string,
    public readonly items: OrderItem[],
    private status: OrderStatus,
  ) {}

  static create(items: OrderItem[]): Order {
    if (items.length === 0) throw new DomainError('订单至少包含一件商品');
    return new Order(crypto.randomUUID(), items, 'pending');
  }

  // 业务规则内聚在领域模型里，而非散落在组件
  get total(): number {
    return this.items.reduce((sum, i) => sum + i.price * i.quantity, 0);
  }

  canCancel(): boolean {
    return this.status === 'pending' || this.status === 'paid';
  }

  cancel(): void {
    if (!this.canCancel()) throw new DomainError('已发货订单不可取消');
    this.status = 'cancelled';
  }
}

// —— 领域层可以脱离 React、脱离浏览器直接测试，快且稳 ——
describe('Order 领域规则', () => {
  it('已发货订单不可取消', () => {
    const order = Order.create([{ price: 10, quantity: 1 }]);
    // ...推进到 shipped 状态
    expect(() => order.cancel()).toThrow('已发货订单不可取消');
  });
});

// —— 应用层：用 Hook 把领域模型接入 React ——
export const useOrderActions = (orderId: string) => {
  const queryClient = useQueryClient();
  const { data } = useQuery({
    queryKey: ['order', orderId],
    queryFn: () => orderRepository.findById(orderId), // 仓储把 DTO 还原成领域对象
  });

  const cancel = useMutation({
    mutationFn: async () => {
      data!.cancel();                       // 调用领域规则（会抛领域异常）
      await orderRepository.save(data!);    // 持久化
    },
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['order', orderId] }),
  });

  return { order: data, canCancel: data?.canCancel() ?? false, cancel: cancel.mutate };
};