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 + ")");
}
}