1. 项目整体设计与技术选型做这个系统的起因很直接某高校教务部门需要一个能在线管理课题申报、审核、存档全流程的Web系统替代原来“表格发群里、负责人收Excel、人工核对再汇总”的老办法。接到需求的时候我就在想这种典型的校内业务系统技术栈选型其实没有什么悬念——后端用Java生态里最稳的SpringBoot前端用Vue3配上现在最顺手的Element Plus组件库持久层用MyBatis系数据库上MySQL。这套组合我在多个项目里验证过开发效率、上手难度、后期维护成本都比较均衡尤其适合中小型团队快速交付。1.1 为什么选前后端分离而不是传统模板渲染早期做Java Web项目很多人习惯用Thymeleaf或者JSP直接在服务端渲染页面一个Controller里既写接口又拼页面业务一复杂代码就纠缠在一起。这次我一开始就想清楚必须做前后端分离原因有三第一那个高校的教务处有多个校区现代Web系统的访问场景早就不是打开电脑用浏览器这么单一移动端、平板、小程序都可能要对接。前后端分离之后后端只要把JSON接口提供给前端调未来接其他端会非常方便不用再为每种终端各写一套页面。第二Vue3这种前端框架在交互体验上有很大优势可以做到局部刷新、表单校验、组件复用页面操作更流畅这对使用者来说体感差异明显。第三前后端分离能明确分工一个人负责接口一个人负责页面接口定义好之后可以并行开发工期能压缩很多。这种架构的代价是需要统一约定接口规范比如返回体要一致、错误码要统一、鉴权方式要明确否则会变成一锅粥。我在这个项目里用了一个统一的RespResult结果封装类所有接口都返回这个结构前端拿到code为200的数据就正常渲染否则弹错误提示开发过程中沟通成本低很多。1.2 技术栈明细与版本选择层级技术选型版本核心用途后端框架SpringBoot3.xWeb服务、依赖管理、自动配置持久层MyBatis-Plus3.5.x单表CRUD免写SQL、分页插件数据库MySQL8.x业务数据存储前端框架Vue33.4组合式API开发、响应式界面构建工具Vite5.x快速启动、热更新UI组件Element Plus2.x表格、表单、弹窗、树形组件状态管理Pinia2.x用户登录态、全局配置存储鉴权方案JWT0.11.x无状态身份认证接口文档Knife4j4.x前后端联调、接口调试文档这里特别说一下SpringBoot版本。我选的3.x版本它要求JDK 17及以上如果团队用惯了JDK 8不建议盲目上3.x升级会有一些兼容性工作量。但如果是新项目我建议直接用3.x因为SpringBoot 2.x已经停止维护新项目没有必要给自己埋坑。MySQL 8.x 同样是现在的绝对主流字符集、索引、窗口函数都比5.7强不少。补充说明如果你所在环境只能使用JDK 8那SpringBoot选2.7.x MyBatis-Plus 3.4.3也能跑得很稳。技术选型永远服务于现有环境不用盲目追新。1.3 项目整体架构蓝图整个系统的架构可以拆成三个层面来看。前端是一个独立的Vue3工程负责用户登录、申报表单填写、课题列表查询、审核意见录入、通知公告发布等界面通过HTTP请求调用后端接口。后端是一个SpringBoot应用采用经典的分层结构Controller接收请求、Service处理业务逻辑、Mapper与数据库交互。数据库MySQL负责持久化所有业务数据。还有一个容易忽略的层面是配置管理。前后端分离之后跨域问题、接口地址管理、环境切换这些都要提前设计好。我在前端用Vite的环境变量根据开发、测试、生产环境切换不同的接口地址后端则用application.yml配合不同环境profile。这样做的好处是部署时只需要改配置不用动代码。2. 数据库设计与核心模块拆解数据库是这类业务系统的地基表结构设计得好不好直接影响后面开发是不是顺畅。我的习惯是在写代码之前先把表设计完整至少把核心的几张表定下来中途再改表结构会很痛苦。这个系统的业务围绕“课题申报”展开涉及的核心角色包括学生或教师申报人、院系管理员、教务处领导另外还有系统管理员。2.1 核心数据表设计我以课题申报管理系统的实际表设计为例核心表包括用户表、课题信息表、申报记录表、审核意见表、通知公告表和系统日志表。每张表的设计都要从业务出发用户表承担认证与角色管理。字段包括账号、密码BCrypt加密存储、姓名、所属院系ID、角色类型。角色采用的是简单的字符串字段区分虽然扩展性不如角色权限表那么强但对这个规模的项目完全够用而且逻辑直观。课题信息表是核心业务表保存课题名称、课题类别重点项目/一般项目/教改项目、申报年度、研究内容摘要、预期成果、预算金额、附件文件路径、当前状态等核心字段。状态字段我用tinyint类型存储0-草稿、1-已提交待审核、2-院系初审通过、3-院系初审驳回、4-校级审核通过、5-校级审核驳回、6-已立项每个状态都对应前端不同的展示样式。申报记录表用于审计追踪保存课题ID、操作人ID、操作动作、操作时间、申报材料快照。这张表的价值在于出现纠纷时能还原整个历史过程属于“保命表”一定要有。审核意见表保存审核人或驳回意见关联申报记录表存储审核级别院系/校级、结论、处理意见文本、审核时间。审核意见支持多轮审批所以是一对多关系。通知公告表用于发布系统通知字段包括标题、内容、发布人ID、发布状态、置顶标记。校园系统里这种信息触达功能很常见简单但很实用。系统日志表记录关键操作日志例如登录日志、导入导出日志、数据修改日志方便出问题时回溯。2.2 表结构设计的几个易错点这里说几个我踩过的坑。第一个坑是关于审核流程的。刚开始我把审核状态只放在申报记录表里后来业务需求说要统计立项率发现单独统计很不方便。后来我把聚合统计下沉到课程表里在课题表上维护一个冗余状态字段统计时可以直接groupBy效率高很多这是一次典型的为了查询效率而冗余的设计。第二个坑是附件存储。最开始的设计是直接存文件字节流到MySQL的BLOB字段后来发现文件不大时还行一旦附件体积涨上去数据库膨胀严重、备份慢、查询降速。后来统一改成在服务器上保存附件文件数据库里只存文件相对路径。部署的时候再配置一个统一的静态资源映射目录实现文件存储和业务的解耦。第三个坑是时间字段。MySQL的datetime和timestamp在实际使用中老有人搞混导致时区错乱。我统一用datetime存储业务时间并在后端使用Java 8的LocalDateTime类型对应同时实体类字段上加TableField(fill FieldFill.INSERT)让框架自动填充创建时间和更新时间。如果你对时区问题特别敏感可以考虑把带时区信息的时间字段与服务器时区配置一起调整好保证上线后不会出现时间差八小时的情况。2.3 登录与权限控制实现思路这个系统涉及三类角色权限设计上我采用的是JWT 拦截器的方式前端在登录成功后拿到token存到Pinia全局Store和本地Storage。后端写了一个拦截器统一拦截需要登录的接口从HTTP请求头取出token解析出用户ID、用户名和角色然后存到当前请求上下文中。角色权限没有做很复杂的RBAC模型就在Controller方法上用自定义注解标注拦截器里校验角色是否匹配。项目规模小的时候这种方案最直接如果后面要扩展真正的RBAC基础的token机制也不用推翻只需要再加一层权限表查询就好。权限这块我提醒一点拦截器里不要只校验token是否存在还要校验token是否过期以及用户状态是否有效否则会有账号被禁用后依然能访问接口的安全隐患。3. 实操过程与核心环节实现这一部分我把整个开发过程从零到一完整梳理一遍按步骤走每一步都写清楚核心代码和关键思路方便照着落地。3.1 工程初始化与基础配置后端工程我用Spring Initializr生成选择Maven作为构建工具Java版本设成17依赖勾选Spring Web、MyBatis Framework、MySQL Driver、Lombok。生成之后手动引入MyBatis-Plus和JWT相关依赖然后在pom.xml中管理版本号。parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version relativePath/ /parent dependencies dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.6/version /dependency dependency groupIdcom.auth0/groupId artifactIdjava-jwt/artifactId version4.4.0/version /dependency dependency groupIdcn.hutool/groupId artifactIdhutool-all/artifactId version5.8.27/version /dependency /dependenciesapplication.yml里面有几个关键配置一个是数据源另一个是MyBatis-Plus的配置。MyBatis-Plus的逻辑删除、乐观锁、主键类型这些配置建议都显式写出来不要靠默认值避免工程里不同机器上的行为不一致。spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/subject_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalse username: root password: root123 servlet: multipart: max-file-size: 20MB max-request-size: 50MB mybatis-plus: global-config: db-config: logic-delete-field: deleted logic-delete-value: 1 logic-not-delete-value: 0 configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl map-underscore-to-camel-case: true3.2 后端核心接口实现过程后端接口要从登录接口说起。登录接口接收前端传来的账号密码先从用户表查账号再用BCrypt校验密码。校验通过后生成JWT字符串返回前端同时返回用户基本信息。这里生成token用到了用户ID和角色作为payloadtoken的有效期设置成8小时过期后前端拦截到401状态自动跳回登录页。PostMapping(/login) public RespResult login(RequestBody LoginDTO dto) { String token authService.login(dto.getAccount(), dto.getPassword()); return RespResult.success(token); }课题申报最核心的接口是发起申报与提交审核。发起申报的逻辑是用户登录后前端调课题保存接口将课题基本信息存到课题表状态默认为草稿用户点“提交申报”之后后端首先做必填项校验再判断该用户本年度是否已经提交过同类型的课题防止重复申报。这里我写了一个校验方法查询本年度相同课题名称和相同申报人政的记录如果存在就返回业务错误码。审核接口的逻辑相对复杂因为审核要区分院系级和校级两个层级。院系管理员审核时只更新课题状态校级审核时还需检查院系初审意见是否已经提交防止跳过流程。为了防止并发操作导致状态错乱我用乐观锁控制了课题表的状态更新在表里增加version字段更新时先比较版本号再更新。3.3 前端页面开发与接口联调前端工程我用Vite创建选择Vue3 JavaScript模板然后安装Element Plus、Pinia、Vue Router、Axios。目录结构上我把页面放在views文件夹内部按模块分子目录比如views/login、views/subject、views/audit、views/system。公共组件放components接口请求统一写在api文件夹。前端技术栈的关键点是封装Axios请求与拦截器。我在拦截器里做两件事第一请求时从Pinia读token放到请求头第二响应时统一处理HTTP状态码和业务状态码HTTP 401强制跳登录页业务code非200时用Element Plus的ElMessage弹出错误提示。这样业务代码在调用接口时根本不用关心错误处理代码清爽很多。课题申报页面的核心是复杂表单我用动态表单的方式来支持多个申报人协同填写。申报课题时可能需要填研究内容、预期成果、经费预算、成员列表等这些字段比较多我是用了一个stps步骤条分三步填完。预算金额在前端做了格式校验只能输入两位小数防止脏数据入库。表格展示页主要用ElTable组件配合分页。分页参数是pageNum和pageSize后端返回总记录数total和当前页records。前端分页组件切换时把页码传给后端查询接口。搜索区域做成表单提交时后端走条件查询前端根据不同状态显示不同的标签颜色比如草稿灰色、待审核橙色、已立项绿色。3.4 前后端分离的联调细节与部署方案联调阶段最容易出问题的就是跨域。我后端写了一个CorsConfig配置类通过WebMvcConfigurer添加跨域映射允许前端开发地址访问。上线时后端用Nginx做反向代理把同域名的/api路径转发到后端服务前端页面由Nginx托管这样生产环境就不存在跨域了配置简单而且稳妥。后端部署我用的是Maven打包成jar包然后配合systemctl服务方式运行。启动命令里指定了JVM参数比如最大堆内存设为512M。前端打包执行npm run build构建产物放在dist目录拷贝到Nginx的html目录下并配置location。整个部署流程我已经验证过两次从零到上线大约二十分钟可以完成。测试环境我建议直接在application.yml里把数据库连接打印出来配合MyBatis-Plus的SQL日志输出联调阶段能在控制台看到每一次执行的SQL排错效率会高非常多。4. 常见问题与排查技巧实录这部分是从这个项目以及类似项目中真实遇到的坑我整理成了速查表每一条都对应具体的排查思路和解决动作希望能帮你少走弯路。4.1 项目中的典型问题速查表症状可能原因排查方法解决方式前端接口请求404接口路径写错或后端Controller没加RequestMapping前缀浏览器F12查看请求URL对照后端日志的映射关系统一约定RESTful路径风格前端api目录和后端Controller对应时间字段显示相差8小时数据源URL未配置serverTimezone或者后端LocalDateTime序列化格式不一致查看数据库连接URL和Jackson配置在数据源URL中加入serverTimezoneAsia/Shanghai并配置jackson时间格式前端上传文件失败Nginx请求体大小限制查看Nginx错误日志在Nginx的server块配置client_max_body_size 50mMySQL中文乱码数据库、表、连接三处字符集不一致查询数据库character_set_database和连接URL创建数据库时指定utf8mb4连接URL加characterEncodingutf8分页数据异常重复排序字段不唯一检查SQL语句观察排序字段分页排序按id加创建时间双字段排序MyBatis-Plus 自动填充不生效缺少TableField(fill...)或MetaObjectHandler配置检查实体类注解和MyBatis-Plus配置类新建MetaObjectHandler实现类配置insertFill和updateFill接口被拦截器拦截放行路径不对拦截器addPathPatterns和excludePathPatterns配置错误查看拦截器注册代码Swagger、登录接口等公开路径必须显式放行4.2 几个值得单独展开的排查实录先说一个登录相关的坑。某次有同学反馈说用户改完密码之后用旧密码居然还能登录。查了半天发现JWT的有效期内没有校验数据库里的最新密码hash导致被踢下线之后旧token依然有效。解决方案是在JWT里放一个密码变更时间戳拦截器解析token后去用户表比对变更时间如果晚于token签发时间就强制要求重新登录。这个方案目前用下来很稳建议有类似需求的系统直接抄走。另一个是上传文件的累积问题。附件文件存在服务器某个目录里刚开始没做清理跑了几个月发现有大量废弃附件占磁盘空间。后面加了一个定时任务每天凌晨扫描申报记录表找出不再关联任何课题记录的文件并删除。同时部署时把文件目录挂载到独立的磁盘这样即使系统重装也不会丢文件。还有一个比较隐蔽的问题是SQL注入。虽然MyBatis的参数绑定机制能防住大部分注入但在使用${}拼接排序字段或者动态表名的时候一定要校验白名单。我看到过不少项目在order by列名上直接用前端参数拼进去这个非常危险。我的做法是排序字段写死一个白名单Map前端传符后做映射查不到就默认按创建时间排序。4.3 踩坑后的优化经验总结做完这个项目后我总结了几条关于业务系统的开发经验。第一不要把数据库当作文件服务器大字段和二进制文件尽量外置数据库只要存好路径和元数据。第二业务系统的权限设计不需要一开始就做到极其复杂但登录认证和操作日志一定要做扎实这是系统安全的第一道和最后一道防线。第三前后端接口的入参校验要同时做前端校验是为了用户体验后端校验才是真正的安全防线。第四日期时间处理统一使用ISO标准格式前端展示时再转成本地格式避免各国各地区用户看到差异。5. 个人实操心得与扩展建议最后分享一点我做这类管理系统的心得。很多人问这类系统难不难其实技术难度并不高从某个角度来说它就是典型的CRUD加状态流转加角色权限。真正的复杂度在于业务流程的梳理比如审核流中驳回之后能不能重新提交、同一个人能不能同时报多个课题、修改课题信息时是否要留痕这些业务规则想清楚并落到代码里系统才算是真正可用。从技术层面如果你已经掌握了SpringBoot和Vue3的基础用法这个项目非常适合作为完整的实战练习它能让你系统性接触登录鉴权、拦截器、多表联查、复杂表单、文件上传、接口文档生成、服务器部署这一整条链路。比东一个压缩包西一个零散笔记的碎片化学习要有效得多。最后再给一个扩展方向这个系统后续还可以加一个数据统计Dashboard比如按学院统计课题申报数量、按年度统计立项率前端用ECharts做可视化大屏。也可以在现有权限体系之上引入更完善的RBAC甚至在课题审核中接入消息通知或企业微信机器人通知。这些扩展都不会推翻现有架构只要你把接口规范、表结构规范、代码分层规范守住系统的生命力会比你预想的长很多。