基于微信小程序的校园网综合服务系统设计与SpringBoot后端实现

1. 为什么我选择做校园网综合服务系统，而不是又做一个"选课助手"

每年的毕业设计季，我都能看到大量同质化的校园系统题目——基本都是"校园二手交易平台""课程表小程序""失物招领系统"这一类。不是说这些题目不好，而是它们普遍存在一个问题：只覆盖了校园生活的某一个切片，做完之后很难真正用起来，答辩时也缺乏纵深可讲。这次我做的"基于微信小程序的校园网综合服务系统"，本质上是一个把多个高频校园场景统一收口的微校园平台，核心目标不是炫技术，而是让"登录一次，办N件事"这件事在校园网环境下真正跑通。

先说说这个系统到底能做什么。学生端进入小程序后，可以完成校园资讯浏览、课表查询、成绩查询、校园卡充值流水查询、报修工单提交与进度跟踪、校内活动报名、失物招领信息发布、意见反馈等核心功能。管理员端则通过SpringBoot后端提供的管理接口，在小程序内嵌的管理页面或Web管理端完成资讯发布、工单派发、活动审核、用户管理、数据统计等操作。换句话说，这是一个典型的"学生—辅导员—后勤/管理员"三方角色联动平台，把原来分散在多个网站、多个公众号菜单里的服务集中到一个微信小程序入口。

这套东西适合谁来参考？我认为主要有三类人：第一类是正在做毕业设计、需要一套能完整跑通"小程序端+后端接口+数据库设计+部署上线"全链路的计算机或软件工程专业学生；第二类是想在校内创业或参与实验室项目、需要快速搭建一个校园服务原型的开发者；第三类是已经工作、但对SpringBoot+微信小程序这套组合还不够熟的Java工程师，可以通过这个项目把前后端联调、微信登录态维护、权限控制这些高频技能点补齐。

选型上，后端采用Java + SpringBoot是深思熟虑的结果。SpringBoot在校园项目里几乎是"标准答案"级别——自动配置极大降低了搭建成本，内嵌Tomcat让部署变得简单，丰富的Starter生态可以快速集成MyBatis-Plus、Redis、OSS等组件。更重要的是，Java技术栈在校园环境里的资料密度最高，遇到问题能搜到的解决方案最多，对需要独立完成项目的学生来说，这比追求冷门框架要稳妥得多。前端选择微信小程序而不是独立App，理由也很直接：微信是学生群体不可能卸载的超级入口，小程序无需安装、扫码即用，而且微信生态提供了完整的登录、支付、消息订阅能力，非常适合校园场景的轻量服务。

我自己在动手前踩过的一个认知误区是：以为"校园网综合服务系统"就等于"把几个功能塞到一个后台里"。真正深入需求后才发现，这类系统的核心难点根本不在于单个功能怎么写，而在于三个交叉问题——多角色权限如何统一管理、高频数据（如课表成绩）如何与校园现有系统对接或模拟、以及服务流程（如报修工单）如何做到状态可追踪。把这几个问题想清楚，项目的技术含金量和答辩深度都会完全不同。这篇文章我会按照从需求分析、数据库设计、后端接口开发、小程序联调，到性能优化和部署上线的完整链路来复盘，所有关键环节都会给出理由和踩坑记录，而不是单纯贴代码。

2. 需求边界与角色权限设计：先想清楚"谁在用、用什么、限制什么"

2.1 三类核心角色的用例拆解

系统设计的第一步不是建表，而是把参与者和他们的操作权限梳理清楚。校园网综合服务系统的用户天然分成三层：学生、教师/辅导员、系统管理员。层级不复杂，但每一层的操作边界必须严格划分，否则后患无穷。

学生端的功能集合可以概括为"查看与提交"。查看课表、成绩、资讯、活动、失物招领；提交报修单、活动报名、意见反馈。这里要注意，学生不应该拥有任何删除或审核权限，比如误报了失物招领信息，只能通过联系管理员来下架，而不是自己直接删除——这是为了防止数据滥用。

教师/辅导员端的职责主要是"审批与核实"。活动报名需要辅导员审核（防止学生随意旷课参加活动）、学生请假或特殊申请需要辅导员通过、报修单的初步核实也可以由辅导员确认后再转给后勤。这个角色的权限落在"查看名下学生数据 + 处理待审批事项"的范围内。

管理员是整个系统的超级入口，管理资讯发布、报修工单分派、用户冻结/解冻、数据看板统计、系统参数配置。从业务体量来看，管理员角色通常数量很少（几人），但是功能点最多。

2.2 为什么选择RBAC模型来实现权限控制

说到权限控制，很多同学的第一个念头是"在用户表加一个role字段，然后if判断"。这在角色只有两种、接口只有十几个的小项目里确实够用，但是一旦功能模块变多，这种硬编码方式会迅速失控——每个接口都要写一堆if/else，后续加角色、加权限点都要全局搜索修改。

我在这个项目里采用的是经典的RBAC（基于角色的访问控制）模型，引入五张核心表：用户表、角色表、菜单权限表、用户角色关联表、角色菜单关联表。直观理解就是"用户—角色—权限"三层映射：不直接把权限绑在用户身上，而是先把权限绑到角色上，再把角色分配给人。这种设计的好处是：新增一个"楼栋管理员"角色时，只需要在角色表里插入一行，然后配置该角色能访问的菜单和接口，不需要改动用户表结构，也不需要改业务代码。

不过这里我必须说一个实际取舍：完整RBAC对这个项目来说略有冗余，所以我在落地时做了一层简化——权限粒度精确到"接口+菜单"级别，但不对数据行级做细粒度控制。比如辅导员只能看到本学院学生的报修单，这一点不是靠RBAC实现的，而是在SQL查询时用college_id条件过滤。换句话说，RBAC负责"你能访问哪些功能"，而数据范围靠业务代码控制。这个组合在校园系统场景里非常实用，既保证了权限管理的统一性和扩展性，又避免了过度设计。

2.3 微信小程序登录态与后端会话的衔接

