简介：这份面向Java Web与机器学习初学者的图书推荐系统项目源码，围绕个性化图书推荐场景，解决图书管理、读书会组织及分类推荐等需求，适合课程设计、毕业设计或协同过滤入门实践。项目后端采用SpringMVC框架，前端以HTML、CSS和JSP页面实现，推荐环节使用协同过滤算法：先提取图书特征，再依据用户点击行为记录偏好，计算目标图书与候选图书间的距离，并将最近邻结果推送给读者；功能覆盖科技、人文、历史、中小学及其他图书分类。压缩包为rar格式，共172个文件、约17MB，包含25个java源文件、58个class编译文件、32个jsp页面、12个jar依赖、8个xml配置、1个sql数据库脚本，以及jpg/png界面素材和docx说明文档，便于还原项目结构与部署运行。已有259人学习，适合希望理解推荐流程并完成可运行系统的读者参考。
1. 一个图书推荐项目接手的真实处境
上个月帮朋友看一个图书推荐系统的源码，登录后台发现首页推荐位置显示的却是「按借阅量倒序」，运营反馈说那个位置点击率还不如旁边的分类导航。项目本身不复杂：Java 后端加一套机器学习训练任务，关键词就是机器学习、图书推荐，思路也不新鲜，协同过滤加内容相似度混合召回。但真正跑起来才发现，卡住人的从来不是 ALS 那一行fit()，而是评分矩阵怎么构造、冷启动怎么保底处理、模型训完怎么让在线服务用上、推荐结果怎么过滤已读。这套完整源码适合两类人：一类是刚学完协同过滤，想找个能跑通的工程练手；另一类是手里有图书或内容类业务，想参考一套推荐链路回去改。
2. 架构与技术选型：Java 后端和离线训练怎么分工
先把整体结构讲清楚，不然读代码会很费劲。这个项目走的是最经典的「离线训练 + 在线服务」两条腿：离线负责把用户行为聚合成评分矩阵、训练模型、导出因子文件；在线只做一件事——拿到用户向量，对候选书打分排序，再经过一层业务过滤返回。两边靠文件解耦，不共享进程，也不共享 JVM。
2.1 技术栈清单与各层职责
后端是 Spring Boot 2.7 + MyBatis-Plus + MySQL 8 + Redis 6，标准的 CRUD 组合，负责图书管理、用户行为上报、推荐接口对外暴露。离线训练用 Spark 3.3 的 MLlib ALS，用 Java API 写，不用 Scala 也不用 Python，主要是为了让整个工程一个mvn package就能出全部产物，部署时不用再维护第二套运行时。模型不落数据库也不起模型服务，直接导出成 CSV 文本，在线侧用纯 JDK 读进内存。
这个选择有取舍。用 Python 起一个 Flask 模型服务看起来更「机器学习」，但实际多了一层 HTTP 序列化、多了一套依赖环境、多了个要监控的进程，中小团队维护起来很吃亏——我见过一个项目因为 Python 环境和训练时的 sklearn 版本对不上，线上打分全是 NaN，排查了两天才定位。用 Mahout 倒是纯 Java，但那条线基本没人维护了，文档也停在老版本。Spark + 文件解耦是折中方案里最省心的。
提示：如果你的行为数据量在千万级以下，ALS 完全可以在单机
local[4]上跑完，不必上集群，省掉一整套调度和权限配置。
2.2 目录结构：六个 Maven 模块各管什么
工程是标准的 Maven 多模块，依赖方向单向：web → service → dao → common，trainer只依赖common，不反向依赖业务模块。这样打包出来的 web 包里不会混进 Spark 的任何 jar，这一点后面排查章节还会专门说。
book-rec/ ├── pom.xml # 父 POM，统一管理 Spark / Spring 版本 ├── rec-common/ # DTO、枚举、常量、日期工具 ├── rec-dao/ # 实体类 + MyBatis Mapper 接口 + XML ├── rec-service/ # 推荐服务、缓存、混合排序、过滤规则 ├── rec-web/ # 启动类、Controller、全局异常处理 ├── rec-trainer/ # Spark ALS 训练 + 因子导出，独立可执行 └── sql/ ├── schema.sql # 建表语句 └── data.sql # 少量演示数据rec-trainer打成 fat jar，用spark-submit提交，也可以本地java -jar直接跑单机模式。rec-web打成可执行 jar，java -jar rec-web.jar起来。两个产物互不干扰，升级模型不需要重启 web 服务。
2.3 一次推荐请求的完整链路
搞清楚调用顺序，后面看代码就不会迷路。用户在首页触发一次推荐，链路是这样的：
- Controller 收到
GET /api/rec/home?userId=1001&size=10，做参数校验； - 先查 Redis 的
rec:user:1001，命中直接返回，这一层能挡掉八成以上流量； - 未命中就去
rec_result表取该用户最近一批离线算好的结果，批次号在batch_no字段里； - 表里也没有（新用户或者刚清过缓存），走实时计算：从内存里的用户因子表取向量，生成候选集，逐本打分，混合排序，业务过滤；
- 结果回写 Redis，TTL 设 6 小时，同时异步落一条曝光日志，给后续训练用。
关键点在第四步的候选集。如果直接拿全部图书做全量打分，10 万本书 × 50 维，单次大概几十毫秒，看着还行，但并发一上来 CPU 就直接被打满。所以项目里先按「用户近 90 天有行为的类目」圈出 500 本候选，再在这 500 本里打分，耗时就降到了个位数毫秒。这是一个非常朴素但很有效的优化，很多教程里不写。
3. 数据层拆解：三张主表撑起整个推荐
推荐系统的上限由数据决定，模型只是把这个上限逼近。这个项目的表设计不算复杂，但每一张都有明确的用途，尤其是行为表，字段设计直接决定了评分矩阵的质量。
3.1 核心表结构与索引设计
book表是物品侧，除了基本信息，有两个字段是专为推荐准备的：tags用于内容召回，hot_score是离线每天算一次的热度分，给冷启动兜底用。
CREATE TABLE book ( id BIGINT PRIMARY KEY AUTO_INCREMENT, title VARCHAR(200) NOT NULL, author VARCHAR(100), category VARCHAR(50), tags VARCHAR(500) COMMENT '逗号分隔标签，供内容召回使用', publish_year INT, avg_rating DECIMAL(3,2) DEFAULT 0, rating_count INT DEFAULT 0, hot_score DOUBLE DEFAULT 0 COMMENT '近30天加权行为分，离线每日刷新', KEY idx_category_hot (category, hot_score), KEY idx_hot (hot_score) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;user_behavior表是行为侧，用一张宽表把所有行为类型收进来，靠behavior_type区分，好处是埋点只写一处，聚合时一次扫描就够。
CREATE TABLE user_behavior ( id BIGINT PRIMARY KEY AUTO_INCREMENT, user_id BIGINT NOT NULL, book_id BIGINT NOT NULL, behavior_type TINYINT NOT NULL COMMENT '1浏览 2收藏 3加书架 4借阅/购买 5评分', rating TINYINT DEFAULT NULL COMMENT '仅 type=5 有效，取值 1-5', stay_seconds INT DEFAULT 0 COMMENT '详情页停留秒数，仅 type=1 有效', created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, KEY idx_user_time (user_id, created_at), KEY idx_book (book_id) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;索引这块踩过坑：一开始只在user_id上建了索引，结果离线聚合时按时间范围过滤，扫了全表。后来改成(user_id, created_at)联合索引，聚合任务从 40 秒降到 3 秒。idx_book是给「某本书的相似用户」这类查询用的，item-based 召回离不开它。
注意：
behavior_type用数字而不是字符串存，聚合时少一次字符串比较，几百万行数据下差别很明显。
3.2 从行为日志到评分矩阵
ALS 需要的是(user_id, book_id, score)三元组，而原始数据是行为流水。中间这一步加权聚合，是效果差异最大的地方，比调 rank 参数重要得多。
加权规则用的是下面这张表，不同类型的信号强度不一样，停留时间也参与计算：
| behavior_type | 含义 | 权重 | 说明 |
|---|---|---|---|
| 1 | 浏览详情页 | 0.3 | 乘以停留时间系数，60 秒封顶 |
| 2 | 收藏 | 1.0 | 明确的兴趣信号 |
| 3 | 加入书架 | 1.5 | 比收藏更强 |
| 4 | 借阅/购买 | 3.0 | 最强隐式信号 |
| 5 | 显式评分 | 直接取 rating | 与隐式分相加后截断到 5 |
聚合 SQL 如下，核心是把同一用户对同一本书的所有行为累加，再用LEAST截断到 5 分，保持和显式评分同一量纲：
-- 生成训练用的评分矩阵，输出 user_id,book_id,score SELECT user_id, book_id, LEAST(5.0, SUM(CASE behavior_type WHEN 1 THEN 0.3 * LEAST(1.0, stay_seconds / 60.0) WHEN 2 THEN 1.0 WHEN 3 THEN 1.5 WHEN 4 THEN 3.0 ELSE 0 END) + MAX(COALESCE(rating, 0)) ) AS score FROM user_behavior WHERE created_at > DATE_SUB(NOW(), INTERVAL 180 DAY) GROUP BY user_id, book_id HAVING score > 0;stay_seconds / 60.0这里必须写60.0而不是60，MySQL 里整数除整数会截断，写错的话所有浏览行为的系数都变成 0，模型就只剩收藏和购买信号，召回覆盖面立刻窄一半。这个错我调过一次，找了半天才发现是除法类型的问题。时间窗口取 180 天是经验值，太长会把用户几年前的兴趣也算进来，太短则矩阵过于稀疏。
聚合完还要做两步清洗：过滤掉行为数少于 5 条的用户，以及被行为数少于 5 次的图书。前者是因为 ALS 对这类用户的向量拟合不出来，训了也是噪声；后者是因为长尾书的因子几乎是随机初始化值，推荐出去大概率是错的。
3.3 冷启动与数据质量保底
新用户没有行为，任何协同过滤都无能为力。项目里的策略是分两层：第一层给「热度榜 + 类目打散」，取hot_score前 100 本，按类目限制每类最多 3 本，保证首页不全是同一个品类的书；第二层是在前端放一个「选 3 个感兴趣的标签」的引导，用户选完立刻写一条伪行为，下次请求就能走进内容召回通道。
新书是另一回事。ALS 对没出现过的 item 没有因子，永远排不上来，这就是所谓的「新书黑洞」。解决办法是保留一路内容召回：用tags和author做匹配，占最终结果的 10% 到 15%，相当于给新书一个探索位。比例不能再高，否则推荐准确度掉得厉害。
4. 推荐核心实现：ALS 训练、在线召回与混合排序
这一章是项目的重点。训练、导出、加载、打分、排序、缓存，六步走完才算一条完整的推荐链路。
4.1 离线训练：Spark MLlib ALS 的参数怎么定
训练入口在rec-trainer模块，主类AlsTrainer，接受命令行参数，方便不同环境跑不同配置。
// rec-trainer/src/main/java/com/example/rec/trainer/AlsTrainer.java public static void main(String[] args) throws Exception { // 1. 解析命令行参数，默认值按中小型图书站的量级给 String input = getArg(args, "--input", "/data/rec/behavior.csv"); String output = getArg(args, "--output", "/data/rec/model"); int rank = Integer.parseInt(getArg(args, "--rank", "50")); int iter = Integer.parseInt(getArg(args, "--iter", "10")); double lambda = Double.parseDouble(getArg(args, "--lambda", "0.05")); SparkSession spark = SparkSession.builder() .appName("book-als-trainer") .config("spark.sql.shuffle.partitions", "16") // 一般设成核数的 2~3 倍 .getOrCreate(); // 2. 读 CSV：user_id,book_id,score，score 已由 3.2 的 SQL 聚合好 StructType schema = new StructType(new StructField[]{ new StructField("user_id", DataTypes.LongType, false, Metadata.empty()), new StructField("book_id", DataTypes.LongType, false, Metadata.empty()), new StructField("score", DataTypes.DoubleType, false, Metadata.empty()) }); Dataset<Row> ratings = spark.read().schema(schema).csv(input).cache(); // 3. 训练：隐式反馈模式，alpha 控制置信度放大的幅度 ALS als = new ALS() .setUserCol("user_id") .setItemCol("book_id") .setRatingCol("score") .setRank(rank) .setMaxIter(iter) .setRegParam(lambda) .setImplicitPrefs(true) .setAlpha(40.0) .setNonnegative(true) .setColdStartStrategy("drop"); ALSModel model = als.fit(ratings); // 4. 导出因子，供在线服务用纯 JDK 读取 exportFactors(model.userFactors(), output + "/user_factors_csv"); exportFactors(model.itemFactors(), output + "/item_factors_csv"); spark.stop(); }这段代码有几个地方值得说。setImplicitPrefs(true)表示按隐式反馈处理，此时rating不是「打了几分」，而是「对这个物品的偏好强度」，内部会转成置信度权重，这也是为什么前面把行为加权到 5 分制——量纲统一后alpha才好调。setColdStartStrategy("drop")必须加，不加的话transform遇到训练集里没出现的用户会返回 NaN，一路传到线上就是推荐分数全是 NaN，前端接口直接空白。setNonnegative(true)让因子非负，可解释性好一些，也避免了部分维度相互抵消。
参数的具体取值参考这张表：
| 参数 | 默认值 | 作用 | 调整建议 |
|---|---|---|---|
| rank | 50 | 隐向量维度 | 图书 5 万本以内 30~60 够用，超过 100 内存翻倍且收益递减 |
| iter | 10 | 迭代轮数 | 看 loss 曲线，一般 10~15 就收敛 |
| lambda | 0.05 | 正则项系数 | 太小推荐同质化严重，太大结果退化成热门榜 |
| alpha | 40 | 置信度放大系数 | 行为越稀疏取值越大，常见 4~40 |
lambda这个值值得多说一句。默认的 0.01 我试过，训出来的结果千人一面，因为正则太弱导致模型过度拟合了少数几个高频用户的行为模式。调到 0.05 之后再调到 0.1，最终 0.05 在覆盖率和准确率之间平衡最好。这种参数没有通用答案，只能拿自己业务的留出集跑指标。
4.2 因子导出与在线加载
Spark 输出的 Parquet 文件在线侧读起来很麻烦，得引parquet-hadoop，还会带进一堆 Hadoop 依赖。所以训练完多做一步，把因子转成 CSV 文本，在线侧只用java.nio.file.Files就能读。
// 把 userFactors / itemFactors 展平成 "id,f0,f1,...,fN" 一行一条 private static void exportFactors(Dataset<Row> df, String path) { df.toJavaRDD() .map((Function<Row, String>) r -> { List<Float> vec = r.getList(1); // 第二列是 Vector StringBuilder sb = new StringBuilder(String.valueOf(r.getLong(0))); for (Float f : vec) sb.append(',').append(f); return sb.toString(); }) .saveAsTextFile(path); // 输出目录，内含 part-00000 等文件 }saveAsTextFile输出的是目录不是单文件，里面按分区生成part-00000、part-00001……在线加载时要把目录下所有part-*都读进来，只读第一个文件会丢数据——这个坑很隐蔽，因为本地local[1]跑的时候只有一个 part 文件，看起来一切正常，一上多核就少一半书。
在线侧的加载器长这样，把全部因子读进一个HashMap：
// rec-service/src/main/java/com/example/rec/service/FactorStore.java public void load(Path dir) throws IOException { Map<Long, float[]> map = new HashMap<>(1 << 18); try (DirectoryStream<Path> ds = Files.newDirectoryStream(dir, "part-*")) { for (Path p : ds) { try (Stream<String> lines = Files.lines(p, StandardCharsets.UTF_8)) { lines.forEach(line -> { String[] parts = line.split(","); float[] vec = new float[parts.length - 1]; for (int i = 1; i < parts.length; i++) { vec[i - 1] = Float.parseFloat(parts[i]); } map.put(Long.parseLong(parts[0]), vec); }); } } } this.factors = map; // 全量放堆内，10 万本 × 50 维约 20MB }内存占用算一下：10 万本书 × 50 维 × 4 字节 = 20MB，用户侧十万级也才几十 MB，全放堆内完全撑得住。如果物品量到千万级，就得换成 Redis 或者堆外内存了。加载时机放在 Spring 的ApplicationRunner里，启动时读一次，之后靠定时任务每天凌晨重新加载新模型。
4.3 在线召回与混合排序
召回决定候选集，排序决定最终顺序，两件事分开做。候选集生成用一条 SQL，圈出用户近期感兴趣类目下的热门书：
-- 取用户近 90 天行为最多的 3 个类目，各取类目内热门书，合并成候选池 SELECT b.id FROM book b JOIN ( SELECT b2.category, COUNT(*) AS cnt FROM user_behavior ub JOIN book b2 ON b2.id = ub.book_id WHERE ub.user_id = #{userId} AND ub.created_at > DATE_SUB(NOW(), INTERVAL 90 DAY) GROUP BY b2.category ORDER BY cnt DESC LIMIT 3 ) c ON c.category = b.category WHERE b.rating_count > 50 ORDER BY b.hot_score DESC LIMIT 500;b.rating_count > 50这个限制相当于给候选池设了最低质量要求，把那些只有两三条行为的书过滤掉，避免推荐出来全是没人看过的冷门。LIMIT 500是经验值，太小召回不够，太大打分耗时上去了。
拿到候选集后，逐本和用户向量做点积，再和内容相似度、热度分加权融合：
public List<RecItem> recommend(long userId, int size) { float[] userVec = factorStore.getUser(userId); if (userVec == null) return fallbackPopular(size); // 冷启动兜底 Set<Long> candidates = candidateService.build(userId, 500); List<ScoredBook> scored = new ArrayList<>(candidates.size()); for (Long bookId : candidates) { float[] itemVec = factorStore.getItem(bookId); if (itemVec == null) continue; double cf = 0d; for (int i = 0; i < userVec.length; i++) cf += userVec[i] * itemVec[i]; double content = contentService.similarity(userId, bookId); // 标签/作者重合度 0~1 double hot = hotService.normalize(bookId); // 热度归一到 0~1 // 三路融合，权重是离线 A/B 调出来的 scored.add(new ScoredBook(bookId, 0.6 * normalizeCf(cf) + 0.25 * content + 0.15 * hot)); } scored.sort(Comparator.comparingDouble(ScoredBook::getScore).reversed()); // 业务过滤：已读、已收藏的踢掉；同作者最多 2 本，同分类最多 4 本 return diversify(scored, size, 2, 4); }权重0.6 / 0.25 / 0.15不是拍脑袋定的，是拿一周的线上曝光日志做离线回放调出来的。纯协同过滤的权重给到 0.8 时，推荐准确率上去了，但推荐内容集中在几个畅销书系列，用户投诉「怎么老是这几本」。加了内容相似度和热度之后，热度分起到探索作用，多样性指标好转，点击率反而没掉。diversify里的同作者、同分类上限就是解决这个问题的，参数可以按业务调。
提示：
normalizeCf做的事是把点积结果按当前候选集的最大最小值归一化到 0~1，否则协同过滤分和内容相似度分不在一个量纲上，加权没有意义。这一步很多人会漏。
4.4 本地跑通：造数、训练、接口验证
理论讲完，落到怎么跑。整个流程四步，每步都有明确的输入输出。
第一步，建库建表并造一批演示数据。sql/目录下有两个脚本，data.sql里带了 800 个用户、3000 本书和约 10 万条行为，够把模型训出个样子：
# 1. 建库建表 + 灌演示数据 mysql -uroot -p -e "CREATE DATABASE book_rec DEFAULT CHARSET utf8mb4;" mysql -uroot -p book_rec < sql/schema.sql mysql -uroot -p book_rec < sql/data.sql # 2. 导出评分矩阵（也可以写成定时任务，这里手动跑一次） mysql -uroot -p book_rec -N -e " SELECT user_id, book_id, LEAST(5.0, SUM(CASE behavior_type WHEN 1 THEN 0.3 * LEAST(1.0, stay_seconds / 60.0) WHEN 2 THEN 1.0 WHEN 3 THEN 1.5 WHEN 4 THEN 3.0 ELSE 0 END) + MAX(COALESCE(rating,0))) AS score FROM user_behavior WHERE created_at > DATE_SUB(NOW(), INTERVAL 180 DAY) GROUP BY user_id, book_id HAVING score > 0 " | tr '\t' ',' > /data/rec/behavior.csv第二步，提交训练任务。本地开发直接用local[4]，不用起集群：
# 3. 训练并导出因子 spark-submit \ --class com.example.rec.trainer.AlsTrainer \ --master "local[4]" \ --driver-memory 4g \ rec-trainer/target/rec-trainer-1.0.jar \ --input /data/rec/behavior.csv \ --output /data/rec/model/20240520 \ --rank 50 --iter 10 --lambda 0.05跑完之后/data/rec/model/20240520/user_factors_csv/和item_factors_csv/两个目录下应该有一批part-*文件，行数分别接近用户数和图书数。行数对不上就说明前面的清洗逻辑有问题，先别急着启动 web。
第三步，改配置文件里的模型路径，启动服务：
# 4. 启动 web，验证接口 java -jar rec-web/target/rec-web-1.0.jar \ --rec.model.path=/data/rec/model/20240520 curl "http://localhost:8080/api/rec/home?userId=1001&size=10"返回的 JSON 里每条带bookId、score、recType三个字段，recType标出来源是CF、CONTENT还是HOT，方便排查是哪一路召回贡献的。第一版跑通之后，建议拿同一个 userId 连请求两次，第二次应该命中 Redis，响应时间从几十毫秒掉到 2 毫秒以内，能用这个现象确认缓存链路是通的。
5. 常见问题排查：五个卡死推荐链路的坑
这套东西跑通不难，难的是跑通之后结果不对。下面五条是我在这类项目里反复遇到的，每条都按「现象 → 原因 → 解决」写，照着对一遍能省很多时间。
5.1 训练链路上的三个坑
第一个：推荐分数全是 NaN，前端一片空白。
现象是接口返回 200，但data数组里所有score都是null，或者干脆是空数组。原因基本只有一个——ALSModel.transform碰到训练集里没出现过的用户，返回的预测值是 NaN，而这个 NaN 一路透传到 Java 侧的点积计算里，整条结果全被污染。解决分两步：训练时加上setColdStartStrategy("drop")，让 Spark 直接丢掉这些行；在线侧再加一层防御，factorStore.getUser(userId)返回 null 时直接走fallbackPopular，不要让 null 进到计算里。两处都做才算稳妥，只做一处总会漏。
第二个：所有用户拿到的推荐一模一样。
现象是换十个 userId 请求，返回的 top10 重合度超过 80%。原因通常是训练数据被污染，比如测试账号和爬虫产生了大量集中行为，把整体分布拉偏了；或者是lambda设得太小，模型退化成只推荐那几个被行为最多的书。解决往三个方向查：先看评分矩阵里行为数前 10 的用户占了多少比例，超过 30% 就要清洗；再看lambda是不是还停在 0.01；最后确认setImplicitPrefs有没有和显式评分模式混用。我一般会先跑一个itemFactors的余弦相似度分布，如果任意两本书的相似度都在 0.9 以上，那基本就是正则太弱了。
第三个：web 服务启动报NoSuchMethodError，指向 Guava。
现象是rec-web打包后启动直接崩，堆栈里是com.google.common.collect.ImmutableList.xxx找不到方法。原因是rec-trainer的 Spark 依赖被传递进了rec-web，Spark 自带的 Guava 版本比 Spring Boot 管理的老得多，类加载时用了旧版。解决办法是在父 POM 里把spark-core和spark-sql的 scope 全部设成provided，并且确认rec-trainer的依赖没有被rec-web反向引用。这也是为什么 4.2 里坚持把因子导成 CSV 而不是让在线服务直接读 Parquet——只要在线侧不碰 Spark 的类，这类冲突就不可能发生。
5.2 在线服务上的两个坑
第四个：推荐接口偶发超时，P99 冲到 2 秒以上。
现象是压测时大部分请求 30ms 以内，但每隔几十个请求就有一个卡到 2 秒。原因有两个常见来源：一是候选集 SQL 没走索引，user_behavior表数据量一大，GROUP BY category就退化成全表扫；二是推荐结果没进缓存，每次请求都重新打分 500 本书。解决是把候选集查询的联合索引补上（3.1 里那个idx_user_time），并且在服务启动时对活跃用户做一次批量预热，把rec:user:{id}提前写进 Redis。预热脚本按最近 7 天有行为的用户跑，一般能覆盖八成流量，剩下的走实时计算也不至于打爆。
第五个：推荐里出现用户刚借过的书。
现象很尴尬，用户点开推荐位第一本就是他昨天刚借的。原因通常是过滤集合只查了rating表，没把user_behavior里 type=4 的记录合并进来；或者是行为上报后没有删缓存，用户看到的是 6 小时前的旧结果。解决是把已读集合统一成一个ReadSetService，内部合并评分表和行为表两路数据，任何一路更新都调一次redis.del("rec:user:" + userId)。删缓存这一步别嫌麻烦，推荐系统里「推荐已读」是最容易被用户察觉的错误，比推荐不准的伤害大得多。
6. 二次开发的改造思路：从能跑到跑得好
源码跑通只是起点，真正落地都要改。按投入产出比排，我建议的改造顺序是：先补内容召回，再做离线评估，最后上 A/B。
6.1 加一路内容召回，解决新书和新用户
ALS 的死穴是冷启动，最直接的补法是用图书的tags、author、category做一路独立的召回，和协同过滤并行，最后在融合层按权重合并。实现上不用引向量库，用倒排索引就够：
// 按标签建倒排：tag -> bookId 列表，启动时从 book 表加载一次 public List<Long> recallByTags(long userId, int limit) { Set<String> userTags = profileService.topTags(userId, 5); // 用户偏好标签 top5 Map<Long, Integer> hit = new HashMap<>(); for (String tag : userTags) { for (Long bookId : invertedIndex.getOrDefault(tag, Collections.emptyList())) { hit.merge(bookId, 1, Integer::sum); // 命中标签数作为相关性粗排 } } return hit.entrySet().stream() .sorted(Map.Entry.<Long, Integer>comparingByValue().reversed()) .limit(limit).map(Map.Entry::getKey).collect(Collectors.toList()); }这段逻辑的关键在topTags，它决定了召回的方向。简单做法是按用户历史行为里出现过的标签做词频统计，复杂一点可以按时间衰减加权——最近读的书权重高。hit里累加的是命中标签数，用作粗排分，最后和协同过滤分一起进融合层。
6.2 离线评估：先证明改动能变好，再上线
没有评估就别谈优化。用留一法构造测试集：每个用户最近一条行为作为测试样本，其余作为训练集，算 HitRate@10 和 NDCG@10。这个脚本不用起服务，直接读因子文件算就行，跑一次几分钟，比上线看数据快得多。
| 指标 | 含义 | 参考基线 |
|---|---|---|
| HitRate@10 | 测试书是否出现在 top10 | 0.18 左右算正常 |
| NDCG@10 | 考虑位置的排序质量 | 0.12 以上可以接受 |
| Coverage | 推荐结果覆盖的图书占比 | 低于 15% 说明同质化严重 |
改完任何一路召回或权重，都先跑一遍这三个指标。我吃过亏：有次把内容召回权重从 0.25 提到 0.4，线上点击率涨了两个点，但覆盖率掉了一半，两周后用户留存反而下降。指标之间是会打架的，单看一个必翻车。
从那以后我每次交接推荐类项目，都会先把因子文件行数、在线加载日志、缓存命中率这三样东西对着看一遍，确认链路真的通了，再去谈参数和模型。希望帮到你。
本文还有配套的精品资源，点击获取
