后台管理系统这种东西，平时很多人都是拿开源模板改一改，真要自己从零搭一次，才发现里面全是细节。最近我把一个商城项目推进到后台管理阶段，从016到027连着一串子任务，核心都是围绕“怎么把后台管理系统的架子立起来”做文章。这篇直接把过程记录下来，从需求边界到技术选型，从工程结构到权限模型，再到实际踩过的坑，按我的思路完整走一遍。如果你正在做类似的电商项目，或者想搞明白一个管理后台背后的设计逻辑，这篇应该能帮你省不少时间。
1. 先搞清楚后台管理系统到底要管什么
1.1 一个商城后台最少要有的五个模块
很多人在搭后台时犯的最大的错误，不是技术没过关，而是根本没想清楚这个后台是为谁服务的、要管哪些业务。我一开始也踩过这个坑，想着先把页面做出来再说，结果做到一半发现需求一改，整个菜单和路由都要动。所以第一步不是写代码，而是把后台的功能边界画清楚。
对于商城类项目来说，后台管理系统至少要覆盖下面这五个模块：
| 模块 | 核心功能 | 备注 |
|---|---|---|
| 商品管理 | SPU/SKU管理、商品上下架、类目管理、品牌管理、属性规格 | 最重的模块，字段多、关联多 |
| 订单管理 | 订单列表、订单详情、发货、退款、售后处理 | 和支付状态强关联，需要留意状态机 |
| 用户管理 | 会员列表、等级管理、禁用/解禁、收货地址查看 | 一般不做注册入口，账号由后台创建或前台注册同步 |
| 营销管理 | 优惠券、满减活动、秒杀场次、首页广告位 | 灵活度高，最容易因需求变化返工 |
| 系统管理 | 管理员账号、角色、菜单权限、操作日志、字典管理 | 所有后台都必备，也是权限模型的核心载体 |
这五个模块里，系统管理往往是第一个要动手的，因为后续所有模块的菜单入口、按钮权限都要挂在系统管理上。换句话说，系统管理是后台的“地基”，地基没打好，后面加什么模块都会觉得别扭。
商品管理是数据模型最复杂的一个。一个商品不仅仅是“名称+价格+图片”，它背后还有品牌、类目、属性、规格、SKU、库存、上架状态等一系列字段。当时我的做法是先理顺SPU和SKU的关系：SPU是“商品”，SKU是“具体可销售的规格组合”，比如“红色/128G”就是一个SKU。这个逻辑如果没想清楚，后面的商品表设计会乱成一锅粥。
1.2 需求边界：哪些功能不该放进后台
后台管理系统天然有一种“什么都能干”的诱惑，但我的经验是，后台是管理工具，不是数据大屏，更不是业务前台。把不适合的功能塞进来，只会拖慢核心功能的开发节奏。
举几个典型的“不该放进来”的功能：
- 实时访问统计和流量趋势图：这些更适合放到独立的数据分析平台，或者用现成的埋点和可视化工具，不要在后台里另起炉灶。
- 给C端用户用的营销落地页：虽然也能在后台里配置，但页面渲染逻辑应该在前台完成，后台只负责维护数据源。
- 复杂的审批流：商城后台的订单退款可能涉及审批，但没必要做一个完整的可配置审批流引擎，先用简单的角色判断硬编码，等业务量起来再抽象也不迟。
定好边界之后，整个后台的工程结构就不会随意膨胀。我当时给自己定的原则是：后台只做数据的管理和维护，凡是面向用户展示的页面，一律放到前台项目里。
2. 技术选型为什么不走现成脚手架
2.1 前端选型：Vue 3 + Element Plus + Vite
后台管理系统的前端，我的选择比较固定：Vue 3 + Element Plus + Vite。这套组合在目前的社区活跃度、组件覆盖率和中文文档质量上都是第一梯队，几乎不太需要犹豫。
Element Plus 里像表格、表单、弹窗、树组件、分页这些后台高频组件都能直接满足需求。Vite 的开发服务器启动速度确实比 Webpack 快一个量级，对于后台这种频繁加减页面、改路由的项目，热更新体验直接决定了开发效率。
需要提醒的是，Vue 3 的生态和 Vue 2 不完全一样，很多老项目里的写法不能直接搬过来。比如 Vue 3 里组合式 API 和<script setup>的组合，配合 Element Plus 会更顺手。如果你是刚接触这个技术栈，建议直接开一个 Vite + Vue 3 的模板工程再引入 Element Plus，不要用老项目去改，反正后台不大，重开一个成本很低。
2.2 后端选型：Spring Boot + MyBatis Plus + JWT
后端框架我用了 Spring Boot 2.7 + MyBatis Plus + JWT。选 MyBatis Plus 而不是 JPA，原因很实际：管理后台里有大量列表查询、分页、条件筛选需求，MyBatis Plus 的Page和QueryWrapper用起来，比 JPA 的 Specification 要直观很多，尤其是写多表关联查询时，MyBatis XML 的掌控力更强。
JWT 和 Session 的选择上，我做了一个简单的对比：
| 方案 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| Session | 服务端可主动失效，状态明确 | 集群环境要共享Session，需要额外方案 | 传统单体后台 |
| JWT | 无状态，扩展方便，天然适配微服务和前后端分离 | Token失效难处理，签名密钥要保管好 | 微服务架构下的管理后台 |
考虑到商城项目通常是微服务架构，后续还会有多个服务间调用，JWT 的无状态特性显然更合适。实际项目里，我给 Token 设置了 2 小时的过期时间，同时在每次请求时校验签名，基本可以平衡安全和体验。
需要说明的是，Spring Boot 我建议用 2.x 而不是 3.x，因为 3.x 刚推出来时一堆中间件的兼容性需要处理，管理后台这种项目没有追逐最新的必要。稳定能跑，比版本新更重要。这个观点可能有点保守，但后台上线后你基本不会频繁升级框架版本。
2.3 接口文档与联调工具的落地
前端和后端并行开发，接口文档如果没有统一到一处，后面联调就是一场灾难。
我的做法是在后端服务里集成了 Knife4j（Swagger 的增强版），接口定义好之后，前端直接对着文档联调，省掉大量“这个字段叫什么”“这个参数类型是什么”的来回沟通。
Knife4j 配合 Spring Boot 的集成方式很简单：引入knife4j-openapi2-spring-boot-starter依赖，然后在配置里指定扫描的包路径，启动后访问/doc.html就能看到每个接口的请求参数、响应结构和示例数据。
还值得一提的是，接口文档不能只在联调期有用。等项目上了线，运营的同事偶尔也要查某个接口的字段含义，这时候一份维护良好的接口文档就是团队资产。
3. 前端工程搭建的几个关键决策
3.1 路由和菜单的设计思路
前端工程搭起来之后，第一个核心决策就是路由怎么组织。我的方案很简单：静态路由 + 动态路由结合。
静态路由只保留三类页面：登录页、404页、无权限页。其余所有业务页面都做成动态路由，由后端根据当前登录用户的菜单权限返回，前端拿到菜单树后动态生成路由规则。
这样做的好处是，菜单的增删改完全由后端控制，前端不需要在代码里硬编码菜单项。运营人员想在某个菜单下加一个子页面，只要在系统管理的菜单维护页面里配置好路由路径和组件路径即可。
前端目录结构我大致是这样组织的：
src/ ├── api/ # 按模块拆分的接口请求 ├── assets/ # 静态资源 ├── components/ # 通用组件 ├── layout/ # 后台整体布局（侧边栏+顶栏+主内容区） ├── router/ # 路由配置 ├── store/ # 全局状态 ├── styles/ # 全局样式 ├── utils/ # 工具函数（含axios封装） └── views/ # 页面组件这个结构按“技术层”而不是“业务层”来划分，是小团队比较适用的方式。当业务模块多了之后，再考虑按模块拆分子目录也不迟。
3.2 登录态管理与 axios 封装
登录态管理是后台体验的底线。如果刷新页面就掉登录，这系统基本没法用。
我的方案是：登录成功后，把 JWT Token 存到localStorage，同时把用户基本信息存到 Pinia/Vuex 中，用于页面展示。每次请求前，从localStorage取出 Token，放到请求头Authorization字段中。
axios 封装是实现这个流程的关键。下面是我在实际项目里用的简化版本：
import axios from 'axios' import { ElMessage } from 'element-plus' import router from '@/router' const service = axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL || '/api', timeout: 10000 }) // 请求拦截器：附加 Token service.interceptors.request.use( (config) => { const token = localStorage.getItem('admin_token') if (token) { config.headers.Authorization = `Bearer ${token}` } return config }, (error) => Promise.reject(error) ) // 响应拦截器：统一处理业务码和 HTTP 状态码 service.interceptors.response.use( (response) => { const res = response.data // 约定后端返回结构为 { code, message, data } if (res.code !== 200) { ElMessage.error(res.message || '请求失败') return Promise.reject(new Error(res.message)) } return res }, (error) => { if (error.response?.status === 401) { localStorage.removeItem('admin_token') router.push('/login') } else { ElMessage.error(error.response?.data?.message || '网络异常') } return Promise.reject(error) } ) export default service这段代码里有两个细节值得注意。第一，后端返回结构统一成{ code, message, data }，前端只关心code是否为 200，这样处理逻辑就非常统一。第二，401 状态码代表 Token 已失效，此时直接清理本地状态并跳回登录页，避免用户在失效状态下继续误操作。
3.3 动态菜单的实现细节
动态菜单的难点不在后端，而在前端怎么渲染。后端返回的是一棵菜单树，前端要把它渲染成侧边栏的多级菜单。
Element Plus 的el-menu组件本身支持多级菜单，配合el-sub-menu和el-menu-item就能实现递归结构。但这里的坑在于：el-sub-menu的index属性要求是唯一字符串，一旦菜单层级深了，手工写死很痛苦。
我的做法是写一个递归菜单组件：
<template> <template v-for="item in menus" :key="item.id"> <!-- 有子菜单 --> <el-sub-menu v-if="item.children && item.children.length > 0" :index="item.path"> <template #title> <span>{{ item.name }}</span> </template> <menu-item :menus="item.children" /> </el-sub-menu> <!-- 叶子菜单 --> <el-menu-item v-else :index="item.path" @click="handleMenuClick(item)"> <span>{{ item.name }}</span> </el-menu-item> </template> </template>递归组件虽然简单，但一定要注意组件自身的 name 要写正确，否则无限递归调用会直接导致页面崩溃。我在第一次写的时候就没给递归组件设置name，结果打开菜单页面浏览器直接卡死。这种错误不算难排查，但确实很浪费时间。
动态路由的生成也和菜单数据强相关。后端返回的菜单树里包含component字段，比如system/user，前端把这串字符串映射到import的路径，再调用路由实例的addRoute方法动态注册。
4. 后端服务搭建与核心表设计
4.1 服务工程怎么切模块
后端服务我没有拆成一个个独立的微服务，而是用单工程 + 模块化的方式组织。对于后台管理系统来说，一开始就拆微服务是过度设计。一个后台服务的开发节奏很快，拆开之后光是服务间调用和部署就会浪费不少时间。
工程内部分层是标准的 Controller-Service-Mapper 三层，额外加了 DTO 用于参数接收和 VO 用于响应返回。Entity 对应数据库表，但不直接暴露给前端接口。这样做的好处是，数据库字段发生变更时，DTO/VO 可以保持不变，对前端的接口稳定性更友好。
目录结构大致如下：
src/main/java/com/project/admin/ ├── controller/ # 接口层 ├── service/ # 业务逻辑层 ├── mapper/ # 数据访问层 ├── entity/ # 数据库映射实体 ├── dto/ # 接收前端参数 ├── vo/ # 返回前端数据 ├── config/ # 配置类（安全、跨域等） └── utils/ # 工具类4.2 用户、角色、菜单的表关系
系统管理模块的后端核心，是我认为整个后台最值得提前规划的部分：权限模型。我采用的是标准的 RBAC（基于角色的访问控制）模型，一共五张核心表：用户表、角色表、菜单表、用户角色关联表、角色菜单关联表。
这五张表的关系可以用一句话概括：用户属于角色，角色拥有菜单权限。菜单表里的数据既用于渲染侧边栏，也用于控制接口访问权限。
建表的 SQL 核心部分大致是：
-- 用户表 CREATE TABLE `sys_user` ( `id` bigint NOT NULL AUTO_INCREMENT, `username` varchar(64) NOT NULL COMMENT '登录名', `password` varchar(128) NOT NULL COMMENT 'BCrypt加密后的密码', `nickname` varchar(64) DEFAULT NULL, `status` tinyint DEFAULT '1' COMMENT '1启用，0禁用', `create_time` datetime DEFAULT NULL, PRIMARY KEY (`id`), UNIQUE KEY `uk_username` (`username`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; -- 角色表 CREATE TABLE `sys_role` ( `id` bigint NOT NULL AUTO_INCREMENT, `role_name` varchar(64) NOT NULL COMMENT '角色名称', `role_code` varchar(64) NOT NULL COMMENT '角色编码', `remark` varchar(255) DEFAULT NULL, PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; -- 菜单表 CREATE TABLE `sys_menu` ( `id` bigint NOT NULL AUTO_INCREMENT, `parent_id` bigint DEFAULT '0' COMMENT '父菜单ID', `name` varchar(64) NOT NULL COMMENT '菜单名称', `path` varchar(128) DEFAULT NULL COMMENT '路由地址', `component` varchar(128) DEFAULT NULL COMMENT '前端组件路径', `icon` varchar(64) DEFAULT NULL, `sort` int DEFAULT '0', `type` tinyint DEFAULT '1' COMMENT '1目录，2菜单，3按钮', PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;用户表里的密码字段，用的是 BCrypt 加密而不是 MD5。MD5 虽然大家都很熟，但它在密码存储场景下已经不够安全了，BCrypt 加盐后即使两个用户密码相同，密文也是不同的，这才是正确的姿势。
菜单表里type字段是个容易被忽略的细节。我不仅存了目录和菜单，还存按钮级别的权限。比如“用户管理”菜单下面还有“新增用户”“编辑”“删除”这三个按钮，每个按钮也是一条菜单记录，只是类型为 3。这样就能实现按钮级别的权限控制，而不仅仅是页面级别的跳转控制。
4.3 验证码和登录接口的实现
登录接口是整个后台服务的第一个核心接口，也是安全性的第一道防线。我实现了图形验证码和账号密码登录两个环节。
验证码生成用的是 Hutool 的工具类，生成后的答案存在服务端缓存中（本地用的是 Caffeine，小规模够用），同时把uuid作为 key 返回给前端。前端提交登录请求时，带上uuid + 验证码输入值，后端先校验验证码是否正确，再检查用户名密码。
登录成功后的处理流程是：
- 根据用户名查询用户信息，校验密码（BCrypt 匹配）
- 查询该用户拥有的角色
- 根据角色查询对应的菜单权限集合
- 用 JWT 生成 Token，把用户 ID 和用户名放进 token 的 payload 中
- 返回 Token 和用户基本信息给前端
整个过程没有复杂的地方，但有一个顺序问题需要注意：验证码校验一定要放在用户名密码校验之前。原因很简单，验证码的目的是防止暴力破解。如果你先校验用户名密码，再校验验证码，恶意请求依然可以通过不断尝试账号密码来绕过验证码的保护。
5. 网关接入与管理服务的路由
5.1 管理后台为什么要走网关
如果商城项目是单体架构，后台管理服务直接暴露端口给前端就行。但我们的项目已经在往微服务方向演进，服务层拆分了商品服务、订单服务、用户服务等多个模块，所以统一入口必须在网关层解决。
我用的网关是 Spring Cloud Gateway。网关做了三件核心事情：
- 统一鉴权：在网关层校验所有请求的 JWT Token，不合法就直接拦截，业务服务不需要在每个接口里重复写鉴权逻辑
- 路由转发：根据请求路径的前缀，转发到对应的服务，比如
/api/system/**转发到后台管理服务 - 跨域处理：在前端域名和后端服务域名不一致时，网关统一加 CORS 响应头
5.2 网关路由配置和跨域处理
网关路由配置的样例大致是这样：
spring: cloud: gateway: routes: - id: admin-service uri: lb://admin-service predicates: - Path=/api/admin/** filters: - StripPrefix=2StripPrefix=2的意思是去除路径前两段。比如前端请求/api/admin/system/user/list，到达后台服务时，路径会变成/system/user/list，这样后端接口定义里不需要额外加一层公共前缀，更清爽。
跨域处理是网关配置里最容易出问题的地方。很多人在后端服务里配了一遍 CORS，又在网关里配了一遍，结果两边头信息冲突，浏览器直接报错。我的建议是，如果用了网关，跨域配置只在网关做，后端管理服务里直接屏蔽掉 Spring MVC 自带的跨域配置。
网关跨域的常规做法是配置CorsWebFilter，放行前端域名。如果你在本地调试，前端用 Vite 的代理也能绕开跨域问题，但要记得上线后网关的跨域配置要覆盖真实域名。
6. 搭建过程中踩过的坑（实录版）
6.1 跨域问题排查了半天
第一次跑通前后端联调时，我在浏览器里看到了那个熟悉又令人沮丧的提示：“请求被跨域策略拦截”。
当时的架构是前端 localhost:5173 直连后端 localhost:8080，跨域必然存在。我第一反应是在后端服务里加一个@CrossOrigin注解，结果接口通了，但网关转发之后的请求又出现了新的跨域问题。来回折腾了半天才意识到，问题出在多个环节同时处理跨域，而且处理方式不一致。
最终的解决方案就是上面说的——只在网关层统一处理，后端服务全部不加跨域配置。这个经验后来也分享给了团队里其他人：分布式架构下的跨域问题，90% 都是因为“每个服务都各自处理跨域”造成的，统一到一个入口处理才是根治的办法。
6.2 刷新页面 404 的问题
后台管理页面用的是 history 模式路由，部署到测试环境后，用户在某个管理页面刷新一下，直接 404。
原因很经典：前端路由是 history 模式，刷新时浏览器会把当前路径发到服务端，服务端找不到对应的资源就返回 404。但前端是一个 SPA，资源文件就在那，只是路径不对。
这个问题在 Nginx 里解决很简单，配置一个try_files：
location / { try_files $uri $uri/ /index.html; }这样刷新非首页路径时，Nginx 会回落到 index.html，前端再根据路由解析出正确的页面。这个配置看起来非常简单，但不熟悉 Nginx 配置的人很容易漏掉，我第一次部署时就漏了，导致测试环境的运营同事反复刷新报错，体验极差。
6.3 Element Plus 按需引入与图标注册
Element Plus 的组件和图标是分开的。组件用的是自动按需导入插件（unplugin-vue-components），图标却需要手动注册或者全局引入。
我刚集成的时候，业务代码里写了<el-table>、<el-form>，组件渲染正常，但一到侧边栏菜单，图标全都不显示。排查了很久才发现，el-icon的图标组件不会通过按需导入插件自动全局注册，需要手动在入口文件里注册需要使用的图标。
我的方案是把常用图标封装到一个文件里统一注册：
import { User, Setting, Goods, Order, ShoppingCart } from '@element-plus/icons-vue' const icons = { User, Setting, Goods, Order, ShoppingCart } export function registerIcons(app) { Object.entries(icons).forEach(([name, component]) => { app.component(name, component) }) }页面里用到的时候，直接名字当组件用就行。记住这句话：Element Plus 的组件可以自动按需引入，但图标必须自己注册，这能省下不少排查时间。
6.4 树形菜单递归组件的坑
递归菜单组件我在前面提到过，但是还有一个细节没有讲透：当菜单树数据中间层存在异常时，比如某条菜单记录的parent_id指向了一个不存在的父级，前端递归组件会陷入死循环。
解决办法是在后端查询菜单树时，加一层数据完整性校验。当时我写了一个方法，先查询出所有启用状态的菜单，然后循环构建树结构时，把父级不存在的数据直接忽略，并记录到日志里。这样既避免前端崩溃，也方便后续排查脏数据。
菜单树的sort字段我建议从一开始就排好，否则菜单顺序会在更新后随意跳动。排序规则是：同一个父级下的菜单按 sort 升序排列，sort 相同按 id 升序。不要问我为什么强调这个，问就是运营同学已经为了菜单顺序找过我好几次了。
7. 这段开发过程中我积累的几点后端经验
后台管理系统搭完一轮之后，有些经验不是看看文档就能想明白，我觉得值得单独写在这里，给大家做个参考。
7.1 接口返回结构要稳定且前置约定
前后端联调时，最常见的返工原因就是接口返回结构前后不一致。有时候后端直接返回了裸数组，有时候又包了一层对象，前端处理起来就要不断写兼容逻辑。
我强烈建议在项目一开始就和前端同事约定好统一的返回结构：{ code: 200, message: "成功", data: ... }。分页数据放到data里，固定结构为{ total, records }。后面所有接口都按这个结构输出，不要再动。接口可以迭代，但外层结构不要变。
以我的实际经验，这个约定确定之后，前后端联调效率至少提升 30%。不然今天一个裸数组、明天一个对象，前端同学光是适配类型就得加班。
7.2 工具类的使用要克制
Hutool、Apache Commons 这些工具库在后台项目中非常常见，能极大地提高开发效率。但有一个度的问题：工具类的使用要克制，不要在一个项目里引入七八个功能重复的工具库。
我见过有的项目同时引入了两个 JSON 工具类，一会儿用这个解析，一会儿用那个序列化，遇到复杂嵌套对象时，行为还不一致，排查起来极其痛苦。我的建议是基础功能用 Hutool，JSON 处理用项目统一的 Jackson，避免把简单的事情变复杂。
7.3 日志规范不能含糊
开发阶段日志写得随随便便，上线以后查问题才后悔莫及。我在后台管理模块里，把操作日志单独做了一个切面，记录谁在什么时间调用了哪个接口、耗时多久、成功还是失败。这样运营和研发在排查问题时，能直接从操作日志定位到具体人、具体时间、具体数据，不再靠猜。
日志的重点不是越多越好，而是关键节点必须覆盖：登录成功与失败、订单状态变化、权限变更、删除操作，这些敏感动作一定要有记录。后台系统权限不小，责任也大，日志就是最后的“证人”。
7.4 不要迷信“大而全”的权限方案
权限控制做到 RBAC 级别已经能覆盖绝大多数后台系统的需求。像数据权限（比如这个管理员只能看某个部门的数据）、字段权限（某些字段不可见）这些高级能力，业务没有明确需求就不要提前做。
我当时也被各种“完整权限系统”的开源项目吸引了目光，最后冷静下来一想，团队现在的业务根本用不上那些复杂特性。RBAC + 按钮级别权限已经足够，把时间留在商品管理、订单管理这些真正影响业务的功能上，性价比高得多。过度设计从来不是体现能力的方式，恰到好处才是。
这套后台管理系统的骨架搭完，项目才有了真正“可以运营”的样子。商品的上下架、订单的发货退款、运营人员的账号分配，都有地方可以落地了。这段时间踩过的坑也让我更清楚一件事：后台的项目本身不太需要炫技，稳定、清晰、可维护，就是最好的设计。如果你也正卡在后台搭建的路上，希望这篇能让你少走几步弯路。
