手工艺展示平台这个选题在Java课设和毕设圈子里几乎年年上榜但大多数同学交上去的只是“能跑通的代码”离“一套完整项目”还有距离。最近我整理了一套基于JavaSpringBootSSM的传统手工艺文化展示平台源码、LW设计说明书、调试文档、答辩讲解一应俱全。这篇文章就从项目拆解、核心功能、交付资料整理、常见踩坑这几个角度完整复盘一遍给正在做同类选题的人一些可以照抄的经验。先交代背景传统手工艺文化展示平台本质上是一个“内容展示后台管理”的Web系统游客能看技艺分类、手工艺品详情、传承人故事、非遗资讯管理员能登录后台维护这些内容。业务边界清楚功能扩展空间大技术栈又正好踩在Java主流框架上所以特别适合拿来讲解SSM和SpringBoot的配合。1. 项目到底在做一个怎样的系统1.1 业务模块与应用场景传统手工艺文化展示平台不是电商系统核心目标是把“手艺”和“人”讲清楚。我整理的这个项目前台模块包括首页轮播、工艺分类导航、手工艺品列表、工艺品详情页、传承人介绍、资讯公告、站内搜索、留言反馈。后台模块则围绕内容生产管理员登录、工艺品增删改查、分类管理、传承人管理、资讯管理、图片上传。前台的核心逻辑是“浏览路径要顺”用户从首页进入后可以按分类筛选也可以直接搜索“刺绣”“木雕”“陶瓷”等关键词。到详情页后除了工艺品的文字介绍和图片还要展示对应的传承人和历史背景这样才算把“文化展示”做出来而不是一个干巴巴的商品列表。后台的逻辑就是标准的CRUD难点不在功能本身而在文件上传、权限控制和数据关联。比如一个工艺品归属某个分类关联某个传承人删除分类时要考虑工艺品是否还在引用这些关联关系必须在代码和数据库层面同时处理好。这套系统适合的落地场景主要有三个地方非遗保护中心做线上宣传窗口、高校文化类社团做作品集展示、以及教学实训里的综合课程设计。前两种场景更看重内容编辑的方便程度第三种场景更看重技术覆盖是否全面。1.2 为什么用SpringBoot搭配SSM而不直接二选一很多同学看到标题里同时出现SpringBoot和SSM会有点懵以为这是两个对立方案。其实不是。SSM是Spring、SpringMVC、MyBatis三个框架的合称SpringBoot则是一套自动化配置的快速开发框架。SpringBoot里照样可以用SpringMVC处理请求用MyBatis操作数据库只是把原来繁琐的XML配置收敛成了自动配置和少量配置项。这里有一个关键决策点如果你的课程设计要求明确写了“基于SSM”而你又想享受SpringBoot的便利完全可以用SpringBoot整合MyBatis再通过SpringMVC的注解方式写控制器。这样做既能满足题目里“SSM”这个关键词又不至于回到写一摞XML的老路。我在交付资料里会把两种理解都解释清楚避免答辩时被老师问住。SpringBoot 2.7.x是目前课设里最稳妥的选择。主要原因有三个稳定、资料多、javax命名空间老项目兼容性好。SpringBoot 3.x虽然新但需要JDK 17而且很多旧教程里的类名还是javax.servlet放到3.x里直接编译不过对新手不太友好。1.3 数据表怎么设计更合理数据表是这类项目的灵魂。我建库时没有追求“大而全”而是按业务闭环拆成了六个核心表分类表、手工艺品表、传承人表、资讯表、用户表、留言表。其中手工艺品表是中心表和分类表、传承人表都要做外键关联。手工艺品表的核心字段大致是这样的字段名类型说明idint主键自增craft_namevarchar工艺品名称category_idint所属分类关联分类表heritage_idint关联传承人可空image_urlvarchar图片相对路径descriptiontext工艺介绍、历史渊源originvarchar产地信息create_timedatetime创建时间为什么把传承人单独建表而不是直接在手工艺品表里存一个名字因为一个传承人可能对应多件作品分开建表才能避免数据冗余。同样分类单独建表也是这个道理后续如果要加“按地区”“按材质”筛选只要在分类表里加字段就行不需要改动大量业务代码。数据库设计时我会格外注意三点字符集统一用utf8mb4因为要支持生僻字和特殊符号时间字段统一用datetime不要混用timestamp外键约束可以保留但删除策略要由代码控制比如删除分类前先判断该分类下是否还有工艺品。2. 核心功能实现与关键代码解读2.1 项目骨架依赖、配置与启动类搭建骨架最忌讳闷头写代码先把依赖和配置搞定后面会省很多事情。我用的父工程是spring-boot-starter-parent版本2.7.18核心依赖只保留了Web、MyBatis、MySQL驱动和Thymeleaf。pom.xml里的关键依赖如下parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version2.3.2/version /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId version8.0.33/version scoperuntime/scope /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-thymeleaf/artifactId /dependency /dependenciesmybatis-spring-boot-starter这个依赖很关键它帮我们把SqlSessionFactory、Mapper扫描等配置自动完成了不需要再去写SqlMapConfig.xml。这正好体现了SpringBoot整合SSM的省事之处。然后是application.yml。我最初因为MySQL时区配置不对启动失败过几次后来固定成下面这套基本没再出过问题server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/craft_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver servlet: multipart: max-file-size: 10MB max-request-size: 10MB mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.craft.entity连接URL里的serverTimezoneAsia/Shanghai一定要写MySQL 8.0的驱动默认时区处理有变化不写可能直接启动报错。multipart配置也很重要SpringBoot默认限制上传文件1MB做手工艺品图片上传远远不够这里直接调到10MB。启动类没有太多花样加上MapperScan扫描Mapper接口即可SpringBootApplication MapperScan(com.craft.mapper) public class CraftApplication { public static void main(String[] args) { SpringApplication.run(CraftApplication.class, args); } }2.2 手工艺品分页展示的三层实现分页展示是手工艺品列表页的核心需求。我选择手写LIMIT分页而不是引入PageHelper。原因很简单手写分页能让你完整说清楚offset和pageSize的计算逻辑答辩时老师追问“分页怎么实现的”你不会卡壳。PageHelper虽然方便但底层的ThreadLocal机制对新手来说反而容易讲不明白。实体类Craft对应手工艺品表Mapper接口定义两个方法一个查列表一个查总数public interface CraftMapper { ListCraft selectByPage(Param(keyword) String keyword, Param(offset) int offset, Param(pageSize) int pageSize); long count(Param(keyword) String keyword); }对应的Mapper XML里用动态SQL处理关键字搜索select idselectByPage resultTypecom.craft.entity.Craft SELECT * FROM craft where if testkeyword ! null and keyword ! craft_name LIKE CONCAT(%, #{keyword}, %) OR origin LIKE CONCAT(%, #{keyword}, %) /if /where ORDER BY create_time DESC LIMIT #{offset}, #{pageSize} /selectService层负责计算分页结果。这里有一个很常见的错误直接用pageNum乘以pageSize当offset结果第二页和第一页数据重叠。正确算法是offset (pageNum - 1) * pageSize。public PageResultCraft list(int pageNum, int pageSize, String keyword) { long total craftMapper.count(keyword); int offset (pageNum - 1) * pageSize; ListCraft list craftMapper.selectByPage(keyword, offset, pageSize); return PageResult.of(total, list); }PageResult是我写的一个简单封装包含total、list、pageNum、pageSize。前端Thymeleaf通过${page.total}就能渲染出“共X条记录”配合页码链接就能实现完整的翻页流程。Controller层要注意参数默认值和非法值处理GetMapping(/crafts) public String list(RequestParam(defaultValue 1) int pageNum, RequestParam(defaultValue 8) int pageSize, String keyword, Model model) { if (pageNum 1) pageNum 1; PageResultCraft page craftService.list(pageNum, pageSize, keyword); model.addAttribute(page, page); return craft/list; }我没有用前后端分离而是直接返回HTML模板。原因很实际课设项目用服务端渲染部署时只需要打一个jar包不需要额外起Nginx或者处理跨域交给答辩演示最省心。2.3 图片上传与访问路径映射手工艺品展示离不开图片。我把图片上传做成两个步骤保存文件到本地目录再把访问路径映射出来。这种方案的优点是简单、可控没有对象存储依赖适合教学演示。上传目录我习惯通过配置动态指定而不是硬编码在代码里app: upload-path: D:/craft_upload/上传接口核心代码PostMapping(/admin/craft/upload) ResponseBody public String upload(RequestParam(file) MultipartFile file) { if (file.isEmpty()) { return 文件不能为空; } String originalFilename file.getOriginalFilename(); String ext originalFilename.substring(originalFilename.lastIndexOf(.)); String newName UUID.randomUUID().toString().replace(-, ) ext; File dir new File(uploadPath); if (!dir.exists()) { dir.mkdirs(); } File dest new File(dir, newName); file.transferTo(dest); return /upload/ newName; }用UUID重命名文件有两个好处避免文件名冲突也避免中文文件名在部分服务器上出现乱码。截取扩展名之前一定先判空不然用户上传无扩展名文件时会发生StringIndexOutOfBoundsException。路径映射用WebMvcConfigurer完成Configuration public class WebConfig implements WebMvcConfigurer { Value(${app.upload-path}) private String uploadPath; Override public void addResourceHandlers(ResourceHandlerRegistry registry) { String location file: uploadPath; registry.addResourceHandler(/upload/**).addResourceHandler(location); } }这里有一个细节也是最容易坑到人的地方Windows下路径写成file:D:/craft_upload/没问题但Linux下路径没有盘符同样写法会变成file:/home/craft/upload前面一样加file:前缀。为了保证跨平台最好用Paths工具类处理。String location Paths.get(uploadPath).toAbsolutePath().toUri().toString(); registry.addResourceHandler(/upload/**).addFilePath(location);实际测试下来这样打包部署到Linux服务器后图片路径也能正常访问不会出现“本地能跑服务器上图片全挂”的尴尬。2.4 管理员登录与权限拦截后台管理功能必须做权限控制不然任何游客都能直接访问后台页面改数据。我没有引入Spring Security而是用Session加HandlerInterceptor实现一个轻量级登录拦截足够应付这类展示平台。先写拦截器public class AdminInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { Object admin request.getSession().getAttribute(admin); if (admin null) { response.sendRedirect(/admin/login); return false; } return true; } }然后在WebConfig里注册并排除登录相关的路径Configuration public class WebConfig implements WebMvcConfigurer { Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(new AdminInterceptor()) .addPathPatterns(/admin/**) .excludePathPatterns(/admin/login, /admin/doLogin); } }这样一个简单的拦截器就能把整个后台保护起来。登录逻辑不要只在DAO层比对用户名密码还要注意密码加密的问题。课设里如果觉得MD5太老可以用Spring自带的BCryptPasswordEncoder也可以直接用MD5加盐。我在这套项目里用的是MD5加盐代码量不大解释起来也方便。用户登录成功后把用户对象放进Session同时记录登录时间。后续要做“记住我”之类的功能也可以基于Session扩展不需要额外改数据库表。3. 交付资料整理源码之外更重要的部分3.1 调试文档怎么写到“拿到就能跑”很多同学交付项目时只给源码和数据库脚本当老师换了一台电脑跑不起来第一反应就是“环境问题”但一句环境问题无法解决任何问题。调试文档的意义就是让一个完全不懂你代码的人也能按步骤跑起来。我整理的调试文档严格按下面这个顺序组织章节关键内容环境准备JDK 8或11、Maven 3.6、MySQL 5.7、IDEA数据库初始化创建数据库craft_db导入craft_db.sql修改配置修改application.yml中的数据库账号密码启动项目运行CraftApplication主类访问入口前台 http://localhost:8080/后台 http://localhost:8080/admin/login默认账户管理员 admin / 123456常见报错端口占用、数据库连接失败、静态资源404写调试文档时我特别强调“默认账号”这一条因为很多项目初始化脚本里根本没有用户数据老师想登录后台却登不进去会直接扣印象分。还有一点如果你用了自定义的数据库名称一定要在文档里写清楚数据库名是craft_db而不是让读者自己去SQL里猜。3.2 LW设计说明书的章节与写作重点LW在课设里通常指设计说明书或论文格式要求各校不同但大框架都差不多。我按通用结构来组织概述、需求分析、系统设计、数据库设计、功能实现、系统测试、总结。需求分析部分不要写成功能列表的平铺而是画用例图、写用例描述。举例游客浏览手工艺品详情这个用例需要描述前置条件游客未登录也可以访问、主流程点击列表项跳到详情页、异常流工艺品不存在时显示友好提示。能写出异常流会显得思考更完整。数据库设计部分除了表结构还要解释每个表之间的关系。我建议画一份简单的ER图用word或者draw.io都行。答辩时老师经常指着ER图问“为什么传承人表和手工艺品表是一对多”这就需要你在设计说明里写清楚业务规则。功能实现部分是最好写的但也最容易写成流水账。我建议按“功能目标核心代码运行效果截图”的结构来写。比如图片上传功能先说明要实现后台添加工艺品时传图再贴上传接口的关键代码最后放一张上传成功后的截图。这样老师看的时候有直观感受而不是面对一堆代码发呆。3.3 答辩演示顺序和高频提问答辩演示的节奏比内容更影响印象分。我总结的稳妥流程是先花一分钟介绍项目背景和技术选型然后从游客视角浏览前台页面再切换管理员身份登录后台演示一个完整的“新增手工艺品”流程最好现场改一条数据再刷新前台验证效果最后打开数据库表展示数据变化。这种“前台展示再到后台操作再回到前台验证”的闭环演示会让评委觉得你真正理解了业务。如果只是照着页面读一遍文字很容易被评委打断提问。高频问题基本集中在几个方向SpringBoot和SSM的关系、MyBatis中#{}和${}的区别、分页查询的SQL怎么写、上传文件怎么防止重名、Session与Cookie的区别。这些问题都不算难但如果你平时写代码全靠自动生成自己不追底层现场很容易答不上来。我的建议是提前准备一份“答辩问题自测清单”把这些问题用口语写在文档里演示前自己对着过两遍。4. 实操中的高频问题与排查方法4.1 环境启动阶段第一个常见坑是MySQL驱动类报错。如果你用SpringBoot 2.7.x和MySQL 8.0驱动类要写com.mysql.cj.jdbc.Driver老版的com.mysql.jdbc.Driver虽然能编译但运行时会警告某些版本甚至直接报ClassNotFoundException。遇到这个问题改配置就行。第二个坑是端口被占用。IDEA控制台报Port 8080 was already in use最直接的办法是执行netstat -ano | findstr 8080找到占用进程的PID然后去任务管理器结束它。也可以直接在application.yml里把端口改到8081但要记得文档里同步改。第三个坑是Maven依赖下载失败。如果你的IDEA下载依赖特别慢大概率是没配阿里镜像。在Maven的settings.xml里加上aliyun镜像问题基本能解决。注意不要只看pom依赖有没有红还要看IDEA右下角的下载进度条。4.2 功能调试阶段功能调试阶段最常见的报错是Invalid bound statement (not found)这是Mapper接口和XML没有正确绑定的典型症状。排查思路分三步检查XML文件的namespace是否等于接口全限定名检查application.yml里的mapper-locations路径是否匹配实际目录检查Mapper接口方法的方法名和XML的id是否完全一致。这三处任何一处拼错运行时就找不到SQL语句。第二个高频问题是页面循环引用。Thymeleaf模板里如果用${page.pageNum}这种写法很容易因为对象嵌套而取不到值。我的建议是模板里统一用封装后的PageResult对象不在页面里写太复杂的EL表达式。遇到页面报SpelEvaluationException或解析错误先简化模板表达式再逐步定位。图片上传也是重灾区。后台添加工艺品时提示上传失败但控制台没有任何报错信息我遇到过两次最后发现是上传目录不存在。transferTo方法不会自动创建父目录所以必须先dir.mkdirs()。还有一次是上传成功但页面显示不了图片后来发现是资源映射路径缺了file:前缀。4.3 打包部署阶段课设项目到了部署阶段最常见的需求是把SpringBoot项目打成可执行jar包。用maven package命令打包后在目标目录里会生成一个jar文件注意用java -jar运行时会报“没有主清单属性”的话说明pom里缺少spring-boot-maven-plugin加上这个插件重新打包即可。部署时上传图片目录会产生一个很隐蔽的问题你本地配置的D:/craft_upload/在Linux服务器上不存在程序会自动创建但jar包运行时工作目录可能和你预期的不一样。我的建议是在部署文档里明确写出需要手动创建上传目录并配置绝对路径避免依赖相对路径。还有一个经常被忽略的点SpringBoot内嵌Tomcat对上传请求大小有限制如果你部署后上传稍微大一点的图片就报MaxUploadSizeExceededException说明配置没有生效。原因可能是multipart配置写在了错误的yml层级或者是被自己的拦截器拦住了。遇到这类问题第一时间看控制台完整的异常堆栈不要靠猜。5. 如果你还想继续扩展这个项目5.1 性能与体验优化课设做完交付并不代表项目就停在原地。如果后续想把这个平台真正用起来我建议从三个方向优化。第一是给首页加缓存。手工艺品分类和热门推荐这类数据基本不经常变动可以用Spring Cache配合Redis把查询结果缓存起来减少数据库压力。思路不复杂存到Redis前先查缓存缓存没有再查库查询成功后写回缓存。第二是图片存储升级。本地文件存储虽然简单但扩展性和备份都比较费劲可以迁移到对象存储服务通过接口上传文件拿到访问URL存入数据库即可代码改动量不会太大。第三是搜索功能改造。SQL里的LIKE模糊查询在数据量小的时候能跑数据量大了会明显变慢。可以引入Elasticsearch或者至少把LIKE %关键字%改成全文索引。如果只是为了应付功能演示这一步可以不做。5.2 架构与功能升级如果想让项目更有亮点可以考虑把前端升级成Vue加Element UI后端用SpringBoot写RESTful API数据库不变。这样虽然代码量增加了但能体现前后端分离的思维对找实习或者参加答辩都有加分作用。不过我要提醒一句前后端分离会带来跨域和部署复杂度的问题。之前的服务端渲染方案只需要一个jar包前后端分离后还需要Nginx托管静态页面或者使用第三方的静态托管平台。时间紧张的时候不要为了炫技把简单项目复杂化。功能上还能加“传承人专题页”“地图展示产地分布”“后台数据统计报表”等模块这些都是传统手工艺平台常见的扩展方向。核心还是先保证基础CRUD稳定再考虑锦上添花。我在实际改这个项目时最大的体会是课设项目最难的不是写代码而是把代码背后的逻辑想清楚再让每个阅读资料的人也能顺利跑起来。先跑通再谈优化先最小闭环再逐步加功能。等你把一套CRUD项目从数据库一路做到前端展示再遇到相似的技术栈基本就能举一反三了。