Spring Boot与MyBatis Plus后台管理系统实战:权限设计与踩坑记录 做后台管理系统最怕什么我的答案很简单框架选型把简单的事情搞复杂。蓝鲸云是我们团队内部一个运营后台的项目代号需求非常典型——登录、用户权限、菜单管理、大量业务表的CRUD并且后续还要不断加新模块。当时我直接把技术栈定成了 Spring Boot MyBatis Plus没有用更重的微服务体系也没有用全手动拼SQL的原生MyBatis。事实证明这个决定让团队在六周内把系统从零推到上线后面迭代也稳得住。这篇文章就基于蓝鲸云这个后台项目把当时的选型思路、表结构设计、权限实现、以及实操中踩过的坑一起拆开讲讲。内容面向正在做后台管理系统、或者打算在 Spring Boot 里集成 MyBatis Plus 的开发者尤其适合那些“业务其实不复杂但配置和样板代码却一堆”的项目。你能从里面拿到一套可以直接抄作业的骨架思路也能避开我当年折腾过好几天的那些坑。1. 为什么选 Spring Boot MyBatis Plus而不是别的组合先说结论这个组合非常适合中小型后台管理系统。它不会替你解决所有业务问题但它能把你从繁琐的配置和重复的 CRUD 代码里捞出来让你把时间留给真正复杂的东西比如权限模型、数据权限、状态流转。1.1 Spring Boot 解决的是“接活成本”如果你经历过 Spring MVC XML 配置的时代应该对那一堆spring-mvc.xml、applicationContext.xml、各种Bean定义印象深刻。Spring Boot 把“约定优于配置”贯彻到底一个spring-boot-starter-web依赖加进去内嵌 Tomcat、自动装配、默认日志框架就全有了。蓝鲸云项目启动阶段我只维护一个application.yml数据库连接、Redis、MyBatis Plus、日志级别全在里面改动即重启不用再翻 XML 找配置项。这里有个容易被低估的点Spring Boot 的 Starter 机制不光是省了配置它把依赖版本也一起管住了。只要父工程指定好 Spring Boot 版本下面各个组件的兼容性基本不会翻车这对团队协作尤其重要新同事拉下代码就能跑不用花一上午装环境。1.2 MyBatis Plus 相比原生 MyBatis 和 JPA 的取舍后台管理系统里的业务表八成以上是标准 CRUD列表查询、详情、新增、编辑、删除。原生 MyBatis 需要你给每张表写 Mapper 接口、XML 映射文件、动态 SQL一张表至少几十行代码十几张表下来就非常枯燥。MyBatis Plus 的核心价值在于BaseMapper直接把这套 CRUD 给你了连insert、updateById、selectList、deleteById都是现成的单表操作用不着写一行 SQL。有人会问那直接用 JPA 不是更省JPA 在简单场景确实省但一碰到多表关联、复杂动态条件查询要么写Query要么写 Specification可读性和可控性都比 MyBatis Plus 的LambdaQueryWrapper差一截。蓝鲸云后台有个订单列表筛选条件有状态、时间段、关键字、渠道来源用户勾什么就查什么我用LambdaQueryWrapper加几个if判断就能拼出来SQL 还能自己在日志里看到出了问题好排查。这一点在团队协作里非常重要因为运营后台的查询条件永远在变你今天不知道明天产品会加什么筛选项所以“代码一眼能看懂”比“写过一次爽到底”重要得多。再说说为什么不引入更重的方案。蓝鲸云整个系统体量就是几十张表、日均几千次访问分库分表、微服务、消息队列这些在这个阶段都是负担而不是收益。技术选型逻辑很简单够用、好维护、出问题时团队成员都能快速接手。2. 整体架构与表设计先画好漏斗再写代码写后台管理系统最容易犯的错就是一上来就写登录登录写完再写用户表然后想到哪补到哪最后权限模型和菜单表绕成一团。蓝鲸云项目一开始我就把架构分层和 RBAC 权限模型定下来了后面所有业务都在这套骨架上长。2.1 工程分层与请求流转我用的是经典的四层结构Controller 层接收参数、Service 层处理业务逻辑、Mapper 层对接数据库、Entity 层映射表结构。额外加了两个对象VO 给前端返回数据DTO 接收前端参数。为什么不直接 Entity 一把梭因为后台表格往往需要“用户列表里带上角色名”“订单列表里带个用户名”你要是直接改 Entity 去冗余存这些字段表结构有一点变动就得跟着改数据库很被动。蓝鲸云的列表接口基本都用 VO 组装Entity 只做数据库映射职责切得干净。请求流转大概是前端请求过来被全局的认证拦截器拦一道验 token通过后进 Controller参数被 Spring 绑定如果校验失败会被全局异常处理器拦住返回。Service 里写业务逻辑需要查库就调 Mapper最后返回ResultT统一对象。这套流转里的几个核心类后面会单独展开。2.2 RBAC 权限模型与核心表设计蓝鲸云的权限模型就是最经典的 RBAC用户关联角色角色关联权限菜单。为什么不做用户直接挂权限因为运营后台的用户是会流动的今天做运营明天可能兼着客服如果直接给用户挂权限每次调岗都要改权限IT 支持得疯掉。中间加一层角色调岗只需要换角色权限全部跟着走。核心表我列出五张sys_user用户表字段有id、username、password、nickname、status、del_flag、create_time、update_time、versionsys_role角色表id、role_code、role_name、statussys_menu菜单权限表id、parent_id、menu_name、path、component、perms、menu_type、sortsys_user_role用户角色关联表id、user_id、role_idsys_role_menu角色菜单关联表id、role_id、menu_id这套结构跑起来后有个很舒服的好处前端菜单树直接查sys_menu按parent_id组装就行后端做接口权限拦截时也只需查角色关联的权限标识集合。比如某个接口要求system:user:add权限用户登录后把角色对应的perms集合缓存进 Redis每次请求只要判断当前用户有没有这个权限标识。很多人把菜单管理和权限管理混在一起蓝鲸云通过menu_type字段区分目录、菜单、按钮三类。按钮也能挂在菜单底下每个按钮配一个权限标识这样前端可以根据后端返回的权限集合决定要不要渲染新增按钮后端也真的会在接口层校验而不是只靠前端隐藏。2.3 逻辑删除与乐观锁数据删除这块我坚持用逻辑删除不用物理删。原因很简单后台管理系统的数据往往有审计和追溯需求用户操作记录、订单流水、角色变更这些一旦物理删除后面追责和数据分析都无从谈起。del_flag字段设个默认值 0删除时更新为 1MyBatis Plus 的TableLogic注解一标查询时自动拼上del_flag 0删除时变成UPDATE不需要你每条 SQL 手动带条件。乐观锁是另一个容易被忽略的点。蓝鲸云的用户编辑功能遇到过并发覆盖的投诉两个管理员同时改一个用户资料后来保存的会覆盖先保存的。解决方案就是加version字段配合Version注解和 MyBatis Plus 的乐观锁插件更新时自动带上version 旧版本号更新成功才把版本号加一。这里有个细节乐观锁插件在更新时如果set了version字段会自己处理但如果你手写 SQL一定要在where条件里带上旧版本号否则等于没锁。3. 核心实现细节拆解从依赖到登录鉴权这一部分我按蓝鲸云项目里真正写代码的顺序来先把基础设施搭好再做鉴权最后才让业务表跑起来。每段代码都是从项目里抽出来的简化版但思路是一样的。3.1 统一返回体与全局异常处理后台管理系统的接口风格统一非常重要否则前端同事会被你逼疯一个接口返回{ code: 200, data: [] }另一个返回{ success: true, result: [] }再一个干脆只返回一个数组。蓝鲸云的ResultT很简单三个字段code、message、data配一个静态方法success(data)和一个fail(code, message)。public class ResultT { private int code; private String message; private T data; public static T ResultT success(T data) { ResultT result new Result(); result.code 200; result.message success; result.data data; return result; } public static T ResultT fail(int code, String message) { ResultT result new Result(); result.code code; result.message message; return result; } // getter / setter 略 }全局异常处理器是另外半个关键点。如果没有它代码里任何地方抛个NullPointerException前端拿到的就是 Spring 默认错误页既丑又没信息量。蓝鲸云在GlobalExceptionHandler里拦截了三类异常自定义的业务异常BusinessException、参数校验异常MethodArgumentNotValidException、以及兜底的Exception。业务异常返回业务错误码参数校验把字段错误拼成可读信息兜底异常记日志再返回“系统开小差”。注意兜底异常不要直接把异常信息返回给前端那会把 SQL 细节甚至表结构泄露出去。日志里记录详细的异常栈返回给前端的话术统一一点既安全又体面。3.2 用 MyBatis Plus 实现动态条件查询没有 MyBatis Plus 之前动态条件查询是 XML 里写if标签一个列表页查十几个条件XML 能写一百多行。蓝鲸云的订单列表接口直接用LambdaQueryWrapper代码就像这样Override public IPageOrderVO pageOrder(OrderQueryDTO query) { LambdaQueryWrapperOrder wrapper Wrappers.lambdaQuery(); wrapper.eq(StringUtils.hasText(query.getOrderNo()), Order::getOrderNo, query.getOrderNo()) .eq(query.getStatus() ! null, Order::getStatus, query.getStatus()) .ge(query.getStartTime() ! null, Order::getCreateTime, query.getStartTime()) .le(query.getEndTime() ! null, Order::getCreateTime, query.getEndTime()) .like(StringUtils.hasText(query.getCustomerName()), Order::getCustomerName, query.getCustomerName()) .orderByDesc(Order::getCreateTime); // 分页查询 IPageOrder page orderMapper.selectPage(new Page(query.getPageNum(), query.getPageSize()), wrapper); // 转 VO略 return PageResult.of(page); }每个条件前面都有个布尔判断前端不传这个参数就直接跳过这个条件。这样做有两个好处一是代码里每个条件对应一个前端筛选字段改动直观二是不用担心 SQL 注入因为LambdaQueryWrapper用的是参数绑定。实际用下来新来的同事看两眼就能上手加搜索条件效率提升非常明显。3.3 分页查询与 PaginationInnerInterceptorMyBatis Plus 的分页不能光靠Page参数需要在配置类里注册MybatisPlusInterceptor并添加PaginationInnerInterceptor。蓝鲸云项目里还顺带加了一个乐观锁的内置拦截器这个插件是加在多分页插件之前的两者互不影响。Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor()); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }分页插件用起来以后有个点必须说selectPage方法的第一个参数是Page对象current从 1 开始size每页条数。很多刚接触的人把 Page 对象放到 Service 里构造完就传进去结果发现第一次还行第二页开始数据重复。原因多半是前端传的pageNum没被正确接收建议所有分页查询的入参都统一叫pageNum和pageSize由前端统一传后端转成 Page 时减一或直接用千万别一会在 Controller 里减一一会在 Service 里又减一这种坑调试起来非常头大。3.4 登录鉴权与权限注解JWT Redis HandlerInterceptor蓝鲸云没有引入 Spring Security因为需求只需要“登录后访问特定接口要求特定权限”用 Spring Boot 自带的 HandlerInterceptor 完全可以覆盖而且没那么重的概念负担。登录成功后后端生成 JWT把 token 和用户权限集合同时写入 Redistoken 作为 key 存下用户信息。JWT 本身包含用户 ID、过期时间Redis 里再存一份主要是为了支持主动失效比如改密码、踢人下线光靠 JWT 本身是做不到这一点的。登录接口的核心逻辑PostMapping(/login) public ResultString login(RequestBody LoginDTO dto) { // 1. 校验用户名密码 User user userService.getByUsername(dto.getUsername()); if (user null || !passwordEncoder.matches(dto.getPassword(), user.getPassword())) { throw new BusinessException(用户名或密码错误); } if (user.getStatus() ! 1) { throw new BusinessException(账号已被禁用); } // 2. 生成 JWT String token jwtUtil.createToken(user.getId(), user.getUsername()); // 3. 查询用户权限集合并写入 Redis设置过期时间 SetString perms userService.getPermsByUserId(user.getId()); redisService.set(RedisKey.TOKEN_PREFIX user.getId(), token, jwtUtil.getExpireSeconds()); redisService.set(RedisKey.PERMS_PREFIX user.getId(), perms, jwtUtil.getExpireSeconds()); return Result.success(token); }权限拦截器做的事情很简单从请求头里拿Authorization解析 JWT把用户信息放进ThreadLocal再检查当前访问的接口是不是标了权限注解如果标了就拿用户 ID 去 Redis 取权限集合判断注解里的权限标识是否在集合里。这里用的是自定义RequiresPermission注解例如RequiresPermission(system:user:add) PostMapping(/user) public ResultVoid addUser(RequestBody UserDTO dto) { userService.addUser(dto); return Result.success(null); }这个方案比 Spring Security 的PreAuthorize模型简单得多特别适合团队里没有专门安全专家的场景。等以后系统体量大了需要动态按部门做数据权限再往拦截器里加规则也来得及。很多人一上来就上 Spring Security配置一堆却只用了最简单的表单登录反而把团队折腾得够呛。3.5 代码生成器让 CRUD 不再无脑蓝鲸云后台管理系统的业务模块有几十个每新增一个模块都要手写 Entity、Mapper、Service、Controller体力劳动太重。我直接用 MyBatis Plus 的代码生成器把几十张表的基础代码一次性生成出来再根据业务手动调整效率提升是秒级的。生成器分五大步配置数据源、配置全局策略作者名、开启 Swagger、配置包名、配置表名、执行生成。全局策略里建议把“RestController 风格”“逻辑删除字段”“乐观锁字段”都打开这样生成的代码会直接带好注解。生成之后也不是无脑直接用我会手动检查这几个点自动生成的 Entity 字段类型是否正确比如LocalDateTime是否被正确映射是否每个表都有合理的唯一索引和查询索引代码生成器不管索引生成的 Mapper 只是空接口有的复杂统计 SQL 需要自己补Service 层需要加的事务注解和业务校验逻辑生成器也不会替你写。说白了代码生成器负责“标准件”业务层负责“非标件”两者配合才舒服。如果只靠生成器不做任何手动改造项目会变成一堆没有灵魂的自动代码后面改起来更费劲。4. 实操中的坑与排查技巧实录写框架这东西网上教程一大把真正值钱的是踩坑记录。蓝鲸云项目开发期和上线初期我至少踩过下面这些坑每一个都花了不少时间排查写出来帮你避一避。4.1 下划线字段与驼峰映射的坑数据库字段习惯用create_time、update_timeJava 属性是createTime。MyBatis Plus 默认开启了驼峰映射但如果你用的数据库连接参数没设置好或者某些字段带了特殊前缀就会出现“查出来为 null”的诡异问题。我的建议是application.yml里明确开启map-underscore-to-camel-case: true同时数据库字段命名严格采用小写下划线Java 属性严格采用驼峰两边一致不要出现createTime对create_time又对createTime这种混乱。还有一个连带问题LocalDateTime序列化。默认 Jackson 会把LocalDateTime序列化成一长串数组前端完全没法用。蓝鲸云里统一配置了 Jackson 的JavaTimeModule和yyyy-MM-dd HH:mm:ss格式全局生效省得每个字段加注解。4.2 分页插件失效一查就是全表最典型的一次某个列表接口数据量一大直接超时。排查后发现问题出在Page没生效后台日志里打印的 SQL 完全没有LIMIT是整表查询后内存里假分页。原因是一个同事在写某个查询方法时自己手写了一条 SQL 放在 XML 里但 Mapper 方法没有把Page参数传进去。注意MyBatis Plus 的分页拦截器是靠解析 Mapper 方法参数里的IPage对象来拦截 SQL 的如果方法签名里没带IPage它就没法帮你加分页。检查方法签名时一定要确认类似IPageOrder selectPage(Page? page, ...)里的IPage出现在参数里。4.3 逻辑删除与唯一索引冲突这坑把我折腾得够惨。用户表里username建了唯一索引逻辑删除用户后再新建一个同名的用户直接数据库报唯一索引冲突。物理删除年代没这问题逻辑删除后旧数据还躺在表里唯一索引自然不会放过你。常见的解法有三种一是把del_flag加进唯一索引里比如(username, del_flag)逻辑删除时把del_flag设成主键 ID 或当前时间戳保证唯一性二是单独建一个逻辑删除位比如deleted_at为 NULL 表示未删除删除时写入删除时间三是干脆允许用户名重复列表里过滤掉已删除的。蓝鲸云最后选的是方案一把del_flag从 0/1 改成逻辑删除时写入主键值既保留唯一约束又不会冲突。4.4 事务失效的几种情况蓝鲸云上线前遇到过比“该加事务没加”更隐蔽的问题明明在方法上标了Transactional但异常发生后数据没有回滚。排查下来原因主要这几类方法不是publicSpring 的 AOP 代理管不到同类内部直接调用比如这个类的方法 A 调方法 BB 标了事务注解但 A 调用 B 时走的是this不是代理对象注解直接失效方法内把异常try...catch吃掉事务一看没有异常往外抛自然不回滚多个线程同时跑在同一个事务方法里事务只绑定了主线程的数据库连接子线程的操作不在事务范围内。排查这类问题建议全局日志里把事务 SQL 和异常日志打开看事务边界内真实执行的 SQL 数量基本就能定位。4.5 慢 SQL 排查心得后台管理系统数据量上来以后慢 SQL 是迟早的事。蓝鲸云在测试环境直接开了 MyBatis Plus SQL 日志打印出完整 SQL 后丢进数据库执行计划里看走没走索引。最常见的问题是查询条件字段建了索引但表里用del_flag 0做全局过滤导致索引失效或者like %关键词%前缀模糊查询导致索引失效。这里建议所有列表查询字段的索引设计要和实际筛选项对齐光有索引却不匹配查询条件等于白建。另外分页查询用offset太深也会慢蓝鲸云的订单列表翻到几十万条以后明显卡顿后来改成用游标分页或者限定最大翻页范围才缓解。这是个典型优化方向具体取舍要看业务允不允许超过最大页数。4.6 常见问题速查表问题现象常见原因处理办法查询结果全是 null驼峰映射没开或字段命名不一致开启map-underscore-to-camel-case规范命名分页查询没生效全部数据返回Mapper 方法参数里没有IPage方法签名补上Page参数逻辑删除后新增同唯一字段记录失败唯一索引仍然约束旧记录唯一索引引入逻辑删除位事务没回滚自调用、非 public、异常被吞调整调用方式异常抛给代理登录后权限不生效接口 403Redis 权限未刷新或 token 过期检查 Redis 键和过期时间代码生成器生成的实体时间字段不对数据库时间类型映射选择错误手动调整字段类型和格式化配置排查这类问题的通用思路其实就一句话先看日志再拆解链路最后看框架源码。不要一上来就怀疑框架有 bug绝大多数问题都出在用法上。我个人在实际操作中的体会是蓝鲸云这个后台从第一行代码到上线真正写业务的时间其实只占一半剩下全花在权限模型、数据一致性这类“看不见的骨架”上。如果让我重来一次我会把第一个星期全部花在表结构和权限模型设计上而不是急着让页面先跑起来。还有一点想特别提醒技术选型永远服务于团队和业务Spring Boot MyBatis Plus 是很好的默认选项但不代表所有后台管理系统都应该这么搭。你团队如果全是 JPA 熟手那用 JPA 也不是不行最怕的是为了技术时髦而选型然后让团队花两周去补框架知识。希望这篇文章能帮你少踩几个坑。如果你以后也在维护类似的 Spring Boot 后台项目遇到有意思的坑欢迎回来聊聊我这边还有不少实战记录等着整理。