SpringBoot+Vue企业客户管理系统：从架构设计到部署避坑全攻略-平芜编程栈

用SpringBoot+Vue做企业客户管理系统，这个组合可以说是Java Web毕设里最稳妥、也最能覆盖考核点的选择之一。我见过不少同学在这个题目上栽跟头，倒不是功能做不出来，而是栽在工程化细节上：数据库脚本执行报错、前后端联调跨域、接口文档对不上、部署后页面白屏。这篇文章就把这类项目从架构设计、数据库脚本、后端接口、前端联调到问题排查的完整链路拆开讲一遍，结合我实际带着项目落地时的经验来写，希望能帮你把毕设做扎实，而不是只停留在“能跑就行”。

1. 整体设计与技术选型背后的考量

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

先说说选型问题。企业客户管理系统这个题目，本质上就是一个典型的CRUD业务系统，核心是围绕客户数据做增删改查、分页搜索、权限控制、数据统计。这类系统对并发要求不高，对业务逻辑的完整性和工程规范性要求却不低，特别适合用SpringBoot+Vue的前后端分离架构来做。

SpringBoot的价值在于它把Spring生态里繁琐的配置大幅简化了。Java Web阶段很多同学用SpringMVC写项目，光一个applicationContext.xml、spring-mvc.xml、web.xml就能折腾半天，各种bean定义、注解扫描、视图解析器配置，稍不留神就启动失败。SpringBoot用自动配置和内嵌Tomcat把这些全干了，一个@SpringBootApplication注解加上几个starter依赖，项目就能跑起来。对于毕设来说，省下来的时间应该花在业务逻辑和系统设计上，而不是浪费在环境配置上。

Vue这边选Vue2还是Vue3其实都行，如果配套的源码是用Vue2写的，就跟着Vue2走，生态成熟、资料多，Element UI的组件风格也适合管理后台。Vue3的组合式API更现代，但如果是参考现有源码做二次开发，保持技术栈一致性比追求版本新更重要。

再补一句，为什么不用SpringBoot+Thymeleaf做成非前后端分离？因为现在企业里的Java Web项目几乎都是前后端分离的主流形态，毕设答辩时老师大概率会问“你这个项目是怎么实现前后端交互的”，你如果答得上接口设计、跨域处理、Token鉴权这一整套，比单纯说“页面是后端模板渲染的”更有说服力，技术含量也高一个档次。

1.2 项目结构如何划分比较合理

拿到一份完整的客户管理系统源码，第一件事不是急着跑起来，而是看懂它的结构。前后端分离项目的目录规划直接影响后续开发的效率，我通常建议按下面这种方式组织：

后端结构：

controller：接收前端请求，参数校验，调用service，返回统一结果对象，不写业务逻辑。
service：业务层接口和实现，处理核心业务规则，比如客户归属变更、重复客户校验、跟进记录的权限校验。
mapper：数据访问层，配合MyBatis或MyBatis-Plus操作数据库。
entity：实体类，和数据库表字段对应。
dto：数据传输对象，用来接收前端传来的复杂参数，避免实体类直接暴露给前端。
common：公共模块，统一返回体、全局异常处理、工具类、常量定义。
config：配置类，跨域配置、拦截器注册、MyBatis-Plus分页插件等。

前端结构（Vue工程内）：

src/api：按模块拆分的接口请求方法，统一封装axios。
src/views：页面组件，按业务模块建文件夹，如customer、followUp、system。
src/router：路由配置，配合动态路由或路由守卫做权限控制。
src/store：全局状态管理，存用户信息、菜单权限、Token。
src/utils：工具函数，比如request.js里面封装axios实例和拦截器。

这种结构的好处是职责清晰：后端controller只看作“服务员”，service是“后厨”，mapper是“仓库管理员”；前端views负责展示，api负责和服务器打交道。你后续想加一个“客户回收站”功能，就在后端加一套controller/service/mapper，前端加一个views/recycle页面和一个api接口文件，互不干扰，这种模块化扩展的能力在毕设答辩时很加分。

2. 数据库设计与SQL脚本落地要点

2.1 客户管理的核心表结构设计

客户管理系统不管功能怎么花哨，核心表就那么几张：客户表、联系人表、跟进记录表、用户表、角色表、权限表。设计得好不好，直接影响后续开发的复杂度。

客户表（customer）是核心中的核心，建议包含这些字段：

id：主键，自增。
customer_name：客户名称（个人客户存姓名，企业客户存公司名）。
customer_level：客户级别，可以用数字表示：1潜在客户、2意向客户、3正式客户、4流失客户。
industry：所属行业。
phone：联系电话，注意手机号和座机分开存，避免查询混乱。
address：客户地址。
owner_id：归属人ID，也就是负责跟这个客户的销售/员工ID，这是客户管理系统的关键字段，很多权限判断都靠它。
status：状态，我用的是0正常、1删除，做逻辑删除而不是物理删除。
create_time、update_time：创建时间和更新时间，用MyBatis-Plus的自动填充功能维护。

