企业官网建设流程全解析

简介：面向计算机专业毕业设计选题与开发落地的精品项目资料包，适合正在确定课题、搭建系统或准备答辩的本科生与初学者使用。内容围绕“源码+论文”组织，汇集多套可参考的毕设项目材料，可用于选题对比、技术路线梳理、功能模块拆解与论文写作借鉴，也便于在现有代码基础上做二次开发。压缩包共2002个文件，整体约432.77MB，以1201个md文档、502个js脚本、174个json配置、86个py程序及少量h、xml、html等文件为主，分别对应项目说明、论文资料、前后端代码、配置数据与页面结构，目录体量较完整，适合按模块检索。已有907人学习下载，说明其在毕设选题场景中具有一定参考热度。读者可从中获取项目源码、论文文档与配置脚本等材料，结合自身课题快速理解系统结构、梳理实现思路，并为开题、开发和答辩准备提供较实用的参考样本。

1. 一套完整方案解决毕业设计季的常见问题

答辩前一周，A同学抱着笔记本冲进实验室：毕业设计系统在自己的机器上能跑，换台电脑就白屏，论文里的模块图跟源码对不上，指导老师问一句“这个功能在哪个类里”就卡壳。这种场面每年五月都在重演，根源并不在技术难度，而在于手里的工程是残缺的：有代码没脚本，有脚本没文档，有文档但跟代码两回事。

这套精品毕设项目分享包针对的正是这类问题。它既不是零散代码片段，也不是单个演示程序，它是一批按「源码 + 数据库脚本 + 论文 + 部署说明」四件套打包的完整项目，覆盖 Java Web 管理系统、Python 数据处理、小程序与浏览器插件几类常见课题，每个目录都能独立编译、独立启动。适合三类人：选题还没定、想先看别人怎么把需求拆成模块的；系统跑不起来、需要一份可对照的完整工程的；论文写了一半、想找模块划分和表结构参照的。拿到压缩包只是开始，下面按我实际拆包的顺序讲：目录怎么组织、第一个项目怎么跑通、核心链路怎么读、出了问题按什么顺序查、最后怎么改成自己的东西。

2. 项目全景拆解：从解压目录到论文附件的四层结构

拿到压缩包，第一件事不是双击运行，而是先弄清楚里面有什么、哪部分是代码、哪部分是文档。我的习惯是解压到不含中文和空格的路径，比如D:/gproject/，因为很多老工程的 Maven 插件和 Node 脚本对中文路径处理得很糟糕，路径里带个空格就能让构建卡在某个莫名其妙的步骤上，这种问题排查起来非常费时。解压完先别急着打开 IDE，用文件管理器把顶层目录过一遍，心里有个目录结构，后面挑项目才不会挑到半成品。

2.1 解压后先理清结构：四层目录与文件清单

一套整理得比较规范的方案，目录通常是这个形状：顶层是按编号加课题名分的项目文件夹，每个文件夹里再分源码区、数据库区、文档区。编号不是随便排的，一般按技术栈或者难度递增，前面的偏基础管理类，后面的带一点业务复杂度。我拆过的几个包里，能直接跑的比例大概七成，剩下三成要么缺 SQL，要么依赖的某个 jar 包没打进去，所以先做一次完整度体检很必要。

单个项目内部的典型文件清单是这样的：

看到某个项目缺sql目录，先别急着放弃，有些作者会把建表语句直接塞在doc里的文档附录，或者写成resources/schema.sql。这种情况我一般全文搜一下CREATE TABLE，能搜到就还有救。

2.2 技术栈分布：Java Web、Python 与小程序三条主线

整包里的项目大致分三条线，选哪条取决于你熟悉什么、答辩时能讲清楚什么。Java 线占比最高，基本是 Spring Boot 或 SSM 加 MyBatis 加 MySQL，前端配 Vue 加 Element UI，这类项目结构规整、分层清晰，答辩时从 Controller 讲到 Service 再讲到 Mapper，逻辑链完整，是最稳的选择。Python 线多是 Django 或 Flask，配上 pandas 做统计分析、或者带一点爬虫采集，代码量小，但答辩时容易被追问算法细节。第三条是小程序和浏览器插件，前端占比大，后端往往很薄甚至直接调云函数。

