refactor(SQL分层): 剩余 85 条注解 SQL 全量迁进 mapper XML,等价性改由 MyBatis 自己判

96 条语句现在全在 src/main/resources/mapper/<模块>/ 下,注解侧 SQL 归零;判据从"基线清单"
改成完成态(逐接口必须为 0 + XML 语句总数 96 + 反向钉:XML 有则注解必须无)。

搬法上踩实了一个坑:注解参数是 Java 表达式("…" + CLIENT_MODULE_TYPES + "…"),
用只认字面量的抽取器搬家会把常量整段吞掉——上一轮生成的 26 份 XML 里因此出现
IN ()、AS status 前面没有表达式(MySQL 语法错),<script> 形态还被多转义一次变成 &amp;lt;。
更糟的是当时"搬迁前快照"与 XML 由同一个抽取器产出,两边一起错所以逐字比对全绿,
抓到现场的是既有的语义用例(TaskCenter 15 条 + 店铺查重那条断 <> 的)。

所以 MigratedSqlEquivalenceTest 改成:账本存注解原文,Java 侧现场用
getDefaultScriptingLanguageInstance().createSqlSource 编译原文,与 XML 解析出的
MappedStatement 各渲染一遍 BoundSql 对撞(空参数 + foreach 喂满 2 元素各一次),
转义对不对由 MyBatis 判定而不是由生成器判定;账本自己再钉 <script>/<if> 成对、不许出现 IN ()。
resultType 那一支不变:期望值由接口签名反射反推,66 条分母钉住。

