前些年帮朋友做毕业设计接触过不少文化展示类项目大多是套个后台管理系统、配个增删改查界面做完就完事。但这次拿到“基于JavaSSMFlask古诗词展演系统”这个题目时我却觉得有点意思——它不是让你纯粹做管理而是要把中国古诗词这种传统文化用新媒体的方式“展”出来。这中间的痛点是诗词是文字展演是视觉和交互如何把两者揉在一起既不能做成PPT轮播又不能做成纯文本阅读器。在搞清楚业务定位、梳理好SSM后端与Flask辅助服务的分工后我搭出了一套完整可跑的数字化展演平台源码、调试文档、讲解视频一应俱全。这篇文章就把整个项目的设计思路、技术选型、核心实现和踩坑实录从头到尾盘一遍给正在做类似文化类全栈项目的同学一个可直接参考的样板。1. 项目背景与整体设计思路1.1 为什么古诗词需要“展演系统”传统文化数字化不是简单把书搬到网上而是要解决传播效率的问题。中国人对诗词并不陌生但认知多数停留在课本上——你知道李白的《将进酒》写了什么但不清楚他是在什么人生阶段写的同时代的杜甫在经历什么这首诗后来又被多少人唱和。传统展示方式是线性阅读很难建立这种“时空网络感”。展演系统的核心价值就是把诗词置于“空间时间人物主题”的多维坐标系里。用户打开系统不是面对一个搜索框和一片列表而是进入一个可浏览的诗词展馆可以沿朝代轴依次走过先秦、汉魏、唐宋、明清也可以点击李白节点看他的生平脉络、代表作品、同时期诗人关联、后人对他的评价。这种呈现方式在信息设计上属于沉浸式内容架构比传统图文列表更符合新媒体视域下的传播规律。实际做下来我最大的感受是这个项目定位对了方向就差不了多少。技术只是实现工具真正的门槛在于怎么把诗词的“意境”转换成系统的信息架构。比如一首《静夜思》文字只有二十个字但与之相关的信息维度可以拆出月亮意象、思乡母题、李白生平、唐代漂泊文化等多个展演切片。系统若能把切片组织成观展路径就有了“展演”的质感。1.2 技术选型SSM为主力Flask做外援很多同学拿到这个题目时问为什么不直接用Spring Boot为什么还要引入Flask这其实牵扯到项目的实际落地场景。SSMSpring SpringMVC MyBatis是经典Java Web组合在高校课程设计和毕业设计中仍是主流考核标准。它对分层架构的要求非常清晰Controller负责接口路由Service负责业务逻辑Mapper负责数据库操作。用SSM去做这类系统最直接的好处是结构规整、难度可控、岗位匹配度高——Java开发岗面试时SSM几乎是必问内容把它吃透了比单纯会用Spring Boot对原理的理解更深。那Flask承担什么角色我让它在系统里做了两件事一是搭建一个轻量的数据辅助服务负责诗词文本的切分、关键词提取、意象标签生成等自然语言处理任务二是为展演页面提供动态聚合接口比如根据当前浏览的诗人实时拉取同时代文人关系数据。这些功能当然可以用Java写但Python生态里现成的分词、文本相似度计算库更丰富开发效率高很多。因此架构上我采用的是“Java主服务负责核心业务Flask辅助服务负责智能处理”的混合模式两者通过HTTP/JSON接口通信互不干扰部署时也是两个独立进程。选这套方案还有一层务实考虑纯SSM技术栈的代码仓库在毕设答辩时容易被问得很细你把Flask部分包装成“基于Python的新媒体数据处理模块”反而能展示技术广度。实际答辩效果也印证了这一点。1.3 系统信息架构从“诗词库”到“展演空间”我把整个系统规划成四个层次基础数据层诗词主库、诗人库、朝代库、意象标签库这是整个系统的数据底座。业务服务层由SSM提供管理端API覆盖诗词/诗人/专题的增删改查、状态管理、用户评论与收藏。展演计算层由Flask提供内容计算能力包括诗词分词、风格标签提取、诗人关系图谱数据组装。呈现层前端页面负责展演效果包含首页展演导航、朝代时间轴、诗人空间地图、诗词主题策展等视图。这个架构的好处是“管理”和“展演”逻辑分离。管理员在后台维护数据普通用户在前台消费展演内容Flask位于中间把原始数据加工成更符合可视化展示的信息结构。比如前端要展示“月”意象的关联诗词Flask先从诗词库分词后打上“月”标签的诗词清单再按情感倾向分组前端拿到分组结果就可以做主题卡片墙。实际编码前我花了两天时间把表结构和接口文档梳理清楚才动手写代码。信息架构设计阶段偷懒后面重构付出的代价是十倍。这个教训值得每一个做全栈项目的人牢记。2. 数据库与核心接口设计2.1 五张核心表的建模细节古诗词展演系统看起来功能不复杂但数据建模要想清楚否则写业务代码时经常卡壳。我最终设计了五张主表字段设计经过几轮调整踩过不少坑后才稳定下来。诗词表是系统的核心。字段包含诗词ID、标题、作者ID、朝代ID、正文、译文、注释、赏析、意象标签、创作背景和浏览量其中意象标签用逗号分隔存储。刚开始我只存了标题、正文和作者结果做“主题策展”功能时根本没法按意象筛选只能在代码里硬匹配关键词效率极低且不准。后来新增了意象标签字段由Flask自动分析正文后回填才彻底解决问题。诗人表不能只存姓名和生卒年。为了满足展演页的“人物志”效果我增加了字号、别称、籍贯、生平简介、代表作数量、诗词风格标签等字段。籍贯和生卒年一起用可以画诗人的地域分布图和时间轴。风格标签如豪放、婉约、田园、边塞由Flask依据诗人作品词频统计生成为后续按风格聚合诗人提供数据支撑。朝代表结构最简单就是朝代名称、起止年份和简介。为什么需要单独建表而不是直接把朝代作为诗词表的一个文本字段因为展演系统需要一条“时间轴”从先秦到明清朝代必须有先后顺序和年份跨度前端才能渲染出连续的时间刻度。另外两张表是用户评论表和用户收藏表用于前台互动。评论表记录用户ID、诗词ID、评论内容、评论时间和父评论ID支持楼中楼收藏表记录用户ID和诗词ID的关联。收藏和评论功能是毕设答辩中体现“系统完整性”的重要抓手建议不要省略。2.2 管理端APISSM的Controller层这样组织SSM接口层我按照资源维度拆分没有把接口全部堆在一个Controller里。诗词管理接口、诗人管理接口、朝代管理接口、用户互动接口各建一个Controller每个Controller内部再按REST风格细分代码结构非常直观。以诗词管理接口为例核心接口包括POST /api/poem新增诗词请求体包含标题、作者ID、朝代ID、正文、译文等字段。DELETE /api/poem/{id}删除诗词同时会级联删除该诗词的评论和收藏记录。PUT /api/poem更新诗词信息可用于管理员修改解析内容或修正意象标签。GET /api/poem/{id}获取诗词详情返回所含字段及作者和朝代的联表信息。GET /api/poem/page分页查询诗词支持关键字搜索和按作者/朝代/意象筛选。分页查询这个接口最值得拿出来说说。我的实现方式是Mapper层接收PageNum、PageSize、Keyword、AuthorId、DynastyId、Tag等参数用动态SQL拼接查询条件。MyBatis的where标签和if标签在这里非常方便条件不确定时不用担心SQL语句出错也不会出现全表扫描——因为未传参数时where条件不生效返回的就是常规分页结果。Controller RequestMapping(/api/poem) public class PoemController { Autowired private PoemService poemService; RequestMapping(value /page, method RequestMethod.GET) ResponseBody public Result pagePoem(RequestParam(defaultValue 1) Integer pageNum, RequestParam(defaultValue 10) Integer pageSize, String keyword, Integer authorId, Integer dynastyId, String tag) { PageHelper.startPage(pageNum, pageSize); ListPoemVO list poemService.queryPoemPage(keyword, authorId, dynastyId, tag); PageInfoPoemVO pageInfo new PageInfo(list); return Result.success(pageInfo); } }2.3 展演数据接口Flask这样与Java配合Flask服务的核心价值有两个做文本分析、给前端提供聚合接口。这两个功能分两个Blueprint实现一个叫analysis一个叫exhibition。analysis服务的接口是POST /analysis/tags接收parameter poemText返回该诗文的意象标签和情感倾向。它内部先对文本做分句再用停用词表过滤虚词保留名词性词汇并与预设的意象词库做匹配最后把匹配到的意象按权重返回。为了让SSM在保存诗词时能自动完成这个打标签的过程我在Java侧写了一个调度工具——诗词入库后通过HTTP Client调用Flask接口拿到标签回填到诗词表的tag字段整个流程对管理端完全透明。exhibition服务则是面向展演页面的聚合接口比如GET /exhibition/poet/{id}/network传入诗人ID后返回诗人的关系图谱数据。这里的“关系”不是我手工维护的而是Flask根据诗人朝代、风格标签和作品高频词的相似度计算出来的——同朝代优先、风格标签重合、高频意象接近的诗人会被标记为关联节点。前端拿到节点和连线数据后用ECharts的关系图就能渲染出诗人社交网络。这里有个技术细节值得说Java和Flask通信时需要统一JSON格式并约定好错误码。我给两个服务定义了统一的返回结构包括code、message和data三个字段Java侧解析时先判断code是否为200再做数据类型转换。这个约定在联调阶段避免了大半沟通成本。3. 核心功能模块的实现与实操3.1 展演导航与主题策展首页首页是整个系统的门面也是“展演感”最强的页面。我没有做传统的列表式首页而是设计了一套模块化展演布局从上到下依次是朝代长卷区、名篇推荐区、主题策展区、诗人图谱入口和最新评论滚动区。朝代长卷区是首页的视觉重心。数据来源于朝代表和诗词表的时间聚合前端按照朝代起止年份计算相对宽度渲染成一条横向时间轴。每个朝代节点显示该朝代的诗词总量和代表诗人头像点击后进入该朝代的诗词展演子页面。这里的优化点是如果直接用图片做长卷后续维护成本太高换朝代还要重新出图。我改成了纯CSS渲染的时间轴数据库里朝代数据变化页面自动跟着变化管理员只需要维护数据就行。主题策展区是体现“新媒体”特点的重点模块。它背后是策展专题表每条专题记录包含专题名称、封面图、简介和关联诗词ID列表。管理员在后台创建专题时可多选诗词加入专题系统自动生成专题的唯一路径。前台展演页加载专题后以卡片墙的形式铺开展示每张卡片是诗词的标题和首句点进去才会展开全文和赏析。这种“先看题、再读文”的交互设计比直接展示全文更符合展演场景的观看节奏。div classexhibition-section div classsection-title h2主题策展/h2 span classsection-more进入展馆/span /div div classcard-wall idtopicCardWall !-- 由JavaScript根据专题数据动态渲染 -- /div /div3.2 诗词详情从单一阅读到多维度呈现诗词详情页是整个系统里投入精力最多的页面。标题和正文展示部分和常规模式一致但正文下方多了一行意象标签每个标签都是可点击的。点击标签后前端调用展演聚合接口返回该意象在所有诗词中的分布情况——比如点击“月”页面下方区域会展开一个横向滑块展示所有含“月”意象的诗词卡片并统计该意象在不同朝代出现的次数渲染成迷你柱状图。这个设计的思路是让用户在阅读一首诗时沿着意象的线索“逛”到更多诗打破单篇阅读的闭环形成展演的“逛展感”。实现层面其实不复杂前端用Ajax请求Flask的意象分布接口返回JSON后拼接DOM渲染即可。这里有一个操作细节需要留意Ajax请求的URL不要写死成localhost:5001要配置成相对路径然后由Nginx做反向代理否则部署到服务器上之后接口会全部404。诗词详情页还加入了作者信息和创作背景Tab。作者信息Tab展示诗人的生平简介、风格标签和代表作列表创作背景Tab则由管理员在后台维护内容来源可以是《唐诗鉴赏辞典》等公共资料也可以是自己整理的历史背景。这个部分对于用户理解诗词非常重要尤其是《春江花月夜》这类需要结合初唐时代氛围才能读透的作品背景信息的展演价值远高于注释本身。3.3 交互功能评论、收藏与用户中心为了让系统具备完整的闭环我做了用户注册登录、收藏诗词、发表评论三件套。用户表放在MySQL里密码用加盐的MD5存储。虽然MD5不算高安全方案但对毕设项目而言是标准做法讲解时你能说清楚加盐的作用就足够了。实际工作中应该用BCrypt或PBKDF2这样的算法这点在调试文档里有补充说明。评论功能采用了异步提交模式。用户在文本框中输入评论点击发表后通过Ajax提交到后端后端校验用户登录状态后写库同时更新诗词的评论总数。评论列表默认按时间倒序排列支持分页加载。为了防刷屏和脏数据我在后端做了两层校验第一层是Session里必须存在用户ID不存在直接返回401第二层是评论字数限制在2到500字之间包含空字符串和纯空格判断。收藏功能比较简单但有个交互细节值得说一下前端在诗词详情页会先请求一个收藏状态接口判断当前诗歌是否已被当前用户收藏然后决定按钮显示为“收藏”还是“已收藏”。点击收藏时前端按钮立刻变为“已收藏”状态然后才发Ajax请求这样用户体验会好很多不会因为网络延迟让人觉得没点上。3.4 后台管理管理员视角的内容维护管理端和前台的展演端在同一个项目里只是通过登录用户的角色字段区分权限。管理员登录后菜单栏展演导航会多出内容管理分组与管理相关的接口都在/api/admin前缀下。诗词管理页面采用经典表格布局左侧是筛选区可按照朝代、作者、意象标签筛选右侧是诗词列表展示标题、作者、朝代、意象标签和操作按钮。操作按钮包含编辑、删除、查看评论和置顶推荐。列表中新增诗词时用弹窗表单表单里最麻烦的字段是“正文”太长的诗会撑开弹窗影响布局。我最终把正文录入改成了textarea自适应高度并在保存时用ModelAttribute自动绑定接收绕开了手动拼接参数的笨办法。朝代管理相对简单就是名称、年份范围、简介的维护。但要注意朝代年份跨度一定要填写完整否则前台时间轴会显示错乱。举例来说如果唐朝只填了618和907时间轴渲染正常如果只填了618没填907那么唐朝的宽度计算会出现负数页面样式会直接崩掉。我在后端做了校验起止年份不得为空且结束年份必须大于开始年份这样从源头上规避了脏数据。3.5 环境搭建与部署流程项目开发环境用的JDK 1.8、Maven 3.6、MySQL 5.7Flask端用Python 3.8。JDK版本建议不要高于1.8因为SSM框架对高版本JDK的兼容性偶尔会有坑特别是CGLIB代理在某些JDK版本下的反射警告虽然不影响运行但看着烦。数据库连接URL必须加上useUnicodetruecharacterEncodingutf8参数否则中文写入后会出现乱码这个问题在Windows本地开发时最容易踩。SSM端我建的Maven工程包含四个模块controller、service、mapper和common。common模块放统一返回结果类、分页工具类、MD5工具类等公共组件。mapper模块放MyBatis的Mapper接口和XML文件XML文件放在resources目录的mapper子目录下。配置文件主要管理数据源、事务管理器、MyBatis的mapper扫描路径和SpringMVC的注解驱动。Flask端工程结构更轻量app.py负责创建应用并注册蓝图config.py存放配置项blueprints目录下按功能拆分路由utils目录放分词工具和意象匹配工具。Flask端建议开启CORS跨域支持用Flask-CORS库即可但要配置成只在开发环境开启生产环境由Nginx统一转发不暴露5001端口。部署时我用Nginx做统一入口监听80端口把/api/poem、/api/comment等Java接口反向代理到8080端口的Tomcat把/exhibition、/analysis等Flask接口反向代理到5001端口的Gunicorn。这样的部署架构在讲解时非常加分别人问“两个服务怎么协同”时你可以直接画出这份代理关系图。4. 常见问题与排查技巧实录4.1 数据库中文乱码这是本地开发时最常遇到的问题。表现是存入的中文正常但读取时变成问号。原因多半是数据库连接URL缺少编码参数或者是MySQL表本身的字符集不是utf8。修复方法是两步走第一步建库时指定字符集为utf8mb4建表时如果没有指定用ALTER TABLE语句修改第二步在数据源URL后面加上?useUnicodetruecharacterEncodingutf8。两个地方都改了重启Tomcat后问题基本消失。有一个坑是MySQL 5.7及以下版本的默认字符集是latin1即使你在URL里指定了编码也没用。这时需要直接修改数据库层面的字符集配置进入MySQL执行ALTER DATABASE 库名 CHARACTER SET utf8mb4再对每张表执行ALTER TABLE 表名 CONVERT TO CHARACTER SET utf8mb4。做完之后重新导入数据问题才会根治。4.2 JSON序列化日期格式异常SSM返回JSON时日期字段默认序列化成时间戳或带时区的格式前端拿到后无法直接显示为“2024-05-20”这样的标准格式。我在实践中找到了最简单的处理方式——在字段上直接标注JSON格式化注解。JsonFormat(pattern yyyy-MM-dd HH:mm:ss, timezone GMT8) private Date createTime;在实体类的日期字段上统一加上这个注解前端拿到的就都是格式化好的字符串。要注意timezone必须指定GMT8否则不同时区的服务器会返回相差8小时的时间前端的“刚刚”判断就会出错。4.3 Flask依赖冲突与兼容性Flask端最容易出问题的地方是依赖库版本冲突。我在本地安装分词库时遇到一个典型情况jieba库的最新版本与Flask框架对Werkzeug的依赖存在版本冲突导致Flask启动时直接抛ImportError。解决方法是手动固定Werkzeug版本为与Flask兼容的版本并在requirements.txt中明确锁定。另一个细节是Flask开发时用的内置服务器性能差并发一高就卡但接口供前端调用频率并不高这个问题不突出。如果要上生产环境建议部署到Gunicorn上用gunicorn -w 4 -b 127.0.0.1:5001 app:app启动4个worker进程对展演系统而言完全够用。4.4 跨域问题Java与Flask的前端联调开发展演页面时前端在一个端口Java接口和Flask接口分别在另外两个端口浏览器会因为跨域限制拦截请求。我在项目中做了两层处理开发阶段用Webpack DevServer的proxy配置把/api和/exhibition前缀的请求分别代理到对应服务生产部署阶段用Nginx统一反向代理。两层方案核心逻辑一样都是让浏览器认为请求是同源的。这里有个新手常犯的错误在Java端使用CrossOrigin注解或者在Flask端直接设置Access-Control-Allow-Origin: *来解决问题。这两个方案短期内有效但会埋下安全隐患——任何网站都能跨域请求你的接口。我在调试文档里明确写了不建议生产环境这么干而是优先使用代理方式解决。4.5 MyBatis动态SQL报错排查写多条件查询时注释掉某个if后SQL拼接报错多半是XML里多写了逗号或漏了空格。MyBatis的where标签能自动处理掉多余的AND或OR但前提是SQL里的AND/OR必须写在条件前面而不是后面。还有一个排查技巧启动项目时把MyBatis的SQL日志打开控制台直接打印执行的SQL语句一眼就能看出拼接问题出在哪。另外一个隐蔽的坑是动态SQL里使用了比较符XML文件会直接解析报错。处理方式是改用lt;转义或者把所有参数传入后再用判断标签不在SQL语句里写小于号。这个细节在讲代码时顺带提一句老师会觉得你考虑得很周全。5. 从项目落地中沉淀的几点体会这套系统从设计到跑通前后花了两周多的时间。回头复盘我认为最有价值的不是代码本身而是这个过程中对“展演系统”这个概念的落地理解。文化类项目的核心从来不是技术复杂度而是你如何用有限的技术手段营造出场景感。SSM也好Flask也好都只是工具关键在于你怎么组织数据、设计交互、引导视线。给正在做类似项目的同学三个建议。第一先画信息架构图再写代码数据表字段想不全就动手后面一定返工。第二前端展演效果的实现优先级不要低于后端接口这个项目叫“展演系统”首页丑到没人愿意点第二下功能做得再深也没意义。第三调试文档从第一天开发就要同步写不要等项目跑通了再回忆过程。我这次把每日开发遇到的问题、解决思路和改动记录全部实时记录在调试文档里最后整理成册时省了巨大的精力答辩时老师翻着文档问项目细节也全都能接上。如果后续方向继续扩展可以考虑接入地图API做诗人生平行迹追踪用时间轴拉出诗词创作编年长卷甚至可以引入简单的AI生成功能根据用户输入的关键词自动创作一首仿古体诗作为展演互动的收尾。技术上的扩展空间还很大但眼下这套系统的骨架已经足够稳健SSM做业务底子Flask做智能外挂新媒体展演的思路也完整跑通了。踩过坑的同学再回头看这套结构应该会有同感好的架构不是设计出来的是在迭代中被验证出来的。