最近陆续有几位做课程设计的同学拿同一类源码来问我网上购物商城系统SpringBoot后端、Vue前端、MySQL数据库标题写得很诱人——【可直接运行】。结果呢每个人遇到的问题也出奇一致有的后端一启动就报数据库连接失败有的前端npm run serve起来之后页面白屏还有的管理员账号怎么都登不进去。说好的可直接运行变成了折腾一天还没跑起来。这套系统的门道其实不在业务有多复杂而在你要把它当成一个整体来看待。SpringBoot负责把后端服务拉起来Vue负责在浏览器里渲染页面MySQL负责存数据三者只要有一处版本不对齐可直接运行就会变成需要排错半小时。这篇文章我就按自己这些年实测跑通类似项目的经验来写先把这套商城源码从外到内拆一遍再给出一条最稳的启动路径最后把所有高频问题集中列出来。无论你是要做课设、想入门SpringBoot和Vue的全栈开发还是打算拿这套源码做二次开发应该都能直接参考。1. 直接可运行的购物商城源码拆开看其实包含三件事1.1 功能边界这套商城到底完整在哪很多人一听网上购物商城系统就以为是个大工程其实拿到源码后你会发现这个体量对新手刚刚好。它本质上是一个B2C网上商城带后台信息管理功能典型结构是用户端 管理端双端并存。用户端负责前台交易链路常见模块大概是这些模块用户端功能账号注册、登录、退出、个人资料修改商品商品列表、商品详情、分类筛选、关键词搜索购物车加入购物车、修改数量、删除、勾选结算订单创建订单、订单列表、取消订单、查看状态管理端则负责信息管理这半边商品和订单都是后台管模块管理端功能商品管理商品新增、编辑、上下架、库存调整分类管理一级/二级分类维护订单管理订单查询、发货、状态变更用户管理用户列表、启用禁用你会发现这套源码并不是只做一个展示型页面而是把用户下单 - 数据落库 - 后台处理订单 - 前端看到状态变化整条闭环串起来了。这也是它能被叫做信息管理系统的原因每个业务对象都有完整的增删改查和状态流转而不是一个静态商城外壳。1.2 技术栈分工三大件各管哪一段技术栈很经典就是主流的前后端分离组合SpringBoot负责后端接口层。工程内部分层通常很清晰Controller接收前端请求Service处理业务逻辑Mapper操作数据库。SpringBoot内嵌了Tomcat最终打成一个Jar包java -jar一跑就是一个完整后端服务。Vue负责前端界面层。使用Vue Router做页面路由Axios请求后端接口组件化的方式组织页面。开发环境里靠Node服务做热更新改完代码浏览器自动刷新。MySQL负责数据存储层。用户、分类、商品、购物车、订单、明细这些数据都落在表里后端Mapper通过SQL或MyBatis映射完成读写。为什么要选这个组合从学习角度看SpringBoot封掉了大量Spring繁琐的XML配置能让新手快速看到接口-业务-数据库这条主线Vue前后端分离的模式又是现在企业开发的主流形态MySQL则直观好懂建几张表就能把业务结构看得明明白白。所以这套组合本身就适合做课设也适合用来入门前后端分离开发。1.3 可直接运行不等于什么都不用配这是我最想强调的一点。源码标题写可直接运行意思是三样东西齐全后端源码、前端源码、数据库初始化SQL脚本。它不是说双击什么文件就能跑而是说——只要把环境对齐就能按固定步骤跑起来。所以拿到代码后第一步不是急着启动而是先找三个文件后端配置文件application.yml里面是数据库连接和端口前端依赖文件package.json里面是依赖列表和启动脚本数据库脚本通常是init.sql或mall.sql里面是建库建表语句和初始数据把这三个文件看明白了这个项目在你手里就已经成功了一半。剩下的问题几乎全是环境版本问题。2. 环境版本先对齐JDK、Node、MySQL一个都不能差2.1 先看pom.xml和package.json程序自己会告诉你要什么版本很多同学上来就装最新版JDK、最新版Node然后项目跑不起来反过来怀疑源码有Bug。其实源码没毛病是版本不对。判断版本基线只需要看两个文件先开后端的pom.xml看spring-boot-starter-parent版本号如果是2.x系列比如2.5、2.7JDK用1.8或11就够了如果是3.x系列JDK必须用17及以上否则编译直接报错再看前端的package.json看vue和vue-cli的版本Vue 2 vue-cli项目Node用14或16最稳Vue 3 Vite项目Node用16或18都可以这两个文件就是项目的说明书先看它们再装环境能避开80%的启动问题。2.2 环境安装顺序与版本矩阵按我的习惯装环境的顺序是固定的JDK - Maven - Node - MySQL。每个版本建议如下表组件推荐版本注意事项JDK1.8 / 11Spring Boot 2.x17Spring Boot 3.x配好JAVA_HOME命令行java -version能通Maven3.6及以上IDEA自带Maven也行重点是能拉依赖Node14 / 16Vue 216 / 18Vue 3建议用nvm做多版本切换别一棵树上吊死MySQL5.7 / 8.0记住root密码后面要写进配置文件这里单独把Node拎出来强调一下Vue 2老项目对Node版本非常敏感Node 17以上跑webpack经常报error:0308010C:digital envelope routines::unsupported一句话就是新版Node的OpenSSL和旧webpack不兼容。你当然可以给启动命令加参数绕过但最简单粗暴的办法就是切换Node 16。这也是为什么我强烈建议用nvm管Node版本一个命令就能换版本比卸载重装舒服太多。2.3 初始化数据库的完整操作数据库是整套系统的基础这一关过不去后端怎么启动都会挂在数据库连接上。先用命令行或图形化客户端连上MySQL然后执行create database mall default character set utf8mb4 collate utf8mb4_general_ci; use mall; source /path/to/mall.sql;注意字符集一定要用utf8mb4别用默认的utf8。utf8mb4是完整的UTF-8支持能存表情符号和生僻字而且和绝大多数项目的字符集设定一致能少掉一堆中文乱码问题。导入之后执行show tables;如果能看到user、category、product、cart、orders这类表说明脚本导入成功。有些SQL脚本里已经自带create database语句那你直接在命令行执行source整个脚本就行不需要手动建库。还有一个小坑如果脚本里有初始管理员账号记得看一眼初始密码登录后台要用。很多项目默认管理员是admin密码是123456或者admin123具体看脚本里的INSERT语句。3. 后端启动环节数据库连接、拦截器白名单、跨域三件套3.1 第一步永远是改application.yml后端启动前必须先把数据库连接配置改成你自己的。打开application.yml找到spring.datasource这一段server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/mall?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrue username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver这里有几个参数需要逐一说清楚jdbc:mysql://localhost:3306/mall里的mall必须和你建库时名字一致不然报Unknown database。useUnicodetruecharacterEncodingutf8是为了中文不乱码几乎每个商城项目都不能少。serverTimezoneAsia/Shanghai解决MySQL时区报错。旧版驱动不指定时区会直接启动失败。allowPublicKeyRetrievaltrue是MySQL 8才需要的。如果你本机是MySQL 8而源码默认配置是给MySQL 5写的不加这个会报Public Key Retrieval is not allowed。driver-class-name也要注意MySQL 8用com.mysql.cj.jdbc.DriverMySQL 5用com.mysql.jdbc.Driver写错会提示找不到驱动类。如果源码里还依赖了Redis比如用Redis存token或做缓存那启动前要把Redis也拉起来否则后端启动时会反复尝试连接Redis直到超时报错。这种情况在较完整的商城项目里很常见。3.2 Maven依赖拉取与Jar包启动配置改完用IDEA打开后端工程右下角会开始拉Maven依赖。这一步考验的是耐心和网络依赖下载完之前不要急着启动。如果依赖一直卡着不动检查两件事第一IDEA里Maven配置对不对用的本地仓库路径在哪第二Maven的中央仓库访问速度。下载慢时可以给Maven的settings.xml配置国内镜像源这是常规操作不属于什么特殊手段放心配就行。依赖就绪后可以直接在IDEA里运行主启动类也可以打包成Jar再运行。我个人的习惯是先打包验证命令行执行mvn clean package -DskipTests打包成功后在target目录下会生成一个mall-0.0.1-SNAPSHOT.jar之类的文件然后java -jar target/mall-0.0.1-SNAPSHOT.jar看到日志里出现Started MallApplication in x.xxx seconds说明后端已经起来了。这时候可以先在浏览器访问一下http://localhost:8080/api/user/login之类的接口能返回JSON就说明基础链路是通的。3.3 登录鉴权白名单没配好接口全401商城项目基本都有登录鉴权。比较常见的做法是登录成功生成一个Token返回给前端前端后续请求在请求头里带上Token后端通过拦截器校验Token是否有效。拦截器逻辑大致长这样public class AuthInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { if (OPTIONS.equalsIgnoreCase(request.getMethod())) { return true; } String token request.getHeader(Authorization); if (token null || !JwtUtil.verify(token)) { response.setStatus(401); return false; } return true; } }注册拦截器时最关键的是放行公共接口registry.addInterceptor(new AuthInterceptor()) .addPathPatterns(/api/**) .excludePathPatterns( /api/user/login, /api/user/register, /api/product/**, /api/category/** );白名单没配好会出现一个非常经典的Bug登录接口本身能通登录成功之后前端再请求商品列表、购物车这些接口全部返回401。排查思路很简单先看请求头里到底有没有带上Token再看后端拦截器是不是把公共接口也拦截了。3.4 跨域配置前后端分离的必经之路前端和后端端口不同比如前端8081、后端8080浏览器就会因为同源策略拦截跨端口请求控制台里报CORS错误。解决方式有两个前端配代理或者后端开跨域。开发环境通常用前端代理更简单但如果你直接通过IP访问后端地址或者想省事一点后端直接加一个跨域配置也行。Configuration public class CorsConfig { Bean public CorsFilter corsFilter() { CorsConfiguration config new CorsConfiguration(); config.addAllowedOriginPattern(*); config.addAllowedHeader(*); config.addAllowedMethod(*); config.setAllowCredentials(true); UrlBasedCorsConfigurationSource source new UrlBasedCorsConfigurationSource(); source.registerCorsConfiguration(/**, config); return new CorsFilter(source); } }注意一个小坑setAllowCredentials(true)的时候addAllowedOrigin不能用*要用addAllowedOriginPattern(*)否则浏览器还是会拦。这个细节很容易漏报错的时候又很不直观建议直接照上面的写法来。4. 前端Vue启动与调试npm install只是开始4.1 package.json决定启动方式前端工程一般是一个独立目录先看package.json的scripts字段scripts: { serve: vue-cli-service serve, build: vue-cli-service build }Vue 2 vue-cli项目启动命令是npm run serveVue 3 Vite项目一般是npm run dev。别想当然以实际package.json写的为准。进入前端目录依次执行npm install npm run servenpm install第一次跑通常会比较久因为要装几百个依赖包。装完之后启动看到Compiled successfully然后打开浏览器访问http://localhost:端口前端页面就出来了。4.2 npm install最容易炸的两个点第一是node-sass安装失败。node-sass是出了名的版本敏感Node 17以上基本装不上。如果你在package.json里看到node-sass最好的办法就是先把Node切到14或16再重新npm install。如果项目里的样式工具是sass或dart-sass那相对没用那么敏感。第二是启动时报OpenSSL错误。如果你Node版本比较高启动webpack时会看到error:0308010C:digital envelope routines::unsupported解决办法要么降Node版本要么在启动命令里加环境变量。在package.json里可以这样改scripts: { serve: NODE_OPTIONS--openssl-legacy-provider vue-cli-service serve }不过这样写Windows下可能有兼容问题最好用cross-env包中转一下或者干脆用nvm换到Node 16省心太多。我自己遇到这种问题都是直接换Node版本不加参数因为参数只是掩盖了版本不匹配的根因。4.3 devServer代理解决开发环境跨域前端页面出来了但页面上没有数据打开浏览器控制台一看全是CORS报错。这种情况十有八九是前端没配代理或者代理指向错了。在Vue 2工程里配置写在根目录的vue.config.jsmodule.exports { devServer: { port: 8081, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } };这段配置的意思是前端把以/api开头的请求全部转发到http://localhost:8080也就是后端地址。这样前端的请求经过代理转发就不再触碰浏览器的同源限制。这里有个很常见的坑前端项目里封装请求时baseURL可能写的是http://localhost:8080/api这样的绝对路径而不是/api相对路径。如果baseURL是绝对路径请求根本不会经过/api这个代理规则CORS照样报错。正确做法是baseURL写/api剩下的交给代理转发。4.4 登录态保持与路由守卫前端登录成功之后需要把Token存起来并在后续请求里带上。通常的做法是存在localStorage里由Axios拦截器统一加请求头。Axios请求拦截器里加上这一句service.interceptors.request.use(config { const token localStorage.getItem(token); if (token) { config.headers[Authorization] token; } return config; });响应拦截器里处理401service.interceptors.response.use( response response.data, error { if (error.response error.response.status 401) { localStorage.removeItem(token); router.push(/login); } return Promise.reject(error); } );路由守卫则负责在页面跳转前判断登录状态router.beforeEach((to, from, next) { const token localStorage.getItem(token); if (to.meta.requiresAuth !token) { next(/login); } else { next(); } });这套机制串联起来用户未登录时访问购物车、订单这些页面就会自动被踢回登录页而不是看到了页面再调接口报401。5. 数据库表结构与下单链路价格快照和库存扣减才是重点5.1 一套典型商城表结构长什么样商场项目不管怎么写核心表逃不出这几张表作用user用户信息category商品分类product商品信息、价格、库存cart购物车记录orders订单主表order_item订单明细表核心字段大概是这样的userid、username、password、nickname、phone、avatar、role、create_timecategoryid、name、parent_id、sortproductid、category_id、name、subtitle、main_image、price、stock、sales、status、detailcartid、user_id、product_id、quantity、checked、create_timeordersid、order_no、user_id、total_price、status、receiver_name、receiver_phone、address、create_time、pay_time、ship_timeorder_itemid、order_id、product_id、product_name、product_image、current_unit_price、quantity、total_price表之间的关联关系也很直观user和orders是一对多一个用户有多张订单orders和order_item是一对多一张订单有多条商品明细cart里的商品只是购物车快照真正下单后数据会进入order_item。5.2 为什么订单明细必须存商品快照这一条是最值得新手记住的设计细节。很多新手设计订单表的时候只放一个product_id以为查订单时去商品表里把名字和价格查出来就行。但这是错的。商品的价格、名称随时可能被后台修改一旦你下单之后商家改了价格历史订单再去商品表关联看到的就不是下单时的价格了。所以正规系统都会设计一张order_item明细表下单的那一瞬间把商品名称、主图、单价、数量全部复制一份存进去。这就像购物小票一样小票上印的是你买的那一刻的单价而不是拿小票去系统里查现在的价格。看字段名就能明白current_unit_price这个字段存的就是下单时刻的商品单价快照。这个小设计决定了这套源码是能跑的教学Demo还是接近真实业务的信息管理系统。5.3 下单接口的完整步骤下单接口是整套系统的核心它的Service方法大概要干这么几件事Transactional public OrderVO createOrder(Long userId, ListCartItem selectedItems) { // 1. 查出购物车选中的商品信息 // 2. 逐个校验商品状态是否正常、库存是否足够 // 3. 用商品当前价格组装 order_item重新计算总价 // 4. 扣减库存update product set stock stock - #{num} where id #{id} and stock #{num} // 5. 生成订单号保存订单主表 // 6. 删除已经下单的购物车记录 // 7. 返回订单号、实际应付金额 }这里面有两个关键点。第一总价必须在后端重新计算不能直接信任前端传过来的价格。前端请求参数里带过来的只是商品数量和购物车明细ID单价要以后端数据库查到的当前价格为准。否则用户把请求改一下就能以超低价下单这是最基础的安全底线。第二扣库存要防超卖。最简单的写法是UPDATE product SET stock stock - #{num} WHERE id #{id} AND stock #{num}这条SQL利用数据库的行锁和条件判断保证即使多个用户同时下单同一件商品也不会出现库存扣成负数。方法上加了Transactional注解意思是整个方法是一个事务扣库存和生成订单要么都成功要么都回滚。绝对不能出现订单生成了、库存却没扣这种情况。5.4 订单状态机怎么流转订单状态一般用一个整型字段表示常见约定状态值含义可执行操作0待付款用户取消超时自动关闭1已付款商家发货2已发货用户确认收货3已完成无4已取消无用户端看到的是待付款/已付款/已发货/已完成后台管理端通过修改这个状态字段来驱动订单流转。比如商家点击发货就是把status从1改成2用户确认收货就是把2改成3。这个状态机很简单但它是信息管理系统里非常典型的设计思路数据在不同状态之间流转每个状态都有对应的操作权限和页面呈现。看懂了这个后面做物流、售后这些扩展功能都会有思路。6. 跑通之后的改造路径从能运行到会改代码6.1 用链路定位法找到要改的文件很多新手不敢改代码是因为不知道往哪里改。这里分享一个我自己一直在用的链路定位法打开浏览器开发者工具切到Network面板页面上随便点一个功能比如商品列表找到一个/api/product/list之类的请求URL在前端工程的src/api目录里搜索这个路径找到对应的请求函数再根据这个URL映射到后端的Controller看它调用了哪个Service顺着Service找到Mapper最后看到真正的SQL这一条链路走下来你就知道页面上某个数据是从哪张表的哪个字段来的了。改前端样式去src/views下找vue文件改业务逻辑去Service里改改查询条件去Mapper里改SQL。五分钟就能定位到要改的文件你就不慌了。6.2 三个最常见的改造点第一个改造点是首页内容。很多商城项目的首页轮播图、公告、推荐位要么是后台一张banner表要么是前端vue文件里写死的数据。改起来不难找到对应的表或组件替换成自己的内容就行。第二个改造点是商品搜索。如果项目本身没有搜索功能最简单的方案是在商品列表接口加一个keyword参数SQL改成SELECT * FROM product WHERE status 1 AND name LIKE CONCAT(%, #{keyword}, %) ORDER BY create_time DESC前端搜索框绑定一个input提交时把关键词当作请求参数发过去即可。第三个改造点是订单支付。标准商城源码通常只做到下单生成订单、状态待付款真正的支付需要接入第三方支付平台的回调。系统里通常已经预留了pay_type、pay_time字段你要做的就是写一个回调接口校验支付结果的签名然后把订单状态从0改成1记录支付时间。这块涉及具体的支付平台接入每家平台的对接文档都不一样但整体思路基本都是回调 - 验签 - 更新订单状态。6.3 接口速查表跑通之后建议对照这张接口表理解前后端是怎么咬合的方法路径功能权限POST/api/user/login用户登录公开POST/api/user/register用户注册公开GET/api/product/list商品分页列表公开GET/api/product/detail/{id}商品详情公开POST/api/cart/add加入购物车登录GET/api/cart/list购物车列表登录POST/api/order/create创建订单登录GET/api/order/list我的订单列表登录PUT/api/admin/order/status修改订单状态管理员也就是说前端页面本质上是一堆接口的调用方后端接口是一堆业务的出口。你要改页面先找页面调的接口你要改接口先找接口对应的Service。接口是前后端之间的契约搞清楚这张表等于拿到了这套源码的地图。6.4 改皮肤和加页面换主题色是很多人拿到源码后想做的第一件事。如果前端用了Element UI一般在main.js或样式变量文件里能找到主题相关配置。Element UI的或Element Plus的主题定制思路都是改CSS变量搜索primary这个关键字找到全局主色值改掉就行。如果项目用了SCSS那就在styles/variables.scss里改全局生效。新增页面也不难在src/views下复制一个现有页面改掉内容然后在src/router里注册一条新路由最后在侧边栏菜单配置里加一项。三步走下来一个新页面就挂上去了。这里面最需要注意的是新增页面的路径和权限配置要跟菜单、路由保持一致少配一项就可能会出现路由存在但访问404或者菜单点了没反应的情况。7. 按出现频次排好的运行问题清单7.1 高频问题排查表把我和几位同学的实测过程汇总一下下面这些问题出现频率最高问题现象真实原因处理办法后端启动失败提示Failed to configure a DataSource数据库没启动或连接参数没改先启动MySQL核对application.yml里的账号密码库名提示Unknown database mallSQL脚本没导入或库名不一致执行create database后再导入脚本提示Access denied for user root数据库密码和yml配置不一致统一两者密码提示Public Key Retrieval is not allowedMySQL8需要额外连接参数在url末尾加allowPublicKeyRetrievaltrue前端npm run serve报openssl错误Node版本太高降到Node 16或加NODE_OPTIONS--openssl-legacy-providernode-sass安装失败node-sass与Node版本不匹配切到Node 14/16或用dart-sass替代前端请求接口CORS报错后端开了跨域但配置不完整或前端baseURL写绝对路径后端用AllowedOriginPattern前端baseURL改成/api登录成功后所有接口都401拦截器白名单没放行或前端没带Token检查excludePathPatterns和Axios请求头后台上传图片访问404静态资源目录没有映射配置addResourceHandlers指向上传目录接口能通但返回数据为空后端字段是下划线前端驼峰没做映射开启mybatis map-underscore-to-camel-case或SQL里写别名这十类问题里前四个都是数据库层面的直接印证了我前面反复说的数据库连接是后端启动的第一关。这一关过了整个系统基本就稳了一半。7.2 我的排查顺序拿到别人给的可直接运行项目我自己的排查顺序是固定的分享给你参考第一先看后端日志看第一个报错是什么。后端日志是所有问题的放大镜它已经把原因写在里面了只是很多人没耐心读。第二用数据库客户端单独连一次MySQL。能连上说明账号、密码、端口没问题连不上后面做什么都是白费。第三后端起来后先用浏览器或接口测试工具访问一个公共接口确认后端对外可用。第四前端起来后打开Network面板看第一个页面请求返回什么状态码。404是路径或代理问题401是权限问题500是后端异常CORS就是跨域配置问题。第五每个环节只验证一条完整链路页面 - 前端代理 - 后端Controller - Service - Mapper - 数据库。链路只要通了后面再遇到问题就都是普通问题。我自己的习惯是拿到任何一套SpringBoot加Vue的可直接运行项目第一件事不是读业务代码而是先把版本对齐、把数据库导入、把后端拉起来、把前端代理配好确认一条最基本的请求链路通了之后再开始看功能。链路通了项目的基本盘就稳了后面所有问题都会变成可定位、可解决的普通问题。这套商城系统的价值也正在于此它是一个能完整跑通的真实业务闭环而不是一堆看起来能跑的代码片段。把这条链路上每一环都吃透一个全栈项目的骨架你就真正拿到手里了。
