项目实训前期准备指南：选题、调研、技术选型与团队协作

实训项目往往是大学阶段最接近真实开发的一段经历。和在教室里写课程作业完全不同，实训不会有人把每一步都给你安排明白，经常是甩给你一个一句话的课题目标，剩下的全靠自己慢慢把它变成能跑、能演示、能答辩的系统。这篇记录是系列笔记的第一篇，主题就是项目实训的前期准备工作。可能很多人觉得“准备”没啥好写的，但我自己的体会是，选题、调研、技术选型、环境搭建这些事情，恰恰决定了你后面两个月的开发是顺顺利利还是天天返工。

这个系列会按项目推进的时间线来写，第一篇聚焦准备阶段，后续再陆续整理开发、联调、测试和验收的过程。准备阶段基本不会产出业务代码，很多人不重视，但它直接决定了项目能不能在限定周期内完成，也决定了团队几个人能不能顺畅协作。我自己在这个阶段踩过不少坑，也对比过几种常见的做法，下面把这些经验和思路完整整理出来，给即将参加实训或者准备接手新项目的同学一个可参考的模板。

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 最终方案和理由：一张表说清楚

最终技术方案如下：

这个方案有几个隐含的考量。前端加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.0，IDE统一为同一个版本，前后端项目的包管理器也做了约定。关于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 前期常见问题速查表

我把准备阶段踩过和看到过的问题整理成了一张表，方便大家对照排查。

这张表不求全，但覆盖了准备阶段绝大多数高频问题。遇到类似的报错，先按表里方向查一遍，比自己对着控制台猜要高效得多。

5.5 给准备阶段加一个“额外保险”

如果你看完上面的内容，还是担心自己漏掉某个环节，我再分享一个小习惯：在实训正式开始的前一天，自己做一次全流程模拟。从克隆仓库开始，按README的说明安装依赖、配置数据库、启动后端、启动前端、调用一次接口，全流程走一遍。如果这个流程能在半小时内走通，说明准备阶段的工作真正完成了。

这个习惯最开始是我自己为了踏实才做的，后来发现它还有一个额外价值：它等于在项目开始前提前测试了一遍交接文档的质量。如果照着文档都跑不起来，那文档肯定存在问题，趁还没开工赶紧修掉；如果文档写得足够清楚，你自己和其他成员都会非常安心。准备工作的完成标准，不是“代码写完了”，而是“一个完全不知道项目细节的人，拿着你的文档能一步一步把项目跑起来”。

实训准备阶段还有一个容易被忽略的点：不要一个人把准备工作全部做完。哪怕别人做得慢、做得粗，也要让每个成员都参与进来。一个人包办所有准备，确实效率高，但其他成员对项目上下文的理解就会不足，后面开发时的沟通成本会成倍增长。分一部分任务出去，让每个人都能讲清楚项目是怎么来的、为什么这么设计，这才是一次成功的前期准备。