React 应用架构模式：目录结构、状态管理与性能优化

UI 层：组件渲染（展示 + 交互事件）
状态层：应用状态（全局状态/派生状态）
数据层：数据获取与业务逻辑（请求/缓存/领域逻辑）

→ 原则：组件不直接调 API、业务逻辑不在组件里
→ 分层 = 「组件只管渲染，状态数据另有归属」

UI 层：
  - 组件树：页面/布局/组件
  - 只接收 props + 触发事件
  - 不关心「数据从哪来」

状态层：
  - 全局状态（用户/主题/会话）
  - 派生状态（由基础状态计算）
  - 状态更新逻辑（reducer/store）

数据层：
  - API 请求封装（fetch 客户端）
  - 缓存（响应缓存/失效）
  - 领域逻辑（业务规则/映射）
→ 边界清晰 = 改一层不动另一层

- 可维护：改 API 不动组件、改 UI 不动逻辑
- 可测试：每层独立测（组件/状态/请求）
- 可扩展：新增页面只加 UI + 数据接入
- 职责单一：不出现「巨型组件」
→ 分离 = 降低耦合，让演进可预测

- UI/状态/数据都是「源码」→ Vite 负责转换/打包
- Vite 提供：快速 dev（迭代）、优化构建（产物）
- 工程化工具：env/模块/代码分割由 Vite 管
→ Vite 是「承载三层」的工程基础设施

// UI 层：组件只消费数据与事件
function UserList({ users, onSelect }) {
  return users.map(u => <li onClick={() => onSelect(u.id)}>{u.name}</li>)
}

// 状态层：管理用户列表状态
function useUsers() {
  const [users, setUsers] = useState([])
  // ...加载与更新逻辑
  return { users, refresh: loadUsers }
}

// 数据层：请求封装（与 UI 无关）
async function fetchUsers() {
  const res = await api.get('/users')
  return res.data
}

❌ 按类型组织（大项目失控）：
src/
  components/    ← 几百个组件混在一起
  hooks/         ← 全局 Hook 混排
  pages/         ← 页面杂乱
  utils/         ← 什么都往里塞
→ 按类型 = 组件多了无法定位、边界模糊

✅ 按功能域组织：
src/
  features/
    auth/          ← 登录功能域
      components/
      hooks/
      api.ts
    user/
      components/
      hooks/
      api.ts
  shared/          ← 跨功能共享
    components/
    utils/
  app/             ← 应用级（路由/布局）
→ 按功能 = 每个功能自包含，独立演进

- 功能域内部：私有组件/逻辑（不外泄）
- 功能域间：通过「公开入口」交互（index.ts）
- 共享层：稳定的通用组件/工具（跨域复用）
- 单向依赖：feature → shared，不反向
→ 边界 = 依赖方向 + 公开入口 + 共享稳定

// features/user/index.ts（对外公开面）
export { UserList, useUsers } from './components'
export type { User } from './types'
// 内部细节不外导（api/hooks 私有）
→ 入口 = 对外契约，内部自由演化

- feature → shared（允许）
- feature → feature（尽量避免，用 shared 中转）
- shared 不依赖任何 feature
- 路由/布局在 app 层组合 feature
→ 依赖方向 = 清晰、单向、可预测

- 小项目：单目录即可（别过度设计）
- 中项目：feature + shared 分层
- 大项目：+ 包边界（monorepo，见 monorepo 篇）
- 演进信号：功能域开始「相互拉扯」→ 拆边界
→ 结构 = 跟随规模演进，别一上来大设计

1. 本地状态：组件内（useState/useReducer）
   - 表单输入、展开/收起、局部 UI 状态
2. 全局状态：跨组件共享（Context/Zustand/Jotai/Redux）
   - 用户、主题、会话、偏好
3. 服务端状态：来自 API 的数据（请求库缓存）
   - 用户列表、订单、实时数据
→ 分治 = 每种状态用「对的工具」，不混用

// 本地：组件私有，用 useState/useReducer
function SearchBox() {
  const [query, setQuery] = useState('')
  // 只在组件内用，不全局化
}
// 原则：能用本地就不用全局（局部化状态）

