Files
crawler-plugin/backend-java/src/test/java/com/nanri/aiimage/SqlLayeringConventionTest.java
T
huangzd1997 c2f429f112 fix(cr-01/02/03/08/09/10/11/13): 会话世代、损耗共享基线、任务活性与工作台包
- CR-01:users.session_epoch(V172)+ JWT sessionEpoch;登录/登出原子推进,
  check_login/requireUser 先比世代再做设备比对;登出不再依赖 machine CAS
- CR-02/09:cost-guard 基线落 Redis(CostGuardBaselineStore),按 elapsed 归一化;
  非持锁实例刷新共享密钥快照;pause() 返回写成功,失败不通知且不推进基线
- CR-03:stuck_requeue_count(V173,上限 20)与 retry_count 分账;终态父任务心跳
  停止 touchRunning 并 markFailedPermanent;良性停续期 markLost=false
- CR-08:工作台包对象 key 加 UUID、0 字节拒绝、同 objectKey 幂等、同版本重复拒绝、
  前端 confirm 超时抬到 10 分钟
- CR-10:Excel onSheetTotal 统一在 onHeader 之后回调(xlsx/xls)
- CR-13/11:迁移头/文件名一致断言(V170 唯一豁免);V167 前置由 CompanyService 同事务
  复制菜单树,已应用迁移未回改
2026-10-25 03:40:15 +08:00

