package com.nanri.aiimage; import org.junit.jupiter.api.Test; import java.io.IOException; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; import java.util.ArrayList; import java.util.LinkedHashMap; import java.util.List; import java.util.Map; import java.util.regex.Matcher; import java.util.regex.Pattern; import java.util.stream.Collectors; import java.util.stream.Stream; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertTrue; import static org.junit.jupiter.api.Assertions.fail; /** * 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 文本块存在, * 改一列要在字符串里数括号,也没有任何工具在写错时拦你。约定只存在于注释的话, * 下一个人加 {@code @Insert} 时它就不存在了。所以这里把"当前有多少"逐个钉死: *

* *

反向失明也一并堵:XML 里的坏 SQL 没有编译期反馈,所以 * {@link #everyXmlStatementMatchesAnInterfaceMethod} 要求 XML 语句名逐字对上接口方法名—— * 对不上的表现是"启动正常、调用才报 no statement",那是线上才会撞到的面。 */ class SqlLayeringConventionTest { /** * 注解里的写 SQL 清单。2026-10-08 全量迁完后为空:任何一条重新出现都直接红, * 新 SQL 一律写进 {@code src/main/resources/mapper/<模块>/Mapper.xml}。 */ private static final Map WRITE_SQL_BASELINE = new LinkedHashMap<>(); /** * 注解里的读 SQL 清单,同样在 2026-10-08 迁完归零。 * *

保留逐接口形态(而不是退回一个"总数 0")是有原因的:以前钉"总数 + 文件数"两个标量时, * A 接口加一条配 B 接口减一条两个标量都不动,闸门形同虚设;逐接口清单在迁移期就是账本, * 迁完后它继续保证"不许在某个接口里悄悄攒回来"。 */ private static final Map SELECT_SQL_BASELINE = new LinkedHashMap<>(); /** * 迁移完成态的分母:XML 里应有的语句总数(85 本轮 + 9 TaskImageCache + 2 AsinResultCache)。 * *

96 → 97:会话容忍新增 1 条只读语句 {@code AdminUserMapper#countLiveWorkFor}。 * 它不是「从注解搬进 XML」而是新写的,所以只在 XML 侧留痕——同一轮 * {@code MigratedSqlEquivalenceTest} 里它被登记成「非迁移语句」,两处一起改才配得上。

*/ // 97 → 98:V157 token 计量新增 1 条写侧语句 {@code UserSecretUsageMapper#addTokens}。 // 它同样是「新写」而非「从注解搬进 XML」,所以两处一起改:本格的总数 + // MigratedSqlEquivalenceTest.NOT_MIGRATED 的点名。与 increment 分两条是口径要求—— // 计次发生在发请求之前(含重试),token 只有响应回来才有读数,合成一条 upsert 就会漏计超时的那次。 // 98 → 99:失败任务重试新增 {@code CollectDataItemMapper#copyItemsForRetry} // (INSERT ... SELECT 复制明细行),同样登记进 NOT_MIGRATED。 // 99 → 115:keywordshare 模块(五国关键词共享网页化,5 份 XML 16 条)新写语句。 // 115 → 124:brandgating 模块(品牌Gating库并入管理后台,1 份 XML 9 条)新写语句; // 两批 19 条 select 逐条登记进 MigratedSqlEquivalenceTest.NOT_MIGRATED(67 → 78 → 86)。 // 124 → 126:损耗监控在 {@code UserSecretUsageMapper} 新写 2 条聚合 select // (当日全量扫描 + 单用户读数),同样逐条登记进 NOT_MIGRATED(86 → 88)。 // 126 → 128:同轮 {@code UserTaskGuardMapper} 的 pause/resume 两条写侧语句从注解迁进 XML。 // 128 → 129:B28 新增 {@code TaskFileJobMapper#selectFileTaskStatus}(按主键读父任务状态), // 新写语句按约定直接进 XML,同轮登记进 MigratedSqlEquivalenceTest.NOT_MIGRATED(88 → 89)。 // 129 → 130:CR-01 新增 {@code LoginUserMapper#incrementSessionEpoch}(会话世代原子自增), // 新写语句直接进 mapper/auth/LoginUserMapper.xml,同轮登记进 NOT_MIGRATED。 private static final int XML_STATEMENT_TOTAL = 130; /** * wrapper 里夹带函数级 SQL 的现状("这不是简单单表"的证据),文件名 → 条数: * apply/inSql 是真谓词,last("FOR UPDATE") 是行锁。 */ private static final Map RAW_SQL_IN_WRAPPERS_BASELINE = rawSqlInWrappersBaseline(); /** * 注解里带动态标签的写 SQL 待迁清单。2026-10-08 已清空—— * {@code }/{@code } 这类 Wrapper 表达不了的语句现在只在 XML 里。 * 再往注解里塞动态标签,{@link #noNewComplexWriteSqlInAnnotations} 直接红。 */ private static final List COMPLEX_WRITE_SQL_BACKLOG = List.of(); /** * "带写 SQL 又不继承 BaseMapper" 的豁免名单,同样已清空:SQL 进了 XML 之后, * 接口继不继承实体都不影响语句落地,这条只用来拦"新 mapper 一上来就写裸注解 SQL"。 */ private static final List MAPPERS_WITHOUT_ENTITY = List.of(); private static final Pattern WRITE_ANNOTATION = Pattern.compile("@(Insert|Update|Delete)\\("); private static final Pattern SELECT_ANNOTATION = Pattern.compile("@Select\\("); private static final Pattern WRITE_ANNOTATION_BODY = Pattern.compile("@(Insert|Update|Delete)\\(\\s*\"\"\"(.*?)\"\"\"", Pattern.DOTALL); private static final Pattern STATEMENT_ID = Pattern.compile("<(?:select|insert|update|delete)\\s+id=\"[^\"]+\""); private static Map rawSqlInWrappersBaseline() { Map baseline = new LinkedHashMap<>(); baseline.put("PublishStaleTaskScanner", 3); // ownerInstanceId 的 JSON_EXTRACT 谓词:3D 前置抽件把 PublishTaskService 那 6 处 // (心跳线+二次判死线各 3 处逐字相同)收成共用一枚 ownerScoped ⇒ 整树 6→3。 baseline.put("SimilarAsinTaskOwnershipSupport", 3); // 同上,state_json 维度 baseline.put("ShopDataCrawlDailyFileService", 4); // last("FOR UPDATE") 行锁 baseline.put("TaskScopePayloadStorageService", 1); // last("limit 1 FOR UPDATE") 混写 baseline.put("SimilarAsinTaskProgressSupport", 1); // inSql 子查询 return baseline; } @Test void annotationSqlInventoryDoesNotGrow() throws IOException { Map actual = new LinkedHashMap<>(); Map actualSelects = new LinkedHashMap<>(); for (Path file : mappers()) { String text = stripComments(read(file)); int writes = count(WRITE_ANNOTATION, text); if (writes > 0) { actual.put(stem(file), writes); } int read = count(SELECT_ANNOTATION, text); if (read > 0) { actualSelects.put(stem(file), read); } } assertEquals(WRITE_SQL_BASELINE, actual, () -> "注解里又出现了写 SQL(基线已归零)。" + System.lineSeparator() + " 新 SQL → 写进 src/main/resources/mapper/<模块>/Mapper.xml;" + "简单单表才用 BaseMapper/实体(wrapper)。当前实测:" + actual); assertEquals(SELECT_SQL_BASELINE, actualSelects, () -> "注解里又出现了 @Select(基线已归零)。" + System.lineSeparator() + " A 接口加一条配 B 接口减一条在这种逐接口钉法下会直接红。当前实测:" + actualSelects); // 归零之后不能拿"清单为空"当自证,分母改由扫描面本身提供 int scanned = mappers().size(); assertTrue(scanned >= 60, () -> "只扫到 " + scanned + " 个 *Mapper.java,多半是目录或工作目录坏了——" + "扫描面塌了的话上面两个 assertEquals(空表) 就成了恒绿"); } /** * wrapper 只该出现在"简单单表"上。函数级谓词(JSON_EXTRACT)、行锁(FOR UPDATE)、 * 子查询(inSql)都说明这条查询已经越过那条线——按口径应进 XML。 * *

{@code last("LIMIT n")} 故意不算越界:MP 的分页 idiomatic 写法就是它, * 全仓 205 处,把它算成违规只会让守卫第一天就没人管。豁免面由 * {@link #limitExemptionDoesNotHideRealSql} 反向钉住。 */ @Test void rawSqlInsideWrappersDoesNotGrow() throws IOException { Map actual = new LinkedHashMap<>(); for (Path file : mainSources()) { int hits = countRawSqlInWrapper(stripComments(read(file))); if (hits > 0) { actual.put(stem(file), hits); } } assertEquals(RAW_SQL_IN_WRAPPERS_BASELINE, actual, () -> "wrapper 里夹带的函数级 SQL 变了。" + System.lineSeparator() + " 新增 → 这条已经不是简单单表,SQL 写进 mapper XML;" + System.lineSeparator() + " 迁走 → 同步减 RAW_SQL_IN_WRAPPERS_BASELINE。当前实测:" + actual); assertTrue(actual.values().stream().mapToInt(Integer::intValue).sum() >= 10, "只数到 " + actual + " 条,多半是正则或目录坏了——恒 0 的闸门比没有闸门更糟"); } @Test void limitExemptionDoesNotHideRealSql() { // 计数器必须"看见" JSON_EXTRACT / FOR UPDATE / inSql,但放过 LIMIT —— 四种形状各喂一条 assertEquals(1, countRawSqlInWrapper("q.apply(\"JSON_UNQUOTE(JSON_EXTRACT(a, '$.b')) = {0}\", v));")); assertEquals(1, countRawSqlInWrapper("q.last(\"FOR UPDATE\"));")); assertEquals(1, countRawSqlInWrapper("q.inSql(FileTaskEntity::getId, \"select id from t\"));")); assertEquals(0, countRawSqlInWrapper("q.last(\"LIMIT \" + safeLimit));"), "LIMIT 分页 idiomatic 写法不该计入,否则 205 处噪音会把这条守卫淹掉"); // 但 "LIMIT 1 FOR UPDATE" 这种混写必须计入——不能被前缀是 LIMIT 就放过 assertEquals(1, countRawSqlInWrapper("q.last(\"limit 1 FOR UPDATE\"));")); } @Test void noNewComplexWriteSqlInAnnotations() throws IOException { List complex = new ArrayList<>(); for (Path file : mappers()) { Matcher matcher = WRITE_ANNOTATION_BODY.matcher(stripComments(read(file))); while (matcher.find()) { String body = matcher.group(2); if (body.contains("