- Context：内置，轻量（中等规模够用）
- Zustand：轻量、简洁、无模板（推荐起步）
- Jotai：原子式（精细粒度，复杂场景）
- Redux：重型、规范（大型 + 严格工具链）
→ 选型 = 规模 × 复杂度 × 团队习惯

- 服务端状态：来自后端，需要「缓存/失效/重试」
- 用请求库管理（TanStack Query / SWR）
  - 缓存：相同请求复用（避免重复拉）
  - 失效：数据变更后自动刷新
  - 重试：失败自动重试
  - 乐观更新：先更新 UI 再确认
→ 服务端状态 ≠ 全局状态，别塞进 Redux

- 只被一个组件用 → 本地
- 被多个「兄弟/子树」共享 → Context/全局
- 来自 API 的异步数据 → 请求库缓存
- 派生值 → 用 selector/计算（别复制状态）
→ 判断 = 作用域 × 来源 × 派生

- 过度全局化：所有 state 都进 store（臃肿）
- 重复存储：同数据多份拷贝（不同步）
- 派生状态冗余：能算的硬存（bug 源）
- 服务端状态塞进全局 store（缓存失效难）
→ 反模式 = 作用域不对 + 重复 + 冗余派生

import { lazy, Suspense } from 'react'
import { BrowserRouter, Routes, Route } from 'react-router-dom'

const About = lazy(() => import('./pages/About'))
const User = lazy(() => import('./pages/User'))

function AppRoutes() {
  return (
    <BrowserRouter>
      <Suspense fallback={<Loading />}>
        <Routes>
          <Route path="/" element={<About />} />
          <Route path="/user/:id" element={<User />} />
        </Routes>
      </Suspense>
    </BrowserRouter>
  )
}
// 每个路由 → 独立 chunk（用到才加载）

- lazy + Suspense：路由级代码分割（首包小）
- 预取：hover/即将进入时预加载（import 提前）
  - 路由 hover：onMouseEnter 触发 import
  - vite:preload：静态已知动态导入自动预取
- 平衡：预取太多 = 请求爆炸
→ 分割 + 预取 = 首包小 + 切换快

- 集中路由表（routes.ts）：路径 → 懒组件
- 嵌套路由：布局与子路由（Outlet）
- 路由守卫：鉴权/权限（包裹 Route）
- 路由元数据：标题/权限/懒加载标记
→ 路由表 = 集中声明 + 守卫 + 元数据

- 路由级：每路由一个 chunk（最常用）
- 组件级：重组件单独分割（懒加载大组件）
- 库级：大依赖独立 chunk（缓存友好）
- 手动：manualChunks 自定义分割
→ 分割维度 = 路由 + 重组件 + 大依赖

- 首包：入口 + 公共（不含懒路由）
- 切路由：懒 chunk 加载（小、快）
- 骨架屏：fallback 显示（防白屏）
- 预取：hover 预加载（体验接近同步）
→ 体验 = 首包小 + 切换有反馈 + 预取

数据层（api 客户端）：
  - 封装请求（统一 baseURL/拦截器/错误）
  - 类型化（请求/响应类型）

服务端状态层（请求库）：
  - useQuery：声明式取数（缓存/失效/重试）
  - useMutation：写操作（乐观更新/失效）

组件层：只调用 hook，不直接 fetch
→ 分层 = api 客户端 + 请求库 hook + 组件消费

import { useQuery } from '@tanstack/react-query'

function useUsers() {
  return useQuery({
    queryKey: ['users'],        // 缓存键
    queryFn: fetchUsers,        // 取数函数
    staleTime: 60_000           // 缓存有效期
  })
}
// 组件里：
const { data, isLoading, isError } = useUsers()

- staleTime：数据「过期」时间（多久重新取）
- invalidateQueries：写操作后失效（重新拉）
- 乐观更新：先更新 UI，再确认/回滚
- 缓存回收：GC（不用即清）
→ 缓存 = staleTime + 失效触发 + 乐观更新

