React 生态全景与项目架构

一句话：React 本身只负责“把状态渲染成 UI”，真实项目还需要路由、请求、状态、表单、组件库、构建、测试、SSR 等生态工具一起组成完整架构。

第 10 篇 / 共 12 篇。

本篇学完你会：知道 React 生态每一类工具解决什么问题、用户管理后台该怎么选型、React 项目架构应该怎么分层。

1. 为什么要单独学 React 生态

React 官方核心很克制。它主要解决：

组件
状态
渲染
交互

但真实用户管理后台还需要：

页面路由
接口请求
登录鉴权
权限按钮
表单校验
表格组件
弹窗组件
全局状态
构建部署
自动测试

这些不是 React 核心全部包办，而是由生态工具组合完成。

React 生态全景与项目架构图

2. React 生态总地图

可以把 React 项目想成一栋楼：

楼层	解决什么	常见工具
UI 核心	组件、状态、渲染	React、React DOM
路由	URL 到页面	React Router
服务端框架	SSR、SSG、全栈路由	Next.js、Remix
全局状态	当前用户、权限、主题	Context、Zustand、Redux Toolkit
服务端数据	请求、缓存、刷新、重试	TanStack Query、SWR
表单校验	输入、校验、提交	React Hook Form、Zod
UI 组件库	表格、弹窗、表单控件	Ant Design、MUI、shadcn/ui
样式	视觉和布局	CSS Modules、Tailwind、styled-components
构建	开发服务、打包	Vite、Next、Rsbuild
测试	保证功能不坏	Vitest、Testing Library、Playwright

React 的生态特点是：选择多、组合自由，但也更需要你会做架构判断。

3. React 核心层

React 核心层包含：

React
React DOM
JSX
Hooks
组件模型

在用户管理后台里，React 核心负责：

function UserManagementPage() {
  const [keyword, setKeyword] = useState('');

  return (
    <section>
      <UserFilter keyword={keyword} onKeywordChange={setKeyword} />
      <UserTable />
    </section>
  );
}

它不直接规定你必须用什么路由、什么请求库、什么 UI 库。这是自由，也是成本。

4. 路由层：React Router

React Router 负责：

路径对应哪个页面
页面跳转
读取 URL 参数
嵌套路由
路由权限

用户管理页面：

{
  path: '/admin/users',
  element: <UserManagementPage />
}

用户详情页：

{
  path: '/admin/users/:id',
  element: <UserDetailPage />
}

读取参数：

const { id } = useParams();

后台项目里，路由通常和权限一起设计：

<RequirePermission code="user:read">
  <UserManagementPage />
</RequirePermission>

5. 服务端框架层：Next.js / Remix

React 本身偏 UI，Next.js / Remix 是更完整的 React 应用框架。它们不是所有 React 项目的必选项，主要在你需要 SSR、SSG、文件路由、服务端能力或全栈能力时才值得优先考虑。

工具	适合
Next.js	官网、内容站、SSR、SSG、全栈 React、复杂产品
Remix	强调 Web 标准、表单、嵌套路由、服务端数据
Vite + React Router	纯前端后台、内部系统、管理端

用户管理后台如果是内部系统，常见选择：

Vite + React Router + API 后端

如果是需要 SEO、首屏、服务端渲染的产品：

Next.js

6. 状态管理层：Context / Zustand / Redux Toolkit

不是所有状态都要全局。

状态	推荐位置
搜索框输入	页面本地 state
编辑表单草稿	表单组件本地 state
当前登录用户	全局状态
权限列表	全局状态
主题、语言	全局状态
服务端列表数据	TanStack Query 或页面 Hook

Context

适合少量、不频繁变化的全局数据：

const AuthContext = createContext<AuthState | null>(null);

Zustand

适合中小项目业务状态：

export const useAuthStore = create<AuthState>((set) => ({
  user: null,
  permissions: [],
  setUser: (user) => set({ user, permissions: user.permissions })
}));

Redux Toolkit

适合大型团队、强规范、复杂调试场景。

大白话：Redux 像正式档案室，Zustand 像轻量文件柜，Context 像公告栏。

7. 服务端数据层：TanStack Query / SWR

用户列表数据来自服务端：

GET /api/users

这类数据和本地 UI 状态不同。它需要：

缓存
重新请求
失败重试
loading
error
分页
失效刷新

TanStack Query 示例：

const usersQuery = useQuery({
  queryKey: ['users', query],
  queryFn: () => fetchUsers(query)
});

保存用户后刷新：

const queryClient = useQueryClient();

await saveUser(form);
queryClient.invalidateQueries({ queryKey: ['users'] });

这比手写很多 useEffect + useState 更稳。

