SpringBoot校园服务平台协同过滤推荐系统设计与实现

这段时间在带同学做毕设评审，越来越明显的一个感觉是：挂在简历和开题报告里的技术名词很多，但真正能在系统里把“推荐”两个字落到代码级的人很少。今天就拿一个很典型的题目——基于SpringBoot的校园服务平台，并且要带协同过滤算法——完整拆一遍设计思路、数据建模、算法实现和工程排坑经验。

这个题目能打几分，通常不取决于你做了多少页面、写了多少个增删改查接口，而是取决于你能不能把“协同过滤算法”从一个论文词汇，变成一个用户打开首页就能看到“为你推荐”列表的完整链路。适合正在写毕设、课程设计，或者想转推荐系统方向的Java后端同学参考，我会按实际开发顺序来讲，里面有代码、有数据、有踩坑记录。

1. 这类项目最值钱的不是CRUD，而是推荐链路

1.1 校园服务平台到底要推荐什么

先把业务范围说清楚。所谓的校园服务平台，落到具体功能上一般不会只有一个模块，常见的是把这几块塞进去：二手教材和闲置物品交易、学习资料分享与下载、竞赛组队、失物招领、校园跑腿代办。这些模块的业务实体差异很大，但在推荐系统里都可以抽象成一个概念——物品（item）。

之所以需要推荐，是因为校园平台天然面临信息过载。一个新生想买二手教材，如果按发布时间排序，他面对的可能是一百多条不相关的商品信息；但如果他两天前浏览过《高等数学》教材，系统应该能把这本教材、同专业的习题集、配套网课资料排到列表前面。这里的核心判断是：不同用户看到的内容列表应该是不一样的，推荐算法就是给每个用户生成一条个性化的排序结果。

我从一开始就建议把“二手交易”作为主要推荐场景，因为它的用户行为最完整。用户在二手场景里会发生浏览、收藏、加入购物车、联系卖家甚至下单这一系列动作，这些动作天然构成协同过滤算法需要的行为数据。学习资料和组队活动可以作为热门榜、分类推荐来补充，这样项目既有算法深度，又有业务广度。

1.2 SpringBoot为什么是这类项目的稳妥选择

有人会问，为什么不用SSM？SSM当然可以用，但如果你把时间花在配置事务、配置MyBatis工厂、处理各种XML上，留给算法的精力就少了。SpringBoot的价值在于自动装配和起步依赖，它能让你用最少的配置把项目跑起来，把开发重心集中在业务和算法上。这一点在做推荐系统这种偏业务逻辑的项目时尤其重要。

另外，SpringBoot的生态对这类项目太友好了。MyBatis有官方starter，Redis有spring-boot-starter-data-redis，定时任务直接一个@Scheduled注解就能跑，后面如果要接消息队列也有现成的starter。校园服务平台通常需要Vue做前端、MySQL存数据、Redis做缓存，SpringBoot正好把这些全都包进去了。

选型还有一个现实考量：答辩和面试的时候，SpringBoot是你最好讲的东西。它能往“自动配置原理”方向聊，能往“MVC分层”方向聊，也能和“推荐算法工程落地”结合。一套技术栈讲三个深度层次，这在项目汇报里非常加分。

1.3 协同过滤选UserCF还是ItemCF

这是整个项目第一个要做的核心技术决策。协同过滤算法分两大类：基于用户的协同过滤（UserCF）和基于物品的协同过滤（ItemCF）。我直接给对比结论。

校园服务平台选ItemCF作为主算法，理由有三条。第一，物品集合稳定。二手教材、学习资料这些物品的生命周期长，相似度矩阵可以每天凌晨算一次，不用实时更新。第二，可解释性强。前端页面可以展示“推荐理由：因为你浏览过《数据结构》”，这种明确理由是UserCF很难做到的。第三，新用户友好。用户刚注册没有任何行为时，UserCF完全无能为力，但ItemCF可以先返回热门物品，等用户产生了一两条浏览行为，就能开始做相似推荐。

如果场景换成校园资讯流或者社团活动动态，那UserCF会更合适，因为用户的兴趣漂移很快，任何一个浏览行为都可能改变他下一秒想看到的内容。我这套方案里也可以保留一个UserCF的辅助推荐通道，作为“猜你喜欢”的第二个数据源，但主推列表用ItemCF。

