企业官网建设流程全解析

拿到一套"师生健康信息管理系统"的源码，先别急着双击运行，我习惯先把它拆开看：它在什么场景下会被需要？数据是怎么流转的？技术栈为什么这么选？里面埋了哪些只有上手才知道的坑？

这套系统的名字很直白，Java Web 师生健康信息管理系统，后端 SpringBoot2 + MyBatis-Plus，前端 Vue3 + Element Plus，数据库 MySQL8.0，交付物里除了前后端源码，还带 SQL 脚本和设计文档。我前后花了两天时间，从跑通环境到逐段读代码，再到复现了几个典型问题，今天这篇文章就是完整拆解笔记。无论你是准备做类似的校园管理项目，还是刚拿到这套源码想快速上手，这一篇都能帮你省下不少踩坑时间。

1. 项目到底在解决什么问题

1.1 需求场景还原

很多人听到"健康信息管理"第一反应是：这不就是个填表系统吗？确实，表面的需求很简单——学生填体温、填位置、填健康状况，老师看一眼结果。但真正落到代码层面，事情就复杂了。

高校里用户角色远不止"老师"和"学生"两类。实际运行至少要拆出五类人：学生（每日填报主体）、辅导员（审核督促）、教师（也要填报）、学院管理员（查看本院数据）、校医院或系统管理员（全局查看、报表导出）。如果只做一张用户表、一套通用权限，后面每加一个角色需求，代码就多一堆 if-else，迟早把项目改烂。

这个项目在权限模型上用了经典方案：用户表保留角色字段，角色绑定权限标识，接口层面用权限标识控制访问。学生只能调自己的上报接口，辅导员能查所带班级的列表，学院管理员能看到本院统计，系统管理员才能做用户管理。权限边界清晰，代码也好维护。

1.2 核心流程闭环

以学生用户为例，完整的操作闭环是这样的：

1. 用学号加密码登录系统
2. 首页看到当天填报状态，没填的会高亮提醒
3. 填写体温、是否咳嗽、是否发热、当前城市、是否接触风险人群等信息
4. 提交后记录状态变成"待审核"
5. 辅导员在审核列表里批量通过，或者标记异常并写备注
6. 学院管理员查询填报率、异常记录
7. 校医院管理员按日期导出全校 Excel

每一步都卡着上一环的数据。没有前面的上报，后面统计和导出全是空表。所以看源码的时候，我会盯着一条数据从写入到被读取的完整链路，这个链路通了，系统的主干就理解了。

1.3 这个项目能扩展成什么

这套系统的价值不在于它叫"健康上报"，而在于它把一条通用流程做得完整：身份认证、权限控制、单日单用户数据防重、审核状态流转、统计看板、文件导出。把它改造成任何"每日必填"类系统都行——考勤上报、实验室安全检查、心理问卷、活动报名，核心骨架基本不用动。

所以本篇拆解，我会把注意力放在通用能力上：登录鉴权怎么做、防重怎么实现、审核状态怎么设计、导出怎么不出 OOM。这些换一个业务场景依然能用。

2. 技术栈选型与架构设计

2.1 后端为什么是 SpringBoot2 + MySQL8.0

现在 SpringBoot3 已经大面积铺开，但这个项目选择 SpringBoot2，并不是技术落后，而是考虑兼容性。很多高校机房和公司内网服务器，JDK8 依然是主力。SpringBoot2.7 是 JDK8 下最稳的版本，团队不用为了跑一个系统强制升级服务器环境，落地阻力小。

MySQL8.0 的选择则更直接：8.0 的默认字符集 utf8mb4、窗口函数、JSON 类型、更好的索引下推，对这类多条件查询和统计报表非常友好。相比 MySQL5.7，8.0 在并发写入和复杂统计上都有明显提升，从 5.7 升级过来成本也不高。

MyBatis-Plus 是另一个省力选择。这类管理系统的数据操作九成是单表 CRUD，MyBatis-Plus 提供开箱即用的 BaseMapper，内置分页插件、逻辑删除、字段自动填充，Service 层代码量能砍一半。它跟原生 MyBatis 相比少了很多 XML 模板代码，跟 JPA 比又保留了 SQL 可控性——团队里哪怕有人 SQL 一般，也不容易写出无法优化的大查询。

2.2 前端为什么是 Vue3 + Element Plus

Vue3 的组合式 API 对这类"多表单 + 状态联动"页面特别合适。拿填报页举例，一个页面要同时管基础信息表单、校验规则、提交进度、审核状态提示，用 Composition API 把这些逻辑按功能块拆开，代码比 Options API 的 data/methods 散装结构清晰得多。