442 lines
23 KiB
Java
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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"):<b>自定义语句一律写进 mapper XML</b>,
* "特别简单"才允许留在 Java 侧,而它只有两种形状——{@code BaseMapper} 自带 CRUD,以及单表按主键/唯一键的点查。
* 带自定义 WHERE 列组合、带投影列清单、带 join/子查询/函数级谓词/动态标签的都算自定义。
* 两份逐接口清单({@code WRITE_SQL_BASELINE} + {@code SELECT_SQL_BASELINE})就是这条口径的账本:
* 迁移进度按它减,新增按它红。
*
* <p>为什么要钉住而不是写在文档里:这个仓原来 0 个 XML、写 SQL 全在注解里,复杂语句
* ({@code <foreach>} + {@code ON DUPLICATE KEY} + 逐列 COALESCE)以 Java 文本块存在,
* 改一列要在字符串里数括号,也没有任何工具在写错时拦你。约定只存在于注释的话,
* 下一个人加 {@code @Insert} 时它就不存在了。所以这里把"当前有多少"逐个钉死:
* <ul>
* <li>新增注解 SQL ⇒ {@link #annotationSqlInventoryDoesNotGrow} 红;</li>
* <li>新增 wrapper 里夹带的函数级 SQL ⇒ {@link #rawSqlInsideWrappersDoesNotGrow} 红,
* 那正是"简单单表"的边界,越界就该进 XML;</li>
* <li>迁走一条 ⇒ 必须同时改基线常量,减法出现在 diff 上。</li>
* </ul>
*
* <p>反向失明也一并堵:XML 里的坏 SQL 没有编译期反馈,所以
* {@link #everyXmlStatementMatchesAnInterfaceMethod} 要求 XML 语句名逐字对上接口方法名——
* 对不上的表现是"启动正常、调用才报 no statement",那是线上才会撞到的面。
*/
class SqlLayeringConventionTest {
/**
* 注解里的写 SQL 清单。<b>2026-10-08 全量迁完后为空</b>:任何一条重新出现都直接红,
* 新 SQL 一律写进 {@code src/main/resources/mapper/<模块>/<Name>Mapper.xml}。
*/
private static final Map<String, Integer> WRITE_SQL_BASELINE = new LinkedHashMap<>();
/**
* 注解里的读 SQL 清单,同样在 2026-10-08 迁完归零。
*
* <p>保留逐接口形态(而不是退回一个"总数 0")是有原因的:以前钉"总数 + 文件数"两个标量时,
* A 接口加一条配 B 接口减一条两个标量都不动,闸门形同虚设;逐接口清单在迁移期就是账本,
* 迁完后它继续保证"不许在某个接口里悄悄攒回来"。
*/
private static final Map<String, Integer> SELECT_SQL_BASELINE = new LinkedHashMap<>();
/**
* 迁移完成态的分母:XML 里应有的语句总数(85 本轮 + 9 TaskImageCache + 2 AsinResultCache)。
*
* <p>96 → 97:会话容忍新增 1 条只读语句 {@code AdminUserMapper#countLiveWorkFor}。
* 它不是「从注解搬进 XML」而是新写的,所以只在 XML 侧留痕——同一轮
* {@code MigratedSqlEquivalenceTest} 里它被登记成「非迁移语句」,两处一起改才配得上。</p>
*/
// 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<String, Integer> RAW_SQL_IN_WRAPPERS_BASELINE = rawSqlInWrappersBaseline();
/**
* 注解里带动态标签的写 SQL 待迁清单。<b>2026-10-08 已清空</b>——
* {@code <foreach>}/{@code <if>} 这类 Wrapper 表达不了的语句现在只在 XML 里。
* 再往注解里塞动态标签,{@link #noNewComplexWriteSqlInAnnotations} 直接红。
*/
private static final List<String> COMPLEX_WRITE_SQL_BACKLOG = List.of();
/**
* "带写 SQL 又不继承 BaseMapper" 的豁免名单,同样已清空:SQL 进了 XML 之后,
* 接口继不继承实体都不影响语句落地,这条只用来拦"新 mapper 一上来就写裸注解 SQL"。
*/
private static final List<String> 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<String, Integer> rawSqlInWrappersBaseline() {
Map<String, Integer> 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<String, Integer> actual = new LinkedHashMap<>();
Map<String, Integer> 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/<模块>/<Name>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。
*
* <p>{@code last("LIMIT n")} 故意不算越界:MP 的分页 idiomatic 写法就是它,
* 全仓 205 处,把它算成违规只会让守卫第一天就没人管。豁免面由
* {@link #limitExemptionDoesNotHideRealSql} 反向钉住。
*/
@Test
void rawSqlInsideWrappersDoesNotGrow() throws IOException {
Map<String, Integer> 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<String> 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("<script>") || body.contains("<if ")
|| body.contains("<foreach") || body.contains("<set>")) {
complex.add(stem(file));
}
}
}
List<String> unexpected = complex.stream().distinct()
.filter(name -> !COMPLEX_WRITE_SQL_BACKLOG.contains(name))
.collect(Collectors.toList());
assertTrue(unexpected.isEmpty(), () -> "这些 mapper 新写了带动态标签的 SQL 注解:" + unexpected
+ " —— 按约定放进 src/main/resources/mapper/<模块>/<Name>Mapper.xml");
assertEquals(COMPLEX_WRITE_SQL_BACKLOG.stream().sorted().collect(Collectors.toList()),
complex.stream().distinct().sorted().collect(Collectors.toList()),
"复杂写 SQL 的待迁清单变了:迁走一条就同时从 COMPLEX_WRITE_SQL_BACKLOG 划掉");
}
/**
* 反向钉:每扫到一份 mapper XML,它的同名接口就不许再留注解 SQL 或 {@code <script>} 残留。
* 名单由 {@code src/main/resources/mapper} 扫出来,不是手写的——多一份 XML 就自动进守卫,
* 少一份也不会让这条用例悄悄变绿。
*/
@Test
void everyMigratedMapperHasNoAnnotatedSqlLeft() throws IOException {
List<Path> xmls = xmlFiles();
assertFalse(xmls.isEmpty(), "一份 XML 都没扫到,这条守卫就是恒绿的");
for (Path xml : xmls) {
String name = stem(xml);
Path file = findMapperInterface(name);
String text = stripComments(read(file));
int writes = count(WRITE_ANNOTATION, text);
int selects = count(SELECT_ANNOTATION, text);
assertTrue(writes == 0 && selects == 0,
() -> name + " 的语句已在 " + xml.getFileName() + " 里,注解却又出现 "
+ writes + " 条写 SQL / " + selects + " 条 @Select:同名会让 MyBatis 启动期抛重复语句");
assertFalse(text.contains("<script>"),
() -> name + " 的注解里还留着 <script>:迁移只做了一半,调用时才报 no statement");
}
}
@Test
void everyXmlStatementMatchesAnInterfaceMethod() throws IOException {
List<Path> xmls = xmlFiles();
assertFalse(xmls.isEmpty(), "mapper XML 目录是空的——迁移通道没落地,本用例就成了恒绿");
for (Path xml : xmls) {
String text = read(xml);
String namespace = firstGroup(Pattern.compile("namespace=\"([^\"]+)\""), text,
xml + " 缺 namespace(MyBatis 无法把语句绑到接口)");
Path iface = findMapperInterfaceByFqn(namespace);
List<String> statementIds = allGroups(Pattern.compile(
"<(select|insert|update|delete)\\s+id=\"([^\"]+)\""), text, 2);
assertFalse(statementIds.isEmpty(), () -> xml + " 里没有任何语句");
for (String id : statementIds) {
assertTrue(declaredMethods(iface).contains(id),
() -> id + "(" + xml.getFileName() + ")在 " + namespace
+ " 上没有同名方法:启动不报错,调用时才报 no statement");
}
assertEquals(stem(iface), stem(xml), "XML 文件名应与接口名一致,便于按名找 SQL");
}
}
@Test
void newMappersMustBeEntityBacked() throws IOException {
List<String> offenders = new ArrayList<>();
for (Path file : mappers()) {
String text = stripComments(read(file));
if (count(WRITE_ANNOTATION, text) > 0 && !text.contains("BaseMapper<")) {
offenders.add(stem(file));
}
}
assertEquals(MAPPERS_WITHOUT_ENTITY, offenders.stream().distinct().sorted().collect(Collectors.toList()),
() -> "带写 SQL 又不继承 BaseMapper<T> 的 mapper 变了:没有实体就没有 wrapper 入口,"
+ "新 mapper 请 extends BaseMapper<XxxEntity>");
}
/**
* 迁移完成态的分母。归零之后,"注解为空"本身证明不了任何东西(扫描面塌了也空),
* 所以把账本搬到 XML 一侧:语句总数必须是 96(本轮平移 85 + TaskImageCache 9 + AsinResultCache 2),
* 少一条就是搬运中丢了语句,多一条就是有人加了语句没记账。
*/
@Test
void migratedStatementsLandInXmlWithoutLoss() throws IOException {
List<Path> xmls = xmlFiles();
int xmlCount = xmls.size();
assertTrue(xmlCount >= 28, () -> "只扫到 " + xmlCount + " 份 mapper XML,目录不对或文件被挪走");
int statements = 0;
for (Path xml : xmls) {
statements += count(STATEMENT_ID, read(xml));
}
int counted = statements;
assertEquals(XML_STATEMENT_TOTAL, counted,
() -> "mapper XML 里数到 " + counted + " 条语句,账本 " + XML_STATEMENT_TOTAL
+ "(分布在 " + xmlCount + " 份文件)—— 迁移漏了,或加了没记账");
}
@Test
void xmlDirectoryIsActuallyOnTheLoadPath() throws IOException {
Path resources = moduleRoot().resolve("src/main/resources/mapper");
assertTrue(Files.isDirectory(resources), "src/main/resources/mapper 不存在,迁移无处可放");
String yml = read(moduleRoot().resolve("src/main/resources/application.yml"));
assertTrue(yml.replaceAll("\\s+", " ").contains("mapper-locations: classpath*:mapper/**/*.xml"),
"application.yml 的 mapper-locations 变了:XML 会被静默忽略,调用时才报 no statement");
}
// ---------- 判据本体(纯函数,喂字符串即可验,不依赖目录里恰好有什么) ----------
/** 数一段源码里"wrapper 夹带函数级 SQL"的次数;last("LIMIT …") 是允许的写法。 */
static int countRawSqlInWrapper(String text) {
int hits = 0;
Matcher m = Pattern.compile("\\.(apply|inSql|having|last)\\(\\s*(\"[^\"]*\"|[^,)\\n]+,\\s*\")")
.matcher(text);
while (m.find()) {
String tail = text.substring(m.start(), Math.min(text.length(), m.end() + 120));
String upper = tail.toUpperCase();
boolean realSql = upper.contains("JSON_") || upper.contains("FOR UPDATE")
|| upper.contains("SELECT ") || upper.contains("WHERE ")
|| m.group(1).equals("inSql") || m.group(1).equals("having");
if (realSql) {
hits++;
}
}
return hits;
}
// ---------- 取样 ----------
private static List<Path> mappers() throws IOException {
return mainSources().stream()
.filter(p -> p.getFileName().toString().endsWith("Mapper.java"))
.collect(Collectors.toList());
}
private static List<Path> mainSources() throws IOException {
Path root = moduleRoot().resolve("src/main/java");
if (!Files.isDirectory(root)) {
fail("找不到 " + root + " —— 用例依赖以 backend-java 为工作目录运行,别让守卫静默通过");
}
try (Stream<Path> walk = Files.walk(root)) {
return walk.filter(Files::isRegularFile)
.filter(p -> p.getFileName().toString().endsWith(".java"))
.sorted()
.collect(Collectors.toList());
}
}
private static List<Path> xmlFiles() {
try (Stream<Path> walk = Files.walk(moduleRoot().resolve("src/main/resources/mapper"))) {
return walk.filter(Files::isRegularFile)
.filter(p -> p.getFileName().toString().endsWith(".xml"))
.sorted()
.collect(Collectors.toList());
} catch (IOException e) {
throw new IllegalStateException("遍历 mapper XML 失败", e);
}
}
private static Path findMapperInterface(String simpleName) {
try {
return mappers().stream()
.filter(p -> stem(p).equals(simpleName))
.findFirst()
.orElseThrow(() -> new IllegalStateException("找不到 mapper 接口 " + simpleName));
} catch (IOException e) {
throw new IllegalStateException(e);
}
}
private static Path findMapperInterfaceByFqn(String fqn) {
String simpleName = fqn.substring(fqn.lastIndexOf('.') + 1);
Path file = findMapperInterface(simpleName);
assertTrue(read(file).contains("package " + fqn.substring(0, fqn.lastIndexOf('.')) + ";"),
() -> "XML namespace 指向 " + fqn + ",但 " + file + " 不在那个包里");
return file;
}
private static List<String> declaredMethods(Path iface) {
// 只要声明行:形如 "Xxx yyy(" 的方法签名,跳过注解与注释
List<String> names = new ArrayList<>();
for (String raw : stripComments(read(iface)).split("\n", -1)) {
String line = raw.trim();
if (line.isEmpty()) {
continue;
}
Matcher m = Pattern.compile("^[\\w<>?,.\\[\\]\\s]+?\\s(\\w+)\\s*\\(").matcher(line);
if (m.find()) {
names.add(m.group(1));
}
}
return names;
}
private static String firstGroup(Pattern pattern, String text, String message) {
Matcher m = pattern.matcher(text);
if (!m.find()) {
throw new IllegalStateException(message);
}
return m.group(1);
}
private static List<String> allGroups(Pattern pattern, String text, int group) {
List<String> out = new ArrayList<>();
Matcher m = pattern.matcher(text);
while (m.find()) {
out.add(m.group(group));
}
return out;
}
private static int count(Pattern pattern, String text) {
int hits = 0;
Matcher m = pattern.matcher(text);
while (m.find()) {
hits++;
}
return hits;
}
private static String stripComments(String text) {
return text.replaceAll("/\\*[\\s\\S]*?\\*/", "").replaceAll("//[^\\n]*", "");
}
private static String stem(Path path) {
String name = path.getFileName().toString();
return name.substring(0, name.length() - (name.endsWith(".java") ? 5 : 4));
}
private static String read(Path path) {
try {
return Files.readString(path, StandardCharsets.UTF_8);
} catch (IOException e) {
throw new IllegalStateException("读取失败: " + path, e);
}
}
/** surefire 的工作目录是模块目录;从仓库根或 IDE 跑时退到 backend-java/。 */
private static Path moduleRoot() {
Path here = Path.of("").toAbsolutePath();
if (Files.isDirectory(here.resolve("src/main/java"))) {
return here;
}
Path nested = here.resolve("backend-java");
if (Files.isDirectory(nested.resolve("src/main/java"))) {
return nested;
}
throw new IllegalStateException("无法定位 backend-java 模块目录(cwd=" + here + ")");
}
}