2. 数据建模与算法落地：把推荐器真正跑起来

2.1 四张核心表这样设计

很多人做这类项目，上来就设计一堆业务表，商品、订单、用户、评论，结果到了写推荐算法的时候发现没有数据可用。正确的顺序是先把推荐需要的数据结构定义好，业务表跟着推荐走。

我的做法是只抽象四张核心表。

用户表（user）

物品表（item）

行为表（behavior）

推荐结果表（recommend_result）

行为表是推荐系统的命根子。用户点开了一个商品详情页，前端调一次后端接口，后端就往behavior表里插入一条浏览记录。这个数据必须从项目第一天就开始采集，否则后面算法写得再好也没法验证。

行为权重映射是很容易被忽略的设计点。我采用的规则是：浏览记1分，收藏记2分，加入购物车记3分，购买记5分。注意这里的score并不是用户给商品的评分，而是行为重要程度的权重。用户在商品详情页停留了30秒，和用户直接下单买走，这两个动作代表的信息量完全不同，如果一律按浏览处理，购买行为的价值就被稀释了。这里还有个答辩常常被问的细节：为什么不在前端直接传score？因为前端传score不可信，正确的做法是前端只传behavior_type，后端根据类型映射分值，防止刷分。

2.2 物品相似度计算的工程实现

ItemCF的第一步是计算物品之间的相似度矩阵，这是整个推荐系统“记忆”的核心。核心思想一句话就能说明白：同时喜欢物品A和物品B的用户越多，A和B越相似。

计算公式用余弦相似度，表现形式是：

sim(A,B) = 同时喜欢A和B的用户数 / sqrt(喜欢A的用户数 × 喜欢B的用户数)

为什么要除以分母？用一个生活例子解释，如果物品A是个超级热门品，比如《高等数学》教材，有一千个用户喜欢它，物品B是个冷门资料，只有两个用户喜欢它，恰巧这两个用户也都喜欢A。如果不做分母归一化，A和B的共现次数是2，看起来很高；但归一化之后差异就出来了。分母的作用是惩罚热门物品，避免一个热门物品和所有物品都相似。

工程实现上不需要引入任何算法库，用HashMap就能算。核心代码我贴出来：