三条线的差异我整理成一张表，选课题的时候可以直接对着看：

我的建议是：如果只剩两个月，选 Java 线里最基础的那套，把跑通和改功能做扎实，比硬啃一个花哨但跑不起来的有用得多。答辩老师看的不是你用了多新的框架，而是你能不能把一条业务链路从头讲到尾。

2.3 论文与源码怎么对应：模块图、表结构、接口清单

这是最容易出问题的一环。论文里的功能模块图通常是三层树状图，最底层的叶子节点应该能一一对应到代码里的 Controller 或者 Service 方法。核对方法很直接：打开论文的模块图，把叶子节点名字抄下来，去src/main/java下按包名找，找不到就说明论文和代码不是一套，或者作者写论文时把功能写多了。

表结构核对更简单，论文的“数据库设计”章节一般会给 E-R 图和表字段说明，把表名列表和sql脚本里的CREATE TABLE对一遍，字段数量、主外键关系对不对得上，五分钟就能判断这套材料是不是原配。接口清单则看 Controller 上的@RequestMapping注解，或者工程里有没有集成 Swagger，有的话直接访问/doc.html或/swagger-ui.html，所有接口一目了然。

提示：论文和代码对不上是常见现象，不必惊慌。缺的功能如果只是论文里写了、代码里没有，你自己补一个简单的增删改查接口，反而成了答辩时可以主动讲的“我做的扩展”。

2.4 用一段脚本整理整包索引

项目一多，光靠眼睛记不住哪个能跑、哪个缺 SQL。我一般会写个十几行的小脚本，扫一遍目录，输出一张索引表，后面挑项目就照着这张表挑。这种脚本不需要多健壮，能跑出结果就行。

# 扫描解压后的根目录，给每个项目打上技术栈和完整度标签 import os ROOT = "./毕设项目合集" # 换成你实际的解压路径 STACK_HINT = { "pom.xml": "Java/Maven", "build.gradle": "Java/Gradle", "requirements.txt": "Python", "manage.py": "Django", "package.json": "Node/前端", "manifest.json": "浏览器插件", } rows = [] for name in sorted(os.listdir(ROOT)): path = os.path.join(ROOT, name) if not os.path.isdir(path): continue hits, has_sql, has_doc = set(), False, False # 只往下走两层，避免扫进 node_modules 拖慢速度 for cur, dirs, files in os.walk(path): if cur.count(os.sep) - path.count(os.sep) > 2: dirs[:] = [] continue for f in files: if f in STACK_HINT: hits.add(STACK_HINT[f]) if f.endswith(".sql"): has_sql = True if f.lower().endswith((".doc", ".docx", ".pdf", ".ppt", ".pptx")): has_doc = True rows.append((name, "/".join(sorted(hits)) or "未知", has_sql, has_doc)) for name, stack, has_sql, has_doc in rows: flag = "可跑" if (has_sql and stack != "未知") else "待查" print(f"{name:<28}{stack:<16}SQL:{str(has_sql):<6}DOC:{str(has_doc):<6}{flag}")

这段脚本里，STACK_HINT是技术栈判定的依据文件，pom.xml出现基本就是 Maven 工程，manage.py出现就是 Django。os.walk里限制了两层深度，因为前端工程的node_modules动辄几万个文件，全扫一遍能等上好几分钟。最后输出的flag列只是粗筛：有 SQL 又有技术栈线索的标“可跑”，其余的标“待查”，并不代表一定跑不起来，只是需要人工再确认一遍。跑完把输出存成index.txt，挑项目时对照着看，能省掉大量反复解压的时间。

3. 首个项目跑通：以一套 Spring Boot 管理系统为例走完启动流程

