《Spring WebFlux React搭建后台管理系统4: antd pro v5 设置》这个系列前几篇主要在做后端Spring WebFlux 的响应式接口、统一响应结构、鉴权过滤器这些基础都打好了。但一个后台管理系统不能只有接口总得有个能让业务方真正点来点去的管理端。这一篇开始切到前端重点讲 antd pro v5 的初始化和各种设置。很多人会觉得前端配置没什么好讲的脚手架一拉改改菜单和标题不就完事了实际接手过项目的人都懂antd pro v5 的设置项远比你想象的多布局怎么定、菜单怎么跟路由联动、权限怎么控制、代理怎么配、请求层怎么跟后端语义对齐每一处都决定你后面开发是顺风顺水还是天天骂娘。这篇就是把我自己实操过程中摸索出来的设置经验完整梳理一遍适合正在用 antd pro v5 做后台管理、后端是 Java 响应式技术栈的开发者参考。1. 为什么前后端分离项目里antd pro v5 值得用先聊几句选型。其实做后台管理系统前端方案多得很但在我个人经验里antd pro v5 是当前综合成本最低的一个。它基于 React 和 Ant Design但更关键的是它把中后台项目最常见的需求都预设好了路由和菜单联动、国际化、权限控制、请求封装、多环境配置、主题切换这些东西如果你从零搭至少要花一到两周去磨而 antd pro v5 的模板把这些都做成了配置项你要做的第一件事是理解它怎么工作而不是重新发明轮子。它跟 Spring WebFlux 搭在一起最舒服的地方在于前端只关心 JSON。WebFlux 的 Mono 和 Flux 在浏览器层面最终体现为异步 JSON 响应前端不需要关心后端是同步还是响应式antd pro v5 的请求层天然支持 Promise 和异步处理两者正好对上。你甚至可以在后端接口还没写完的时候先用 antd pro v5 自带的 mock 机制把前端页面跑起来等后端就绪后再把请求切过去这种开发节奏对前后端并行推进非常友好。当然antd pro v5 也有让人头疼的地方它封装层级比较深很多东西如果你不去翻源码根本不知道从哪个配置入口改。这也就是我写这篇的核心原因把我踩过的、摸过的设置项都交代清楚让准备入坑的人少走弯路。2. 初始化设置三步拿到工程2.1 使用官方脚手架创建项目antd pro v5 推荐直接用官方脚手架初始化命令很简单npx create-umilatest执行后会有交互式提示选择 ant-design-pro 模板即可。如果对交互式命令不放心也可以直接指定名称但官方推荐用交互式方式因为可以顺带选择是否需要 Tailwind 等扩展。初始化完成后进入项目目录安装依赖我用的是 pnpmcd your-project-name pnpm install pnpm dev启动之后默认端口是 8000浏览器打开就能看到一套完整的后台管理系统模板。需要注意 Node 版本建议 16 以上太老的版本跑不动我实测在 Node 14 上会直接报依赖兼容性错误。2.2 先认清目录再动手改拿到工程第一件事不是急着改页面而是把目录结构过一遍。antd pro v5 的目录约定很明确搞清楚之后基本不用看文档也能摸到对应设置入口。config/全局配置文件目录config.ts是入口routes.ts管路由proxy.ts管代理defaultSettings.ts管默认布局参数。src/业务代码目录pages/放页面components/放公共组件services/放接口请求access.ts管权限逻辑app.tsx是运行时配置入口。.env环境变量文件主要用来区分不同构建环境。我个人习惯是先把config/defaultSettings.ts通读一遍因为里面每个字段都会直接反映在页面上改一遍就能建立起直觉认识然后再去看路由和权限。3. 全局布局设置把模板改成自己团队的样子3.1 defaultSettings 里的关键参数antd pro v5 的布局、主题、标题等设置核心都集中在config/defaultSettings.ts。刚拿到工程时里面的参数已经把大部分中后台的常见形态预设好了你要做的是调整成符合自己项目的形态。export default { title: 后台管理系统, layout: mix, navTheme: light, primaryColor: #1677ff, contentWidth: Fluid, fixedHeader: false, fixSiderbar: true, locale: zh-CN, };简单解释一下这几个参数对应什么title就是浏览器标签页和登录页左上角显示的项目名layout是导航整体布局side是侧边栏top是顶部导航mix是混合模式顶栏一级菜单、侧栏二级菜单navTheme控制导航栏的主题是亮色还是暗色primaryColor是全局主色改这一个值整个站点的按钮、链接、选中态都会跟着变contentWidth控制内容区域是固定宽度还是自适应中后台项目我一般选Fluid因为内部系统屏幕分辨率差别大自适应更实用。如果你想做全局暗色模式需要设置navTheme: realDark。这里有个坑我提一下antd pro v5 的模板在暗色模式下部分表格、表单的背景色需要额外适配如果你只是把navTheme改成realDark而页面组件没同步适配视觉上会有明显的割裂感白一块黑一块。处理方式是把暗色模式做成运行时切换而不是全局固定切换时动态修改 Ant Design 的主题算法这样组件库的颜色体系会整体跟着变。3.2 运行时设置与静态设置的区别配置项有些是静态的改完要重启 dev server 才生效比如路由文件routes.ts有些是运行时的页面里能动态改比如用户手动切换暗色模式。antd pro v5 把布局相关参数在运行时抽成了一个Settings对象存在全局状态里。初次上手可能会懵觉得为什么我在代码里改了变量页面没变化其实是因为运行时的设置优先级更高。实操中建议这样分工代码里defaultSettings.ts只维护“品牌层面”的配置比如主色、项目名、默认布局这些不允许用户随便改布局偏好类设置交给运行时比如用户是否固定侧栏、是否开启暗色模式这些保存在本地存储里页面刷新后能恢复用户上次的选择。两者边界清楚之后后续做“用户自定义布局”这种需求时会轻松很多不需要重构现有代码。4. 路由与菜单设置页面是如何挂到导航上的4.1 routes.ts 的基本结构与映射规则antd pro v5 最核心的约定就是路由配置即菜单配置。你不需要单独做一个菜单管理模块只需要在config/routes.ts里声明路由侧边栏菜单会自动生成。先看一个实际可用的配置片段export default [ { path: /, name: 首页, icon: HomeOutlined, component: ./Home, }, { path: /system, name: 系统管理, icon: SettingOutlined, routes: [ { path: /system/user, name: 用户管理, component: ./System/User, }, { path: /system/role, name: 角色管理, component: ./System/Role, }, ], }, ];这里的映射规则很直观path决定浏览器访问地址name决定菜单显示名称icon决定菜单图标component指向src/pages/下的页面文件路径写./System/User就对应src/pages/System/User.tsx。嵌套的routes数组对应二级菜单一级菜单不配置component只承担分组作用。有个细节提醒icon字段在 v5 里有两种写法一种是字符串形式如HomeOutlined另一种是组件形式直接在配置里引入图标组件。如果图标显示不出来大概率是字符串拼写跟图标名对不上去ant-design/icons里核对一下命名。4.2 菜单隐藏、排序与面包屑联动不是所有页面都应该出现在侧边栏。比如登录页、404 页、详情页这些不需要用户从菜单进入。控制方式是在路由配置上加hideInMenu: true{ path: /user/login, name: 登录, hideInMenu: true, component: ./User/Login, }菜单排序默认按路由数组的顺序但如果你用了国际化菜单项的顺序可能会因为 name 的 key 转换而被打乱这时可以在路由上显式加menuRender或者调整数组顺序来保证展示顺序符合预期。面包屑是跟着路由层级自动生成的嵌套层级越深面包屑越完整一般不需要额外配置只有当某个路由想从面包屑中隐藏时可以用hideInBreadcrumb: true控制。路径和组件对应关系是最容易出问题的点。如果你的页面文件实际存放在src/pages/User/List.tsx但路由写component: ./UserList运行时会出现页面空白并报找不到模块。开发时如果路由改了但页面没反应过来可以重启 dev server这个属于路由配置的静态特性不是缓存问题。4.3 登录态拦截与初始路由跳转后台管理系统默认都要做登录拦截。antd pro v5 里这一块的入口在src/app.tsx其中layout配置里的onPageChange是最常用的拦截位export const layout { onPageChange: () { const token localStorage.getItem(token); if (!token location.pathname ! /user/login) { history.push(/user/login); } }, };这段代码的意思是每次路由跳转前先检查本地有没有 token如果没有且用户访问的不是登录页就强制跳回登录页。这个逻辑看起来简单但它是整个后台系统的第一道安全闸门。要注意的是前端的拦截只能防君子不能防小人真正安全的判断必须以后端为准前端拦截的意义是提供好的用户体验让未登录用户第一时间被引导到登录页而不是看到一堆空白页面。5. 权限设置v5 的 Access 权限模型怎么用5.1 权限配置的三段式流程antd pro v5 的权限控制跟后端常见的 RBAC 模型很接近但实现方式完全是前端式的。整个体系由三段组成全局初始化状态、权限判断函数、路由上的权限标记。第一步在src/app.tsx里定义getInitialState登录后把当前用户的信息和权限标识拉取出来放进全局状态export async function getInitialState() { const token localStorage.getItem(token); if (token) { const currentUser await fetchCurrentUser(); return { currentUser, permissions: currentUser.permissions }; } return { currentUser: undefined, permissions: [] }; }第二步在src/access.ts里写权限判断逻辑返回一个对象对象里的每个字段对应一种权限判断结果export default function access(initialState: { permissions: string[] }) { const { permissions } initialState || {}; return { canAdmin: permissions?.includes(admin) || false, }; }第三步在路由配置上给受控页面打标记{ path: /system/user, name: 用户管理, component: ./System/User, access: canAdmin, }这样当canAdmin为false时用户访问这个路由会被引导到 403 页面菜单项也不会显示。这套机制的核心思路是集中管理权限判断逻辑页面组件里不用到处写 if else改权限规则时只动access.ts一处即可。5.2 按钮级权限与权限接口设计路由级权限只控制页面能不能看但实际业务里更常见的是“页面能看按钮不能点”。比如普通用户能看到用户列表但没有“新增用户”按钮。antd pro v5 在组件层提供了useAccess和Access组件import { Access, useAccess } from umi; const canAccess useAccess(); return ( Access accessible{canAccess.canAdmin} button新增用户/button /Access );这里要专门说一下权限接口设计。既然前端权限来自后端那么后端接口最好返回一个统一的权限标识数组比如[admin, user:list, user:create]前端拿到后直接跟路由和按钮的权限标记做比对。我在跟 WebFlux 后端对接时习惯把权限数据放在用户信息接口里一起返回而不是单独开一个权限查询接口减少前端一次请求也方便getInitialState一次性初始化完成。权限调整后前端没生效也是常见问题原因是getInitialState有缓存或者用户信息没刷新。开发调试时可以临时在getInitialState里写死返回权限来验证页面效果确认逻辑无误后再改回真实请求。6. 开发代理与多环境设置跟 WebFlux 后端联调的关键6.1 为什么必须配代理前端 dev server 默认跑在 8000 端口Spring WebFlux 后端我习惯跑在 8080 端口。浏览器直接访问 8000 端口的前端时请求http://localhost:8080/api/xxx会触发跨域浏览器会拦截响应。解决跨域的方式有很多种比较一劳永逸的是在开发环境配置代理让前端的/api请求在服务端转发到后端浏览器看起来是同源的就不会有跨域拦截的问题。antd pro v5 把代理配置独立成了config/proxy.ts默认长这样export default { dev: { /api: { target: http://localhost:8080, changeOrigin: true, }, }, };changeOrigin: true是为了让后端收到的请求头中的 Host 变成后端的地址避免个别后端框架做域名校验时出问题。配好之后前端请求/api/user/list实际会被转发到http://localhost:8080/api/user/list。6.2 多环境变量与 mock 开关开发、测试、生产环境的后端地址大概率不一样所以不能把代理地址写死。antd pro v5 通过.env文件里的UMI_ENV来区分环境然后在config/config.ts里读取这个变量做分支判断# .env UMI_ENVdev// config/config.ts export default defineConfig({ proxy: proxy[process.env.UMI_ENV || dev], });这样pnpm dev走本地后端pnpm build走线上后端都是通过UMI_ENV切换的。还有一个很容易被忽略的设置项是 mock。刚初始化工程时自带 mock 数据后端接口没写你也能点出页面数据来。但接了真实后端之后mock 会挡住真实请求让人误以为接口挂了。关闭方式有两种一种是在config.ts里设置mock: false另一种是利用环境变量只在开发环境开启 mock其他环境直接关掉。个人建议线上构建必须关闭 mock否则某些接口一直返回假数据排查起来非常痛苦。7. 请求层设置与后端接口语义对齐的关键7.1 request 封装与拦截器antd pro v5 的请求层基于umi的request封装我们一般会在src/utils/request.ts里做统一处理。这里有几个必须设置的项基础地址、超时时间、请求拦截器、响应拦截器。看看一个典型的配置import { request } from umi; import { message } from antd; const httpRequest request.extend({ timeout: 10000, errorConfig: { errorThrower: true, }, requestInterceptors: [ (url, options) { const token localStorage.getItem(token); if (token) { options.headers { ...options.headers, Authorization: Bearer ${token}, }; } return { url, options }; }, ], responseInterceptors: [ (response) { const code response.code; if (code 401) { history.push(/user/login); } return response; }, ], }); export default httpRequest;请求拦截器统一加 token这样页面业务代码里不需要每次手动携带鉴权头。响应拦截器里统一处理业务状态码特别是 401直接跳登录。这里有个重要原则拦截器只做通用逻辑不要写太多业务 if else否则后面变成了一个大杂烩别人接手根本不敢动。7.2 与 Spring WebFlux 响应结构对齐Spring WebFlux 后端接口如果返回的是统一响应结构比如{ code, message, data }前端请求层一定要对齐这个语义。举个具体例子后端接口返回{ code: 0, message: success, data: { list: [], total: 0 } }那前端请求层就应该在响应拦截器里先判codecode不为 0 就弹错误提示并抛出异常业务代码里拿到的永远是干净的data。这种约定统一以后页面里写请求代码会非常简洁不用每个页面都去判断一次响应状态。我在对接 WebFlux 后端时还额外注意了一点WebFlux 的Mono异步响应偶尔会出现延迟所以前端请求层的超时时间不宜设置太短本地开发建议 10 秒线上根据接口耗时特性再调整。7.3 服务层目录约定工程里src/services/目录用来统一放接口定义。页面组件不直接写请求地址而是调用服务层封装好的方法。比如用户管理接口// src/services/user.ts import httpRequest from /utils/request; export async function getUserList(params: { current: number; pageSize: number }) { return httpRequest(/api/user/list, { method: GET, params }); } export async function createUser(data: any) { return httpRequest(/api/user/create, { method: POST, data }); }这样做的收益是长远的后端接口地址变了只需要改服务层一个文件所有页面调用方不受影响接口复用时直接 import 服务方法不用到处复制请求代码。中后台项目的接口数量一般几十个起步没有这层封装后期维护成本会直线上升。8. 常见设置问题与排查实录这里整理一下我在实际搭建过程中遇到的典型问题按问题现象、原因、处理方式列出来方便直接对照排查。问题现象可能原因处理方式菜单不显示路由没配置 name 或 icon 不合法检查 routes.tsname 是菜单显示的前提页面空白但无报错component 路径与 pages 目录文件不匹配核对 routes.ts 中 component 路径重启 dev server代理不生效config/proxy.ts 环境名没匹配当前 UMI_ENV检查 .env 里的 UMI_ENV 与 proxy key 是否一致权限路由进不去access.ts 返回字段名与路由 access 字段不一致统一权限字段命名确保字符串完全一致接口一直返回假数据mock 未关闭或服务层地址仍走 mock 前置设置 mock: false确认请求地址非 /mock 前缀暗色模式样式错乱组件未适配暗色或 AntD 算法未同步切换运行时切换主题算法不用 navTheme 固定图标显示问号icon 字符串拼写错误对照 ant-design/icons 官方命名检查登录后不跳转onPageChange 里跳转逻辑被缓存确认 app.tsx 改动已生效检查 history 路径排查这类配置问题时最有效的手段是看浏览器 Network 面板和 Console 报错。代理配没配成功看 Network 里请求的实际地址是什么权限字段对不对看 initialState 在全局状态里的实际值。养成先看事实再猜原因的习惯大部分问题五分钟内都能定位。再补充几个我个人的经验。第一antd pro v5 是配置驱动的理解一个配置项最靠谱的方式是去 node_modules 里搜它的类型定义比看博客和文档更准确。第二不要一上来就大刀阔斧改模板先把默认工程跑起来、把菜单和路由的关系理清楚再逐步定制。第三接真实后端前必须把 mock、代理、环境变量这三件事彻底搞明白否则后面联调时你会被各种“鬼问题”折磨到怀疑人生。这个系列到这里前端基础架子算是立住了。下一篇可以开始写具体的业务页面比如列表页、表单页和 WebFlux 后端接口的联调实战。到时再把分页、搜索、状态切换这些后台管理高频操作怎么落地讲细一点。