1. 项目概述：一套能跑通的协同过滤推荐系统
在做Java后端开发的这几年里，我陆续接手过不少电商、内容社区类的项目，几乎每个产品经理都会提一句“能不能给用户做个性化推荐”。这句话听着简单，落地起来却是一大摊子事：算法怎么选、数据怎么存、推荐结果怎么算、接口怎么设计、前端怎么展示。如果只是拿现成的推荐平台调接口，往往受限于数据格式和业务耦合度，改了半个月发现还是不合适。
正因如此，我花了几个周末，用Java SpringBoot+Vue3+MyBatis+MySQL这套经典组合，从零搭了一个前后端分离的协同过滤电影推荐系统。这里说的“系统源码”不是那种只跑demo的玩具工程，而是把用户登录注册、电影信息管理、评分记录、协同过滤推荐、以及前端推荐列表展示这些完整链路都串起来了。你拿到手之后，跑起来就能看见推荐效果，改起来也知道每一行代码在干嘛。
这篇文章的核心思路就是把这些技术点和落地过程掰开揉碎讲一遍：从推荐算法的原理解读，到表结构设计、后端接口实现、前端交互，再到实际部署中容易踩的坑，全部覆盖。适合正在学SpringBoot和Vue3的开发者，也适合那些手里有项目但不知道怎么引入推荐功能的人。读完你不仅能复现这个系统，还能根据自己的业务场景去调整算法细节。
我始终觉得，推荐系统不是什么高深莫测的东西，它的本质就一句话：在你还没明确说要什么的时候，系统先猜你想看什么。而协同过滤就是猜得比较准的那一类办法。下面我们一步步把它拆开。
2. 协同过滤算法原理：先搞清楚“猜你喜欢”的依据
2.1 两种主流协同过滤思路的对比
协同过滤（Collaborative Filtering）的核心假设很简单：相似的人会有相似的喜好，相似的事物会被同一个人喜欢。这句话听起来像废话，但推荐系统里最经典、最稳定的算法就是建立在这个假设上的。实际落地时，它分成两条路——基于用户的协同过滤（User-Based CF）和基于物品的协同过滤（Item-Based CF）。
基于用户的协同过滤，思路是找到和你“口味一致”的邻居用户。比如A同学和你看过的电影重合度很高，而且A同学给某部冷门文艺片打了高分，那这部片子应该也符合你的口味。它的优点是能推荐出跨度很大的新内容，缺点是用户量大的时候，计算用户之间相似度的成本直线上升，我们习惯称之为“用户维度的稀疏问题”。
基于物品的协同过滤，思路则反过来：先算出物品之间的相似度，然后根据你历史上喜欢过的物品，给你推荐和这些物品最相似的电影。比如你给《盗梦空间》打了五星，系统发现给《星际穿越》打五星的人和你是同一批人，于是《星际穿越》就被推到你面前。它的优点是计算过程可以提前离线做好，线上响应快，也是工业界电商平台用得最多的方案。
那这个电影推荐系统选了哪条路？我建议你两个都实现，但默认用基于物品的协同过滤。原因后面会详细说，这里先给个结论：电影场景下用户数量远大于电影数量，物品相似度矩阵的规模可控；而基于用户的方式在冷启动阶段和实时性上都有明显劣势，适合做辅助策略。
2.2 相似度计算：余弦相似度和皮尔逊相关系数
不管走哪条路，协同过滤绕不开一个核心问题：怎么量化“相似”。
最常用的相似度计算方法是余弦相似度。把两个人（或两部电影）的评分数据看成高维空间里的两个向量，然后计算它们之间的夹角。夹角越小，说明方向越一致，也就是越相似。公式写成：
similarity = cos(θ) = Σ(ai * bi) / (sqrt(Σ(ai²)) * sqrt(Σ(bi²)))这个公式的好处是它天然能消除“打分尺度不同”的问题。比如有的人习惯打高分，觉得6分的电影已经不错了；有的人打分严格，6分已经算烂片。用余弦相似度，向量的模长被归一化，比的是方向而不是长度，所以能在一定程度上抵消这种打分偏移。
另一个常用的是皮尔逊相关系数，公式稍微复杂一点：
similarity = Σ((ai - avg_a) * (bi - avg_b)) / (sqrt(Σ(ai - avg_a)²) * sqrt(Σ(bi - avg_b)²))它比普通余弦相似度多了一步：先减去各自的平均分，再做余弦计算。这一步的效果是进一步去除了“打分严格度”的影响，只保留“评分模式”的相似性。换句话说，A用户给电影普遍打低分，B用户给电影普遍打高分，但如果他们都觉得某几部电影是各自列表里的翘楚，那皮尔逊会认为他们相似度很高。
作为通用做法，我建议：数据量小、评分数值明确的时候用皮尔逊相关系数；数据量大、需要快速计算的场景用余弦相似度。这个电影推荐系统里，我两种都写了工具方法，方便你们对比效果。
2.3 预测评分的加权公式与TopN推荐
算出相似度之后，怎么把相似用户的评分“转嫁”给目标用户？这里用加权平均公式：
预测评分 = Σ(相似度 * 评分) / Σ(|相似度|)意思很直白：和你越相似的人，他打的分数权重越高。然后对目标用户没看过的电影，逐一计算预测评分，按分数从高到低排序，取前N个就是TopN推荐。
实际工程里，我们不会真去预测所有电影的分数，那样性能太差。通常的做法是预先给每个用户维护一个“已评分物品集合”，推荐时只考虑“用户没评过分的物品”里那些至少被K个邻居用户评过分的物品，K一般取5到20。这样能显著压缩计算量。
这类算法我习惯用一个demo数据来验证。比如只有5个用户、8部电影，手动构造评分矩阵，跑一遍推荐逻辑，看看结果是否符合直觉。这一步过关了，再接真实的电影数据集，出问题也容易定位。
3. 系统架构与数据库设计：表结构比算法更先决定成败
3.1 前后端分离的整体架构
这个项目采用前后端分离架构，和传统单体JSP项目最大的区别在于：前端和后端是两个独立部署的应用，通过HTTP接口通信，只是开发时放在同一个仓库里管理。
后端是一套SpringBoot应用，负责提供RESTful API。前端是一套Vue3工程，通过axios调用后端的接口，渲染页面。数据库是MySQL，在Java和MySQL之间用MyBatis作为持久层框架。
为什么要这样做？从开发角度看，前后端分离以后，前端工程师和后端工程师可以并行开发，不用互相等页面和接口。从维护角度看，后端接口可以同时服务Web端、移动端，甚至以后接入第三方系统。从部署角度看，前端打包成静态资源后扔到Nginx里，后端单独跑一个Jar包，扩展和排障都清晰。
当然，分离架构也有代价。最直接的麻烦就是跨域问题。前端页面在端口3000（或80）上运行，后端接口在端口8080上运行，浏览器的同源策略会拦截掉这些跨域请求。后文我会讲跨域怎么配置，这里先记住一件事：开发环境配好CORS，生产环境用Nginx反向代理，把不同路径转发到不同服务，两个都要提前想好，别等上线了再改。
3.2 核心表结构设计与关系梳理
整个系统的核心业务数据就三类：用户、电影、评分。表结构我做了精简设计，实际运行效率不错，这里给出最关键的几张表。
用户表（user）负责存账号和昵称：
CREATE TABLE `user` ( `id` bigint(20) NOT NULL AUTO_INCREMENT, `username` varchar(50) NOT NULL COMMENT '登录名', `password` varchar(100) NOT NULL COMMENT '加密后的密码', `nickname` varchar(50) DEFAULT NULL COMMENT '昵称', `created_at` datetime DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (`id`), UNIQUE KEY `uk_username` (`username`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;电影表（movie）虽然叫“电影推荐”，但字段设计需要考虑推荐功能的扩展性。基本字段是标题、年份、类型、封面图URL、简介。我特别加了一个genre字段，因为后续做冷启动策略时会用到“同类型电影优先推荐”的兜底逻辑：
CREATE TABLE `movie` ( `id` bigint(20) NOT NULL AUTO_INCREMENT, `title` varchar(200) NOT NULL COMMENT '电影名称', `genre` varchar(100) DEFAULT NULL COMMENT '类型，多个用逗号分隔', `release_year` int(11) DEFAULT NULL, `poster_url` varchar(500) DEFAULT NULL COMMENT '海报链接', `description` text, PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;评分表（rating）是整个推荐系统的数据基石。所有协同过滤计算都基于这张表。它的设计要点在于唯一约束：同一个用户对同一部电影只能有一条评分记录。
CREATE TABLE `rating` ( `id` bigint(20) NOT NULL AUTO_INCREMENT, `user_id` bigint(20) NOT NULL, `movie_id` bigint(20) NOT NULL, `score` tinyint(4) NOT NULL COMMENT '评分1-5', `created_at` datetime DEFAULT CURRENT_TIMESTAMP, `updated_at` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`id`), UNIQUE KEY `uk_user_movie` (`user_id`, `movie_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;3.3 用户评分矩阵与MySQL查询的衔接
算法课上讲的评分矩阵，是一张二维表，行是用户，列是电影，交叉点是分数。这是一种数学上的抽象概念。到了MySQL里，我们不可能真的建一张“用户x电影”的二维大表——用户数量和电影数量一多，表体积就会爆炸，而且绝大多数格子都是空的。评分表本质上就是用“稀疏行存”去表达“稠密矩阵”的数学概念。
实际写代码时，我们需要把评分数据从表里查出来，组装成算法能用的Map结构。一个最常用的查询是“查出所有评分记录”：
<select id="selectAllRatings" resultType="map"> SELECT user_id, movie_id, score FROM rating </select>然后在后端Java代码里组装成Map<Long, Map<Long, Double>>，外层key是用户ID，内层key是电影ID，value是分数。这是算法层的标准输入格式。如果数据量很大，比如超过百万级评分，就不能一次全查了，得用分页或流式处理。不过对于教学级和中小规模的电影推荐系统，一次性加载完全没问题，MySQL扛得住。
这套设计还有一个隐形的优势：**新用户注册后，不需要在矩阵里给他预留位置。**他产生评分了，评分表里自然多一行；他没评分，表中就没有数据。稀疏矩阵的存储由关系型数据库天然解决了，我们只需要在算法层处理“评分太少导致相似度算不出来”的冷启动问题。
4. 后端工程实现：SpringBoot与MyBatis的衔接细节
4.1 工程分层与请求处理链路
后端工程我按照经典的分层架构来组织，每个层各司其职，避免几百行代码堆在一个类里。
- Controller层：接收前端请求，做参数校验，调用Service层，返回统一格式的响应。
- Service层：业务逻辑的核心，协同过滤算法的调用也在这层。
- DAO层（Mapper）：用MyBatis接口加XML文件实现SQL操作。
- Entity层：与数据库表对应的实体类。
- DTO/VO层：Controller与前端交互的数据对象，避免把数据库实体直接暴露给前端。
拿“获取电影推荐列表”这个接口举例，整个链路是：前端发起GET请求到/api/recommend/list?userId=1，Controller接收后调用RecommendService，Service先从数据库查用户的历史评分，再调用协同过滤算法组件计算TopN电影ID，最后把电影ID集合传给Mapper查出完整电影信息，封装成VO返回前端。这个链路看似绕，但每一层职责分明，后续要替换算法或者加缓存都方便。
一个很重要的编码习惯是：Controller层不写业务逻辑，Service层不写SQL。我发现有不少初学者图省事，直接在Controller里注入Mapper开始查库。这样写demo没问题，但项目一复杂就完全失控。测试没法写，事务控制没法做，接口复用也基本不可能。分层不是形式主义，而是为了给未来的自己减少麻烦。
4.2 统一响应体与全局异常处理
前后端分离项目，接口的返回格式必须统一，不然前端解析数据会写出一堆if else。我定义了一个Result类，所有接口都返回这个结构：
{ "code": 200, "message": "success", "data": {} }code是业务状态码，200代表成功，非200代表各种异常；message是给前端展示的提示信息；data是真正的业务数据。这样做的好处有两个：一是前端可以用同一套拦截器处理错误，二是后端可以比较规范地处理业务异常。
配合统一响应体的，是SpringBoot的@RestControllerAdvice全局异常处理。比如参数校验失败时抛出业务异常，全局异常处理器捕捉后转换成统一的Result格式返回，而不是让框架默认的异常页直接暴露给用户。尤其是不需要让前端看到完整的堆栈信息，抛给用户一个“系统繁忙，请稍后再试”的message，然后把完整错误记到日志文件里，这才是一个成熟工程该有的表现。
4.3 MyBatis的XML映射与动态SQL
MyBatis在这个系统里承担了所有数据库操作。选择它而不是JPA，原因很简单：推荐系统里有很多多表关联查询和动态条件拼装，MyBatis的XML映射写起来直白、可控，SQL优化也方便。
举个有代表性的例子：推荐结果是一组电影ID，需要用WHERE id IN (...)查询，但IN子句的长度每次不确定。XML里这么写：
<select id="selectMoviesByIds" resultType="com.example.entity.Movie"> SELECT * FROM movie WHERE id IN <foreach collection="ids" item="id" open="(" separator="," close=")"> #{id} </foreach> </select>foreach是MyBatis动态SQL里特别高频的标签。需要注意的是，如果ids集合过大，比如超过1000个，IN子句会很长，可能触发MySQL的SQL解析限制。经验做法是分批查询，每次500个，或者用临时表来替代IN。这个电影推荐系统里TopN一般取10到20个，所以不存在这个问题，但如果有人拿这个系统改成商品推荐，这个坑就要注意了。
另一个关键点是MyBatis的结果映射。数据库字段名通常用下划线风格（user_id），Java属性用驼峰风格（userId），在application.yml里开启驼峰映射可以省掉一大堆手写映射：
mybatis: configuration: map-underscore-to-camel-case: true4.4 开发环境跨域配置
前后端分离项目，跨域是绕不过去的第一道坎。开发阶段最简单的解法是在后端加一个CORS配置类：
@Configuration public class CorsConfig implements WebMvcConfigurer { @Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/api/**") .allowedOriginPatterns("http://localhost:*") .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS") .allowedHeaders("*") .allowCredentials(true) .maxAge(3600); } }我特别强调一下allowedOriginPatterns和allowedOrigins的区别：前者支持通配符，后者在allowCredentials(true)的时候不允许使用*。如果前端地址是http://localhost:3000，后端调试接口时用allowedOrigins("http://localhost:3000")也能行，但代码换到别的端口就又要改。用OriginPatterns配合通配符，一次配好，开发时随便切端口都不怕。
配置完CORS之后，记得让前端开发工具看一眼Network面板，如果预检请求（OPTIONS）返回200，真实请求也正常，那跨域就算是调通了。
4.5 实时计算与缓存优化的取舍
初版系统里，每次请求推荐列表都会实时跑一遍协同过滤计算。这样做逻辑最简单，但性能很差。用户评分稍多一点、电影数量稍多一点，一个推荐接口就要计算好几百次余弦相似度，响应时间轻松超过1秒。
我对这个系统的优化策略是：短周期缓存+定时预热。具体做法是：在Service层加一个本地缓存（ConcurrentHashMap），key是用户ID，value是推荐结果列表，设置5到10分钟的有效期。用户触发推荐请求时，先查缓存，缓存没有再算。同时后台开一个定时任务，每10分钟对活跃用户的推荐结果做一次预热，这样用户真正请求时，大部分命中的是缓存，响应时间能压到100毫秒以内。
本地缓存的缺点是多实例部署时每个实例各自维护一份，存在一致性偏差。但对于中小规模系统，这点偏差完全可接受。如果以后要上多实例，把本地缓存换成Redis，把key设计成recommend:user:{userId}，逻辑几乎不用改。
5. Vue3前端实现：从工程搭建到推荐页渲染
5.1 Vite构建工具与Composition API的组织方式
前端工程我用Vite搭建，Vue版本是3.x。选Vite不选Webpack，最直观的感受就是启动速度快，开发模式下用ES Module原生加载，浏览器直接按需编译，几乎感觉不到等待。
Vue3里最核心的编程范式变化是Composition API。拿推荐页来举例，我会把逻辑按功能拆成几个独立的组合函数（composables），而不是把所有代码堆在一个大组件里。
- useAuth：管理用户登录状态和本地Token存储。
- useRating：管理用户对电影的评分操作，调用后端接口，更新本地列表。
- useRecommend：负责获取推荐列表、处理加载状态和错误提示。
比如useRecommend的核心逻辑：
import { ref } from 'vue' import { getRecommendList } from '@/api/recommend' export function useRecommend(userId) { const list = ref([]) const loading = ref(false) const fetchRecommend = async () => { loading.value = true try { const { data } = await getRecommendList(userId) list.value = data } finally { loading.value = false } } return { list, loading, fetchRecommend } }组件里只需要调用这个函数，拿到返回值后绑定到模板。页面结构清爽，复用性也好。以后要加“猜你喜欢”和“热门推荐”两个Tab，每个Tab都可以复用useRecommend，只要传入不同的接口参数。
5.2 路由与状态管理：Pinia替代Vuex的选择
Vue3项目里状态管理我选的是Pinia，不是Vuex。Pinia是Vue官方团队推荐的新一代状态管理库，API更简洁，去掉了Vuex里那些繁琐的mutations概念。在电影推荐系统里，全局状态主要存两样东西：当前用户信息和用户评分过的电影列表。
为什么评分列表要放全局状态？因为用户可能在推荐页给某部电影打了分，然后跳到“我的评分”页面，两个页面需要共享这份数据。如果每个页面都单独请求接口，不仅浪费请求，还会出现数据不同步的视觉问题。
Pinia里定义一个store：
import { defineStore } from 'pinia' export const useUserStore = defineStore('user', { state: () => ({ userId: null, nickname: '', token: '', ratedMovies: [] }), actions: { setUser(user) { this.userId = user.id this.nickname = user.nickname } } })组件里调用store的时候，注意一个细节：不要直接解构整个store然后又去修改它。Pinia的state是响应式的，但如果你用ES6解构，会丢掉响应性。正确做法是storeToRefs来解构state，或者直接通过store实例去访问和修改。
5.3 推荐结果展示与交互设计
前端推荐结果我用了一个横向滚动的卡片列表来呈现，每个卡片包含电影海报、标题、类型和评分。页面结构看起来类似主流视频网站的推荐区，但实现并没有多复杂，就是flex布局加overflow-x滚动。
用户点击某部电影时，弹出详情浮层，里面展示电影简介，底部放一个1到5星的评分控件。用户提交评分后，前端调用后端POST /api/rating接口，同时更新Pinia里维护的已评分列表。下次刷新推荐页时，由于后端算法参考了新的评分数据，推荐结果就会跟着变化。这个交互闭环很重要，它让用户能直观感受到“我点的每一步都在影响推荐结果”。
前端还有一细节容易被忽略：海报加载失败时的占位图。如果poster_url是外链，可能因为防盗链或网络原因加载失败，一个丑陋的图片破图标非常影响观感。我的做法是给<img>加一个@error事件，失败时替换成本地默认图，再用loading="lazy"做懒加载，首屏性能也能改善。
5.4 接口封装与请求拦截器
前端所有接口调用都要走统一的axios实例，而不是每个组件各自import axios。原因很简单：统一实例可以集中处理Token注入、错误提示、超时配置。
我封装了一个request.js，核心逻辑就是创建axios实例，加上请求拦截器和响应拦截器：
const service = axios.create({ baseURL: '/api', timeout: 10000 }) service.interceptors.request.use(config => { const token = localStorage.getItem('token') if (token) { config.headers['Authorization'] = 'Bearer ' + token } return config }) service.interceptors.response.use( response => { const res = response.data if (res.code !== 200) { ElMessage.error(res.message || '请求出错') return Promise.reject(new Error(res.message)) } return res.data }, error => { ElMessage.error('网络异常，请稍后重试') return Promise.reject(error) } )值得一提的是，baseURL在开发环境直接写http://localhost:8080/api就能通，但到生产环境这样写就尴尬了。生产推荐用Nginx做代理，把/api前缀的请求转发到后端服务，前端打包出来的代码里不需要写任何后端地址。这就是为什么我在axios配置里baseURL只写/api，看起来像相对路径，实际由Nginx统一处理。这套模式在前后端分离项目里非常成熟，建议直接沿用。
6. 协同过滤算法的工程落地：代码实现与性能优化
6.1 物品相似度矩阵的构建与存储
基于物品的协同过滤，工程上的第一步是构建“物品-物品相似度矩阵”。这个矩阵可以在系统启动时从数据库加载所有评分数据，然后一次性计算完成，也可以做成定时任务离线更新。
在我的实现里，相似度矩阵本质上是一个Map<Long, Map<Long, Double>>，外层key是电影ID，内层是一个Map，key是其它电影ID，value是它们的相似度。每一轮计算的核心逻辑如下：
public Map<Long, Map<Long, Double>> computeItemSimilarity() { Map<Long, Map<Long, Double>> similarityMatrix = new HashMap<>(); List<Movie> movies = movieMapper.selectAll(); for (Movie m1 : movies) { Map<Long, Double> simMap = new HashMap<>(); for (Movie m2 : movies) { if (m1.getId().equals(m2.getId())) continue; double similarity = calcPearson(m1.getId(), m2.getId()); if (similarity > 0.01) { simMap.put(m2.getId(), similarity); } } similarityMatrix.put(m1.getId(), simMap); } return similarityMatrix; }这个双重循环看起来很笨拙，但对于几千部电影的量级完全够用。如果电影数量到几万部，双重循环的O(n²)复杂度就有压力了，需要用更高效的方式剪枝——比如只计算同一类型（genre）下电影两两之间的相似度，完全跳过跨类型的组合，计算量能降低一个数量级以上。
6.2 冷启动问题的三种兜底策略
协同过滤有个被反复吐槽的缺陷：新用户没有评分数据，算不出和谁相似；新电影没人评过分，也进不了推荐池。学算法的时候老师会提一嘴“冷启动”，但做工程的人得真正给出解法。我在这套系统里做了三层兜底策略。
第一层，新用户冷启动。如果用户没有评分记录，推荐逻辑直接切换到“热门电影榜”，按平均评分和评分人数综合排序，取TopN返回。虽然这算不上个性化，但至少首页不是空的。
第二层，新电影冷启动。如果某部电影在评分表里一条记录都没有，它在协同过滤里永远不可能被推荐。这时候需要内容特征的兜底：在我的表设计里，每部电影有genre字段，新电影会和同类型里最热门的电影产生关联，作为一种“人工先验相似度”注入相似度矩阵。
第三层，混合策略。如果用户的评分记录很少（比如只有一两部），算出来的相似度矩阵会非常稀疏，推荐结果很可能质量很差。这时我做了个加权融合：协同过滤结果占60%权重，热门榜结果占40%权重，按比例混合后输出。等用户评分变多了，再慢慢调高协同过滤的权重。这种策略业界叫Hybrid Recommendation，实现起来不复杂，效果提升却很明显。
我个人建议，真实项目里永远不要只裸用协同过滤。它是推荐效果的天花板，但不是地板。先用热门兜底，再叠加协同过滤，线上效果才能撑得住。
6.3 SpringBoot定时任务与缓存的结合
为了让推荐结果不拖慢接口响应，我是这样设计定时任务的：系统启动后，SpringBoot的@Scheduled注解方法会每10分钟拉取一次数据库里的最新评分数据，重新计算相似度矩阵，然后把矩阵放到一个单例缓存对象里。用户请求推荐列表时，算法组件只负责“读取缓存矩阵+计算TopN”，整个过程不涉及数据库批量查询。
@Component public class RecommendCacheTask { private final RecommendService recommendService; @Scheduled(fixedDelay = 600000) public void refreshSimilarity() { recommendService.rebuildSimilarityMatrix(); } }这段代码里有个不起眼但非常关键的细节：定时任务里用fixedDelay而不是fixedRate。因为计算相似度矩阵本身可能要跑几秒甚至几十秒，如果用fixedRate，即使上一次任务还没跑完，下一次就到了时间点，可能会并行起多个计算任务，白白消耗CPU和数据库连接。fixedDelay保证上一次执行完再等10分钟才跑下一次，天然避免任务叠加。
6.4 推荐接口的性能压测数据
为了验证这套系统的性能，我用本地环境做了一个简单压测，配置是单机SpringBoot应用+MySQL，数据量模拟了200个用户、500部电影、8000条评分记录。
压测结果给我最直观的感受是：加了矩阵缓存之后，推荐接口的P99响应时间从1600毫秒降到120毫秒左右。之前每次请求都现场计算相似度，相当于把最耗时的部分暴露给了所有用户；现在计算被定时任务吸收，接口只做矩阵查询和TopN排序。这个对比让我更坚定了一个原则：推荐系统里，能离线算的绝不实时算，能缓存结果的就别缓存过程数据。
另外要注意的是，如果推荐结果本身也要缓存，一定要为缓存设置合理的过期时间。一套推荐结果缓存10分钟，和冷启动策略配合起来，用户刚注册时看到的“热门推荐”，在产生第一条评分后的10分钟才会更新，这个时延在真实体验中完全可接受，还能避免数据库被频繁打穿。
7. 数据准备与效果验证：没有数据，算法就是空中楼阁
7.1 造数脚本与人工评分数据的生成
很多同学拿到项目源码后第一件事就是run，一跑发现推荐列表是空的，就开始怀疑代码写错了。其实90%的情况是数据库里没有评分数据，协同过滤自然算不出任何东西。
要让推荐系统“活”起来，必须先给它喂数据。我的做法是写一个造数脚本，往movie表里插入几十部经典电影，再往rating表里批量插入一批模拟评分数据。造数脚本用Java的CommandLineRunner触发，项目启动时自动执行，也可以用SQL文件手动导入。数据格式要有意识地模拟真实行为：比如一部分用户倾向于打高分，一部分用户风格分散，还有几个用户只评了很少的电影，专门用来测试冷启动分支。
生成评分时用随机数是省事，但太“随机”的数据不能体现协同过滤的效果。我建议造数时参考“真实用户打分习惯”：每个用户先随机选5到20部电影，再以某个“口味向量”为基准生成分数。比如给用户A设定偏好方向“科幻片4分起步，爱情片2分封顶”，这样A的评分数据就有明显的风格特征，推荐结果也会更有区分度。
7.2 推荐效果的人工检验方法
推荐系统好不好，不能只看“接口通没通”，还得看“推得准不准”。对于这种教学级项目，我习惯用两个方法检验。
方法一：同用户复核法。选一个评分行为比较丰富的用户，手动查看他的历史评分记录，记住他喜欢的电影类型。然后调用推荐接口，看看推荐结果里有多少部电影和这些类型重合。如果一个用户只看恐怖片，推荐列表却塞满了动画片，那算法肯定出了问题。
方法二：相似度监督法。直接用SQL查数据库，挑出两个明显风格相似的电影，比如《黑客帝国》和《盗梦空间》，看看计算出来的相似度值是否接近于1。如果两部八竿子打不着的电影反而相似度最高，那数据结构组装或者评分读取那一步很可能有bug。
我自己踩过一次很离谱的坑：相似度计算出来全是1.0。排查半天，发现是因为评分表的唯一约束没有建好，同一个user_id和movie_id出现了多条记录，导致矩阵里出现了大量重复键覆盖，最终算出来的结果自然就畸形了。从那以后，我每次造数脚本跑完都会先执行一条去重检查SQL，确认数据干净再测算法。
7.3 用真实公开数据集扩展系统的思路
如果本地造数已经不能满足需求，想拿真实数据测试系统的承受能力，可以找一些公开的电影评分数据集来导入。国内外的公开数据集和MovieLens这类的经典数据集，格式通常是一个CSV文件，列是用户ID、电影ID、评分、时间戳。导入MySQL只需要写一个小工具类，读CSV逐行插入rating表。
需要提前说一句：公开数据集的用户ID是独立的数字编号，和系统里user表的自增主键是两套体系。导入时必须做好映射，可以先把数据集里的用户ID存到user表的一个扩展字段里，再在导入评分时查询映射关系。否则评分数据挂到了错误的用户头上，推荐结果会非常诡异。
还有一个容易被忽视的地方是：真实数据集的评分标准不一定是1到5分。有的是1到10分，有的是浮点数。导入时要根据系统定义的评分范围做归一化处理，否则评分数值超出tinyint的取值区间，MyBatis插入时直接报Data truncation错误。
8. SpringBoot集成细节：事务、分页、日志与安全
8.1 评分写操作的事务控制
电影推荐系统涉及写操作的接口主要是评分接口（用户提交对某部电影的评分）。在动手写代码前，我习惯先想清楚：一个写操作涉及几张表的变更？是否需要和别的业务操作绑定成一个原子操作？
当前这个系统评分接口只操作rating表一张表，事务需求看起来不强。但健康的编码习惯是：凡是涉及写库的操作，一律加上@Transactional注解。理由不是为了防现在，而是为了防以后。等到需求变成“评分后自动更新用户标签表”时，事务边界就十分必要了。不加注解的后果是，第一个操作成功、第二个操作失败，数据库出现半成品数据，排查起来会相当痛苦。
有一点需要特别说明：@Transactional只对RuntimeException和Error触发回滚，受检异常默认不会触发回滚。如果你在事务方法里catch住了异常然后吞掉，Spring感知不到失败，事务照样提交，数据库就会产生脏数据。所以我在评分接口里的写法是：Service层方法不catch异常，让异常向上抛给Controller层，由全局异常处理器统一拦截。这样事务边界清晰，异常处理也统一。
8.2 推荐列表的分页参数与前端联动
前端展示推荐结果时，我用了“加载更多”的分页方式，接口设计接收current和size两个参数。相比传统的页码分页，“加载更多”在C端产品里交互更流畅，用户不用来回跳页。
协同过滤推荐接口的分页有个特殊性：算法先算出一个完整的TopN列表（比如100部电影），然后从里面截取当前页的数据返回。这个“先全量算、再分页取”的方案，和普通业务表的分页完全不一样。普通分页是SQL层面的LIMIT和OFFSET，推荐分页是算法结果层面的切片操作。如果只截取了当前页，而没有保留算法算出的完整列表，用户点“加载更多”时推荐结果会变化，体验很怪。
解决方案是：一次性算出TopN列表，缓存起来（比如缓存100条），前端每次翻页从缓存里切片。这要求接口要么多传一个page参数，要么前端在第一次请求后就拿到全部推荐ID，后续翻页直接用本地数组，不再请求后端。考虑到TopN一般也不大，第二种方案更省事，前端代码更简洁。
8.3 日志记录与推荐效果追踪
我在开发这个系统的过程中，花了很多时间调算法参数，但真正帮上大忙的其实是日志。这里说的日志不是框架自动打印的访问日志，而是业务日志。
比如在推荐Service里，我会输出一条这样的日志：
reckey=recommend:user:1, strategy=item_cf, total=100, filter_out=23, cold_start=true, cost_ms=35意思是：某某用户走了基于物品的协同过滤策略，算法内部候选集总共100部，过滤掉23部用户已看过的，命中了冷启动分支，整个计算耗时35毫秒。这样一条日志的价值非常高。上线之后，如果产品反馈“推荐结果好像不太对”，你不需要靠猜，直接查日志看每个用户走了什么策略、滤掉了什么、耗时多少，问题常常一眼就定位了。
Logback的配置里，我建议把业务日志单独输出到一个文件，和应用日志分开。推荐系统是长期演进的功能，积累的日志数据本身又能反哺后续的算法优化，形成正向循环。
9. 常见问题与排查技巧实录
9.1 表数据乱码与MySQL字符集问题
电影标题里出现中文乱码，是这类系统最常遇到的第一个问题。乱码的根因基本都在MySQL连接参数或数据库字符集设置上。如果你的连接串长这样：
jdbc:mysql://localhost:3306/movie_db?useUnicode=true&characterEncoding=utf8那大概率没有包含serverTimezone参数，而且MySQL 8.x的服务端如果默认字符集不是utf8mb4，那么即使连接参数正确，存进去的数据也可能乱。两个手段一起上：一是建库时显式指定字符集为utf8mb4；二是在SpringBoot配置里把连接URL加上相关参数。utf8mb4和utf8的区别在于后者不能存Emoji字符，推荐系统里用户昵称可能带表情符号，因此直接选utf8mb4，不要再纠结utf8。
9.2 MyBatis报错Invalid bound statement (not found)
这个报错是MyBatis初学者的高发区。意思是说MyBatis在启动时扫描到的Mapper接口和XML文件对不上，找不到接口方法对应的SQL语句。排查顺序我已经形成肌肉记忆了：
- 检查接口方法名和XML里的id是否完全一致，包括参数个数。
- 检查XML文件的namespace是否和Mapper接口的全限定名一致。
- 检查application.yml里mapper-locations配置是否指向了XML所在的目录。
- 检查target目录下是否已经生成XML文件——Maven多模块项目里，XML放在src/main/java目录下时，需要在pom里额外配置resources插件，否则编译后XML不会被打包进去。
这套排查走完，绝大多数情况都能定位。最后一种情况最隐蔽，也最常见，尤其是从别人仓库clone下来的项目，first build时target目录是空的，忘了XML会被过滤掉，一运行就报这个错。
9.3 Vue3响应式丢失导致推荐列表不更新
前端也有一类高频坑：用户提交评分后，推荐列表理论上应该变化，但页面上纹丝不动。排查半天发现，问题出在Vue3的响应式代理上。
Vue3的响应式基于Proxy，它对ref和reactive包裹的对象才有追踪能力。如果在setup里直接用一个普通变量存储推荐列表，然后异步接口返回后直接赋值，页面不会重新渲染，因为Vue根本不知道这个变量变了。正确做法是用ref([])声明列表，赋值时通过.value。
另一个隐蔽的坑是：**用reactive包裹数组，然后用Object.prototype.push之外的方式整个替换数组，响应性可能丢失。**拿reactive({ list: [] })举例，如果你写state.list = newArray，Proxy是可以侦测到的；但如果你在子组件里直接对数组下标赋值，可能不会触发更新。最省心的方法是列表数据一律用ref管理，保证每一步操作都在响应式系统的追踪范围内。
9.4 推荐结果为空或全是一样的热门电影
如果推荐接口能返回数据，但返回的是同一个热门列表，无论切换哪个用户都一样，这说明协同过滤的核心逻辑压根没触发，兜底策略把接口接管了。可能的原因有两个。
一是评分表里确实没有数据，或者当前用户没有评分记录，所以算法层判断“该用户是冷启动用户”，走了热门榜。这种情况是符合预期的，不是bug。二是算法层读取评分数据时有bug，导致矩阵为空，误判成冷启动。排查方法是打印算法层的输入评分数量，对比评分表里的实际数量，看看到底是数据不存在还是读取逻辑出了问题。
我见过一种很搞笑的配置错误：造数脚本里插入了评分数据，但插入后忘了提交事务，MySQL的默认隔离级别下，另一个连接查不到未提交的数据。于是算法层始终读不到评分，永远走热门兜底。后来把事务改成自动提交才解决了。这类”数据和代码都没错”的问题，反而最磨人，排查时一定要考虑事务隔离级别这种底层配置。
9.5 外链海报加载过慢或直接加载失败
推荐结果页如果每张卡片都要请求外部图片服务，页面加载速度会被拖累。我在实际项目里遇到的情况是：部分外链域名存在防盗链机制，浏览器从我们的域名发起图片请求，直接被403拒绝，海报区域一片空白。
解决办法有几个，按推荐排序：后端定时把海报图片下载到本地或对象存储，返回给前端的是我们自己的URL；前端用失败占位图兜底；给img标签加referrerPolicy="no-referrer"，绕过防盗链限制。最好的方案永远是第一种，图片资源本地化，可靠性和加载速度都可控。如果只是想跑通demo，先用默认图兜底，等以后换正式海报资源再一起处理。
10. 项目扩展方向：从电影推荐延伸到通用推荐能力
电影推荐系统做完以后，最大的价值已经不是“推荐电影”本身，而是这套“数据采集-算法计算-结果缓存-API输出”的链路可以迁移到非常多业务场景。我在考虑扩展时，优先想的是下面几个方向。
第一，给系统增加内容推荐能力。目前协同过滤只依赖评分数据，但电影本身有标题、类型、简介文本。如果引入文本相似度，把标签和描述向量化，就能让新电影也有推荐机会。最简单做法是用中文分词工具抽取关键词，构建标签向量，然后计算余弦相似度。这一步能有效缓解协同过滤对新物品的冷启动问题。
第二，接入更多的隐式反馈数据。评分是显式反馈，用户必须主动操作才有数据；但真实的用户行为更多是隐式反馈，比如浏览详情页、收藏、点击、停留时长。这些行为可以转换成分数，比如点击加1分，收藏加3分，完整看完加2分。一旦把隐式反馈纳入评分体系，推荐算法的数据量会大一个量级，效果也会更细腻。
第三，把推荐结果做成可解释的。现在的接口只返回电影列表，用户不知道为什么推荐《星际穿越》。如果加一个reason字段，告诉用户“因为你给《盗梦空间》打了5分，所以推荐了这部”，推荐的可信度会大幅提升。实现起来也不难：算法在计算预测评分时，记录贡献最大的邻居评分，把对应的电影作为解释依据返回给前端即可。这是性价比极高且用户体验提升明显的一个扩展。
我对这个项目的定位是“麻雀虽小，五脏俱全”。从工程的角度看，它把前后端分离、数据库设计、算法落地、缓存策略、异常处理这些常规技能都串起来了；从算法的角度看，它把协同过滤从理论公式变成了可运行、可验证、可调优的真实功能。实际运行下来，我对它的预期是它能成为以后接更多业务推荐需求的起点。