Element Plus 是 Vue3 生态里最成熟的中后台组件库，表格、表单、日期选择器、上传组件都有现成方案。配合 Vite 的开发服务器，冷启动和热更新速度比老一代构建工具快了一个量级，日常开发体验提升非常明显。

2.3 前后端目录与分层职责

后端结构是标准 MVC 分层：

src/main/java/com/xx/health ├── controller // 接口入口，只做参数接收和响应封装 ├── service // 业务逻辑层，事务边界 ├── mapper // MyBatis-Plus Mapper 接口 ├── entity // 数据库实体 ├── common // 统一返回、异常处理、工具类 └── config // 拦截器、CORS、分页插件等配置

这个分层的价值在于：Controller 层很薄，业务逻辑收在 Service，后续加事务、加缓存、加消息通知都有地方放。新手最容易犯的错是把业务全堆在 Controller，一时看着方便，改造时处处受罪。

前端结构：

src ├── api // 接口请求封装 ├── router // 路由配置 ├── store // Pinia 状态管理 ├── views // 页面组件 ├── components // 通用组件 └── utils // 工具函数

路由部分用了动态路由方案，登录后根据角色从后端拉菜单权限，再动态注册路由。这样做的好处是权限模型变化时前端不用改代码，后端返回什么菜单，前端就显示什么页面。

2.4 环境准备与快速启动

跑这套项目需要准备的环境很简单：JDK8 或 JDK11、Maven 3.6+、Node.js 16+、MySQL8.0。

启动顺序有讲究：

1. 先用项目里的 health.sql 脚本初始化数据库
2. 修改 application-dev.yml 里的数据库连接信息
3. 启动后端，看到 Spring Boot 启动日志无报错
4. 进入前端目录执行 npm install，再 npm run dev
5. 打开前端页面，用文档里的默认账号登录

如果你拿到的是完整源码包，里边的文档和 SQL 通常是配套的。先别急着改代码，按文档跑通一遍，确认登录、填报、审核、导出这些主流程没断了，再开始逐段看代码，这样的效率最高。

3. 数据库设计与核心表结构

3.1 用户、角色、权限的设计

数据库设计是这套系统的地基。用户表包含学号/工号、姓名、密码、角色ID、所属学院、班级、状态，字段命名规范，类型选择也合理。

密码字段存的是 BCrypt 加密后的哈希，不是明文也不是简单 MD5。这一点我在代码里专门确认过。用 BCrypt 的好处是自带随机盐，同一个密码每次加密结果都不一样，即使数据库泄露，破解成本也高得多。

角色表只存了角色名和描述，没有把权限表拆得很碎。权限控制靠的是权限标识字符串，比如student:report:submit、admin:user:list，挂在角色上。这个设计在几千用户、十几种权限的规模下完全够用，优点是查询快、好理解，缺点是权限粒度为"接口级"，不能精确到具体数据行。如果想做成"辅导员只能看自己带的班级"，需要额外在 SQL 查询里加数据范围条件，这个项目通过查询参数已经处理了。

3.2 健康上报主表与唯一索引

核心业务表是健康上报表，我把它记为 health_report。字段设计大致是这样：

这张表最关键的设计是联合唯一索引。在 user_id 和 report_date 上建了唯一约束，从数据库层面保证"一个人一天只能有一条主记录"。这个设计能兜底应用层所有的校验漏洞——哪怕前端绕过按钮、后端绕过判断，数据库也能把重复数据挡回去。

参考 DDL 大概这样：