索引表列出来之后，挑第一个练手的项目。我建议选结构最标准的 Spring Boot 加 MySQL 那套，依赖少、启动快、报错信息也容易看懂。下面这套流程是我这些年反复用的顺序：先对版本，再建库，再改配置，最后按清单验证。跳过任何一步，后面都可能多花两小时。整个过程大概四十分钟，其中二十分钟是在等依赖下载。

3.1 版本对齐：JDK、Maven、MySQL 三件套

版本不匹配是启动失败的头号原因，而且报错信息往往指向别处，让人误判。常见情况是工程用 JDK 8 写的，本机装的是 JDK 17，编译时冒出一堆module java.base does not export或者 Lombok 相关的NoSuchFieldError。反过来，工程用了 JDK 17 的新语法，本机是 JDK 8，那就是一片红色波浪线。

开始前先在命令行确认三件事：

java -version # 看 JDK 主版本，老工程多为 1.8 mvn -v # 看 Maven 是否配置了正确的 JAVA_HOME mysql --version # 看 MySQL 是 5.7 还是 8.x

看pom.xml里的<java.version>或者<maven.compiler.source>，跟本机 JDK 对上再往下走。MySQL 的版本差异主要体现在驱动包上：5.7 用com.mysql.jdbc.Driver，8.x 用com.mysql.cj.jdbc.Driver，连接串参数也不一样。如果本机是 8.x 而工程写的是老驱动，最简单的解法是改pom.xml里的mysql-connector-java版本到 8.0.x，然后同步改连接串，别想着装个 5.7 迁就它，装完还有编码和时区一堆事。

注意：如果你机器上装了多个 JDK，JAVA_HOME指向哪个，Maven 就用哪个，跟java -version显示的未必一致。改完环境变量记得重开一个终端窗口，旧窗口里的变量不会刷新。

3.2 建库导入数据：SQL 脚本的两种导入方式

数据库这一步，我见过太多人直接在图形化工具里打开 SQL 文件全选执行，结果脚本里没有CREATE DATABASE和USE语句，表全建到了默认库里，程序启动时报“表不存在”。正确做法是先看一眼脚本头部有没有建库语句，没有就自己建。

命令行方式最稳，两条命令解决：

# 显式指定字符集，避免中文数据导入后变问号 mysql -uroot -p123456 -e "CREATE DATABASE graduation_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;" # 把脚本导入指定库，注意不要在脚本里再写 USE mysql -uroot -p123456 graduation_db < sql/graduation_db.sql

导入完别急着启动，先验证一下表和数据的数量：

USE graduation_db; SHOW TABLES; -- 表数量应该和论文里写的一致 SELECT COUNT(*) FROM sys_user; -- 初始账号一般在 1~3 条 SELECT table_name, table_comment FROM information_schema.tables WHERE table_schema = 'graduation_db'; -- 顺带看一眼中文注释有没有乱码

如果table_comment显示成一堆问号，说明客户端字符集没对上，导入时用的连接不是 utf8mb4，重导一遍即可，别指望后面改配置能救回来，数据已经写坏了。

图形化工具也不是不能用，Navicat 和 DBeaver 都支持“运行 SQL 文件”，但要在连接属性里把编码设成 UTF-8，并且勾选“遇到错误继续”之外的选项时想清楚，脚本中途报错停下来比静默跳过好排查。

3.3 改配置与启动：application.yml 里必须改的四个参数

配置文件通常在src/main/resources/application.yml或application.properties。需要改的地方不多，但每一项都影响能不能起来。

server: port: 8089 # 答辩机 8080 常被占，换一个省事 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver # serverTimezone 不写，8.x 驱动启动就抛时区异常 # allowPublicKeyRetrieval 不写，某些账号认证方式下连不上 url: jdbc:mysql://127.0.0.1:3306/graduation_db?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&useSSL=false username: root password: 123456 servlet: multipart: max-file-size: 10MB # 默认 1MB，传论文附件直接 500 max-request-size: 20MB mybatis: mapper-locations: classpath:mapper/*.xml # 路径写错，启动报 Invalid bound statement type-aliases-package: com.example.graduation.entity pagehelper: helper-dialect: mysql # 方言不填，分页会退化成全表查询 reasonable: true # 页码越界时自动纠正到首页或末页