8. 表单层：React Hook Form / Zod

编辑用户表单包含：

姓名必填
邮箱格式
角色选择
状态选择
提交 loading
错误提示

React Hook Form 负责表单状态，Zod 负责校验规则。

const schema = z.object({
  name: z.string().min(1, '请输入姓名'),
  email: z.string().email('邮箱格式不正确')
});

大白话：

React Hook Form 管“输入过程”
Zod 管“规则是否合格”

9. UI 组件层：Ant Design / MUI / shadcn/ui

用户管理后台很需要 UI 组件：

Table
Modal
Form
Select
Button
Message
Pagination

常见选择：

组件库	特点
Ant Design	后台管理系统成熟，表格表单强
MUI	Material Design 风格，海外生态常见
shadcn/ui	更像组件源码模板，适合定制设计系统
Radix UI	无样式基础组件，适合自建组件库

如果你做企业后台，Ant Design 往往很省时间。

如果你做品牌产品，shadcn/ui 或 Radix + Tailwind 更适合定制。

10. 样式层：CSS Modules / Tailwind / CSS-in-JS

React 样式选择很多：

方式	适合
CSS Modules	普通项目，局部样式清晰
Tailwind	快速搭界面，统一设计 token
styled-components / emotion	JS 驱动样式，动态样式多
vanilla-extract	类型安全 CSS，工程化强

用户管理后台推荐：

组件库样式 + 少量 CSS Modules / Tailwind

不要一开始就混太多样式方案。

11. 构建和工程化层：Vite / Next / Turborepo

纯前端后台：

Vite + React + TypeScript

多项目仓库：

pnpm workspace + Turborepo

需要 SSR/SSG 或全栈能力的 React 产品：

Next.js

工程化还包括：

ESLint / Biome
Prettier
TypeScript
环境变量
构建检查
CI/CD

12. 测试层：Vitest / Testing Library / Playwright

不同测试解决不同问题：

测试	看什么
Vitest	函数、Hook、工具方法
Testing Library	组件按用户视角能不能用
Playwright	浏览器里完整流程是否正常

用户管理后台可以测：

列表能显示用户
搜索能过滤
新增弹窗能打开
表单错误能提示
保存后列表刷新
无权限不显示按钮

13. 移动端和跨端：React Native / Expo

React 生态还有一个重要分支：React Native。

工具	作用
React Native	用 React 思路写原生 App
Expo	更完整的 React Native 开发平台

如果你未来想做 App，React 生态的跨端能力是优势。

但注意：React Web 和 React Native 不是完全一样，DOM、样式、组件都不同，只是组件心智和状态模型相通。

14. 用户管理后台推荐架构

一个稳妥 React 后台架构：

src/
  app/
    router.tsx
    providers.tsx
  shared/
    request/
    ui/
    utils/
  features/
    users/
      api.ts
      types.ts
      hooks/
        use-users.ts
      components/
        user-filter.tsx
        user-form.tsx
        user-table.tsx
      pages/
        user-management-page.tsx
  stores/
    auth-store.ts

推荐组合：

层	推荐
构建	Vite
路由	React Router
请求缓存	TanStack Query
全局状态	Zustand
表单	React Hook Form + Zod
UI	Ant Design 或 shadcn/ui
测试	Vitest + Playwright

15. 常见选型错误

错误一：所有东西都放 Redux

搜索框、弹窗开关、表单草稿，不一定要进全局。

错误二：不用请求缓存库，手写一堆 useEffect

简单页面可以手写。项目复杂后，缓存、刷新、重试会越来越麻烦。

错误三：组件库和样式系统混乱

Ant Design、MUI、Tailwind、CSS-in-JS 全都混在一起，会让项目风格和维护成本失控。

错误四：目录按技术堆，不按业务聚合

不推荐：

components/
hooks/
api/
pages/

所有业务混在一起。

更推荐：

features/users/
features/roles/
features/auth/

16. 学习顺序

建议这样学 React 生态：

1. React 核心：组件、state、props、Hooks
2. React Router：页面和 URL
3. 请求层：fetch/axios -> TanStack Query
4. 状态管理：Context -> Zustand -> Redux Toolkit
5. 表单：React Hook Form + Zod
6. UI 组件库：Ant Design 或 shadcn/ui
7. 工程化：Vite、TypeScript、测试、构建
8. 进阶：Next.js、SSR、React Native

最后记住一句话：

React 生态不是背工具名，而是知道每一类工具在项目架构里负责哪一层。

上一篇建议：大白话讲解——React vs Vue 真实开发任务对比.md

下一篇建议：大白话讲解——Vue 生态全景与项目架构.md