如果你在公司里听到“这次用rea搭”这种话，别以为是在说React——它是我们内部对这套前端工程化方案的代号。简单讲，rea是一套从零搭建的React + TypeScript开发框架，把中后台项目里最常踩的坑提前填平：组件复用、请求层封装、路由权限、状态管理，这些原本每个项目都要重写一遍的东西，现在全部收敛成一套可复用的基础设施。这个项目是我在一家做企业软件服务的团队里牵头做的。当时手里有好几个业务系统：用户运营后台、订单管理平台、数据报表系统，还有后来接的客服工作台。表面上项目各不相干，翻到底层代码却发现有大量重复劳动，而且每个项目的写法都不一样。为了让后面新项目不再从零折腾，也为了让老项目可以逐步往统一方案上迁移，我花了一段时间梳理痛点、选型、写基建，最后把整套东西落地成了内部代号“rea”的工程化框架。这篇文章从需求背景、技术选型、目录设计、核心模块实现，到踩坑记录和排查思路，都会完整讲一遍。如果你正准备搭建自己的前端脚手架，或者在纠结中后台项目怎么工程化，这篇应该能给你不少可以直接抄的参考。1. 项目定位：为什么需要“rea”这套基础设施1.1 团队协作中的真实痛点先说一下背景。我当时所在的团队负责公司内部好几条业务线的前端，包括用户运营后台、订单管理系统、数据报表平台，还有后来接的一个客服工作台。表面上看项目很多，实际上翻开代码，里面的逻辑高度相似：都是典型的列表页、详情页、弹窗表单、状态流转，都是登录后才能访问，都是调用同一批后端接口。但问题也出在这：每个项目都是独立仓库存代码，技术栈各玩各的。有的从社区模板拷来一套，有的还是老式的类组件写法，有的甚至沿用了jQuery时代遗留的插件。维护成本奇高，一个人接手一个不熟悉的项目，光看代码结构就要花半天。每次新来一个同事，都要重新熟悉一遍当时项目的约定，很多经验沉淀不下来。后来领导准备把几条业务线的前端统一收口，让我牵头做技术方案。我当时提的核心思路是：不要急着把所有项目代码合并到一个仓库里，而是先抽出一套公共的开发框架，让大家在新项目里基于这套东西起步，老项目逐步迁移。这个框架的代号，就叫“rea”。它不是一个具体的业务系统，而是一个承载了业务开发通用能力的底座。1.2 方案选型背后的取舍选型这件事，说起来简单，做起来很容易陷入争论。我列一下rea最终的技术栈，顺便说说为什么是它们：React 18 + TypeScript：没有选Vue，不是因为Vue不好，而是因为团队里React熟练度更高，且业务组件生态更丰富。TypeScript是硬性要求，中后台项目领域模型复杂，接口返回结构差异很大，没有类型系统后期一定失控。Vite作为构建工具：相比Webpack，Vite的启动速度和热更新体验确实提升了一个量级。开发一个大型中后台，每次改代码等Webpack编译几十秒，太折磨。Vite的按需编译特性，让本地开发几乎是毫秒级反馈。Zustand做全局状态管理：团队之前用过Redux，但Redux的样板代码太多了，定义一个action、一个reducer，还要配selector，遇到异步逻辑还要引入中间件。Zustand的store就是一个hook，写起来非常直接，底层依赖React的useSyncExternalStore，性能没有问题。Ant Design作为基础组件库：企业级中后台场景下，AntD的组件覆盖度是最全的。我们不重复造轮子，只在其之上做二次封装。其实选Vite这件事，当时有个同事担心生产环境打包质量不如Webpack。我查了一些资料，也做了对比测试，Vite在压缩、代码分割方面用的是Rollup做生产构建，成熟度足够。真正需要注意的是后续一些依赖库的兼容性，这个在第4章踩坑部分细说。这套组合最终用起来很顺，但我要强调一点：技术选型没有银弹，关键是匹配团队的现实情况。如果你所在的团队Vue更熟练，那换成Vue 3 + Pinia完全等价；如果你要兼容老浏览器，Vite可能需要额外处理。先想清楚约束条件，再选技术栈，而不是先选技术栈再找理由。2. 核心架构：目录设计与模块拆分2.1 目录结构决策逻辑我见过太多项目，目录结构一开始没想清楚，半年后代码就乱成一锅粥。常见的乱法有两种：一是按文件类型堆，components下面扔了几百个文件，没人知道哪个是给哪个页面用的；二是按页面堆，一个页面文件夹里塞了api、types、utils、components全放一起，跨页面复用的时候就到处复制粘贴。rea在设计目录的时候，坚持了一个核心原则：按业务功能组织，而不是按技术类型组织。具体结构如下：src/ app/ # 应用启动、路由配置、全局布局 router.tsx layout/ features/ # 业务功能模块，每个模块自带组件、hooks、api Dashboard/ UserManage/ OrderManage/ components/ # 跨模块复用的通用组件 PageTable/ FilterBar/ StatusTag/ hooks/ # 通用hooks useTable/ useModal/ api/ # 全局请求实例与API定义 client.ts store/ # 全局状态 authStore.ts types/ # 全局类型定义 utils/ # 工具函数注意features层的逻辑：每个业务模块是一个独立的小王国，模块内部可以有自己的components、hooks、api，模块与模块之间尽量不互相引用。跨模块要共享的东西，提升到顶层的components、hooks。这样的好处是，后续业务扩展时，新增一个模块的成本很低，删除一个模块也不会影响其他模块。这个结构当时是从某本讲领域驱动设计的书里得到的灵感，但不要现在就去学那一套复杂的建模方法，先抓住“按业务边界聚合”这一个点就够了。实际开发时，发现某个组件在两个模块里出现，就往上提；发现某个文件跨模块互相引用了，就重新审视边界。这个维护过程比一开始设计得更完美更重要。2.2 请求层封装的细节设计请求层是工程化里最容易出彩、也最容易翻车的一层。我见过最敷衍的写法，是每个页面里直接import axios然后在业务代码里写请求。这样做的直接后果：后端返回错误时，每个页面各弹各的提示，有的页面甚至忘了处理错误，用户点了保存按钮没反应。rea的请求层分三层设计：第一层是axios实例的配置，设置baseURL、超时时间、请求头处理：import axios from 'axios' const client = axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL, timeout: 15000, }) client.interceptors.request.use((config) => { const token = localStorage.getItem('access_token') if (token) { config.headers.Authorization = `Bearer ${token}` } return config }) client.interceptors.response.use( (response) => { const res = response.data // 约定后端返回 { code, data, message } 结构 if (res.code !== 0) { message.error(res.message) return Promise.reject(new Error(res.message)) } return res.data }, (error) => { if (error.response?.status === 401) { // 统一跳登录 location.href = '/login' } else { message.error(error.message || '网络异常，请稍后重试') } return Promise.reject(error) } )第二层是API函数的组织。我的习惯是每个feature对应一个api文件，按后端接口的模块名分组。比如UserManage模块的用户接口：import { client } from '@/api/client' export const userApi = { list: (params: UserListParams) => client.get('/users', { params }), create: (data: UserCreatePayload) => client.post('/users', data), update: (id: number, data: UserUpdatePayload) => client.put(`/users/${id}`, data), }第三层是在业务代码里通过hooks调用API，把loading、error、数据状态收敛起来。这里用到了TanStack Query（准确的说是TanStack Query），它帮我们解决了缓存、重试、竞态这些麻烦事。我强烈建议，中后台项目里请求状态管理直接用TanStack Query，不要在Zustand里手动维护服务端数据。区分这两者的一个简单标准：服务端数据（列表、详情、下拉选项）交给TanStack Query；客户端数据（弹窗开关、当前选中的tab）用Zustand。这个分流规则一开始就定好，后面就不会出现把接口返回数据塞进全局store、导致组件无限刷新的惨案。2.3 状态管理与数据流方案Zustand这边，我只维护真正的全局客户端状态。最典型的例子是登录用户信息。登录接口返回用户信息和token，token存到localStorage或cookie，用户信息放store里，供全局布局、权限判断、个人中心使用。一个典型的authStore长这样：import { create } from 'zustand' interface AuthState { user: UserInfo | null permissions: string[] setUser: (user: UserInfo) => void setPermissions: (perms: string[]) => void logout: () => void } export const useAuthStore = create<AuthState>((set) => ({ user: null, permissions: [], setUser: (user) => set({ user }), setPermissions: (permissions) => set({ permissions }), logout: () => { localStorage.removeItem('access_token') set({ user: null, permissions: [] }) }, }))这里有一个我后来特别想强调的经验：不要试图用一个store管所有东西。多个store按领域拆分，等同于给全局状态画了清晰的责任边界。比如某个页面里选中的筛选项，它的生命周期范围只是当前页面，就没有必要提升到全局store，用组件的useState就足够了。另外一种很常见的错误是，把请求状态也塞进Zustand里。比如手动维护一个loading字段、一个error字段、一个data字段，然后每个用到这个数据的组件都从一个全局store里取。这会导致数据同步非常麻烦，因为多个组件可能同时修改同一个状态，调试起来很痛苦。Token、用户信息、权限列表这类身份相关的数据放全局store，其余数据尽量做到就近管理。3. 关键模块的实现与踩坑实录3.1 组件库设计：从业务组件到基础组件rea没有自己写一套基础UI组件库，那样做成本太高，也没有必要。我们做的是一件更务实的事：在Ant Design基础上做业务组件的二次封装，把那些“每个页面都要写一遍的组合逻辑”沉淀成组件。第一个典型的业务组件是PageTable，它组合了筛选表单、表格、分页三个部分。以前每写一个列表页，都要手动维护筛选值、分页参数、请求loading、表格数据、选中行状态。有了PageTable，只需要传入配置：<PageTable columns={columns} fetchFn={userApi.list} rowKey="userId" defaultParams={{ status: 'active' }} onSearch={(params) => handleSearch(params)} onSelectionChange={(keys) => handleSelection(keys)} />PageTable内部做的事情，是把筛选表单的状态、分页的页码和页大小、请求参数、数据刷新逻辑全部封装好。使用者不需要关心它内部怎么管理loading，只需要关注业务配置。封装业务组件时有几个经验可以分享：配置优先：能用配置表达的就不要用JSX。比如筛选项、表格列、操作按钮，写成配置数组，比写一堆JSX节点更容易维护，也方便以后从接口返回动态配置。扩展槽位：组件一定要留children、render slot这类扩展入口，否则遇到特殊需求时只能改源码，那就失去复用的意义了。稳定API：组件一旦被多个模块使用，它的prop类型定义更改会牵连一片调用方。所以设计组件props时要多想一步，把可能需要支持的场景提前考虑进去。比如PageTable的onSelectionChange，最初没设计，后来有页面需要批量操作，只好升级组件。提前设计好，能省很多麻烦。另外还有一个细节是，业务组件需要对外暴露底层的AntD组件实例。比如PageTable的查询按钮要加一个loading状态，需要拿到内部Table的ref，这时候就用forwardRef把ref透传下去。设计组件API的时候要同时考虑“配置型用法”和“命令式用法”，否则后期补ref会打破组件封装的边界。3.2 路由与权限控制的落地权限控制是后台系统绕不开的需求。rea采用的是菜单+按钮两级权限模型：菜单权限：根据当前用户的权限列表过滤出他能访问的路由，动态生成侧边栏菜单。按钮权限：通过一个权限指令或自定义hook控制某个按钮是否渲染。路由部分用的是React Router v6，配合一个routes配置数组，在初始化时根据登录状态和权限动态生成。踩坑最多的点是页面刷新后路由丢失。由于路由是动态生成的，刷新时应用重新初始化，如果此时token还在、但权限数据还没从后端拉回来，路由表可能是空的，用户就被打到404页面。这个问题的解决办法是把用户信息和权限的初始化逻辑做成一个async操作，在应用真正渲染路由之前await它完成。具体做法是在入口组件里加一个全局的启动步骤：function App() { const [ready, setReady] = useState(false) useEffect(() => { initAppData() .then(() => setReady(true)) .catch(() => location.href = '/login') }, []) if (!ready) { return <Spin fullscreen /> } return <AppRouter /> }这个方案效果很好，但需要注意initAppData里加载失败时的处理。如果接口报错，不能卡在loading页面，必须明确跳转到登录页或者展示错误页。我测试的时候就遇到过后端服务临时重启，导致整个后台刷新后一直白屏，排查半天才发现是初始化请求没有捕获错误。按钮权限的落地，工具函数层面可以参考这个思路：export const hasPermission = (perm: string): boolean => { return useAuthStore.getState().permissions.includes(perm) }在组件里使用的时候就配合useMemo或者直接用条件渲染，比如：{canDelete && ( <Button danger onClick={handleDelete}>删除</Button> )}这里的canDelete来自一个权限hook，它会订阅state变化。这里要注意，不要在业务组件里直接调用useAuthStore.getState()后依赖它的返回值，因为getState()不会触发组件订阅更新，权限变化时组件不会重新渲染。正确的方式是通过selector订阅store里的permissions字段。3.3 性能优化的三个关键操作中后台项目性能优化的空间，不像C端网站那么巨大，但有几个点是必须要做的。第一个是路由级懒加载。React Router v6里用lazy和Suspense实现，这个比较标准：const UserManage = lazy(() => import('@/features/UserManage')) <Routes> <Route path="/users" element={ <Suspense fallback={<PageLoading />}> <UserManage /> </Suspense> } /> </Routes>把每个业务模块的代码拆分到独立chunk，首屏只加载必要的代码。实测下来，主包体积能减少四成以上。特别是那种体积很大的图表库、富文本编辑器，只有在进入对应页面时才加载，首屏速度提升明显。第二个是大表格的虚拟滚动。中后台页面经常有几百上千条数据的表格，直接渲染会有明显卡顿。AntD的Table本身支持虚拟滚动，但需要配置对应的虚拟列表组件，或者直接使用后续版本中Experimental的virtualization配置。我们在rea里直接引入了一个虚拟列表组件，只渲染可视区域的行，内存和渲染压力都会小很多。注意，使用虚拟滚动后，某些需要在表格外层包裹固定宽度的操作（比如横向滚动容器、固定列表格）可能会出现渲染异常，需要额外调试。我建议在接入之前先在原型上验证一下，不要等到真实页面做了一半才去切换虚拟滚动，那时排查成本会高很多。第三个是useCallback和useMemo的合理使用，但这里我要泼一盆冷水：不要过度优化。很多项目把useCallback用得到处都是，结果代码可读性变差，性能却没有提升。一个简单的原则：只有当子组件使用了React.memo，或者某个计算量真的很大（比如排序、过滤几百条数据），再考虑useCallback和useMemo。否则，大多数情况下直接写就是在浪费精力。还有一个容易忽略的点是图片资源和静态资源的懒加载。中后台系统虽然不像电商页面那么依赖图片，但有些数据看板会展示很多图表icon、业务Logo，如果不做处理，首屏请求的资源数量会非常多。在Vite里可以通过配置assetsInlineLimit把小的静态资源直接内联，大的资源再配合懒加载，可以明显减少网络请求数。4. 常见问题排查与技巧实录4.1 TypeScript类型带来的连锁报错由于rea用了严格模式（strict: true），刚开始时团队成员写代码频繁遇到类型报错，最常见的是后端返回到前端之后被axios泛型吞掉了类型。我们的后端接口约定返回结构是{ code, data, message }，但类型定义里data具体是什么，每个接口不一样。如果把client封装成直接返回response.data.data，TypeScript就会搞不清楚具体的data类型。解决方法是给client实例定义泛型方法：const request = { get: <T,>(url: string, params?: object): Promise<T> => client.get(url, { params }), post: <T,>(url: string, data?: object): Promise<T> => client.post(url, data), }然后调用时显式传入返回类型：const users = await request.get<UserListResponse>('/users', { page: 1 })这样可以保证接口返回数据的类型安全，也避免了一次any把类型系统击穿的连锁效应。实际开发中，接口返回的数据结构经常变，后期维护类型定义也是一项工作，所以最好在后端接口文档或mock数据变动时顺手更新一下types文件，让类型始终和接口保持一致。4.2 请求竞态问题请求竞态是中后台开发里一个很容易被忽略但后果严重的bug。简单说，用户在搜索框输入关键词，每敲一个字母就触发一次请求，上一次的请求返回得比下一次还慢，于是旧数据把新数据覆盖了，页面显示的不是用户最终要的结果。解决方式有几种。我首推AbortController：const controller = new AbortController() useEffect(() => { fetchData({ keyword, signal: controller.signal }) return () => controller.abort() }, [keyword])在TanStack Query里，它默认就用AbortController处理了这种竞态问题，而且会自动取消之前的请求。这也是我推荐引入TanStack Query的另一个重要原因。如果你还在手动管理请求，至少要在公共请求层里支持传入signal，并妥善处理被abort的异常，避免catch到错误后仍然弹出错误提示。这个坑特别隐蔽，表面上看是“数据不对”，实际上是竞态问题。4.3 打包体积优化用Vite构建中后台项目，默认的构建结果已经很不错。但rea项目初期还是遇到了一个坑：某个功能模块打包后体积爆炸，排查发现是某个第三方图表库被整体引入。虽然是按需引入的方式，但该库的ESM版本还是把整个包引了进来。解决方法是手动配置按需加载，在Vite的build.rollupOptions中把该库单独拆分，然后用动态import只加载用到的图表类型。类似的场景还有日期处理库、大型表格库，都值得检查是否被整体打包进来了。建议养成定期看打包报告的习惯，Vite内置的build --report或使用vite-plugin-visualizer都能帮你快速定位体积大户。还有一点是关于第三方库版本升级。Vite的依赖预构建机制在依赖更新后需要重新构建，有时候会在开发环境出现缓存导致奇怪的问题。碰到这种问题，先尝试删除node_modules和dist目录，重新install和build，很多时候就能解决。4.4 一些不起眼但很实用的技巧环境变量管理：使用import.meta.env.VITE_*前缀的变量，但要注意别把敏感信息放进去，前端的环境变量本来就是公开的。区分开发、测试、生产环境，用.env.development、.env.test、.env.production文件管理，清晰有效。请求失败的统一提示：在拦截器里统一处理，可以减少业务代码里的重复错误弹窗。但有些场景比如自动保存，用户不希望看到错误弹窗频繁出现，需要给请求方法加一个silent选项绕过统一提示。保持组件默认导出的统一：如果每个业务组件都默认导出，页面级组件引用时的import路径会看起来更整齐。这个纯属团队风格问题，但统一就好，省得团队里一半人用默认导入一半人用命名导入。mock接口的接入方案：中后台开发经常要等后端接口就绪，建议在工程化框架里预留好mock层。开发时可以切到mock数据，后端就绪后再切回真实接口，不用改业务代码。写在最后的一点体会如果把rea从零到一的过程浓缩成一句话，我会说：搭建一套基础设施，比的不是谁写的代码更炫，而是谁对团队协作中的痛点理解得更深。技术选型、目录设计、代码分层，背后都是“减少沟通成本、降低心智负担”这一目的。我后来在另一个项目里又做了一次类似的工程化梳理，发现很多思路依然有效，但每个团队都有自己特殊的上下文，照搬方案不如先理解原则。如果你正准备做类似的事情，我的建议是：先花两周时间梳理现有代码里的重复模式，理清真正的痛点，再动手搭框架。框架本身不是目的，让团队写业务代码更快、更稳，才是衡量这个框架是否值得存在的唯一标准。另外，工程化基础设施永远不要追求一步到位，先解决最痛的问题，再在后续项目中一点一点补齐能力，这样反而能让框架沉淀出真正有价值的东西。
如果你在公司里听到“这次用rea搭”这种话，别以为是在说React——它是我们内部对这套前端工程化方案的代号。简单讲，rea是一套从零搭建的React + TypeScript开发框架，把中后台项目里最常踩的坑提前填平：组件复用、请求层封装、路由权限、状态管理，这些原本每个项目都要重写一遍的东西，现在全部收敛成一套可复用的基础设施。这个项目是我在一家做企业软件服务的团队里牵头做的。当时手里有好几个业务系统：用户运营后台、订单管理平台、数据报表系统，还有后来接的客服工作台。表面上项目各不相干，翻到底层代码却发现有大量重复劳动，而且每个项目的写法都不一样。为了让后面新项目不再从零折腾，也为了让老项目可以逐步往统一方案上迁移，我花了一段时间梳理痛点、选型、写基建，最后把整套东西落地成了内部代号“rea”的工程化框架。这篇文章从需求背景、技术选型、目录设计、核心模块实现，到踩坑记录和排查思路，都会完整讲一遍。如果你正准备搭建自己的前端脚手架，或者在纠结中后台项目怎么工程化，这篇应该能给你不少可以直接抄的参考。1. 项目定位：为什么需要“rea”这套基础设施1.1 团队协作中的真实痛点先说一下背景。我当时所在的团队负责公司内部好几条业务线的前端，包括用户运营后台、订单管理系统、数据报表平台，还有后来接的一个客服工作台。表面上看项目很多，实际上翻开代码，里面的逻辑高度相似：都是典型的列表页、详情页、弹窗表单、状态流转，都是登录后才能访问，都是调用同一批后端接口。但问题也出在这：每个项目都是独立仓库存代码，技术栈各玩各的。有的从社区模板拷来一套，有的还是老式的类组件写法，有的甚至沿用了jQuery时代遗留的插件。维护成本奇高，一个人接手一个不熟悉的项目，光看代码结构就要花半天。每次新来一个同事，都要重新熟悉一遍当时项目的约定，很多经验沉淀不下来。后来领导准备把几条业务线的前端统一收口，让我牵头做技术方案。我当时提的核心思路是：不要急着把所有项目代码合并到一个仓库里，而是先抽出一套公共的开发框架，让大家在新项目里基于这套东西起步，老项目逐步迁移。这个框架的代号，就叫“rea”。它不是一个具体的业务系统，而是一个承载了业务开发通用能力的底座。1.2 方案选型背后的取舍选型这件事，说起来简单，做起来很容易陷入争论。我列一下rea最终的技术栈，顺便说说为什么是它们：React 18 + TypeScript：没有选Vue，不是因为Vue不好，而是因为团队里React熟练度更高，且业务组件生态更丰富。TypeScript是硬性要求，中后台项目领域模型复杂，接口返回结构差异很大，没有类型系统后期一定失控。Vite作为构建工具：相比Webpack，Vite的启动速度和热更新体验确实提升了一个量级。开发一个大型中后台，每次改代码等Webpack编译几十秒，太折磨。Vite的按需编译特性，让本地开发几乎是毫秒级反馈。Zustand做全局状态管理：团队之前用过Redux，但Redux的样板代码太多了，定义一个action、一个reducer，还要配selector，遇到异步逻辑还要引入中间件。Zustand的store就是一个hook，写起来非常直接，底层依赖React的useSyncExternalStore，性能没有问题。Ant Design作为基础组件库：企业级中后台场景下，AntD的组件覆盖度是最全的。我们不重复造轮子，只在其之上做二次封装。其实选Vite这件事，当时有个同事担心生产环境打包质量不如Webpack。我查了一些资料，也做了对比测试，Vite在压缩、代码分割方面用的是Rollup做生产构建，成熟度足够。真正需要注意的是后续一些依赖库的兼容性，这个在第4章踩坑部分细说。这套组合最终用起来很顺，但我要强调一点：技术选型没有银弹，关键是匹配团队的现实情况。如果你所在的团队Vue更熟练，那换成Vue 3 + Pinia完全等价；如果你要兼容老浏览器，Vite可能需要额外处理。先想清楚约束条件，再选技术栈，而不是先选技术栈再找理由。2. 核心架构：目录设计与模块拆分2.1 目录结构决策逻辑我见过太多项目，目录结构一开始没想清楚，半年后代码就乱成一锅粥。常见的乱法有两种：一是按文件类型堆，components下面扔了几百个文件，没人知道哪个是给哪个页面用的；二是按页面堆，一个页面文件夹里塞了api、types、utils、components全放一起，跨页面复用的时候就到处复制粘贴。rea在设计目录的时候，坚持了一个核心原则：按业务功能组织，而不是按技术类型组织。具体结构如下：src/ app/ # 应用启动、路由配置、全局布局 router.tsx layout/ features/ # 业务功能模块，每个模块自带组件、hooks、api Dashboard/ UserManage/ OrderManage/ components/ # 跨模块复用的通用组件 PageTable/ FilterBar/ StatusTag/ hooks/ # 通用hooks useTable/ useModal/ api/ # 全局请求实例与API定义 client.ts store/ # 全局状态 authStore.ts types/ # 全局类型定义 utils/ # 工具函数注意features层的逻辑：每个业务模块是一个独立的小王国，模块内部可以有自己的components、hooks、api，模块与模块之间尽量不互相引用。跨模块要共享的东西，提升到顶层的components、hooks。这样的好处是，后续业务扩展时，新增一个模块的成本很低，删除一个模块也不会影响其他模块。这个结构当时是从某本讲领域驱动设计的书里得到的灵感，但不要现在就去学那一套复杂的建模方法，先抓住“按业务边界聚合”这一个点就够了。实际开发时，发现某个组件在两个模块里出现，就往上提；发现某个文件跨模块互相引用了，就重新审视边界。这个维护过程比一开始设计得更完美更重要。2.2 请求层封装的细节设计请求层是工程化里最容易出彩、也最容易翻车的一层。我见过最敷衍的写法，是每个页面里直接import axios然后在业务代码里写请求。这样做的直接后果：后端返回错误时，每个页面各弹各的提示，有的页面甚至忘了处理错误，用户点了保存按钮没反应。rea的请求层分三层设计：第一层是axios实例的配置，设置baseURL、超时时间、请求头处理：import axios from 'axios' const client = axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL, timeout: 15000, }) client.interceptors.request.use((config) => { const token = localStorage.getItem('access_token') if (token) { config.headers.Authorization = `Bearer ${token}` } return config }) client.interceptors.response.use( (response) => { const res = response.data // 约定后端返回 { code, data, message } 结构 if (res.code !== 0) { message.error(res.message) return Promise.reject(new Error(res.message)) } return res.data }, (error) => { if (error.response?.status === 401) { // 统一跳登录 location.href = '/login' } else { message.error(error.message || '网络异常，请稍后重试') } return Promise.reject(error) } )第二层是API函数的组织。我的习惯是每个feature对应一个api文件，按后端接口的模块名分组。比如UserManage模块的用户接口：import { client } from '@/api/client' export const userApi = { list: (params: UserListParams) => client.get('/users', { params }), create: (data: UserCreatePayload) => client.post('/users', data), update: (id: number, data: UserUpdatePayload) => client.put(`/users/${id}`, data), }第三层是在业务代码里通过hooks调用API，把loading、error、数据状态收敛起来。这里用到了TanStack Query（准确的说是TanStack Query），它帮我们解决了缓存、重试、竞态这些麻烦事。我强烈建议，中后台项目里请求状态管理直接用TanStack Query，不要在Zustand里手动维护服务端数据。区分这两者的一个简单标准：服务端数据（列表、详情、下拉选项）交给TanStack Query；客户端数据（弹窗开关、当前选中的tab）用Zustand。这个分流规则一开始就定好，后面就不会出现把接口返回数据塞进全局store、导致组件无限刷新的惨案。2.3 状态管理与数据流方案Zustand这边，我只维护真正的全局客户端状态。最典型的例子是登录用户信息。登录接口返回用户信息和token，token存到localStorage或cookie，用户信息放store里，供全局布局、权限判断、个人中心使用。一个典型的authStore长这样：import { create } from 'zustand' interface AuthState { user: UserInfo | null permissions: string[] setUser: (user: UserInfo) => void setPermissions: (perms: string[]) => void logout: () => void } export const useAuthStore = create<AuthState>((set) => ({ user: null, permissions: [], setUser: (user) => set({ user }), setPermissions: (permissions) => set({ permissions }), logout: () => { localStorage.removeItem('access_token') set({ user: null, permissions: [] }) }, }))这里有一个我后来特别想强调的经验：不要试图用一个store管所有东西。多个store按领域拆分，等同于给全局状态画了清晰的责任边界。比如某个页面里选中的筛选项，它的生命周期范围只是当前页面，就没有必要提升到全局store，用组件的useState就足够了。另外一种很常见的错误是，把请求状态也塞进Zustand里。比如手动维护一个loading字段、一个error字段、一个data字段，然后每个用到这个数据的组件都从一个全局store里取。这会导致数据同步非常麻烦，因为多个组件可能同时修改同一个状态，调试起来很痛苦。Token、用户信息、权限列表这类身份相关的数据放全局store，其余数据尽量做到就近管理。3. 关键模块的实现与踩坑实录3.1 组件库设计：从业务组件到基础组件rea没有自己写一套基础UI组件库，那样做成本太高，也没有必要。我们做的是一件更务实的事：在Ant Design基础上做业务组件的二次封装，把那些“每个页面都要写一遍的组合逻辑”沉淀成组件。第一个典型的业务组件是PageTable，它组合了筛选表单、表格、分页三个部分。以前每写一个列表页，都要手动维护筛选值、分页参数、请求loading、表格数据、选中行状态。有了PageTable，只需要传入配置：<PageTable columns={columns} fetchFn={userApi.list} rowKey="userId" defaultParams={{ status: 'active' }} onSearch={(params) => handleSearch(params)} onSelectionChange={(keys) => handleSelection(keys)} />PageTable内部做的事情，是把筛选表单的状态、分页的页码和页大小、请求参数、数据刷新逻辑全部封装好。使用者不需要关心它内部怎么管理loading，只需要关注业务配置。封装业务组件时有几个经验可以分享：配置优先：能用配置表达的就不要用JSX。比如筛选项、表格列、操作按钮，写成配置数组，比写一堆JSX节点更容易维护，也方便以后从接口返回动态配置。扩展槽位：组件一定要留children、render slot这类扩展入口，否则遇到特殊需求时只能改源码，那就失去复用的意义了。稳定API：组件一旦被多个模块使用，它的prop类型定义更改会牵连一片调用方。所以设计组件props时要多想一步，把可能需要支持的场景提前考虑进去。比如PageTable的onSelectionChange，最初没设计，后来有页面需要批量操作，只好升级组件。提前设计好，能省很多麻烦。另外还有一个细节是，业务组件需要对外暴露底层的AntD组件实例。比如PageTable的查询按钮要加一个loading状态，需要拿到内部Table的ref，这时候就用forwardRef把ref透传下去。设计组件API的时候要同时考虑“配置型用法”和“命令式用法”，否则后期补ref会打破组件封装的边界。3.2 路由与权限控制的落地权限控制是后台系统绕不开的需求。rea采用的是菜单+按钮两级权限模型：菜单权限：根据当前用户的权限列表过滤出他能访问的路由，动态生成侧边栏菜单。按钮权限：通过一个权限指令或自定义hook控制某个按钮是否渲染。路由部分用的是React Router v6，配合一个routes配置数组，在初始化时根据登录状态和权限动态生成。踩坑最多的点是页面刷新后路由丢失。由于路由是动态生成的，刷新时应用重新初始化，如果此时token还在、但权限数据还没从后端拉回来，路由表可能是空的，用户就被打到404页面。这个问题的解决办法是把用户信息和权限的初始化逻辑做成一个async操作，在应用真正渲染路由之前await它完成。具体做法是在入口组件里加一个全局的启动步骤：function App() { const [ready, setReady] = useState(false) useEffect(() => { initAppData() .then(() => setReady(true)) .catch(() => location.href = '/login') }, []) if (!ready) { return <Spin fullscreen /> } return <AppRouter /> }这个方案效果很好，但需要注意initAppData里加载失败时的处理。如果接口报错，不能卡在loading页面，必须明确跳转到登录页或者展示错误页。我测试的时候就遇到过后端服务临时重启，导致整个后台刷新后一直白屏，排查半天才发现是初始化请求没有捕获错误。按钮权限的落地，工具函数层面可以参考这个思路：export const hasPermission = (perm: string): boolean => { return useAuthStore.getState().permissions.includes(perm) }在组件里使用的时候就配合useMemo或者直接用条件渲染，比如：{canDelete && ( <Button danger onClick={handleDelete}>删除</Button> )}这里的canDelete来自一个权限hook，它会订阅state变化。这里要注意，不要在业务组件里直接调用useAuthStore.getState()后依赖它的返回值，因为getState()不会触发组件订阅更新，权限变化时组件不会重新渲染。正确的方式是通过selector订阅store里的permissions字段。3.3 性能优化的三个关键操作中后台项目性能优化的空间，不像C端网站那么巨大，但有几个点是必须要做的。第一个是路由级懒加载。React Router v6里用lazy和Suspense实现，这个比较标准：const UserManage = lazy(() => import('@/features/UserManage')) <Routes> <Route path="/users" element={ <Suspense fallback={<PageLoading />}> <UserManage /> </Suspense> } /> </Routes>把每个业务模块的代码拆分到独立chunk，首屏只加载必要的代码。实测下来，主包体积能减少四成以上。特别是那种体积很大的图表库、富文本编辑器，只有在进入对应页面时才加载，首屏速度提升明显。第二个是大表格的虚拟滚动。中后台页面经常有几百上千条数据的表格，直接渲染会有明显卡顿。AntD的Table本身支持虚拟滚动，但需要配置对应的虚拟列表组件，或者直接使用后续版本中Experimental的virtualization配置。我们在rea里直接引入了一个虚拟列表组件，只渲染可视区域的行，内存和渲染压力都会小很多。注意，使用虚拟滚动后，某些需要在表格外层包裹固定宽度的操作（比如横向滚动容器、固定列表格）可能会出现渲染异常，需要额外调试。我建议在接入之前先在原型上验证一下，不要等到真实页面做了一半才去切换虚拟滚动，那时排查成本会高很多。第三个是useCallback和useMemo的合理使用，但这里我要泼一盆冷水：不要过度优化。很多项目把useCallback用得到处都是，结果代码可读性变差，性能却没有提升。一个简单的原则：只有当子组件使用了React.memo，或者某个计算量真的很大（比如排序、过滤几百条数据），再考虑useCallback和useMemo。否则，大多数情况下直接写就是在浪费精力。还有一个容易忽略的点是图片资源和静态资源的懒加载。中后台系统虽然不像电商页面那么依赖图片，但有些数据看板会展示很多图表icon、业务Logo，如果不做处理，首屏请求的资源数量会非常多。在Vite里可以通过配置assetsInlineLimit把小的静态资源直接内联，大的资源再配合懒加载，可以明显减少网络请求数。4. 常见问题排查与技巧实录4.1 TypeScript类型带来的连锁报错由于rea用了严格模式（strict: true），刚开始时团队成员写代码频繁遇到类型报错，最常见的是后端返回到前端之后被axios泛型吞掉了类型。我们的后端接口约定返回结构是{ code, data, message }，但类型定义里data具体是什么，每个接口不一样。如果把client封装成直接返回response.data.data，TypeScript就会搞不清楚具体的data类型。解决方法是给client实例定义泛型方法：const request = { get: <T,>(url: string, params?: object): Promise<T> => client.get(url, { params }), post: <T,>(url: string, data?: object): Promise<T> => client.post(url, data), }然后调用时显式传入返回类型：const users = await request.get<UserListResponse>('/users', { page: 1 })这样可以保证接口返回数据的类型安全，也避免了一次any把类型系统击穿的连锁效应。实际开发中，接口返回的数据结构经常变，后期维护类型定义也是一项工作，所以最好在后端接口文档或mock数据变动时顺手更新一下types文件，让类型始终和接口保持一致。4.2 请求竞态问题请求竞态是中后台开发里一个很容易被忽略但后果严重的bug。简单说，用户在搜索框输入关键词，每敲一个字母就触发一次请求，上一次的请求返回得比下一次还慢，于是旧数据把新数据覆盖了，页面显示的不是用户最终要的结果。解决方式有几种。我首推AbortController：const controller = new AbortController() useEffect(() => { fetchData({ keyword, signal: controller.signal }) return () => controller.abort() }, [keyword])在TanStack Query里，它默认就用AbortController处理了这种竞态问题，而且会自动取消之前的请求。这也是我推荐引入TanStack Query的另一个重要原因。如果你还在手动管理请求，至少要在公共请求层里支持传入signal，并妥善处理被abort的异常，避免catch到错误后仍然弹出错误提示。这个坑特别隐蔽，表面上看是“数据不对”，实际上是竞态问题。4.3 打包体积优化用Vite构建中后台项目，默认的构建结果已经很不错。但rea项目初期还是遇到了一个坑：某个功能模块打包后体积爆炸，排查发现是某个第三方图表库被整体引入。虽然是按需引入的方式，但该库的ESM版本还是把整个包引了进来。解决方法是手动配置按需加载，在Vite的build.rollupOptions中把该库单独拆分，然后用动态import只加载用到的图表类型。类似的场景还有日期处理库、大型表格库，都值得检查是否被整体打包进来了。建议养成定期看打包报告的习惯，Vite内置的build --report或使用vite-plugin-visualizer都能帮你快速定位体积大户。还有一点是关于第三方库版本升级。Vite的依赖预构建机制在依赖更新后需要重新构建，有时候会在开发环境出现缓存导致奇怪的问题。碰到这种问题，先尝试删除node_modules和dist目录，重新install和build，很多时候就能解决。4.4 一些不起眼但很实用的技巧环境变量管理：使用import.meta.env.VITE_*前缀的变量，但要注意别把敏感信息放进去，前端的环境变量本来就是公开的。区分开发、测试、生产环境，用.env.development、.env.test、.env.production文件管理，清晰有效。请求失败的统一提示：在拦截器里统一处理，可以减少业务代码里的重复错误弹窗。但有些场景比如自动保存，用户不希望看到错误弹窗频繁出现，需要给请求方法加一个silent选项绕过统一提示。保持组件默认导出的统一：如果每个业务组件都默认导出，页面级组件引用时的import路径会看起来更整齐。这个纯属团队风格问题，但统一就好，省得团队里一半人用默认导入一半人用命名导入。mock接口的接入方案：中后台开发经常要等后端接口就绪，建议在工程化框架里预留好mock层。开发时可以切到mock数据，后端就绪后再切回真实接口，不用改业务代码。写在最后的一点体会如果把rea从零到一的过程浓缩成一句话，我会说：搭建一套基础设施，比的不是谁写的代码更炫，而是谁对团队协作中的痛点理解得更深。技术选型、目录设计、代码分层，背后都是“减少沟通成本、降低心智负担”这一目的。我后来在另一个项目里又做了一次类似的工程化梳理，发现很多思路依然有效，但每个团队都有自己特殊的上下文，照搬方案不如先理解原则。如果你正准备做类似的事情，我的建议是：先花两周时间梳理现有代码里的重复模式，理清真正的痛点，再动手搭框架。框架本身不是目的，让团队写业务代码更快、更稳，才是衡量这个框架是否值得存在的唯一标准。另外，工程化基础设施永远不要追求一步到位，先解决最痛的问题，再在后续项目中一点一点补齐能力，这样反而能让框架沉淀出真正有价值的东西。