企业官网建设流程全解析

一套基于 SpringBoot 与 Vue 的前后端分离管理系统，配上 MyBatis 做持久层、MySQL 做数据存储，这个技术组合在国内的中小型项目里几乎是"标配"。标题里提到的 BB 平台管理系统，从命名习惯来看，大概率是一个面向教学辅助、内容运营或社区协作类的综合管理后台，涵盖用户管理、内容管理、权限控制、数据统计等常见模块。我接触过不少类似结构的项目，也帮人做过二次开发和部署排障，深知一套"能跑起来"的源码和一套"能改得动、扛得住"的工程之间，差的是大量文档里不会写的细节。这篇内容就围绕这套技术栈，把整体设计思路、核心模块实现、实操部署流程和踩坑经验完整拆一遍，适合正在做课程设计、毕业项目、企业内部工具，或者想系统学习前后端分离开发的朋友参考。不管你是刚接触 SpringBoot 的新手，还是已经能写 CRUD 但想搞懂工程化组织的老手，下面这些内容都能直接拿去用。

1. 整体架构设计与技术选型拆解

1.1 为什么是 SpringBoot + Vue 这套组合

先说说选型逻辑。管理系统这类需求，本质上是"数据增删改查 + 权限 + 报表"的组合，业务复杂度不高但对开发效率要求极高。SpringBoot 的价值在于把 Spring 生态里那些繁琐的 XML 配置全部收敛成注解和 starter 依赖，一个spring-boot-starter-web就能把内嵌 Tomcat、SpringMVC、Jackson 序列化全部拉起来，省掉大量环境搭建时间。Vue 这边，响应式数据绑定加上组件化开发，让管理后台里大量的表格、表单、弹窗能够高效复用，配合 Element UI 或 Ant Design Vue 这类组件库，一个标准列表页半小时就能搭出来。

前后端分离的核心收益是职责清晰。后端只负责提供 RESTful 接口和业务逻辑，前端只负责渲染和交互，两边通过 JSON 通信。这样做的好处是前端可以独立部署到静态服务器，后端可以独立扩容，团队里前后端人员也能并行开发。代价是跨域问题、接口联调成本、鉴权方案要额外设计，这些后面会详细讲。

MyBatis 作为持久层，相比 JPA 的优势在于 SQL 完全可控。管理系统里经常有复杂的多表关联查询、动态条件拼接、分页统计，MyBatis 的 XML 映射和动态 SQL 标签处理起来更顺手，性能调优时也能直接看到最终执行的 SQL。MySQL 则是这类项目最务实的选择，社区资料多、运维成本低、中小数据量下性能足够。

1.2 分层结构与模块划分

一套能长期维护的项目，目录结构必须清晰。我习惯按这样的方式组织后端代码：

com.example.bbplatform ├── config // 全局配置：跨域、拦截器、MyBatis、Swagger ├── controller // 接口层，只做参数校验和调用 service ├── service // 业务逻辑层，接口与实现分离 │ └── impl ├── mapper // MyBatis 映射接口 ├── entity // 数据库实体 ├── dto // 数据传输对象，用于接口出入参 ├── vo // 视图对象，用于前端展示 ├── common // 通用类：统一返回、异常、常量、工具 └── interceptor // 登录拦截、权限校验

这里有个容易被忽视的点：entity、dto、vo 要分开。很多新手图省事，一个实体类从头用到尾，结果数据库字段一改，接口契约就崩了，前端跟着遭殃。DTO 负责接收前端参数（可以做校验注解），VO 负责返回给前端（可以裁剪敏感字段如密码），entity 只对应数据库表。三层分离虽然多写几个类，但后期改需求时能救命。

前端 Vue 项目则按视图和组件划分：

src ├── api // 所有接口请求封装 ├── views // 页面级组件 ├── components // 可复用组件 ├── router // 路由配置与守卫 ├── store // 状态管理 ├── utils // 请求封装、工具函数 └── assets // 静态资源

接口请求统一收口到api目录，好处是接口地址变更时只改一处，也方便统一加 loading、错误提示。

1.3 数据库设计的几个关键决策

管理系统的数据库设计，核心是把"用户—角色—权限"这条线理清楚。常见的 RBAC 模型需要五张表：用户表、角色表、权限（菜单）表，外加两张关联表。这里我建议权限表直接用树形结构存储菜单，用parent_id字段维护层级，前端渲染侧边栏时递归生成即可。

字段设计上有几个实操建议：主键统一用bigint自增或雪花 ID，避免业务字段做主键；所有表加create_time、update_time、deleted三个字段，其中deleted做逻辑删除，物理删除在生产环境是大忌；状态类字段用tinyint存枚举值并在代码里定义常量，别直接存中文。字符集统一utf8mb4，排序规则utf8mb4_general_ci，这样中文和特殊符号都不会出乱码。