四个必改项分别是：端口、数据库连接串、账号密码、文件上传大小。serverTimezone和allowPublicKeyRetrieval是 MySQL 8 驱动的两个关键参数，缺一个就连不上，报错信息还都指向“Communications link failure”，看不出是参数问题。reasonable: true这个配置很实用，前端传个pageNum=0或者超出总页数，它自动纠正，不会返回空列表让前端以为没数据。

改完就可以打包启动了：

mvn clean package -DskipTests # 跳过测试，很多毕设工程的测试类本身就跑不过 java -jar target/graduation-1.0.0.jar

-DskipTests这个参数几乎是必须的，因为不少工程的单元测试是模板生成的，或者依赖了本地才有的数据，打包时必然失败。跳过测试不影响运行，但答辩前最好还是把测试类删掉或者补完，免得老师翻代码时问一句“你这测试怎么是空的”。

3.4 验证清单：登录、列表、上传三个动作

看到控制台打出Started Application in x seconds只能说明容器起来了，业务通不通还得手动点一遍。我固定按三个动作验证，覆盖了鉴权、查询、文件三条主链路：

第一，打开http://127.0.0.1:8089，用README里的默认账号登录，能进首页说明拦截器和 session 或 token 逻辑是通的。第二，进任意一个列表页，翻到第二页，能正常出数据说明分页插件生效了，如果第二页和第一页数据一样，就是PageHelper没起作用。第三，找一个带上传的入口，传一张小图和一份 PDF，两个都成功说明 multipart 配置没问题。

三个动作里任何一个失败，都别急着改代码，先看浏览器 F12 的 Network 面板：状态码 401 是鉴权问题，404 是路径或静态资源映射问题，500 就去控制台看堆栈的第一行Caused by，那里才是真正的错误源头，上面那一堆只是调用链。

4. 核心链路拆解：登录鉴权、分页查询与文件上传的三段实现

项目跑起来之后，接下来要读懂代码。一套管理系统动辄上百个类，全看一遍不现实，也没必要。答辩老师最爱追问的其实是几条主干链路：用户怎么登录进来的、列表数据怎么查出来的、文件怎么存进去的。这三条链路读透了，剩下的增删改查都是同一个模式，照着套就行。下面按我读代码的顺序，把这三段拆开讲。

4.1 登录鉴权：从 JWT 签发到拦截器校验的完整链路

登录本身不难，难的是登录之后每个请求怎么证明“我是我”。这套方案里的项目大多用 JWT，流程是：登录接口校验账号密码，成功后签发一个 token 返回给前端，前端存起来，之后每次请求都带在Authorization头里，后端用拦截器统一校验。

先看拦截器这一端，这是整条链路的关卡：

