如果有朋友看到“rea”这个词大概率会以为是一个外语单词的缩写。其实这是我给内部系统重构项目里前端工程起的代号全称是 React Enterprise Application简单来说就是一套跑在浏览器里的企业内部中后台系统负责登录、权限、订单管理、数据看板这些看起来不怎么起眼、但直接影响业务日常运转的功能。我从需求梳理做到上线交付前后花了四个月中间被权限设计、性能优化、工程化治理三座大山反复碾压。这篇文章准备把整个项目的决策过程、实现主线和踩坑实录都摊开来讲写给正在做 React 中后台项目、或者正准备对老系统做一次彻底重构的朋友。项目代号叫 rea其实还有一层意思renew enterprise application重构企业应用。当时接手这个系统的时候我们团队面临的是接近两万行几乎没有注释的旧代码。为了不让历史包袱继续滚雪球我们才决定重启炉灶。下面我会按实际项目的推进顺序来说每个环节都会带上当时的取舍理由和后来验证的结果。1. rea项目到底要解决什么问题旧系统的三座山1.1 第一座山代码耦合到不敢动这个系统是几年间陆续堆出来的一开始只是一套简单的内部数据录入页面后来不断有新的业务场景加进来组件之间就开始变得互相粘连。最常见的情况是某个订单状态变量被全局挂在某个对象上列表页可以改详情页也读它甚至导出功能也依赖它一旦改动就会牵一发动全身。当时团队里甚至流传着一句玩笑话“敢动共享状态的人就要做好周末被电话叫醒的准备。”这不是夸大是老项目衔接带来的真实心理阴影。具体来说页面之间传递数据完全靠全局状态组件卸载了变量还留在内存里。有一回线上用户反馈一个诡异问题A用户登录之后能看到B用户刚刚搜索过的订单号排查了很久才发现是全局变量在会话之间没有清理数据流完全没有边界。这类问题在老系统里非常多所以 rea 项目里的状态管理被当成第一优先级重新设计所有共享数据必须有明确的来源和去向不允许再出现“谁都能改、谁都不知道是谁改的”这种状态。1.2 第二座山权限控制形同虚设旧系统的权限模型基本属于“字典驱动”。菜单里配置了一堆权限字段前端根据当前用户是否包含某个字段来决定按钮显不显示而后端接口没有真正的数据范围校验。换句话说只要知道接口地址普通用户完全可以通过浏览器控制台直接调用管理员的接口数据。这个隐患才是这次重构最大的动力来源。在 rea 项目里权限被当成核心模块来设计而不是附属功能。所有接口请求都必须在网关层校验令牌和权限码前端只做交互层面的提示和按钮隐藏。我们内部有一个原则前端权限只是用户体验的一部分真正的安全底线必须由后端守住。这个原则在后续整个开发过程中帮我们避免了很多弯路也值得每一个做中后台系统的人认真对待。1.3 范围怎么定先把30个需求砍成6个模块需求评审的第一轮业务方列了一个长长的清单里面大概有30个“想要的东西”比如“导出的时候顺便给老板发一封邮件”“列表页能不能加一个很炫的3D图表”等等。我的做法是先不讨论技术而是把所有需求都按四个维度打分是否当前业务必须要、是否影响日常操作频率、重构时是否必须重做、不做的代价有多大。打分收敛后真正进入 rea 一期范围的只剩6个模块登录与权限、用户管理、订单列表、数据看板、消息中心、系统配置。每个模块的边界都写得很清楚订单列表只负责查询、筛选、导出不做新建订单数据看板只展示统计结果不承接下钻明细。这个“只重构不加新需求”的约定非常关键它保证了我们不会被无限的需求蔓延拖垮也让团队可以把精力集中在最核心的技术改造上。2. 技术选型的底层逻辑为什么最后定了 React 18 TypeScript Vite2.1 框架层面为什么没换 Vue 或 Svelte当时团队内部也有人提议既然都重写了不如试试别的前端框架。我认真对比过 Vue 3、Svelte、以及继续用 React 的成本。Vue 3 的响应式模型和模板语法确实很优雅生态也很成熟Svelte 的编译时优化让包体积很有吸引力。但最终选择继续使用 React核心理由不是技术优劣而是团队认知成本和生态覆盖能力。团队十几个人里大部分人的主力技术栈就是 React 和 TypeScript切换框架意味着所有人都要花时间重新学习最佳实践而我们的首要任务是在期限内把一个有风险的系统平稳替换掉。另外中后台项目真正依赖的是庞大的组件生态和状态管理方案React 在这个方向上的沉淀确实最厚。至于 Svelte我很欣赏它的设计理念但内部业务系统需要长期维护稳定的社区和人才储备比炫酷的编译逻辑更实际。2.2 构建工具Vite 带来的不只是快老项目用的是 Webpack配置已经膨胀到两千多行每次构建接近五分钟开发环境热更新慢得让人想下班。选构建工具时我在 Webpack 和 Vite 之间做过一轮实测同样一个中后台 demoWebpack 冷启动大概 8 秒左右Vite 冷启动只需要 1 秒多代码改动触发的热更新更是质的差别基本是亚秒级。Vite 底层依赖浏览器的原生 ES Module开发阶段不做整体打包而是按需转换文件所以项目越大它的优势越明显。生产构建时它又切换回 Rollup 做静态打包产物质量也有保障。当然 Vite 不是没有问题比如部分老旧的 CommonJS 格式依赖在预构建阶段会报错需要手动在 optimizeDeps 里配置 include。我们在 rea 项目里就遇到过一个老库的兼容问题后面会专门聊到这类坑。2.3 状态管理为什么没有选 Redux Toolkit中后台项目绕不开一个话题——状态管理。选择方案时Redux Toolkit 的规范性和中间件体系都很强但它会带来非常多的样板代码一个小功能可能要同时修改 action、reducer、selector 三个文件维护成本不低。我们在前期调研时列过一个对比表这里直接放出来供参考方案样板代码调试成本TypeScript 支持心智模型Redux Toolkit较多需要中间件和 DevTools优秀单向数据流规范明确MobX较少响应式追踪可读性好良好可变响应式与 React 略有错位Zustand非常少直接读取状态直观优秀简单 store无 Provider最终我们选了 Zustand。它的核心 API 非常小可以像 hooks 一样直接读取状态不需要 Provider 包裹也没有模板化的 action 类型定义。对于一个内部管理系统我们需要的是低心智负担和快速的开发效率而不是一套严格但繁琐的流程。选 Zustand 的理由很简单足够简单足够明确状态变更可以被直观地追踪。2.4 数据请求层axios 封装与 TanStack Query 的缓存思路rea 项目里的请求层用了 axios 统一封装负责三件事携带令牌、统一错误处理、统一返回结构解析。拦截器里做 401 跳登录做 403 提示无权限业务错误走统一的 toast 提示。这一层是所有页面的地基如果没有统一处理几十个页面每个都要自己写一遍错误判断代码很快就会失控。但我们没有把请求结果直接塞进 Zustand。服务端状态的缓存和管理交给了 TanStack Query。这是很多中后台项目容易忽略的优化点列表数据其实属于服务端状态不需要全局共享更应该关注的是缓存什么时候过期、什么时候重新拉取。TanStack Query 提供 key 管理和缓存回收机制比如订单列表用 [orders, currentPage, filters] 作为 key切页时能复用已缓存的数据回到第一页不会重新 loading 闪烁。设置 staleTime 为 5 分钟、gcTime 为 10 分钟之后整个列表页的体验明显平顺了很多。3. rea 核心实现主线动态权限路由与配置化组件3.1 RBAC 权限模型路由是根据菜单生成的权限设计上我们采用了经典的 RBAC 模型用户属于若干角色角色绑定若干权限点权限点包含菜单访问权限和按钮操作权限。后端登录接口返回三样东西当前用户信息、角色列表、可访问的菜单树。前端拿到菜单树之后再通过一个路由映射表把它转成 React Router 的 Route 对象。这里有一个所有前端都要记住的教训动态路由的目的是让业务方快速配置菜单而不是实现安全。真正防止越权的逻辑必须落在后端接口上。我们在 rea 项目里为此专门做了一次后端联调约定每个接口都必须校验当前用户的角色和数据范围哪怕前端没有把某个按钮渲染出来接口依然需要拒绝无权限的请求。前端路由对权限只负责“体验友好”如果你要做一个中后台系统建议直接把这条原则写进开发规范里。3.2 组件配置化表单和表格的重复劳动不值得用户管理、订单列表、消息中心这几个模块的形状高度相似一个搜索区、一个表格、一个分页器、偶尔一个导出按钮。如果每个页面独立写一遍 JSX不仅代码量爆炸而且后续加一个公共字段要改七八个文件。我们在 rea 项目里抽了两个配置化组件ConfigForm 和 ProTable。ConfigForm 通过一个 schema 描述表单字段的渲染方式、校验规则、联动逻辑和布局信息组件内部统一处理表单状态和提交逻辑。ProTable 接收列配置、请求函数、分页参数内部自动管理 loading、分页和查询条件。这两个组件把重复逻辑收敛到同一个文件里业务页面只需要提供配置和数据请求函数。不过这里我也想泼一点冷水配置化适合结构标准、重复度高的中后台场景如果你的表单有大量特殊布局和复杂联动强行用配置化未必比直接写 JSX 好维护。rea 项目里我们后来也保留了部分页面直接写 JSX 的入口这是个度的问题。3.3 TypeScript 的作用让接口数据不再靠猜重构最大的收益之一来自 TypeScript。老系统里接口返回的数据基本靠“猜”属性名到底是 orderNo 还是 order_id每个团队成员的记忆都不一样。rea 项目里我们先和后端对了一遍接口文档然后为每个核心模块定义了类型订单 Order、用户 User、菜单 Menu、角色 Role。类型定义带来的改变是很实际的以前改接口字段需要全局搜索字符串现在编译期就能发现漏改的地方以前前后端联调经常因为字段命名不一致扯皮现在接口返回值与类型不匹配时测试阶段就能提前暴露。我们甚至用类型工具把菜单树和路由配置的关联关系约束了起来让新增菜单时不容易把路径写错。TypeScript 不是万能的但在中后台项目里它确实把很多“也许没问题”变成了“编译期可见”。4. rea 性能优化实录首屏从 3.2 秒降到 1.1 秒踩过哪些坑4.1 第一版分包拆得太碎反而更慢功能基本开发完后第一次做性能摸底结果很不好看首屏加载时间在慢速网络环境下要 3.2 秒JS 总体积 2.1MB。我的第一反应是拆包把每个路由页面都做成懒加载于是用 React.lazy 和 Suspense 把六个模块全拆了一遍一顿操作猛如虎。结果构建产物里生成了 150 多个体积很小的 chunk。分包粒度过小浏览器需要发起大量并发请求去拉这些小文件即使现代网络协议能处理并发在弱网环境下小文件的请求开销依然很可观首屏不降反升。分包的正确思路应该是按“稳定边界”切第三方供应商包单独拆、UI 组件库单独拆、图表类库单独拆、业务公共代码单独拆页面级懒加载只保留真正需要优先渲染的路由。最终我们在 Vite 的 rollupOptions 里配置 manualChunks把 vendor、组件库、图表库、业务公共模块分别合并产物从 150 多个 chunk 收敛到十几个首屏体积直接降下来一大截。4.2 React.memo 被滥用后出现的诡异闪烁数据看板模块上线前我注意到一个奇怪的现象图表页面在切换筛选条件的瞬间会有轻微的闪动明明数据请求还没有返回但页面看起来像是被“局部刷新”了一下。排查后发现问题出在当时“一眼看上去很合理的优化”上我们给大量组件套了 React.memo希望通过减少重渲染来提升性能。但很多组件的 props 里包含了每次渲染都会重新创建的对象或函数比如某个父组件里直接写了 onClick 箭头函数这一行代码让 React.memo 的浅比较永远返回 falsememo 形同虚设还要额外承担一层比较开销。甚至在某些场景下这种多余的包裹反而拖慢了渲染。后来我们做了两件事第一删掉几乎所有没有实测收益的 memo第二真正需要缓存的组件用稳定的 useCallback 和 useMemo 保证依赖引用不变。性能和代码可读性在某些时候是相反的内部系统里可读性优先于微小的渲染优化。4.3 用数据看效果优化前后对照表指标优化前优化后首屏 JS 体积2.1 MB880 KBFCP首次内容绘制3.2 s1.3 sLCP最大内容绘制3.8 s1.5 sTTI可交互时间4.5 s2.1 s生产构建耗时约 5 min45 s 左右除了前端分包还在部署层做了两件事一是开启网站在生产环境的 gzip 压缩配置了 Nginx 的 gzip on文本资源直接再瘦 70% 左右二是确认静态资源链路里开启了 HTTP 协议的现代特性减少握手带来的延迟。性能优化从来不是单一手段的结果而是拆包、缓存、压缩、加载策略组合起来的效果。4.4 开发环境一切正常、生产环境慢半拍rea 项目里还碰到一个很典型的问题开发环境切页面都快得离谱但是部署到测试环境后第一次打开总感觉慢了半拍。后来发现是生产构建时没有正确区分环境变量接口域名还在指向本地 mock 服务导致真实环境下出现大量等待超时后才回退的逻辑。这个坑让我养成了一个习惯任何项目上线前先在生产构建产物里看一眼资源的请求域名和各接口的实际返回时间而不是盯着开发环境的控制台自嗨。5. 工程化收尾从代码规范到 CI/CD 与上线监控5.1 从第一天就定下来的规范ESLint Prettier Husky重构项目最怕的是最后又变回一盘散沙所以工程化规范必须从第一天就开始。代码规范方面rea 项目里用的是 ESLint 的 recommended 配置加 TypeScript 检查格式统一交给 Prettier然后用 Husky 在 pre-commit 阶段跑 lint-staged。也就是说不合规范的代码根本进不到提交记录里而不是等到 Code Review 时靠人眼去挑空格和分号。这里有个小经验ESLint 和 Prettier 同时存在时需要把格式相关的规则在 ESLint 里关掉避免两边打架。很多团队配完 Prettier 后没做这一步导致同一个文件被两个工具反复改写git diff 看得人头疼。规范这套东西前期配置成本不算高但收益是持续的越到项目后期越明显。5.2 单元测试只覆盖最关键的路径中后台项目要不要写单测我的看法是不要追求覆盖率数字而是先覆盖最容易出问题的路径。rea 项目里我们重点测了三类东西权限路由的生成逻辑也就是菜单转路由的函数是否正确通用表格组件的分页和查询交互以及数据格式化工具函数。用 Vitest 加 Testing Library 做单测跑一轮大概十几秒反馈速度很快。冒烟测试则由一条简单的脚本完成启动构建产物用无头浏览器依次访问登录页、跳转菜单、搜索订单、导出文件这些核心链路如果任何一个环节报错CI 直接判为失败。这类测试不是为了消灭所有 bug而是为了在每次迭代后快速确认主流程没有断。等人工点一遍再发现成本就高多了。5.3 CI/CD 流程与 Nginx 部署里的两个小坑持续集成用的是我们在某 Git 托管平台里配置的流水线三个核心阶段安装依赖、执行 lint 和测试、生产构建和归档。每次合并到主干分支后流水线会自动跑一遍构建产物再上传到部署服务器整个过程大约十几分钟。这个流程确保了一个原则只有经过自动检查的代码才能进到部署环节。部署层有两个坑值得单独说。第一中后台系统如果用了 history 模式路由刷新某个子页面时 Nginx 默认会返回 404必须把 location 配置里的 try_files 指向 index.html把所有路径都回落到应用入口。第二静态资源要设好缓存策略带 hash 的文件可以设置长时间的缓存而不带 hash 的 index.html 必须设置为不缓存否则发布新版本后用户拿到的永远是旧文件。这类“为什么我改了代码线上没变化”的排查最容易让人崩溃。上线之后我们还接了一套前端异常监控重点看三件事JS 运行错误、接口失败率、页面白屏率。监控指标本身不产生修复效果但它能在用户反馈之前提前暴露问题。某一次上线后我看到白屏率曲线跳了一个点点开详情发现是某个浏览器版本不支持新的语法特性立刻补上了兼容配置避免了更大的线上事故。6. 最后聊聊 rea 项目留给我的一些实在体会这一步看下来好像每一步都有很多技术细节但说实话这个项目让我最受益的并不是某一种工具而是处理问题的方式。首先不要把重构当成炫技的机会。本来只想换一个稳定的技术栈如果顺手升级了十几个依赖、改掉了一套业务逻辑你会在发布前夜同时面对无数个爆炸点。rea 项目里我们严格锁定了依赖版本业务逻辑以“搬运为主改造为辅”很多隐蔽问题因此没有发生。其次权限问题的底线意识值得反复强调。前端永远只负责界面表现后端必须对每一次请求校验身份、权限和数据范围。我们内部有个说法“前端负责把人带到门口门能不能进、能进到哪一层必须由门禁系统来回答。”这个门禁在前端工程里就是动态路由和按钮控制在真正的系统里就是接口鉴权。两者配合才能组成一个靠谱的权限体系。最后一条经验是关于工具链的规范这种东西越早定越省钱。等代码写了两万行再想着补 ESLint、补自动化测试动力和成本都会成倍上升。我在 rea 项目里最大的感慨是工程化的核心不是用多酷的技术而是让团队里每个人都能在同样的轨道上稳定前进。如果你正准备重构一个内部系统希望这篇记录能帮你少走几个我走过的弯路。
