如果你在网上搜"音乐推荐系统"，会看到大量Demo把热歌榜点两下、按播放量排个序就叫"推荐"。说实话，这类东西放到简历上，第一轮问算法原理基本就露馅了。最近我给某同学梳理了一个基于Spring Boot的协同过滤音乐网站的设计与实现思路，发现真正走通"用户行为采集→离线协同过滤→在线接口返回"这个闭环并不难，难点在于很多人会跳过数据建模和冷启动，直接去写Mapper查数据库。今天我把这个项目从零搭建的完整过程写出来：方案为什么选物品协同过滤而不是用户协同过滤、行为日志怎么转成评分矩阵、相似度计算和TopN推荐怎么用Java实现、Spring Boot里怎么安排定时任务和缓存，以及最后怎么评估推荐效果、怎么处理新用户和新歌曲。如果你想做的是毕业设计或者练手项目，这篇应该能帮你少走不少弯路。
1. 先别写代码：方案选型才是这个项目的生死线
1.1 为什么"热门排行"不是协同过滤
我见过不少同学的"推荐系统"长这样：写个接口查歌曲表，按播放量倒序排，翻页就完事了。热门播放榜本身是推荐系统里一个必要组件，但它跟协同过滤是两码事。协同过滤的核心假设是"和你相似的人喜欢的东西，你也可能喜欢"，或者"你喜欢的东西的相似物，你也可能喜欢"——注意，它依赖的是用户之间的行为关联，而不是单品本身的统计热度。
这个区别直接决定系统有没有"个性化"。如果所有用户拿到同样30首歌，那不管界面怎么包装，它都不是推荐系统。我刚开始做这种项目时也犯过这个毛病，后来被人一句话问住了："你这个推荐结果，把用户id换成随机数，跟热歌榜有什么区别？"所以动手之前，最好先想清楚到底要解决什么问题：是让老用户发现新歌，还是让新用户快速建立兴趣。这个问题想不清楚，后面的算法选择全是碰运气。
1.2 音乐场景下我为什么优先选ItemCF而不是UserCF
基于用户的协同过滤（UserCF）找的是"跟我口味像的人"，然后把这些人听过的歌推荐给我；基于物品的协同过滤（ItemCF）找的是"跟我听过的歌像的歌"，然后把相似的歌推荐给我。这两种思路在电商、视频、音乐里都有应用，但音乐平台我更推荐ItemCF。
原因有三点。第一，用户量通常远大于歌曲量，UserCF要在用户之间建相似矩阵，用户数量到十万级别之后，离线计算量会非常难看；而歌曲库相对稳定，ItemCF只需要维护歌曲之间的相似关系。第二，音乐口味变化快，用户这个月迷摇滚、下个月听民谣，UserCF把"历史口味相似的人"当成一个稳定聚类，很容易追不上这种口味漂移；ItemCF基于"最近听了什么歌"做扩散，能更快响应用户的短期兴趣。第三，ItemCF推荐结果的解释性更好，可以直接说"因为你喜欢某首歌，所以推荐了它的相似曲目"，这个理由在产品展示和论文答辩里都比"因为你跟某用户相似"好讲得多。
当然这不是说UserCF完全不能用。如果系统用户规模很小、歌曲库特别大，或者你想做"好友都在听"这种社交化推荐，UserCF也有它的价值。选型没有绝对标准，但得知道自己为了什么选它，别拿个模板硬套。
1.3 行为数据就是你的评分：唯一靠谱的"推荐信号"
协同过滤需要一个"用户-物品评分矩阵"，但音乐产品通常没有显式的打分按钮，所以常见的做法是把隐式行为转成分数。这是很多教程最糊弄的地方——直接初始化一个随机矩阵就当评分用了。如果用随机评分，算法再花哨也是自嗨，因为矩阵里根本没有真实规律可学。
我在这个项目里的信号源就是一张行为日志表，记录用户什么时候、对哪首歌、做了什么动作。动作至少包括：播放、完整播放、收藏、加入歌单、跳过。别小看这几个动作，后面评分规则定成什么样，全靠它们撑起来。后面我会专门讲行为日志怎么落表和转分，这里先记住一个原则：真实行为日志是推荐系统的原料。没有原料，后面全是空中楼阁。
2. 搭建数据地基：从行为日志到用户-歌曲评分矩阵
2.1 四张核心表：用户、歌曲、行为、推荐结果
这个项目我用MySQL存业务数据，Redis做缓存。数据库层面核心就四张表，别贪多，把字段设计好就够了。
用户表很简单：user_id、nickname、注册时间，再加一个可选字段用来存新用户选择的音乐风格偏好，这个字段在冷启动阶段会起到关键作用。歌曲表除了常规的歌曲名、歌手名、时长、封面图URL，一定要留两个字段：style（风格标签，比如摇滚、民谣、电子）和状态位。风格标签是后面冷启动和相似歌扩散的关键，很多Demo把歌曲表建得光秃秃的，等要做新歌推荐时才发现没数据可用。
行为日志表是重中之重，我建议至少留这些字段：
| 字段 | 说明 |
|---|---|
| user_id | 用户id |
| song_id | 歌曲id |
| behavior_type | 行为类型：play/finish/collect/playlist/skip |
| listen_seconds | 本次听了多少秒 |
| song_duration | 歌曲总时长 |
| source | 来源标记，比如搜索、歌单、推荐位 |
| create_time | 行为发生时间 |
注意 listen_seconds 和 song_duration 必须同时存下来，因为你判断"完整播放"不能靠用户有没有点暂停按钮，要靠听歌时长和歌曲总时长的比例，这个比例才是硬指标。
推荐结果表存离线算好的结果：user_id、song_id、score、batch_date。batch_date 用来区分是哪一批任务生成的。这张表要和行为日志表分开，因为推荐结果是给在线接口快速读取的，行为日志是给离线算法反复扫描的，两个用途完全不同，混在一张表里会互相拖累。
2.2 行为转评分：别把权重拍脑袋定死
有了日志表，第二步是把用户在某首歌上的所有行为聚合成一个分数。我用的是一套加权规则，长这样：
| 行为类型 | 触发条件 | 得分 |
|---|---|---|
| 完整播放 | listen_seconds / song_duration >= 0.9 | 1.0 |
| 部分播放 | listen_seconds / song_duration >= 0.3 | 0.6 |
| 收藏 | 点击收藏按钮 | 2.0 |
| 加入歌单 | 把歌加进自建歌单 | 1.5 |
| 搜索后播放 | source标记为search | 1.2 |
| 跳过 | listen_seconds < 10秒且非完整播放 | -0.5 |
同一首歌的多次行为分数直接累加，累加结果写进 user_song_score 表：user_id、song_id、score。这一步本质上就是把一个用户对上百首歌的行为压成了一个稀疏向量。
权重的具体数字不是关键，关键在相对关系合理：收藏的权重必须大于普通播放，主动跳过要拉低分数，搜索行为说明用户有明确意图，应该比随机推荐点进来的播放更有分量。这些权重完全可以后续再调，所以行为日志表字段一定要留够。我第一次做的时候只存了"播放次数"一个指标，后来想加跳过惩罚，发现根本查不到用户听了多少秒，只能从零开始重新攒数据，教训相当深刻。
2.3 稀疏矩阵的存储方式：别真去搞一个二维大数组
很多教程画了一张很漂亮的用户×歌曲矩阵图，但实际上你不会真的去存这个二维数组。用户数一万、歌曲数五千，那就是五千万个格子，存成普通表直接爆炸。正确做法是用稀疏结构：只存"用户对哪些歌有过行为"，行为之外的位置默认就是0。
在Java内存里可以用 Map<Long, Map<Long, Double>> 表示，外层key是userId，内层key是songId，value是聚合分数。在MySQL里就是 user_song_score 表，一行代表"这个用户对这首歌有这么多分"。这样就算十万用户、几十万行数据也完全扛得住。后面算法计算时也是在稀疏结构上遍历，而不是去遍历那个巨大的全量矩阵，这样性能才是可控的。
3. 算法实现：物品共现矩阵与TopN推荐生成
3.1 从余弦相似度到物品共现矩阵
物品协同过滤的相似度公式很经典，歌曲i和歌曲j的相似度等于"同时喜欢这两首歌的用户数 / 各自被喜欢次数的平方根"，数学上就是余弦相似度的一种形式，公式写出来是：
sim(i, j) = |N(i) ∩ N(j)| / sqrt(|N(i)| * |N(j)|)
N(i) 是"对歌曲i有正向行为的用户集合"。分母的平方根是为了对热门歌曲做惩罚，否则那些人人听过的热门歌会跟任何歌都"相似"，推荐结果会越来越集中在头部，长尾歌曲完全没有出头的机会。
如果用户行为本身有强度差异，也可以把分子换成两首歌上"用户分数乘积之和"，这就是带权重的共现。我的建议是项目初期先用不带权的经典版本来理解，跑通之后升级成带权版本，效果会平滑一些，也方便写对比实验。
3.2 Java实现：预计算歌曲相似表
实现时没必要在每次请求里算相似度，我选择在定时任务里预计算一张 song_similar 表，字段是 song_id、similar_song_id、sim_score、update_time。核心代码如下：
public void buildSimilarTable(Map<Long, Map<Long, Double>> userSongs) { // 统计每首歌被多少用户产生过正向行为 Map<Long, Double> songCnt = new HashMap<>(); // 共现矩阵，key为歌曲i，value为 <歌曲j, 共现值> Map<Long, Map<Long, Double>> coMatrix = new HashMap<>(); for (Map<Long, Double> songs : userSongs.values()) { List<Long> ids = new ArrayList<>(songs.keySet()); for (Long i : ids) { songCnt.merge(i, 1.0, Double::sum); for (Long j : ids) { if (Objects.equals(i, j)) continue; coMatrix.computeIfAbsent(i, k -> new HashMap<>()) .merge(j, 1.0, Double::sum); } } } // 归一化：除以 sqrt(歌曲i被喜欢次数 * 歌曲j被喜欢次数) List<SongSimilar> similarList = new ArrayList<>(); for (Map.Entry<Long, Map<Long, Double>> e : coMatrix.entrySet()) { Long i = e.getKey(); for (Map.Entry<Long, Double> inner : e.getValue().entrySet()) { Long j = inner.getKey(); double sim = inner.getValue() / Math.sqrt(songCnt.get(i) * songCnt.get(j)); similarList.add(new SongSimilar(i, j, sim)); } } // 只保留每首歌TopK相似项，排序后截断，再批量落库 // 落库前清掉上批次数据，避免脏数据累积 }这段代码看着简单，但有三个地方要留意。第一，遍历用户歌曲对时是 O(用户数 × 平均行为数²)，如果平均行为数到几百，这个循环会非常重，所以后面必须做TopK截断、必须用定时任务而非在线计算。第二，similarList 规模很大时不能逐条insert，要用批处理或者先写临时表再整体替换。第三，相似度截断不能只看绝对阈值，建议先跑一次看看分数分布再决定保留前多少名，我在后面调参部分还会详细说这个坑。
3.3 推荐打分：最近行为扩散加权
有了相似歌曲表，推荐生成就非常直接了。核心思路是：拿用户最近一段时间有正向行为的歌曲，去相似表里找它们的相似歌，按相似度加权求和，最后过滤掉用户已经听过的歌，按分数排序取前N。
用Java写出来大概是这样的：
public List<Long> recommend(Long userId, int recentSize, int topN) { // 1. 取用户最近的 recentSize 首正向行为歌曲，按时间倒序 List<Long> recentSongs = songScoreService.findRecentSongIds(userId, recentSize); if (recentSongs.isEmpty()) { return hotSongService.top(topN); // 冷启动兜底 } // 2. 收集候选歌曲并按加权分数累加 Map<Long, Double> scoreMap = new HashMap<>(); Set<Long> history = songScoreService.findHistorySongIds(userId); for (Long songId : recentSongs) { double userScore = songScoreService.getUserSongScore(userId, songId); for (SongSimilar sim : songSimilarRepo.findTop30BySongId(songId)) { if (history.contains(sim.getSimilarSongId())) continue; scoreMap.merge(sim.getSimilarSongId(), userScore * sim.getSimScore(), Double::sum); } } // 3. 排序取前 topN return scoreMap.entrySet().stream() .sorted(Map.Entry.<Long, Double>comparingByValue().reversed()) .limit(topN) .map(Map.Entry::getKey) .collect(Collectors.toList()); }这里几个参数值得解释一下。取"最近有行为的歌曲"时，我只取最近20到30首，而不是把用户几个月前的行为全部搬出来。推荐系统应该对齐用户当前口味，而不是用户整个历史画像——就像你给朋友推荐歌，不会把他高中时期听的所有歌全部算一遍。每条相似歌曲只取Top30，是为了控制候选集规模和计算量。历史歌曲必须过滤，不然用户已经听过的歌被反复推荐，体验会非常差。
3.4 为什么必须离线预计算，而不是在线实时算
这个点是我觉得工程化项目跟玩具Demo最大的分水岭。如果把相似度计算放在在线接口里，每来一个请求就全量扫一遍共现矩阵，数据库和CPU都会扛不住。用户量起来之后，一个普通请求可能触发几十万次计算，接口延迟直接飙到几秒，然后引发连锁雪崩。
正确做法是把计算拆成"离线批处理"和"在线查询"两步。离线批处理每天凌晨跑一次，算好相似表和推荐结果写库；在线接口只做三件事：查缓存、查结果表、冷启动兜底。这样接口吞吐量能轻松上来，算法逻辑也隔离在任务模块里，下次想换算法（比如换成基于标签的召回）也不会牵连在线代码。
4. Spring Boot工程落地的几个关键环节
4.1 定时任务：凌晨3点全量重算
Spring Boot里做定时任务很简单，一个 @Scheduled 注解加一个配置项就行。我的任务配置是每天凌晨3点执行，因为凌晨用户行为最少，跑推荐计算不会跟在线请求争资源。
@Component @Slf4j public class RecommendScheduler { @Scheduled(cron = "0 0 3 * * ?") public void rebuildAllRecommend() { long start = System.currentTimeMillis(); // 1. 从行为日志聚合出用户-歌曲评分矩阵 Map<Long, Map<Long, Double>> userSongs = behaviorService.buildUserSongMatrix(); // 2. 重建歌曲相似表 similarSongService.rebuild(userSongs); // 3. 对活跃用户生成推荐结果 recommendResultService.generateForActiveUsers(userSongs); // 4. 清理旧缓存 cacheService.clearRecommendCache(); log.info("recommend task finished, cost {} ms", System.currentTimeMillis() - start); } }这里重点想提醒的是幂等性。定时任务如果中途失败重跑，或者上一批还没跑完下一批又开始，会产生重复和脏数据。我的做法是给 recommend_result 表加唯一索引 (user_id, song_id, batch_date)，每次任务用一个新的 batch_date，跑完后再把旧批次清掉。另外，日志里一定要记录耗时和处理量，不然任务挂了你都不知道挂在哪一步。
4.2 推荐接口设计与结果落库
离线算好的推荐结果直接查表返回，接口设计得很薄：
@RestController @RequestMapping("/api/recommend") public class RecommendController { @GetMapping("/songs") public Result<List<SongVO>> recommendSongs(@RequestParam Long userId, @RequestParam(defaultValue = "30") int limit) { List<SongVO> list = recommendService.getTopN(userId, limit); return Result.ok(list); } }recommendService 内部的处理顺序是：先查Redis缓存，缓存没有就查 recommend_result 表，表里也没有就进入冷启动分支。每一层都很快，不会出现复杂计算。接口返回的歌曲对象里可以带 score 字段和理由字段，前端拿到后可以展示"因为你最近常听民谣，为你推荐这张歌单"，交互感和答辩展示里的功能性亮点都有了。
4.3 Redis缓存与热点回退
推荐结果的缓存key我用 recommend:user:{userId}，value是JSON数组，过期时间设成22小时。这样设计有个讲究：任务每天凌晨3点跑，过期时间必须短于24小时，否则任务更新完数据后，旧缓存还得再存活一段时间，用户看到的是新旧混在一起的结果。所以过期时间设成22小时是偏保守的，保证凌晨任务跑完后缓存能被自然淘汰或者被主动清掉。
另外不需要给所有用户都建缓存。活跃用户的推荐结果被频繁读取，缓存价值最大；长尾用户几个月登录一次，缓存纯粹浪费内存，直接查结果表就行。我通常只对近7天有过行为的用户生成推荐结果，少于这个阈值的用户走冷启动或热门兜底，省时省力，指标也不会差。
4.4 项目模块划分与整体数据流
整个项目的模块划分我建议按职责拆，别把什么都塞进一个Controller。大致是：行为采集模块负责接收和落库用户行为，推荐引擎模块负责定时任务和算法计算，推荐服务模块负责在线接口和缓存，歌曲管理模块负责后台歌曲录入和标签维护。
数据流从头到尾是：用户点歌产生行为日志 → 行为日志落库 → 定时任务聚合评分矩阵 → 重建相似表 → 生成推荐结果 → Redis或MySQL给在线接口读取。这条链路通了，前端就是展示层的事，后面换成别的算法也容易。
5. 冷启动、离线评估与调参踩坑记录
5.1 新用户和新歌曲的冷启动方案
协同过滤对没有行为的用户无能为力，这是算法本身的特性，不是代码bug。新用户注册时我建议让他选几个喜欢的音乐风格，存到用户表里。推荐服务检测到该用户没有足够行为时，就先按风格偏好召回一批同风格歌曲，再混入一定比例的热门歌。这样比单纯给热歌榜的体验好很多，而且用户一旦开始产生行为，系统就能平滑过渡到协同过滤。
新歌曲的冷启动更容易被忽略。歌曲刚上传时没有任何用户行为，永远不会进入相似表，所谓"推荐新歌"就成了摆设。我的做法是：歌曲上传后按风格标签找出同风格下的已有歌曲，把新歌挂到这些歌曲的相似关系里；同时在推荐结果里预留"探索位"，比如Top10里放一两首新歌或低热度歌曲，避免系统永远只推头部内容。探索位的比例不用太高，10%到30%就够，太高会影响整体准确率。
5.2 离线评估：留一法算准确率、召回率和覆盖率
推荐效果不能靠肉眼感觉，得有量化指标。我的离线评估方法是时间切分：把每个用户的行为按时间排序，取前80%作为训练集，后20%作为测试集。用训练集跑推荐，看推荐结果里有多少能命中测试集。
核心指标有三个。准确率@K等于推荐列表前K首里命中测试集的歌曲数除以K，衡量"推的到底是不是用户真的会听的"；召回率@K等于命中数除以测试集歌曲总数，衡量"用户喜欢的歌有多少被找出来了"；覆盖率等于推荐结果里去重后的歌曲数除以歌曲总数，衡量"系统是不是只会推头部热门歌"。这三个指标跑下来，算法和参数的优劣就非常清楚了，也方便论文里画对比图。
5.3 我调参过程中踩过的三个坑
第一个坑是相似度阈值拍脑袋定。我第一次把阈值设为0.1，结果推荐结果发散得离谱，因为数据量小的时候，很多歌曲的共现次数会被偶然因素放大。后来我先把相似度分数分布统计出来，发现大量相似度集中在0到0.05之间，才把阈值定到0.15，效果立刻稳了。记住：阈值要根据自己数据的分布来定，不是网上抄一个0.2就能直接用的。
第二个坑是重复任务产生脏数据。第一次跑完定时任务后，我手动又触发了一次，结果推荐表里同一批数据出现两份，前端展示时一首歌混在前后两个位置。加唯一索引之后解决。这种细节面试官很爱问，因为能体现你是不是真的跑过完整流程，而不只是写了个Demo。
第三个坑是测试数据造得太"干净"。为了快速看到推荐效果，我一开始模拟了100个用户，每个人只听两个固定风格里的歌，准确率高达80%以上，看起来非常爽，实际上完全失真。后来加了大约10%的随机行为，模拟用户偶尔乱点的情况，指标立刻回落到合理区间。造数据也要造得有噪声，否则调参时会被虚假的漂亮指标带偏。
最后给准备动手的人一个建议：先不要急着做前端界面，先把数据流跑通——用户点歌产生行为日志，定时任务把行为变成相似表和推荐结果，接口把结果吐出来。这一条链路通了，后面换算法、加功能、写文档都有底气。真要说这套项目里最容易被低估的，就是行为日志的设计，多留几个字段，后面调评分规则和做冷启动时能省一大堆事。我在实际项目里每改一次评分规则，都会庆幸当初存了听歌时长和跳过动作，而不是只存一个播放次数。