@Component public class AuthInterceptor implements HandlerInterceptor { @Autowired private JwtUtil jwtUtil; @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 浏览器的跨域预检请求不带 token，直接放行，否则永远跨域失败 if ("OPTIONS".equalsIgnoreCase(request.getMethod())) { return true; } String header = request.getHeader("Authorization"); if (header == null || !header.startsWith("Bearer ")) { writeJson(response, 401, "未登录"); return false; } try { // 去掉 "Bearer " 前缀再解析，前缀是前端加的，别一起塞进解析器 Claims claims = jwtUtil.parse(header.substring(7)); // 把用户信息挂到 request 上，Controller 里直接取，避免重复查库 request.setAttribute("userId", claims.get("userId", Integer.class)); request.setAttribute("role", claims.get("role", String.class)); return true; } catch (ExpiredJwtException e) { writeJson(response, 401, "登录已过期"); return false; } catch (Exception e) { writeJson(response, 401, "凭证无效"); return false; } } // 统一输出 JSON，前端拦截 401 后跳登录页 private void writeJson(HttpServletResponse resp, int code, String msg) throws IOException { resp.setStatus(code); resp.setContentType("application/json;charset=UTF-8"); resp.getWriter().write("{\"code\":" + code + ",\"msg\":\"" + msg + "\"}"); } }

这段代码有三个细节值得说。第一，OPTIONS请求必须放行，这是跨域预检，浏览器不会给它带自定义头，拦下来就是“跨域失败”但实际是鉴权失败，非常容易误判。第二，token 前缀Bearer是前端拼的，解析时要substring(7)切掉，切错位置会得到一个格式错误的字符串，抛出的异常还看不出原因。第三，把userId和role塞进request属性，后面业务代码直接request.getAttribute("userId")取，省掉一次数据库查询，也让 Service 层不必依赖登录上下文。

拦截器写好了还得注册，并且要配白名单：

@Configuration public class WebConfig implements WebMvcConfigurer { @Autowired private AuthInterceptor authInterceptor; @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(authInterceptor) .addPathPatterns("/api/**") // 只拦业务接口 .excludePathPatterns( "/api/auth/login", // 登录本身不能拦 "/api/auth/register", "/api/common/**", // 验证码、字典数据 "/upload/**" // 已上传的静态资源 ); } }

addPathPatterns用/api/**而不是/**，是为了把静态资源和上传文件排除在外，否则页面加载一张图片都要带 token，浏览器做不到。excludePathPatterns里最容易漏的是/api/common/**，验证码接口被拦了，登录页就永远刷不出验证码，用户以为系统坏了。

4.2 分页查询：PageHelper 的插入位置与失效场景

分页是列表页的核心，也是新手最容易写错的地方。这个方案里的 Java 项目基本都用 PageHelper，用法看着简单，但有一个很关键的约束：startPage只对紧跟其后的第一条查询生效。

@GetMapping("/page") public Result<PageInfo<UserVO>> page( @RequestParam(defaultValue = "1") Integer pageNum, @RequestParam(defaultValue = "10") Integer pageSize, @RequestParam(required = false) String keyword) { // 必须紧贴查询，中间不能插别的 SQL 调用 PageHelper.startPage(pageNum, pageSize); List<UserVO> list = userService.listByKeyword(keyword); // PageInfo 里带了 total、pages、hasNextPage，前端分页组件直接吃 PageInfo<UserVO> pageInfo = new PageInfo<>(list); return Result.ok(pageInfo); }

对应的 Mapper XML 里不要自己写LIMIT，写了就跟插件打架，最终 SQL 会变成LIMIT ?, ? LIMIT ?，直接语法错误。正确的写法是只写WHERE条件，ORDER BY可以写，插件会自己在外面套一层LIMIT。

<select id="listByKeyword" resultType="com.example.graduation.vo.UserVO"> SELECT u.id, u.username, u.real_name, u.role, u.create_time FROM sys_user u <where> <if test="keyword != null and keyword != ''"> AND (u.username LIKE CONCAT('%', #{keyword}, '%') OR u.real_name LIKE CONCAT('%', #{keyword}, '%')) </if> </where> ORDER BY u.create_time DESC </select>

失效场景主要有三个：startPage后面跟着的第一条查询不是你想分页的那条；在 Service 里先查了别的表再调分页方法；或者用了@Transactional加异步，线程上下文里PageHelper的本地变量丢了。判断方法很简单，把 MyBatis 的 SQL 日志打开，看实际执行语句里有没有LIMIT，没有就是没生效。

pageSize这个参数建议在 Controller 里加个上限，比如超过 100 就强制改成 100。不然前端传个pageSize=100000，等于全表捞出来再内存分页，答辩演示时数据库数据少看不出来，真实场景就是一次慢查询。

4.3 文件上传：后缀校验、UUID 命名与路径陷阱

上传功能代码不长，坑却很密。最常见的两个问题是文件名冲突导致覆盖，以及相对路径被解析到 Tomcat 临时目录，重启后文件全没了。

@PostMapping("/upload") public Result<String> upload(@RequestParam("file") MultipartFile file) throws IOException { if (file.isEmpty()) { return Result.fail("文件为空"); } String original = file.getOriginalFilename(); // 后缀白名单，别用黑名单，绕过的办法太多了 String suffix = original.substring(original.lastIndexOf(".")).toLowerCase(); List<String> allow = Arrays.asList(".jpg", ".png", ".pdf", ".doc", ".docx"); if (!allow.contains(suffix)) { return Result.fail("不支持的文件类型"); } // UUID 重命名，避免同名覆盖，也避免中文名在部分容器下乱码 String name = UUID.randomUUID().toString().replace("-", "") + suffix; // 用绝对路径，相对路径会落到 tomcat 临时目录，重启即丢 Path target = Paths.get(uploadDir).resolve(name).toAbsolutePath(); Files.createDirectories(target.getParent()); file.transferTo(target.toFile()); // 返回可访问的相对 URL，前端拼上域名即可预览 return Result.ok("/upload/" + name); }

uploadDir一般从配置文件读，别硬编码。Paths.get(uploadDir).resolve(name).toAbsolutePath()这行的toAbsolutePath()是关键，MultipartFile.transferTo传相对路径时，Spring 会相对于临时目录解析，表现就是“上传成功但页面 404”，重启之后文件彻底消失。这个坑我踩过一次，排查了快一个小时才反应过来。

后缀白名单也别偷懒用endsWith判断整个文件名，a.jsp.jpg这种双后缀在某些容器配置下会被当成 jsp 解析，虽然现在的 Spring Boot 内嵌容器默认不解析，但答辩老师看到代码里没有校验，问一句就挺尴尬。

对应的静态资源映射也要配上，不然上传完访问不到：

@Override public void addResourceHandlers(ResourceHandlerRegistry registry) { // 把 /upload/** 映射到磁盘目录，注意结尾的斜杠不能少 registry.addResourceHandler("/upload/**") .addResourceLocations("file:" + uploadDir + "/"); }

file:前缀表示磁盘路径而非 classpath，结尾的斜杠必须保留，少了斜杠在某些系统上会拼错路径。

4.4 Excel 导出：响应头与输出流的两处细节

导出功能在管理系统里出场率很高，成绩表、用户名单都要导出。用 EasyExcel 写起来代码很短，但响应头和流的处理有两处必须注意。

@GetMapping("/export") public void export(HttpServletResponse response) throws IOException { response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"); response.setCharacterEncoding("utf-8"); // 文件名必须 URL 编码，中文名不编码在部分浏览器下会变成乱码 String fileName = URLEncoder.encode("成绩表", "UTF-8").replaceAll("\\+", "%20"); response.setHeader("Content-Disposition", "attachment;filename*=utf-8''" + fileName + ".xlsx"); List<ScoreExportVO> data = scoreService.listForExport(); // 直接写 response 的输出流，不要手动 close，容器负责关闭 EasyExcel.write(response.getOutputStream(), ScoreExportVO.class) .sheet("成绩") .doWrite(data); }

第一处是文件名编码，URLEncoder.encode之后要把+替换成%20，否则文件名里的空格会变成加号。第二处是流不要手动关，response.getOutputStream()由容器管理，自己关了会导致响应截断，下载下来的文件打不开，报“文件已损坏”。

导出实体类上要用注解指定表头：

public class ScoreExportVO { @ExcelProperty("学号") private String studentNo; @ExcelProperty("姓名") private String realName; @ExcelProperty("课程") private String courseName; @ExcelProperty("分数") private BigDecimal score; }

@ExcelProperty的 value 就是最终表头文字，顺序按字段声明顺序来。要调整列宽或者加样式，可以在doWrite之前加.registerWriteHandler(...)，但答辩演示没必要搞太花，能正常导出、表头对得上就够。

5. 避坑与排查：跑不起来时按这张顺序表往下查

跑不通的时候最忌讳乱改。我见过有人一遇到启动失败就开始删依赖、换 JDK、重装数据库，改到最后自己都不知道哪一步起了作用。正确的做法是按阶段排查：启动阶段看日志第一行，数据阶段看连接和字符集，联调阶段看浏览器 Network。下面这几条是我在不同项目上反复遇到的，每条都按现象、原因、解决三段记，照着对号入座就行。

5.1 启动阶段：端口占用、JDK 错配与依赖拉不下来

现象一：控制台报Port 8080 was already in use，或者启动到一半自动退出，没有任何异常堆栈。

原因通常是上一个进程没杀干净，或者本机装了别的服务占了 8080。Windows 上更隐蔽的情况是端口被系统保留区占用，netstat看不到任何进程，但就是绑不上。

解决分两步。先查占用：

# Windows netstat -ano | findstr :8080 # Linux / macOS lsof -i :8080

查到 PID 就taskkill /PID xxx /F或kill -9。查不到进程说明是保留端口，直接把application.yml里的server.port改成 8089 或 9090，比跟系统较劲快得多。答辩现场换端口还能顺手讲一句“端口冲突的处理”，算是加分。

现象二：编译报NoSuchFieldError、NoClassDefFoundError，或者 Lombok 的@Data全红。

原因是 JDK 版本和工程不匹配。Java 8 的工程用 JDK 17 编译，Lombok 老版本会直接崩；反过来 JDK 17 的工程用 8 编译，var、record这些语法不认。

解决办法是看pom.xml里的<java.version>，把 IDE 的 Project SDK 和 Maven 的JAVA_HOME都调成一致的版本。IDEA 里要改三处：Project Structure 的 SDK、Settings 里的 Java Compiler 版本、Maven Runner 的 JRE。三处不一致就会出现“命令行能打包、IDE 里全红”的灵异现象。

提示：如果实在对不齐，可以在pom.xml里把 Lombok 升到 1.18.24 以上，它对高版本 JDK 兼容更好，改一行版本号往往比折腾环境快。

5.2 数据阶段：中文乱码、时区报错与主键不连续

现象三：页面上的中文全变成???，或者导入数据后查询结果里带问号。

原因分两种。一种是数据库或表本身不是 utf8mb4 字符集，另一种是连接串里没写characterEncoding=utf8。前者是存的时候就坏了，后者是取的时候坏了，表现一样但修法不同。

先查库和表的字符集：

SELECT default_character_set_name FROM information_schema.schemata WHERE schema_name = 'graduation_db'; SHOW CREATE TABLE sys_user;

如果库是latin1，那就得重建库再导一遍数据，改表字符集救不回已经写坏的内容。如果库是对的，那就是连接串问题，补上useUnicode=true&characterEncoding=utf8即可。MySQL 8 默认字符集已经是 utf8mb4，反而是老项目从 5.7 迁过来时容易出这个问题。

现象四：启动时报The server time zone value 'xxx' is unrecognized。

这是 MySQL 8 驱动的经典报错，连接串里少了serverTimezone。补上serverTimezone=Asia/Shanghai就好。这个参数除了消除报错，还影响datetime字段的读写，不写的话存进去的时间可能差 8 小时，演示时“创建时间”显示成前一天晚上，看着很怪。

现象五：新增数据后主键跳号，或者插入报主键重复。

原因通常是建表时用了自增主键，但初始数据里手写了很大的 id，自增计数器没跟上；或者是用了AUTO_INCREMENT=1但表里有历史数据。解决方法是执行ALTER TABLE 表名 AUTO_INCREMENT = 当前最大id + 1;，或者干脆把自增起始值设成一个安全的数。有些项目为了演示好看，初始数据 id 写到 1000 多，自增还从 1 开始，插几条就撞了。

5.3 联调阶段：跨域、401 循环跳转与静态资源 404

现象六：前端调接口报CORS policy，Network 里请求状态是(failed)或者 200 但被浏览器拦掉。

原因是前后端分离部署，端口不同就是跨域。注意跨域拦截发生在浏览器侧，后端日志里可能什么错都没有，看着像“请求没发出去”。

解决方式有两种。开发阶段用后端配CorsConfig：

@Configuration public class CorsConfig { @Bean public CorsFilter corsFilter() { CorsConfiguration cfg = new CorsConfiguration(); // 用 allowedOriginPatterns 而不是 allowedOrigins，后者配 * 时和凭证冲突 cfg.addAllowedOriginPattern("*"); cfg.addAllowedHeader("*"); cfg.addAllowedMethod("*"); cfg.setAllowCredentials(true); UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); source.registerCorsConfiguration("/**", cfg); return new CorsFilter(source); } }

注意allowCredentials(true)和allowedOrigins("*")不能同时用，会报“凭证模式下不允许通配源”。用allowedOriginPatterns可以绕开这个限制。生产环境当然要收紧到具体域名，但毕设演示阶段这样配没问题，答辩时能说出这个区别反而是加分项。

现象七：登录成功后不停跳回登录页，或者所有接口都返回 401。

原因是 token 存了但没带上，或者带了但后端解析失败。常见于前端请求拦截器写错，比如把 token 存在localStorage里但请求头取的是sessionStorage；也可能后端拦截器的白名单漏了登录接口，导致登录请求本身被拦。

排查步骤是先看 Network 里登录请求和后续请求的Authorization头，有没有值、格式对不对（应该是Bearer xxx）。再看后端拦截器的excludePathPatterns是否包含登录路径。最后看 token 的过期时间，有些工程签发时写死 30 秒，演示到一半就过期了，改长一点。

现象八：上传的图片显示不出来，Network 里 404，但文件确实在磁盘上。

原因是静态资源映射没配，或者配了但路径拼错。检查addResourceHandlers里的addResourceLocations是不是file:开头、结尾有没有斜杠。另外前端拼 URL 时要注意别把后端的 context-path 丢掉，/upload/xxx.jpg和/api/upload/xxx.jpg是两回事。

还有个隐蔽情况：文件在 Windows 上路径用反斜杠，存进数据库后返回给前端，浏览器解析成别的路径。解决办法是存库时统一存相对 URL，不要存绝对路径，可移植性也好。

6. 二次开发改造：把一套毕设工程改成能讲二十分钟的作品

跑通只是底线。真正让答辩有东西可讲的，是在原工程上做出能说清楚的改动。改什么、改到什么程度，得有个取舍，不是功能越多越好。

我的建议是先做权限，再做日志，这两个改动都是“横切”的，能串起整套代码的调用链。权限改造的落点在拦截器里加一层菜单校验：登录时把用户的角色和菜单权限一起查出来放进 token 或者缓存，拦截器里根据请求路径匹配菜单表，没权限直接返回 403。改完你就能讲清楚“一个请求从进入到被拒绝，中间经过了哪几个环节”，这个问题能撑满五分钟。

日志改造的落点是 AOP。写一个@Log注解，切面里拿方法名、参数、耗时、当前用户，异步写进日志表。代码不到五十行，但涉及到注解、切面、线程池三个知识点，老师问起来有得聊。

@Aspect @Component public class LogAspect { @Autowired private LogService logService; // 只切带自定义注解的方法，避免全量拦截拖慢性能 @Around("@annotation(com.example.graduation.annotation.Log)") public Object around(ProceedingJoinPoint point) throws Throwable { long start = System.currentTimeMillis(); Object result = point.proceed(); long cost = System.currentTimeMillis() - start; // 异步落库，不阻塞主流程 logService.saveAsync(point.getSignature().getName(), cost); return result; } }

改造完一定要回归验证，别只测新功能。原来的增删改查、分页、上传都得重新点一遍，权限改错最容易导致老功能 403。我一般的做法是改之前先录一段完整操作的录屏，改完对着录屏一步步走，哪一步不一样就停下来查。

血泪经验是：改之前一定先备份一份原始工程，压缩包改名加日期，别在原目录上直接改。我第一次改这类项目时没备份，权限配错导致所有接口 403，又找不到改回哪里，最后重新解压从头配了一遍。从那以后我每次动核心配置前都强制走一遍“复制目录 + 改副本”的流程，慢三十秒，省三小时。希望帮到你。

本文还有配套的精品资源，点击获取