- 快速切换参数：多个请求竞态（旧响应覆盖新）
- 请求库处理：请求 key 变化自动取消旧请求
- 去重：相同 key 并发请求只发一次（复用）
- 防抖/合并：高频输入节流请求
→ 竞态 = 请求库按 key 取消 + 去重

- 错误状态：isError + 错误信息展示
- 重试：retry 次数 + 退避
- 错误分类：网络/业务/鉴权（分策略）
- 兜底：fallback 数据/缓存优先
→ 错误 = 分类 + 重试 + 兜底展示

- 直接在组件 fetch（无缓存，重复拉）
- 忽略竞态（旧数据覆盖新数据）
- 忘记失效（写后 UI 不刷新）
- 无加载/错误状态（体验差）
→ 陷阱 = 绕开请求库自己管理异步

CSR（客户端渲染）：
  - 首屏：JS 加载 → 渲染（慢首次，快交互）
  - SEO：初始 HTML 空（爬虫看内容难）
  - 优点：简单、部署静态
  - 缺点：首屏慢、SEO 弱

SSR（服务端渲染）：
  - 首屏：服务端出 HTML（快首屏、SEO 好）
  - 交互：hydrate 激活（JS 接手）
  - 优点：首屏快、SEO 好
  - 缺点：服务端资源、复杂度
→ 选择 = 首屏需求 × SEO 需求 × 资源

- 内容型站点（博客/官网）：SEO 关键 → SSR
- 应用型（后台/管理）：SEO 不重要 → CSR
- 混合：营销页 SSR + 应用页 CSR（同应用）
- 性能敏感：SSR 首屏 > CSR（低端设备更明显）
→ 判断 = 内容属性 + SEO + 设备环境

- 关键路由 SSR（内容/SEO）
- 应用路由 CSR（交互/动态）
- 按路由选择渲染模式（同框架支持）
- Vite SSR 框架：支持路由级混合
→ 混合 = 关键内容 SSR、动态应用 CSR

- 服务端取数：SSR 时预取（请求库在服务端跑）
- 数据序列化：传给客户端（避免二次取）
- 脱水/注水（dehydrate/hydrate）：状态传递
- 避免：SSR 与 CSR 数据不一致（闪变）
→ SSR 数据 = 服务端预取 + 序列化传递

- SSR 需要 Node 服务（非纯静态）
- Vite SSR：构建 server bundle + client bundle
- 服务端框架：Express/Koa 挂载
- 边缘渲染（Edge）：SSR 到边缘（更快）
→ 部署 = 静态 CSR / Node SSR / 边缘 SSR

- 全栈框架：Next.js（但非 Vite 内核）
- Vite SSR 库：vite-plugin-ssr / SvelteKit（多框架）
- React 专属：@vitejs/plugin-react 有 SSR 支持
- 轻量：自写 server + Vite SSR（可控但复杂）
→ 选型 = 全栈需求 vs 轻量可控

// 组合：用 children / 插槽组合
function Card({ title, children, actions }) {
  return (
    <div className="card">
      <h2>{title}</h2>
      {children}
      {actions}
    </div>
  )
}
// 扩展：通过组合而非改基类
function ProductCard() {
  return <Card title={p.title} actions={<BuyBtn />} />
}
→ 组合 = children/插槽扩展，不改基类

// 受控组件：状态由父级控制（单一数据源）
function Input({ value, onChange }) {
  return <input value={value} onChange={onChange} />
}

// 非受控：组件内部状态（defaultValue）
function Input() {
  const [value, setValue] = useState('')
  // 父级无法控制 → 用于「内部简单表单」
}
→ 受控 = 父控数据源，非受控 = 内部自管

- 重复逻辑 → 抽成 Hook（数据获取/表单/计时器）
- Hook 命名 useXxx（约定）
- Hook 单一职责（一个 Hook 一件事）
- 逻辑 Hook 与展示组件分离
→ Hook = 复用逻辑的「最小单元」

// 避免无谓重渲染
const MemoizedList = memo(List)   // 缓存组件
const handleClick = useCallback(fn, [deps])  // 稳定回调
const value = useMemo(() => compute(a, b), [a, b])  // 缓存计算
// 配合 Profiler 观察渲染