为什么推荐逻辑删除？因为客户的跟进记录、关联订单（如果有）往往和客户表有业务关联，物理删掉客户会导致历史数据丢失。企业客户管理场景里，客户信息即使不再合作了也要留档分析。表里加一个deleted字段，查询时统一加where deleted = 0，MyBatis-Plus里用@TableLogic注解就能自动处理。

跟进记录表（follow_record）记录每一次和客户的沟通情况，字段包括：id、customer_id、user_id（跟进人）、content（跟进内容）、next_time（下次跟进时间）、create_time。这个表在毕设里属于“亮点功能”所在，很多同学只做到客户CRUD，加上跟进记录才能体现“企业管理”的业务深度。

用户表和权限这块，如果要做RBAC（基于角色的权限控制），那就是五张表：用户表、角色表、菜单权限表、用户角色关联表、角色菜单关联表。如果题目里没强调权限粒度，也可以用相对简单的方案：用户表加一个role字段，区分管理员和普通员工。管理员能看所有客户，普通员工只能看自己名下的客户。这个在答辩时同样能讲清楚，而且代码量少很多。

2.2 SQL脚本最容易踩的几个坑

SQL脚本是很多人忽略但特别容易出问题的地方。我整理几个实际踩过的坑。

第一，字符集问题。建库语句一定要指定utf8mb4，不要用默认的latin1。utf8mb4比utf8多了对emoji符号的支持，而且兼容性更好。建库语句参考这样写：

CREATE DATABASE IF NOT EXISTS customer_system DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

第二，导入顺序问题。如果SQL脚本里有外键约束，导入时必须先建父表再建子表，否则会报外键关联错误。更建议的做法是：开发阶段建表不要用物理外键，而是保留逻辑外键（也就是只存owner_id这样的关联字段，不声明FOREIGN KEY约束）。原因很简单，物理外键在删除数据、批量导入时都很麻烦，很多企业开发现在也明确不用物理外键，这个理念在答辩时可以拿出来说。

第三，初始化数据要够用。一份只有表结构没有数据的SQL脚本，前端登录进去是一片空白，演示效果大打折扣。好的SQL脚本应该自带管理员账号（比如admin/123456，密码是BCrypt加密后的值）、几个测试用的角色、几十条行业分布合理的客户数据（制造业、互联网、金融、零售都来几条）、若干条跟进记录。这样前端联调时各种功能都能直接演示，不需要手动造数据。

第四，字段类型不要乱用。金额用decimal别用float，时间用datetime，手机号用varchar别用bigint（否则前端显示会丢精度，也别用int直接存不下11位）。真人的身份证号需要用加密或脱敏处理，毕设里如果没有这个字段最好，有的话一定不要明文存储。

3. 后端核心模块与接口文档实操

3.1 登录鉴权和权限控制的常见实现

企业客户管理系统里的用户权限和登录状态管理，是毕设答辩时老师最爱深挖的点。很多同学的实现是“前端跳转登录页就完事”，这属于没有真正掌握权限控制的逻辑。

比较标准的做法是：用户提交用户名密码，后端校验通过后，生成一个Token（通常用JWT），返回给前端。前端把Token存在本地存储里，之后每次请求都在Header里带上Authorization: Bearer xxx。后端通过拦截器或者Spring Security过滤器统一校验Token，校验通过才放行请求。

JWT的好处是服务端不需要存Session，天然适合前后端分离。实际代码里可以这样用：

// 登录成功后生成Token String token = Jwts.builder() .setSubject(user.getUsername()) .claim("userId", user.getId()) .claim("role", user.getRole()) .setExpiration(new Date(System.currentTimeMillis() + 1000 * 60 * 60 * 8)) .signWith(SignatureAlgorithm.HS256, secretKey) .compact();

拦截器里校验Token，同时把用户信息放进ThreadLocal或者Request attribute里，方便后续service层获取当前登录用户。

@Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { String token = request.getHeader("Authorization"); if (token == null || token.isEmpty()) { throw new BusinessException(401, "未登录或登录已过期"); } // 解析Token，校验签名和过期时间 Claims claims = Jwts.parser().setSigningKey(secretKey).parseClaimsJws(token.replace("Bearer ", "")).getBody(); request.setAttribute("userId", claims.get("userId")); return true; }

这里的几个关键选择解释一下：Token过期时间设8小时，是因为一般工作场景就是一个白天，到期后前端跳回登录页重新登录。加密规则用HS256就够了，是对称加密，前后端都只需要密钥。Token里只放用户ID和角色这种非敏感信息，不要放密码。

权限控制再进一步，是在查询客户列表时做数据权限过滤。普通员工登录后，SQL查询自动加上owner_id = 当前登录用户ID的条件，管理员不加这个条件。实现方式可以在service层判断角色后拼接条件，也可以用MyBatis-Plus的拦截器做数据权限，毕设用前一种就足够清晰了。

3.2 客户模块接口设计与文档组织

接口文档对于前后端分离项目来说不是可选项，是必需品。没有接口文档，前端想调一个新接口，只能去翻后端代码，效率极低，也容易理解偏。

先看统一返回体的设计。一个项目里所有接口的返回值应该保持统一格式，我常用的结构是：

{ "code": 200, "message": "操作成功", "data": { } }

其中code=200表示成功，code=401表示未认证，code=500表示服务器异常，data里放实际数据。这样做的好处是前端axios拦截器里可以统一判断code，不用每个接口单独处理异常分支。

客户模块的接口一般包括这些，我列一张表给你看，接口文档照着这个结构来写就不会乱：

接口地址	请求方式	功能说明	主要参数
/api/login	POST	用户登录	username, password
/api/customer/page	GET	客户分页查询	pageNum, pageSize, customerName, level
/api/customer/detail	GET	客户详情	id
/api/customer/add	POST	新增客户	customer对象
/api/customer/update	PUT	修改客户	customer对象
/api/customer/delete	DELETE	删除客户（逻辑删）	id
/api/customer/export	GET	导出客户Excel	查询条件
/api/follow/add	POST	新增跟进记录	customerId, content, nextTime
/api/follow/list	GET	跟进记录列表	customerId

写接口文档时，每一个接口至少要包含：请求地址、请求方式、请求参数说明（字段名、类型、是否必填、含义）、返回示例。用代码块展示JSON示例最清晰：

{ "code": 200, "message": "操作成功", "data": { "total": 58, "records": [ { "id": 1, "customerName": "某制造企业", "customerLevel": 3, "industry": "制造业", "ownerName": "张三", "createTime": "2024-03-01 10:20:30" } ] } }

关于接口文档的形式，如果觉得手写Markdown维护起来麻烦，项目里可以集成Swagger（Springfox或springdoc），自动生成在线接口文档，接口注释写好之后文档就出来了。不过即便有Swagger，我建议还是保留一份Markdown形式的接口文档，答辩时打印出来或者展示给老师看，信息层级比Swagger更直观。

3.3 分页查询和模糊搜索的后端实现

分页查询是客户管理系统最高频的接口，所有列表页都离不开它。用MyBatis-Plus的Page对象来实现分页非常方便，核心逻辑就几行：

public PageResult<Customer> pageCustomers(CustomerQuery query) { Page<Customer> page = new Page<>(query.getPageNum(), query.getPageSize()); LambdaQueryWrapper<Customer> wrapper = new LambdaQueryWrapper<>(); wrapper.like(StringUtils.hasText(query.getCustomerName()), Customer::getCustomerName, query.getCustomerName()) .eq(query.getLevel() != null, Customer::getCustomerLevel, query.getLevel()) .eq(Customer::getDeleted, 0) .orderByDesc(Customer::getCreateTime); customerMapper.selectPage(page, wrapper); return PageResult.of(page); }

这里有个容易犯的错：模糊搜索时只判断了参数是否为空，没有处理空格和特殊字符。建议在service层先trim一下参数，再加上StringUtils.hasText判断，保证搜索条件的健壮性。

查询结果按创建时间倒序排，新录入的客户在最前面，这是最符合实际使用习惯的排序方式。如果客户量大了，还可以加一个按最近跟进时间排序的功能，这样销售打开列表看到的是“最需要跟进的客户”，企业使用的真实感一下就出来了。

4. 前端Vue接入与页面实现要点

4.1 从零开始跑通前端的步骤

拿到前端源码，本地跑起来通常分三步。第一步确认Node环境，推荐Node 14到16之间的版本，太新的版本有时候会遇到依赖兼容问题。第二步在项目根目录执行npm install安装依赖，如果遇到网络超时，配置一下淘宝镜像源npm config set registry https://registry.npmmirror.com。第三步执行npm run serve启动开发服务器。

前端开发服务器默认端口通常是8080，而后端SpringBoot默认也是8080，两者会冲突。解决方案是在vue.config.js里配代理，既解决端口冲突也解决跨域问题：

module.exports = { devServer: { port: 8081, proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } } };

这样前端请求/api/customer/page时，开发服务器会把请求转发到后端的http://localhost:8080/api/customer/page，前端代码里就不需要写完整域名了，联调阶段非常方便。

