diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/task/mapper/TaskImageCacheMapper.java b/backend-java/src/main/java/com/nanri/aiimage/modules/task/mapper/TaskImageCacheMapper.java index 449be5389..4d4cfcb8c 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/task/mapper/TaskImageCacheMapper.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/task/mapper/TaskImageCacheMapper.java @@ -2,18 +2,15 @@ package com.nanri.aiimage.modules.task.mapper; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.nanri.aiimage.modules.task.model.entity.TaskImageCacheEntity; -import org.apache.ibatis.annotations.Delete; import org.apache.ibatis.annotations.Mapper; import org.apache.ibatis.annotations.Param; -import org.apache.ibatis.annotations.Select; -import org.apache.ibatis.annotations.Update; import java.time.LocalDateTime; import java.util.List; /** * P2-12:图片缩略图缓存 mapper。提供 LRU 命中刷新、按 url_hash 直读字节两个轻量入口, - * 其余 CRUD 走 {@link BaseMapper} 默认实现。 + * 其余 CRUD 走 {@link BaseMapper} 默认实现。SQL 在 resources/mapper/task/TaskImageCacheMapper.xml。 */ @Mapper public interface TaskImageCacheMapper extends BaseMapper { @@ -21,47 +18,35 @@ public interface TaskImageCacheMapper extends BaseMapper { /** * 命中时同步 bumping last_used_at,便于后续按 LRU 清理过期未用记录。 */ - @Update("UPDATE biz_task_image_cache SET last_used_at = NOW(3) WHERE url_hash = #{urlHash}") int touchLastUsed(@Param("urlHash") String urlHash); /** * 批量命中检查:仅取 url_hash 列(避免把 image_bytes BLOB 拉回 JVM)。 */ - @Select("") List selectUrlHashes(@Param("urlHashes") List urlHashes); /** * 批量 bumping last_used_at。 */ - @Update("") int touchLastUsedBatch(@Param("urlHashes") List urlHashes); /** * 按 url_hash 直读缩略图字节,命中时返回 BLOB;未命中返回 null。 * 选择只 select image_bytes 一列,避免把整行 entity(含 url 字符串)拉回 JVM。 */ - @Select("SELECT image_bytes FROM biz_task_image_cache WHERE url_hash = #{urlHash} LIMIT 1") byte[] selectBytesByUrlHash(@Param("urlHash") String urlHash); /** * Task 14:批量直读缩略图字节。只 select url_hash + image_bytes 两列, * 避免把整行 entity(含 url 字符串)拉回 JVM;配合 batchSize 分片控制 IN 长度。 */ - @Select("") List selectBytesByUrlHashes(@Param("urlHashes") List urlHashes); - @Select("SELECT COALESCE(SUM(byte_size), 0) FROM biz_task_image_cache") Long sumByteSize(); - @Select("SELECT COALESCE(SUM(byte_size), 0) FROM (SELECT byte_size FROM biz_task_image_cache ORDER BY last_used_at LIMIT #{limit}) oldest") Long sumOldestBatchByteSize(@Param("limit") int limit); - @Delete("DELETE FROM biz_task_image_cache WHERE last_used_at < #{cutoff} ORDER BY last_used_at LIMIT #{limit}") int deleteExpiredBatch(@Param("cutoff") LocalDateTime cutoff, @Param("limit") int limit); - @Delete("DELETE FROM biz_task_image_cache ORDER BY last_used_at LIMIT #{limit}") int deleteOldestBatch(@Param("limit") int limit); } diff --git a/backend-java/src/main/resources/mapper/task/TaskImageCacheMapper.xml b/backend-java/src/main/resources/mapper/task/TaskImageCacheMapper.xml new file mode 100644 index 000000000..b1453ef3c --- /dev/null +++ b/backend-java/src/main/resources/mapper/task/TaskImageCacheMapper.xml @@ -0,0 +1,63 @@ + + + + + + + WHERE url_hash IN + #{hash} + + + + UPDATE biz_task_image_cache SET last_used_at = NOW(3) WHERE url_hash = #{urlHash} + + + + + + UPDATE biz_task_image_cache SET last_used_at = NOW(3) + + + + + + + + + + + + + + DELETE FROM biz_task_image_cache WHERE last_used_at < #{cutoff} + ORDER BY last_used_at LIMIT #{limit} + + + + DELETE FROM biz_task_image_cache ORDER BY last_used_at LIMIT #{limit} + + diff --git a/backend-java/src/test/java/com/nanri/aiimage/SqlLayeringConventionTest.java b/backend-java/src/test/java/com/nanri/aiimage/SqlLayeringConventionTest.java index 1fed5176c..96354798c 100644 --- a/backend-java/src/test/java/com/nanri/aiimage/SqlLayeringConventionTest.java +++ b/backend-java/src/test/java/com/nanri/aiimage/SqlLayeringConventionTest.java @@ -21,8 +21,11 @@ import static org.junit.jupiter.api.Assertions.assertTrue; import static org.junit.jupiter.api.Assertions.fail; /** - * SQL 分层约定的守卫。口径(2026-10-08 定):SQL 尽量写进 mapper XML, - * wrapper 只留给"简单单表"(无 join、无函数级谓词、无动态标签),注解里不再新增 SQL。 + * SQL 分层约定的守卫。口径(2026-10-08 定,同日收紧到"档 B"):自定义语句一律写进 mapper XML, + * "特别简单"才允许留在 Java 侧,而它只有两种形状——{@code BaseMapper} 自带 CRUD,以及单表按主键/唯一键的点查。 + * 带自定义 WHERE 列组合、带投影列清单、带 join/子查询/函数级谓词/动态标签的都算自定义。 + * 两份逐接口清单({@code WRITE_SQL_BASELINE} + {@code SELECT_SQL_BASELINE})就是这条口径的账本: + * 迁移进度按它减,新增按它红。 * *

为什么要钉住而不是写在文档里:这个仓原来 0 个 XML、写 SQL 全在注解里,复杂语句 * ({@code } + {@code ON DUPLICATE KEY} + 逐列 COALESCE)以 Java 文本块存在, @@ -45,12 +48,12 @@ class SqlLayeringConventionTest { private static final Map WRITE_SQL_BASELINE = writeSqlBaseline(); /** - * 读侧注解 SQL 的总量与文件数(2026-10-08 实测 65 条 / 16 个接口)。 - * 读侧按"尽量 XML"是主要待迁面,最重的是 TaskCenterQueryMapper; - * 钉总数而不是逐条清单,是因为逐条会把这份守卫变成迁移进度表——它该只做"别再加"的闸门。 + * 读侧注解 SQL 的逐接口清单(2026-10-08 实测 65 条 / 16 个接口,迁走 TaskImageCacheMapper 后 60 / 15)。 + * + *

为什么从"总数 + 文件数"两个标量改成逐接口:标量守恒的是**和**,A 接口减一条、 + * B 接口加一条时两个标量都不动,闸门照样绿——档 B 口径下这等于没有闸门。 */ - private static final int SELECT_ANNOTATION_TOTAL = 65; - private static final int SELECT_ANNOTATION_FILES = 16; + private static final Map SELECT_SQL_BASELINE = selectSqlBaseline(); /** * wrapper 里夹带函数级 SQL 的现状("这不是简单单表"的证据),文件名 → 条数: @@ -71,7 +74,7 @@ class SqlLayeringConventionTest { private static final List MAPPERS_WITHOUT_ENTITY = List.of("UserColumnPermissionMapper"); /** 已经迁到 XML 的:反向钉住"不许再用注解把 SQL 写回来"(注解 + XML 同名会让启动期抛重复语句)。 */ - private static final List MIGRATED_TO_XML = List.of("AsinResultCacheMapper"); + private static final List MIGRATED_TO_XML = List.of("AsinResultCacheMapper", "TaskImageCacheMapper"); private static final Pattern WRITE_ANNOTATION = Pattern.compile("@(Insert|Update|Delete)\\("); private static final Pattern SELECT_ANNOTATION = Pattern.compile("@Select\\("); @@ -93,12 +96,32 @@ class SqlLayeringConventionTest { baseline.put("ShopDataDuplicateScanMapper", 1); baseline.put("QueryAsinMapper", 1); baseline.put("SoftwareVersionMapper", 1); - baseline.put("TaskImageCacheMapper", 4); baseline.put("TaskResultItemMapper", 1); baseline.put("UserSecretUsageMapper", 2); return baseline; } + /** 读侧基线:TaskImageCacheMapper 的 5 条已在 mapper/task/TaskImageCacheMapper.xml 里。 */ + private static Map selectSqlBaseline() { + Map baseline = new LinkedHashMap<>(); + baseline.put("TaskCenterQueryMapper", 20); + baseline.put("ShopManageGroupMapper", 9); + baseline.put("ShopDuplicateCheckItemMapper", 5); + baseline.put("ShopDuplicateCheckSourceMapper", 5); + baseline.put("ImageVideoAdminTaskMapper", 4); + baseline.put("UserColumnPermissionMapper", 3); + baseline.put("ShopDataDuplicateScanMapper", 3); + baseline.put("AdminUserMapper", 2); + baseline.put("ShopDataCrawlAdminTasksMapper", 2); + baseline.put("QueryAsinMapper", 2); + baseline.put("BrandCrawlTaskMapper", 1); + baseline.put("DedupeTotalDataMapper", 1); + baseline.put("FileResultMapper", 1); + baseline.put("FileTaskMapper", 1); + baseline.put("TaskScopeStateMapper", 1); + return baseline; + } + private static Map rawSqlInWrappersBaseline() { Map baseline = new LinkedHashMap<>(); baseline.put("PublishTaskService", 6); // ownerInstanceId 的 JSON_EXTRACT 谓词 @@ -112,8 +135,7 @@ class SqlLayeringConventionTest { @Test void annotationSqlInventoryDoesNotGrow() throws IOException { Map actual = new LinkedHashMap<>(); - int selects = 0; - List selectFiles = new ArrayList<>(); + Map actualSelects = new LinkedHashMap<>(); for (Path file : mappers()) { String text = stripComments(read(file)); int writes = count(WRITE_ANNOTATION, text); @@ -122,8 +144,7 @@ class SqlLayeringConventionTest { } int read = count(SELECT_ANNOTATION, text); if (read > 0) { - selects += read; - selectFiles.add(stem(file)); + actualSelects.put(stem(file), read); } } assertEquals(WRITE_SQL_BASELINE, actual, () -> "注解里的写 SQL 清单变了。" + System.lineSeparator() @@ -131,10 +152,12 @@ class SqlLayeringConventionTest { + "简单单表才用 BaseMapper/实体(wrapper)。" + System.lineSeparator() + " 迁走 → 把这一项从 WRITE_SQL_BASELINE 里减掉,让减法出现在 diff 上。"); assertFalse(actual.isEmpty(), "清单为空说明本用例没扫到任何 mapper,判据本身坏了"); - assertEquals(SELECT_ANNOTATION_TOTAL, selects, - () -> "注解里的 @Select 总数变了(读侧同样按 XML 优先)。迁一条就减一:" + selectFiles); - assertEquals(SELECT_ANNOTATION_FILES, selectFiles.size(), - "带注解 @Select 的接口个数变了:" + selectFiles); + assertEquals(SELECT_SQL_BASELINE, actualSelects, () -> "注解里的 @Select 逐接口清单变了(读侧同样 XML 优先)。" + + System.lineSeparator() + + " 迁一条就从这里划掉一条;A 接口减一条配 B 接口加一条在这种钉法下会直接红。" + + System.lineSeparator() + + " 当前实测:" + actualSelects); + assertFalse(actualSelects.isEmpty(), "读侧清单为空说明正则或目录坏了——恒绿的闸门比没有闸门更糟"); } /** @@ -248,6 +271,28 @@ class SqlLayeringConventionTest { + "新 mapper 请 extends BaseMapper"); } + /** + * 这条是给"逐文件清单"这次改动自证的:以前钉的是总数 65 + 文件数 16 两个标量, + * 于是 A 接口加一条、B 接口减一条就能让两个标量双双不动而绕过闸门。 + * 这里在内存里造出那次搬家——总和仍是基线总和,清单必须不等。 + */ + @Test + void thePerFileLedgerCatchesWhatTheScalarsCouldNot() { + int baselineTotal = SELECT_SQL_BASELINE.values().stream().mapToInt(Integer::intValue).sum(); + assertTrue(baselineTotal > 0, "基线本身是空的,下面的断言就是恒真"); + + Map moved = new LinkedHashMap<>(SELECT_SQL_BASELINE); + moved.merge("ShopManageGroupMapper", 1, Integer::sum); + moved.merge("ShopDuplicateCheckItemMapper", -1, Integer::sum); + + assertEquals(baselineTotal, moved.values().stream().mapToInt(Integer::intValue).sum(), + "这次搬家必须让总数不变,否则它证明不了标量钉法的失明"); + assertEquals(SELECT_SQL_BASELINE.size(), moved.size(), + "这次搬家必须让文件数也不变"); + assertFalse(SELECT_SQL_BASELINE.equals(moved), + "逐文件清单没看见这次搬家——说明它退化成了标量比较"); + } + @Test void xmlDirectoryIsActuallyOnTheLoadPath() throws IOException { Path resources = moduleRoot().resolve("src/main/resources/mapper"); diff --git a/backend-java/src/test/java/com/nanri/aiimage/modules/task/mapper/TaskImageCacheMapperXmlTest.java b/backend-java/src/test/java/com/nanri/aiimage/modules/task/mapper/TaskImageCacheMapperXmlTest.java new file mode 100644 index 000000000..d85c6e8c1 --- /dev/null +++ b/backend-java/src/test/java/com/nanri/aiimage/modules/task/mapper/TaskImageCacheMapperXmlTest.java @@ -0,0 +1,182 @@ +package com.nanri.aiimage.modules.task.mapper; + +import com.baomidou.mybatisplus.core.MybatisConfiguration; +import com.nanri.aiimage.modules.task.model.entity.TaskImageCacheEntity; +import org.apache.ibatis.builder.xml.XMLMapperBuilder; +import org.apache.ibatis.io.Resources; +import org.apache.ibatis.mapping.BoundSql; +import org.apache.ibatis.mapping.MappedStatement; +import org.apache.ibatis.session.Configuration; +import org.junit.jupiter.api.Test; + +import java.io.InputStream; +import java.time.LocalDateTime; +import java.util.HashMap; +import java.util.List; +import java.util.Map; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * {@code TaskImageCacheMapper} 从注解迁到 mapper XML 后的等价性守卫。 + * + *

这个 mapper 的行为不变量只有一条值得钉死:任何语句都不许把 {@code image_bytes} 顺带拉回来 + * ——它是 BLOB,缓存表整行回读会把"省内存的缓存"变成内存负担。迁 SQL 时最容易顺手写成 + * {@code SELECT *},而那在单测里不会红(没有库),所以这里直接对真 {@code BoundSql} 断言列形状。 + * + *

另外两条是 XML 特有的失明面:{@code <} 忘了转义成 {@code <} 会让文件解析失败(这条会红, + * 但红得没道理可寻),而注解+XML 同名只在启动期抛,本地不起容器看不见。 + */ +class TaskImageCacheMapperXmlTest { + + private static final String XML = "mapper/task/TaskImageCacheMapper.xml"; + private static final String NS = "com.nanri.aiimage.modules.task.mapper.TaskImageCacheMapper"; + + private static final List STATEMENT_IDS = List.of( + "touchLastUsed", "selectUrlHashes", "touchLastUsedBatch", "selectBytesByUrlHash", + "selectBytesByUrlHashes", "sumByteSize", "sumOldestBatchByteSize", + "deleteExpiredBatch", "deleteOldestBatch"); + + @Test + void xmlParsesAndBindsEveryInterfaceMethod() throws Exception { + Configuration configuration = parseXml(); + for (String id : STATEMENT_IDS) { + assertTrue(configuration.hasStatement(NS + "." + id), + () -> XML + " 里没有 " + id + ":语句名必须与接口方法名逐字一致,否则调用时才报 no statement"); + } + assertTrue(configuration.hasMapper(TaskImageCacheMapper.class), + "namespace 没能绑定到接口——检查包路径与 mybatis-plus.mapper-locations"); + assertEquals(STATEMENT_IDS.size(), STATEMENT_IDS.stream() + .filter(id -> configuration.hasStatement(NS + "." + id)).count(), + "接口方法与 XML 语句数不齐"); + } + + @Test + void annotationsAreGoneSoTheStatementIsNotDefinedTwice() { + for (var method : TaskImageCacheMapper.class.getDeclaredMethods()) { + for (var annotation : List.of(org.apache.ibatis.annotations.Select.class, + org.apache.ibatis.annotations.Insert.class, org.apache.ibatis.annotations.Update.class, + org.apache.ibatis.annotations.Delete.class)) { + assertFalse(method.isAnnotationPresent(annotation), + () -> method.getName() + " 还带着 " + annotation.getSimpleName() + + ":注解 + XML 同名会让 MyBatis 启动期抛重复语句"); + } + } + } + + /** 缓存表的本行不变量:只有两条直读字节的语句允许碰 image_bytes。 */ + @Test + void onlyTheByteReadingStatementsTouchTheBlobColumn() throws Exception { + Configuration configuration = parseXml(); + for (String id : List.of("touchLastUsed", "selectUrlHashes", "touchLastUsedBatch", + "sumByteSize", "sumOldestBatchByteSize", "deleteExpiredBatch", "deleteOldestBatch")) { + String sql = sqlOf(configuration, id, params(id)); + assertFalse(sql.contains("image_bytes"), + () -> id + " 把 BLOB 列带回来了:" + sql); + } + assertTrue(sqlOf(configuration, "selectBytesByUrlHash", params("selectBytesByUrlHash")) + .contains("image_bytes"), "直读字节的语句必须真的取 image_bytes"); + } + + @Test + void theSharedInFragmentStillExpandsOnePlaceholderPerHash() throws Exception { + Configuration configuration = parseXml(); + for (String id : List.of("selectUrlHashes", "touchLastUsedBatch", "selectBytesByUrlHashes")) { + BoundSql boundSql = statement(configuration, id).getBoundSql(Map.of("urlHashes", List.of("a", "b", "c"))); + String sql = boundSql.getSql().replaceAll("\\s+", " "); + assertEquals(3, countOccurrences(sql, "?"), + () -> id + " 的 IN 长度不对(片段被改坏或 foreach 丢了): " + sql); + assertTrue(sql.contains("url_hash IN ( ? , ? , ? )"), () -> id + " 的 IN 形状变了: " + sql); + assertFalse(sql.contains("$"), () -> id + " 出现 ${} 拼接面"); + } + } + + /** 复用的代价要说清:片段写死了参数名,引用它的语句必须都带 @Param("urlHashes")。 */ + @Test + void everyStatementUsingTheFragmentDeclaresTheHashesParam() throws Exception { + for (String id : List.of("selectUrlHashes", "touchLastUsedBatch", "selectBytesByUrlHashes")) { + BoundSql boundSql = statement(parseXml(), id).getBoundSql(Map.of("urlHashes", List.of("a"))); + assertTrue(boundSql.getParameterMappings().stream() + .anyMatch(m -> "urlHashes".equals(m.getProperty()) || "__frch_hash_0".equals(m.getProperty())), + () -> id + " 没接上片段的 urlHashes 参数"); + } + } + + @Test + void limitStaysABoundParameterAndTheLessThanSurvivedEscaping() throws Exception { + Configuration configuration = parseXml(); + + String oldest = sqlOf(configuration, "sumOldestBatchByteSize", Map.of("limit", 20)); + assertTrue(oldest.contains("LIMIT ?"), () -> "LIMIT 被写死成字面量了:" + oldest); + assertEquals(1, countOccurrences(oldest, "?"), "只该有 1 个 limit 占位符: " + oldest); + + String expired = sqlOf(configuration, "deleteExpiredBatch", Map.of("cutoff", LocalDateTime.now(), "limit", 50)); + // < 还原成 < 才对;残留 < 说明转义写进了 SQL 本体 + assertTrue(expired.contains("last_used_at < ?"), () -> "删除条件里的 < 没还原:" + expired); + assertFalse(expired.contains("<"), () -> "XML 转义漏进了 SQL:" + expired); + assertTrue(expired.contains("ORDER BY last_used_at LIMIT ?"), + () -> "LRU 顺序删变成了全表删风险:" + expired); + } + + @Test + void now3PrecisionAndResultTypesSurviveTheMove() throws Exception { + Configuration configuration = parseXml(); + for (String id : List.of("touchLastUsed", "touchLastUsedBatch")) { + assertEquals(1, countOccurrences(sqlOf(configuration, id, params(id)), "NOW(3)"), + () -> id + " 的 NOW(3) 精度丢了(退化成 NOW() 会丢毫秒,LRU 排序就不准了)"); + } + assertSame(byte[].class, statement(configuration, "selectBytesByUrlHash").getResultMaps().get(0).getType(), + "byte[] 的 resultType 应为 \"[B\""); + assertSame(String.class, statement(configuration, "selectUrlHashes").getResultMaps().get(0).getType()); + assertSame(TaskImageCacheEntity.class, + statement(configuration, "selectBytesByUrlHashes").getResultMaps().get(0).getType()); + assertSame(Long.class, statement(configuration, "sumByteSize").getResultMaps().get(0).getType()); + } + + private static MappedStatement statement(Configuration configuration, String id) { + return configuration.getMappedStatement(NS + "." + id); + } + + private static String sqlOf(Configuration configuration, String id, Object parameter) { + return statement(configuration, id).getBoundSql(parameter).getSql().replaceAll("\\s+", " ").trim(); + } + + /** 各语句按自己的 @Param 形状喂,缺一个 MyBatis 会在取 BoundSql 时就抛。 */ + private static Map params(String id) { + Map parameter = new HashMap<>(); + switch (id) { + case "touchLastUsed", "selectBytesByUrlHash" -> parameter.put("urlHash", "h1"); + case "selectUrlHashes", "touchLastUsedBatch", "selectBytesByUrlHashes" -> + parameter.put("urlHashes", List.of("h1", "h2")); + case "sumOldestBatchByteSize", "deleteOldestBatch" -> parameter.put("limit", 10); + case "deleteExpiredBatch" -> { + parameter.put("cutoff", LocalDateTime.now()); + parameter.put("limit", 10); + } + default -> { + } + } + return parameter; + } + + private static Configuration parseXml() throws Exception { + MybatisConfiguration configuration = new MybatisConfiguration(); + try (InputStream in = Resources.getResourceAsStream(XML)) { + new XMLMapperBuilder(in, configuration, XML, configuration.getSqlFragments()).parse(); + } + return configuration; + } + + private static int countOccurrences(String haystack, String needle) { + int at = 0; + int count = 0; + while ((at = haystack.indexOf(needle, at)) >= 0) { + count++; + at += needle.length(); + } + return count; + } +}