实训项目往往是大学阶段最接近真实开发的一段经历。和在教室里写课程作业完全不同实训不会有人把每一步都给你安排明白经常是甩给你一个一句话的课题目标剩下的全靠自己慢慢把它变成能跑、能演示、能答辩的系统。这篇记录是系列笔记的第一篇主题就是项目实训的前期准备工作。可能很多人觉得“准备”没啥好写的但我自己的体会是选题、调研、技术选型、环境搭建这些事情恰恰决定了你后面两个月的开发是顺顺利利还是天天返工。这个系列会按项目推进的时间线来写第一篇聚焦准备阶段后续再陆续整理开发、联调、测试和验收的过程。准备阶段基本不会产出业务代码很多人不重视但它直接决定了项目能不能在限定周期内完成也决定了团队几个人能不能顺畅协作。我自己在这个阶段踩过不少坑也对比过几种常见的做法下面把这些经验和思路完整整理出来给即将参加实训或者准备接手新项目的同学一个可参考的模板。1. 项目实训到底在练什么先把目标拆明白1.1 实训开始前真正要回答的三个问题我们这次实训开始前带队的老师开了一次动员会会上反复强调的不是“你们要做出一个多牛的系统”而是“过程完整、逻辑清晰、能讲明白”。这句话一开始听着像套话后来回头看才发现它才是整个实训的核心评判标准。实训不是企业里的商业项目不会有人真的把系统拿到生产环境去用所以它的核心价值在于让你把从需求分析到部署上线的完整链路走一遍并且能在答辩时把每一个决策讲清楚。我建议所有人在动工之前先回答三个问题第一这个项目要解决谁的什么问题第二完成它需要哪几个核心功能哪些功能可以不做第三用什么技术来做为什么是这些技术而不是别的。这三个问题不解决后面写代码就是无头苍蝇。第一周我就是在做这件事。没有直接打开IDE而是用两天时间把项目目标拆成了四层分别对应实训的不同考察点业务目标看你能不能理解场景技术目标看你会不会选型落地过程目标看你的开发节奏和协作规范成果目标看最终能拿出什么。这四层拆完之后我才觉得心里有底了也才知道后面每一个环节该往哪个方向使劲。1.2 选题的核心原则与逻辑实训的课题来源一般有两种一种是老师给定的题目列表一种是团队自己提方向。我们当时是混合式给定列表里可选也允许自拟。选课题的时候我给自己定下了三条原则。第一条是难度适中。实训周期一般就八到十周还要包括文档撰写、答辩准备和演示录制真正写代码的时间根本没有想象中那么多。所以这个题目得保证在周期内能完成80%以上的核心功能而不是把战线拉满。第二条是业务场景明确。系统要解决什么问题用户是谁操作流程是什么样的这些事情越清晰后续需求分析就越容易文档也越好写。第三条是技术栈贴合主流。找工作的时候简历上写的技术和招聘岗位要求能不能匹配这个在选型阶段就要想好而不是等项目做完了才后悔。结合这三条原则我最终选定了实训管理系统这个方向。这里还要解释一下为什么选它——这类题目确实不少见但正因为常见它的业务边界是清晰的不会像“智能推荐平台”那样需要大量算法和数据处理。一个实训管理系统角色就是管理员、教师、学生三类流程就是申报、审批、录入成绩、归档这些领域逻辑在教务场景里已经非常成熟适合在有限时间内做出一个完整可用的东西又能覆盖数据库设计、前后端交互、权限控制和数据统计这些核心技术点。1.3 为什么坚持选“管理系统”而不是“新技术Demo”在选题对比阶段也有朋友建议做图像识别、小程序、智能硬件之类看起来更“高级”的方向。这些方向不是不好但放在实训这个场景里有几个现实问题很难绕开。先说数据。图像识别需要训练样本智能硬件需要物理设备如果没有现成条件前期的数据采集和设备调试就会消耗大量时间。再说交付。实训最终要演示和答辩管理系统类项目只要数据填进去就能完整展示从登录到审批再到统计的全链路效果而算法类项目如果模型效果不稳定或者环境依赖特别复杂演示当天可能连环境都起不来。最后说技术验证。管理系统的核心流程覆盖了增删改查、权限管理、状态流转、多条件查询这些恰恰是日常开发里最高频的能力做完一个系统之后你对整个Web开发链路的理解会明显上去。这不是说新技术方向不好而是说选型要匹配环境和目标。实训的目的是在有限周期内走通流程、做出成果而不是在一个点上反复打磨。如果放到毕业论文或者长期科研项目里选择深度方向是合理的但实训阶段的核心诉求是“全链路可交付”。2. 前期调研怎么做从需求描述到可执行清单2.1 调研不只是“看资料”而是建立信息框架很多同学做前期调研时做的事就是去搜索引擎搜一堆文章收藏了但没消化最后问卷一关什么也没留下。我这次换了一种做法——把调研拆成了三个具体层面每一层最后都要有一个产出物。第一层是“同类系统长什么样”。去把实训管理、科研管理、教务管理这类系统的介绍、截图、功能列表都翻出来找出它们共有的模块。产出物是一张功能清单标出哪些是每个系统都有的标配功能哪些是某几个系统才有的差异化功能。第二层是“用户的操作流程是什么”。这个阶段最重要的是画出角色流程图比如管理员发布实训任务、学生提交申报、导师审批、教务归档每一步的数据从哪来、到哪去都要在纸上先走一遍。第三层才是“技术实现怎么选”也就是这一套流程用什么框架和工具来实现。这个顺序不能反。很多人习惯一上来就纠结用Vue还是用React但技术选型应该建立在需求理解之上。你连要做什么样的页面、承载什么数据都没想清楚选型就是空中楼阁。2.2 把需求写成“能落地的文档”角色、流程、状态调研之后就要产出需求文档。实训阶段的需求文档不用像企业里几十页那么厚但五个关键点必须写清楚。第一是角色定义清楚。管理员、教师、学生分别能做什么、不能做什么权限边界要在文档里写明避免开发到中途才发现某个人是不是加不到系统里。第二是流程必须能走通。什么是起点、什么算完成、完成后去哪每一步都要有明确的出口。第三是字段要明确。每张表有哪些字段哪些是主键哪些是外键哪些允许为空这些前期不定义后期前后端联调时就会疯狂扯皮。第四是边界要划清。这个项目不做哪些功能比如不做消息推送、不做支付、不做社交边界明确了才好挡需求。第五是优先级要排序。哪些功能是买不动的核心哪些是时间充裕再做的扩展要有一个明确的MVP范围。我吃过一次亏早期没有把审批流程的状态机设计好导致写业务的时候到处是if else嵌套页面逻辑越写越混乱。后来才意识到前期花半天时间把状态流转图画清楚比后期修逻辑省力得多。状态机这个事特别值得提前做它能让你把所有边界情况在动工前就暴露出来而不是在代码里边写边改。2.3 调研带来的一次关键决策调整调研还有一个很实际的作用帮助你砍功能。我们最初设想的功能列表里除了核心的申报和审批还加了不少“听起来挺美”的功能比如站内通知、批量导入、图表大屏等等。带着这些想法去调研之后发现一个问题——如果照单全收这个周期内几乎不可能做完。比如站内通知看起来简单但要做好需要角色分组、接收规则、已读未读、消息记录查询这些展开就是一堆工作量。批量导入则需要处理Excel模板、格式校验、错误回显也是不小的工程。图表大屏更不用说数据可视化本身就是一个专门的方向。于是我做了一个关键决定通知只做最简单的列表展示不搞已读未读批量导入砍掉改成手工单条录入图表统计保留但只做两三个核心维度。这次做减法让我非常受益。原本以为功能删了是“损失”实际做了之后发现核心流程因为集中了时间而完成得更扎实。到了项目后期我反而省出了时间回补了两个小的扩展点这在功能全开的计划下是不可能做到的。前期花两天做减法后期能少熬两周夜这件事真实发生过。3. 技术选型与方案评估怎么定下前后端和数据库3.1 技术选型时我们对比了什么需求文档基本稳定之后就进入了技术方案评估。技术选型不能凭感觉拍脑袋我的做法是列了一张对比表从几个维度逐个评估候选方案。第一个维度是团队熟悉度。四个人里谁用过什么技术、熟练到什么程度要摸清底。因为实训时间有限不可能让全团队在项目期间从头学一个新框架。第二个维度是学习成本。如果有一个技术能够一天上手另一个需要两周适应除非特别必要否则优先选前者。第三个维度是市场需求。我们选技术时兼顾了“以后找工作能不能用上”所以会去看招聘网站上对应岗位的数量和平均薪资这很好理解。第四个维度是部署和演示的难度。项目最后要能稳定跑起来部署越简单越好环境越不容易出问题越好。我拿前端技术做了一个例子React和Vue都很主流但调研后发现实际岗位需求中两个框架都有大量机会这意味着选哪个都不算错。决定性因素变成团队熟悉度——我们多数人之前接触过Vue生态组件库又很全最终前端定了Vue。这不是因为Vue比React好而是因为团队在它上面的熟练度更高项目周期又紧没必要为了追求“技术新鲜感”去增加学习成本。3.2 最终方案和理由一张表说清楚最终技术方案如下层次选型选择理由前端框架Vue 3 Vite团队熟悉度高语法简洁组件生态成熟Vite构建速度快UI组件库Element Plus覆盖管理端常用组件表单、表格、弹窗开箱即用后端框架Spring Boot 3.x生态成熟资料丰富内置依赖管理适合快速搭建企业级接口数据库MySQL 8.0使用最广的关系型数据库事务、索引、权限控制完善接口文档Swagger OpenAPI自动生成接口文档前后端联调时减少沟通成本部署Docker Compose Nginx本地构建镜像一键启动整套服务演示换机器也不慌这个方案有几个隐含的考量。前端加Vite是因为开发热更新非常快能明显提升多人开发时的效率后端没有用更轻的框架是因为Spring Boot在校园和企业里的资料最多遇到问题能搜到靠谱答案对一个时间紧张的实训项目来说可查资料丰富本身就是最大的优势部署用Docker Compose是因为它能把MySQL、后端、前端三套服务打包到一起换电脑演示时一键拉起不用去现场配环境。3.3 选型时需要避开的一个大坑技术选型阶段最容易犯的错误是盲目追求“高级感”。我们团队在讨论时也有一位同学提过要不要上微服务架构或者用消息队列和Redis缓存。我当时的回答是这些技术本身都很优秀但我们需要判断的是它们适不适合当前这个项目。实训管理系统这类项目本质是一个业务逻辑清晰的中小型单体应用。它没有海量并发不需要独立扩展单个服务也没有跨系统的异步任务要处理。在这种规模下引入微服务带来的不是技术红利而是服务拆分、远程调用、配置管理、链路追踪等一系列额外复杂度。同理这个阶段的Redis缓存也意义不大因为数据量大不到需要缓存来分担压力的程度直接查数据库反而少一层维护成本。技术选型应该匹配需求而不是为了“简历好看”去硬塞技术栈。实训项目最该证明的能力是你理解需求能选合适的方案能把一个完整的东西做出来并讲明白。任何时候业务闭环的完整度优先于技术词汇的堆积。真要学分布式和中间件可以放到实训结束之后再深入而不是在这个阶段和它硬磕。4. 环境搭建与团队协作规范开工前必须做好的交接4.1 统一环境版本踩过一次版本不一致的坑团队一共四个人笔记本电脑型号和系统都不一样有Windows也有macOS所以开写代码之前先做了一件事统一开发环境。这一步是我用一次合作失败的代价换来的教训——之前和同学组队做课设时有人用了Spring Boot 2.x有人用了3.x结果接口调不通找了一下午原因才发现是版本差异带来的隐性问题。这次我们提前定下了统一版本清单JDK用17稳定版前端Node.js用18 LTS后端框架用Spring Boot 3.2版本数据库用MySQL 8.0IDE统一为同一个版本前后端项目的包管理器也做了约定。关于Node版本我还特别提醒团队里所有人在终端里检查一下node -v的输出是否一致因为Node 18和16在部分依赖的兼容性上存在差异一旦不一致node_modules安装出来的依赖树就会不一样。这个版本清单最后写在了项目README里新成员加入或者换电脑时照着清单装就行。统一版本这件事本身不难难的是在项目开始前就意识到它重要。等到写了两千行代码再发现问题那就是全局返工了。4.2 最小链路先行第一个commit要完成什么环境统一之后我没有让大家直接开工去写业务代码而是规定了开整之前必须先把“最小链路”跑通。所谓最小链路就是前端页面能通过接口把数据保存到数据库再从数据库读出来渲染到页面上。这个链路只要通了就说明整个开发环境没有问题了。具体的初始化流程我按顺序做了一遍也分享给大家参考。第一步创建前后端两个代码仓库分别初始化好目录结构。第二步前端用Vite的创建工具拉一个Vue基础模板确认开发服务器能起来。第三步后端用Spring Initializr页面生成工程依赖只勾选了Spring Web、MyBatis和MySQL Driver避免默认模板生成一堆用不到的东西。第四步配置数据库连接新建数据库调整好用户名密码和时区参数。第五步后端写一个最简单的接口比如根据用户表返回一条记录前端页面上调一下这个接口把结果显示出来。第六步确认整条链路走通之后提交第一个commit。这个过程半天就能完成但价值非常大。只要最小链路通了后续业务开发的每一件事都可以基于一个可靠的基础进行如果链路不通问题大概率出在环境配置解决起来也很快。第一次提交就把这个基础固化下来后面所有人都从小链路的代码上继续开发就不会出现方向性混乱。4.3 团队协作约定分支、commit和接口文档四个人开发同一个项目没有约定协作规范很快会变成一场灾难。我们在动工之前花了一个小时定了几条非常简单的规矩虽然简单但后面省了非常多事。第一条是Git分支模型。只分工我们用了三个层级main分支只放稳定可用的版本每个迭代结束后由负责人合并develop分支是日常开发的主干所有人从这里checkout自己的功能分支每个新功能单独拉一个feature/xxx分支开发完成后发起合并申请由另一个人代码评审后再合并。这条规矩最重要它保证了main分支的代码随时可以运行演示前不至于因为某个人的半成品代码把整个项目搞挂。第二条是commit信息格式。我们约定用type(scope): description的格式比如feat(user): 新增学生申报接口、fix(auth): 修复登录超时问题。规范的提交历史让回溯bug非常方便看一眼git log就能知道某块功能是谁、在什么时候、因为什么改的。第三条是接口文档。前期大家人手一份Swagger页面地址同时约定每个接口必须注明入参、出参和错误响应。任何人都不能只写一个接口不写文档不然联调阶段就是互相猜谜。前期花半小时把这个约定定下来比后期多花半天去对接口信息值多了。5. 前期准备阶段的常见问题与避坑记录5.1 依赖下载和版本冲突是最常见的坑实训准备阶段遇到的第一批问题几乎全集中在依赖管理和版本冲突上。我们在第一天就遇到过npm install卡死四个人对着转圈的小光标干瞪眼。排查发现是默认下载源在当前网络环境下太慢改成了镜像源之后问题秒解。所以在这里明确建议项目一开始就在项目根目录配置文件里把npm的镜像源设置好同时在文档里让每个成员执行检查命令确认设置生效。另一个问题出现在版本锁定。当时有一个同学没有提交package-lock.json文件导致他在本地私自升了一个小版本依赖后其他人拉取代码再install时得到了不同的依赖树出现了行为不一致。后来我们规定了这个文件必须提交同时所有人在安装新包时必须用相同的大版本号避免找依赖问题浪费无意义的时间。端依赖冲突还相对好解决Java这边的坑更多样。一个很典型的例子是MyBatis的依赖版本和Spring Boot版本不匹配导致启动报错这个问题让一位同学卡了很久。好在解决方案并不复杂直接用Spring Initializr勾选版本让框架自己决定兼容依赖而不手动去逐个指定版本。这也是我前面推荐大家用Initializr生成项目的原因它帮你规避了手工拼依赖可能埋下的隐患。5.2 数据库连不上和时区差八小时的问题数据库连接问题在准备阶段也是高发区。一个非常经典的错误是本地跑后端能连数据库但放入Docker容器之后就报连接拒绝原因其实很简单——数据库连接串里的host还写着localhost或者127.0.0.1。在容器里localhost指向的是容器自己不是装有MySQL的宿主机或另一个容器正确的写法应该是用一个可通过Docker内部网络访问的别名如果在Compose里部署可以写Compose服务名作为数据库主机名。还有一个和数据库有关的细节是时区参数。MySQL连接串如果没指定时区经常会遇到Java后端返回的时间比本地时间早八个小时。虽然这个问题在业务代码里可以通过全局配置修掉但根因还是在连接串中补齐了时区参数这样数据库侧和业务侧的时间口径才能保持一致。这类问题最麻烦的不是答案本身而是排查路径长。很多时候你以为代码逻辑有错逐行检查半天最后发现就是配置文件里一个单词的问题。准备阶段就把数据库连接串和部署脚本写对、写清晰后期联调会省心很多。5.3 团队节奏不同步怎么办准备阶段团队内部最容易出的问题还不是技术而是节奏不同步。有人进度快已经把接口写好了有人还在装环境连项目都跑不起来。这种情况下很容易产生焦虑甚至互相甩锅。我的处理方式是开了一次简短的同步会把每个人的进度拉平然后定了一个原则完成自己的任务后顺手整理一份简单说明放到共享文档里让别人能复现你的环境有阻塞时不要硬扛超过一小时先把问题发到群聊里同步信息再自己继续排查。这两条简单约定让团队看起来像“同一个团队”了而不是各干各的这个问题在前期准备阶段提前解决就不用忍受它在开发中期突然爆发。5.4 前期常见问题速查表我把准备阶段踩过和看到过的问题整理成了一张表方便大家对照排查。现象常见原因快速排查方向npm install卡住或下载失败默认源速度慢切换为镜像源检查代理设置前后端接口调不通版本不一致或地址写错确认技术版本清单检查请求URL和端口容器内数据库连接失败host仍写localhost改为Compose服务名或容器别名中文时间与本地差8小时连接串缺少时区参数连接串补充时区参数并配全局时区配置启动项目时依赖报错手动引入了版本冲突的依赖用 Spring Initializr 重新生成改由框架管理版本合并分支一堆冲突多人改同一文件拆分配置文件模块按功能分散提交某人的代码别人跑不起来node_modules或本地配置未清理规范化.gitignore统一提交package-lock.json这张表不求全但覆盖了准备阶段绝大多数高频问题。遇到类似的报错先按表里方向查一遍比自己对着控制台猜要高效得多。5.5 给准备阶段加一个“额外保险”如果你看完上面的内容还是担心自己漏掉某个环节我再分享一个小习惯在实训正式开始的前一天自己做一次全流程模拟。从克隆仓库开始按README的说明安装依赖、配置数据库、启动后端、启动前端、调用一次接口全流程走一遍。如果这个流程能在半小时内走通说明准备阶段的工作真正完成了。这个习惯最开始是我自己为了踏实才做的后来发现它还有一个额外价值它等于在项目开始前提前测试了一遍交接文档的质量。如果照着文档都跑不起来那文档肯定存在问题趁还没开工赶紧修掉如果文档写得足够清楚你自己和其他成员都会非常安心。准备工作的完成标准不是“代码写完了”而是“一个完全不知道项目细节的人拿着你的文档能一步一步把项目跑起来”。实训准备阶段还有一个容易被忽略的点不要一个人把准备工作全部做完。哪怕别人做得慢、做得粗也要让每个成员都参与进来。一个人包办所有准备确实效率高但其他成员对项目上下文的理解就会不足后面开发时的沟通成本会成倍增长。分一部分任务出去让每个人都能讲清楚项目是怎么来的、为什么这么设计这才是一次成功的前期准备。