生产部署时则不同，前端执行npm run build打包出dist目录，可以用Nginx托管，同时把/api反向代理到Java服务。这一步如果毕设要求部署演示，需要提前练一遍。

4.2 几个最影响使用体验的前端细节

前端部分，很多同学做出来的页面功能是对的但不好用，问题往往出在细节上。我举几个实际优化过的地方。

第一，axios拦截器统一处理登录过期。在src/utils/request.js里封装axios实例，响应拦截器里判断返回体的code，如果是401就清除本地存储的用户信息并跳回登录页。这样用户操作到一半Token过期时，不会看到一堆报错弹窗，而是干净地回到登录页。

第二，客户搜索表单做成“点击查询才搜索”，而不是输入框一变化就发请求。虽然监听input事件即时搜索看起来很炫，但每次敲键盘都会触发一次接口请求，数据库压力大，体验也不一定好。加一个搜索按钮，按回车也能触发，这个交互模式在企业后台里更常见。

第三，客户列表的分页组件要配好。Element UI的el-pagination组件，要设置current-page、page-size、total三个属性，并监听页码变化事件。有的人只是把数据塞到列表里，忘了分页，数据一多页面就卡。

第四，表单校验在前端做一层。新增客户时，客户名称必填、手机号格式校验、级别下拉框必选，这些用Element UI的rules规则配置好。前端校验是体验兜底，后端校验是数据安全，两层都要有。

第五，动态菜单和按钮权限。如果项目做了RBAC权限模型，前端的菜单应该根据登录用户的角色动态渲染，而不是写死。简单做法是登录成功后请求一个“获取用户菜单”的接口，后端根据角色返回菜单列表，前端router.addRoutes动态添加。这部分的实现细节比较绕，但一旦做出来，答辩时可以说“系统支持不同角色看到不同菜单，普通员工看不到系统管理模块”，这就是一个实打实的功能亮点。

5. 常见问题排查与避坑实录

5.1 环境与配置类问题速查

跑毕设项目时，环境类问题占了一半以上。我按高频到低频整理了一份排查表，遇到问题时直接对照排查。

问题现象	排查思路	解决办法
后端启动报数据库连接失败	先看数据库服务有没有启动，再看连接URL主机名、端口、库名是否对得上	检查`application.yml`里的url、username、password，确认SQL脚本已经执行成功
连接MySQL报时区错误	报错里带`serverTimezone`字样	URL后面加`?serverTimezone=Asia/Shanghai&useUnicode=true&characterEncoding=utf8`
前端页面请求接口跨域	浏览器Console里出现CORS报错	优先用vue.config.js配代理；若后端单独配置跨域，用`@CrossOrigin`或全局CorsFilter
刷新页面404	前端路由用了history模式，Nginx没配fallback	Nginx配置`try_files $uri $uri/ /index.html;`
Maven依赖下载慢或失败	检查Maven中央仓库连通性	在settings.xml里配置阿里云镜像仓库
数据库中文乱码	建库时字符集不对，或者连接URL没指定编码	库表统一utf8mb4，连接URL加上`characterEncoding=utf8`
前端npm install报版本冲突	node版本过高或过低	优先用Node 14 LTS版本，删除node_modules重装

5.2 代码与逻辑类问题排查实录

环境问题解决了，接下来是代码层面的问题。这类问题往往没有统一的报错提示，需要顺着代码逻辑去排查。

一个我在实际项目中反复遇到的问题：新增客户成功后列表不刷新。原因是新增成功后没有重新请求列表接口，或者调了查询接口但页码重置了。解决办法是新增成功后触发fetchList(1)，把页码打回第一页，让用户看到最新数据。这个细节看着小，但没处理好会让用户觉得“系统没反应”。

还有一个坑：日期格式化。Java后端返回的LocalDateTime序列化后是类似2024-03-01T10:20:30的格式，带了个T，前端直接显示很丑。解决办法是后端在application.yml里配置：

spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT+8

或者在字段上加@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")注解。如果不处理，列表页的时间列就会显示成不伦不类的格式，答辩演示时很扣分。

逻辑删除字段的坑也值得一提。如果实体类里没有对deleted字段做逻辑删除注解，那么SQL脚本里的deleted字段就只是个摆设，删除操作会真的删数据。务必检查实体类上有没有@TableLogic。

再补充一个排查问题的高效思路：后端接口报错了，先看后端控制台日志，找到异常堆栈里的第一行，那才是问题的根本，弹窗里的中文提示往往被后端catch后吞掉了真实信息。前端报错了，先打开浏览器F12看Network面板，看请求到底发出去了没有、返回状态码是多少、响应体是什么。养成这个习惯，大部分问题十分钟内能定位。