「已注销」从拿到一份“基于SpringBoot的音乐网站设计与实现（源码+lw+部署文档+讲解等）”这样的毕业设计/课程设计压缩包开始，到真正把网站跑起来并弄懂每个模块的来龙去脉，中间的距离往往比想象中大得多。我接手过好几轮这类项目，源码结构大同小异，但真正决定这个项目是“能交差”还是“能学到东西”的，往往不是那几百兆的代码，而是你对SpringBoot这套生态的理解深度。这篇文章我打算换一种讲法：不按目录平铺直叙，而是站在一个刚拿到完整源码包、准备二次开发或准备答辩的人的角度，把音乐网站从技术选型、数据建模、核心功能实现，到部署上线、问题排查的完整链路拆开揉碎。特别是那些网上文档里根本不会写的东西——比如为什么你的SpringBoot版本一高就各种报错、前后端分离时跨域到底卡在哪、数据库表字段命名怎么影响MyBatis映射，我会结合实操经验逐一说清楚。
1. 项目整体设计与技术选型思路
1.1 拿到源码包之后，先看懂它到底是什么架构
打开任何一个完整交付的音乐网站源码包，通常你会看到三类东西：后端Java工程（一般是Maven结构）、前端页面文件（可能是静态HTML/Thymeleaf模板，也可能是Vue工程）、以及一份word文档（也就是标题里的lw，论文/说明文档）。第一件事不是急着运行，而是先判断这个项目是单体渲染还是前后端分离。判断方法很简单：看src/main/resources/templates下面有没有HTML文件，如果有，说明是服务端渲染；如果后端只是提供接口、前端是独立的dist目录或者单独的Vue工程，那就是前后端分离。
这两种架构的处理方式完全不同。单体渲染版本，静态资源由SpringBoot托管，你只需要改一个application.yml的端口号和数据库连接，然后直接启动；前后端分离版本则需要同时跑两个服务，还要处理跨域、接口前缀、Token传递这些额外问题。从我接手的这类项目看，大多数高校毕设还是以单体+Thymeleaf为主，因为代码量少、答辩好讲，但最近两年SpringBoot+Vue的前后端分离版本也越来越多，因为很多学校开始要求“前后端分离”作为加分项。你应该在动手前花10分钟确认这个定位，否则后面调试方向会完全跑偏。
1.2 为什么这类项目清一色选择SpringBoot
说句实话，音乐网站这个业务场景，用PHP、Python Flask、甚至Node.js都能做，但SpringBoot能成为这类交付项目的绝对主流，核心原因有三点。第一是生态成熟度，Spring Boot整合MyBatis、Spring Security、Redis、Quartz这些常用组件基本是零配置起步，这对开发周期只有几周的学生项目来说是致命的优势；第二是部署形态简单，内置Tomcat，打包成jar直接java -jar就能跑，不需要单独装Web服务器；第三是就业导向，国内Java岗位面试几乎绕不开SpringBoot，所以大家宁愿用更“重”的方案也要把简历技术栈刷绿。
不过这里我要补一个很多教程不会讲的细节：SpringBoot的自动装配原理才是它真正拉开差距的地方。你写一个@SpringBootApplication注解，为什么就能自动扫描到Controller、自动配置数据源、自动加载配置文件？根源在于spring.factories和@EnableAutoConfiguration配合的SPI机制。SpringBoot把所有需要自动配置的类都列在META-INF/spring.factories文件里，启动时通过SpringFactoriesLoader加载，再配合@ConditionalOnClass、@ConditionalOnMissingBean这类条件注解去判断“这个类在不在classpath里”“用户有没有自己定义过Bean”。音乐网站项目里，你能直接用spring-boot-starter-web、mybatis-spring-boot-starter，本质都是这个机制在起作用。如果答辩被问到“SpringBoot是怎么做到自动配置的”，讲清楚这一层，分数档次完全不一样。
1.3 一篇完整“lw”文档到底应该包含什么
这个标题里的“lw”在论文/说明文档语境下，通常意味着你交付的不仅有代码，还有配套的文档和讲解视频。一份合格的lw文档，绝不是把代码贴一遍，而是要讲清楚需求分析、系统设计、数据库设计、实现过程、测试结果这五大部分。实操中我发现大多数人卡在数据库设计这一章，因为画ER图容易，但要解释清楚“为什么用户表和评论表要分开”“为什么歌单表和歌曲表要做中间表”就很难。这恰恰是答辩老师最爱问的地方。
如果你要基于这份源码包写自己的文档，我的建议是先把项目里所有实体类梳理出来，对照数据库脚本逐个核对字段，然后反向画出E-R图。这个过程虽然枯燥，但能帮你快速理解每个表结构存在的意义。音乐网站的数据模型核心其实就是三张主表和若干张关系表：用户表（user）、歌曲表（song）、歌单表（song_list），以及用户收藏歌单、歌单包含歌曲这类多对多关系表。理解了这些，你才能解释索引为什么要建在哪些字段上、为什么评论表和用户表是外键关联。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心功能模块与数据库设计详解
2.1 用户模块：注册登录、Session与安全设计
音乐网站的用户模块看起来简单，无非是注册、登录、退出、个人信息修改，但这里面有个容易被忽略的坑：密码的存储方式。我见过太多项目源码里直接把密码明文存在数据库，或者只用MD5加密一次，这在答辩时是重大扣分点。正确的做法至少是加盐哈希，比如使用BCryptPasswordEncoder。SpringSecurity自带这个加密器，即使你不想引入SpringSecurity全家桶，单独引入spring-security-crypto这个依赖也可以直接用。
实际实现时，注册的逻辑是：前端提交用户名和密码，后端先查一次数据库确认用户名不存在，然后对密码做BCrypt加密，再插入用户表。登录的逻辑是：根据用户名查出用户记录，用BCryptPasswordEncoder的matches方法比对输入的密码和密文是否一致。这里必须注意一个细节——不要自己写比对逻辑，也不要尝试解密，BCrypt本身是不可逆的。很多新手会在登录时把数据库里的密文查出来再加密一次去比对，这属于理解错误。密文比对应该每次都拿你输入的明文去和存储的密文匹配。
对于登录状态的保持，常见做法有两种：Session方式和Token方式。单体渲染项目大多用Session，配合SpringBoot自带的HttpSession即可；前后端分离项目基本都用Token，通常用JWT。JWT的思路是服务端登录成功时签发一个带过期时间的令牌，前端后面每次请求都把它放在请求头里，后端用一个拦截器或过滤器校验令牌合法性。这个校验过程要注意设置白名单——注册、登录、获取歌曲列表这类接口应该放行，而修改个人信息、收藏歌单这类接口才需要校验。
2.2 歌曲与歌单模块：E-R建模和一对多、多对多关系
歌曲是音乐网站的核心数据实体，至少要包含：歌曲ID、歌曲名、歌手名、专辑名、时长、歌词、播放URL（或本地文件路径）、封面图URL、所属分类、播放次数等字段。歌单是用户的组织维度，一个用户可以创建多个歌单，一个歌单可以包含多首歌曲，同时一首歌也可以出现在多个歌单里，所以标准的建模方式是——歌单表song_list、歌曲表song，还有一张中间表song_list_detail（或者叫song_list_song），字段就是主键、歌单ID、歌曲ID、添加时间。
很多人在这一步会省掉中间表，直接在歌单表加一个song_ids字段，用逗号拼接。这在数据量小的时候看不出问题，但一旦做收藏、移除、统计的时候就需要split字符串，性能和查询体验都很差。如果你在代码里看到类似String[] ids = songIds.split(",")这种写法，建议在二次开发时把它重构为标准中间表。另外，歌曲的播放量和歌单的收藏量这类统计字段，如果在首页有排行榜展示，不要每次实时count，直接在表里加一个播放次数字段，播放时+1，页面只查这个字段，性能会好很多。等以后数据量大了，再用定时任务或消息队列去异步更新。
2.3 评论与推荐模块：扩展功能的加分玩法
基础版的音乐网站功能一般停留在听歌和建歌单，但要拿高分，评论、搜索、个人中心、后台管理等扩展功能就很重要。评论模块比较简单，一张评论表：评论ID、歌曲ID（或歌单ID）、用户ID、评论内容、评论时间，复杂一点可以加父评论ID做楼中楼。这里有个容易踩的坑：前端展示评论时需要显示用户昵称而不是用户ID，所以SQL一定要做联表查询，把user表关联进来select出nickname；如果只是直接在Java代码里for循环查用户表，那就是经典的N+1查询问题。
推荐模块则是很多同学不知道怎么下手的地方。最简单可落地的方案是基于用户收藏歌单做协同过滤——找到和你收藏了同样歌单的其他用户，看看他们还收藏了什么别的歌单，把交集推荐给你。这个算法不复杂，写起来也就是几个for循环的事，但听起来效果不错。如果你的项目用了Redis，还可以把推荐结果缓存起来，设置一小时过期，这样接口响应速度飞快，答辩时说“使用Redis缓存层来优化推荐接口性能”，这个点就很有说服力。
2.4 数据表设计时的命名规范和字段类型选择
数据库表设计决定了这个项目后边改起来痛不痛苦。我复盘过很多份音乐网站源码，发现它们踩的坑惊人地相似：表名、字段名不统一，有的用驼峰有的用下划线，然后MyBatis映射配置一会儿开驼峰转换一会儿不开，排查起来烦死人。这里给出一个统一的约定：数据库字段一律用下划线命名，实体类字段一律用驼峰命名，MyBatis全局配置map-underscore-to-camel-case=true，这样两者自动映射，逻辑清晰还不用写一堆resultMap。如果字段名不一致，建议在MyBatis的XML里显式写resultMap，宁可多写几行，也不要为了省事去改实体类字段名。
字段类型选择也有讲究。歌曲时长用int存秒数就行，不要用varchar存“03:25”这种字符串，这样后面计算播放进度、统计总时长会非常痛苦。播放次数、收藏数这类计数用int，评论内容用varchar或text，具体看长度。最容易被忽视的是创建时间字段，建议用datetime类型，并且在后端代码里统一用LocalDateTime去映射，而不是老旧的java.util.Date。MyBatis对LocalDateTime支持很好，但你要确认使用的MyBatis版本不要太老，否则会有类型转换问题。
3. SpringBoot音乐网站核心实现与踩坑记录
3.1 从零搭建SpringBoot项目骨架，版本究竟怎么选
刚才热身时提到“SpringBoot版本太高”是最近大家搜得非常多的问题，我在实操中深有体会。很多人拿到源码包后发现pom.xml里写的spring-boot-starter-parent版本是2.7.x或3.x，而本地JDK是1.8，启动直接报错无法运行，这是因为SpringBoot 3.x要求JDK 17+。如果你是从“源码+部署文档”里拿到一个2.x版本项目，却配了JDK 17，又会遇到一堆javax到jakarta的迁移问题（SpringBoot 3.x把javax.servlet换成了jakarta.servlet）。所以第一步定版本，最简单粗暴的规则是：JDK 1.8对应SpringBoot 2.5~2.7，JDK 17对应SpringBoot 3.0+。我自己的推荐组合是JDK 8 + SpringBoot 2.7.x，因为这个组合兼容性最好，网上资料也最多，遇到问题搜起来容易解决。
确定版本后建Maven工程，关键依赖大概这几个：spring-boot-starter-web（Web功能）、mybatis-spring-boot-starter（数据库访问）、mysql-connector-java（MySQL驱动，注意SpringBoot 2.7管理的是8.0.x版本）、lombok（简化实体类代码）、spring-boot-starter-validation（参数校验）。如果播放和上传需要文件处理，可能还要引入commons-io或hutool，看个人习惯。pom.xml不要一股脑全粘，先保证能启动，再按需添加。
3.2 配置文件里最容易出问题的三项：端口、数据源、文件上传大小
application.yml是整个项目最先要调整的文件，也是部署时最容易出问题的地方。端口配置server.port默认8080，如果你本机8080被占用了，可以改成8081或别的。数据源配置里，spring.datasource.url项必须写对数据库名和时区参数，比如jdbc:mysql://localhost:3306/music?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai。这里的serverTimezone参数非常关键，不设的话连数据库时经常报时区错误。用户名和密码按你本地MySQL的实际配置来改。
文件上传配置是音乐网站特有的重点。上传歌曲MP3、上传封面图这些功能，如果不在配置里调大限制，上传稍微大一点的文件就会报MaxUploadSizeExceededException。SpringBoot 2.x需要在application.yml里配spring.servlet.multipart.max-file-size: 100MB和spring.servlet.multipart.max-request-size: 100MB。如果项目用到了第三方存储（比如阿里云OSS），那还要额外配置accessKey和bucket，这时候注意不要把真实密钥提交到Git仓库，用环境变量占位符比较稳妥。
3.3 登录鉴权的关键代码：拦截器、JWT与ThreadLocal
登录鉴权这块，我建议尽量不依赖SpringSecurity整体框架，因为对毕设项目来说学习成本高、配置复杂，而且网上能搜到的音乐网站SpringSecurity整合教程往往版本差异很大，容易踩坑。自己实现拦截器+Hutool的JWT工具其实就够了。核心步骤是三步：一，写一个LoginInterceptor实现HandlerInterceptor接口，在preHandle中从请求头Authorization里取出Token，解析成功就放行，失败就返回401；二，写一个WebConfig实现WebMvcConfigurer，注册拦截器并设置excludePathPatterns放行登录、注册、歌曲列表等公开接口；三，登录成功后生成Token，把用户ID存进去，后续接口需要当前用户信息时再解析Token得到用户ID。
这里有个进阶技巧：解析Token得到一个userId后，不要每次都去数据库查用户对象，可以在拦截器里把userId通过ThreadLocal存起来，请求结束时再remove。这样一个请求处理链路中的任何地方都能拿到当前用户ID，不用层层传参。ThreadLocal的使用要注意线程池环境下必须remove，否则会有内存泄漏和数据错乱的问题。如果你在一个Controller里new了一个线程或使用了异步任务，ThreadLocal里的值不一定能传过去，这个情况要理解清楚。
3.4 上传和播放音乐时遇到的几个真实坑
音乐上传和播放是实现过程中体验最“实在”的部分，但也是问题高发区。第一个坑是上传文件的保存路径。本地开发时你随便指定一个D:/upload目录就行，但部署到Linux服务器后路径就变了，所以最好在配置文件里用music.upload-path这种自定义属性来设置，代码里通过@Value注入，这样换环境只改配置不动代码。第二个坑是上传后的文件访问。SpringBoot默认的静态资源路径是classpath:/static/，如果你把文件存在了服务器磁盘的其他位置，前端是访问不到的，需要配置映射：写一个WebMvcConfigurer，把/music/**这样的URL映射到实际的磁盘路径。第三个坑是播放时MP3的跨域请求。如果你做了前后端分离，前端是localhost:8081，音乐文件却由localhost:8080提供，播放器请求音频文件属于跨域请求，要在后端加跨域配置，否则前端看着文件存在，但播放器一直不响。
视频/音频流播放还有一个细节：
3.5 MyBatis多表查询：别让N+1问题拖垮你
音乐网站首页通常要展示“最新歌曲”“热门歌单”，每条歌曲又要关联歌手、专辑，每个歌单又要关联创建者昵称。新手最常犯的错误是先用一个select查出列表，然后在循环里再去查关联表，这样数据库被反复查询，列表稍微长一点就慢得不行。这里我的建议是：一是用联表查询，一条SQL把歌曲和歌手信息带出来，MyBatis的resultMap配置association或collection，或者直接查询DTO字段；二是如果要做的页面是首页这种高性能要求的，直接用VO类接收联表查询结果，不要用实体类硬套。
MyBatis的XML文件里写动态SQL也要注意，比如歌曲名称模糊搜索、按分类筛选、排序字段动态传入，这些用
4. 前后端联调、部署上线与文档交付
4.1 前后端联调时的三个关键配置：跨域、接口前缀、请求封装
现在的SpringBoot音乐网站很多都采用了Vue前端加接口后端的方式，联调时最头疼的就是跨域和接口地址问题。先讲跨域，后端最简单的处理方式是在配置类里实现WebMvcConfigurer，重写addCorsMappings方法，配置allowedOriginPatterns为*，allowedMethods为GET,POST,PUT,DELETE,OPTIONS。注意这里有个细节：allowedOrigins("")在携带凭证（credentials为true）时会被浏览器拒绝，所以如果你用了Token但请求头没有带withCredentials，可以用allowedOrigins("")；如果带了凭证，就必须用allowedOriginPatterns或者指定具体域名。否则你会发现前端发请求报了CORS error，后端却看得见请求进来了，这就是凭证和通配符冲突导致浏览器拦截了响应。
接口前缀问题也很容易出岔子。后端Controller定义的是/api/user/login，前端如果走Vue开发服务器的代理，需要在vue.config.js里配置proxy把/api转发到http://localhost:8080。这里常见错误是漏配代理或者配了之后target端口写错，导致请求一直404。建议前端统一封装一个request.js，把baseURL设为"/api"，通过环境变量区分开发和生产，这样部署到服务器时只要改nginx或后端地址即可，不用全项目替换IP。
4.2 把源码跑起来的标准步骤：从导入到访问首页
这里整理一下从零到一跑通项目的标准步骤，适用于绝大多数SpringBoot单体音乐网站。第一步：安装JDK 8或者17（看项目版本），安装MySQL 5.7或8.0，安装Maven 3.6+，安装IDEA或Eclipse。第二步：用IDEA导入源码包里的back-end文件夹（或者项目根目录的pom.xml），等待Maven下载依赖。如果你的Maven用的国内镜像源如阿里云，下载会快很多。第三步：创建一个数据库，名字和application.yml里的一致，然后把源码包里的music.sql导入。导入时注意MySQL版本，如果MySQL 8.0导入5.7的脚本一般没问题，但反过来可能会有语法兼容问题。第四步：修改application.yml里的数据库用户名和密码，确认端口号没被占用。第五步：启动项目的main方法，控制台出现“Started Application in x seconds”说明启动成功。第六步：浏览器访问http://localhost:8080，看到首页说明基本跑通了。
如果你拿到的是前后端分离版本，还要在第四步之后额外启动前端工程。前端一般是npm install安装依赖，然后npm run serve启动开发服务器，默认访问localhost:8081，然后通过代理请求后端。npm install遇到node-sass报错是非常常见的，因为node-sass需要本地编译，建议下载项目时看清楚package.json里用的是sass还是node-sass，如果是node-sass，换成dart-sass（即sass）能避免大量编译问题。
4.3 部署到云服务器：打包、放行端口、守护进程
部署环节是很多同学在答辩前最紧张的一步。SpringBoot打包很简单：在项目根目录执行mvn clean package -DskipTests，target目录下会生成一个jar包，通常是项目名-0.0.1-SNAPSHOT.jar。这个jar内置了Tomcat，可以直接用java -jar xxx.jar启动。但是如果你在本地运行没问题，部署到Linux服务器后访问不了，首先要排查的永远是防火墙和安全组，而不是Java代码。云服务器除了操作系统防火墙（firewalld或ufw），还要在云控制台的安全组规则里放行8080端口。这两个地方任何一个没配置好，都会出现“本地能访问服务器不能访问”的诡异现象。
启动方式上，nohup java -jar xxx.jar > app.log 2>&1 &是最基本的做法，但是日志会无限增长，而且进程管理不方便。更好的做法是写成systemd服务，配置文件放在/etc/systemd/system/music.service，设置WorkingDirectory、ExecStart、Restart=always，然后systemctl daemon-reload && systemctl enable music && systemctl start music。这样即使进程崩溃，systemd也能自动拉起，答辩演示时基本不会出幺蛾子。另外，如果用nginx做反向代理，记得把nginx配置里的proxy_pass设置到http://127.0.0.1:8080，并且处理一下WebSocket（如果项目有聊天室功能），需要加Upgrade和Connection请求头。
4.4 部署文档该怎么看、怎么改写
标题里强调“部署文档”，说明交付时少了这份文档是不完整的。但拿到别人的部署文档，不能直接照抄，因为每个人的服务器环境、数据库密码、路径规划都不一样。我的做法是拿到文档后先把以下几项替换成自己的：数据库连接串和账号；上传文件保存路径；日志文件路径；端口号。然后按文档步骤操作一遍，凡是遇到“此处应出现xxx结果”的，都截图保存下来，这样这份文档就变成了自己的部署手册。答辩时老师如果问部署细节，你直接打开自己的截图讲，比背文本要有说服力得多。
部署文档中最容易被忽略的是环境变量。如果你的项目里配置了数据库密码、OSS密钥这类敏感信息，不要写死在application.yml里，也不要在文档里贴出真实值。用${DB_PASSWORD}这种占位符，然后在服务器/etc/profile或systemd服务里设置环境变量，这样部署文档就算外发，密码也不会泄露。这是工作环境里的标准做法，拿到项目里提前养成习惯，面试聊起来还挺加分。
5. 调试技巧、性能优化与常见问题速查
5.1 本地调试的两板斧：断点日志和接口测试
开发阶段调试SpringBoot音乐网站，最核心的手段其实是两部分：一是IDEA断点调试，二是用Postman或Apifox做接口测试。很多刚接触SpringBoot的同学遇到BUG就只会System.out.println，然后一遍遍重启项目，效率非常低。建议遇到接口返回数据不对时，先在Controller入口和Service方法第一行打上断点，用Debug模式运行，看参数是否传进来了、SQL是否执行了、返回的对象里字段有没有值。Debug时注意看IDEA的Variables窗口，能直接看到数据库查询结果，这样你几乎能立刻定位到是SQL写错了还是参数接收错了。
接口测试方面，我强烈建议把音乐网站的每个接口都用Apifox维护一份。注册接口、登录接口、歌曲列表、上传歌曲，每个接口写好参数和预期返回。这样有两点好处：一是前端还没写好的时候，后端就已经可以自测了；二是答辩前快速回归所有接口，避免演示到一半发现某个功能被你改挂了。如果项目里已经引入了spring-boot-starter-test和JUnit 5，可以再补几个简单的单元测试，比如对用户注册时用户名重复校验的Service方法写一个测试类。不是所有代码都要测，挑几个关键业务逻辑测一下，文档里也好看。
5.2 性能优化：从索引到缓存，哪些值得做
音乐网站这种规模的业务，性能优化不需要一上来就上高深技术，先把几个最基础的做好。第一条是数据库索引。用户表的用户名（登录查）、歌曲表的分类ID和播放次数（列表和排行榜）、评论表的歌曲ID（评论列表），这些字段都要建索引。你可以在MySQL命令行执行EXPLAIN SELECT查看执行计划，看看有没有出现type=ALL的全表扫描，有就说明缺索引。第二条是缓存。把首页的推荐歌单和热门歌曲做成Redis缓存，key比如hot:songs:1h，value是JSON串，过期时间3600秒。这样数据库压力小很多，接口响应时间能降低一个量级。第三条是SQL优化。避免select *，只查需要的字段；不要在where条件里的字段上做函数运算，比如WHERE YEAR(create_time)=2023会让索引失效；limit分页尽量用主键或唯一索引做游标分页，而不是offset越大越慢的普通分页。
第三种优化方案如果要在项目里落地，注意处理缓存穿透和缓存雪崩。音乐网站的推荐接口如果缓存失效，突然大量请求同时打到数据库，容易一下子把MySQL搞垮。简单加一个空值缓存（缓存“无数据”而不是不缓存）和一个随机过期时间，就能规避大部分问题。讲到这里顺带提一句：不要在这个项目里过度设计，比如为了“性能优化”就去引入微服务、消息队列，对一个单机部署的音乐网站来说，这反而是为答辩埋雷。
5.3 常见报错速查：大家踩过的坑都在这里
下面整理了一份音乐网站SpringBoot项目中高频出现的报错和解决方案，几乎每一类我都见过有人在一个群里来回问三遍。
| 报错信息 | 最常见原因 | 解决方法 |
|---|---|---|
| java.sql.SQLException: Unknown database 'music' | 数据库没建，或配置文件里的库名和实际不一致 | 在MySQL执行CREATE DATABASE music，然后重新导入SQL |
| java.sql.SQLException: Access denied for user 'root'@'localhost' | 数据库用户名或密码错误 | 核对application.yml里的用户名密码，注意MySQL 8.0默认认证插件和密码策略 |
| Server returns invalid timezone. Go to 'Advanced' tab | MySQL时区设置问题 | 在连接串加serverTimezone=Asia/Shanghai，或执行set global time_zone='+8:00' |
| ClassNotFoundException: javax.xml.bind.JAXBException | JDK版本太高（11+），缺少JAXB模块 | 换JDK 8，或者引入javax.xml.bind:jaxb-api依赖 |
| Failed to start bean 'documentationPluginsBootstrapper' | SpringBoot 2.6+和Swagger版本冲突 | 在application.yml加spring.mvc.pathmatch.matching-strategy=ant_path_matcher |
| Whitelabel Error Page | 后端接口异常或404 | 看控制台完整异常栈，对照Controller里的@RequestParam和前端传参是否一致 |
| Cannot resolve symbol 'LocalDateTime' | JDK版本过低或Lombok版本老 | 升级JDK到8+，或调整Lombok版本 |
| org.apache.ibatis.binding.BindingException: Invalid bound statement | Mapper接口和XML映射路径对不上 | 检查MyBatis的mapper-locations配置，以及XML的namespace是否完整 |
| 前端访问接口跨域 | 后端未配置CORS或配置了凭证但用了allowedOrigins("*") | 按上文4.1节修改CORS配置 |
| 上传文件时连接被重置 | nginx默认client_max_body_size太小 | nginx配置加client_max_body_size 100m |
这些报错里，最隐蔽的是那种“明明代码看起来没问题，就是跑不通”的情况，比如SpringBoot启动时报循环依赖。循环依赖在SpringBoot 2.6之后默认是禁止的，会出现BeanCurrentlyInCreationException。如果你是从旧项目升上来的，直接在配置里spring.main.allow-circular-references=true可以临时解决，但更根本的办法是重构代码，把A依赖B、B依赖A的循环结构，通过提取公共Service或懒加载（@Lazy）来打破。音乐网站项目里循环依赖一般出现在Service层互相调用时，比如UserService和SongService都调用了对方的某方法，设计阶段画出依赖关系就能避免。
5.4 答辩/交付前的最终检查清单
最后分享一个我每次交付项目前都会过一遍的检查清单，照着查能帮你避开绝大部分尴尬场景。第一，功能演示路径要顺畅：从注册新用户开始，登录、搜索歌曲、播放、收藏歌单、发表评论，一条主流程走完，确保中间没有断点。第二，异常输入要兜底：注册时重复用户名、上传非MP3文件、搜索框中输入特殊符号，这些场景如果后端没有做校验，很容易现场翻车。建议在Controller参数上用@Validated加注解，在Service做好手动判断，返回统一的Result对象。第三，数据库脚本要干净：交付的SQL文件最好是能直接执行、不会报错的版本，别把自己测试用的一堆脏数据也导进去。第四，端口和账号要写在文档顶部：运维或老师接手时，第一件事就是看端口和数据库账号，找不到会很抓狂。第五，代码里不要留调试痕迹：System.out.println、本地绝对路径、测试邮箱地址等，能清就清。
个人体会是，这类SpringBoot音乐网站项目的价值不在于功能多复杂，而在于它是一个麻雀虽小五脏俱全的完整闭环——从前端页面到后端接口、从数据库设计到部署上线，一个项目里你能练到全栈的每一个环节。源码包里已经给你的只是地基，要真正让它变成“自己的项目”，动手改两个模块、补一个功能、写一遍部署文档，比看十遍短视频教程要有用得多。这也是我每次收到这类咨询都建议对方先读代码再动手的原因：源码是引子，琢磨透了才是你的。