校园网综合服务系统因为是微信小程序端，绕不开微信登录体系。这里要讲清楚登录的完整链路，很多第一次做小程序的同学都在这个地方懵过。

微信小程序的登录流程是这样的：小程序端调用wx.login()拿到一个临时凭证code，把这个code传给后端；后端拿到code后，调用微信的code2Session接口，用appid + appsecret + code换回openid和session_key。其中openid是用户在当前小程序下的唯一标识，session_key用于解密用户手机号等敏感信息。

这个流程里最关键的一个设计决策是：后端不要直接把openid返回给小程序端，更不能拿openid当会话凭证。原因很简单——小程序端代码是半公开的，网络请求可以被抓包，如果openid直接暴露在响应里，别人拿到你的openid就能伪造你的身份。正确做法是后端在首次登录后，生成一个自定义的登录凭证（我使用的是JWT令牌），并建立token -> openid的映射关系，后续所有请求都通过请求头里的token来识别用户身份。

我在实现时用一个工具方法统一管理当前登录用户：

java复制public class UserContext {
    private static final ThreadLocal<Integer> CURRENT_USER = new ThreadLocal<>();

    public static void set(Long userId) {
        CURRENT_USER.set(userId);
    }

    public static Long get() {
        return CURRENT_USER.get();
    }

    public static void clear() {
        CURRENT_USER.remove();
    }
}

配合一个拦截器，在进入Controller之前解析JWT并把用户ID放入ThreadLocal：

java复制public class LoginInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        String token = request.getHeader("Authorization");
        if (StringUtils.isBlank(token)) {
            throw new BusinessException(401, "未登录或登录已过期");
        }
        // 解析JWT，拿到userId，存入ThreadLocal
        Long userId = JwtUtil.parseToken(token);
        UserContext.set(userId);
        return true;
    }
}

这里有一个非常容易踩的坑：ThreadLocal在当前线程处理完请求后必须清理，否则在Tomcat线程池复用的场景下，下一次请求可能会读到上一个用户的ID。所以我实现了afterCompletion方法调用UserContext.clear()。这个细节在自测阶段可能永远不暴露，但一旦并发量上来就是严重的安全漏洞。

2.4 服务模块划分：微服务还是单体？

又一个很多同学纠结的问题：校园网综合服务系统听起来功能很多，要不要拆微服务？我的结论非常明确——不拆。这个项目从功能数量和团队规模来看，单体应用是最合理的选择。微服务带来的服务发现、配置中心、分布式事务、链路追踪等复杂性，对这个体量来说完全是负资产。

但我做了一件比"拆不拆微服务"更重要的事情：在单体内部做了清晰的模块划分，采用典型的分层架构——Controller层只负责参数接收和响应封装，Service层承载业务逻辑，Mapper层通过MyBatis-Plus操作数据库。这样即使将来某个模块（比如报修工单）单独拆出去，代码迁移的成本也能控制在可接受范围。模块划分上按照业务域拆包：

text复制com.campus.platform
├── controller          # 接口层
│   ├── AuthController
│   ├── InfoController
│   ├── CourseController
│   ├── RepairController
│   ├── ActivityController
│   └── AdminController
├── service             # 业务层
├── mapper              # 数据访问层
├── entity              # 实体类
├── common              # 通用类：返回结果、异常、常量
├── config              # 配置类：拦截器、跨域、JWT等
└── utils               # 工具类

这样设计的收益是：职责边界清晰，多人协作或后续维护时不需要在整个项目里大海捞针式找代码；同时测试时可以针对Service层写单元测试，不需要启动整个Web容器，测试效率提升明显。

3. 数据库与核心表结构设计：校园数据模型的取舍与反范式设计

3.1 核心数据表全景

数据库是这类系统最容易"建完就后悔"的部分。我见过太多人在刚拿到题目时就把二十多张表一股脑建出来，结果做到一半发现冗余字段、找不到关联键、类型定义不合理。正确的做法是先画业务流程图，再根据流程抽象出实体关系。

这个系统最终的核心表我控制在18张以内，主要分四组：

• 用户权限组：user（用户基础信息）、role（角色）、user_role（用户角色关联）、menu（菜单权限）、role_menu（角色菜单关联）
• 信息内容组：banner（轮播图）、notice（校园资讯公告）、activity（校园活动）、activity_signup（活动报名记录）、lost_found（失物招领）
• 教学服务组：course（课程）、course_student（学生选课关联）、score（成绩）
• 服务流程组：repair_order（报修单）、repair_log（报修流转日志）、feedback（意见反馈）

下面我会重点讲其中最有代表性的几张表，因为它们的取舍直接影响了系统可用性。

3.2 用户表：为什么不用微信openid做主键

用户表是整个系统的地基，这里我做过一个重要的设计决策。很多教程为了方便直接把openid作为用户表主键，但这会让业务系统与微信体系过度耦合。如果将来要接入支付宝小程序或自建App呢？openid就是完全无用的字段。更稳妥的设计是独立的id自增主键，openid作为唯一索引存在，同时预留union_id字段用于跨平台用户统一识别。