- 容器组件：取数/状态（逻辑）
- 展示组件：纯渲染（props）
- 布局组件：结构（无逻辑）
- 页面组件：组合容器+布局
→ 拆分 = 按「职责」而非「大小」

- 单一职责：一个组件一件事
- props 最小化：少而明确（接口稳定）
- 无隐藏副作用：渲染要纯（副作用进 effect）
- 命名清晰：能看出「是什么」
→ 原则 = 职责单一 + 接口小 + 纯渲染 + 命名清

1. 加载性能：首屏多久能看（包体/请求/渲染）
2. 渲染性能：交互是否流畅（重渲染/卡顿）
3. 运行性能：业务计算/内存（大计算/泄漏）
→ 性能 = 加载 + 渲染 + 运行三维

- 代码分割：路由懒加载（首包小）
- 摇树：删除未用依赖（见 Tree-shaking 篇）
- 资源优化：图片压缩/字体子集/CDN
- 预加载：关键资源 preload、动态 chunk 预取
- 构建配置：esbuild 压缩、target 合理
→ 加载 = 分割 + 摇树 + 资源 + 预取

- 重渲染控制：memo/useCallback/useMemo
- 列表性能：key 稳定、虚拟列表（长列表）
- 状态局部化：少全局状态（减少订阅者）
- 慢组件隔离：独立 memo（防拖累父级）
- Profiler 定位：找出高频重渲染组件
→ 渲染 = 控制重渲染 + 虚拟列表 + 定位

- 大计算：useMemo 缓存 + 防抖节流
- 内存：清理监听/定时器（effect cleanup）
- 数据结构：避免大对象拷贝
- 长任务：拆片（Web Worker，见 worker 篇）
→ 运行 = 缓存 + 清理 + 拆片

- 浏览器性能面板：加载瀑布/重渲染
- React DevTools Profiler：渲染耗时
- Web Vitals：LCP/INP/CLS（核心指标）
- 打包分析：visualizer 包体占比
→ 测量 = 浏览器面板 + Profiler + Vitals + visualizer

1. 测量：建立基线（Vitals/包体）
2. 定位：瀑布/Profiler 找瓶颈
3. 优化：针对瓶颈（分割/重渲染/资源）
4. 复测：对比基线（是否改善）
5. 门禁：预算 CI 检查（防回退）
→ 流程 = 测量 → 定位 → 优化 → 复测 → 门禁

// vite.config.ts 按模式/环境配置
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig(({ mode }) => ({
  plugins: [react()],
  define: {
    // 环境变量注入（import.meta.env）
    __APP_VERSION__: JSON.stringify(process.env.npm_package_version)
  },
  build: {
    target: 'es2020',
    sourcemap: mode === 'development'
  }
}))
// mode: development/production/自定义

- .env / .env.development / .env.production
- VITE_ 前缀变量暴露给客户端（import.meta.env.VITE_*）
- 非 VITE_ 前缀：仅服务端构建可用
- 类型声明：env.d.ts 声明类型
→ env = VITE_ 前缀暴露 + 按环境文件 + 类型声明

- CI：构建 + 测试 + 包体预算
- 产物：dist/ 静态部署（Nginx/CDN）
- 资源哈希：缓存友好（内容哈希）
- 回滚：产物版本管理
- 监控：部署后错误率/性能
→ 部署 = CI 构建 + 静态产物 + 监控

- HMR：热更新（改代码即见）
- alias：@/ 指向 src（路径简洁）
- 代码检查：ESLint + 格式化
- 类型检查：tsc（CI 里跑）
- 测试：Vitest（见 Vitest 篇）
→ 体验 = HMR + alias + lint + 类型 + 测试

- 模板：create-vite react-ts（起步）
- 目录：src/features + shared（第 2 节）
- 配置：tsconfig/vite.config/eslint（集中）
- 脚本：dev/build/preview/test/lint
- 文档：README + 架构决策（ADR）
→ 工程化 = 模板 + 结构 + 配置 + 脚本 + 文档