取数入口跟着换:6 支原本读 @Select 注解的守卫(TaskCenter/Dedupe/店铺查重/通知保留/
鉴权形状/后台扩权)改走 MapperXmlSupport,断言内容一字未动;后台扩权那条"不许有 wrapper
投影"从全文 doesNotContain(".select(") 改成只扫可执行行——接口里现在只剩签名,
而 javadoc 正写着"别用 selectList(.select(...))",全文判会被自己的注释喂饱。

隔离树全量 4059 例 0 红(基线 4054,+5 为新增等价性与 XML 用例)。这批要生效得随下一版 jar 发版。
This commit is contained in:
2026-10-08 12:00:43 +08:00
parent 4d2f3fc754
commit 419ab3be64
62 changed files with 1490 additions and 890 deletions
@@ -0,0 +1,410 @@
package com.nanri.aiimage;
import com.baomidou.mybatisplus.core.MybatisConfiguration;
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.mapping.SqlSource;
import org.junit.jupiter.api.Test;
import java.io.IOException;
import java.io.InputStream;
import java.lang.reflect.GenericArrayType;
import java.lang.reflect.Method;
import java.lang.reflect.ParameterizedType;
import java.lang.reflect.Type;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
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.assertTrue;
import static org.junit.jupiter.api.Assertions.fail;
/**
* 注解 SQL 平移到 mapper XML 的等价性守卫。
*
* <p>基准是<b>搬迁前注解的原文</b>({@code src/test/resources/sql-layering/migrated-statements.tsv},
* 85 条),而且比对发生在 <b>MyBatis 解析之后</b>:把注解原文现场交给
* {@code LanguageDriver.createSqlSource}(注解当年就是走这条路进 MyBatis 的),
* 与 XML 解析出来的 {@code MappedStatement} 各渲染一遍 {@code BoundSql} 再对撞。
* 这样"元素体该怎么转义"由 MyBatis 判定,不由生成脚本判定——
* 上一轮正是拿生成器的输出当基准,同一个解析器错两遍,85 条"逐字相等"全绿而 SQL 已经残缺。
*
* <p>渲染用两组参数各对撞一次:空参数(所有 {@code <if>} 走 false 支)与把
* {@code <foreach collection>} 喂满 2 个元素(动态支展开成 {@code ?,?})。
* 两边同抛异常也算一致,但必须是同一异常类型与同一消息,不许一边过一边炸。
*
* <p>第二支管 {@code resultType}:期望类型由反射从接口签名反推,不由生成脚本算,
* 避免"生成时解错、断言时照着错的对"。
*/
class MigratedSqlEquivalenceTest {
private static final String FIXTURE = "sql-layering/migrated-statements.tsv";
private static final int LEDGER_ROWS = 85;
private static final int LEDGER_SELECTS = 60;
/** 全部 mapper XML 里的 select 总数:账本 60 + TaskImageCache 5 + AsinResultCache 1。 */
private static final int XML_SELECT_TOTAL = 66;
/** 账本 5 列:接口 / 方法 / @Select 种类 / 是否含常量插值 / 注解原文(Java 反转义后那条串)。 */
private static final int LEDGER_COLUMNS = 5;
private static final int BASELINE_COL = 4;
private static final Pattern STATEMENT = Pattern.compile(
"(?is)<(select|insert|update|delete)\\s+id=\"([A-Za-z0-9_]+)\"([^>]*)>(.*?)</\\1>");
private static final Pattern RESULT_TYPE = Pattern.compile("resultType=\"([^\"]+)\"");
private static final Pattern FOREACH_COLLECTION = Pattern.compile("collection=[\"'](\\w+)[\"']");
private static final Pattern TEST_NAME = Pattern.compile("test=[\"']([^\"']*)[\"']");
private static final Pattern HASH_PARAM = Pattern.compile("#\\{\\s*([A-Za-z_]\\w*)");
/** OGNL 里的字面量与方法名不是参数名,喂值进去会让两边同时以错误告终。 */
private static final Set<String> OGNL_WORDS =
Set.of("null", "true", "false", "and", "or", "not", "size", "isEmpty", "equals", "length");
@Test
void ledgerItselfIsTheExpectedShape() throws IOException {
List<String[]> rows = readLedger();
assertEquals(LEDGER_ROWS, rows.size(), "fixture 行数变了——它是搬迁前的快照,不该跟着代码漂");
assertEquals(LEDGER_SELECTS, rows.stream().filter(r -> "Select".equals(r[2])).count(),
"fixture 里的 Select 条数与基线不符(读侧账本 = 60)");
assertEquals(LEDGER_ROWS - LEDGER_SELECTS,
rows.stream().filter(r -> !"Select".equals(r[2])).count(),
"写侧条数对不上(25 = Insert+Update+Delete)");
assertTrue(rows.stream().allMatch(r -> !r[1].isEmpty() && !r[BASELINE_COL].isEmpty()),
"fixture 有空方法名或空 SQL,说明抽取器漏了形状");
// 基准得是「整条注解串」:半截 <script> 外壳说明抽取被截断(上一轮就是把常量与标签吃了)
assertTrue(rows.stream().allMatch(r ->
r[BASELINE_COL].startsWith("<script>") == r[BASELINE_COL].contains("</script>")),
"有基准行的 <script> 外壳不成对——抽取时注解表达式被截断了");
assertTrue(rows.stream().allMatch(r ->
r[BASELINE_COL].contains("<if") == r[BASELINE_COL].contains("</if>")),
"有基准行的 <if> 不成对——常量插值没展开");
assertTrue(rows.stream().noneMatch(r -> r[BASELINE_COL].contains("IN ()")),
"有基准行出现空的 IN (),说明 foreach/常量被吞了");
}
@Test
void everyMigratedStatementRendersTheSameSqlAsTheAnnotationDid() throws Exception {
Map<String, String> baselines = new LinkedHashMap<>();
Map<String, String> kinds = new LinkedHashMap<>();
for (String[] row : readLedger()) {
baselines.put(row[0] + "#" + row[1], unescapeJava(row[4]));
kinds.put(row[0] + "#" + row[1], row[2].toLowerCase());
}
List<String> problems = new ArrayList<>();
int checked = 0;
for (Path xml : mapperXmls()) {
String iface = stem(xml);
if (!baselines.keySet().stream().anyMatch(k -> k.startsWith(iface + "#"))) {
continue; // TaskImageCache / AsinResultCache 由各自用例钉,不在这本账里
}
Class<?> mapperClass = Class.forName(namespaceOf(xml));
MybatisConfiguration configuration = parseInto(xml, new MybatisConfiguration());
Matcher m = STATEMENT.matcher(read(xml));
while (m.find()) {
String key = iface + "#" + m.group(2);
String baseline = baselines.get(key);
if (baseline == null) {
problems.add(key + " 在基准账本里没有对应注解(XML 多出一条语句)");
continue;
}
checked++;
if (!kinds.get(key).equals(m.group(1))) {
problems.add(key + " 注解是 @" + kinds.get(key) + ",XML 用了 <" + m.group(1) + ">");
continue;
}
MappedStatement fromXml =
configuration.getMappedStatement(mapperClass.getName() + "." + m.group(2));
// 注解当年就是走这条驱动进 MyBatis 的(MapperAnnotationBuilder 用的正是默认脚本语言),
// 所以这里拿它现场编译基准串,等价性由 MyBatis 判定而不是由生成脚本判定。
SqlSource fromAnnotation = configuration.getDefaultScriptingLanguageInstance()
.createSqlSource(configuration, baseline, Object.class);
for (Map<String, Object> params : renderParams(baseline)) {
String where = key + "(" + params.get("_case") + ")";
compare(fromXml.getBoundSql(params), fromAnnotation.getBoundSql(params), where, problems);
}
}
}
int checkedRows = checked;
assertEquals(LEDGER_ROWS, checkedRows,
() -> "只比对了 " + checkedRows + " 条,其余没在 XML 里落地(应为 " + LEDGER_ROWS + " 条)");
assertTrue(problems.isEmpty(),
() -> "这些语句搬完之后 MyBatis 渲染出的 SQL 与注解时不同(" + problems.size() + " 处):"
+ System.lineSeparator() + String.join(System.lineSeparator(), problems));
}
/** 两边各渲染一次:都出 SQL 就逐字比,都抛就比异常,一边过一边炸必须算问题。 */
private static void compare(BoundSql a, BoundSql b, String where, List<String> problems) {
String sqlA, sqlB;
try {
sqlA = normalize(a.getSql());
} catch (RuntimeException e) {
problems.add(where + " XML 侧渲染就抛:" + e);
return;
}
try {
sqlB = normalize(b.getSql());
} catch (RuntimeException e) {
problems.add(where + " 注解侧渲染抛 " + e.getClass().getSimpleName()
+ " 而 XML 侧正常出 SQL: " + sqlA);
return;
}
if (!sqlA.equals(sqlB)) {
problems.add(where + System.lineSeparator()
+ " 注解渲染: " + sqlB + System.lineSeparator()
+ " XML 渲染 : " + sqlA);
return;
}
if (a.getParameterMappings().size() != b.getParameterMappings().size()) {
problems.add(where + " 占位符数不同:注解 " + b.getParameterMappings().size()
+ " vs XML " + a.getParameterMappings().size() + " —— " + sqlA);
}
}
/** 空参数走所有 <if> 的 false 支;再喂满 foreach 走动态支。两支都要两边一致。 */
private static List<Map<String, Object>> renderParams(String baseline) {
Map<String, Object> full = new HashMap<>();
Set<String> collections = new java.util.LinkedHashSet<>();
Matcher fc = FOREACH_COLLECTION.matcher(baseline);
while (fc.find()) {
collections.add(fc.group(1));
}
Set<String> names = new java.util.LinkedHashSet<>(collections);
Matcher t = TEST_NAME.matcher(baseline);
while (t.find()) {
Matcher word = Pattern.compile("\\w+").matcher(t.group(1));
while (word.find()) {
String w = word.group();
if (!OGNL_WORDS.contains(w)) {
names.add(w);
}
}
}
Matcher h = HASH_PARAM.matcher(baseline);
while (h.find()) {
names.add(h.group(1));
}
for (String name : names) {
full.put(name, collections.contains(name) ? List.of("a", "b") : "v");
}
return List.of(Map.of("_case", "空参数"), Map.of("_case", "带参数"))
.stream().map(marker -> {
Map<String, Object> params =
new HashMap<>("_case".equals(marker.get("_case")) ? Map.of() : full);
params.putAll(marker);
return params;
}).collect(Collectors.toList());
}
/** resultType 必须与接口方法签名一致;期望值由反射算,不用生成脚本的结论。 */
@Test
void everySelectKeepsTheReturnTypeItsAnnotationHad() throws Exception {
List<String> problems = new ArrayList<>();
int checked = 0;
for (Path xml : mapperXmls()) {
String text = read(xml);
Matcher ns = Pattern.compile("namespace=\"([^\"]+)\"").matcher(text);
if (!ns.find()) {
problems.add(xml + " 缺 namespace");
continue;
}
Class<?> iface = Class.forName(ns.group(1));
MybatisConfiguration configuration = parseInto(xml, new MybatisConfiguration());
Matcher m = STATEMENT.matcher(text);
while (m.find()) {
if (!"select".equals(m.group(1))) {
continue;
}
String method = m.group(2);
checked++;
MappedStatement statement =
configuration.getMappedStatement(iface.getName() + "." + method);
Class<?> resolved = statement.getResultMaps().get(0).getType();
Matcher attrs = RESULT_TYPE.matcher(m.group(3));
String declared = attrs.find() ? attrs.group(1) : null;
if (declared == null) {
problems.add(iface.getSimpleName() + "#" + method + " 的 <select> 没写 resultType");
continue;
}
Class<?> expected = expectedType(iface, method);
if (expected == null) {
problems.add(iface.getSimpleName() + "#" + method + " 找不到接口方法签名");
} else if (!compatible(expected, resolved)) {
problems.add(iface.getSimpleName() + "#" + method
+ " resultType=" + declared + " 解析成 " + resolved.getName()
+ ",而方法签名要的是 " + expected.getName());
}
}
}
int checkedSelects = checked;
assertTrue(problems.isEmpty(), () -> "resultType 与接口签名不一致(" + problems.size() + " 条):"
+ System.lineSeparator() + String.join(System.lineSeparator(), problems));
// 这支扫的是全部 mapper XML,所以分母比账本大:本轮 60 + TaskImageCache 5 + AsinResultCache 1
assertEquals(XML_SELECT_TOTAL, checkedSelects,
() -> "只检查了 " + checkedSelects + " 条 select,应为 " + XML_SELECT_TOTAL
+ " 条(正则或 XML 漂了)");
}
/** 只把 XML 解析进配置:XMLMapperBuilder 会顺带按 namespace 绑上接口。 */
private static MybatisConfiguration parseInto(Path xml, MybatisConfiguration configuration)
throws IOException {
try (InputStream in = Files.newInputStream(xml)) {
new XMLMapperBuilder(in, configuration, xml.toString(),
configuration.getSqlFragments()).parse();
}
return configuration;
}
private static Class<?> expectedType(Class<?> iface, String method) {
for (Method m : iface.getDeclaredMethods()) {
if (!m.getName().equals(method)) {
continue;
}
return unwrap(m.getGenericReturnType());
}
return null;
}
/** List<X> / Set<X> / Collection<X> 取 X;byte[] 原样;泛型数组元素再解一层。 */
private static Class<?> unwrap(Type type) {
if (type instanceof ParameterizedType pt) {
Type raw = pt.getRawType();
if (raw instanceof Class<?> c && (c == List.class || c == java.util.Set.class
|| c == java.util.Collection.class || c == Iterable.class)) {
return unwrap(pt.getActualTypeArguments()[0]);
}
return (Class<?>) raw;
}
if (type instanceof GenericArrayType ga) {
Class<?> component = unwrap(ga.getGenericComponentType());
if (component == byte.class) {
return byte[].class;
}
return java.lang.reflect.Array.newInstance(component, 0).getClass();
}
if (type instanceof Class<?> c) {
if (c == long.class) {
return Long.class;
}
if (c == int.class) {
return Integer.class;
}
if (c == boolean.class) {
return Boolean.class;
}
if (c == double.class) {
return Double.class;
}
return c;
}
return Object.class;
}
private static boolean compatible(Class<?> expected, Class<?> resolved) {
if (expected == resolved) {
return true;
}
if (Map.class.isAssignableFrom(expected)) {
return Map.class.isAssignableFrom(resolved);
}
return resolved != null && expected.isAssignableFrom(resolved);
}
private static List<String[]> readLedger() throws IOException {
try (InputStream in = Resources.getResourceAsStream(FIXTURE)) {
String text = new String(in.readAllBytes(), StandardCharsets.UTF_8);
List<String[]> rows = new ArrayList<>();
for (String line : text.split("\n")) {
if (line.isBlank()) {
continue;
}
String[] cols = line.split("\t", -1);
if (cols.length != 5) {
throw new IllegalStateException("fixture 列数不对: " + line.substring(0,
Math.min(80, line.length())));
}
rows.add(cols);
}
return rows;
}
}
private static List<Path> mapperXmls() throws IOException {
Path dir = moduleRoot().resolve("src/main/resources/mapper");
if (!Files.isDirectory(dir)) {
fail("找不到 " + dir + " —— 本用例依赖以 backend-java 为工作目录运行");
}
try (Stream<Path> walk = Files.walk(dir)) {
return walk.filter(p -> p.getFileName().toString().endsWith(".xml"))
.sorted().collect(Collectors.toList());
}
}
private static String namespaceOf(Path xml) {
Matcher m = Pattern.compile("namespace=\"([^\"]+)\"").matcher(read(xml));
if (!m.find()) {
throw new IllegalStateException(xml + " 缺 namespace");
}
return m.group(1);
}
/** tsv 里的基准行是 Java 转义过的(一行一条),还原成注解当年真正的那个字符串。 */
private static String unescapeJava(String s) {
StringBuilder out = new StringBuilder(s.length());
for (int i = 0; i < s.length(); i++) {
char c = s.charAt(i);
if (c == '\\' && i + 1 < s.length()) {
char n = s.charAt(++i);
switch (n) {
case 'n' -> out.append('\n');
case 't' -> out.append('\t');
case 'r' -> out.append('\r');
case '\\' -> out.append('\\');
default -> out.append(n);
}
continue;
}
out.append(c);
}
return out.toString();
}
private static String normalize(String text) {
return text.replaceAll("\\s+", " ").trim();
}
private static String read(Path path) {
try {
return Files.readString(path, StandardCharsets.UTF_8);
} catch (IOException e) {
throw new IllegalStateException("读取失败: " + path, e);
}
}
private static String stem(Path path) {
String name = path.getFileName().toString();
return name.substring(0, name.length() - 4);
}
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 + ")");
}
}
@@ -44,16 +44,23 @@ import static org.junit.jupiter.api.Assertions.fail;
*/
class SqlLayeringConventionTest {
/** 写 SQL(@Insert/@Update/@Delete)在注解里的现状清单:文件名 → 条数。只许减,不许加。 */
private static final Map<String, Integer> WRITE_SQL_BASELINE = writeSqlBaseline();
/**
* 注解里的写 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 实测 65 条 / 16 个接口,迁走 TaskImageCacheMapper 后 60 / 15)。
* 注解里的读 SQL 清单,同样在 2026-10-08 迁完归零。
*
* <p>为什么从"总数 + 文件数"两个标量改成逐接口:标量守恒的是**和**,A 接口减一条、
* B 接口加一条时两个标量都不动,闸门照样绿——档 B 口径下这等于没有闸门。
* <p>保留逐接口形态(而不是退回一个"总数 0")是有原因的:以前钉"总数 + 文件数"两个标量时,
* A 接口加一条配 B 接口减一条两个标量都不动,闸门形同虚设;逐接口清单在迁移期就是账本,
* 迁完后它继续保证"不许在某个接口里悄悄攒回来"。
*/
private static final Map<String, Integer> SELECT_SQL_BASELINE = selectSqlBaseline();
private static final Map<String, Integer> SELECT_SQL_BASELINE = new LinkedHashMap<>();
/** 迁移完成态的分母:XML 里应有的语句总数(85 本轮 + 9 TaskImageCache + 2 AsinResultCache)。 */
private static final int XML_STATEMENT_TOTAL = 96;
/**
* wrapper 里夹带函数级 SQL 的现状("这不是简单单表"的证据),文件名 → 条数:
@@ -62,65 +69,24 @@ class SqlLayeringConventionTest {
private static final Map<String, Integer> RAW_SQL_IN_WRAPPERS_BASELINE = rawSqlInWrappersBaseline();
/**
* 其中"复杂"的写 SQL(注解正文含动态标签)——Wrapper 表达不了(批量/INSERT…SELECT/upsert),
* 按约定应迁到 XML。这是待迁 backlog,不是许可名单:迁走一条要同时从这里划掉。
* 注解里带动态标签的写 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(
"CollectDataItemMapper", "DedupeTotalDataMapper", "InvalidAsinDataMapper",
"UserColumnPermissionMapper", "PublishItemMapper", "ShopDataCrawlItemMapper",
"QueryAsinMapper", "TaskResultItemMapper");
private static final List<String> COMPLEX_WRITE_SQL_BACKLOG = List.of();
/** 唯一没有实体可走的 mapper:连 wrapper 的入口都没有,所以只能写裸 SQL。 */
private static final List<String> MAPPERS_WITHOUT_ENTITY = List.of("UserColumnPermissionMapper");
/** 已经迁到 XML 的:反向钉住"不许再用注解把 SQL 写回来"(注解 + XML 同名会让启动期抛重复语句)。 */
private static final List<String> MIGRATED_TO_XML = List.of("AsinResultCacheMapper", "TaskImageCacheMapper");
/**
* "带写 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 Map<String, Integer> writeSqlBaseline() {
Map<String, Integer> baseline = new LinkedHashMap<>();
baseline.put("CollectDataItemMapper", 1);
baseline.put("DedupeTotalDataMapper", 1);
baseline.put("DeviceLogFileMapper", 1);
baseline.put("ImageVideoAsyncTaskMapper", 3);
baseline.put("InvalidAsinDataMapper", 1);
baseline.put("UserNotificationMapper", 2);
baseline.put("UserColumnPermissionMapper", 4);
baseline.put("PriceTrackLoopRunMapper", 1);
baseline.put("PublishItemMapper", 1);
baseline.put("ShopDataCrawlItemMapper", 4);
baseline.put("ShopDataDuplicateScanMapper", 1);
baseline.put("QueryAsinMapper", 1);
baseline.put("SoftwareVersionMapper", 1);
baseline.put("TaskResultItemMapper", 1);
baseline.put("UserSecretUsageMapper", 2);
return baseline;
}
/** 读侧基线:TaskImageCacheMapper 的 5 条已在 mapper/task/TaskImageCacheMapper.xml 里。 */
private static Map<String, Integer> selectSqlBaseline() {
Map<String, Integer> 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 final Pattern STATEMENT_ID =
Pattern.compile("<(?:select|insert|update|delete)\\s+id=\"[^\"]+\"");
private static Map<String, Integer> rawSqlInWrappersBaseline() {
Map<String, Integer> baseline = new LinkedHashMap<>();
@@ -147,17 +113,17 @@ class SqlLayeringConventionTest {
actualSelects.put(stem(file), read);
}
}
assertEquals(WRITE_SQL_BASELINE, actual, () -> "注解里的写 SQL 清单变了。" + System.lineSeparator()
+ " 新增 → 写进 src/main/resources/mapper/<模块>/<Name>Mapper.xml;"
+ "简单单表才用 BaseMapper/实体(wrapper)。" + System.lineSeparator()
+ " 迁走 → 把这一项从 WRITE_SQL_BASELINE 里减掉,让减法出现在 diff 上。");
assertFalse(actual.isEmpty(), "清单为空说明本用例没扫到任何 mapper,判据本身坏了");
assertEquals(SELECT_SQL_BASELINE, actualSelects, () -> "注解里的 @Select 逐接口清单变了(读侧同样 XML 优先)。"
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 接口加一条在这种钉法下会直接红。"
+ System.lineSeparator()
+ " 当前实测:" + actualSelects);
assertFalse(actualSelects.isEmpty(), "读侧清单为空说明正则或目录坏了——恒绿的闸门比没有闸门更糟");
+ " A 接口加一条配 B 接口减一条在这种逐接口钉法下会直接红。当前实测:" + actualSelects);
// 归零之后不能拿"清单为空"当自证,分母改由扫描面本身提供
int scanned = mappers().size();
assertTrue(scanned >= 60,
() -> "只扫到 " + scanned + " 个 *Mapper.java,多半是目录或工作目录坏了——"
+ "扫描面塌了的话上面两个 assertEquals(空表) 就成了恒绿");
}
/**
@@ -220,19 +186,26 @@ class SqlLayeringConventionTest {
"复杂写 SQL 的待迁清单变了:迁走一条就同时从 COMPLEX_WRITE_SQL_BACKLOG 划掉");
}
/**
* 反向钉:每扫到一份 mapper XML,它的同名接口就不许再留注解 SQL 或 {@code <script>} 残留。
* 名单由 {@code src/main/resources/mapper} 扫出来,不是手写的——多一份 XML 就自动进守卫,
* 少一份也不会让这条用例悄悄变绿。
*/
@Test
void everyMigratedMapperHasNoAnnotatedSqlLeft() {
for (String name : MIGRATED_TO_XML) {
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));
assertFalse(count(WRITE_ANNOTATION, text) > 0,
() -> name + " 已迁到 XML,注解里却又出现写 SQL:同名会让 MyBatis 启动期抛重复语句");
assertFalse(count(SELECT_ANNOTATION, text) > 0,
() -> name + " 已迁到 XML,注解里却又出现 @Select:" + name);
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");
assertTrue(xmlFiles().stream().anyMatch(x -> stem(x).equals(name)),
() -> name + " 声称已迁 XML,但 src/main/resources/mapper 下没有同名文件");
() -> name + " 的注解里还留着 <script>:迁移只做了一半,调用时才报 no statement");
}
}
@@ -272,25 +245,23 @@ class SqlLayeringConventionTest {
}
/**
* 这条是给"逐文件清单"这次改动自证的:以前钉的是总数 65 + 文件数 16 两个标量,
* 于是 A 接口加一条、B 接口减一条就能让两个标量双双不动而绕过闸门。
* 这里在内存里造出那次搬家——总和仍是基线总和,清单必须不等。
* 迁移完成态的分母。归零之后,"注解为空"本身证明不了任何东西(扫描面塌了也空),
* 所以把账本搬到 XML 一侧:语句总数必须是 96(本轮平移 85 + TaskImageCache 9 + AsinResultCache 2),
* 少一条就是搬运中丢了语句,多一条就是有人加了语句没记账。
*/
@Test
void thePerFileLedgerCatchesWhatTheScalarsCouldNot() {
int baselineTotal = SELECT_SQL_BASELINE.values().stream().mapToInt(Integer::intValue).sum();
assertTrue(baselineTotal > 0, "基线本身是空的,下面的断言就是恒真");
Map<String, Integer> 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),
"逐文件清单没看见这次搬家——说明它退化成了标量比较");
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
@@ -3,6 +3,9 @@ package com.nanri.aiimage.common.security;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.fail;
import com.nanri.aiimage.common.mapper.AdminUserMapper;
import com.nanri.aiimage.testutil.MapperXmlSupport;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
@@ -76,13 +79,15 @@ class AuthChainQueryShapeTest {
assertThat(service).doesNotContain("selectList(");
String mapper = read(sourceNamed("AdminUserMapper.java"));
Matcher method = Pattern.compile(
"LocalDateTime selectCompanySuperAdminEarliestExpiry\\([\\s\\S]{0,400}").matcher(mapper);
assertThat(method.find()).as("mapper 里那个标量方法还在").isTrue();
assertThat(mapper).contains("MIN(expires_at)");
assertThat(mapper).contains("LocalDateTime selectCompanySuperAdminEarliestExpiry(");
// 2026-10-08 SQL 迁进 mapper XML:断言内容一字未动,取文本的入口换到语句体本身。
// 顺带去掉原来那个「方法名起 400 字符」的定宽窗口——它会截错,也会因上面多一行注释而失明。
String sql = MapperXmlSupport.statementBody(AdminUserMapper.class,
"selectCompanySuperAdminEarliestExpiry");
assertThat(sql).contains("MIN(expires_at)");
// 判据必须仍锁死在"本公司 + 公司超管",扩到全站会把别家的到期算进这家
assertThat(mapper).contains("role = 'company_super_admin'");
assertThat(mapper).contains("company_id = #{companyId}");
assertThat(sql).contains("role = 'company_super_admin'");
assertThat(sql).contains("company_id = #{companyId}");
}
private static List<Path> scannedSources() throws IOException {
@@ -3,6 +3,9 @@ package com.nanri.aiimage.common.security;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.fail;
import com.nanri.aiimage.common.mapper.AdminUserMapper;
import com.nanri.aiimage.testutil.MapperXmlSupport;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
@@ -214,14 +217,20 @@ class ConsoleWideningGuardrailTest {
String mapper = read(mainSource("common/mapper/AdminUserMapper.java"));
int at = mapper.indexOf("Long countAdminMenuGrants(");
assertThat(at).as("入口探针方法还在").isGreaterThan(0);
String head = mapper.substring(Math.max(0, at - 400), at);
assertThat(head).contains("SELECT COUNT(1)");
assertThat(head).doesNotContain(".select(");
// 探针必须仍限定本公司:否则别家公司的授权能给这条账号开门
assertThat(head).contains("cm.company_id");
assertThat(head).contains("ucp.user_id = #{userId}");
assertThat(head).contains("cm.menu_type = 'admin'");
assertThat(mapper.substring(at)).contains("@Param(\"companyId\")");
// 2026-10-08 SQL 迁进 mapper XML:断言内容一字未动,只把取文本的入口换到语句体本身,
// 顺带去掉"方法名前 400 字符"那个定宽窗口(会截错,也会因注释变长而失明)。
String sql = MapperXmlSupport.statementBody(AdminUserMapper.class, "countAdminMenuGrants");
assertThat(sql).contains("SELECT COUNT(1)");
// 探针必须仍限定本公司:否则别家公司的授权能给这条账号开门
assertThat(sql).contains("cm.company_id");
assertThat(sql).contains("ucp.user_id = #{userId}");
assertThat(sql).contains("cm.menu_type = 'admin'");
// 接口侧不许出现 wrapper 投影写法。SQL 搬进 XML 后接口只剩签名与 javadoc,
// 而 javadoc 里就写着「别用 selectList(.select(columnId))」这段教训——只扫可执行行,
// 否则这条断言会被自己的注释喂饱(注释越长越像"有问题",那不是它该管的事)。
assertThat(executableLinesContaining(mapper, ".select("))
.as("mapper 源码读到了(上面 indexOf 已证),这里必须是零命中").isEmpty();
}
/** 自检:扫描面与两个分母都必须是实打实的非空,且页面门/豁免恰好铺满入口门清单。 */
@@ -1,14 +1,12 @@
package com.nanri.aiimage.modules.dedupe.mapper;
import com.baomidou.mybatisplus.core.MybatisConfiguration;
import com.nanri.aiimage.modules.dedupe.model.entity.DedupeTotalDataEntity;
import org.apache.ibatis.builder.annotation.MapperAnnotationBuilder;
import com.nanri.aiimage.testutil.MapperXmlSupport;
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.lang.reflect.Method;
import java.util.List;
import java.util.Map;
@@ -22,7 +20,7 @@ import static org.junit.jupiter.api.Assertions.assertTrue;
* <p>为什么必须单独有一支:服务层测试用 mock 捕获的是实体对象,看不到最终 SQL——本表写侧
* 靠的是注解里的列清单(不是 MyBatis-Plus 的实体字段推导),把 {@code company_id} 从清单里漏掉
* 或把 {@code #{row.companyId}} 写成 {@code ${...}} 都是"SQL 变了而 service 测试照样绿"。
* 走 {@code MapperAnnotationBuilder} 解析注解、向真 {@code BoundSql} 断言,
* 走真 {@code XMLMapperBuilder} 解析 mapper XML、向真 {@code BoundSql} 断言,
* 口径照抄 {@code ShopDataDuplicateCheckCompanyScopeTest#boundSqlFor}。</p>
*/
class DedupeTotalDataMapperSqlTest {
@@ -46,11 +44,10 @@ class DedupeTotalDataMapperSqlTest {
}
private static BoundSql boundSqlFor(int rowCount) throws Exception {
Method method = DedupeTotalDataMapper.class.getMethod("insertBatchIgnore", List.class);
String script = String.join(" ", method.getAnnotation(org.apache.ibatis.annotations.Insert.class).value());
assertTrue(script.contains("company_id"), "注解原文应含 company_id(生成 SQL 才可能含): " + script);
Configuration configuration = new MybatisConfiguration();
new MapperAnnotationBuilder(configuration, DedupeTotalDataMapper.class).parse();
// SQL 已从注解迁到 mapper XML(档 B 口径),原文与语句都要从 XML 那侧取
String script = MapperXmlSupport.statementBody(DedupeTotalDataMapper.class, "insertBatchIgnore");
assertTrue(script.contains("company_id"), "XML 语句体应含 company_id(生成 SQL 才可能含): " + script);
Configuration configuration = MapperXmlSupport.configurationWith(DedupeTotalDataMapper.class);
MappedStatement statement = configuration.getMappedStatement(
DedupeTotalDataMapper.class.getName() + ".insertBatchIgnore");
List<DedupeTotalDataEntity> rows = new java.util.ArrayList<>(rowCount);
@@ -3,10 +3,11 @@ package com.nanri.aiimage.modules.notification.service;
import com.nanri.aiimage.common.service.DistributedJobLockService;
import com.nanri.aiimage.config.NotificationProperties;
import com.nanri.aiimage.modules.notification.mapper.UserNotificationMapper;
import org.apache.ibatis.annotations.Delete;
import com.nanri.aiimage.testutil.MapperXmlSupport;
import org.junit.jupiter.api.Test;
import org.mockito.ArgumentCaptor;
import java.io.IOException;
import java.time.Duration;
import java.time.LocalDateTime;
import java.util.List;
@@ -153,13 +154,10 @@ class NotificationRetentionServiceTest {
private static String deleteSqlOf(String methodName) {
try {
Delete delete = UserNotificationMapper.class
.getMethod(methodName, LocalDateTime.class, int.class)
.getAnnotation(Delete.class);
assertThat(delete).as("%s 上的 @Delete 注解", methodName).isNotNull();
return String.join(" ", delete.value());
} catch (NoSuchMethodException ex) {
throw new AssertionError(ex);
// SQL 已在 mapper XML 里(档 B 口径),取原文的入口跟着换到 XML 侧
return MapperXmlSupport.statementBody(UserNotificationMapper.class, methodName);
} catch (IOException | RuntimeException ex) {
throw new AssertionError(methodName + " 的 DELETE 语句在 mapper XML 里取不到", ex);
}
}
}
@@ -8,16 +8,13 @@ import static org.mockito.Mockito.never;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
import com.baomidou.mybatisplus.core.MybatisConfiguration;
import com.nanri.aiimage.modules.shopduplicatecheck.TestFixtures;
import com.nanri.aiimage.modules.shopduplicatecheck.mapper.ShopDuplicateCheckSourceMapper;
import java.lang.reflect.Method;
import com.nanri.aiimage.testutil.MapperXmlSupport;
import java.util.Arrays;
import java.util.List;
import java.util.Map;
import java.util.Set;
import org.apache.ibatis.annotations.Select;
import org.apache.ibatis.builder.annotation.MapperAnnotationBuilder;
import org.apache.ibatis.mapping.BoundSql;
import org.apache.ibatis.mapping.MappedStatement;
import org.apache.ibatis.session.Configuration;
@@ -166,13 +163,9 @@ class ShopDataDuplicateCheckCompanyScopeTest {
}
private static BoundSql boundSqlFor(List<Long> memberIds) throws Exception {
Method method = ShopDuplicateCheckSourceMapper.class
.getMethod("selectShopNamesOwnedBy", List.class);
String script = String.join(" ", method.getAnnotation(Select.class).value());
Configuration configuration = new MybatisConfiguration();
// 走注解构建器的同一条路径:把这条语句注册进 configuration,再向它要 BoundSql
new MapperAnnotationBuilder(configuration, ShopDuplicateCheckSourceMapper.class)
.parse();
// SQL 已迁进 mapper XML:addMapper()/MapperAnnotationBuilder 都拿不到它,
// 必须用 MapperXmlSupport 把接口与同名 XML 一起装进配置。
Configuration configuration = MapperXmlSupport.configurationWith(ShopDuplicateCheckSourceMapper.class);
MappedStatement statement = configuration.getMappedStatement(
ShopDuplicateCheckSourceMapper.class.getName() + ".selectShopNamesOwnedBy");
return statement.getBoundSql(Map.of("memberIds", memberIds));
@@ -1,11 +1,13 @@
package com.nanri.aiimage.modules.taskcenter.mapper;
import com.baomidou.mybatisplus.core.MybatisConfiguration;
import com.nanri.aiimage.testutil.MapperXmlSupport;
import org.apache.ibatis.mapping.BoundSql;
import org.apache.ibatis.mapping.MappedStatement;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import java.io.IOException;
import java.time.LocalDateTime;
import java.util.HashMap;
import java.util.List;
@@ -28,9 +30,10 @@ class TaskCenterQueryMapperSqlTest {
private static MybatisConfiguration configuration;
@BeforeAll
static void setUp() {
configuration = new MybatisConfiguration();
configuration.addMapper(TaskCenterQueryMapper.class);
static void setUp() throws IOException {
// 2026-10-08 SQL 迁进 mapper XML:addMapper() 只会装 BaseMapper 的内置方法,
// 自定义语句必须由 MapperXmlSupport 把同名 XML 一起装进来。
configuration = MapperXmlSupport.configurationWith(TaskCenterQueryMapper.class);
}
private static BoundSql render(String method, Map<String, Object> params) {
@@ -0,0 +1,104 @@
package com.nanri.aiimage.testutil;
import com.baomidou.mybatisplus.core.MybatisConfiguration;
import org.apache.ibatis.builder.xml.XMLMapperBuilder;
import org.apache.ibatis.io.Resources;
import org.apache.ibatis.session.Configuration;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
import java.util.stream.Stream;
/**
* 给"钉 SQL 形状"的用例用的取数通道:SQL 已从注解搬进 mapper XML(档 B 口径,2026-10-08),
* 所以这类用例不能再靠 {@code method.getAnnotation(Select.class).value()} 或只
* {@code addMapper()} 拿语句——那两条路现在分别给出 NPE 和"语句不存在"。
*
* <p>注意 {@code addMapper()} 自己不会加载我们这份 XML:MyBatis 只按
* {@code com/…/mapper/XxxMapper.xml} 这个同名路径去找,而我们的语句在
* {@code src/main/resources/mapper/<模块>/XxxMapper.xml}(由 {@code mybatis-plus.mapper-locations}
* 在运行期扫进来)。所以这里显式把两份都装进同一个 Configuration。
*/
public final class MapperXmlSupport {
private static final Pattern STATEMENT = Pattern.compile(
"(?is)<(select|insert|update|delete)\\s+id=\"%s\"[^>]*>(.*?)</\\1>");
private MapperXmlSupport() {
}
/** 装好接口(BaseMapper 的内置方法)与同名 XML(自定义语句)的配置,供取 BoundSql。 */
public static MybatisConfiguration configurationWith(Class<?> mapper) throws IOException {
MybatisConfiguration configuration = new MybatisConfiguration();
configuration.addMapper(mapper);
Path xml = xmlOf(mapper);
try (InputStream in = Files.newInputStream(xml)) {
new XMLMapperBuilder(in, configuration, xml.toString(),
configuration.getSqlFragments()).parse();
}
return configuration;
}
/** 取某条语句在 XML 里的原文(实体已还原),断言比较符/转义是否落地时用这支。 */
public static String statementBody(Class<?> mapper, String method) throws IOException {
Matcher m = Pattern.compile(String.format(STATEMENT.pattern(), Pattern.quote(method)))
.matcher(read(xmlOf(mapper)));
if (!m.find()) {
throw new IllegalStateException(mapper.getSimpleName() + "#" + method
+ " 在 " + xmlOf(mapper) + " 里没有语句");
}
return unescape(m.group(2));
}
private static Path xmlOf(Class<?> mapper) throws IOException {
String wanted = mapper.getSimpleName() + ".xml";
List<Path> hits;
Path dir = moduleRoot().resolve("src/main/resources/mapper");
if (!Files.isDirectory(dir)) {
throw new IllegalStateException("找不到 " + dir + " —— 本 helper 依赖以 backend-java 为工作目录运行");
}
try (Stream<Path> walk = Files.walk(dir)) {
hits = walk.filter(p -> p.getFileName().toString().equals(wanted)).collect(Collectors.toList());
}
if (hits.isEmpty()) {
throw new IllegalStateException(mapper.getSimpleName() + " 没有对应的 mapper XML:"
+ "SQL 若还在注解里就不该走这支,若在 XML 里请检查文件名与接口名是否逐字一致");
}
if (hits.size() > 1) {
throw new IllegalStateException("同名 mapper XML 有 " + hits.size() + " 份:" + hits);
}
return hits.get(0);
}
private static String unescape(String text) {
return text.replace("&lt;", "<").replace("&gt;", ">").replace("&amp;", "&");
}
private static String read(Path path) throws IOException {
return new String(Files.readAllBytes(path), StandardCharsets.UTF_8);
}
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 + ")");
}
/** 供 Resources 走类路径取主资源(target/classes 在测试类路径上)。 */
public static InputStream classpathResource(String path) throws IOException {
return Resources.getResourceAsStream(path);
}
}