public class ItemCFCalculator { /** * 根据用户行为列表计算物品相似度矩阵 * @return key: itemId, value: (relatedItemId, similarity) */ public Map<Long, Map<Long, Double>> calcSimilarityMatrix(List<Behavior> behaviors) { // 第一步：构建用户 -> 物品集合的倒排表 Map<Long, Set<Long>> userItems = new HashMap<>(); for (Behavior b : behaviors) { userItems.computeIfAbsent(b.getUserId(), k -> new HashSet<>()).add(b.getItemId()); } // 第二步：统计物品共现次数 Map<Long, Map<Long, Integer>> coCount = new HashMap<>(); Map<Long, Integer> itemCount = new HashMap<>(); for (Set<Long> items : userItems.values()) { for (Long a : items) { itemCount.put(a, itemCount.getOrDefault(a, 0) + 1); for (Long b : items) { if (a.equals(b)) { continue; } coCount.computeIfAbsent(a, k -> new HashMap<>()) .put(b, coCount.get(a).getOrDefault(b, 0) + 1); } } } // 第三步：计算余弦相似度 Map<Long, Map<Long, Double>> matrix = new HashMap<>(); for (Map.Entry<Long, Map<Long, Integer>> entry : coCount.entrySet()) { Long itemA = entry.getKey(); for (Map.Entry<Long, Integer> e : entry.getValue().entrySet()) { Long itemB = e.getKey(); double sim = e.getValue() / Math.sqrt( (double) itemCount.get(itemA) * itemCount.get(itemB)); matrix.computeIfAbsent(itemA, k -> new HashMap<>()).put(itemB, sim); } } return matrix; } }

这个实现有两个工程上的关键点。第一，先用倒排表把“用户-物品”关系转成“用户-物品集合”，避免对全部行为做笛卡尔积。第二，相似度矩阵算完后放进一个静态缓存Map里，不用每次用户请求都重新计算。校园服务平台的物品量级通常在几千条以内，全量计算一次耗时几十到几百毫秒，完全可以接受。

2.3 TopN推荐生成与冷启动兜底

有了相似度矩阵，推荐生成就是一个加权求和的过程。对用户u来说，候选物品i的预测分等于：用户u所有产生过行为的物品j，分别乘以物品j与物品i的相似度，再除以相似度之和做归一化。

预测分(u,i) = Σ( sim(i,j) × score(u,j) ) / Σ sim(i,j)

归一化这步不能省，否则行为多的用户天然会得到更高分，推荐结果就失去了用户间的可比性。

生成推荐列表的代码实现如下：

public List<RecommendItem> recommend(Long userId, int topN) { // 用户已交互物品，生成推荐时必须过滤掉 Set<Long> interacted = behaviorMapper.selectItemIdsByUser(userId); // 用户已有行为的评分map Map<Long, Double> userScores = behaviorMapper.selectScoresByUser(userId); // 相似度矩阵，实际开发中从缓存获取 Map<Long, Map<Long, Double>> matrix = getSimilarityMatrix(); Map<Long, Double> scoreMap = new HashMap<>(); Map<Long, Double> weightSum = new HashMap<>(); for (Map.Entry<Long, Double> entry : userScores.entrySet()) { Long itemJ = entry.getKey(); double scoreUJ = entry.getValue(); Map<Long, Double> simMap = matrix.getOrDefault(itemJ, Collections.emptyMap()); for (Map.Entry<Long, Double> simEntry : simMap.entrySet()) { Long itemI = simEntry.getKey(); if (interacted.contains(itemI)) { continue; } double w = simEntry.getValue(); scoreMap.put(itemI, scoreMap.getOrDefault(itemI, 0.0) + w * scoreUJ); weightSum.put(itemI, weightSum.getOrDefault(itemI, 0.0) + w); } } List<RecommendItem> result = new ArrayList<>(); for (Map.Entry<Long, Double> e : scoreMap.entrySet()) { double weight = weightSum.getOrDefault(e.getKey(), 0.0); if (weight == 0) { continue; } result.add(new RecommendItem(e.getKey(), e.getValue() / weight)); } result.sort((a, b) -> Double.compare(b.getScore(), a.getScore())); return result.stream().limit(topN).collect(Collectors.toList()); }

这版代码里有一行特别重要：过滤已交互物品。很多同学第一次跑推荐，发现用户刚买完一本教材，推荐列表里又出现同款教材，就是漏了这一步。协同过滤的本质是发现用户没有直接见过但可能喜欢的物品，如果连用户已经买过的东西都推出来，系统会显得很蠢。

冷启动场景怎么处理？我在代码里加了一个分支：如果用户行为少于5条，直接返回热门榜。热门榜的SQL很简单，按行为次数聚合排序。新用户看到热门榜，点进两三个浏览后，协同过滤就开始有数据可用了。新物品上线没人买，相似度矩阵里没有它的位置，我的做法是给新物品加一个小比例的随机探索分，让它有一定机会被曝光。这个做法在算法上叫探索与利用的平衡，你不需要把它做得太复杂，一个0.05~0.1的随机分就够了。

3. 工程整合细节：SpringBoot、MyBatis、Vue一起怎么玩

3.1 项目结构与启动装配

项目采用前后端分离架构，后端是SpringBoot，前端是Vue，但部署时把前端打包进SpringBoot，整体变成一个jar包。

后端包结构我长期实践下来最顺手的是这一版：

com.campus.service ├── controller # 接口层 │ ├── RecommendController │ ├── ItemController │ └── BehaviorController ├── service # 业务逻辑 │ ├── recommend │ │ ├── ItemCFCalculator │ │ └── RecommendService │ └── item │ └── ItemService ├── mapper # MyBatis接口 ├── entity # 实体类 ├── config # 配置类 └── common # 统一返回、异常处理

启动类加上@MapperScan和@EnableScheduling两个注解，比SSM时代手动配置MapperFactoryBean和任务调度器省太多事。

@SpringBootApplication @EnableScheduling @MapperScan("com.campus.service.mapper") public class CampusServiceApplication { public static void main(String[] args) { SpringApplication.run(CampusServiceApplication.class, args); } }

这里有个细节值得说一下：为什么用MyBatis而不是Spring Data JPA？推荐系统里有大量统计类的SQL，比如按用户聚合行为、按物品聚合次数、多表join出推荐原因。MyBatis可以把这部分SQL写得很直接，可控性强。JPA在处理复杂统计时要么写JPQL，要么走原生SQL，反而不如MyBatis顺手。

application.yml里主要配置MySQL数据源、Redis连接、MyBatis的mapUnderscoreToCamelCase和mapper扫描路径。没有特别魔幻的配置，唯一提醒的是地图下划线转驼峰一定要开启，否则数据库里的user_id死活映射不到entity的userId属性上。

3.2 推荐接口与定时任务的完整链路

推荐模块的接口我设计了三个，一个主推、两个辅助：

用户打开首页后，完整链路是这样的：前端带userId请求推荐接口；后端先查Redis缓存，缓存key可以设计成recommend:user:{userId}，命中就直接返回；没命中就去recommend_result表查离线推荐结果；如果用户行为太少导致表里没有数据，就返回热门榜兜底；最终结果写入Redis，设置两小时过期。

为什么每个用户的推荐结果还要落一张表？因为推荐结果需要可解释、可回溯，而且凌晨计算的结果如果只放内存，服务一重启就全没了。落表以后，用户每次请求走的是一次普通SQL查询，压力很小。

定时任务这部分，我用SpringBoot原生@Scheduled就够用：

@Component public class RecommendTask { @Scheduled(cron = "0 0 3 * * ?") public void dailyRefresh() { // 1. 从behavior表拉取最近30天行为数据 // 2. 调用ItemCFCalculator计算相似度矩阵 // 3. 对所有活跃用户生成Top50推荐 // 4. 批量写入recommend_result表 } }

为什么定在凌晨3点？校园网络凌晨在线人数最少，推荐计算是CPU密集和IO密集混合的任务，在低峰期跑不会影响白天用户请求的性能。这一步在答辩时可以顺势讲一讲“离线计算与在线服务分离”的架构思想，属于很标准的推荐系统分层。

推荐结果不要按单个用户一条一条insert。我前期试过，100个用户每次跑要30秒；后来改成MyBatis批量insert，一次提交200条，耗时降到2秒。这个优化直接用SqlSession批量模式，代码改动量不大，收益却是数量级的。

3.3 前端打包进SpringBoot的部署方案

Vue和SpringBoot前后端分离，很多同学卡在跨域上。前端起了个8081端口，后端8080端口，调接口时报CORS错误，然后倒腾各种跨域配置。我的做法更省事：直接把Vue打包后的dist文件夹塞进SpringBoot。

操作步骤三步走：

1. 前端项目执行npm run build，生成dist目录；
2. 把dist目录下所有文件复制到SpringBoot的src/main/resources/static目录；
3. 启动SpringBoot，浏览器访问http://localhost:8080，直接就能看到前端首页。

这样做的好处太多了：首先不需要单独部署Nginx，项目最终交付就是一个jar包；其次前后端同源，不需要处理跨域；再者在idea里直接启动，不用每次手动切两个服务。前端页面是静态资源，SpringBoot默认映射了/static路径，直接把文件丢进去就能访问。

唯一的坑是Vue Router用了history模式的话，前端页面在浏览器刷新时会404。原因很简单：SpringBoot内嵌的Tomcat处理不了前端路由的“伪路径”。我用了hash模式，URL会带个#号，虽然没那么好看，但稳定可靠。如果非要用history模式，就得写一个Controller转发非API请求到index.html，相对麻烦一点。对毕设和内部系统来说，hash模式足够了。

4. 实测数据：用了推荐算法和没用的区别

4.1 仿真数据怎么造

实际项目上线前没有真实用户行为，但推荐效果必须在开发阶段就验证。我用Python脚本生成了一套仿真行为数据，模拟了100个用户、50个物品、大约800条行为记录。

数据生成的逻辑不是纯随机，而是模拟了“用户兴趣分组”。我先把50个物品按主题分成5组，让80%的用户行为集中在自己归属的主题组内，剩下20%随机产生，模拟现实中的偶然兴趣。生成脚本的核心部分：

import random random.seed(42) users = range(1, 101) items = range(1, 51) clusters = 5 rows = [] for u in users: user_cluster = u % clusters main_pool = [i for i in items if i % clusters == user_cluster] # 从主兴趣池里挑3~8个，再从全局池挑1~2个做噪声 chosen = random.sample(main_pool, random.randint(3, 8)) chosen += random.sample([i for i in items if i not in main_pool], random.randint(1, 2)) for it in chosen: # 主兴趣池内行为更重：收藏/加购/购买 if it in main_pool: behavior_type = random.randint(2, 4) else: behavior_type = 1 rows.append((u, it, behavior_type))

造完数据导入MySQL。注意要留一份测试集，不能拿全部行为去训练再评估。我按用户行为时间排序，前80%做训练集，后20%做测试集，这样能验证算法是否真的能从历史行为预测未来行为。

4.2 评测指标：准确率、召回率、覆盖率对比

推荐系统的离线评测我用三个核心指标：Precision@10、Recall@10、覆盖率。定义不复杂：

• Precision@10：推荐列表前10条里，有多少条出现在测试集（用户未来真实行为中），除以10；
• Recall@10：推荐列表前10条里命中的数量，除以用户在测试集里的总行为数；
• Coverage：推荐结果覆盖了多少个物品，除以全量物品数。

同一份仿真数据下，ItemCF和两个基准策略的对比结果：

看数据能得出两个结论。第一，ItemCF相比热门推荐，Precision提升了大约60%，这说明个性化排序确实比单纯按热度排更能命中用户兴趣。第二，ItemCF的覆盖率不是最高但也不是最低，在0.44左右，说明算法没有完全陷入“只推热门”的陷阱，长尾物品也有机会被曝光。随机推荐的覆盖率虽然高，但准确率惨不忍睹，没有任何实用价值。

这些数字给不了绝对结论，毕竟仿真数据和真实行为有差距，但至少证明了“协同过滤算法在校园服务平台里比拍脑袋排序有效”这一判断是站得住的。毕业答辩时把这张表拿出来，比空谈理论有说服力得多。

4.3 接口性能实测与缓存效果

推荐模块的性能敏感性很高，首页加载多等一秒，用户流失率都会上升。我做了三组对比实验：

最直观的对比是12ms和220ms，差了接近20倍。每次请求全量计算的问题在于，相似度矩阵构建涉及遍历行为表、双重循环统计共现次数，用户量一大CPU直接打满，高峰期必然出现超时和错误请求。改成“凌晨离线计算推荐结果，用户请求只查表”的模式后，性能瓶颈彻底消失。

实际线上部署时，我又加了Redis这一层，目的是抗住首页的高频访问。同一个用户短时间内多次刷新首页，如果每次都查MySQL，数据库的压力也不小。Redis的set和get开销极低，把序列化好的推荐列表直接放进去，两个小时内重复请求全部命中缓存。

性能优化的思路其实一句话就能概括：算法层尽量离线算，服务层尽量缓存查询结果，不要让计算密集的任务跑到用户请求的链路里来。这个原则放到任何推荐系统项目里都成立。

5. 常见问题与排错实录

5.1 相似度计算慢到无法忍受

项目第一次跑通推荐功能时，我印象特别深——打开首页等了八秒。一开始以为SQL慢，把MyBatis的日志打开一看，SQL正常；再定位，发现相似度矩阵在每次请求时都全量计算了一遍，而且物品双循环是O(n²)复杂度，50个物品还看不出问题，跑到几百个物品就直接卡死。

解决办法两个层面的。代码层面，把计算好的相似度矩阵放进ConcurrentHashMap做缓存，设置过期时间，每天定时任务刷新一次。架构层面，把推荐计算从请求链路移到凌晨定时任务，用户请求只读离线算好的推荐结果表，不再参与矩阵计算。

优化后，全量计算一次只要120ms，用户请求响应跌到几十毫秒。这个坑是推荐项目新人必踩的，踩过一次你就明白“离线计算”这个词不是学术概念，而是工程生存刚需。

5.2 推荐结果里混入用户已经买过的商品

现象很直观：用户下单了一本二手教材，第二天打开首页，推荐第一还是这本教材。检查代码才发现，推荐生成逻辑里漏了“过滤已交互物品”这一步。

修复方式就是在推荐计算的候选物品遍历前，先用一条SQL把用户交互过的itemId全部查出来，构建成一个Set，加权求和时直接跳过。注意这里不能只过滤“购买”，浏览、收藏、加购过的都应该过滤，否则推荐列表里全是用户看腻了的物品。

我踩过这个坑之后习惯性地加了一个单元测试，用固定数据构造10条推荐，断言返回结果里不能出现行为表里已有的itemId。哪怕是一次性的毕设项目，这种断言也能在后续改动时救你命。

5.3 SpringBoot版本太高带来的兼容性坑

这个项目刚开始我用了最新的SpringBoot版本，结果计划赶不上变化。最先遇到的问题是MyBatis starter的版本不兼容——旧的mybatis-spring-boot-starter还在用spring.factories注册自动配置，新版SpringBoot改成了AutoConfiguration.imports机制，旧starter完全不生效，项目能启动但Mapper全部bean找不到。

另外一个高频坑是WebMvcConfigurerAdapter。早年教程里写的是继承这个抽象类，SpringBoot 2.6之后它被彻底移除，必须改成实现WebMvcConfigurer接口。如果照着老博客敲代码，编译直接报错。

我的建议是，这类项目选Spring Boot 2.7 + MyBatis 2.3组合，这是经过海量项目验证的稳定搭配。如果非要上Spring Boot 3.x，那MyBatis必须换3.x版本，同时JDK最少17起步。切记不要无脑选最新版本，稳定组合能帮你省下大量排错时间。

5.4 定时任务不执行或互相阻塞

离线推荐任务写好后，第一天跑通了，第二天却没有任何推荐结果更新。排查了半天，最后发现是启动类少了@EnableScheduling。所有@Scheduled注解在没有这个开关的情况下全部静默失效，日志里什么错误都不提示，非常隐蔽。

另一个更隐蔽的问题是定时任务互相阻塞。SpringBoot默认的@Scheduled是单线程调度，如果任务列表里有一个长任务卡住了，后面所有任务都得排队等。我后来加了一个调度线程池配置：

@Configuration public class ScheduleConfig implements SchedulingConfigurer { @Override public void configureTasks(ScheduledTaskRegistrar taskRegistrar) { taskRegistrar.setScheduler(Executors.newScheduledThreadPool(4)); } }

四个线程并行执行任务，推荐计算、热门榜刷新、缓存预热各走各的，互不干扰。

5.5 冷启动、稀疏矩阵与SQL慢查询

新注册用户没有任何行为数据，推荐接口会返回空列表。这个问题的标准解法是热门兜底，但热门兜底也有讲究：不能只按总行为数排序，要按“最近30天”的行为数排序，否则那些上线很久的僵尸物品永远占着热门榜。

数据稀疏问题在校园平台很常见，很多用户就注册时点了几下，之后再也不活跃。训练算法时我把行为数少于3条的用户直接过滤掉，不参与相似度计算。这样虽然减少了训练样本量，但留下来的数据质量高，算出来的相似度矩阵更可信。

SQL慢查询主要发生在behavior表全表聚合时。我建了联合索引idx_user_item(user_id, item_id, create_time)，用户行为上报、推荐过滤这两类高频SQL都走索引。另外，推荐结果批量写入一定要用batch insert，单条循环插入在MySQL里要经历几千次网络往返，性能差距天壤之别。

做这类项目最大的心得是：协同过滤算法的代码量其实很小，真正的复杂度全在数据清洗、行为日志和工程边界情况上。算法原理看两篇文章就懂了，但把推荐链路跑得又稳又快，靠的是每一个细节的打磨。建议你先别急着追求Flink、Spark那一套大数据方案，先把单元子跑通、把行为数据采好、把离线计算的闭环建起来，这套思路放到任何推荐系统里都是通用的。后面如果行为数据量真的大到单机算不动了，再考虑把计算层升级成Flink流处理，那就是从“能用”走向“能扛”的下一步了。