refactor: 复习耗时聚合改为强类型结果并补充数据访问规范

This commit is contained in:
2026-10-09 11:53:41 +08:00
parent 3b33cd8396
commit 67c8711eee
7 changed files with 139 additions and 55 deletions
+9
View File
@@ -173,5 +173,14 @@ mvn spring-boot:run # 启动(默认 profile: local)
## 编码规范 ## 编码规范
### 数据访问层 ### 数据访问层
- **优先使用纯 MyBatis-Plus Java API**(`Wrappers.<T>lambdaQuery()`、`selectList`、`selectById` 等),避免手写 XML SQL - **优先使用纯 MyBatis-Plus Java API**(`Wrappers.<T>lambdaQuery()`、`selectList`、`selectById` 等),避免手写 XML SQL
- 复杂查询通过 `Wrappers` 链式构建条件,必要时使用 `.apply()` 拼接原生 SQL 片段 - 复杂查询通过 `Wrappers` 链式构建条件,必要时使用 `.apply()` 拼接原生 SQL 片段
- **查询结果一律用类承载,禁止 `selectMaps` + 字符串 key 取值**
- MyBatis 对 Map 结果直接用 JDBC 列名作 key,不做属性映射:`map-underscore-to-camel-case` 与「属性名大小写不敏感」只对类结果生效。而数据库的标识符大小写规则各不相同(MySQL 保留别名、H2/PostgreSQL 转小写、Oracle 转大写),`row.get("taskNum")` 会在部分库上静默取到 null,表现为「数据莫名变 0」而不是报错
- 单列聚合用 `selectObjs`,多列聚合用下面的自定义 Mapper 方法
- **`Wrapper` 表达不了的查询(`SUM`/`GROUP BY`/多表 `JOIN`)收敛到 Mapper 层**,用自定义方法 + **显式结果类**(`dto/` 下的类或实体),参考 `ReviewRecallRecordMapper.sumReviewDurationByTask` → `dto/TaskReviewDuration` + `resources/mapper/ReviewRecallRecordMapper.xml`
- 结果映射优先写显式 `<resultMap>`(`property` ↔ `column` 一一对应),不依赖 `map-underscore-to-camel-case` 的默认值,也不依赖列名大小写
- **自定义 SQL 不会被 `@TableLogic` 自动追加逻辑删除条件**,必须显式写 `deleted = 0`;租户条件 `created_by = ?` 仍由 `TenantLineInnerInterceptor` 自动追加
- 上述两条不能只靠 mock 单测,需落库集成测试守住(参考 `ReviewDurationIntegrationTest`)
- 反向约束:`Wrapper` 能表达的查询不要为「类型安全」提前下沉为自定义 SQL;确实要下沉时,SQL 只留在 Mapper 层,不要在 service 里拼字符串
@@ -0,0 +1,16 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
/**
* 任务维度的复习耗时聚合结果(复习-07)。
* <p>由 Mapper 层的聚合查询直接映射,避免用 Map 承载查询结果。</p>
*/
@Data
public class TaskReviewDuration {
private String taskNum;
/** 该任务累计复习耗时(秒) */
private Long reviewDurationSeconds;
}
@@ -1,9 +1,24 @@
package com.guo.learningprogresstracker.mapper; package com.guo.learningprogresstracker.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.guo.learningprogresstracker.dto.TaskReviewDuration;
import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity; import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity;
import org.apache.ibatis.annotations.Mapper; import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;
import java.util.Collection;
import java.util.List;
@Mapper @Mapper
public interface ReviewRecallRecordMapper extends BaseMapper<ReviewRecallRecordEntity> { public interface ReviewRecallRecordMapper extends BaseMapper<ReviewRecallRecordEntity> {
/**
* 按任务汇总复习耗时(秒,复习-07)。
* <p>Wrapper 无法表达 SUM + GROUP BY,因此放在 Mapper 层用自定义 SQL + 显式结果类;
* 语句见 {@code resources/mapper/ReviewRecallRecordMapper.xml}(逻辑删除条件已显式写出,
* 租户条件由拦截器自动追加)。</p>
*
* @param taskNums 需要汇总的任务编号;为空时返回空列表
*/
List<TaskReviewDuration> sumReviewDurationByTask(@Param("taskNums") Collection<String> taskNums);
} }
@@ -3,6 +3,7 @@ package com.guo.learningprogresstracker.service.impl;
import com.baomidou.mybatisplus.core.toolkit.Wrappers; import com.baomidou.mybatisplus.core.toolkit.Wrappers;
import com.guo.learningprogresstracker.dto.ReviewFeedItem; import com.guo.learningprogresstracker.dto.ReviewFeedItem;
import com.guo.learningprogresstracker.dto.ReviewTaskStats; import com.guo.learningprogresstracker.dto.ReviewTaskStats;
import com.guo.learningprogresstracker.dto.TaskReviewDuration;
import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity; import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity;
import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity; import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
import com.guo.learningprogresstracker.entity.StudyReportsEntity; import com.guo.learningprogresstracker.entity.StudyReportsEntity;
@@ -382,43 +383,19 @@ public class ReviewServiceImpl implements ReviewService {
} }
/** /**
* 按任务汇总复习行为累计耗时(复习-07)。在 SQL 侧聚合,只把任务数量的行拉回内存, * 按任务汇总复习行为累计耗时(复习-07)。聚合在 SQL 侧完成,只把任务数量的行拉回内存,
* 不随回忆记录条数增长。 * 不随回忆记录条数增长;结果由 {@code TaskReviewDuration} 承载,不走 Map。
*/ */
private void fillReviewDuration(Map<String, ReviewTaskStats> statsByTaskNum) { private void fillReviewDuration(Map<String, ReviewTaskStats> statsByTaskNum) {
List<Map<String, Object>> rows = reviewRecallRecordMapper.selectMaps( List<TaskReviewDuration> rows = reviewRecallRecordMapper.sumReviewDurationByTask(statsByTaskNum.keySet());
Wrappers.<ReviewRecallRecordEntity>query() for (TaskReviewDuration row : rows) {
.select("task_num AS taskNum", ReviewTaskStats stats = statsByTaskNum.get(row.getTaskNum());
"COALESCE(SUM(review_duration_seconds), 0) AS reviewDurationSeconds") if (stats != null && row.getReviewDurationSeconds() != null) {
.in("task_num", statsByTaskNum.keySet()) stats.setReviewDurationSeconds(row.getReviewDurationSeconds());
.groupBy("task_num"));
for (Map<String, Object> row : rows) {
Object taskNum = columnValue(row, "taskNum");
Object duration = columnValue(row, "reviewDurationSeconds");
ReviewTaskStats stats = taskNum == null ? null : statsByTaskNum.get(taskNum.toString());
if (stats != null && duration instanceof Number number) {
stats.setReviewDurationSeconds(number.longValue());
} }
} }
} }
/**
* 取聚合结果的列:别名大小写随数据库实现不同(MySQL 保留、H2 会转为小写),这里统一不区分大小写。
*/
private static Object columnValue(Map<String, Object> row, String column) {
Object direct = row.get(column);
if (direct != null) {
return direct;
}
for (Map.Entry<String, Object> entry : row.entrySet()) {
if (entry.getKey() != null && entry.getKey().equalsIgnoreCase(column)) {
return entry.getValue();
}
}
return null;
}
private void fillReportAndFragmentCount(Map<String, String> sessionToTaskNum, private void fillReportAndFragmentCount(Map<String, String> sessionToTaskNum,
Map<String, ReviewTaskStats> statsByTaskNum) { Map<String, ReviewTaskStats> statsByTaskNum) {
if (sessionToTaskNum.isEmpty()) { if (sessionToTaskNum.isEmpty()) {
@@ -0,0 +1,31 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper
PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
"http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.guo.learningprogresstracker.mapper.ReviewRecallRecordMapper">
<!-- 显式列映射:不依赖 map-underscore-to-camel-case,也不依赖数据库的标识符大小写规则 -->
<resultMap id="TaskReviewDurationMap" type="com.guo.learningprogresstracker.dto.TaskReviewDuration">
<result property="taskNum" column="task_num" jdbcType="VARCHAR"/>
<result property="reviewDurationSeconds" column="review_duration_seconds" jdbcType="BIGINT"/>
</resultMap>
<!--
按任务汇总复习耗时(复习-07)。
注意:自定义 SQL 不会被 @TableLogic 自动追加 deleted 条件,必须显式写出;
租户条件 created_by 由 TenantLineInnerInterceptor 自动追加(有集成测试覆盖)。
-->
<select id="sumReviewDurationByTask" resultMap="TaskReviewDurationMap">
SELECT task_num,
COALESCE(SUM(review_duration_seconds), 0) AS review_duration_seconds
FROM review_recall_records
WHERE deleted = 0
<if test="taskNums != null and !taskNums.isEmpty()">
AND task_num IN
<foreach collection="taskNums" item="num" open="(" separator="," close=")">
#{num}
</foreach>
</if>
GROUP BY task_num
</select>
</mapper>
@@ -10,32 +10,38 @@ import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired; import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest; import org.springframework.boot.test.context.SpringBootTest;
import java.util.concurrent.atomic.AtomicInteger;
import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertEquals;
/** /**
* 复习耗时的落库与聚合集成测试(复习-07):在真实 SQL(含租户条件、逻辑删除与 GROUP BY 聚合)下验证。 * 复习耗时的落库与聚合集成测试(复习-07):在真实 SQL(含租户条件、逻辑删除与 GROUP BY 聚合)下验证。
* <p>聚合走自定义 Mapper SQL,因此这里同时守住两个容易漏的条件:租户隔离与逻辑删除。</p>
*/ */
@SpringBootTest @SpringBootTest
class ReviewDurationIntegrationTest { class ReviewDurationIntegrationTest {
private static final String USER_A = "复习耗时集成测试用户A";
private static final String USER_B = "复习耗时集成测试用户B";
/** GenerateNumTool 在同毫秒内会生成相同编号(数据-03),集成测试自己保证任务编号唯一。 */
private static final AtomicInteger SEQ = new AtomicInteger();
@Autowired @Autowired
private ReviewService reviewService; private ReviewService reviewService;
@Autowired @Autowired
private ReviewRecallRecordMapper recallRecordMapper; private ReviewRecallRecordMapper recallRecordMapper;
/** GenerateNumTool 在同毫秒内会生成相同编号(数据-03),集成测试自己保证任务编号唯一。 */ @BeforeEach
private static final java.util.concurrent.atomic.AtomicInteger SEQ = new java.util.concurrent.atomic.AtomicInteger(); void setUp() {
StpUtil.login(USER_A, "test_device");
}
private static String uniqueTaskNum() { private static String uniqueTaskNum() {
return "TASKRD-IT-" + System.nanoTime() + "-" + SEQ.incrementAndGet(); return "TASKRD-IT-" + System.nanoTime() + "-" + SEQ.incrementAndGet();
} }
@BeforeEach
void setUp() {
StpUtil.login("复习耗时集成测试用户", "test_device");
}
@Test @Test
void reviewDuration_isPersistedAndAggregatedPerTask() { void reviewDuration_isPersistedAndAggregatedPerTask() {
String taskNum = uniqueTaskNum(); String taskNum = uniqueTaskNum();
@@ -45,26 +51,48 @@ class ReviewDurationIntegrationTest {
insertRecall(taskNum, 120); insertRecall(taskNum, 120);
insertRecall(otherTaskNum, 60); insertRecall(otherTaskNum, 60);
ReviewTaskStats stats = reviewService.getReviewTaskStats(taskNum); assertEquals(420L, reviewService.getReviewTaskStats(taskNum).getReviewDurationSeconds(),
assertEquals(420L, stats.getReviewDurationSeconds(), "同一任务应累计 300+120 秒"); "同一任务应累计 300+120 秒");
assertEquals(60L, reviewService.getReviewTaskStats(otherTaskNum).getReviewDurationSeconds(),
ReviewTaskStats otherStats = reviewService.getReviewTaskStats(otherTaskNum); "不同任务之间不应串数据");
assertEquals(60L, otherStats.getReviewDurationSeconds(), "不同任务之间不应串数据");
} }
@Test @Test
void reviewDuration_databaseDefaultIsZero() { void reviewDuration_databaseDefaultIsZero() {
ReviewRecallRecordEntity record = new ReviewRecallRecordEntity(); ReviewRecallRecordEntity saved = insertRecall(uniqueTaskNum(), null);
record.setTaskNum(uniqueTaskNum());
record.setRecallContent("- 未计时回忆");
record.setRecallRatio(0.0);
recallRecordMapper.insert(record);
ReviewRecallRecordEntity reloaded = recallRecordMapper.selectById(record.getId()); assertEquals(0, recallRecordMapper.selectById(saved.getId()).getReviewDurationSeconds(),
assertEquals(0, reloaded.getReviewDurationSeconds(), "未上报耗时时应落库为 0,而不是 null"); "未上报耗时时应落库为 0,而不是 null");
} }
private void insertRecall(String taskNum, int durationSeconds) { @Test
void reviewDuration_customSqlStillIsolatedByTenant() {
String taskNum = uniqueTaskNum();
insertRecall(taskNum, 300);
StpUtil.login(USER_B, "test_device");
insertRecall(taskNum, 999);
assertEquals(999L, reviewService.getReviewTaskStats(taskNum).getReviewDurationSeconds(),
"用户 B 只应看到自己的记录");
StpUtil.login(USER_A, "test_device");
assertEquals(300L, reviewService.getReviewTaskStats(taskNum).getReviewDurationSeconds(),
"自定义 SQL 也必须被租户拦截器追加 created_by 条件");
}
@Test
void reviewDuration_excludesLogicallyDeletedRecords() {
String taskNum = uniqueTaskNum();
ReviewRecallRecordEntity deleted = insertRecall(taskNum, 300);
insertRecall(taskNum, 120);
recallRecordMapper.deleteById(deleted.getId());
assertEquals(120L, reviewService.getReviewTaskStats(taskNum).getReviewDurationSeconds(),
"自定义 SQL 未被 @TableLogic 自动追加条件,必须显式过滤 deleted = 0");
}
private ReviewRecallRecordEntity insertRecall(String taskNum, Integer durationSeconds) {
ReviewRecallRecordEntity record = new ReviewRecallRecordEntity(); ReviewRecallRecordEntity record = new ReviewRecallRecordEntity();
record.setTaskNum(taskNum); record.setTaskNum(taskNum);
record.setRecallContent("- 集成测试回忆"); record.setRecallContent("- 集成测试回忆");
@@ -74,5 +102,6 @@ class ReviewDurationIntegrationTest {
record.setExtraCount(0); record.setExtraCount(0);
record.setReviewDurationSeconds(durationSeconds); record.setReviewDurationSeconds(durationSeconds);
recallRecordMapper.insert(record); recallRecordMapper.insert(record);
return record;
} }
} }
@@ -4,6 +4,7 @@ import com.baomidou.mybatisplus.core.MybatisConfiguration;
import com.baomidou.mybatisplus.core.metadata.TableInfoHelper; import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
import com.guo.learningprogresstracker.dto.ReviewFeedItem; import com.guo.learningprogresstracker.dto.ReviewFeedItem;
import com.guo.learningprogresstracker.dto.ReviewTaskStats; import com.guo.learningprogresstracker.dto.ReviewTaskStats;
import com.guo.learningprogresstracker.dto.TaskReviewDuration;
import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity; import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity;
import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity; import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
import com.guo.learningprogresstracker.entity.StudyReportsEntity; import com.guo.learningprogresstracker.entity.StudyReportsEntity;
@@ -24,7 +25,6 @@ import org.mockito.junit.jupiter.MockitoExtension;
import java.time.LocalDateTime; import java.time.LocalDateTime;
import java.util.List; import java.util.List;
import java.util.Map;
import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.mockito.ArgumentMatchers.any; import static org.mockito.ArgumentMatchers.any;
@@ -161,9 +161,9 @@ class ReviewServiceImplTest {
when(studyReportsMapper.selectList(any())).thenReturn(List.of()); when(studyReportsMapper.selectList(any())).thenReturn(List.of());
when(studyReportFragmentsMapper.selectList(any())).thenReturn(List.of()); when(studyReportFragmentsMapper.selectList(any())).thenReturn(List.of());
// 聚合结果里出现了不在任务列表中的 taskNum,应被忽略 // 聚合结果里出现了不在任务列表中的 taskNum,应被忽略
when(reviewRecallRecordMapper.selectMaps(any())).thenReturn(List.of( when(reviewRecallRecordMapper.sumReviewDurationByTask(any())).thenReturn(List.of(
Map.of("taskNum", "T1", "reviewDurationSeconds", 420L), reviewDuration("T1", 420L),
Map.of("taskNum", "T_UNKNOWN", "reviewDurationSeconds", 100L))); reviewDuration("T_UNKNOWN", 100L)));
List<ReviewTaskStats> stats = reviewService.getReviewTaskStats(); List<ReviewTaskStats> stats = reviewService.getReviewTaskStats();
@@ -171,4 +171,11 @@ class ReviewServiceImplTest {
assertEquals(600, stats.get(0).getEffectiveTime()); assertEquals(600, stats.get(0).getEffectiveTime());
assertEquals(420L, stats.get(0).getReviewDurationSeconds()); assertEquals(420L, stats.get(0).getReviewDurationSeconds());
} }
private static TaskReviewDuration reviewDuration(String taskNum, Long seconds) {
TaskReviewDuration row = new TaskReviewDuration();
row.setTaskNum(taskNum);
row.setReviewDurationSeconds(seconds);
return row;
}
} }