对“rea”这个词我第一反应是 React。这几年做前端跟 React 生态打交道的时间占了大部分从最开始用 Class 组件写业务到后来全面拥抱 Hooks再到把服务端渲染、微前端、性能优化这些硬骨头一个个啃下来“rea”这个缩写其实挺能代表 React 技术栈在实际项目里的地位——它不只是一个 UI 库更是一整套解决复杂前端工程问题的思路。这篇文章我不打算讲那种“Hello World”级别的入门教程而是想从一个实际落地的跨端项目出发聊聊 React 技术栈在真实业务里怎么选型、怎么组织代码、怎么排查那些让人掉头发的疑难杂症。如果你正在用 React 做项目或者正打算从零搭建一个中大型前端应用这篇文章应该能给你一些直接能抄作业的经验。1. 项目整体设计与思路拆解1.1 “rea”到底想解决什么问题我接到的这个模拟项目X要求做一个跨平台的管理系统支持桌面端和移动端访问核心功能包括数据看板、工单流转、权限管理和实时消息提醒。技术选型的时候团队内部有过争执有人建议用传统多页面方案有人建议引入低代码平台但最后我们还是敲定了 React。理由其实很实在。React 的组件化模型特别适合这种业务复杂、界面元素复用度高的管理系统。你看光是表格、表单、弹窗、图表这些在管理系统里几乎每个页面都有如果用传统模板引擎每个页面都要复制粘贴一大段 HTML 和对应的 JS 逻辑维护成本直接爆炸。而 React 可以把这些拆成独立组件一次编写处处引用。另一个关键因素是 React 的生态足够成熟。路由有 React Router状态管理有 Redux、ZustandUI 组件库有 Ant Design、Material UI数据请求有 React Query、SWR几乎你能想到的每一种业务场景社区里都已经有经过大量项目验证的方案。这意味着我们不需要从零造轮子而是把成熟方案组合起来风险可控开发效率也高。至于跨端需求React 本身是平台无关的——一套代码通过不同的渲染器可以运行在 Web、移动端原生环境和桌面端。虽然这个项目最终只做了 Web 端但选型时考虑到未来可能要做移动端 AppReact 技术栈的延续性是最平滑的。1.2 整体技术架构的选型逻辑核心架构分成五层UI 层React 18 TypeScript组件库选 Ant Design状态层服务端状态用 React Query客户端全局状态用 Zustand路由层React Router v6按业务模块做代码分割样式层CSS Modules 配合设计系统变量工程层Vite 构建 ESLint Prettier Jest 测试这里面有几个选型是反复权衡过的。先说 TypeScript。很多人觉得写 TS 麻烦多写一堆类型定义拖慢开发速度。但项目规模大了之后TS 的价值会越来越明显。管理系统通常涉及大量的数据模型用户、订单、工单、权限这些实体之间的关系复杂如果没有类型约束改动一个接口字段可能满项目都是报错而且很多错误是运行时才能发现的。用 TS 之后很多低级错误在编译期就被拦截了重构的胆子也大了很多。再说 Zustand 和 Redux 的选择。Redux 虽然经典但样板代码实在太多写一个 action 要定义 action type、action creator、reducer 分支流程繁琐。Zustand 足够轻量API 设计贴近 Hooks 风格在 React 18 的并发特性下表现也稳定。特别是它不需要 Context Provider 包裹整个应用避免了不必要的重渲染这对管理系统的性能是实打实的帮助。React Query 解决的是服务端状态的问题。管理系统里大量操作是数据的增删改查手动管理 loading、error、缓存这些逻辑很容易出 bug而且代码极其无聊。React Query 把这些逻辑抽象掉自带缓存、重试、失效刷新、乐观更新让开发者可以专注于业务本身。1.3 这套方案的优势和避开的坑这套架构跑下来最大的体会是边界清晰。每一层只负责自己的事情UI 组件不直接发请求状态管理不关心组件渲染路由只负责分发。团队协作的时候大家不用互相猜代码意图新人上手也快。另外一个隐性优势是调试体验。Zustand 的 devtools 插件、React Query 的开发者工具、React DevTools 的 Profiler三件套基本上覆盖了从数据流到渲染性能的所有追踪需求。对比之前用过的某些一体化框架出问题时经常只能靠 console.log 盲猜这次的体验简直是天壤之别。当然也有过犹豫。比如要不要用 Next.js 做服务端渲染。考虑再三这个管理系统是内部工具型应用对 SEO 没有要求首屏加载时间虽然重要但不至于到非要 SSR 不可的程度而且 SSR 会带来服务端运维成本和更复杂的部署流程权衡下来感觉不划算最终选择了纯客户端渲染加路由级代码分割。2. 核心细节解析与实操要点2.1 状态管理的分层策略状态管理的第一个原则不要把所有的状态都放到全局 Store 里。我把状态分成三类服务端状态数据来自后端 API需要缓存和失效管理——交给 React Query全局客户端状态登录用户信息、主题配置、权限标识——交给 Zustand局部组件状态弹窗开关、表单值、下拉框选中项——老老实实放 useState 和 useReducer这个分层策略最大的作用是避免 Zustand Store 变成一个装垃圾的大仓库。很多人写代码很容易图省事什么东西都想往全局 Store 里放结果一个 Store 几百个字段任何地方改了一个字段所有监听这个 Store 的组件都要检查是不是需要重新渲染——性能问题就是这么出现的。以这个管理系统为例Zustand 里只放了这么几个东西interface GlobalState { userInfo: UserInfo | null permissions: string[] themeMode: light | dark sidebarCollapsed: boolean setUserInfo: (user: UserInfo | null) void setPermissions: (perms: string[]) void toggleTheme: () void toggleSidebar: () void }你看这里面没有任何业务列表数据全是跟整个应用生命周期相关的全局信息。业务数据全部走 React Query 的路由级缓存。这样 Zustand 的状态变化频率极低几乎不会引发多余的组件渲染。2.2 组件划分的粒度把控组件划分粒度是个经验活太粗了复用性差太细了过度设计。我的原则是“按业务能力划分不以 DOM 大小论英雄”。比如一个“工单详情”页面我不会按照“头部区域”“中部区域”“底部区域”这种纯展示结构来拆组件而是按照“工单基本信息”“流转记录时间线”“关联附件列表”“操作按钮组”这种业务模块来拆分。每个业务模块自包含数据获取逻辑和 UI 展示这样模块之间可以独立修改、独立测试、独立复用。一个小技巧在组件内部通过自定义 Hook 封装数据请求逻辑。比如function useWorkOrderDetail(orderId: string) { return useQuery({ queryKey: [workOrder, orderId], queryFn: () fetchWorkOrderDetail(orderId), staleTime: 5 * 60 * 1000, }) }组件文件里只处理渲染逻辑数据逻辑全在 Hook 里。换接口、加缓存策略、做乐观更新都只改 Hook完全不碰组件代码。这是我特别推荐的一种组织方式代码会变得非常干净。2.3 权限控制的实现思路管理系统的权限控制是个绕不开的坎。我们把权限分成了两个维度路由级权限和按钮级权限。路由级权限在 React Router v6 里通过一个封装好的AuthGuard组件实现。用户登录后后端返回一个权限码数组我们根据权限码动态生成路由表没有权限的路由直接不注册也就无法访问const routeMap { dashboard: { element: Dashboard /, permission: dashboard.view }, workOrder: { element: WorkOrder /, permission: workorder.view }, userManagement: { element: UserManagement /, permission: user.manage }, } const accessibleRoutes Object.entries(routeMap) .filter(([, config]) hasPermission(config.permission)) .map(([path, config]) ({ path, element: config.element }))按钮级权限通过一个自定义指令风格的组件控制没有权限时不渲染按钮function CanAccess({ permission, children }: { permission: string, children: React.ReactNode }) { const { permissions } useGlobalStore() return hasPermission(permissions, permission) ? {children}/ : null }这里有个容易踩坑的点前端权限控制只是用户体验层面的隐藏真正的安全校验必须在后端做。前端控制做到“友好”后端校验做到“可靠”两条腿走路才安全。2.4 样式方案与主题切换样式方案简要说明一下用了 CSS Modules。它在编译阶段给类名加上局部哈希避免全局污染又不会像 CSS-in-JS 那样带来运行时性能开销。主题切换则用 CSS 变量配合 Ant Design 的 ConfigProvider 实现。在:root下定义语义化的设计变量:root { --color-primary: #1677ff; --color-bg: #ffffff; --color-text: #1f1f1f; } [data-themedark] { --color-primary: #4d9fff; --color-bg: #141414; --color-text: #e0e0e0; }Zustand 里的themeMode变化后自动给document.documentElement打上>npm create vitelatest rea-project -- --template react-ts cd rea-project npm install紧接着装一堆必要的依赖npm install react-router-dom zustand tanstack/react-query antd axios dayjs npm install -D eslint prettier typescript-eslint/parser typescript-eslint/eslint-pluginVite 在开发体验上的确比老一代的 Webpack 舒服太多依赖预构建、按需编译、热更新秒级响应起步几乎没有等待感。构建速度对于中大型项目来说后期也能节省不少工时。后端接口的统一封装我单独写了一个模块基于 axios 实例统一处理 baseURL、token 注入、错误码拦截const http axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL, timeout: 10000, }) http.interceptors.request.use((config) { const token useGlobalStore.getState().userInfo?.token if (token) { config.headers.Authorization Bearer ${token} } return config }) http.interceptors.response.use( (response) { if (response.data.code ! 0) { message.error(response.data.message) return Promise.reject(new Error(response.data.message)) } return response.data.data }, (error) { if (error.response?.status 401) { // 清空用户信息跳转登录页 useGlobalStore.getState().setUserInfo(null) window.location.href /login } return Promise.reject(error) } )3.2 搭建可插拔的路由框架路由骨架直接决定项目的拓展性。我把路由拆成了静态路由和动态路由两部分。静态路由是登录页、404页这类所有用户都能访问的页面动态路由是根据登录用户权限生成的路由数组。React Router v6 里的useRoutes这个 Hook 让我摆脱了以前SwitchRoute的繁琐写法function AppRoutes() { const routes useMemo(() buildAccessibleRoutes(), [permissions]) return useRoutes([ { path: /login, element: LoginPage / }, { path: /, element: MainLayout /, children: routes }, { path: *, element: NotFoundPage / }, ]) }每个业务模块的路由都做懒加载。懒加载是这里最关键的优化手段不然首屏 bundle 会越来越大——做过前端都应该清楚bundle 大小和首屏加载速度直接挂钩const WorkOrderPage lazy(() import(/pages/WorkOrder))路由层面还做了一个“路由切换进度条”的效果模仿某个知名后台框架的体验在useEffect里监听路由变化如果组件懒加载超过 200ms 就显示一个顶部进度条。这个小东西很提升使用体感实现也不复杂花了不到半天。3.3 数据请求与管理的最佳实践React Query 里一个重要的设计是保持queryKey的统一规划。我习惯把一个领域的查询 key 集中定义在一个常量表里export const queryKeys { workOrder: { detail: (id: string) [workOrder, detail, id], list: (params: WorkOrderQueryParams) [workOrder, list, params], }, user: { list: (params: UserQueryParams) [user, list, params], }, }这样使用时语义清晰而且任何地方需要让某个缓存失效时可以通过queryClient.invalidateQueries({ queryKey: [workOrder] })精确地控制失效范围不会误伤其他数据。做表单提交时React Query 的useMutation配合乐观更新是一个非常实用的技巧。以“更新工单状态”为例先展示给用户 UI 已经更新再发后端请求const mutation useMutation({ mutationFn: updateWorkOrderStatus, onMutate: async (newStatus) { await queryClient.cancelQueries({ queryKey: [workOrder, orderId] }) const previousData queryClient.getQueryData([workOrder, orderId]) queryClient.setQueryData([workOrder, orderId], (old) ({ ...old, status: newStatus, })) return { previousData } }, onError: (_err, _vars, context) { queryClient.setQueryData([workOrder, orderId], context?.previousData) }, onSettled: () { queryClient.invalidateQueries({ queryKey: [workOrder] }) }, })这套模式让整个交互体验非常丝滑后端返回失败时自动回滚。3.4 关键页面的实现复盘数据看板页面是这次项目的重头戏。页面里有四个统计卡片、一个趋势折线图、一个分类饼图、一个实时动态列表。我的做法是统计卡片的数据用useQuery并行抓取但如果一个接口挂了不能影响其他模块。并行请求用Promise.allSettled包了一层这样即使某个接口异常页面其他区域依然能正常展示。这也是一个从实际项目中总结出来的思路不要把鸡蛋放在一个篮子里单一接口的错误不应当导致整个页面白屏。工单列表页则是典型的查、筛、分页场景。搜索条件我用useState保存通过useQuery的queryKey关联筛选条件每次筛选变化都会自动触发请求配合keepPreviousData: true切换分页时上一页数据会保留展示避免加载闪烁。useQuery({ queryKey: queryKeys.workOrder.list(params), queryFn: () fetchWorkOrderList(params), keepPreviousData: true, })这都是 React Query 的现成能力但用好了以后用户体验确实上了一个档次。实时消息提醒模块开始时用了 WebSocket后来发现后端同学提供的推送频率不高数据量也不大换成轮询反而更稳定每 15 秒拉一次未读消息加上refetchInterval配置useQuery({ queryKey: [unreadMessages], queryFn: fetchUnreadMessages, refetchInterval: 15000, })3.5 构建配置与部署细节构建阶段做了几件关键事情。第一是拆包。Vite 默认会把所有依赖和业务代码打到一个 chunk 里虽然现代浏览器支持 HTTP/2但首屏解析一个大文件的时间仍然不理想。我在vite.config.ts里用manualChunks手动拆分build: { rollupOptions: { output: { manualChunks: { react-vendor: [react, react-dom, react-router-dom], antd-vendor: [antd, ant-design/icons], chart-vendor: [echarts], }, }, }, }这样公共依赖单独缓存浏览器下次加载时命中的概率更高整体加载体验更好。第二是移除调试代码。生产构建时通过环境变量判断把console.log和debugger语句剔除保证生产环境日志干净。第三是静态资源走 CDN 配置。项目部署后图片和字体等静态资源加上了内容哈希指纹配合 CDN 缓存回源请求数量大幅下降。4. 常见问题与排查技巧实录4.1 组件无限重渲染的噩梦开发中遇到过最头疼的问题之一是某页面一打开就卡死CPU 直接飙满。排查后发现问题出在useEffect的依赖数组里放了一个未记忆化的对象。问题伪代码如下const config { pageSize: 10, sortBy: createTime } useEffect(() { fetchData(config) }, [config])由于config是每次渲染都新建的对象引用地址每次都不同useEffect的依赖比较永远不相等导致重复请求 - 更新数据 - 重新渲染 - 重新创建 config - 重复请求……直接死循环。从这次的问题我总结出一个教训所有用于useEffect依赖的引用类型值都要用useMemo或useCallback稳定引用或者直接把基本类型的参数一个一个列出来。不能偷懒传一个对象。4.2 React Query 缓存未失效导致的数据陈旧使用 React Query 之后“数据不刷新”是容易被忽视的问题。有一次测试反馈说修改了工单备注后详情页还是显示旧内容排查发现我忘记在修改备注的mutation里调用invalidateQueries。这个坑说白了就是React Query 默认缓存不会自动知道你的后端数据变了你得主动告诉它“这个数据过时了”。添加一行失效刷新之后问题就解决了。经验是在每次mutation成功的回调里把关联查询全部失效。如果你发现自己频繁忘了可以在mutation的onSettled里统一处理不要只依赖单个调用的onSuccess。4.3 样式主题切换后的残留问题主题切换在刚开始的实现中踩过一个坑。Ant Design 5 的ConfigProvider默认通过cssVar: true启用 CSS 变量模式但自定义的组件如果用了自己的定色值切到深色模式时就会出现“一半深色一半浅色”的割裂感。排查后发现是某些组件的行内样式直接写死了颜色不经过 CSS 变量。后来我专门做了一个代码扫描把所有写死的十六进制颜色都替换成了 CSS 变量引用并规定后续新增代码必须使用设计系统的变量代码审查环节会专门检查这一点。4.4 路由懒加载导致的首屏白屏路由懒加载虽然能缩减 bundle 体积但也会引入一个体验问题网络较慢时切换路由会有一段白屏时间。后来通过加了一个“全局加载状态”组件解决在Suspense的fallback里挂一个和导航栏一体的顶部进度条。这样用户明确感知到“正在加载”而不是“卡死了”。Route path/workOrder element{ Suspense fallback{PageLoading /} WorkOrderPage / /Suspense } /4.5 排查技巧速查表症状排查方向常用工具页面无响应/卡死React DevTools 的 Profiler 看渲染耗时重点检查 useEffect 循环React DevTools数据更新不及时查 React Query 缓存 key 是否匹配invalidateQueries 是否调用React Query DevTools组件渲染了但样式错乱CSS Module 哈希冲突或主题变量未生效检查类名和变量引用浏览器 Elements 面板打包后体积过大查依赖是否重复打包有无遗漏的按需加载配置可用 rollup-plugin-visualizer 可视化分析Vite 构建报告接口请求频繁无意义检查是否有多个组件同时请求同一数据考虑提升到父组件或改用共享缓存浏览器 Network 面板4.6 调试技巧React Query DevTools 是排查缓存问题的最强工具。安装接入只需要三行import { ReactQueryDevtools } from tanstack/react-query-devtools // 开发环境下挂载 ReactQueryDevtools initialIsOpen{false} /有了它你能直观看到每个查询的缓存状态、最后更新时间、被哪些组件订阅。这在追查“为什么页面数据不新”这种问题时效率极高比反复查接口日志舒服多了。4.7 性能优化实录项目后期做了一次性能体检用 Lighthouse 测出来的首屏性能分数从 68 提到了 90 以上主要做了三件事。第一件事减少首屏不必要的 JS。利用React.lazy把看板页面的图表库单独拆出去因为图表库体积不小在首屏是不需要的等用户滚动到图表区域再加载即可。这个简单操作让首屏 JS 总量减少了约 30%。第二件事图片懒加载。管理系统的列表页有很多上传的截图附件直接用img loadinglazy /原生属性就解决了没有任何额外成本。第三件事优化大列表渲染。工单列表一页 50 条数据每条数据里有富文本内容渲染时明显卡顿。后来对列表项做了React.memo并为富文本内容做了缓存滚动体验立刻好了很多。5. 从进阶视角再看“rea”这个项目5.1 团队协作规范的沉淀做完这个项目我们沉淀了一套适合中小型前端团队的协作规范核心是三份文档组件命名与目录结构规范、状态管理使用规范、代码审查检查清单。组件命名上我特别重视路径即身份的命名方式比如src/components/WorkOrder/StatusTag.tsx只看路径就知道它是工单域下的状态标签组件。不用src/components/Common/StatusTag.tsx因为 Common 是垃圾场什么都能往里丢最终什么都找不到。状态管理使用规范里明确列了三条红线禁止在全局 Store 里存放接口返回的业务列表数据禁止在组件里直接用store.dispatch以外的副作用操作全局状态全局 Store 更新时注意不可变更新方式没有做浅层比较的 Store 更新会引发全部订阅者重渲染代码审查清单则是保护项目质量的最低防线有没有写死颜色值、有没有未使用的 imports、有没有绕过权限校验的直连接口调用、有没有 useEffect 依赖数组里引用了外部对象。5.2 未来的扩展思路这个项目后续如果要演进方向上我考虑了三条路。第一条是引入微前端架构。如果未来多个团队要并行开发不同业务线微前端能干这事把大应用拆成若干个独立部署、独立升级的子应用。目前项目还不到需要拆分的地步真到了那份上我倾向用 qiankun 之类的成熟框架自研微前端加载器看起来很美但成本真的很吓人。第二条是迁移部分页面到服务端渲染。如果业务开始对 SEO 或首屏秒开有要求可以挑选核心页面用 Next.js 重构而不是全部推翻重来。渐进式迁移才是低风险路径。第三条是接入单元测试和端到端测试的完整流水线。目前测试覆盖率只有核心工具函数和几个关键组件后续应该把工单流转这条主干链路用 Playwright 跑一遍端到端避免每次发版都要人肉回归。5.3 踩过坑后的几点体感整个项目做到最后回头看不只是技术层面的收获。有些经验是写代码写不出来非得在项目里踩了坑才能体会到的。一是对“约定大于配置”的理解。架构定的规范和约定越明确团队成员越多沟通成本节省得越明显。特别是封装好了数据请求、权限判断、路由生成这些基建后写业务页面的同学几乎只需要关心 UI 交互本身。二是对“过早优化”的克制。一开始有几个同事提议马上引入测试覆盖率门槛和 CI 流水线但项目前期需求变化极快早期设计大量调整时如果把时间大量消耗在维护测试上反而拖慢迭代。后来在核心链路稳定之后再把测试补上成本低得多价值也更高。三是对技术选型的敬畏。回头看 Zustand 可能不是每个项目的首选但在我们的场景下确实够用、好用。技术选型没有什么一招鲜核心思路始终是结合团队实际情况权衡投入产出比选择学习成本适中、生态成熟、退路清晰的方案。很多时候不用最时髦的框架反而能走得最远。React 这套生态之丰富给了开发者很多自由但也正因为自由空间大更容易走偏。一个项目的成功往往不在于用了什么新技术而在于把已经足够好的技术用出了体系、用出了规范。这大概就是我在这个项目里最深的感受吧。 
长河君 · 2026/10/21 23:24:56 · 阅读 1.2k React技术栈在大型跨端项目中的落地实践与工程化解析
对“rea”这个词我第一反应是 React。这几年做前端跟 React 生态打交道的时间占了大部分从最开始用 Class 组件写业务到后来全面拥抱 Hooks再到把服务端渲染、微前端、性能优化这些硬骨头一个个啃下来“rea”这个缩写其实挺能代表 React 技术栈在实际项目里的地位——它不只是一个 UI 库更是一整套解决复杂前端工程问题的思路。这篇文章我不打算讲那种“Hello World”级别的入门教程而是想从一个实际落地的跨端项目出发聊聊 React 技术栈在真实业务里怎么选型、怎么组织代码、怎么排查那些让人掉头发的疑难杂症。如果你正在用 React 做项目或者正打算从零搭建一个中大型前端应用这篇文章应该能给你一些直接能抄作业的经验。1. 项目整体设计与思路拆解1.1 “rea”到底想解决什么问题我接到的这个模拟项目X要求做一个跨平台的管理系统支持桌面端和移动端访问核心功能包括数据看板、工单流转、权限管理和实时消息提醒。技术选型的时候团队内部有过争执有人建议用传统多页面方案有人建议引入低代码平台但最后我们还是敲定了 React。理由其实很实在。React 的组件化模型特别适合这种业务复杂、界面元素复用度高的管理系统。你看光是表格、表单、弹窗、图表这些在管理系统里几乎每个页面都有如果用传统模板引擎每个页面都要复制粘贴一大段 HTML 和对应的 JS 逻辑维护成本直接爆炸。而 React 可以把这些拆成独立组件一次编写处处引用。另一个关键因素是 React 的生态足够成熟。路由有 React Router状态管理有 Redux、ZustandUI 组件库有 Ant Design、Material UI数据请求有 React Query、SWR几乎你能想到的每一种业务场景社区里都已经有经过大量项目验证的方案。这意味着我们不需要从零造轮子而是把成熟方案组合起来风险可控开发效率也高。至于跨端需求React 本身是平台无关的——一套代码通过不同的渲染器可以运行在 Web、移动端原生环境和桌面端。虽然这个项目最终只做了 Web 端但选型时考虑到未来可能要做移动端 AppReact 技术栈的延续性是最平滑的。1.2 整体技术架构的选型逻辑核心架构分成五层UI 层React 18 TypeScript组件库选 Ant Design状态层服务端状态用 React Query客户端全局状态用 Zustand路由层React Router v6按业务模块做代码分割样式层CSS Modules 配合设计系统变量工程层Vite 构建 ESLint Prettier Jest 测试这里面有几个选型是反复权衡过的。先说 TypeScript。很多人觉得写 TS 麻烦多写一堆类型定义拖慢开发速度。但项目规模大了之后TS 的价值会越来越明显。管理系统通常涉及大量的数据模型用户、订单、工单、权限这些实体之间的关系复杂如果没有类型约束改动一个接口字段可能满项目都是报错而且很多错误是运行时才能发现的。用 TS 之后很多低级错误在编译期就被拦截了重构的胆子也大了很多。再说 Zustand 和 Redux 的选择。Redux 虽然经典但样板代码实在太多写一个 action 要定义 action type、action creator、reducer 分支流程繁琐。Zustand 足够轻量API 设计贴近 Hooks 风格在 React 18 的并发特性下表现也稳定。特别是它不需要 Context Provider 包裹整个应用避免了不必要的重渲染这对管理系统的性能是实打实的帮助。React Query 解决的是服务端状态的问题。管理系统里大量操作是数据的增删改查手动管理 loading、error、缓存这些逻辑很容易出 bug而且代码极其无聊。React Query 把这些逻辑抽象掉自带缓存、重试、失效刷新、乐观更新让开发者可以专注于业务本身。1.3 这套方案的优势和避开的坑这套架构跑下来最大的体会是边界清晰。每一层只负责自己的事情UI 组件不直接发请求状态管理不关心组件渲染路由只负责分发。团队协作的时候大家不用互相猜代码意图新人上手也快。另外一个隐性优势是调试体验。Zustand 的 devtools 插件、React Query 的开发者工具、React DevTools 的 Profiler三件套基本上覆盖了从数据流到渲染性能的所有追踪需求。对比之前用过的某些一体化框架出问题时经常只能靠 console.log 盲猜这次的体验简直是天壤之别。当然也有过犹豫。比如要不要用 Next.js 做服务端渲染。考虑再三这个管理系统是内部工具型应用对 SEO 没有要求首屏加载时间虽然重要但不至于到非要 SSR 不可的程度而且 SSR 会带来服务端运维成本和更复杂的部署流程权衡下来感觉不划算最终选择了纯客户端渲染加路由级代码分割。2. 核心细节解析与实操要点2.1 状态管理的分层策略状态管理的第一个原则不要把所有的状态都放到全局 Store 里。我把状态分成三类服务端状态数据来自后端 API需要缓存和失效管理——交给 React Query全局客户端状态登录用户信息、主题配置、权限标识——交给 Zustand局部组件状态弹窗开关、表单值、下拉框选中项——老老实实放 useState 和 useReducer这个分层策略最大的作用是避免 Zustand Store 变成一个装垃圾的大仓库。很多人写代码很容易图省事什么东西都想往全局 Store 里放结果一个 Store 几百个字段任何地方改了一个字段所有监听这个 Store 的组件都要检查是不是需要重新渲染——性能问题就是这么出现的。以这个管理系统为例Zustand 里只放了这么几个东西interface GlobalState { userInfo: UserInfo | null permissions: string[] themeMode: light | dark sidebarCollapsed: boolean setUserInfo: (user: UserInfo | null) void setPermissions: (perms: string[]) void toggleTheme: () void toggleSidebar: () void }你看这里面没有任何业务列表数据全是跟整个应用生命周期相关的全局信息。业务数据全部走 React Query 的路由级缓存。这样 Zustand 的状态变化频率极低几乎不会引发多余的组件渲染。2.2 组件划分的粒度把控组件划分粒度是个经验活太粗了复用性差太细了过度设计。我的原则是“按业务能力划分不以 DOM 大小论英雄”。比如一个“工单详情”页面我不会按照“头部区域”“中部区域”“底部区域”这种纯展示结构来拆组件而是按照“工单基本信息”“流转记录时间线”“关联附件列表”“操作按钮组”这种业务模块来拆分。每个业务模块自包含数据获取逻辑和 UI 展示这样模块之间可以独立修改、独立测试、独立复用。一个小技巧在组件内部通过自定义 Hook 封装数据请求逻辑。比如function useWorkOrderDetail(orderId: string) { return useQuery({ queryKey: [workOrder, orderId], queryFn: () fetchWorkOrderDetail(orderId), staleTime: 5 * 60 * 1000, }) }组件文件里只处理渲染逻辑数据逻辑全在 Hook 里。换接口、加缓存策略、做乐观更新都只改 Hook完全不碰组件代码。这是我特别推荐的一种组织方式代码会变得非常干净。2.3 权限控制的实现思路管理系统的权限控制是个绕不开的坎。我们把权限分成了两个维度路由级权限和按钮级权限。路由级权限在 React Router v6 里通过一个封装好的AuthGuard组件实现。用户登录后后端返回一个权限码数组我们根据权限码动态生成路由表没有权限的路由直接不注册也就无法访问const routeMap { dashboard: { element: Dashboard /, permission: dashboard.view }, workOrder: { element: WorkOrder /, permission: workorder.view }, userManagement: { element: UserManagement /, permission: user.manage }, } const accessibleRoutes Object.entries(routeMap) .filter(([, config]) hasPermission(config.permission)) .map(([path, config]) ({ path, element: config.element }))按钮级权限通过一个自定义指令风格的组件控制没有权限时不渲染按钮function CanAccess({ permission, children }: { permission: string, children: React.ReactNode }) { const { permissions } useGlobalStore() return hasPermission(permissions, permission) ? {children}/ : null }这里有个容易踩坑的点前端权限控制只是用户体验层面的隐藏真正的安全校验必须在后端做。前端控制做到“友好”后端校验做到“可靠”两条腿走路才安全。2.4 样式方案与主题切换样式方案简要说明一下用了 CSS Modules。它在编译阶段给类名加上局部哈希避免全局污染又不会像 CSS-in-JS 那样带来运行时性能开销。主题切换则用 CSS 变量配合 Ant Design 的 ConfigProvider 实现。在:root下定义语义化的设计变量:root { --color-primary: #1677ff; --color-bg: #ffffff; --color-text: #1f1f1f; } [data-themedark] { --color-primary: #4d9fff; --color-bg: #141414; --color-text: #e0e0e0; }Zustand 里的themeMode变化后自动给document.documentElement打上>npm create vitelatest rea-project -- --template react-ts cd rea-project npm install紧接着装一堆必要的依赖npm install react-router-dom zustand tanstack/react-query antd axios dayjs npm install -D eslint prettier typescript-eslint/parser typescript-eslint/eslint-pluginVite 在开发体验上的确比老一代的 Webpack 舒服太多依赖预构建、按需编译、热更新秒级响应起步几乎没有等待感。构建速度对于中大型项目来说后期也能节省不少工时。后端接口的统一封装我单独写了一个模块基于 axios 实例统一处理 baseURL、token 注入、错误码拦截const http axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL, timeout: 10000, }) http.interceptors.request.use((config) { const token useGlobalStore.getState().userInfo?.token if (token) { config.headers.Authorization Bearer ${token} } return config }) http.interceptors.response.use( (response) { if (response.data.code ! 0) { message.error(response.data.message) return Promise.reject(new Error(response.data.message)) } return response.data.data }, (error) { if (error.response?.status 401) { // 清空用户信息跳转登录页 useGlobalStore.getState().setUserInfo(null) window.location.href /login } return Promise.reject(error) } )3.2 搭建可插拔的路由框架路由骨架直接决定项目的拓展性。我把路由拆成了静态路由和动态路由两部分。静态路由是登录页、404页这类所有用户都能访问的页面动态路由是根据登录用户权限生成的路由数组。React Router v6 里的useRoutes这个 Hook 让我摆脱了以前SwitchRoute的繁琐写法function AppRoutes() { const routes useMemo(() buildAccessibleRoutes(), [permissions]) return useRoutes([ { path: /login, element: LoginPage / }, { path: /, element: MainLayout /, children: routes }, { path: *, element: NotFoundPage / }, ]) }每个业务模块的路由都做懒加载。懒加载是这里最关键的优化手段不然首屏 bundle 会越来越大——做过前端都应该清楚bundle 大小和首屏加载速度直接挂钩const WorkOrderPage lazy(() import(/pages/WorkOrder))路由层面还做了一个“路由切换进度条”的效果模仿某个知名后台框架的体验在useEffect里监听路由变化如果组件懒加载超过 200ms 就显示一个顶部进度条。这个小东西很提升使用体感实现也不复杂花了不到半天。3.3 数据请求与管理的最佳实践React Query 里一个重要的设计是保持queryKey的统一规划。我习惯把一个领域的查询 key 集中定义在一个常量表里export const queryKeys { workOrder: { detail: (id: string) [workOrder, detail, id], list: (params: WorkOrderQueryParams) [workOrder, list, params], }, user: { list: (params: UserQueryParams) [user, list, params], }, }这样使用时语义清晰而且任何地方需要让某个缓存失效时可以通过queryClient.invalidateQueries({ queryKey: [workOrder] })精确地控制失效范围不会误伤其他数据。做表单提交时React Query 的useMutation配合乐观更新是一个非常实用的技巧。以“更新工单状态”为例先展示给用户 UI 已经更新再发后端请求const mutation useMutation({ mutationFn: updateWorkOrderStatus, onMutate: async (newStatus) { await queryClient.cancelQueries({ queryKey: [workOrder, orderId] }) const previousData queryClient.getQueryData([workOrder, orderId]) queryClient.setQueryData([workOrder, orderId], (old) ({ ...old, status: newStatus, })) return { previousData } }, onError: (_err, _vars, context) { queryClient.setQueryData([workOrder, orderId], context?.previousData) }, onSettled: () { queryClient.invalidateQueries({ queryKey: [workOrder] }) }, })这套模式让整个交互体验非常丝滑后端返回失败时自动回滚。3.4 关键页面的实现复盘数据看板页面是这次项目的重头戏。页面里有四个统计卡片、一个趋势折线图、一个分类饼图、一个实时动态列表。我的做法是统计卡片的数据用useQuery并行抓取但如果一个接口挂了不能影响其他模块。并行请求用Promise.allSettled包了一层这样即使某个接口异常页面其他区域依然能正常展示。这也是一个从实际项目中总结出来的思路不要把鸡蛋放在一个篮子里单一接口的错误不应当导致整个页面白屏。工单列表页则是典型的查、筛、分页场景。搜索条件我用useState保存通过useQuery的queryKey关联筛选条件每次筛选变化都会自动触发请求配合keepPreviousData: true切换分页时上一页数据会保留展示避免加载闪烁。useQuery({ queryKey: queryKeys.workOrder.list(params), queryFn: () fetchWorkOrderList(params), keepPreviousData: true, })这都是 React Query 的现成能力但用好了以后用户体验确实上了一个档次。实时消息提醒模块开始时用了 WebSocket后来发现后端同学提供的推送频率不高数据量也不大换成轮询反而更稳定每 15 秒拉一次未读消息加上refetchInterval配置useQuery({ queryKey: [unreadMessages], queryFn: fetchUnreadMessages, refetchInterval: 15000, })3.5 构建配置与部署细节构建阶段做了几件关键事情。第一是拆包。Vite 默认会把所有依赖和业务代码打到一个 chunk 里虽然现代浏览器支持 HTTP/2但首屏解析一个大文件的时间仍然不理想。我在vite.config.ts里用manualChunks手动拆分build: { rollupOptions: { output: { manualChunks: { react-vendor: [react, react-dom, react-router-dom], antd-vendor: [antd, ant-design/icons], chart-vendor: [echarts], }, }, }, }这样公共依赖单独缓存浏览器下次加载时命中的概率更高整体加载体验更好。第二是移除调试代码。生产构建时通过环境变量判断把console.log和debugger语句剔除保证生产环境日志干净。第三是静态资源走 CDN 配置。项目部署后图片和字体等静态资源加上了内容哈希指纹配合 CDN 缓存回源请求数量大幅下降。4. 常见问题与排查技巧实录4.1 组件无限重渲染的噩梦开发中遇到过最头疼的问题之一是某页面一打开就卡死CPU 直接飙满。排查后发现问题出在useEffect的依赖数组里放了一个未记忆化的对象。问题伪代码如下const config { pageSize: 10, sortBy: createTime } useEffect(() { fetchData(config) }, [config])由于config是每次渲染都新建的对象引用地址每次都不同useEffect的依赖比较永远不相等导致重复请求 - 更新数据 - 重新渲染 - 重新创建 config - 重复请求……直接死循环。从这次的问题我总结出一个教训所有用于useEffect依赖的引用类型值都要用useMemo或useCallback稳定引用或者直接把基本类型的参数一个一个列出来。不能偷懒传一个对象。4.2 React Query 缓存未失效导致的数据陈旧使用 React Query 之后“数据不刷新”是容易被忽视的问题。有一次测试反馈说修改了工单备注后详情页还是显示旧内容排查发现我忘记在修改备注的mutation里调用invalidateQueries。这个坑说白了就是React Query 默认缓存不会自动知道你的后端数据变了你得主动告诉它“这个数据过时了”。添加一行失效刷新之后问题就解决了。经验是在每次mutation成功的回调里把关联查询全部失效。如果你发现自己频繁忘了可以在mutation的onSettled里统一处理不要只依赖单个调用的onSuccess。4.3 样式主题切换后的残留问题主题切换在刚开始的实现中踩过一个坑。Ant Design 5 的ConfigProvider默认通过cssVar: true启用 CSS 变量模式但自定义的组件如果用了自己的定色值切到深色模式时就会出现“一半深色一半浅色”的割裂感。排查后发现是某些组件的行内样式直接写死了颜色不经过 CSS 变量。后来我专门做了一个代码扫描把所有写死的十六进制颜色都替换成了 CSS 变量引用并规定后续新增代码必须使用设计系统的变量代码审查环节会专门检查这一点。4.4 路由懒加载导致的首屏白屏路由懒加载虽然能缩减 bundle 体积但也会引入一个体验问题网络较慢时切换路由会有一段白屏时间。后来通过加了一个“全局加载状态”组件解决在Suspense的fallback里挂一个和导航栏一体的顶部进度条。这样用户明确感知到“正在加载”而不是“卡死了”。Route path/workOrder element{ Suspense fallback{PageLoading /} WorkOrderPage / /Suspense } /4.5 排查技巧速查表症状排查方向常用工具页面无响应/卡死React DevTools 的 Profiler 看渲染耗时重点检查 useEffect 循环React DevTools数据更新不及时查 React Query 缓存 key 是否匹配invalidateQueries 是否调用React Query DevTools组件渲染了但样式错乱CSS Module 哈希冲突或主题变量未生效检查类名和变量引用浏览器 Elements 面板打包后体积过大查依赖是否重复打包有无遗漏的按需加载配置可用 rollup-plugin-visualizer 可视化分析Vite 构建报告接口请求频繁无意义检查是否有多个组件同时请求同一数据考虑提升到父组件或改用共享缓存浏览器 Network 面板4.6 调试技巧React Query DevTools 是排查缓存问题的最强工具。安装接入只需要三行import { ReactQueryDevtools } from tanstack/react-query-devtools // 开发环境下挂载 ReactQueryDevtools initialIsOpen{false} /有了它你能直观看到每个查询的缓存状态、最后更新时间、被哪些组件订阅。这在追查“为什么页面数据不新”这种问题时效率极高比反复查接口日志舒服多了。4.7 性能优化实录项目后期做了一次性能体检用 Lighthouse 测出来的首屏性能分数从 68 提到了 90 以上主要做了三件事。第一件事减少首屏不必要的 JS。利用React.lazy把看板页面的图表库单独拆出去因为图表库体积不小在首屏是不需要的等用户滚动到图表区域再加载即可。这个简单操作让首屏 JS 总量减少了约 30%。第二件事图片懒加载。管理系统的列表页有很多上传的截图附件直接用img loadinglazy /原生属性就解决了没有任何额外成本。第三件事优化大列表渲染。工单列表一页 50 条数据每条数据里有富文本内容渲染时明显卡顿。后来对列表项做了React.memo并为富文本内容做了缓存滚动体验立刻好了很多。5. 从进阶视角再看“rea”这个项目5.1 团队协作规范的沉淀做完这个项目我们沉淀了一套适合中小型前端团队的协作规范核心是三份文档组件命名与目录结构规范、状态管理使用规范、代码审查检查清单。组件命名上我特别重视路径即身份的命名方式比如src/components/WorkOrder/StatusTag.tsx只看路径就知道它是工单域下的状态标签组件。不用src/components/Common/StatusTag.tsx因为 Common 是垃圾场什么都能往里丢最终什么都找不到。状态管理使用规范里明确列了三条红线禁止在全局 Store 里存放接口返回的业务列表数据禁止在组件里直接用store.dispatch以外的副作用操作全局状态全局 Store 更新时注意不可变更新方式没有做浅层比较的 Store 更新会引发全部订阅者重渲染代码审查清单则是保护项目质量的最低防线有没有写死颜色值、有没有未使用的 imports、有没有绕过权限校验的直连接口调用、有没有 useEffect 依赖数组里引用了外部对象。5.2 未来的扩展思路这个项目后续如果要演进方向上我考虑了三条路。第一条是引入微前端架构。如果未来多个团队要并行开发不同业务线微前端能干这事把大应用拆成若干个独立部署、独立升级的子应用。目前项目还不到需要拆分的地步真到了那份上我倾向用 qiankun 之类的成熟框架自研微前端加载器看起来很美但成本真的很吓人。第二条是迁移部分页面到服务端渲染。如果业务开始对 SEO 或首屏秒开有要求可以挑选核心页面用 Next.js 重构而不是全部推翻重来。渐进式迁移才是低风险路径。第三条是接入单元测试和端到端测试的完整流水线。目前测试覆盖率只有核心工具函数和几个关键组件后续应该把工单流转这条主干链路用 Playwright 跑一遍端到端避免每次发版都要人肉回归。5.3 踩过坑后的几点体感整个项目做到最后回头看不只是技术层面的收获。有些经验是写代码写不出来非得在项目里踩了坑才能体会到的。一是对“约定大于配置”的理解。架构定的规范和约定越明确团队成员越多沟通成本节省得越明显。特别是封装好了数据请求、权限判断、路由生成这些基建后写业务页面的同学几乎只需要关心 UI 交互本身。二是对“过早优化”的克制。一开始有几个同事提议马上引入测试覆盖率门槛和 CI 流水线但项目前期需求变化极快早期设计大量调整时如果把时间大量消耗在维护测试上反而拖慢迭代。后来在核心链路稳定之后再把测试补上成本低得多价值也更高。三是对技术选型的敬畏。回头看 Zustand 可能不是每个项目的首选但在我们的场景下确实够用、好用。技术选型没有什么一招鲜核心思路始终是结合团队实际情况权衡投入产出比选择学习成本适中、生态成熟、退路清晰的方案。很多时候不用最时髦的框架反而能走得最远。React 这套生态之丰富给了开发者很多自由但也正因为自由空间大更容易走偏。一个项目的成功往往不在于用了什么新技术而在于把已经足够好的技术用出了体系、用出了规范。这大概就是我在这个项目里最深的感受吧。