系统最终章：从功能完成到可交付的权限、幂等与部署验证指南

海兰德铁道学院是一个轨道交通岗位技能培训信息系统的代号。项目推进到最终章，团队最常遇到的状态不是功能没写，而是功能写了一大堆，真正换一台机器、换一个账号、按一条完整业务流走一遍，立刻暴露出权限漏洞、数据不一致、部署环境不干净、演示脚本临场卡壳。最终章真正要回答的问题，不是“还能加什么功能”，而是“当前这一版能不能安全地交给使用者”。这里以“实训报名与成绩发布”作为核心业务链路，从数据模型、工程保护、验证路径、部署与文档几个角度，说明最终章应该检查什么、补什么、怎么验证，并给出一条可复现的排错链路。适合正在做实训项目收尾、毕业设计提交前自查，或者负责一个小型内部系统上线前验收的同学参考。

1. 最终章的核心目标：从“功能写完”变为“可以交付”

1.1 “能跑”和“能交付”之间差了哪些工作

开发阶段的“能跑”，通常是在本机环境下验证了一次成功操作。最终章要面对的是验收环境，可能是另一台电脑、另一个数据库、另一个人来操作。要把这一次成功操作扩展成一组用例，并补上失败路径，才算真正可交付。

可以交付的系统至少满足这些条件：

• 在一个干净环境里，按业务顺序执行完核心流程不会中断。
• 未登录、无权限、重复提交、参数错误等异常操作有明确反馈。
• 关键日志能定位到某一次请求的执行过程。
• 部署文档和SQL脚本可以独立复现。
• 数据不会出现重复、孤儿记录、状态错乱。

很多项目在“能跑”阶段被贴上“完成”标签，实际上缺少的是边界处理、权限校验、并发保护和部署验证。这几项在功能开发阶段容易被忽略，在最终章却会决定验收是否通过。

“能跑”和“能交付”的差异可以这样对比：

维度	能跑	能交付
功能	核心接口通	核心、边界、异常路径都覆盖
数据	本地有数据	唯一约束、状态机、外键关系正确
权限	登录能进	未登录和无权限操作均被拦截
依赖	本机可启动	新环境按文档可复现
运维	日志有输出	日志可定位、配置可外置、可备份回滚
文档	代码里有注释	README、部署、接口、数据字典完整

1.2 用收尾清单圈定工作边界

最终章最容易犯的错误是继续加需求。每加一个功能，就会带来新的接口、新的数据、新的回归风险。建议先冻结需求，按收尾清单逐项核对，而不是让开发人员继续在代码里“顺手补一个功能”。

一份可复用的收尾清单可以这样定义：

1. 数据模型是否满足业务约束：唯一索引、外键关系、状态字段。
2. 核心业务链路是否完整：查询、报名、确认、发布成绩、查看结果。
3. 后端接口是否都做了登录和权限校验。
4. 写操作是否具备幂等或并发保护。
5. 异常分支是否有提示、日志和状态码。
6. 部署过程是否能在干净环境里复现。
7. 演示数据是否干净，是否存在脏数据和重复数据。
8. 文档是否和当前代码一致。

注意：收尾清单不是上线后才贴到会议室里的，建议在进入最终章第一天就建立，每处理完一项就记录验证结果。这样验收时可以把记录直接作为项目状态说明。

2. 从数据模型开始核对：实训报名与成绩的状态机

2.1 报名和成绩表先设计成这样

一个轨道交通技能培训系统，至少要覆盖三类数据：实训课程、学生报名、成绩发布。下面给出一个最小例子，后续代码都围绕它展开。

CREATE TABLE train_course ( id BIGINT PRIMARY KEY AUTO_INCREMENT, course_name VARCHAR(100) NOT NULL, capacity INT NOT NULL DEFAULT 30, status VARCHAR(20) NOT NULL DEFAULT 'DRAFT', created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP ); CREATE TABLE train_enrollment ( id BIGINT PRIMARY KEY AUTO_INCREMENT, course_id BIGINT NOT NULL, student_id BIGINT NOT NULL, status VARCHAR(20) NOT NULL, version INT NOT NULL DEFAULT 0, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, UNIQUE KEY uk_course_student (course_id, student_id) ); CREATE TABLE train_score ( id BIGINT PRIMARY KEY AUTO_INCREMENT, enrollment_id BIGINT NOT NULL, score DECIMAL(5,2), published_by BIGINT, published_at DATETIME, version INT NOT NULL DEFAULT 0, UNIQUE KEY uk_enrollment (enrollment_id) );