CREATE TABLE `health_report` ( `id` bigint NOT NULL AUTO_INCREMENT, `user_id` bigint NOT NULL COMMENT '上报人ID', `report_date` date NOT NULL COMMENT '上报日期', `temperature` decimal(4,1) DEFAULT NULL COMMENT '体温', `health_status` varchar(20) DEFAULT '正常' COMMENT '健康状况', `is_cough` tinyint(1) DEFAULT '0' COMMENT '是否咳嗽', `is_fever` tinyint(1) DEFAULT '0' COMMENT '是否发热', `location` varchar(255) DEFAULT NULL COMMENT '当前所在位置', `contact_risk` tinyint(1) DEFAULT '0' COMMENT '是否接触风险人群', `status` tinyint(1) DEFAULT '0' COMMENT '审核状态', `deleted` tinyint(1) DEFAULT '0' COMMENT '逻辑删除', PRIMARY KEY (`id`), UNIQUE KEY `uk_user_date` (`user_id`, `report_date`, `deleted`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='每日健康上报表';

注意我把唯一索引建成了三元组（user_id, report_date, deleted），而不是只建（user_id, report_date）。原因在本文第 6 章会详细讲，这是逻辑删除和唯一索引最常见的一个冲突点。

3.3 异常登记与审核状态字段

系统里除了主上报表，还有一张异常登记表，用于记录体温异常、症状明显等特殊情况。它与主表是一对多的关系：一天内一个人可以有多条异常记录（上午正常，下午发烧被登记），但主表一天只有一条汇总状态。

审核没有单独拆一张表，而是直接在主表上加 status、auditor_id、audit_remark 字段。这个设计很务实——一个用户一天一条记录，审核状态变更直接 UPDATE 原行即可。如果以后需要完整的审核流水历史，再拆一张 audit_log 表也不迟。

3.4 初始化数据的重要性

项目的 SQL 脚本里除了建表，还预置了角色数据、一个系统管理员账号、测试学院班级数据。这一步千万别跳过。没有初始角色和默认账号，前端登录进去会发现菜单全是空的，权限判断全失效。新手排错最容易在这里卡住，以为代码有问题，其实是数据库初始化数据没导入完整。

4. 核心功能实现详解

4.1 登录鉴权：JWT + 拦截器 + 自定义注解

登录接口是 /api/auth/login。前端提交学号和密码，后端用 BCrypt 做密码匹配，匹配成功后生成一个 JWT，里面包含 userId、角色编码、过期时间，返回给前端。前端把 Token 存到 localStorage，每次请求通过 Authorization 请求头带上。

Token 过期时间在这个项目里默认设了 4 小时。校园场景里学生上午和下午可能各登录一次，4 小时够用。前端 Axios 拦截器发现请求返回 401 时，会清除本地 Token 并跳转登录页，处理方式简单可靠。

接口权限控制没有靠每个 Controller 手动判断，而是封装了自定义注解：

@Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) public @interface RequireRole { String[] value(); }

在拦截器里统一做 Token 校验和角色判断。白名单接口（登录、验证码、健康检查）直接放行，其余接口先解析 Token，再按注解比对角色，不匹配直接返回 403。这样Controller 里的代码干净很多，权限规则也集中在一个文件里维护。

拦截器核心逻辑简写：

@Component public class JwtInterceptor implements HandlerInterceptor { @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { if (handler instanceof HandlerMethod) { HandlerMethod hm = (HandlerMethod) handler; RequireRole requireRole = hm.getMethodAnnotation(RequireRole.class); if (requireRole == null) { return true; } String token = request.getHeader("Authorization"); if (StringUtils.isBlank(token) || !jwtUtil.validate(token)) { response.setStatus(401); return false; } String roleCode = jwtUtil.extractRole(token); if (!Arrays.asList(requireRole.value()).contains(roleCode)) { response.setStatus(403); return false; } } return true; } }

这套东西看起来简单，实际生产环境里还有两个细节要注意：一是 Token 要设置一个合理的过期时间，太短天天让用户重登，太长泄露了风险大；二是密码加密不要用 MD5，即使加盐也不建议，BCrypt 是基本盘。

4.2 每日上报：防重与并发控制

上报接口是系统压力最大的接口，设计核心是"先查后插 + 唯一索引兜底"：

1. 前端提交前先调用查询接口获取当日填报状态，已填报则提示用户
2. 后端先查一次当日记录，存在则直接返回提醒
3. 不存在就执行 INSERT，数据库唯一索引兜底
4. 万一并发场景下两条请求同时插入，唯一索引会拦住后到的那个，捕获 DuplicateKeyException 转成"请勿重复提交"提示

这条路径没有设计复杂的事务，因为一次填报就是一条单表 INSERT，涉及的状态流转在提交完成后异步处理。这样并发能力完全取决于 MySQL 单表写入能力。实测高峰期并发提交几百条，MySQL8.0 可以轻松扛住。

如果以后要支持辅导员批量代填，可以在 JDBC 连接串上开启 rewriteBatchedStatements=true，再用 MyBatis-Plus 的 saveBatch，批量插入性能能提升一个量级。

4.3 辅导员审核：状态流转与批量处理

审核是这套系统的第二个核心业务。状态字段 status 取值范围：0待审核、1通过、2异常、3驳回。辅导员界面有筛选条件，默认只看待审核记录，可以单条操作，也可以勾选多条批量通过。

批量通过的 SQL 看起来很简单，但有一个关键细节：WHERE 条件里除了 id IN 列表，还要带上AND status = 0。这样能防止两个辅导员同时审核同一条记录时，后审核的人把前面的结果覆盖掉。这种乐观锁思路在处理并发审核时非常实用。

审核通过的记录，前端列表会实时更新。前端轮询待审核数量，发现变化就刷新列表，实现成本低，也不引入 WebSocket 复杂度。对数据量小的管理后台来说，这是最优解。

4.4 统计看板与 Excel 导出

管理端的价值在统计。首页看板需要展示今日填报率、各学院填报人数排名、异常趋势。

这些指标如果每次都全表聚合查询，高峰期数据库压力会比较大。这个项目用了简单缓存策略：当日统计结果缓存 5 分钟，过期后重新计算，在数据实时性和查询压力之间取了个平衡。数据量到几千人时，本地缓存完全够用。

Excel 导出用的是 EasyExcel。相比 POI 原生 API，EasyExcel 流式写入在处理几万行数据时内存占用低很多。这一点非常重要，因为 POI 的 XSSFWorkbook 会把整个 Excel 文件结构放在内存里，数据量一上来很容易 OOM。用 EasyExcel 按行写，内存占用非常稳定。

4.5 前端页面与表单校验

前端最核心的页面是填报页。体温输入框有三个校验规则：数字范围必须在 35 到 42 之间，小数位只能有一位，非法字符即时拦截。Element Plus 的 form 校验用自定义 validator 可以轻松实现。

日期处理上，填报页默认显示当天日期，不可选未来日期，历史日期也不允许正常用户补报。这些限制前后端都要做，否则有人直接构造请求就能绕过前端提交未来数据。

这里有个前端常见的坑：日期组件拿到的是 Date 对象或者格式化字符串，提交给后端时可能因为时区偏移导致日期差一天。所以项目里统一用字符串格式yyyy-MM-dd传递日期参数，后端用@DateTimeFormat解析，前后端约定一致，就不会出问题。

5. 前后端联调与部署实践

5.1 统一返回结构与异常处理

前后端联调最烦的是接口格式不统一。这套系统在响应结构上做了统一约定：

{ "code": 200, "message": "ok", "data": {} }

code=200 代表成功，其它 code 代表业务失败。后端有一个全局异常处理器，统一捕获参数校验异常、业务异常和系统异常，把可读的错误信息返回给前端，不会把堆栈信息直接暴露出去。

前端 Axios 响应拦截器也做了配套：请求拦截器负责加 Token，响应拦截器统一判断 code，业务失败就用 Element Plus 的 Message 组件弹出后端返回的 message。这样一来，前端页面基本不用写重复的错误处理代码。

5.2 Axios 封装与 Token 管理

Axios 封装看起来简单，但有几个细节直接决定使用体验。请求拦截器从 localStorage 取 Token，但这有一个坑：如果系统支持多标签页，一个标签页退出登录后，其它标签页的 Token 并不会自动清除。这个问题在管理后台里不算严重，如果较真可以引入 token 失效广播机制，或者干脆用 cookie 与后端保持会话，但使用 Header 传 Token 仍然是目前主流的无状态方案。

响应拦截器里对 401 的处理一定要谨慎。用户 Token 过期会收到 401，拦截器跳转登录页没问题，但要避免在 Token 失效瞬间多个请求同时返回 401 而导致重复跳转。加一个标志位锁就可以解决。

5.3 CORS 跨域配置

前端是独立部署的 Vite 应用，后端是 SpringBoot 服务，不同源必然碰到跨域问题。

后端配置了 CORS 允许来源、允许方法、允许请求头。有一个容易忽略的点：如果将来切换到 Cookie 鉴权，就必须开启 allowCredentials=true，同时 CORS 允许的来源不能再用通配符*，必须写明具体来源。这个项目走 JWT Header 方案，绕开了 Cookie 跨域的坑，部署上省心不少。

如果是在开发环境，更省事的方案是用 Vite 的 proxy 代理，把/api前缀的请求转发到后端地址，这样浏览器看到的还是同源请求，完全不碰跨域问题。生产环境则建议用 Nginx 统一反向代理，前后端都在同一个域名下，跨域问题直接消失。

5.4 生产构建与服务器部署

前端构建：

npm run build

生成的 dist 目录交给 Nginx 托管。Nginx 里需要注意把未知路径都 rewrite 到 index.html，否则刷新页面会出现 404，因为 Vue Router 的 history 模式需要服务端配合。

后端打包：

mvn clean package -DskipTests

生成 jar 包后直接java -jar运行。生产环境配置文件要单独抽出来，比如 application-prod.yml，数据库密码、端口等敏感配置不要写进代码仓库。启动时通过--spring.profiles.active=prod指定环境。

加密的数据库密码怎么处理？常见做法是把密码放在环境变量里，Spring Boot 用${DB_PASSWORD}占位符读取。这样即使代码仓库泄露，生产环境密码也不会暴露。

6. 常见问题与避坑实录

6.1 MySQL8.0 的时区与 SSL 问题

这是项目跑到第一步最常见的报错：The server time zone value '?й' is unrecognized。MySQL8.0 的 JDBC 驱动会强制要求声明 serverTimezone，连接串上加上：

?serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true

能一次性解决时区报错和 SSL 连接警告。allowPublicKeyRetrieval=true 这个参数很多人忽略，本地 MySQL8.0 用 caching_sha2_password 认证时，非 SSL 连接第一次需要获取服务端公钥，不加这个参数会连不上。

6.2 逻辑删除与唯一索引的冲突

这是这套系统里最容易踩的隐藏坑。项目用了 MyBatis-Plus 的逻辑删除字段，默认值 0。问题来了：假设唯一索引只建了 (user_id, report_date)，某天有一条记录被逻辑删除了（deleted=1），第二天用户重新上报同一天的数据，数据库里那条"已删除"的记录依然存在，唯一索引就会阻止新的 INSERT，报 DuplicateKeyException。

解决方案就是我在建表 SQL 里写的：唯一索引改为 (user_id, report_date, deleted)。因为逻辑删除后新插入的记录 deleted=1，和已删除那条的 deleted=1 相同，仍然会冲突。

这里还有一个更深的坑：如果需求允许同一天数据被删除多次、重新填报多次，三元组索引依然会冲突。MySQL 的普通索引不会对 NULL 去重，所以可以再把 deleted 字段默认值改成 NULL，删除时置为当前时间戳，这样每次删除的值都不同，唯一索引完全放行。但这么做会破坏 MyBatis-Plus 对逻辑删除的默认判断，需要自定义逻辑删除值。具体取舍要根据业务需求来。

6.3 前端时间显示偏移 8 小时

后端 LocalDateTime 序列化成 JSON 返回给前端时，如果时区配置不对，前端会看到比实际时间少 8 小时。

解决办法在后端统一配置 Jackson 的时区为 GMT+8，或者干脆把时间以字符串格式 "yyyy-MM-dd HH:mm:ss" 传给前端。管理类系统对时间的格式一致性要求高，推荐后者，简单直接，不容易受时区干扰。

6.4 高峰期并发与限流

每日填报高峰往往集中在某个时间段，几千人同时提交。除了数据库单表单条插入这种优化外，最好在 Nginx 做一层限流，比如单 IP 每分钟最多 20 次请求。这个项目源码本身没有内置限流组件，但改造时引入 Redis + 令牌桶或者 Nginx 的 limit_req 模块，成本很低，能有效防止接口被刷爆。

还有一个容易忽略的细节：前端提交按钮在点击后要立即禁用，避免用户双击重复提交。后端做防重，前端也要做防抖，两层防护才能保证体验和数据都正常。

6.5 从报错到定位：问题排查心态

接手这套项目时最容易遇到的情况是：按照文档配好了环境，启动却报各种错。我的排查顺序是：

1. 先看后端启动日志，确认数据库连接、SQL 初始化有没有问题
2. 再看前端控制台和 Network 面板，确认接口请求有没有发出去
3. 如果请求发出去了但报错，用 IDEA 在后端打断点，顺着接口一路往下走

绝大多数"页面打不开"或"登录不上"的问题，都出在环境配置上，而不是源码逻辑上。把注意力放在"接口、表结构、页面"三者对应关系上，比盯着某一段代码反复猜靠谱得多。

7. 扩展方向与个人沉淀

这套 SpringBoot2 + Vue3 + MyBatis-Plus + MySQL8.0 的组合，对校园内部管理类系统来说是稳得住的方案。它没有追新框架，而是每一步都选择可维护、可排查的成熟路径，这对团队协作和后续交接非常重要。

如果后续要在这个系统上做扩展，我优先建议做两件事：一是给核心的上报、审核、导出操作加操作日志，方便出问题时溯源；二是把统计接口的缓存从"本地内存"升级为 Redis，这样前端部署多副本时，不需要担心实例之间的缓存一致性问题。这两件事做完，系统的生产可用性会明显上一个台阶。

最后分享一个接手这类全栈项目的小技巧：第一步别急着改代码，先把项目跑起来，然后对着接口文档把后端接口全部过一遍，再打开数据库看表结构。把"接口-表-页面"三者对应起来之后，整个项目在你脑子里就是一张图了，剩下的事情只是往图里填细节。这套方法我用了很多年，每到一个新项目都从这张图开始，省下的时间远比我花在排错上的多。