2. 核心模块实现与关键细节

2.1 统一返回结构与全局异常处理

接口返回格式不统一是联调阶段最大的痛点。我的做法是定义一个Result<T>泛型类，包含code、message、data三个字段，所有接口统一返回这个结构。成功时code=200，业务异常时返回约定的错误码，前端在请求拦截器里统一判断code决定是否弹错误提示。

public class Result<T> { private Integer code; private String message; private T data; public static <T> Result<T> success(T data) { Result<T> r = new Result<>(); r.setCode(200); r.setMessage("操作成功"); r.setData(data); return r; } public static <T> Result<T> error(Integer code, String message) { Result<T> r = new Result<>(); r.setCode(code); r.setMessage(message); return r; } }

配套的全局异常处理器用@RestControllerAdvice加@ExceptionHandler实现，把业务异常、参数校验异常、系统异常分别捕获，转换成统一的 Result 返回。这样 controller 里就不用到处写 try-catch，代码干净很多。参数校验异常要特别处理，把MethodArgumentNotValidException里的字段错误信息提取出来返回给前端，用户才知道具体哪个字段填错了。

2.2 登录鉴权与 Token 方案

前后端分离下，传统的 Session 方案因为跨域和分布式部署的问题不太适用，主流做法是 Token 鉴权。用户登录成功后，后端生成一个 Token（可以用 JWT，也可以自己生成 UUID 存 Redis），返回给前端，前端存到 localStorage，之后每次请求在请求头Authorization里带上。

JWT 的好处是无状态，服务端不用存，但缺点是无法主动失效（比如用户被禁用后 Token 还没过期仍能访问）。我的折中方案是：JWT 里只放用户 ID 和过期时间，每次请求拦截器里查一次 Redis 或数据库确认用户状态，虽然多一次查询，但安全性有保障。如果项目规模小、并发低，直接查数据库也完全够用。

拦截器实现上，用HandlerInterceptor的preHandle方法校验 Token，校验通过后把用户信息塞进ThreadLocal，后续 service 层可以直接取当前登录用户，不用层层传参。这里有个坑：ThreadLocal 用完必须 remove，否则线程池复用时会串数据，这个 bug 排查起来非常隐蔽。

@Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { String token = request.getHeader("Authorization"); if (StringUtils.isBlank(token)) { throw new BusinessException(401, "未登录"); } Claims claims = JwtUtil.parse(token); UserContext.set(claims.get("userId", Long.class)); return true; } @Override public void afterCompletion(...) { UserContext.remove(); // 必须清理 }

2.3 MyBatis 动态 SQL 与分页处理

管理后台的列表查询几乎都是"多条件动态筛选 + 分页"。MyBatis 的<if>、<where>标签处理动态条件非常顺手：

<select id="selectPage" resultType="UserVO"> SELECT u.id, u.username, u.nickname, r.role_name FROM sys_user u LEFT JOIN sys_user_role ur ON u.id = ur.user_id LEFT JOIN sys_role r ON ur.role_id = r.id <where> u.deleted = 0 <if test="keyword != null and keyword != ''"> AND (u.username LIKE CONCAT('%', #{keyword}, '%') OR u.nickname LIKE CONCAT('%', #{keyword}, '%')) </if> <if test="status != null"> AND u.status = #{status} </if> </where> ORDER BY u.create_time DESC </select>

分页推荐用 PageHelper 插件，在查询前调用PageHelper.startPage(pageNum, pageSize)，它会自动拦截 SQL 加上LIMIT，并把总数封装进PageInfo。注意 PageHelper 只对紧接着的第一条查询生效，中间不能插入其他查询，否则分页会错乱，这个坑我见过不止一次。

提示：模糊查询用CONCAT('%', #{keyword}, '%')而不是${}拼接，前者是预编译参数，能防 SQL 注入，后者是字符串直接拼接，有安全风险。

2.4 前端请求封装与路由守卫

前端用 axios 封装一个统一的请求实例，配置baseURL、超时时间，在请求拦截器里自动带上 Token，在响应拦截器里统一处理错误码：

const service = axios.create({ baseURL: '/api', timeout: 10000 }) service.interceptors.request.use(config => { const token = localStorage.getItem('token') if (token) config.headers['Authorization'] = token return config }) service.interceptors.response.use( res => { const { code, message, data } = res.data if (code === 200) return data if (code === 401) { router.push('/login'); return Promise.reject(message) } Message.error(message) return Promise.reject(message) }, err => { Message.error('网络异常'); return Promise.reject(err) } )

路由守卫负责在跳转前检查登录状态和权限。router.beforeEach里判断目标路由是否需要登录、当前用户是否有对应权限，没有就重定向到登录页或无权限页。权限判断依赖后端返回的菜单列表，前端动态生成可访问路由，这样不同角色登录看到的菜单是不一样的。

3. 完整部署流程与实操记录

3.1 环境准备与依赖版本对齐

部署前先把版本对齐，这是避免"在我电脑上能跑"的关键。我实测稳定的一套组合是：JDK 8 或 17（看项目用的 SpringBoot 版本，2.x 配 JDK 8，3.x 必须 JDK 17）、Maven 3.6+、MySQL 5.7 或 8.0、Node.js 16 或 18。版本不匹配是启动失败的头号原因，比如 SpringBoot 3.x 用了 JDK 8 会直接报类找不到。

MySQL 建库时注意字符集：

CREATE DATABASE bb_platform DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

导入 SQL 脚本后检查表是否都建成功，重点看有没有外键约束导致的导入顺序问题。如果脚本里表之间有外键依赖，导入顺序错了会报错，稳妥做法是先关掉外键检查SET FOREIGN_KEY_CHECKS=0;，导完再打开。

3.2 后端配置与启动

后端要改的核心配置在application.yml里，主要是数据库连接、端口、文件上传路径：

server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/bb_platform?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver mybatis: mapper-locations: classpath:mapper/*.xml configuration: map-underscore-to-camel-case: true

map-underscore-to-camel-case: true这个配置很关键，它让数据库的create_time自动映射到实体的createTime，省掉大量resultMap配置。启动时如果报数据源连接失败，先确认 MySQL 服务是否启动、端口是否被占用、密码是否正确，这三个排查完基本能解决八成问题。

3.3 前端构建与联调

前端先npm install装依赖，然后改vue.config.js里的代理配置，把/api转发到后端地址，解决开发环境跨域：

devServer: { port: 8081, proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true, pathRewrite: { '^/api': '' } } } }

npm run serve启动后访问http://localhost:8081，用默认账号登录测试。生产环境则npm run build打包出dist目录，丢到 Nginx 里托管，Nginx 配置里把/api反向代理到后端服务，同时处理 Vue Router 的 history 模式回退：

location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8080/; }

try_files这行不加的话，刷新非首页路由会 404，这是 Vue history 模式部署最常见的坑。

3.4 部署检查清单

上线前我习惯过一遍这张表，能挡掉大部分低级问题：

4. 常见问题排查与避坑经验

4.1 启动与运行期高频问题

实际部署中遇到的问题，八成集中在几个固定位置。下面这张速查表是我这些年攒下来的，基本覆盖了新手会踩的坑：

4.2 性能与安全方面的实操心得

管理系统虽然并发不高，但有些细节不注意会埋雷。密码绝对不能明文存，用 BCrypt 加密，Spring Security 里有现成的BCryptPasswordEncoder，即使不用 Security 也可以单独引入这个工具类。接口要做权限校验，不能只靠前端隐藏按钮，后端每个敏感接口都要校验当前用户是否有对应权限，前端隐藏只是体验优化，不是安全措施。

文件上传要限制类型和大小，别让用户传个 exe 上来。上传路径不要放在项目目录里，独立到一个固定目录，否则重新部署时文件就丢了。日志方面，用 Logback 按天切割，保留 30 天，出问题时能回溯。

注意：逻辑删除字段一定要在所有查询里带上deleted = 0条件，漏一处就会把已删除数据查出来，这种 bug 上线后很难发现，建议在 MyBatis 拦截器里统一处理，或者用 MyBatis-Plus 的逻辑删除插件自动拼接。

4.3 二次开发时的扩展建议

拿到源码后想加功能，建议先摸清三件事：接口返回结构、鉴权流程、数据库表关系。加新模块时照着现有模块的结构复制一份改，比从零写快得多，也能保证风格统一。新增接口记得同步更新前端的 api 封装和路由配置，权限表里也要加对应的菜单记录，否则新页面在菜单里出不来。

如果要做成多环境部署，把配置按application-dev.yml、application-prod.yml拆开，启动时用--spring.profiles.active=prod指定，避免改配置改出事故。数据库变更用 Flyway 或 Liquibase 管理版本，团队协作时能避免"你改了我不知道"的混乱。

这套技术栈本身不复杂，真正拉开差距的是工程细节：统一返回、全局异常、逻辑删除、权限校验、部署配置，每一项单独看都是小事，组合起来决定了一个项目能不能长期维护。我在实际项目里最大的体会是，前期多花半天把基础设施搭好，后期能省下好几天的排障时间，尤其是统一返回和全局异常这两块，越早做越省心。