sql复制CREATE TABLE `user` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `openid` varchar(64) NOT NULL COMMENT '微信openid',
  `union_id` varchar(64) DEFAULT NULL COMMENT '开放平台unionid',
  `student_no` varchar(20) DEFAULT NULL COMMENT '学号',
  `real_name` varchar(32) DEFAULT NULL COMMENT '真实姓名',
  `college_id` bigint(20) DEFAULT NULL COMMENT '学院ID',
  `class_name` varchar(64) DEFAULT NULL COMMENT '班级',
  `phone` varchar(20) DEFAULT NULL COMMENT '手机号',
  `avatar` varchar(255) DEFAULT NULL COMMENT '头像URL',
  `role_code` varchar(32) NOT NULL DEFAULT 'STUDENT' COMMENT '角色编码',
  `status` tinyint(1) NOT NULL DEFAULT 1 COMMENT '状态：1正常 0冻结',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_openid` (`openid`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';

我特意把角色编码直接冗余在用户表里（role_code），而不是完全靠关联表去查。为什么？因为业务场景里90%的请求都需要知道"当前请求者是什么角色"，如果每次都去连查user_role再joinrole，性能不划算，代码也啰嗦。这是典型的"适度反范式"——在RBAC的规范设计之上，为了高频查询做了冗余，同时通过user_role表保证角色分配的灵活性。管理员想调整某个用户的角色，依然走关联表逻辑。

另一个细节是手机号字段，很多同学直接设计成varchar(11)，这没问题，但要注意微信小程序的手机号授权流程返回的是加密数据，需要后端用session_key解密后才能拿到明文手机号。我一开始忽略了这一点，导致解密工具类写了一半才发现需要处理AES-128-CBC解密。这块建议同学们注意：微信官方推荐动态手机号验证，不要在客户端明文传手机号。

3.3 报修工单表：状态机驱动是业务核心

报修单是这个系统里业务流程最复杂的部分，它的表结构设计直接决定了后续的工单流转逻辑能不能写清楚。我的设计思路是"主表+日志表"组合：主表保存工单当前状态和核心信息，日志表记录每一次状态变更的痕迹。

sql复制CREATE TABLE `repair_order` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `order_no` varchar(32) NOT NULL COMMENT '工单编号',
  `user_id` bigint(20) NOT NULL COMMENT '报修人ID',
  `category` varchar(32) NOT NULL COMMENT '报修类别：水/电/网络/家具/其他',
  `description` varchar(500) NOT NULL COMMENT '问题描述',
  `images` varchar(1000) DEFAULT NULL COMMENT '图片URL，逗号分隔',
  `address` varchar(200) NOT NULL COMMENT '报修地点',
  `status` tinyint(1) NOT NULL DEFAULT 0 COMMENT '状态：0待受理 1处理中 2已完成 3已关闭',
  `assignee_id` bigint(20) DEFAULT NULL COMMENT '处理人ID',
  `handle_result` varchar(500) DEFAULT NULL COMMENT '处理结果',
  `score` tinyint(1) DEFAULT NULL COMMENT '评分1-5',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_user_id` (`user_id`),
  KEY `idx_status` (`status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='报修单';

状态字段用tinyint而不是字符串，是因为数字在数据库里比较和索引的效率更高，而且不容易因为大小写、空格等问题产生脏数据。状态枚举在Java侧用枚举类严格约束：

java复制@Getter
@AllArgsConstructor
public enum RepairStatus {
    PENDING(0, "待受理"),
    PROCESSING(1, "处理中"),
    FINISHED(2, "已完成"),
    CLOSED(3, "已关闭");

    private final int code;
    private final String desc;

    public static RepairStatus of(int code) {
        for (RepairStatus status : values()) {
            if (status.code == code) {
                return status;
            }
        }
        throw new IllegalArgumentException("未知状态: " + code);
    }
}

日志表repair_log记录每一次状态变更：谁在什么时间把工单从什么状态改成了什么状态、备注信息是什么。这样设计有几个直接好处：第一，学生端"进度追踪"功能可以直接查日志列表，从待受理到处理中到完成的每一个时间点都展示给用户；第二，管理员在处理纠纷时有据可查；第三，为后续做"超时未处理工单自动提醒"提供了时间计算的数据来源。

3.4 课表与成绩：模拟数据如何设计得"像真的"

这里要坦白一个校园系统普遍面对的尴尬：真正对接教务系统、一卡通系统的数据接口通常需要学校信息化部门的授权，毕设场景下很难拿到真实数据。所以绝大多数校园类毕设的做法是模拟数据，但模拟数据也要模拟得专业，不能随随便便造几条垃圾数据。

我的做法是：课程表采用"周次+星期几+节次"的三维模型，设计一张course表和一张course_student关联表。课程表里存课程基本信息，关联表存哪些学生选了这门课。查询某学生的课表时，以student_no为条件查出关联的课程列表，再按周次和节次排序。这样设计的好处在于：一是符合真实教务系统的数据模型逻辑，答辩时能讲清楚为什么这样建表；二是可以很方便地扩展"调课"功能——在课程表里加一个is_adjust字段和调整后的时间字段即可，不需要动关联表架构。

成绩表更简单，但有一个细节值得注意：成绩设计成score_value和score_point两个字段。score_value是百分制分数，score_point是课程绩点，绩点通过分数区间映射计算（90-100对应4.0，85-89对应3.7，以此类推）。很多初次设计的同学只存一个分数，后面想做GPA计算时就傻眼了。虽然毕设阶段可能只需要展示分数不一定要算绩点，但这个字段预留能让系统显得完整很多。

3.5 索引设计：别等慢SQL了才后悔

数据库设计里最容易被忽视的就是索引。这个系统的数据量不会特别大，但有些查询的形态如果不加索引，随着数据积累会越来越慢。我的建索引原则很简单：

• 所有外键字段建普通索引，比如user_id、college_id、activity_id
• 所有状态字段建普通索引，比如status，因为学生端"我的报修单列表"基本都是以用户ID+状态为条件的查询
• 所有需要排序的字段利用联合索引覆盖，比如"活动列表按创建时间倒序"，给create_time建索引就够了
• 联表查询时，驱动表的关联字段必须有索引

实际的坑出现在我最初给repair_order同时建了idx_user_id和idx_status两个单列索引，但查询"某个用户所有待受理的工单列表"WHERE user_id = ? AND status = ?时，MySQL只能选其中一个索引。后来我把这两个字段合并升级为联合索引uk_user_status(user_id, status)，查询效率提升了一个量级。这个优化在数据量只有几千条时感受不明显，但答辩时如果评委问"如何优化慢查询"，这就是一个很好的实战案例。

4. 后端核心接口实现：SpringBoot里的业务难点逐个拆解

4.1 统一返回结构与全局异常处理，提升开发效率

后端接口设计的第一步是定好统一返回格式。我使用的是标准的Result<T>结构：

java复制@Data
public class Result<T> {
    private Integer code;
    private String message;
    private T data;

    public static <T> Result<T> ok(T data) {
        Result<T> result = new Result<>();
        result.setCode(200);
        result.setMessage("success");
        result.setData(data);
        return result;
    }

    public static <T> Result<T> error(Integer code, String message) {
        Result<T> result = new Result<>();
        result.setCode(code);
        result.setMessage(message);
        return result;
    }
}

同时配合全局异常处理器，把业务异常、参数校验异常、系统异常统一拦截，返回给小程序端一个结构一致的错误信息。这样做的好处非常明显：前端在做接口封装时，只需要判断code是不是200，不需要对每种异常做特殊处理；后端在业务代码里想中断流程时，直接抛异常即可：

java复制throw new BusinessException(1001, "该活动已报名，不能重复报名");

这里我要强调一个经验：异常码规划不能随心所欲。我给这个系统定的规则是——1xxx表示用户相关错误，2xxx表示业务规则错误，3xxx表示数据权限错误，401表示登录失效。这样前端接到错误码后，可以根据码段快速定位问题类型，甚至实现全局弹提示。比如401可以统一跳回登录页，2xxx统一弹出message内容。这个规则越早定越好，否则开发到一半再统一错误码，改动量会非常大。

4.2 微信登录接口：从code换token的完整实现

微信登录接口是整个系统前后端联调的第一关，代码量不大但要点密集。核心逻辑如下：

java复制@PostMapping("/login")
public Result<LoginVO> login(@RequestBody LoginDTO dto) {
    // 1. 调用微信code2Session接口换取openid
    JSONObject sessionInfo = wxService.code2Session(dto.getCode());
    String openid = sessionInfo.getString("openid");
    
    // 2. 根据openid查用户，不存在则自动注册
    User user = userMapper.selectByOpenid(openid);
    if (user == null) {
        user = registerNewUser(openid);
    }
    if (user.getStatus() == 0) {
        throw new BusinessException(401, "账号已被冻结，请联系管理员");
    }
    
    // 3. 生成JWT令牌，返回给前端
    String token = JwtUtil.generateToken(user.getId(), user.getRoleCode());
    LoginVO vo = new LoginVO();
    vo.setToken(token);
    vo.setUserInfo(convert(user));
    return Result.ok(vo);
}

这个接口里有几个关键点值得展开讲。

wx.code2Session的后端实现用的是restTemplate或okhttp调用微信接口。要注意的是，微信服务器的响应是JSON格式，但失败时返回的JSON结构和成功时不一样，需要做好判断。成功的响应中包含openid、session_key、unionid；失败时返回errcode和errmsg。如果不做错误处理，遇到网络波动或code过期时，程序会直接NPE，给小程序端返回一个500，排查起来很费劲。

第二个关键点：code是一次性的，而且有效期只有几分钟。如果前端在请求登录接口时发生了超时重试，第二次用同一个code再去请求，微信会返回40029 code无效。所以我在前端设计了"登录中"的防重复点击状态，同时在代码里对code为空的请求直接提示前端重新调用wx.login。

第三个关键点，也是我自己踩过的坑：session_key不能只用来解密手机号，它还和用户会话状态密切相关，但后端不应该把session_key返回给前端。原因很简单，session_key一旦泄露，配合抓包工具，任何人都能解密该用户在小程序端的加密数据。正确的做法是登录接口之后立即把session_key存储在后端缓存中，按openid作为key，需要解密时从缓存取。我在项目里用Redis存储session_key并设置了两小时过期，这样用户每次打开小程序时静默登录刷新一次，保证解密能力的同时降低安全风险。

4.3 校园资讯与课表查询：缓存策略和性能优化

资讯公告和课表查询是典型的高频读、低频率写场景。这种场景下最忌讳的写法是每次请求都直接查数据库。我的做法是引入Redis缓存，用简单的"缓存穿透+缓存击穿"防护策略。

先定义缓存key的规范。

text复制campus:info:list:{page}:{size}
campus:course:student:{studentNo}
campus:score:student:{studentNo}:{semester}

查询资讯列表时，先查缓存，缓存没有再去查数据库，并设置5分钟过期时间：

java复制public List<Notice> getNoticeList(int page, int size) {
    String key = "campus:notice:list:" + page + ":" + size;
    String cached = redisTemplate.opsForValue().get(key);
    if (StringUtils.isNotBlank(cached)) {
        return JSON.parseArray(cached, Notice.class);
    }
    List<Notice> list = noticeMapper.selectList(
        new LambdaQueryWrapper<Notice>()
            .eq(Notice::getStatus, 1)
            .orderByDesc(Notice::getCreateTime)
            .last("limit " + (page - 1) * size + "," + size)
    );
    redisTemplate.opsForValue().set(key, JSON.toJSONString(list), 5, TimeUnit.MINUTES);
    return list;
}

这里有个细节：为什么要存JSON字符串而不是直接用RedisTemplate的序列化方式存对象？因为我用的RedisTemplate如果默认使用JDK序列化，会往Redis里写入一堆Java序列化的乱码，而且其他客户端（比如命令行或前端排查工具）读出来完全不可读。改成手动JSON序列化后，数据在Redis里的可读性明显提升，排查问题方便很多。

课表查询的缓存策略则稍有不同。课表一旦确定，一学期内很少变化，完全没有必要每次缓存5分钟，我直接设置缓存一天。但课程调整又需要实时生效，所以我在管理后台提供"清除课程缓存"的按钮，管理员调整课程后可一键刷新缓存。这比设置合理的TTL更实用，也更贴近实际业务需求。

缓存穿透和击穿在这个项目里其实不太容易出现——数据量小、并发低。但既然系统定位是"综合服务平台"，带上缓存设计是加分项。我加了两个最基础的防护：查询数据库结果为null时，也往缓存里写一个空值（设置较短过期时间），防止恶意高频请求直接穿透到数据库；热点key（比如首页资讯）用setnx做简单的互斥锁，避免缓存过期瞬间大量请求同时打到数据库。代码量不大，但足以在答辩时体现你对高并发场景的基础认知。

4.4 报修工单的状态流转与消息触达

工单系统的核心是状态机。我见过不少同学把状态流转写成一堆if/else嵌套在Service里，初看能跑，但加一个"取消申请"或者"重新指派"的需求时，代码会变成意大利面。这里我推荐一个简单实用的状态机模式：用Map预先定义好合法流转路径。

java复制private static final Map<Integer, Set<Integer>> TRANSITIONS = new HashMap<>();

static {
    TRANSITIONS.put(RepairStatus.PENDING.getCode(), Set.of(
        RepairStatus.PROCESSING.getCode(),
        RepairStatus.CLOSED.getCode()
    ));
    TRANSITIONS.put(RepairStatus.PROCESSING.getCode(), Set.of(
        RepairStatus.FINISHED.getCode(),
        RepairStatus.CLOSED.getCode()
    ));
    TRANSITIONS.put(RepairStatus.FINISHED.getCode(), Set.of(RepairStatus.CLOSED.getCode()));
    TRANSITIONS.put(RepairStatus.CLOSED.getCode(), Set.of());
}

public void changeStatus(Long orderId, int fromStatus, int toStatus, Long operatorId, String remark) {
    Set<Integer> allowed = TRANSITIONS.get(fromStatus);
    if (allowed == null || !allowed.contains(toStatus)) {
        throw new BusinessException(2001, "非法状态流转: " + fromStatus + " -> " + toStatus);
    }
    repairOrderMapper.updateStatus(orderId, toStatus);
    repairLogMapper.insert(...);
}

状态机方案有几个明显优势：第一，非法流转在入口就被拦截，不会污染数据；第二，新增合法流转路径只需要改Map配置，不需要改动业务代码；第三，逻辑一目了然，评审在看代码时能快速理解你的设计思路。

工单流转之后还有一件事：消息触达。学生提交报修单、管理员受理工单、处理完成这三个关键节点，都应该通知用户。微信小程序官方提供的订阅消息能力正好用在这里。需要注意的是，订阅消息是"一次性订阅"——用户必须主动点击"允许"按钮才能订阅一次，而且一次订阅只能接受一条消息。所以我在学生提交报修单时，设计了连续弹窗订阅两次的交互：一次订阅"受理通知"，一次订阅"完成通知"。小程序端的订阅代码长这样：

javascript复制async subscribeRepairMessage() {
    const tmplIds = [
        '受理通知模板ID',
        '完成通知模板ID'
    ];
    await wx.requestSubscribeMessage({ tmplIds });
}

后端在工单状态变化时，通过调用微信的订阅消息接口推送模板消息。这里最容易出问题的是模板ID配置：模板需要在微信公众平台申请，而且一条模板对应一个固定的场景。我们一开始图省事把"受理通知"和"完成通知"合在同一个模板里，结果发现同一个模板不能连续推送两次给同一个用户，必须要两个不同的模板ID。这个坑耗费了我们不少时间排查，写在这里希望其他人不要再踩。

4.5 文件上传：图片压缩与路径管理

报修单和失物招领都需要图片上传，这个功能虽然不复杂，但设计不好非常影响体验。校园网环境下，学生手机上传图片，单张照片动辄5MB，如果不做压缩直接传到服务器，既占带宽又拖慢请求。我在小程序端先用wx.compressImage把图片压缩到合适大小再上传：

javascript复制wx.compressImage({
    src: tempFilePath,
    quality: 80,
    success: (res) => {
        wx.uploadFile({
            url: BASE_URL + '/common/upload',
            filePath: res.tempFilePath,
            name: 'file',
            success: (res) => {
                const data = JSON.parse(res.data);
                // data.data 就是文件访问URL
            }
        });
    }
});

后端接收文件后，我采取的是"本地存储+Nginx映射"的方式，而不是引入OSS。理由很简单：毕设阶段的服务器通常没有云厂商的OSS资源包，而且为这个项目引入OSS会增加配置复杂度。本地存储只需要在配置文件中指定上传路径，然后通过Nginx把/uploads/**映射到磁盘目录，就能实现图片的公网访问。

yaml复制file:
  upload-path: /data/campus/uploads/
  access-prefix: /uploads/

这里有一个需要注意的路径安全问题：文件上传接口一定要做好文件类型校验。只允许jpg、jpeg、png、gif等白名单后缀，同时校验文件内容的前几个字节是否为对应图片格式的魔数，避免有人把jsp或php文件伪装成图片传上去，造成服务器被getshell的安全风险。虽然校园项目一般没人攻击，但这个安全意识最好从第一天就有。

4.6 管理员端数据统计：SQL聚合与可视化设计

管理端的核心价值在数据看板。学生人数增长、报修工单分类统计、活动参与率等指标，如果靠人工查表分析，效率低且容易遗漏。我在后端写了几个聚合查询接口，比如：

java复制public List<Map<String, Object>> countRepairByCategory() {
    return repairOrderMapper.selectMaps(
        new QueryWrapper<RepairOrder>()
            .select("category, COUNT(*) as total")
            .groupBy("category")
    );
}

这个接口返回的数据，小程序管理端拿到后用ECharts或者小程序原生的canvas图表渲染出来。这里我遇到的一个实际问题是：小程序端的canvas图表组件对数据格式要求比较严格，后端直接返回的Map转成JSON后，小程序的图表库（比如echarts-for-weixin）需要的是[{name: '水电', value: 42}, ...]格式，与后端原生返回的结构有差异。我的做法是在后端直接组装成前端需要的结构，而不是让前端再做一层转换。这个原则就是：后端接口按前端渲染需求输出，而不是让前端硬凑。

管理端做统计时还需要注意时间维度。一开始我只统计历史总量，发现意义不大。后来加上"近7天报修趋势"“本月活动报名人数”等时间范围查询，在Controller里接收startDate和endDate参数，SQL里用BETWEEN过滤。这样管理端才能看到真实的运营走势。

5. 小程序端的搭建与联调细节：从注册到上线全流程

5.1 项目初始化和基础架构选型

小程序端我采用原生框架开发，没有使用uni-app或Taro。原因有两个：第一，项目是毕设或中小型项目，原生框架完全足够，而且微信开发者工具的调试体验最好，资料文档也最全；第二，用uni-app的话，遇到疑难问题很多人会怀疑是框架问题，排查成本远高于原生。不要为了"跨端"而跨端，这个决策逻辑同样适用于后端不要为了"微服务"而微服务。

开发的工程结构我做了分层：

text复制miniprogram/
├── api/               # 接口请求封装
│   ├── request.js     # 请求工具
│   ├── auth.js
│   ├── info.js
│   ├── course.js
│   ├── repair.js
│   └── activity.js
├── pages/             # 页面
│   ├── index/         # 首页
│   ├── info/          # 资讯详情
│   ├── course/        # 课表
│   ├── score/         # 成绩
│   ├── repair/        # 报修
│   ├── activity/      # 活动
│   ├── profile/       # 我的
│   └── admin/         # 管理端页面
├── components/        # 公共组件
├── utils/             # 工具函数
└── app.js

在request.js里统一封装请求逻辑，包括附加token、统一错误处理、401自动跳登录。这是小程序开发中非常基础但重要的封装，否则每个页面都要写一遍wx.request的错误处理，会烦死。

5.2 自定义导航栏：适配安全区是必修课

校园网综合服务系统首页需要一个自定义导航栏，放搜索框和轮播定位。默认导航栏的颜色、字体都不好调，而且返回按钮等交互不符合定制需求，所以必须自定义导航栏。但自定义导航栏的第一个坑就是适配不同机型的顶栏高度。

微信小程序的顶部导航栏高度并不是固定的。我封装了一个工具方法来动态计算：

javascript复制function getNavBarInfo() {
    const windowInfo = wx.getWindowInfo();
    const menuButtonInfo = wx.getMenuButtonBoundingClientRect();
    return {
        navBarHeight: (menuButtonInfo.top - windowInfo.statusBarHeight) * 2 + menuButtonInfo.height,
        menuButtonWidth: menuButtonInfo.width,
        statusBarHeight: windowInfo.statusBarHeight
    };
}

然后把这个高度注入到全局数据，页面onLoad时使用。如果不做这个适配，同一个页面在iPhone 13和安卓全面屏上显示的高度会差出一截，布局被挤压得非常难看。

顺便说一句，网上很多教程还在用wx.getSystemInfoSync获取状态栏高度，但这个接口在较新版本的基础库上已经不建议使用，推荐改用wx.getWindowInfo。这种API升级在微信小程序生态里很常见，写代码时一定要去查当前基础库版本的官方文档，不要迷信旧博客的代码。

5.3 登录态守门员：前端如何配合token保持会话

小程序端和后端的会话配合，核心在于三个动作：启动时静默登录、请求时附加token、失效时自动重新登录。

启动时，我在app.js的onLaunch里读取本地存储中的token。如果有token，先不急着跳转，而是让用户直接进入页面，同时异步向后端请求/auth/check接口验证token有效性。如果有效，刷新用户信息；如果失效，就删除本地token并重新走wx.login静默登录。这个"先信后验"的策略，可以避免启动时白屏等待，体验更好。

请求时，在request.js的Header里统一附加token：

javascript复制const header = {
    'Content-Type': 'application/json'
};
const token = wx.getStorageSync('token');
if (token) {
    header['Authorization'] = token;
}
wx.request({
    url: BASE_URL + url,
    method: method,
    data: data,
    header: header,
    timeout: 10000,
    success: (res) => {
        if (res.data.code === 401) {
            // token失效，清除并重新登录
            wx.removeStorageSync('token');
            handleLogin();
            return;
        }
        resolve(res.data);
    }
});

这里有个容易被忽略的问题：小程序的wx.request默认超时时间是60秒，如果后端接口响应慢，用户会长时间等待。统一设置10秒超时并配合loading提示，能显著提升体验。另外，wx.request的并发数量限制是10个，如果页面请求过多，会出现请求排队的情况，所以我在部分高频页面做了请求合并，比如首页的资讯、轮播图、待办数量，合并到一个聚合接口里一次请求返回，既减少网络往返又规避并发限制。

5.4 前后端联调最常见的三处不一致

联调阶段是项目中最容易吵架的阶段，绝大多数问题不是代码bug，而是两边对同一件事的理解不一致。我总结了这个项目里遇到的三个最典型的不一致点。

第一个是时间格式。Java后端返回的LocalDateTime默认序列化成"2025-06-01T10:30:00"这种带T的格式，小程序端直接展示会很难看。解决办法有两种：后端字段加@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")注解，或者在全局配置里自定义Jackson的序列化规则。我推荐后一种，因为一处配置全局生效，不会漏掉字段：

java复制@Bean
public Jackson2ObjectMapperBuilderCustomizer jsonCustomizer() {
    return builder -> {
        builder.simpleDateFormat("yyyy-MM-dd HH:mm:ss");
        builder.serializers(new LocalDateTimeSerializer(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")));
        builder.deserializers(new LocalDateTimeDeserializer(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")));
    };
}

第二个是数据状态的数字与字符串混淆。我在后端定义的状态码是Integer类型的0和1，但小程序端在switch判断时不小心写成了字符串'0'和'1'，导致条件永远不成立。这类问题的排查非常耗时，因为接口返回的数据看半天也不知道为什么判断不对。后来我养成了一个习惯：前端所有状态判断必须显式转换类型后再比较，例如Number(res.data.code)，避免无意中的类型陷阱。

第三个是分页参数从1开始还是从0开始。我在后端接口里统一从1开始，因为MySQL的limit子句本身是从0偏移的，需要在后端做(page - 1) * size的转换。前后端约定好"页码从1开始"后，联调就顺畅多了。很多新手前后端各写各的，前端传0后端处理不当会查丢第一页数据，排查它浪费时间的最终原因就是没有提前定好接口文档规范。

5.5 体验优化：骨架屏、下拉刷新与加载占比

一个能给答辩加分的点，是前端体验细节。我做了三件事。

一是骨架屏。首页在数据未返回时，用一排灰色的占位块模拟页面结构，等数据到达后再替换成真实内容。小程序端实现骨架屏非常简单，可以用wx.showLoading简单替代，但骨架屏的视觉体验明显更高。

二是下拉刷新。课表页和资讯列表页都支持下拉刷新，配合enablePullDownRefresh配置，并在回调里清掉对应的Redis缓存（或者调用后端刷新接口），让用户看到数据确实发生了变化。这里要注意，下拉刷新后必须调用wx.stopPullDownRefresh()关闭刷新动画，否则动画会一直转。

三是图片懒加载。资讯列表里的缩略图、活动海报等都设置loading="lazy"属性。这个属性在小程序里是原生支持的，加上之后页面滚动时的加载卡顿感明显改善。小项目不需要引入复杂的懒加载库，原生属性就够了。

6. 性能、安全与稳定性：让系统从"能跑"变成"能扛"

6.1 数据库层面的防坑：N+1查询和慢SQL治理

虽然校园系统的并发量不大，但代码质量问题迟早会在某些场景下爆发。N+1查询是我在写活动列表时无意中引入的经典问题：查询活动列表时，先查出所有活动，然后循环每条活动记录去统计报名人数。当一页有20个活动时，就会产生1次主查询+20次统计查询。数据量小的时候完全没感觉，但活动超过200条时，接口响应时间直线上升。

修复方法是使用一条SQL联表统计：

java复制public List<ActivityVO> getActivityWithCount(int page, int size) {
    return activityMapper.selectActivityWithSignupCount(page, size);
}

对应的Mapper XML核心是：

xml复制<select id="selectActivityWithSignupCount" resultType="com.campus.platform.vo.ActivityVO">
    SELECT a.*, COUNT(s.id) AS signup_count
    FROM activity a
    LEFT JOIN activity_signup s ON a.id = s.activity_id
    WHERE a.status = 1
    GROUP BY a.id
    ORDER BY a.create_time DESC
    LIMIT #{offset}, #{size}
</select>

把N+1合并成一次SQL，性能提升是数量级的。这类问题的通用信号是：接口响应时间越长，随着数据量增长越明显，用日志或者开发工具看一眼SQL执行数量就能定位。

慢SQL治理方面，我养成了定期打开MySQL的慢查询日志的习惯。在my.cnf里配置：

ini复制slow_query_log = 1
slow_query_log_file = /var/log/mysql/mysql-slow.log
long_query_time = 1

然后把超过1秒的SQL全部捞出来逐条分析。开发阶段用EXPLAIN查看执行计划，重点看type是否走到了index或range，以及rows扫描的行数是否合理。这个小习惯让我在正式部署前就挽回了好几条全表扫描的SQL。

6.2 后端安全加固：越权访问是校园系统的重灾区

校园系统最常被攻击的方向不是SQL注入——因为用MyBatis-Plus参数绑定的方式基本天然免疫——而是越权访问。简单来说，就是普通用户通过篡改请求参数，拿到了其他用户的数据，或者做了不该做的操作。

最典型的越权场景在报修单查询。如果查询接口直接接收repairOrderId参数，然后无脑返回对应的工单数据，那任何登录用户只要遍历ID，就能看到其他人的报修信息了。必须做数据归属校验：

java复制public RepairOrder getRepairOrderDetail(Long orderId, Long currentUserId) {
    RepairOrder order = repairOrderMapper.selectById(orderId);
    if (order == null) {
        throw new BusinessException(2002, "工单不存在");
    }
    boolean isOwner = order.getUserId().equals(currentUserId);
    boolean isAdmin = UserContext.getRole().equals("ADMIN");
    if (!isOwner && !isAdmin) {
        throw new BusinessException(403, "无权查看该工单");
    }
    return order;
}

这个校验逻辑几乎适用于这个系统里所有"按ID查询详情"的接口，包括成绩查询、课表查询、工单详情、意见反馈等。我把它提炼成一个通用方法，每次写查询接口时都主动带上，从根源上杜绝越权。

另一个值得提的安全风险是文件上传接口。我前面提到要校验文件后缀和文件头，这里再补充一点：上传后的文件访问路径不要暴露真实磁盘路径，而是通过Nginx的URL映射访问。这样即使攻击者知道了文件名，也无法通过拼接路径访问到服务器上的其他目录。

6.3 依赖与版本管理：SpringBoot 3.x还是2.x？

写SpringBoot项目时，几乎所有同学都会卡在版本选择上。我的建议非常直接：如果是为了学习和毕设，选SpringBoot 2.7.x + JDK 8/11 + MyBatis-Plus 3.5.x，不要一上来就追新。

原因很现实：3.x版本要求JDK 17起步，而很多校园的机器、云服务器还有网上的教程都基于JDK 8。虽然JDK 17已经普及，但一旦你在3.x里遇到某个starter不兼容或者某个配置写法变了，网上搜到的解决方案大概率还是针对2.x的，排查成本很高。同样的道理，MyBatis-Plus的3.5.x版本对SpringBoot 2.x的适配非常稳定，不需要为了"用新版"给自己制造麻烦。技术选型的核心目标是"稳妥解决问题"，而不是"展示最新版本"。

版本锁定也很重要。Maven项目里建议把常用依赖的版本统一放到<properties>里维护，避免不同模块使用相同但版本不一致的依赖。我在项目里遇到过一个典型的版本冲突：同时引入了一个传递依赖的低版本fastjson和一个直接依赖的高版本fastjson，最后类加载时走了低版本，导致新API不可用，排查了很久才发现是版本覆盖的问题。

6.4 部署上线：从本地到云服务器的完整路径

本地开发环境跑通之后，部署上线是另一个门槛。我的部署方案选型是"轻量应用服务器 + Nginx + MySQL + Redis + SpringBoot fat jar"，核心就几个步骤。

第一步，在application-prod.yml里配置生产环境的数据库、Redis和文件上传路径，不能用开发环境的配置。这里我踩过一个坑：本地MySQL的账号密码是root/123456，部署到服务器后忘了改，直接把开发环境配置上传，导致数据库可被任意连接。虽然只是个泄题事故没有实际损失，但这个教训一定要记住。

第二步，用Maven打包成可执行jar包：

bash复制mvn clean package -DskipTests

第三步，把jar包上传到服务器，用nohup启动，同时打开SpringBoot的Actuator健康检查接口，配合systemd做成服务，实现开机自启和崩溃后自动重启。这一步如果手动启动，服务器重启后项目就起不来了，非常麻烦。

bash复制nohup java -jar campus-system.jar --spring.profiles.active=prod > app.log 2>&1 &

第四步，Nginx配置反向代理和静态资源映射：

nginx复制server {
    listen 80;
    server_name your.domain.com;

    location /api/ {
        proxy_pass http://127.0.0.1:8080/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /uploads/ {
        alias /data/campus/uploads/;
    }
}

小程序端请求的BASE_URL就指向这个域名，并且必须在微信公众平台后台配置服务器域名白名单。注意，小程序对请求域名有严格要求：必须是HTTPS，且IP地址不能直接使用。如果没有HTTPS证书，可以申请免费证书，也可以用cloudbase等平台做中转。这里如果没提前准备好证书，审核或真机调试时会卡住很麻烦。

第五步，也是很容易被忽视的：服务器安全组配置。云服务商的防火墙默认只开放少部分端口，如果忘记放行80/443端口，页面永远打不开。排查起来又慢又容易让人怀疑代码写错了，实际上只是安全组没有放行。

6.5 线上故障排查：OOM与接口超时的实战思路

部署上线后，第一次面临"线上问题"是最锻炼人的。

我遇到的第一个线上问题是OOM：java.lang.OutOfMemoryError: insufficient memory。查日志发现是启动脚本里没有指定JVM内存参数，默认的堆大小和云服务器内存不匹配。修复方案是显式指定堆内存：

bash复制java -jar campus-system.jar
    -Xms256m -Xmx512m
    -XX:+HeapDumpOnOutOfMemoryError
    -XX:HeapDumpPath=/data/logs/heapdump.hprof

这里除了设置堆大小，还配置了OOM时自动dump堆快照，方便事后用jvisualvm或MAT分析。这个参数在开发环境几乎不会被触发，但线上内存一紧张就必须有，不然OOM了只能瞎猜。

第二个问题是接口偶发超时。现象是某个接口偶尔需要十几秒才返回，正常时候几百毫秒。后来排查发现是数据库连接池配置过小，忙时所有连接都被占满，新请求只能排队等连接。修复方法是调整HikariCP配置：

yaml复制spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 30000

这两个问题虽然简单，但都是校园项目部署后最常见的"第一课"。如果同学们在部署时留意一下JVM参数和连接池配置，至少能少踩两个坑。

7. 答辩与项目呈现：如何把系统从"代码能跑"讲成"方案完整"

代码写完、系统上线，真正到了答辩环节，很多同学反而不知道该怎么讲。我参与过一些校内评审，也看过不少毕设演示，最普遍的遗憾是：系统功能做了很多，但讲的人没能把设计逻辑、难点解决和系统价值串起来。

我的建议是准备一份"项目讲解四段论"：先讲背景与痛点（为什么做这个系统，解决什么问题），再讲总体方案（技术选型、架构设计、模块划分、角色权限模型），然后挑两到三个最有技术深度的点深讲（比如统一登录态与安全控制、报修流程状态机与消息触达、缓存设计与性能优化），最后现场演示核心流程（登录→查看信息→提交报修→管理员处理→学生收到通知→完成订单）。这个结构既有高度又有细节，既能展示工程全貌又能体现技术深度。

演示环节有一个容易翻车的细节：一定要用真机演示，不要只开模拟器。模拟器里的小程序登录逻辑一般没问题，但真机上的请求域名校验、授权弹窗、网络环境都可能出现模拟器里不会有的问题。提前用真机跑一遍所有核心流程，确认校园网环境下请求正常再上场。

另外，PPT里不要罗列大段代码，而是放几张核心的架构图、表关系图、流程图，配合关键代码的截图说明。尤其是状态机流转、登录时序、缓存策略这些设计亮点，用图表远比贴代码更能让评委快速理解你的设计思路。

还有一个小技巧：主动准备"系统不足与后续规划"这一页。任何人都知道毕业设计不可能是完美的，主动承认不足并提出改进方向，比被评委指出缺陷后被动解释要体面得多。比如可以说"当前课表与成绩为模拟数据，后续可以对接学校统一身份认证与教务系统API""报修工单的自动派单目前基于简单轮询，后续可以基于维修人员负载做智能调度"。这会让评委觉得你对系统有清晰的认知和不断深入的方向感。

8. 写在最后：做校园项目时我学到的最重要一课

这个项目从需求梳理、数据库设计、后端开发、小程序联调，到部署上线、答辩准备，整个周期大概花了两到三周左右的业余时间。回头复盘，我最大的感受是：做这类校园综合服务系统，技术本身并不是最大的瓶颈，真正的难点在于——你愿不愿意把每个看似简单的功能都往"真实可用"的方向多想一步。

比如登录不是"调通接口就行"，而是要考虑token安全、会话失效、自动续期；报修不是"能提交就行"，而是要有状态流转、权限校验、消息通知；缓存不是"加上Redis就行"，而是要考虑缓存穿透、缓存一致性、key规范。这些"多想一步"做的事情，单独看都不难，但合在一起，就是让系统从"课程作业"变成"能上线试用产品"的分水岭。

如果你也正在做类似的校园项目，我的建议是：先画清楚角色和流程，再建库表，写接口时先想好异常怎么处理，联调时先定好接口规范，部署时先把JVM参数和连接池配置好。把这几件基础事做好，整个开发过程会顺畅很多。

最后分享一个很实用的小工具习惯：我整个开发过程中都在用HBuilderX调试小程序，配合微信开发者工具做真机预览，同时用Postman做后端接口自测。前后端联调时，先把后端接口在浏览器或Postman里跑通，再连小程序，能省掉大量"不知道是前端还是后端问题"的排查时间。希望这篇复盘能帮你少走一些弯路，做出一个真正能打的项目。