这里的核心是train_enrollment表。唯一索引uk_course_student保证同一个学生对同一门课程只能出现一次报名主记录，即使前端因为网络问题把请求发了两遍，数据库也会挡住重复数据。train_score表通过enrollment_id唯一索引保证一份报名记录只对应一条成绩。

version字段暂时还不做逻辑处理，它给后续的乐观锁使用。如果最终章发现成绩或报名状态可能被多人同时修改，这个字段会成为必要的保护手段。

2.2 状态不是字符串，是业务规则

很多项目直接用字符串存状态，比如status等于ENROLLING、CONFIRMED、CANCELLED、FINISHED。但问题在于，任意位置都可以直接执行update train_enrollment set status='CONFIRMED'，状态流转就失去了约束。

推荐使用 Java 枚举定义状态：

public enum EnrollmentStatus { ENROLLING, // 报名中 CONFIRMED, // 已确认 CANCELLED, // 已取消 FINISHED // 已完成 }

然后在 Service 层统一处理状态流转，不允许其他代码直接修改状态字段。一个示例方法如下：

public Enrollment confirmEnrollment(Long enrollmentId) { Enrollment e = enrollmentMapper.selectById(enrollmentId); if (e == null) { throw new BusinessException("报名记录不存在"); } if (e.getStatus() == EnrollmentStatus.CANCELLED) { throw new BusinessException("已取消的记录不能确认"); } if (e.getStatus() == EnrollmentStatus.CONFIRMED) { return e; } e.setStatus(EnrollmentStatus.CONFIRMED); enrollmentMapper.updateById(e); return e; }

这段代码做了三件事：先判断记录是否存在，再判断当前状态是否允许流转，最后做幂等返回。已经确认过的记录再确认一次会直接返回，而不会重复写库。

2.3 最终章要清理的几种脏数据

一套系统跑了一段时间后，数据库里可能出现以下脏数据：

• 报名记录对应的课程被删除，形成孤儿记录。
• 成绩记录对应的报名不存在。
• 课程名额已满，但课程状态还是报名中。
• 同一学生同一课程出现多条报名记录，说明唯一索引没有正确建立。

可以用如下 SQL 排查：

-- 查询没有对应课程报名的孤儿报名记录 SELECT te.id, te.course_id FROM train_enrollment te LEFT JOIN train_course tc ON te.course_id = tc.id WHERE tc.id IS NULL; -- 查询没有对应报名记录的成绩 SELECT ts.id FROM train_score ts LEFT JOIN train_enrollment te ON ts.enrollment_id = te.id WHERE te.id IS NULL; -- 查询已经满员但状态仍然是报名中的课程 SELECT tc.id, tc.course_name, tc.capacity FROM train_course tc WHERE tc.status = 'ENROLLING' AND (SELECT COUNT(*) FROM train_enrollment te WHERE te.course_id = tc.id AND te.status <> 'CANCELLED') >= tc.capacity;

这三条 SQL 应该作为最终章数据检查的固定脚本保留下来。修复的方式不是看到异常就手动删数据，而是先确认业务规则，再写一次性修复脚本，并记录下来。

3. 把最容易漏掉的工程保护补上

3.1 后端权限校验不能只靠前端按钮

前端隐藏按钮只影响界面展示。一个熟悉接口调用的人完全可以直接绕过页面，向后台发送请求。如果后端接口没有权限校验，就会出现“学生没有教师权限，但直接调用接口发布了成绩”的情况。

Spring Boot 项目里，最简单的做法是使用拦截器统一校验登录态和角色。一个示例实现如下：

public class RoleInterceptor implements HandlerInterceptor { @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { if (!(handler instanceof HandlerMethod)) { return true; } LoginUser user = (LoginUser) request.getAttribute("loginUser"); if (user == null) { throw new UnauthorizedException("请先登录"); } RequireRole requireRole = ((HandlerMethod) handler).getMethodAnnotation(RequireRole.class); if (requireRole != null && !user.getRoles().contains(requireRole.value())) { throw new ForbiddenException("无权限执行该操作"); } return true; } }

这段代码会拦截所有接口请求。先判断当前处理对象是不是普通方法，再判断登录用户是否存在，最后检查方法上的@RequireRole注解。最终章一定要逐个接口确认，是否所有写接口都配置了登录认证。注册拦截器时，记得把登录接口放在放行列表里，否则会出现“登录接口本身无法访问”的问题。

3.2 报名接口：用唯一索引兜住重复请求

学生报名时如果连续点击两次“报名”，或者因为网络重试验证请求被发送了两次，业务层可能插入两条报名记录。即使数据库有唯一索引，也需要在代码里捕获异常并返回业务提示，而不是让用户看到一条数据库异常。

典型实现如下：

@Transactional public void enroll(Long courseId, Long studentId) { try { TrainCourse course = courseMapper.selectById(courseId); if (course == null || !"ENROLLING".equals(course.getStatus())) { throw new BusinessException("该课程当前不可报名"); } Enrollment e = new Enrollment(); e.setCourseId(courseId); e.setStudentId(studentId); e.setStatus(EnrollmentStatus.ENROLLING); enrollmentMapper.insert(e); } catch (DuplicateKeyException ex) { throw new BusinessException("你已经报名过该课程"); } }

这里的顺序是：先做业务校验，再插入数据，遇到唯一索引冲突时返回友好提示。@Transactional保证报名记录和后续其他写入操作的一致性。

注意：唯一索引是最后防线，不是唯一的并发控制。如果还需要防止报名人数超过课程容量，常见思路是在事务里对课程记录加锁，或使用数据库条件更新更新名额。在最终章阶段，至少要先保证不会产生重复报名。

3.3 成绩发布：乐观锁防止覆盖

教师 A 和教师 B 同时打开同一份成绩记录，都看到 85 分。A 改成 90 分并保存，B 改成 70 分并保存，最后数据库里留存的是 70 分，A 的修改被静默覆盖。这时需要在train_score的version字段上做乐观锁。

int updated = scoreMapper.update( null, new LambdaUpdateWrapper<TrainScore>() .eq(TrainScore::getId, scoreId) .eq(TrainScore::getVersion, oldVersion) .set(TrainScore::getScore, newScore) .set(TrainScore::getVersion, oldVersion + 1) ); if (updated == 0) { throw new BusinessException("成绩已被其他人修改，请刷新后重试"); }

update的where条件中带上了version = oldVersion。只有当前版本号还等于操作者查询到的版本号时，更新才会成功。如果期间有人改过，updated等于 0，业务层会提示用户刷新后重试，而不是直接覆盖。

成绩发布是典型的并发写场景，最终章一定要检查是否补了乐观锁。没有版本号的成绩表，在多人同时操作时一定会有数据覆盖问题。

3.4 高频查询要不要上缓存

课程列表这类高频查询，可以加缓存减少数据库压力。但最终章不要为了“显得技术完整”就随意引入 Redis。需要先评估数据量、查询频率和变更频率。

如果只是几千条课程记录，访问量也不高，直接用本地缓存即可。一个常见的做法是使用 Caffeine：

spring: cache: type: caffeine

然后在查询方法上增加缓存注解：

@Cacheable(cacheNames = "courseList", key = "#status") public List<TrainCourse> listCourses(String status) { return courseMapper.selectList( new LambdaQueryWrapper<TrainCourse>() .eq(TrainCourse::getStatus, status)); }

加了缓存之后，必须同步考虑失效时机。比如课程状态从报名中变成已开始时，要执行@CacheEvict清理对应缓存，否则用户会一直看到旧状态。最终章最容易踩的坑就是“缓存加了，数据更新后用户看不到新内容”。

4. 用固定的验证脚本证明核心链路可用

4.1 把点击页面的动作变成脚本

手工点击页面做验收，容易漏步骤，也容易每次点出不同结果。最终章建议准备一组可以重复执行的接口脚本，按业务顺序验证。

下面是一个 bash 示例，假设后端已经启动在本地 8080 端口：

# 1 登录获取 token TOKEN=$(curl -s -X POST http://localhost:8080/api/auth/login \ -H 'Content-Type: application/json' \ -d '{"username":"student01","password":"123456"}' | jq -r '.data.token') # 2 查询可报名的课程 curl -s http://localhost:8080/api/courses?status=ENROLLING \ -H "Authorization: Bearer $TOKEN" # 3 报名课程 curl -s -X POST http://localhost:8080/api/enrollments \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{"courseId":1}' # 4 重复报名，观察是否被幂等拦截 curl -s -X POST http://localhost:8080/api/enrollments \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{"courseId":1}'

这个脚本可以保存到项目的scripts/acceptance.sh目录中。以后每次改了代码，都可以重新跑一遍，对比输出结果。脚本比手工点击更稳定，也更容易作为验收记录归档。

4.2 预期结果和异常输出要提前定义

最终章要给关键接口定义明确的预期结果，不能只验证“请求没有报 500”。下面是一张可以贴在验收记录里的表：

场景	请求	预期 HTTP 状态	预期业务码
登录成功	POST /api/auth/login	200	SUCCESS
未登录查询课程	GET /api/courses	401	UNAUTHORIZED
重复报名	POST /api/enrollments	409	DUPLICATE_ENROLL
对未开放课程报名	POST /api/enrollments	400	COURSE_NOT_ENROLLING
成绩并发冲突	PUT /api/scores/1	409	VERSION_CONFLICT

错误响应该包含业务码、提示信息和 traceId，方便日志定位：

{ "code": "DUPLICATE_ENROLL", "message": "你已经报名过该课程", "traceId": "a3f9e0c1-9d2b-4e6f-8f2c-1b3d6a9e5c01" }

如果接口在报错时只返回一个笼统的500，最终章就需要给统一异常处理补上这些信息。否则演示时，用户看到白屏或Internal Server Error，连问题都说不清楚。

4.3 日志要能按 traceId 串联

排查问题时，最怕日志里只有零散打印，缺少请求标识。建议在拦截器或过滤器里生成 traceId 放进日志框架的 MDC，在统一异常处理里记录完整异常信息。

一个最小日志配置：

logging: level: root: INFO com.highland.training: DEBUG

从现象到根因，推荐按下面顺序排查：

1. 请求内容是否正确：URL、请求头、JSON 字段。
2. 配置文件是否生效：环境变量、profile 是否选择正确。
3. 依赖版本是否匹配：JDK、Spring Boot、MySQL 驱动。
4. 权限是否缺失：登录态、角色、注解是否配置正确。
5. 环境是否正常：端口、数据库连接、Redis 连接。
6. 数据是否有问题：唯一约束、状态值、脏数据。
7. 日志是否记录关键路径：先找 traceId，再看 SQL，再看异常栈。

不要一开始就怀疑框架有问题。大多数最终章排错，最后定位到的都是常见配置或数据问题。

5. 学习环境与生产环境必须分开看待

5.1 学习环境用一条命令起依赖

开发验证阶段，可以用 Docker Compose 快速创建 MySQL 和 Redis 依赖。一个最小配置如下：

services: mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: rootpass MYSQL_DATABASE: highland_train ports: - "3306:3306" redis: image: redis:7 ports: - "6379:6379"

启动命令：

docker compose up -d mvn spring-boot:run

这是学习环境的快速方案。数据库密码不要直接作为生产配置使用，Docker 里的数据容器一旦删除，数据也会消失，所以只能用于开发调试和功能验证。

5.2 生产环境最少要补哪些配置

生产环境需要把配置从代码仓库里剥离出来，尤其是数据库口令。推荐通过环境变量注入，并暴露健康检查接口：

spring: datasource: url: jdbc:mysql://数据库地址:3306/highland_train username: platform_user password: ${DB_PASSWORD} redis: host: ${REDIS_HOST} port: ${REDIS_PORT} cache: type: redis management: endpoints: web: exposure: include: health,info

这样的配置意味着数据库口令不写死在仓库里，而是在部署时通过环境变量传入。health接口暴露后，监控系统可以定时检查服务状态。

注意：生产环境的数据库账户要遵循最小权限原则，应用账户只需要业务库的增删改查权限，不应当使用 root 账户。备份、回滚、监控这些能力，必须在最终章完成，而不是等上线出问题再补。

5.3 上线前备份和回滚至少准备这些

上线前至少准备三样东西：数据库备份、上一版本的部署产物、数据库变更脚本。这样一旦发布出问题，可以恢复数据并切回旧版本。

备份命令示例：

mysqldump -u platform_user -p highland_train > highland_train_backup_$(date +%Y%m%d_%H%M%S).sql

回滚顺序建议是：

1. 恢复数据库备份，或反向执行变更脚本。
2. 切换回上一版 jar 包或镜像。
3. 重启服务。
4. 检查健康检查接口和关键业务接口。

这里要注意，数据库变更脚本必须是可回滚的。如果某个 SQL 是删除字段，那么回滚脚本必须能把字段加回来。最终章如果不维护这类脚本，回滚就只能靠人工处理，风险很高。

6. 文档和演示才是最终章容易被看见的部分

6.1 最小文档集

项目文档不需要写得像产品手册，但至少要覆盖使用和排障所需的信息。建议在docs目录下维护以下文件：

docs/ README.md deploy.md api.md >